Finish examples

Author: theory

spec/filter.go

@@ -114,6 +114,13 @@ func (p *ParenExpr) writeTo(buf *strings.Builder) {
 	buf.WriteRune(')')
 }
 
+// String returns the string representation of p.
+func (p *ParenExpr) String() string {
+	var buf strings.Builder
+	p.writeTo(&buf)
+	return buf.String()
+}
+
 // NotParenExpr represents a parenthesized expression preceded with a !.
 type NotParenExpr struct {
 	LogicalOr
@@ -131,6 +138,13 @@ func (np *NotParenExpr) writeTo(buf *strings.Builder) {
 	buf.WriteRune(')')
 }
 
+// String returns the string representation of np.
+func (np *NotParenExpr) String() string {
+	var buf strings.Builder
+	np.writeTo(&buf)
+	return buf.String()
+}
+
 // testFilter returns false if the np.LogicalOrExpression returns true and
 // true if it returns false.
 func (np *NotParenExpr) testFilter(current, root any) bool {

spec/function.go

@@ -115,7 +115,8 @@ func (nt NodesType) String() string {
 	return fmt.Sprintf("%v", []any(nt))
 }
 
-// LogicalType is a JSONPath type that represents true or false.
+// LogicalType is a JSONPath type that represents true or false. Generally
+// used as a function return value or argument.
 type LogicalType uint8
 
 const (
@@ -296,7 +297,9 @@ func (la *LiteralArg) asValue(_, _ any) JSONPathValue {
 }
 
 // SingularQueryExpr represents a query that produces a single [ValueType]
-// (JSON value), or nothing.
+// (JSON value), or nothing. Used in contexts that require a singular value,
+// such as comparison operations and function arguments. It therefor
+// implements [CompVal] and [FunctionExprArg].
 type SingularQueryExpr struct {
 	// The kind of singular query, relative (from the current node) or
 	// absolute (from the root node).

spec/normalized.go

@@ -22,7 +22,10 @@ type NormalSelector interface {
 }
 
 // NormalizedPath represents a normalized path identifying a single value in a
-// JSON query argument, as [defined by RFC 9535].
+// JSON query argument, as [defined by RFC 9535]. Defines a simplified string
+// format that exclusively uses single quotation marks for names. Useful for
+// converting to JSON Pointer (via [NormalizedPath.Pointer]) or other JSON
+// pointer-type formats.
 //
 // [defined by RFC 9535]: https://www.rfc-editor.org/rfc/rfc9535#name-normalized-paths
 type NormalizedPath []NormalSelector

spec/spec_example_test.go

@@ -317,13 +317,98 @@ func ExampleLogicalOr() {
 	// Output: @["answer"] || 42
 }
 
-// type LogicalType
-// type NodesType
-// type NormalizedPath
-// type NotParenExpr
-// type ParenExpr
-// type SingularQueryExpr
-// type ValueType
+func ExampleLogicalType() {
+	fmt.Printf("%v\n", spec.Logical(true))
+	fmt.Printf("%v\n", spec.Logical(false))
+	// Output:
+	// true
+	// false
+}
+
+// Use a [spec.NodesType] to create a list of nodes, a.k.a. a JSON array.
+func ExampleNodesType() {
+	fmt.Printf("%v\n", spec.Nodes("hi", 42, true))
+	// Output: [hi 42 true]
+}
+
+// Use a [spec.ParenExpr] to group together a [spec.LogicalAnd].
+func ExampleParenExpr() {
+	paren := spec.Paren(
+		spec.And(
+			spec.Value(42),
+			spec.Existence(
+				spec.Query(false, spec.Child(spec.Name("answer"))),
+			),
+		),
+	)
+	fmt.Printf("%v\n", paren)
+	// Output: (42 && @["answer"])
+}
+
+// Use a [spec.NotParenExpr] to negate a [spec.LogicalAnd] group.
+func ExampleNotParenExpr() {
+	not := spec.NotParen(
+		spec.And(
+			spec.Value(42),
+			spec.Existence(
+				spec.Query(false, spec.Child(spec.Name("answer"))),
+			),
+		),
+	)
+	fmt.Printf("%v\n", not)
+	// Output: !(42 && @["answer"])
+}
+
+// Compare a normalized JSONPath and its JSON Pointer equivalent.
+func ExampleNormalizedPath() {
+	norm := spec.Normalized(
+		spec.Name("x"),
+		spec.Index(1),
+		spec.Name("y"),
+	)
+	fmt.Printf("%v\n", norm)
+	fmt.Printf("%v\n", norm.Pointer())
+	// Output:
+	// $['x'][1]['y']
+	// /x/1/y
+}
+
+func ExampleSingularQueryExpr() {
+	singular := spec.SingularQuery(
+		true,
+		spec.Name("profile"),
+		spec.Name("contacts"),
+		spec.Index(0),
+		spec.Name("email"),
+	)
+	fmt.Printf("%v\n", singular)
+	// Output: $["profile"]["contacts"][0]["email"]
+}
+
+// Create [spec.ValueType]s of each supported JSON type.
+func ExampleValueType() {
+	for _, val := range []any{
+		"hello",
+		42,
+		98.6,
+		json.Number("1024"),
+		true,
+		nil,
+		map[string]any{"x": true},
+		[]any{1, 2, false},
+	} {
+		fmt.Printf("%v\n", spec.Value(val))
+	}
+	// Output:
+	// hello
+	// 42
+	// 98.6
+	// 1024
+	// true
+	// <nil>
+	// map[x:true]
+	// [1 2 false]
+}
 
 // bookstore returns an unmarshaled JSON object.
 func bookstore() any {