allow optionality for key=val tokens

Author: cppforlife

docs/examples.md

@@ -1,19 +1,25 @@
 ## Pointer syntax
 
 - pointers always start at the root of the document
+
 - strings typically refer to hash keys (ex: `/key1`)
   - strings ending with `?` refer to hash keys that may or may not exist
+    - "optionality" carries over to the items to the right
+
 - integers refer to array indices (ex: `/0`, `/-1`)
+
 - `-` refers to an imaginary index after last array index (ex: `/-`)
-- `key=val` notation matches hashes (ex: `/key=val`)
+
+- `key=val` notation matches hashes within an array (ex: `/key=val`)
+  - values ending with `?` refer to array items that may or may not exist
 
 See pointer test examples in [patch/pointer_test.go](../patch/pointer_test.go).
 
 ## Operations
 
 Following example is used to demonstrate operations below:
 
-```
+```yaml
 key: 1
 
 key2:
@@ -74,7 +80,17 @@ There are two available operations: `replace` and `remove`.
 
 - requires that `key2` hash exists
 - allows `nested`, `another_nested` and `super_nested` not to exist because `?` carries over to nested keys
-- creates `another_nested` and `super_nested` before sets `super_nested` to `10`
+- creates `another_nested` and `super_nested` before setting `super_nested` to `10`, resulting in:
+
+  ```yaml
+  ...
+  key2:
+    nested:
+      another_nested:
+        super_nested: 10
+      super_nested: 2
+    other: 3
+  ```
 
 ### Array
 
@@ -116,7 +132,7 @@ There are two available operations: `replace` and `remove`.
 - finds array item with matching key `name` with value `item7`
 - adds `count` key as a sibling of name, resulting in:
 
-	```
+	```yaml
 	...
 	items:
 	- name: item7
@@ -132,4 +148,23 @@ There are two available operations: `replace` and `remove`.
 
 - errors because there are two values that have `item8` as their `name`
 
+```yaml
+- type: replace
+  path: /items/name=item9?/count
+  value: 10
+```
+
+- appends array item with matching key `name` with value `item9` because values ends with `?` and item does not exist
+- creates `count` and sets it to `10` within created array item, resulting in:
+
+  ```yaml
+  ...
+  items:
+  - name: item7
+  - name: item8
+  - name: item8
+  - name: item9
+    count: 10
+  ```
+
 See full example in [patch/integration_test.go](../patch/integration_test.go).

patch/ops.go

@@ -7,6 +7,7 @@ type Op interface {
 }
 
 // Ensure basic operations implement Op
+var _ Op = Ops{}
 var _ Op = ReplaceOp{}
 var _ Op = RemoveOp{}
 var _ Op = ErrOp{}

patch/pointer.go

@@ -46,17 +46,13 @@ func NewPointerFromString(str string) (Pointer, error) {
 
 		tok = rfc6901Decoder.Replace(tok)
 
+		// parse as after last index
 		if isLast && tok == "-" {
 			tokens = append(tokens, AfterLastIndexToken{})
 			continue
 		}
 
-		kv := strings.SplitN(tok, "=", 2)
-		if len(kv) == 2 {
-			tokens = append(tokens, MatchingIndexToken{Key: kv[0], Value: kv[1]})
-			continue
-		}
-
+		// parse as index
 		idx, err := strconv.Atoi(tok)
 		if err == nil {
 			tokens = append(tokens, IndexToken{idx})
@@ -67,6 +63,20 @@ func NewPointerFromString(str string) (Pointer, error) {
 			optional = true
 		}
 
+		// parse name=val
+		kv := strings.SplitN(tok, "=", 2)
+		if len(kv) == 2 {
+			token := MatchingIndexToken{
+				Key:      kv[0],
+				Value:    strings.TrimSuffix(kv[1], "?"),
+				Optional: optional,
+			}
+
+			tokens = append(tokens, token)
+			continue
+		}
+
+		// it's a map key
 		token := KeyToken{
 			Key:      strings.TrimSuffix(tok, "?"),
 			Optional: optional,
@@ -110,16 +120,28 @@ func (p Pointer) String() string {
 			strs = append(strs, "-")
 
 		case MatchingIndexToken:
-			strs = append(strs, fmt.Sprintf("%s=%s", typedToken.Key, typedToken.Value))
+			key := rfc6901Encoder.Replace(typedToken.Key)
+			val := rfc6901Encoder.Replace(typedToken.Value)
+
+			if typedToken.Optional {
+				if !optional {
+					val += "?"
+					optional = true
+				}
+			}
+
+			strs = append(strs, fmt.Sprintf("%s=%s", key, val))
 
 		case KeyToken:
 			str := rfc6901Encoder.Replace(typedToken.Key)
+
 			if typedToken.Optional { // /key?/key2/key3
 				if !optional {
 					str += "?"
 					optional = true
 				}
 			}
+
 			strs = append(strs, str)
 
 		default:

patch/pointer_test.go

@@ -21,18 +21,6 @@ var testCases = []PointerTestCase{
 	{"/", []Token{RootToken{}, KeyToken{Key: ""}}},
 	{"/ ", []Token{RootToken{}, KeyToken{Key: " "}}},
 
-	// Escaping (todo support ~2 for '?'; ~3 for '=')
-	{"/m~0n", []Token{RootToken{}, KeyToken{Key: "m~n"}}},
-	{"/a~01b", []Token{RootToken{}, KeyToken{Key: "a~1b"}}},
-	{"/a~1b", []Token{RootToken{}, KeyToken{Key: "a/b"}}},
-
-	// Special chars
-	{"/c%d", []Token{RootToken{}, KeyToken{Key: "c%d"}}},
-	{"/e^f", []Token{RootToken{}, KeyToken{Key: "e^f"}}},
-	{"/g|h", []Token{RootToken{}, KeyToken{Key: "g|h"}}},
-	{"/i\\j", []Token{RootToken{}, KeyToken{Key: "i\\j"}}},
-	{"/k\"l", []Token{RootToken{}, KeyToken{Key: "k\"l"}}},
-
 	// Maps
 	{"/key", []Token{RootToken{}, KeyToken{Key: "key"}}},
 	{"/key/", []Token{RootToken{}, KeyToken{Key: "key"}, KeyToken{Key: ""}}},
@@ -55,10 +43,42 @@ var testCases = []PointerTestCase{
 
 	// Matching index token
 	{"/name=val", []Token{RootToken{}, MatchingIndexToken{Key: "name", Value: "val"}}},
+	{"/name=val?", []Token{RootToken{}, MatchingIndexToken{Key: "name", Value: "val", Optional: true}}},
+	{"/name=val?/name2=val", []Token{
+		RootToken{},
+		MatchingIndexToken{Key: "name", Value: "val", Optional: true},
+		MatchingIndexToken{Key: "name2", Value: "val", Optional: true},
+	}},
 	{"/=", []Token{RootToken{}, MatchingIndexToken{Key: "", Value: ""}}},
+	{"/=?", []Token{RootToken{}, MatchingIndexToken{Key: "", Value: "", Optional: true}}},
 	{"/name=", []Token{RootToken{}, MatchingIndexToken{Key: "name", Value: ""}}},
 	{"/=val", []Token{RootToken{}, MatchingIndexToken{Key: "", Value: "val"}}},
 	{"/==", []Token{RootToken{}, MatchingIndexToken{Key: "", Value: "="}}},
+
+	// Optionality
+	{"/key?/name=val", []Token{
+		RootToken{},
+		KeyToken{Key: "key", Optional: true},
+		MatchingIndexToken{Key: "name", Value: "val", Optional: true},
+	}},
+	{"/name=val?/key", []Token{
+		RootToken{},
+		MatchingIndexToken{Key: "name", Value: "val", Optional: true},
+		KeyToken{Key: "key", Optional: true},
+	}},
+
+	// Escaping (todo support ~2 for '?'; ~3 for '=')
+	{"/m~0n", []Token{RootToken{}, KeyToken{Key: "m~n"}}},
+	{"/a~01b", []Token{RootToken{}, KeyToken{Key: "a~1b"}}},
+	{"/a~1b", []Token{RootToken{}, KeyToken{Key: "a/b"}}},
+	{"/name~0n=val~0n", []Token{RootToken{}, MatchingIndexToken{Key: "name~n", Value: "val~n"}}},
+
+	// Special chars
+	{"/c%d", []Token{RootToken{}, KeyToken{Key: "c%d"}}},
+	{"/e^f", []Token{RootToken{}, KeyToken{Key: "e^f"}}},
+	{"/g|h", []Token{RootToken{}, KeyToken{Key: "g|h"}}},
+	{"/i\\j", []Token{RootToken{}, KeyToken{Key: "i\\j"}}},
+	{"/k\"l", []Token{RootToken{}, KeyToken{Key: "k\"l"}}},
 }
 
 var _ = Describe("NewPointer", func() {

patch/remove_op.go

@@ -62,6 +62,10 @@ func (op RemoveOp) Apply(doc interface{}) (interface{}, error) {
 				}
 			}
 
+			if typedToken.Optional && len(idxs) == 0 {
+				return doc, nil
+			}
+
 			if len(idxs) != 1 {
 				errMsg := "Expected to find exactly one matching array item for path '%s' but found %d"
 				return nil, fmt.Errorf(errMsg, NewPointer(tokens[:i+2]), len(idxs))

patch/remove_op_test.go

@@ -155,6 +155,25 @@ var _ = Describe("RemoveOp.Apply", func() {
 			}))
 		})
 
+		It("removes nested matching item that does not exist", func() {
+			doc := map[interface{}]interface{}{
+				"abc": []interface{}{
+					map[interface{}]interface{}{"opr": "opr"},
+				},
+				"xyz": "xyz",
+			}
+
+			res, err := RemoveOp{Path: MustNewPointerFromString("/abc/opr=not-opr?")}.Apply(doc)
+			Expect(err).ToNot(HaveOccurred())
+
+			Expect(res).To(Equal(map[interface{}]interface{}{
+				"abc": []interface{}{
+					map[interface{}]interface{}{"opr": "opr"},
+				},
+				"xyz": "xyz",
+			}))
+		})
+
 		It("returns an error if it's not an array is being accessed", func() {
 			_, err := RemoveOp{Path: MustNewPointerFromString("/key=val")}.Apply(map[interface{}]interface{}{})
 			Expect(err).To(HaveOccurred())

patch/replace_op.go

@@ -72,18 +72,24 @@ func (op ReplaceOp) Apply(doc interface{}) (interface{}, error) {
 				}
 			}
 
-			if len(idxs) != 1 {
-				errMsg := "Expected to find exactly one matching array item for path '%s' but found %d"
-				return nil, fmt.Errorf(errMsg, NewPointer(tokens[:i+2]), len(idxs))
-			}
+			if typedToken.Optional && len(idxs) == 0 {
+				obj = map[interface{}]interface{}{typedToken.Key: typedToken.Value}
+				prevUpdate(append(typedObj, obj))
+				// no need to change prevUpdate since matching item can only be a map
+			} else {
+				if len(idxs) != 1 {
+					errMsg := "Expected to find exactly one matching array item for path '%s' but found %d"
+					return nil, fmt.Errorf(errMsg, NewPointer(tokens[:i+2]), len(idxs))
+				}
 
-			idx := idxs[0]
+				idx := idxs[0]
 
-			if isLast {
-				typedObj[idx] = op.Value
-			} else {
-				obj = typedObj[idx]
-				// no need to change prevUpdate since matching item can only be a map
+				if isLast {
+					typedObj[idx] = op.Value
+				} else {
+					obj = typedObj[idx]
+					// no need to change prevUpdate since matching item can only be a map
+				}
 			}
 
 		case KeyToken:
@@ -110,10 +116,12 @@ func (op ReplaceOp) Apply(doc interface{}) (interface{}, error) {
 					switch tokens[i+2].(type) {
 					case AfterLastIndexToken:
 						obj = []interface{}{}
+					case MatchingIndexToken:
+						obj = []interface{}{}
 					case KeyToken:
 						obj = map[interface{}]interface{}{}
 					default:
-						errMsg := "Expected to find key or after last index token at path '%s'"
+						errMsg := "Expected to find key, matching index or after last index token at path '%s'"
 						return nil, fmt.Errorf(errMsg, NewPointer(tokens[:i+3]))
 					}
 

patch/replace_op_test.go

@@ -75,7 +75,7 @@ var _ = Describe("ReplaceOp.Apply", func() {
 		})
 	})
 
-	Describe("array wtih after last item", func() {
+	Describe("array with after last item", func() {
 		It("appends new item", func() {
 			res, err := ReplaceOp{Path: MustNewPointerFromString("/-"), Value: 10}.Apply([]interface{}{})
 			Expect(err).ToNot(HaveOccurred())
@@ -146,7 +146,7 @@ var _ = Describe("ReplaceOp.Apply", func() {
 			}))
 		})
 
-		It("returns an error if no items found", func() {
+		It("returns an error if no items found and matching is not optional", func() {
 			doc := []interface{}{
 				map[interface{}]interface{}{"key": "val2"},
 				map[interface{}]interface{}{"key2": "val"},
@@ -208,6 +208,38 @@ var _ = Describe("ReplaceOp.Apply", func() {
 			}))
 		})
 
+		It("appends missing matching item if it does not exist", func() {
+			doc := []interface{}{map[interface{}]interface{}{"xyz": "xyz"}}
+
+			res, err := ReplaceOp{Path: MustNewPointerFromString("/name=val?/efg"), Value: 1}.Apply(doc)
+			Expect(err).ToNot(HaveOccurred())
+
+			Expect(res).To(Equal([]interface{}{
+				map[interface{}]interface{}{"xyz": "xyz"},
+				map[interface{}]interface{}{
+					"name": "val",
+					"efg":  1,
+				},
+			}))
+		})
+
+		It("appends nested missing matching item if it does not exist", func() {
+			doc := []interface{}{map[interface{}]interface{}{"xyz": "xyz"}}
+
+			res, err := ReplaceOp{Path: MustNewPointerFromString("/name=val?/efg/name=val"), Value: 1}.Apply(doc)
+			Expect(err).ToNot(HaveOccurred())
+
+			Expect(res).To(Equal([]interface{}{
+				map[interface{}]interface{}{"xyz": "xyz"},
+				map[interface{}]interface{}{
+					"name": "val",
+					"efg": []interface{}{
+						map[interface{}]interface{}{"name": "val"},
+					},
+				},
+			}))
+		})
+
 		It("returns an error if it's not an array is being accessed", func() {
 			_, err := ReplaceOp{Path: MustNewPointerFromString("/key=val")}.Apply(map[interface{}]interface{}{})
 			Expect(err).To(HaveOccurred())
@@ -347,10 +379,10 @@ var _ = Describe("ReplaceOp.Apply", func() {
 		It("returns an error if missing key needs to be created but next access does not make sense", func() {
 			doc := map[interface{}]interface{}{"xyz": "xyz"}
 
-			_, err := ReplaceOp{Path: MustNewPointerFromString("/abc?/name=val"), Value: 1}.Apply(doc)
+			_, err := ReplaceOp{Path: MustNewPointerFromString("/abc?/0"), Value: 1}.Apply(doc)
 			Expect(err).To(HaveOccurred())
 			Expect(err.Error()).To(Equal(
-				"Expected to find key or after last index token at path '/abc?/name=val'"))
+				"Expected to find key, matching index or after last index token at path '/abc?/0'"))
 		})
 
 		It("returns an error if it's not a map when key is being accessed", func() {

patch/tokens.go

@@ -13,9 +13,12 @@ type AfterLastIndexToken struct{}
 type MatchingIndexToken struct {
 	Key   string
 	Value string
+
+	Optional bool
 }
 
 type KeyToken struct {
-	Key      string
+	Key string
+
 	Optional bool
 }