Rename ComparisonExpr, add Wildcard(), doc stable

Rename `ComparisonExpr` to `CompExpr` to match the naming of `CompVal`
and `CompOp`.

Replace the `Wildcard` global variable with the `Wildcard()`
constructor, which returns a singleton, but an be be changed in the
future if for some reason it needs not to be a singleton.

Document the stable types and constructors in the `spec` package, and
note that there may be some changes to other stuff in the future (though
probably not).

Link to the `Wildcard` global from the `WildcardSelector` docs and
document that `Registry.Get` is used internally by the parser.

Author: theory

CHANGELOG.md

@@ -34,6 +34,8 @@ All notable changes to this project will be documented in this file. It uses the
     package have been labeled as such.
 *   Fixed links and typos in the main package documentation, and moved the
     registry example under `WithRegistry`.
+*   Replaced the `spec.Wildcard` variable with a the function
+    `spec.Wildcard()`.
 
 ### 📔 Notes
 

parser/parse.go

@@ -117,7 +117,7 @@ func parseNameOrWildcard(lex *lexer) (spec.Selector, error) {
 	case identifier:
 		return spec.Name(tok.val), nil
 	case '*':
-		return spec.Wildcard, nil
+		return spec.Wildcard(), nil
 	default:
 		return nil, unexpected(tok)
 	}
@@ -137,7 +137,7 @@ func (p *parser) parseDescendant() (*spec.Segment, error) {
 	case identifier:
 		return spec.Descendant(spec.Name(tok.val)), nil
 	case '*':
-		return spec.Descendant(spec.Wildcard), nil
+		return spec.Descendant(spec.Wildcard()), nil
 	default:
 		return nil, unexpected(tok)
 	}
@@ -169,7 +169,7 @@ func (p *parser) parseSelectors() ([]spec.Selector, error) {
 			}
 			selectors = append(selectors, filter)
 		case '*':
-			selectors = append(selectors, spec.Wildcard)
+			selectors = append(selectors, spec.Wildcard())
 		case goString:
 			selectors = append(selectors, spec.Name(tok.val))
 		case integer:
@@ -613,7 +613,7 @@ func parseLiteral(tok token) (*spec.LiteralArg, error) {
 }
 
 // parseComparableExpr parses a [ComparisonExpr] (comparison-expr) from lex.
-func (p *parser) parseComparableExpr(left spec.CompVal) (*spec.ComparisonExpr, error) {
+func (p *parser) parseComparableExpr(left spec.CompVal) (*spec.CompExpr, error) {
 	// Skip blank space.
 	lex := p.lex
 	lex.skipBlankSpace()

parser/parse_test.go

@@ -85,15 +85,15 @@ func TestParseSimple(t *testing.T) {
 		{
 			name: "wildcard",
 			path: "$.*",
-			exp:  spec.Query(true, spec.Child(spec.Wildcard)),
+			exp:  spec.Query(true, spec.Child(spec.Wildcard())),
 		},
 		{
 			name: "wildcard_wildcard",
 			path: "$.*.*",
 			exp: spec.Query(
 				true,
-				spec.Child(spec.Wildcard),
-				spec.Child(spec.Wildcard),
+				spec.Child(spec.Wildcard()),
+				spec.Child(spec.Wildcard()),
 			),
 		},
 		{
@@ -102,7 +102,7 @@ func TestParseSimple(t *testing.T) {
 			exp: spec.Query(
 				true,
 				spec.Child(spec.Name("x")),
-				spec.Child(spec.Wildcard),
+				spec.Child(spec.Wildcard()),
 			),
 		},
 		{
@@ -122,23 +122,23 @@ func TestParseSimple(t *testing.T) {
 		{
 			name: "desc_wildcard",
 			path: "$..*",
-			exp:  spec.Query(true, spec.Descendant(spec.Wildcard)),
+			exp:  spec.Query(true, spec.Descendant(spec.Wildcard())),
 		},
 		{
 			name: "desc_wildcard_2x",
 			path: "$..*..*",
 			exp: spec.Query(
 				true,
-				spec.Descendant(spec.Wildcard),
-				spec.Descendant(spec.Wildcard),
+				spec.Descendant(spec.Wildcard()),
+				spec.Descendant(spec.Wildcard()),
 			),
 		},
 		{
 			name: "desc_wildcard_name",
 			path: "$..*.xyz",
 			exp: spec.Query(
 				true,
-				spec.Descendant(spec.Wildcard),
+				spec.Descendant(spec.Wildcard()),
 				spec.Child(spec.Name("xyz")),
 			),
 		},
@@ -147,7 +147,7 @@ func TestParseSimple(t *testing.T) {
 			path: "$.*..xyz",
 			exp: spec.Query(
 				true,
-				spec.Child(spec.Wildcard),
+				spec.Child(spec.Wildcard()),
 				spec.Descendant(spec.Name("xyz")),
 			),
 		},
@@ -967,12 +967,12 @@ func TestParseSelectors(t *testing.T) {
 		{
 			name: "slice_wildcard",
 			path: `$[:,   *]`,
-			exp:  spec.Query(true, spec.Child(spec.Slice(), spec.Wildcard)),
+			exp:  spec.Query(true, spec.Child(spec.Slice(), spec.Wildcard())),
 		},
 		{
 			name: "wildcard_slice",
 			path: `$[  *,  :   ]`,
-			exp:  spec.Query(true, spec.Child(spec.Wildcard, spec.Slice())),
+			exp:  spec.Query(true, spec.Child(spec.Wildcard(), spec.Slice())),
 		},
 		{
 			name: "slice_neg_start",
@@ -990,13 +990,13 @@ func TestParseSelectors(t *testing.T) {
 			exp:  spec.Query(true, spec.Child(spec.Slice(nil, nil, -2))),
 		},
 		{
-			name: "index_name_slice, wildcard",
+			name: "index_name_slice_wildcard",
 			path: `$[3, "🦀", :3,*]`,
 			exp: spec.Query(true, spec.Child(
 				spec.Index(3),
 				spec.Name("🦀"),
 				spec.Slice(nil, 3),
-				spec.Wildcard,
+				spec.Wildcard(),
 			)),
 		},
 		{
@@ -1118,7 +1118,7 @@ func TestParseSelectors(t *testing.T) {
 		{
 			name: "wildcard_tab",
 			path: "$[*\t]",
-			exp:  spec.Query(true, spec.Child(spec.Wildcard)),
+			exp:  spec.Query(true, spec.Child(spec.Wildcard())),
 		},
 		{
 			name: "slice_newline",
@@ -1146,7 +1146,7 @@ func TestParseSelectors(t *testing.T) {
 			exp: spec.Query(true, spec.Descendant(
 				spec.Name("hi"),
 				spec.Index(2),
-				spec.Wildcard,
+				spec.Wildcard(),
 				spec.Slice(4, 5),
 			)),
 		},
@@ -1177,7 +1177,7 @@ func TestParseSelectors(t *testing.T) {
 				true,
 				spec.Child(spec.Name("names")),
 				spec.Child(spec.Name("first_name")),
-				spec.Descendant(spec.Wildcard),
+				spec.Descendant(spec.Wildcard()),
 			),
 		},
 		{
@@ -1214,7 +1214,7 @@ func TestParseSelectors(t *testing.T) {
 		{
 			name: "default_slice_wildcard_segment",
 			path: `$[::,*]`,
-			exp:  spec.Query(true, spec.Child(spec.Slice(), spec.Wildcard)),
+			exp:  spec.Query(true, spec.Child(spec.Slice(), spec.Wildcard())),
 		},
 		{
 			name: "leading_zero_index",

registry/registry.go

@@ -87,7 +87,8 @@ func (r *Registry) Register(
 }
 
 // Get returns a reference to the registered function extension named name.
-// Returns nil if no function with that name has been registered.
+// Returns nil if no function with that name has been registered. Used by the
+// parser to match a function name to its implementation.
 func (r *Registry) Get(name string) *spec.FuncExtension {
 	r.mu.RLock()
 	defer r.mu.RUnlock()

spec/filter.go

@@ -7,7 +7,7 @@ import (
 // BasicExpr defines the basic interface for filter expressions.
 // Implementations:
 //
-//   - [ComparisonExpr]
+//   - [CompExpr]
 //   - [ExistExpr]
 //   - [FuncExpr]
 //   - [LogicalAnd]

spec/function_test.go

@@ -420,7 +420,7 @@ func TestFilterQuery(t *testing.T) {
 		},
 		{
 			name:     "current_wildcard",
-			query:    Query(false, Child(Wildcard)),
+			query:    Query(false, Child(Wildcard())),
 			current:  []any{13, 2, []any{4}},
 			exp:      []any{13, 2, []any{4}},
 			typeKind: FuncNodes,

spec/op.go

@@ -41,42 +41,41 @@ type CompVal interface {
 	asValue(current, root any) PathValue
 }
 
-// ComparisonExpr is a filter expression that compares two values, which
-// themselves may themselves be the output of expressions. Interfaces
-// implemented:
+// CompExpr is a filter expression that compares two values, which themselves
+// may themselves be the output of expressions. Interfaces implemented:
 //
 //   - [BasicExpr]
 //   - [fmt.Stringer]
-type ComparisonExpr struct {
+type CompExpr struct {
 	left  CompVal
 	op    CompOp
 	right CompVal
 }
 
-// Comparison creates and returns a new [ComparisonExpr] that uses op to
-// compare left and right.
-func Comparison(left CompVal, op CompOp, right CompVal) *ComparisonExpr {
-	return &ComparisonExpr{left, op, right}
+// Comparison creates and returns a new [CompExpr] that uses op to compare
+// left and right.
+func Comparison(left CompVal, op CompOp, right CompVal) *CompExpr {
+	return &CompExpr{left, op, right}
 }
 
 // writeTo writes a string representation of ce to buf. Defined by
 // [stringWriter].
-func (ce *ComparisonExpr) writeTo(buf *strings.Builder) {
+func (ce *CompExpr) writeTo(buf *strings.Builder) {
 	ce.left.writeTo(buf)
 	fmt.Fprintf(buf, " %v ", ce.op)
 	ce.right.writeTo(buf)
 }
 
 // String returns the string representation of ce.
-func (ce *ComparisonExpr) String() string {
+func (ce *CompExpr) String() string {
 	var buf strings.Builder
 	ce.writeTo(&buf)
 	return buf.String()
 }
 
 // testFilter uses ce.Op to compare the values returned by ce.Left and
 // ce.Right relative to current and root. Defined by [BasicExpr].
-func (ce *ComparisonExpr) testFilter(current, root any) bool {
+func (ce *CompExpr) testFilter(current, root any) bool {
 	left := ce.left.asValue(current, root)
 	right := ce.right.asValue(current, root)
 	switch ce.op {