Simplify FuncType, conversion validation, names

Replace the `ConvertsTo*()` methods on `FuncType` with `ConvertsTo()` on
`FuncExprArg`. This allows more-direct conversion-checking without
separately fetching the type.

Remove the `FuncLiteral` and `FuncSingularQuery` variants of `FuncType`.
Implementations of `ConvertsTo()` now properly distinguishes between
singular and non-singular queries, and the Literal type provided no
value over `ValueType`. This restores `FuncLiteral` to just the three
variants defined by [RFC 9535 Section 2.4.1]: `ValueType`, `NodesType`,
and `LogicalType`.

Improve the docs for `ValueFrom()`, `NodesFrom()`, and `LogicalFrom()`
to document whether and how each type is converted, and describe how to
avoid panics for invalid conversion by checking `ConvertsTo()` in the
function extension validator. Also improve the text of the `panic()`
messages, and remove the handling of boolean values from
`LogicalFrom()`, as `Logical()` handles that behavior.

Remove `NodesQueryExpr`, a thin wrapper around `PathQuery`, by simply
implementing the `FuncExprArg` interface on Query.

Move the `Function` struct to `spec` and name it `FuncExtension`. Have
the registry construct it via the `Extension()` constructor, which
tightens things up quite a bit. Also move the `Validator` and
`Evaluator` aliases to `spec` and use them consistently. Remove the
`PathFunction` interface, as it's no longer needed; we instead use
`FuncExtension` directly. More consistently refer to them as "function
extensions" in the docs, to patch the phrase of the spec.

Rename `JSONPathValue` to `PathValue`, as the `JSON` prefix feels
redundant.

  [RFC 9535 Section 2.4.1]: https://www.rfc-editor.org/rfc/rfc9535#name-type-system-for-function-ex

Author: theory

.golangci.yaml

@@ -35,7 +35,7 @@ linters:
         - empty
         - stdlib
         - generic
-        - spec\.JSONPathValue
+        - spec\.PathValue
         - spec\.FuncExprArg
         - spec\.Selector
         - spec\.BasicExpr

CHANGELOG.md

@@ -11,13 +11,17 @@ All notable changes to this project will be documented in this file. It uses the
 
 ### ⚡ Improvements
 
-*   Made significant changes to the `spec` package toward public stability,
-    usability, and greater comprehension. The names of things are more
-    consistent, the APIs more legible and user-friendly. See [PR #14] for
-    details.
+*   Significantly refactored the `spec` package toward greater stability,
+    usability, and increased comprehensibility. The names of things are more
+    consistent, the APIs more legible and user-friendly. Quite a few types
+    were renamed or merged.
 *   Added support for [json.Number] values to complement the existing support
     for Go core numeric types. This should allow for transparent handling of
     values marshaled with [json.Decoder.UseNumber] enabled.
+*   Moved the function extension types from the `registry` to the `spec`
+    package, simplifying `registry` and the handling of function extensions,
+    without changing the interface for using a registry or adding extensions
+    to it.
 
 ### 📚 Documentation
 
@@ -26,7 +30,8 @@ All notable changes to this project will be documented in this file. It uses the
     and complete lists of interface implementations and examples for each
     significant type. See [PR #14] for details.
 *   Removed the "Package Stability" statement from the README, as all packages
-    are considered stable.
+    are considered stable or else potentially unstable types in the `spec`
+    package have been labeled as such.
 *   Fixed links and typos in the main package documentation, and moved the
     registry example under `WithRegistry`.
 

parser/parse_test.go

@@ -201,7 +201,7 @@ func TestParseFilter(t *testing.T) {
 		"__true",
 		spec.FuncLogical,
 		func([]spec.FuncExprArg) error { return nil },
-		func([]spec.JSONPathValue) spec.JSONPathValue {
+		func([]spec.PathValue) spec.PathValue {
 			return spec.LogicalTrue
 		},
 	)

path_example_test.go

@@ -275,7 +275,7 @@ func validateFirstArgs(args []spec.FuncExprArg) error {
 		return fmt.Errorf("expected 1 argument but found %v", len(args))
 	}
 
-	if !args[0].ResultType().ConvertsToNodes() {
+	if !args[0].ConvertsTo(spec.FuncNodes) {
 		return errors.New("cannot convert argument to nodes")
 	}
 
@@ -285,7 +285,7 @@ func validateFirstArgs(args []spec.FuncExprArg) error {
 // firstFunc defines the custom first() JSONPath function. It converts its
 // single argument to a [spec.NodesType] value and returns a [spec.ValueType]
 // that contains the first node. If there are no nodes it returns nil.
-func firstFunc(jv []spec.JSONPathValue) spec.JSONPathValue {
+func firstFunc(jv []spec.PathValue) spec.PathValue {
 	nodes := spec.NodesFrom(jv[0])
 	if len(nodes) == 0 {
 		return nil

registry/funcs.go

@@ -13,13 +13,12 @@ import (
 // checkLengthArgs checks the argument expressions to length() and returns an
 // error if there is not exactly one expression that results in a compatible
 // [spec.FuncValue] value.
-func checkLengthArgs(fea []spec.FuncExprArg) error {
-	if len(fea) != 1 {
-		return fmt.Errorf("expected 1 argument but found %v", len(fea))
+func checkLengthArgs(args []spec.FuncExprArg) error {
+	if len(args) != 1 {
+		return fmt.Errorf("expected 1 argument but found %v", len(args))
 	}
 
-	kind := fea[0].ResultType()
-	if !kind.ConvertsToValue() {
+	if !args[0].ConvertsTo(spec.FuncValue) {
 		return errors.New("cannot convert argument to Value")
 	}
 
@@ -37,7 +36,7 @@ func checkLengthArgs(fea []spec.FuncExprArg) error {
 //   - If jv[0] is an map[string]any, the result is the number of members in
 //     the map.
 //   - For any other value, the result is nil.
-func lengthFunc(jv []spec.JSONPathValue) spec.JSONPathValue {
+func lengthFunc(jv []spec.PathValue) spec.PathValue {
 	v := spec.ValueFrom(jv[0])
 	if v == nil {
 		return nil
@@ -58,13 +57,12 @@ func lengthFunc(jv []spec.JSONPathValue) spec.JSONPathValue {
 // checkCountArgs checks the argument expressions to count() and returns an
 // error if there is not exactly one expression that results in a
 // [spec.FuncNodes]-compatible value.
-func checkCountArgs(fea []spec.FuncExprArg) error {
-	if len(fea) != 1 {
-		return fmt.Errorf("expected 1 argument but found %v", len(fea))
+func checkCountArgs(args []spec.FuncExprArg) error {
+	if len(args) != 1 {
+		return fmt.Errorf("expected 1 argument but found %v", len(args))
 	}
 
-	kind := fea[0].ResultType()
-	if !kind.ConvertsToNodes() {
+	if !args[0].ConvertsTo(spec.FuncNodes) {
 		return errors.New("cannot convert argument to Nodes")
 	}
 
@@ -75,20 +73,19 @@ func checkCountArgs(fea []spec.FuncExprArg) error {
 // a ValueType containing an unsigned integer for the number of nodes in
 // jv[0]. Panics if jv[0] doesn't exist or is not convertible to
 // [spec.NodesType].
-func countFunc(jv []spec.JSONPathValue) spec.JSONPathValue {
+func countFunc(jv []spec.PathValue) spec.PathValue {
 	return spec.Value(len(spec.NodesFrom(jv[0])))
 }
 
 // checkValueArgs checks the argument expressions to value() and returns an
 // error if there is not exactly one expression that results in a
 // [spec.FuncNodes]-compatible value.
-func checkValueArgs(fea []spec.FuncExprArg) error {
-	if len(fea) != 1 {
-		return fmt.Errorf("expected 1 argument but found %v", len(fea))
+func checkValueArgs(args []spec.FuncExprArg) error {
+	if len(args) != 1 {
+		return fmt.Errorf("expected 1 argument but found %v", len(args))
 	}
 
-	kind := fea[0].ResultType()
-	if !kind.ConvertsToNodes() {
+	if !args[0].ConvertsTo(spec.FuncNodes) {
 		return errors.New("cannot convert argument to Nodes")
 	}
 
@@ -100,7 +97,7 @@ func checkValueArgs(fea []spec.FuncExprArg) error {
 //
 //   - If jv[0] contains a single node, the result is the value of the node.
 //   - If jv[0] is empty or contains multiple nodes, the result is nil.
-func valueFunc(jv []spec.JSONPathValue) spec.JSONPathValue {
+func valueFunc(jv []spec.PathValue) spec.PathValue {
 	nodes := spec.NodesFrom(jv[0])
 	if len(nodes) == 1 {
 		return spec.Value(nodes[0])
@@ -111,15 +108,14 @@ func valueFunc(jv []spec.JSONPathValue) spec.JSONPathValue {
 // checkMatchArgs checks the argument expressions to match() and returns an
 // error if there are not exactly two expressions that result in compatible
 // [spec.FuncValue] values.
-func checkMatchArgs(fea []spec.FuncExprArg) error {
+func checkMatchArgs(args []spec.FuncExprArg) error {
 	const matchArgLen = 2
-	if len(fea) != matchArgLen {
-		return fmt.Errorf("expected 2 arguments but found %v", len(fea))
+	if len(args) != matchArgLen {
+		return fmt.Errorf("expected 2 arguments but found %v", len(args))
 	}
 
-	for i, arg := range fea {
-		kind := arg.ResultType()
-		if !kind.ConvertsToValue() {
+	for i, arg := range args {
+		if !arg.ConvertsTo(spec.FuncValue) {
 			return fmt.Errorf("cannot convert argument %v to Value", i+1)
 		}
 	}
@@ -132,11 +128,11 @@ func checkMatchArgs(fea []spec.FuncExprArg) error {
 // implied \A and \z anchors and used to match the first, returning LogicalTrue for
 // a match and LogicalFalse for no match. Returns LogicalFalse if either jv value
 // is not a string or if jv[1] fails to compile.
-func matchFunc(jv []spec.JSONPathValue) spec.JSONPathValue {
+func matchFunc(jv []spec.PathValue) spec.PathValue {
 	if v, ok := spec.ValueFrom(jv[0]).Value().(string); ok {
 		if r, ok := spec.ValueFrom(jv[1]).Value().(string); ok {
 			if rc := compileRegex(`\A` + r + `\z`); rc != nil {
-				return spec.LogicalFrom(rc.MatchString(v))
+				return spec.Logical(rc.MatchString(v))
 			}
 		}
 	}
@@ -146,15 +142,14 @@ func matchFunc(jv []spec.JSONPathValue) spec.JSONPathValue {
 // checkSearchArgs checks the argument expressions to search() and returns an
 // error if there are not exactly two expressions that result in compatible
 // [spec.FuncValue] values.
-func checkSearchArgs(fea []spec.FuncExprArg) error {
+func checkSearchArgs(args []spec.FuncExprArg) error {
 	const searchArgLen = 2
-	if len(fea) != searchArgLen {
-		return fmt.Errorf("expected 2 arguments but found %v", len(fea))
+	if len(args) != searchArgLen {
+		return fmt.Errorf("expected 2 arguments but found %v", len(args))
 	}
 
-	for i, arg := range fea {
-		kind := arg.ResultType()
-		if !kind.ConvertsToValue() {
+	for i, arg := range args {
+		if !arg.ConvertsTo(spec.FuncValue) {
 			return fmt.Errorf("cannot convert argument %v to Value", i+1)
 		}
 	}
@@ -167,11 +162,11 @@ func checkSearchArgs(fea []spec.FuncExprArg) error {
 // to match the former, returning LogicalTrue for a match and LogicalFalse for no
 // match. Returns LogicalFalse if either value is not a string, or if jv[1]
 // fails to compile.
-func searchFunc(jv []spec.JSONPathValue) spec.JSONPathValue {
+func searchFunc(jv []spec.PathValue) spec.PathValue {
 	if val, ok := spec.ValueFrom(jv[0]).Value().(string); ok {
 		if r, ok := spec.ValueFrom(jv[1]).Value().(string); ok {
 			if rc := compileRegex(r); rc != nil {
-				return spec.LogicalFrom(rc.MatchString(val))
+				return spec.Logical(rc.MatchString(val))
 			}
 		}
 	}