Finish doc copyedit

Author: theory

path.go

@@ -53,7 +53,7 @@ func (p *Path) Select(input any) NodeList {
 }
 
 // SelectLocated returns the values that JSONPath query p selects from input
-// as [spec.LocatedNode] structs that pair the values with the [normalized
+// as [spec.LocatedNode] objects that pair the values with the [normalized
 // paths] that identify them. Unless you have a specific need for the unique
 // normalized path for each value, you probably want to use [Path.Select].
 //

spec/function.go

@@ -82,8 +82,8 @@ type JSONPathValue interface {
 
 // NodesType defines a node list (a list of JSON values) for a function
 // expression parameters or results, as defined by [RFC 9535 Section 2.4.1].
-// It can also be used in filter expressions. The underlying values should be
-// strings, integers, floats, [json.Number]s, nil, true, false, []any, or
+// It can also be used in filter expressions. The underlying types should be
+// string, integer, float, [json.Number], nil, true, false, []any, or
 // map[string]any. Interfaces implemented:
 //
 // - [JSONPathValue]
@@ -93,8 +93,8 @@ type JSONPathValue interface {
 type NodesType []any
 
 // Nodes creates a NodesType that contains val, all of which should be the Go
-// equivalent of the JSON data types: strings, integers, floats,
-// [json.Number]s, nil, true, false, []any, or map[string]any.
+// equivalent of the JSON data types: string, integer, float, [json.Number],
+// nil, true, false, []any, or map[string]any.
 func Nodes(val ...any) NodesType {
 	return NodesType(val)
 }
@@ -134,8 +134,8 @@ func (nt NodesType) String() string {
 // parameters or results, as defined by [RFC 9535 Section 2.4.1]. Interfaces
 // implemented:
 //
-// - [JSONPathValue]
-// - [fmt.Stringer]
+//   - [JSONPathValue]
+//   - [fmt.Stringer]
 //
 // [RFC 9535 Section 2.4.1]: https://www.rfc-editor.org/rfc/rfc9535.html#section-2.4.1
 type LogicalType uint8
@@ -192,21 +192,21 @@ func (lt LogicalType) writeTo(buf *strings.Builder) {
 
 // ValueType encapsulates a JSON value for a function expression parameter or
 // result, as defined by [RFC 9535 Section 2.4.1]. It can also be used as in
-// filter expression. The underlying value should be a string, integer, float,
-// nil, true, false, []any, or map[string]any. A nil ValueType pointer
-// indicates no value. Interfaces implemented:
+// filter expression. The underlying value should be a string, integer,
+// [json.Number], float, nil, true, false, []any, or map[string]any. A nil
+// ValueType pointer indicates no value. Interfaces implemented:
 //
-// - [JSONPathValue]
-// - [BasicExpr]
-// - [fmt.Stringer]
+//   - [JSONPathValue]
+//   - [BasicExpr]
+//   - [fmt.Stringer]
 //
 // [RFC 9535 Section 2.4.1]: https://www.rfc-editor.org/rfc/rfc9535.html#section-2.4.1
 type ValueType struct {
 	any
 }
 
-// Value returns a new ValueType for val, which must be the Go equivalent of a
-// JSON data type: string, integer, float, [json.Number], nil, true, false,
+// Value returns a new [ValueType] for val, which must be the Go equivalent of
+// a JSON data type: string, integer, float, [json.Number], nil, true, false,
 // []any, or map[string]any.
 func Value(val any) *ValueType {
 	return &ValueType{val}
@@ -357,7 +357,7 @@ func (la *LiteralArg) asValue(_, _ any) JSONPathValue {
 }
 
 // SingularQueryExpr represents a query that produces a single [ValueType]
-// (JSON value), or nothing. Used in contexts that require a singular value,
+// (JSON value) or nothing. Used in contexts that require a singular value,
 // such as comparison operations and function arguments. Interfaces
 // implemented:
 //
@@ -373,7 +373,7 @@ type SingularQueryExpr struct {
 }
 
 // SingularQuery creates and returns a [SingularQueryExpr] that selects a
-// single value.
+// single value at the path defined by selectors.
 func SingularQuery(root bool, selectors ...Selector) *SingularQueryExpr {
 	return &SingularQueryExpr{relative: !root, selectors: selectors}
 }
@@ -469,7 +469,7 @@ func (fq *NodesQueryExpr) writeTo(buf *strings.Builder) {
 }
 
 // PathFunction represents a JSONPath function. See
-// [github.com/theory/jsonpath/registry] for the implementation.
+// [github.com/theory/jsonpath/registry.Function] for the implementation.
 type PathFunction interface {
 	Name() string
 	ResultType() FuncType
@@ -570,7 +570,7 @@ type NotFuncExpr struct {
 }
 
 // NotFunction creates and returns a new NotFuncExpr that will execute fn
-// against the return values of args and return the inverses of its return
+// against the return values of args and return the inverse of its return
 // value.
 func NotFunction(fn *FuncExpr) NotFuncExpr {
 	return NotFuncExpr{fn}

spec/normalized.go

@@ -102,8 +102,9 @@ func (np NormalizedPath) MarshalText() ([]byte, error) {
 	return []byte(np.String()), nil
 }
 
-// LocatedNode pairs a value with its location within the JSON query argument
-// from which it was selected. Used only for nodes in a [NormalizedPath].
+// LocatedNode pairs a value with the [NormalizedPath] for its location within
+// the JSON query argument from which it was selected. Returned by
+// implementations of [Selector]'s SelectLocated method.
 type LocatedNode struct {
 	// Node is the value selected from a JSON query argument.
 	Node any `json:"node"`

spec/query.go

@@ -10,14 +10,14 @@ type PathQuery struct {
 	root     bool
 }
 
-// Query returns a new query consisting of segments. When root is true it
-// indicates a query from the root of a value. Set to false for filter
+// Query returns a new [PathQuery] consisting of segments. When root is true
+// it indicates a query from the root of a value. Set to false for filter
 // subqueries.
 func Query(root bool, segments ...*Segment) *PathQuery {
 	return &PathQuery{root: root, segments: segments}
 }
 
-// Segments returns q's [Segment]s.
+// Segments returns q's [Segment] objects.
 func (q *PathQuery) Segments() []*Segment {
 	return q.segments
 }
@@ -36,7 +36,7 @@ func (q *PathQuery) String() string {
 	return buf.String()
 }
 
-// Select selects the [Segment]s from current or root and returns the result.
+// Select selects the values from current or root and returns the results.
 // Returns just current if q has no segments. Defined by the [Selector]
 // interface.
 func (q *PathQuery) Select(current, root any) []any {
@@ -55,9 +55,9 @@ func (q *PathQuery) Select(current, root any) []any {
 	return res
 }
 
-// SelectLocated selects the [Segment]s from current or root and returns the
-// resulting values as [LocatedNode] structs. Returns just current if q has no
-// segments. Defined by the [Selector] interface.
+// SelectLocated values from current or root into [LocatedNode] objects and
+// returns the results. Returns just current if q has no segments. Defined by
+// the [Selector] interface.
 func (q *PathQuery) SelectLocated(current, root any, parent NormalizedPath) []*LocatedNode {
 	res := []*LocatedNode{nil}
 	if q.root {

spec/segment.go

@@ -67,7 +67,7 @@ func (s *Segment) Select(current, root any) []any {
 	return ret
 }
 
-// SelectLocated selects and returns values as [LocatedNode] structs from
+// SelectLocated selects and returns values as [LocatedNode] objects from
 // current or root for each of seg's selectors. Defined by the [Selector]
 // interface.
 func (s *Segment) SelectLocated(current, root any, parent NormalizedPath) []*LocatedNode {

spec/selector.go

@@ -23,7 +23,7 @@ type Selector interface {
 	Select(current, root any) []any
 
 	// SelectLocated selects values from current and/or root and returns them
-	// in [LocatedNode] structs with their located normalized paths
+	// in [LocatedNode] objects with their located normalized paths
 	SelectLocated(current, root any, parent NormalizedPath) []*LocatedNode
 
 	// isSingular returns true for selectors that can only return a single
@@ -44,7 +44,7 @@ type Name string
 // Defined by the [Selector] interface.
 func (Name) isSingular() bool { return true }
 
-// String returns a quoted string representation of n.
+// String returns the quoted string representation of n.
 func (n Name) String() string {
 	return strconv.Quote(string(n))
 }
@@ -166,7 +166,7 @@ func (WildcardSelector) Select(input, _ any) []any {
 }
 
 // SelectLocated selects the values from input and returns them with their
-// normalized paths in a slice of [LocatedNode] structs. Returns an empty
+// normalized paths in a slice of [LocatedNode] objects. Returns an empty
 // slice if input is not []any map[string]any. Defined by the [Selector]
 // interface.
 func (WildcardSelector) SelectLocated(input, _ any, parent NormalizedPath) []*LocatedNode {
@@ -268,7 +268,7 @@ func (i Index) writePointerTo(buf *strings.Builder) {
 //   - [Selector]
 //   - [fmt.Stringer]
 //
-// RFC 9535 Section 2.3.4]: https://www.rfc-editor.org/rfc/rfc9535.html#name-array-slice-selector
+// [RFC 9535 Section 2.3.4]: https://www.rfc-editor.org/rfc/rfc9535.html#name-array-slice-selector
 type SliceSelector struct {
 	// Start of the slice; defaults to 0.
 	start int
@@ -381,7 +381,7 @@ func (s SliceSelector) Select(input, _ any) []any {
 }
 
 // SelectLocated selects values from input for the indexes specified by s and
-// returns thm with their normalized paths as [LocatedNode] structs. Returns
+// returns thm with their normalized paths as [LocatedNode] objects. Returns
 // an empty slice if input is not a slice. Indexes outside the bounds of input
 // will not be included in the return value. Defined by the [Selector]
 // interface.
@@ -495,7 +495,7 @@ func (f *FilterSelector) Select(current, root any) []any {
 	return ret
 }
 
-// SelectLocated selects and returns [LocatedNode] structs with values that f
+// SelectLocated selects and returns [LocatedNode] objects with values that f
 // filters from current. Filter expressions may evaluate the current value
 // (@), the root value ($), or any path expression. Defined by the [Selector]
 // interface.

spec/spec_example_test.go

@@ -191,14 +191,14 @@ func ExampleNonExistExpr() {
 // Construct a path expression as a function argument.
 func ExampleNodesQueryExpr() {
 	reg := registry.New()
-	filter := spec.Filter(spec.And(
-		spec.Function(reg.Get("length"),
-			spec.NodesQuery(
-				spec.Query(false, spec.Child(spec.Index(0))),
-			),
-		)))
-	fmt.Printf("%v\n", filter)
-	// Output: ?length(@[0])
+	fnExpr := spec.Function(
+		reg.Get("length"),
+		spec.NodesQuery(
+			spec.Query(false, spec.Child(spec.Index(0))),
+		),
+	)
+	fmt.Printf("%v\n", fnExpr)
+	// Output: length(@[0])
 }
 
 // Each [spec.FuncType] converted to one of the spec-standard function types,
@@ -332,32 +332,40 @@ func ExampleNodesType() {
 	// Output: [hi 42 true]
 }
 
-// Use a [spec.ParenExpr] to group together a [spec.LogicalAnd].
+// Use a [spec.ParenExpr] to group the result of a [LogicalOr] expression.
 func ExampleParenExpr() {
 	paren := spec.Paren(
 		spec.And(
-			spec.Value(42),
 			spec.Existence(
 				spec.Query(false, spec.Child(spec.Name("answer"))),
 			),
 		),
+		spec.And(
+			spec.Existence(
+				spec.Query(false, spec.Child(spec.Name("question"))),
+			),
+		),
 	)
 	fmt.Printf("%v\n", paren)
-	// Output: (42 && @["answer"])
+	// Output: (@["answer"] || @["question"])
 }
 
-// Use a [spec.NotParenExpr] to negate a [spec.LogicalAnd] group.
+// Use a [spec.NotParenExpr] to negate the result of a [LogicalOr] expression.
 func ExampleNotParenExpr() {
 	not := spec.NotParen(
 		spec.And(
-			spec.Value(42),
 			spec.Existence(
 				spec.Query(false, spec.Child(spec.Name("answer"))),
 			),
 		),
+		spec.And(
+			spec.Existence(
+				spec.Query(false, spec.Child(spec.Name("question"))),
+			),
+		),
 	)
 	fmt.Printf("%v\n", not)
-	// Output: !(42 && @["answer"])
+	// Output: !(@["answer"] || @["question"])
 }
 
 // Compare a normalized JSONPath and its JSON Pointer equivalent.
@@ -386,7 +394,7 @@ func ExampleSingularQueryExpr() {
 	// Output: $["profile"]["contacts"][0]["email"]
 }
 
-// Create [spec.ValueType]s of each supported JSON type.
+// Create A [spec.ValueType] for each supported JSON type.
 func ExampleValueType() {
 	for _, val := range []any{
 		"hello",
@@ -411,6 +419,45 @@ func ExampleValueType() {
 	// [1 2 false]
 }
 
+func ExampleLocatedNode() {
+	// Query all "author" object properties.
+	p := jsonpath.New(spec.Query(
+		true,
+		spec.Descendant(spec.Name("author")),
+	))
+
+	// Select LocatedNodes from unmarshaled JSON input.
+	store := bookstore()
+	nodes := p.SelectLocated(store)
+
+	// Show the LocatedNodes.
+	items, err := json.MarshalIndent(nodes, "", "  ")
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Printf("%s\n", items)
+
+	// Output:
+	// [
+	//   {
+	//     "node": "Nigel Rees",
+	//     "path": "$['store']['book'][0]['author']"
+	//   },
+	//   {
+	//     "node": "Evelyn Waugh",
+	//     "path": "$['store']['book'][1]['author']"
+	//   },
+	//   {
+	//     "node": "Herman Melville",
+	//     "path": "$['store']['book'][2]['author']"
+	//   },
+	//   {
+	//     "node": "J. R. R. Tolkien",
+	//     "path": "$['store']['book'][3]['author']"
+	//   }
+	// ]
+}
+
 // bookstore returns an unmarshaled JSON object.
 func bookstore() any {
 	src := []byte(`{