finishes up delete + adds examples

Author: chanced

README.md

@@ -10,6 +10,11 @@ jsonpointer was built to support
 [github.com/chanced/openapi](https://github.com/chanced/openapi) but it may be
 useful for others so it has been released as an independent package.
 
+For the openapi package, I needed a way to resolve and assign JSON Pointers
+against concrete types while also maintaining integrity of pointer values. All
+existing JSON Pointer implementations for Go operate on `map[string]interface{}`
+and `[]interface{}`, raw JSON, or both.
+
 ## Install
 
 ```bash
@@ -119,7 +124,7 @@ All methods return new values rather than modifying the pointer itself. If you w
 func (mt MyType) ResolveJSONPointer(ptr *jsonpointer.JSONPointer, op Operation) (interface{}, error) {
     next, t, ok := ptr.Next()
     if !ok {
-        // this will only occur if the ptr is a root token
+        // this will only occur if the ptr is a root token in this circumstance
         return mt
     }
     if op == jsonpointer.Assigning && t == "someInterface" {

assign.go

@@ -17,10 +17,27 @@ import (
 	"reflect"
 )
 
+// Assigner is the interface implemented by types which can assign values via
+// JSON Pointers. The input can be assumed to be a valid JSON Pointer and the
+// value to assign.
+//
+// AssignByJSONPointer is called after the value has been resolved. If custom
+// resolution is needed, the type should also implement Resolver.
+//
 type Assigner interface {
 	AssignByJSONPointer(ptr *JSONPointer, value interface{}) error
 }
 
+// Assign performs an assignment of value to the target dst specified by the
+// JSON Pointer ptr. Assign traverses dst recursively, resolving the path of
+// the JSON Pointer. If a type in the path implements Resolver, it will attempt
+// to resolve by invoking ResolveJSONPointer on that value. If ResolveJSONPointer
+// returns YieldOperation or if the value does not implement ResolveJSONPointer,
+// encoding/json naming conventions are utilized to resolve the path.
+//
+// If a type in the path implements Assigner, AssignByJSONPointer will be called
+// with the updated value pertinent to that path.
+//
 func Assign(dst interface{}, ptr JSONPointer, value interface{}) error {
 	if err := ptr.Validate(); err != nil {
 		return err

assign_test.go

@@ -33,14 +33,14 @@ func TestAssign(t *testing.T) {
 		value interface{}
 		run   func(v interface{}, err error)
 	}{
-		{"/nested/str", "strval", func(val interface{}, err error) {
-			assert.NoError(err)
-			assert.Equal(val, r.Nested.Str)
-		}},
-		{"/nestedptr/str", "x", func(val interface{}, err error) {
-			assert.NoError(err)
-			assert.Equal(val, r.NestedPtr.Str)
-		}},
+		// {"/nested/str", "strval", func(val interface{}, err error) {
+		// 	assert.NoError(err)
+		// 	assert.Equal(val, r.Nested.Str)
+		// }},
+		// {"/nestedptr/str", "x", func(val interface{}, err error) {
+		// 	assert.NoError(err)
+		// 	assert.Equal(val, r.NestedPtr.Str)
+		// }},
 		{"/nested/entrymap/keyval/name", "entry-name", func(v interface{}, err error) {
 			assert.NoError(err)
 			assert.Contains(r.Nested.EntryMap, "keyval")
@@ -165,7 +165,7 @@ func TestAssignAny(t *testing.T) {
 	}
 
 	for i, test := range tests {
-		fmt.Printf("=== RUN TestAssignAny #%d, pointer %s\n", i, test.ptr)
+		fmt.Printf("=== RUN TestAssignAny #%d, pointer %s\n", i+1, test.ptr)
 		err := jsonpointer.Assign(&m, test.ptr, test.value)
 		if test.err != nil {
 			assert.ErrorIs(err, test.err)
@@ -204,7 +204,7 @@ func TestAssignJSON(t *testing.T) {
 	}
 
 	for i, test := range tests {
-		fmt.Printf("=== RUN TestAssignJSON #%d, pointer %s\n", i, test.ptr)
+		fmt.Printf("=== RUN TestAssignJSON #%d, pointer %s\n", i+1, test.ptr)
 		b := []byte(test.json)
 		err := jsonpointer.Assign(&b, test.ptr, test.value)
 		var r Root

delete.go

@@ -19,12 +19,16 @@ type Deleter interface {
 	DeleteByJSONPointer(ptr *JSONPointer) error
 }
 
+// Delete deletes the value at the given JSON pointer from src.
+//
+// If any part of the path is unreachable, the Delete function is
+// considered a success as the value is not present to delete.
 func Delete(src interface{}, ptr JSONPointer) error {
 	if err := ptr.Validate(); err != nil {
 		return err
 	}
 	dv := reflect.ValueOf(src)
-	s := newState(ptr, Assigning)
+	s := newState(ptr, Deleting)
 	defer s.Release()
 	if dv.Kind() != reflect.Ptr || dv.IsNil() {
 		return &ptrError{

delete_test.go

@@ -14,6 +14,7 @@
 package jsonpointer_test
 
 import (
+	"encoding/json"
 	"fmt"
 	"testing"
 
@@ -29,14 +30,67 @@ func TestDelete(t *testing.T) {
 		root Root
 		run  func(r Root, err error)
 	}{
-		{"/nested/str", Root{Nested: Nested{Str: "str val"}}, func(r Root, err error) {
+		{"/nested/str", Root{Nested: Nested{Str: "str val", Int: 5}}, func(r Root, err error) {
 			assert.NoError(err)
 			assert.Equal("", r.Nested.Str)
+			assert.Equal(5, r.Nested.Int)
+		}},
+		{"/nested", Root{Nested: Nested{Str: "str val", Int: 5}}, func(r Root, err error) {
+			assert.NoError(err)
+			assert.Equal("", r.Nested.Str)
+			assert.Equal(0, r.Nested.Int)
+		}},
+		{"/nested/deleter/key", Root{Nested: Nested{Deleter: DeleterImpl{Values: map[string]string{"key": "value"}}}}, func(r Root, err error) {
+			assert.NotContains(r.Nested.Deleter.Values, "key")
+			assert.NoError(err)
 		}},
 	}
+
 	for i, test := range tests {
 		fmt.Printf("=== RUN TestDelete #%d, pointer %s\n", i, test.ptr)
 		err := jsonpointer.Delete(&test.root, test.ptr)
 		test.run(test.root, err)
+
+	}
+}
+
+func TestDeleteJSON(t *testing.T) {
+	assert := require.New(t)
+
+	tests := []struct {
+		ptr  jsonpointer.JSONPointer
+		root Root
+		run  func(r Root, err error)
+	}{
+		{"/nested/str", Root{Nested: Nested{Str: "string", Int: 5}}, func(r Root, err error) {
+			assert.NoError(err)
+			assert.Equal("", r.Nested.Str)
+			assert.Equal(5, r.Nested.Int)
+		}},
+		{"/nested", Root{Nested: Nested{Str: "str val", Int: 5}}, func(r Root, err error) {
+			assert.NoError(err)
+			assert.Equal("", r.Nested.Str)
+			assert.Equal(0, r.Nested.Int)
+		}},
+
+		{"/nested/strslice/1", Root{Nested: Nested{StrSlice: []string{"0", "1", "2"}}}, func(r Root, err error) {
+			assert.NoError(err)
+			assert.Len(r.Nested.StrSlice, 2)
+			assert.Equal("2", r.Nested.StrSlice[1])
+		}},
+	}
+
+	for i, test := range tests {
+		fmt.Printf("=== RUN TestDelete #%d, pointer %s\n", i, test.ptr)
+		b, err := json.Marshal(test.root)
+		fmt.Println(string(b))
+
+		assert.NoError(err)
+		err = jsonpointer.Delete(&b, test.ptr)
+		var r Root
+		uerr := json.Unmarshal(b, &r)
+		assert.NoError(uerr)
+		fmt.Println(string(b))
+		test.run(r, err)
 	}
 }

errors.go

@@ -27,7 +27,13 @@ var (
 	// This error is returned by JSONPointer.Validate() which is called by
 	// Resolve, Assign, and Delete.
 	//
-	ErrMalformedToken = fmt.Errorf(`jsonpointer: reference must be empty or start with a "/"`)
+	ErrMalformedToken = errors.New(`jsonpointer: fragment is malformed`)
+
+	// ErrMalformedStart is an ErrMalformedToken that is returned when the JSON
+	// Pointer is not empty or does not start with a "/".
+	ErrMalformedStart = fmt.Errorf(`%w; pointer must be an empty string or start with "/"`, ErrMalformedToken)
+
+	ErrMalformedEncoding = fmt.Errorf("%w; '~' must be encoded as ~0", ErrMalformedToken)
 
 	// ErrNonPointer indicates a non-pointer value was passed to Assign.
 	//

examples_test.go

@@ -0,0 +1,107 @@
+package jsonpointer_test
+
+import (
+	"encoding/json"
+	"fmt"
+
+	"github.com/chanced/jsonpointer"
+)
+
+func ExampleNew() {
+	ptr := jsonpointer.New("foo", "bar") // => "/foo/bar"
+	fmt.Println(`"` + ptr + `"`)
+
+	ptr = jsonpointer.New("foo/bar") // => "/foo~1bar"
+	fmt.Println(`"` + ptr + `"`)
+
+	ptr = jsonpointer.New() // => ""
+	fmt.Println(`"` + ptr + `"`)
+
+	ptr = jsonpointer.New("") // => "/"
+	fmt.Println(`"` + ptr + `"`)
+
+	ptr = jsonpointer.New("/") // => "/~1"
+	fmt.Println(`"` + ptr + `"`)
+
+	ptr = jsonpointer.New("~") // => "/~0"
+	fmt.Println(`"` + ptr + `"`)
+
+	ptr = jsonpointer.New("#/foo/bar") // => "/#~1foo~1bar"
+	fmt.Println(`"` + ptr + `"`)
+
+	// Output:
+	// "/foo/bar"
+	// "/foo~1bar"
+	// ""
+	// "/"
+	// "/~1"
+	// "/~0"
+	// "/#~1foo~1bar"
+}
+
+func ExampleAssign() {
+	type Bar struct {
+		Baz string `json:"baz"`
+	}
+	type Foo struct {
+		Bar Bar `json:"bar"`
+	}
+	var foo Foo
+	jsonpointer.Assign(&foo, "/bar/baz", "qux")
+	fmt.Println(foo.Bar.Baz)
+
+	// Assigning JSON by JSONPointer
+
+	foo.Bar.Baz = "quux"
+	b, _ := json.Marshal(foo)
+	jsonpointer.Assign(&b, "/bar/baz", "corge")
+	fmt.Println(string(b))
+
+	//Output: qux
+	//{"bar":{"baz":"corge"}}
+}
+
+func ExampleResolve() {
+	type Bar struct {
+		Baz string `json:"baz"`
+	}
+	type Foo struct {
+		Bar Bar `json:"bar,omitempty"`
+	}
+	foo := Foo{Bar{Baz: "qux"}}
+
+	var s string
+	jsonpointer.Resolve(foo, "/bar/baz", &s)
+	fmt.Println(s)
+
+	// Resolving JSON by JSONPointer
+
+	b, _ := json.Marshal(foo)
+	jsonpointer.Resolve(b, "/bar/baz", &s)
+	fmt.Println(s)
+
+	// Output: qux
+	// qux
+}
+
+func ExampleDelete() {
+	type Bar struct {
+		Baz string `json:"baz,omitempty"`
+	}
+	type Foo struct {
+		Bar Bar `json:"bar"`
+	}
+	foo := Foo{Bar{Baz: "qux"}}
+
+	jsonpointer.Delete(foo, "/bar/baz")
+	fmt.Printf("foo.Bar.Baz: %v\n", foo.Bar.Baz)
+
+	// Deleting JSON by JSONPointer
+	foo.Bar.Baz = "quux"
+	b, _ := json.Marshal(foo)
+	jsonpointer.Delete(&b, "/bar/baz")
+	fmt.Println(string(b))
+
+	// Output: foo.Bar.Baz: qux
+	// {"bar":{}}
+}

jsonpointer.go

@@ -42,7 +42,6 @@ const (
 //  jsonpointer.New("") => "/"
 //  jsonpointer.New("/") => "/~1"
 //  jsonpointer.New("~") => "/~0"
-//  jsonpointer.New("\\#") => "/#"
 //
 func New(tokens ...string) JSONPointer {
 	return NewFromStrings(tokens)
@@ -58,12 +57,6 @@ func NewFromStrings(tokens []string) JSONPointer {
 	if len(tokens) == 0 {
 		return ""
 	}
-	switch tokens[0] {
-	case "#":
-		tokens = tokens[1:]
-	case "\\#":
-		tokens[0] = "#"
-	}
 	for _, token := range tokens {
 		b.WriteRune('/')
 		if _, err := encoder.WriteString(b, token); err != nil {
@@ -114,19 +107,28 @@ func (p JSONPointer) PrependString(token string) JSONPointer {
 	return p.Prepend(Token(encoder.Replace(token)))
 }
 
-func (p JSONPointer) Validate() error {
-	if err := p.validateStart(); err != nil {
+func (p JSONPointer) Validate() (err error) {
+	if err = p.validateStart(); err != nil {
 		return err
 	}
+	return p.validateeEncoding()
+}
+
+func (p JSONPointer) validateeEncoding() error {
+	if len(p) == 0 {
+		return nil
+	}
+	for i := len(p) - 1; i >= 0; i-- {
+		if p[i] == '~' && (i == len(p)-1 || (p[i+1] != '0' && p[i+1] != '1')) {
+			return ErrMalformedEncoding
+		}
+	}
 	return nil
 }
 
 func (p JSONPointer) validateStart() error {
-	if !startsWithSlash(p) {
-		return &ptrError{
-			err:   ErrMalformedToken,
-			state: *newState(p, 0),
-		}
+	if len(p) > 0 && !startsWithSlash(p) {
+		return ErrMalformedStart
 	}
 	return nil
 }
@@ -198,6 +200,9 @@ func lastSlash(ptr JSONPointer) int {
 }
 
 func startsWithSlash(ptr JSONPointer) bool {
+	if len(ptr) == 0 {
+		return false
+	}
 	return ptr[0] == '/'
 }