Expand conversion examples, docs

Author: theory

path.go

@@ -62,7 +62,7 @@ func (p *Path) SelectLocated(input any) LocatedNodeList {
 	return p.q.SelectLocated(nil, input, spec.Normalized())
 }
 
-// Parser parses JSONPath strings into [Path]s.
+// Parser parses JSONPath strings into [Path] objects.
 type Parser struct {
 	reg *registry.Registry
 }

spec/function.go

@@ -43,23 +43,26 @@ const (
 	FuncLogical
 )
 
-// ConvertsToValue returns true if ft can be converted to a [ValueType]. Used
-// by [github.com/theory/jsonpath/registry.NewFunction] validator functions
-// to ensure the compatibility of parameter expressions.
+// ConvertsToValue returns true if ft can be converted to a [ValueType]. In
+// other words, ft values can safely be passed to [ValueFrom] without it
+// panicking. Used by [github.com/theory/jsonpath/registry.NewFunction]
+// validator functions to ensure the compatibility of parameter expressions.
 func (ft FuncType) ConvertsToValue() bool {
 	return ft == FuncValue || ft == FuncLiteral || ft == FuncSingularQuery
 }
 
 // ConvertsToLogical returns true if ft can be converted to a [LogicalType].
-// Used by [github.com/theory/jsonpath/registry.NewFunction] validator
-// functions to ensure the compatibility of parameter expressions.
+// In other words, ft values can safely be passed to [LogicalFrom] without it
+// panicking. Used by [github.com/theory/jsonpath/registry.NewFunction]
+// validator functions to ensure the compatibility of parameter expressions.
 func (ft FuncType) ConvertsToLogical() bool {
 	return ft == FuncLogical || ft == FuncNodes || ft == FuncSingularQuery
 }
 
-// ConvertsToNodes returns true if ft can be converted to a [NodesType]. Used
-// by [github.com/theory/jsonpath/registry.NewFunction] validator functions to
-// ensure the compatibility of parameter expressions.
+// ConvertsToNodes returns true if ft can be converted to a [NodesType]. In
+// other words, ft values can safely be passed to [NodesFrom] without it
+// panicking. Used by [github.com/theory/jsonpath/registry.NewFunction]
+// validator functions to ensure the compatibility of parameter expressions.
 func (ft FuncType) ConvertsToNodes() bool {
 	return ft == FuncNodes || ft == FuncSingularQuery
 }
@@ -103,9 +106,10 @@ func Nodes(val ...any) NodesType {
 func (NodesType) FuncType() FuncType { return FuncNodes }
 
 // NodesFrom attempts to convert value to a [NodesType] and panics if it
-// cannot. Used by [github.com/theory/jsonpath/registry.NewFunction] evaluator
-// functions to convert types, which should have already been validated by the
-// validator function.
+// cannot. Should only be used for a value whose [FuncType.ConvertsToNodes]
+// returns true. Use in [github.com/theory/jsonpath/registry.NewFunction]
+// evaluator functions to convert types, which should have already been
+// validated by [FuncType.ConvertsToNodes] in the validator function.
 func NodesFrom(value JSONPathValue) NodesType {
 	switch v := value.(type) {
 	case NodesType:
@@ -163,9 +167,10 @@ func (lt LogicalType) Bool() bool { return lt == LogicalTrue }
 func (LogicalType) FuncType() FuncType { return FuncLogical }
 
 // LogicalFrom attempts to convert value to a [LogicalType] and panics if it
-// cannot. Used by [github.com/theory/jsonpath/registry.NewFunction] evaluator
-// functions to convert types, which should have already been validated by the
-// validator function.
+// cannot. Should only be used for a value whose [FuncType.ConvertsToLogical]
+// returns true. Use in [github.com/theory/jsonpath/registry.NewFunction]
+// evaluator functions to convert types, which should have already been
+// validated by [FuncType.ConvertsToLogical] in the validator function.
 func LogicalFrom(value any) LogicalType {
 	switch v := value.(type) {
 	case LogicalType:
@@ -221,10 +226,11 @@ func (vt *ValueType) String() string { return fmt.Sprintf("%v", vt.any) }
 // FuncType returns [FuncValue]. Defined by the [JSONPathValue] interface.
 func (*ValueType) FuncType() FuncType { return FuncValue }
 
-// ValueFrom attempts to convert value to a ValueType and panics if it cannot.
-// Used by [github.com/theory/jsonpath/registry.NewFunction] evaluator
-// functions to convert types, which should have already been validated by the
-// validator function.
+// ValueFrom attempts to convert value to a [ValueType] and panics if it
+// cannot. Should only be used for a value whose [FuncType.ConvertsToValue]
+// returns true. Use in [github.com/theory/jsonpath/registry.NewFunction]
+// evaluator functions to convert types, which should have already been
+// validated by [FuncType.ConvertsToValue] in the validator function.
 func ValueFrom(value JSONPathValue) *ValueType {
 	switch v := value.(type) {
 	case *ValueType:

spec/op.go

@@ -97,8 +97,8 @@ func (ce *ComparisonExpr) testFilter(current, root any) bool {
 	}
 }
 
-// equalTo returns true if left and right are nils, or if both are
-// [ValueType]s and [valueEqualTo] returns true for their underlying values.
+// equalTo returns true if left and right are nils, or if both are [ValueType]
+// objects and [valueEqualTo] returns true for their underlying values.
 // Otherwise it returns false.
 func equalTo(left, right JSONPathValue) bool {
 	switch left := left.(type) {

spec/spec_example_test.go

@@ -419,6 +419,47 @@ func ExampleValueType() {
 	// [1 2 false]
 }
 
+func ExampleValueFrom() {
+	for _, val := range []spec.JSONPathValue{
+		spec.Value("hello"), // converts to value
+		spec.Nodes(1, 2, 3), // does not convert to value
+		spec.Logical(false), // does not convert to value
+	} {
+		if val.FuncType().ConvertsToValue() {
+			fmt.Printf("val: %v\n", spec.ValueFrom(val))
+		}
+	}
+	// Output: val: hello
+}
+
+func ExampleNodesFrom() {
+	for _, val := range []spec.JSONPathValue{
+		spec.Value("hello"), // does not convert to nodes
+		spec.Nodes(1, 2, 3), // converts to nodes
+		spec.Logical(false), // does not convert to nodes
+	} {
+		if val.FuncType().ConvertsToNodes() {
+			fmt.Printf("nodes: %v\n", spec.NodesFrom(val))
+		}
+	}
+	// Output: nodes: [1 2 3]
+}
+
+func ExampleLogicalFrom() {
+	for _, val := range []spec.JSONPathValue{
+		spec.Value("hello"), // does not convert to logical
+		spec.Nodes(1, 2, 3), // converts to logical (existence)
+		spec.Logical(false), // converts to logical
+	} {
+		if val.FuncType().ConvertsToLogical() {
+			fmt.Printf("logical: %v\n", spec.LogicalFrom(val))
+		}
+	}
+	// Output:
+	// logical: true
+	// logical: false
+}
+
 func ExampleLocatedNode() {
 	// Query all "author" object properties.
 	p := jsonpath.New(spec.Query(