Revamp the spec package and document for stability

Revisit and make significant changes to the spec package toward public
stability, usability, and greater comprehension. Make the names of
things more consistent, the APIs more legible and user-friendly, and the
documentation thorough, with examples for each significant type.

Details:

*   Add examples for all the various types.
*   Make type names more consistent and appropriately descriptive:
    *   Always use `Func` as a prefix rather than sometimes `Function`
    *   Rename `FilterQuery` to `NodesQuery` to complement
        `SingularQuery`
    *   Remove the `Func` prefix from the stringification of `FuncType`s
    *   Always use `Nodes` as a suffix in methods, constructors, and
        value names (`FuncNodes`) than sometimes `NodeList` (but retain
        the latter for types)
    *   `ValueType`, and `NodesType` stringification now returns
        Go-formatted values rather than the strings "ValueType" and
        "NodesType"
*   Use variadic parameters in object constructors to decrease verbosity
    and improve legibility.
*   Ensure consistent stringification and implementation of
    `fmt.Stringer`.
*   Document the use cases for each type, and list interface
    implementations for improved cross-referencing.
*   Consistently use doc links when referring to other types, fix
    invalid type names in doc comments, and copiously cross-reference
    related types.
*   Add constructors for most types that lacked them, and use them
    consistently in the parser and registry packages.
*   Add links to the relevant parts of [RFC 9535] for most types.
*   Replace `FuncType.ConvertsTo()` method and its dependent data type,
    `PathType`, with separate methods for each type that function
    validators care about: `ConvertsToValue()`, `ConvertsToLogical()`,
    and `ConvertsToNode()`.
*   Make fields of most structs private where they weren't already. The
    exception is `LocatedNode`, which is a simple wrapper around a value
    and its location.
*   Remove the "Package Stability" statement from the README.

Also: Add support for `json.Number` values to complement the existing
support for all Go numeric types. This should allow for transparent
handling of values marshaled with [json.Decoder.UseNumber] enabled.

[RFC 9535]: https://www.rfc-editor.org/rfc/rfc9535.html
[json.Decoder.UseNumber]: https://pkg.go.dev/encoding/json#Decoder.UseNumber

Author: theory

.golangci.yaml

@@ -36,7 +36,7 @@ linters:
         - stdlib
         - generic
         - spec\.JSONPathValue
-        - spec\.FunctionExprArg
+        - spec\.FuncExprArg
         - spec\.Selector
         - spec\.BasicExpr
         - spec\.CompVal

CHANGELOG.md

@@ -7,6 +7,26 @@ All notable changes to this project will be documented in this file. It uses the
   [Semantic Versioning]: https://semver.org/spec/v2.0.0.html
     "Semantic Versioning 2.0.0"
 
+## [v0.10.0] — Unreleased
+
+### ⚡ 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, and the documentation
+    thorough, with examples for each significant type. See [PR #14] for
+    details.
+*   Removed the "Package Stability" statement from the README, as all packages
+    are considered stable.
+*   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.
+
+  [v0.4.1]: https://github.com/theory/jsonpath/compare/v0.4.1...v0.10.0
+  [json.Number]: https://pkg.go.dev/encoding/json#Number
+  [json.Decoder.UseNumber]: https://pkg.go.dev/encoding/json#Decoder.UseNumber
+  [PR #14]: https://github.com/theory/jsonpath/pull/14
+
 ## [v0.4.1] — 2025-05-02
 
 ### 🪲 Bug Fixes

README.md

@@ -33,21 +33,6 @@ A brief overview of [RFC 9535 JSONPath] syntax:
 | `?<logical-expr>`  | filter selector: selects particular children using a logical expression |
 | `length(@.foo)`    | function extension: invokes  a function in a filter expression          |
 
-## Package Stability
-
-The root `jsonpath` package is stable and ready for use. These are the main
-interfaces to the package.
-
-The `registry` package is also stable, but exposes data types from the `spec`
-package that are still in flux. Argument data types may still change.
-
-The `parser` package interface is also stable, but in general should not be
-used directly.
-
-The `spec` package remains under active development, mainly refactoring,
-reorganizing, renaming, and documenting. Its interface therefore is not stable
-and should not be used for production purposes.
-
 ## Copyright
 
 Copyright © 2024-2025 David E. Wheeler

parser/parse.go

@@ -105,7 +105,7 @@ func (p *parser) parseQuery(root bool) (*spec.PathQuery, error) {
 			fallthrough
 		default:
 			// Done parsing.
-			return spec.Query(root, segs), nil
+			return spec.Query(root, segs...), nil
 		}
 	}
 }
@@ -288,7 +288,7 @@ func (p *parser) parseFilter() (*spec.FilterSelector, error) {
 	if err != nil {
 		return nil, err
 	}
-	return spec.Filter(lor), nil
+	return spec.Filter(lor...), nil
 }
 
 // parseLogicalOrExpr parses a [LogicalOrExpr] from lex. A [LogicalOrExpr] is
@@ -410,7 +410,7 @@ func (p *parser) parseBasicExpr() (spec.BasicExpr, error) {
 
 // parseFunctionFilterExpr parses a [BasicExpr] (basic-expr) that starts with
 // ident, which must be an identifier token that's expected to be the name of
-// a function. The return value will be either a [FunctionExpr]
+// a function. The return value will be either a [spec.FuncExpr]
 // (function-expr), if the function return value is a logical (boolean) value.
 // Otherwise it will be a [ComparisonExpr] (comparison-expr), as long as the
 // function call is compared to another expression. Any other configuration
@@ -481,7 +481,7 @@ func (p *parser) parseParenExpr() (*spec.ParenExpr, error) {
 	if err != nil {
 		return nil, err
 	}
-	return spec.Paren(expr), nil
+	return spec.Paren(expr...), nil
 }
 
 // parseParenExpr parses a [*spec.NotParenExpr] expression (logical-not-op
@@ -493,14 +493,14 @@ func (p *parser) parseNotParenExpr() (*spec.NotParenExpr, error) {
 	if err != nil {
 		return nil, err
 	}
-	return spec.NotParen(expr), nil
+	return spec.NotParen(expr...), nil
 }
 
 // parseFunction parses a function named tok.val from lex. tok should be the
 // token just before the next call to lex.scan, and must be an identifier
 // token naming the function. Returns an error if the function is not found in
 // the registry or if arguments are invalid for the function.
-func (p *parser) parseFunction(tok token) (*spec.FunctionExpr, error) {
+func (p *parser) parseFunction(tok token) (*spec.FuncExpr, error) {
 	function := p.reg.Get(tok.val)
 	if function == nil {
 		return nil, makeError(tok, fmt.Sprintf("unknown function %v()", tok.val))
@@ -516,14 +516,14 @@ func (p *parser) parseFunction(tok token) (*spec.FunctionExpr, error) {
 		return nil, makeError(paren, fmt.Sprintf("function %v() %v", tok.val, err.Error()))
 	}
 
-	return spec.Function(function, args), nil
+	return spec.Function(function, args...), nil
 }
 
 // parseFunctionArgs parses the comma-delimited arguments to a function from
 // lex. Arguments may be one of literal, filter-query (including
 // singular-query), logical-expr, or function-expr.
-func (p *parser) parseFunctionArgs() ([]spec.FunctionExprArg, error) {
-	res := []spec.FunctionExprArg{}
+func (p *parser) parseFunctionArgs() ([]spec.FuncExprArg, error) {
+	res := []spec.FuncExprArg{}
 	lex := p.lex
 	for {
 		switch tok := p.lex.scan(); tok.tok {
@@ -730,7 +730,7 @@ func parseSingularQuery(startToken token, lex *lexer) (*spec.SingularQueryExpr,
 			selectors = append(selectors, spec.Name(tok.val))
 		default:
 			// Done parsing.
-			return spec.SingularQuery(startToken.tok == '$', selectors), nil
+			return spec.SingularQuery(startToken.tok == '$', selectors...), nil
 		}
 	}
 }