Start adding spec examples

Author: theory

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

spec/op.go

@@ -54,6 +54,13 @@ func (ce *ComparisonExpr) writeTo(buf *strings.Builder) {
 	ce.Right.writeTo(buf)
 }
 
+// String returns the string representation of ce.
+func (ce *ComparisonExpr) 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.
 func (ce *ComparisonExpr) testFilter(current, root any) bool {

spec/selector.go

@@ -1,6 +1,3 @@
-// Package spec provides object definitions and execution for RFC 9535
-// JSONPath query expressions. It remains under active development therefore
-// should generally not be used directly except for experimental purposes.
 package spec
 
 import (

spec/spec.go

@@ -0,0 +1,5 @@
+// Package spec provides RFC 9535 JSONPath query AST and execution. It will
+// mainly be of interest to those wishing to implement their own parsers, to
+// convert from other JSON path-type languages, and to implement functions for
+// [github.com/theory/jsonpath/registry].
+package spec

spec/spec_example_test.go

@@ -0,0 +1,234 @@
+package spec_test
+
+import (
+	"encoding/json"
+	"fmt"
+	"log"
+
+	"github.com/theory/jsonpath"
+	"github.com/theory/jsonpath/spec"
+)
+
+// Select all the authors of the books in a bookstore object.
+func Example() {
+	// Construct a jsonpath query.
+	p := jsonpath.New(spec.Query(
+		true,
+		spec.Child(spec.Name("store")),
+		spec.Child(spec.Name("book")),
+		spec.Child(spec.Wildcard),
+		spec.Child(spec.Name("author")),
+	))
+
+	// Select values from unmarshaled JSON input.
+	store := bookstore()
+	nodes := p.Select(store)
+
+	// Show the selected values.
+	items, err := json.Marshal(nodes)
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Printf("%s\n", items)
+
+	// Output: ["Nigel Rees","Evelyn Waugh","Herman Melville","J. R. R. Tolkien"]
+}
+
+// Construct a couple of different path queries.
+func ExamplePathQuery() {
+	// Create a query and its segments.
+	q := spec.Query(
+		true,
+		spec.Child(spec.Name("store")),
+		spec.Child(spec.Name("book")),
+		spec.Child(spec.Wildcard),
+		spec.Child(spec.Name("author")),
+	)
+	fmt.Printf("%v\n", q)
+
+	// Create a query with multi-selector segments.
+	q = spec.Query(
+		true,
+		spec.Child(spec.Name("profile")),
+		spec.Descendant(spec.Name("email"), spec.Name("phone")),
+	)
+	fmt.Printf("%v\n", q)
+
+	// Output:
+	// $["store"]["book"][*]["author"]
+	// $["profile"]..["email","phone"]
+}
+
+// Create a child segment that selects the name "hi", th index 2, or slice
+// 1-3.
+func ExampleSegment_child() {
+	child := spec.Child(
+		spec.Name("hi"),
+		spec.Index(2),
+		spec.Slice(1, 3, 1),
+	)
+	fmt.Printf("%v\n", child)
+	// Output: ["hi",2,1:3]
+}
+
+// Create a descendant segment that selects the name "email" or array index
+// zero from a node or any of its descendant nodes.
+func ExampleSegment_descendant() {
+	child := spec.Descendant(
+		spec.Name("email"),
+		spec.Index(0),
+	)
+	fmt.Printf("%v\n", child)
+	// Output: ..["email",0]
+}
+
+// Create a few types of slice selectors.
+func ExampleSliceSelector() {
+	// Select all values in a slice.
+	for _, sliceSelector := range []any{
+		spec.Slice(),         // full slice
+		spec.Slice(1, 4),     // items 1-3
+		spec.Slice(nil, 8),   // items 0-7
+		spec.Slice(4, -1, 3), // items 4-last step by 3
+		spec.Slice(5, 1, -2), // items 5-2, step by -2
+
+	} {
+		fmt.Printf("%v\n", sliceSelector)
+	}
+	// Output:
+	// :
+	// 1:4
+	// :8
+	// 4:-1:3
+	// 5:1:-2
+}
+
+// Create a few types of name selectors.
+func ExampleName() {
+	for _, nameSelector := range []any{
+		spec.Name("hello"),                 // ascii
+		spec.Name(`Charlie "Bird" Parker`), // quoted
+		spec.Name("އައްސަލާމް ޢަލައިކުމް"), // Unicode
+		spec.Name("📡🪛🪤"),                   // emoji
+	} {
+		fmt.Printf("%v\n", nameSelector)
+	}
+	// Output:
+	// "hello"
+	// "Charlie \"Bird\" Parker"
+	// "އައްސަލާމް ޢަލައިކުމް"
+	// "📡🪛🪤"
+}
+
+// Create a few types of index selectors.
+func ExampleIndex() {
+	for _, indexSelector := range []any{
+		spec.Index(0),  // first item
+		spec.Index(3),  // fourth item
+		spec.Index(-1), // last item
+	} {
+		fmt.Printf("%v\n", indexSelector)
+	}
+	// Output:
+	// 0
+	// 3
+	// -1
+}
+
+func ExampleWildcard() {
+	fmt.Printf("%v\n", spec.Wildcard)
+	// Output: *
+}
+
+// Create a filter selector that selects nodes with a descendant that contains
+// an object field named "x".
+func ExampleFilterSelector() {
+	f := spec.Filter(spec.And(
+		spec.Existence(
+			spec.Query(false, spec.Descendant(spec.Name("x"))),
+		),
+	))
+	fmt.Printf("%v\n", f)
+	// Output: ?@..["x"]
+}
+
+// Create a comparison expression that compares a literal value to a path
+// expression.
+func ExampleComparisonExpr() {
+	cmp := spec.Comparison(
+		spec.Literal(42),
+		spec.EqualTo,
+		spec.SingularQuery(false, spec.Name("age")),
+	)
+	fmt.Printf("%v\n", cmp)
+	// Output: 42 == @["age"]
+}
+
+// Create an existence expression as a filter expression.
+func ExampleExistExpr() {
+	filter := spec.Filter(spec.And(
+		spec.Existence(
+			spec.Query(false, spec.Child(spec.Name("x"))),
+		),
+	))
+	fmt.Printf("%v\n", filter)
+	// Output: ?@["x"]
+}
+
+// Create a nonexistence expression as a filter expression.
+func ExampleNonExistExpr() {
+	filter := spec.Filter(spec.And(
+		spec.Nonexistence(
+			spec.Query(false, spec.Child(spec.Name("x"))),
+		),
+	))
+	fmt.Printf("%v\n", filter)
+	// Output: ?!@["x"]
+}
+
+// bookstore returns an unmarshaled JSON object.
+func bookstore() any {
+	src := []byte(`{
+	  "store": {
+	    "book": [
+	    {
+	      "category": "reference",
+	      "author": "Nigel Rees",
+	      "title": "Sayings of the Century",
+	      "price": 8.95
+	    },
+	    {
+	      "category": "fiction",
+	      "author": "Evelyn Waugh",
+	      "title": "Sword of Honour",
+	      "price": 12.99
+	    },
+	    {
+	      "category": "fiction",
+	      "author": "Herman Melville",
+	      "title": "Moby Dick",
+	      "isbn": "0-553-21311-3",
+	      "price": 8.99
+	    },
+	    {
+	      "category": "fiction",
+	      "author": "J. R. R. Tolkien",
+	      "title": "The Lord of the Rings",
+	      "isbn": "0-395-19395-8",
+	      "price": 22.99
+	    }
+	    ],
+	    "bicycle": {
+	    "color": "red",
+	    "price": 399
+	    }
+	  }
+	}`)
+
+	// Parse the JSON.
+	var value any
+	if err := json.Unmarshal(src, &value); err != nil {
+		log.Fatal(err)
+	}
+	return value
+}