Add Pointer method to NormalizedPath

Author: theory

CHANGELOG.md

@@ -7,6 +7,16 @@ 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.4.0] — Unreleased
+
+### ⚡ Improvements
+
+*   Added the `Pointer` method to `NormalizedPath`. It returns an [RFC 9535
+    JSON Pointer] string representation of the normalized path.
+
+  [v0.4.0]: https://github.com/theory/jsonpath/compare/v0.3.0...v0.4.0
+  [RFC 9535 JSON Pointer]: https://www.rfc-editor.org/rfc/rfc9535#name-normalized-paths
+
 ## [v0.3.0] — 2024-12-28
 
 ### ⚡ Improvements

spec/normalized.go

@@ -8,10 +8,17 @@ import (
 // NormalSelector represents a single selector in a normalized path.
 // Implemented by [Name] and [Index].
 type NormalSelector interface {
-	// writeNormalizedTo writes n to buf formatted as a [normalized path] element.
+	// writeNormalizedTo writes the selector to buf formatted as a [normalized
+	// path] element.
 	//
 	// [normalized path]: https://www.rfc-editor.org/rfc/rfc9535#section-2.7
 	writeNormalizedTo(buf *strings.Builder)
+
+	// writePointerTo writes the selector to buf formatted as a [JSON Pointer]
+	// reference token.
+	//
+	// [JSON Pointer]: https://www.rfc-editor.org/rfc/rfc6901
+	writePointerTo(buf *strings.Builder)
 }
 
 // NormalizedPath represents a normalized path identifying a single value in a
@@ -30,6 +37,18 @@ func (np NormalizedPath) String() string {
 	return buf.String()
 }
 
+// Pointer returns an [RFC 6901 JSON Pointer] string representation of np.
+//
+// [RFC 6901 JSON Pointer]: https://www.rfc-editor.org/rfc/rfc6901
+func (np NormalizedPath) Pointer() string {
+	buf := new(strings.Builder)
+	for _, e := range np {
+		buf.WriteRune('/')
+		e.writePointerTo(buf)
+	}
+	return buf.String()
+}
+
 // Compare compares np to np2 and returns -1 if np is less than np2, 1 if it's
 // greater than np2, and 0 if they're equal. Indexes are always considered
 // less than names.

spec/normalized_test.go

@@ -16,49 +16,66 @@ func TestNormalSelector(t *testing.T) {
 	for _, tc := range []struct {
 		name string
 		elem NormalSelector
-		exp  string
+		str  string
+		ptr  string
 	}{
 		{
 			name: "object_value",
 			elem: Name("a"),
-			exp:  `['a']`,
+			str:  `['a']`,
+			ptr:  `a`,
 		},
 		{
 			name: "array_index",
 			elem: Index(1),
-			exp:  `[1]`,
+			str:  `[1]`,
+			ptr:  `1`,
 		},
 		{
 			name: "escape_apostrophes",
 			elem: Name("'hi'"),
-			exp:  `['\'hi\'']`,
+			str:  `['\'hi\'']`,
+			ptr:  "'hi'",
 		},
 		{
 			name: "escapes",
 			elem: Name("'\b\f\n\r\t\\'"),
-			exp:  `['\'\b\f\n\r\t\\\'']`,
+			str:  `['\'\b\f\n\r\t\\\'']`,
+			ptr:  "'\b\f\n\r\t\\'",
 		},
 		{
 			name: "escape_vertical_unicode",
 			elem: Name("\u000B"),
-			exp:  `['\u000b']`,
+			str:  `['\u000b']`,
+			ptr:  "\u000B",
 		},
 		{
 			name: "escape_unicode_null",
 			elem: Name("\u0000"),
-			exp:  `['\u0000']`,
+			str:  `['\u0000']`,
+			ptr:  "\u0000",
 		},
 		{
 			name: "escape_unicode_runes",
 			elem: Name("\u0001\u0002\u0003\u0004\u0005\u0006\u0007\u000e\u000F"),
-			exp:  `['\u0001\u0002\u0003\u0004\u0005\u0006\u0007\u000e\u000f']`,
+			str:  `['\u0001\u0002\u0003\u0004\u0005\u0006\u0007\u000e\u000f']`,
+			ptr:  "\u0001\u0002\u0003\u0004\u0005\u0006\u0007\u000e\u000F",
+		},
+		{
+			name: "escape_pointer",
+			elem: Name("this / ~that"),
+			str:  `['this / ~that']`,
+			ptr:  "this ~1 ~0that",
 		},
 	} {
 		t.Run(tc.name, func(t *testing.T) {
 			t.Parallel()
 			buf := new(strings.Builder)
 			tc.elem.writeNormalizedTo(buf)
-			a.Equal(tc.exp, buf.String())
+			a.Equal(tc.str, buf.String())
+			buf.Reset()
+			tc.elem.writePointerTo(buf)
+			a.Equal(tc.ptr, buf.String())
 		})
 	}
 }
@@ -70,42 +87,62 @@ func TestNormalizedPath(t *testing.T) {
 	for _, tc := range []struct {
 		name string
 		path NormalizedPath
-		exp  string
+		str  string
+		ptr  string
 	}{
+		{
+			name: "empty_path",
+			path: NormalizedPath{},
+			str:  "$",
+			ptr:  "",
+		},
 		{
 			name: "object_value",
 			path: NormalizedPath{Name("a")},
-			exp:  "$['a']",
+			str:  "$['a']",
+			ptr:  "/a",
 		},
 		{
 			name: "array_index",
 			path: NormalizedPath{Index(1)},
-			exp:  "$[1]",
+			str:  "$[1]",
+			ptr:  "/1",
 		},
 		{
 			name: "neg_for_len_5",
 			path: NormalizedPath{Index(2)},
-			exp:  "$[2]",
+			str:  "$[2]",
+			ptr:  "/2",
 		},
 		{
 			name: "nested_structure",
 			path: NormalizedPath{Name("a"), Name("b"), Index(1)},
-			exp:  "$['a']['b'][1]",
+			str:  "$['a']['b'][1]",
+			ptr:  "/a/b/1",
 		},
 		{
 			name: "unicode_escape",
 			path: NormalizedPath{Name("\u000B")},
-			exp:  `$['\u000b']`,
+			str:  `$['\u000b']`,
+			ptr:  "/\u000b",
 		},
 		{
 			name: "unicode_character",
 			path: NormalizedPath{Name("\u0061")},
-			exp:  "$['a']",
+			str:  "$['a']",
+			ptr:  "/a",
+		},
+		{
+			name: "nested_structure_pointer_stuff",
+			path: NormalizedPath{Name("a~x"), Name("b/2"), Index(1)},
+			str:  "$['a~x']['b/2'][1]",
+			ptr:  "/a~0x/b~12/1",
 		},
 	} {
 		t.Run(tc.name, func(t *testing.T) {
 			t.Parallel()
-			a.Equal(tc.exp, tc.path.String())
+			a.Equal(tc.str, tc.path.String())
+			a.Equal(tc.ptr, tc.path.Pointer())
 		})
 	}
 }

spec/selector.go

@@ -77,7 +77,7 @@ func (n Name) SelectLocated(input, _ any, parent NormalizedPath) []*LocatedNode
 }
 
 // writeNormalizedTo writes n to buf formatted as a [normalized path] element.
-// Implements [NormalSelector].
+// Defined by [NormalSelector].
 //
 // [normalized path]: https://www.rfc-editor.org/rfc/rfc9535#section-2.7
 func (n Name) writeNormalizedTo(buf *strings.Builder) {
@@ -109,6 +109,17 @@ func (n Name) writeNormalizedTo(buf *strings.Builder) {
 	buf.WriteString("']")
 }
 
+// writePointerTo writes n to buf formatted as a [JSON Pointer] reference
+// token. Defined by [NormalSelector].
+//
+// [JSON Pointer]: https://www.rfc-editor.org/rfc/rfc6901
+func (n Name) writePointerTo(buf *strings.Builder) {
+	buf.WriteString(strings.ReplaceAll(
+		strings.ReplaceAll(string(n), "~", "~0"),
+		"/", "~1",
+	))
+}
+
 // WildcardSelector is the underlying nil value used by [Wildcard].
 type WildcardSelector struct{}
 
@@ -226,6 +237,14 @@ func (i Index) writeNormalizedTo(buf *strings.Builder) {
 	buf.WriteRune(']')
 }
 
+// writePointerTo writes n to buf formatted as a [JSON Pointer] reference
+// token. Defined by [NormalSelector].
+//
+// [JSON Pointer]: https://www.rfc-editor.org/rfc/rfc6901
+func (i Index) writePointerTo(buf *strings.Builder) {
+	buf.WriteString(strconv.FormatInt(int64(i), 10))
+}
+
 // SliceSelector is a slice selector, e.g., [0:100:5].
 type SliceSelector struct {
 	// Start of the slice; defaults to 0.