add usage examples

Author: dpb587-pivotal

LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2016 Dmitriy Kalinin
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -1,93 +1,5 @@
 ## go-patch
 
-More or less based on https://tools.ietf.org/html/rfc6902.
+Roughly based on JSON patch: https://tools.ietf.org/html/rfc6902.
 
-## Pointer (aka path)
-
-More or less based on https://tools.ietf.org/html/rfc6901.
-
-- Root
-- Index (ex: `/0`, `/-1`)
-- AfterLastIndex (ex: `/-`)
-- MatchingIndex (ex: `/key=val`)
-- Key: `/key`
-
-## Operations
-
-- Remove
-- Replace
-
-## Example
-
-### Input
-
-```yaml
-releases:
-- name: capi
-  version: 0.1
-
-instance_groups:
-- name: cloud_controller
-  instances: 0
-  jobs:
-  - name: cloud_controller
-    release: capi
-
-- name: uaa
-  instances: 0
-```
-
-### Operations
-
-```yaml
-- type: replace
-  path: /instance_groups/name=cloud_controller/instances
-  value: 1
-
-- type: replace
-  path: /instance_groups/name=cloud_controller/jobs/name=cloud_controller/consumes?/db
-  value:
-    instances:
-    - address: some-db.local
-    properties:
-      username: user
-      password: pass
-
-- type: replace
-  path: /instance_groups/name=uaa/instances
-  value: 1
-
-- type: replace
-  path: /instance_groups/-
-  value:
-    name: uaadb
-    instances: 2
-```
-
-### Output
-
-```yaml
-releases:
-- name: capi
-  version: latest
-
-instance_groups:
-- name: cloud_controller
-  instances: 1
-  jobs:
-  - name: cloud_controller
-    release: capi
-    consumes:
-      db:
-        instances:
-        - address: some-db.local
-        properties:
-          username: user
-          password: pass
-
-- name: uaa
-  instances: 1
-
-- name: uaadb
-  instances: 2
-```
+[Usage examples](docs/examples.md)

docs/examples.md

@@ -0,0 +1,135 @@
+## 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
+- 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`)
+
+See pointer test examples in [patch/pointer_test.go](../patch/pointer_test.go).
+
+## Operations
+
+Following example is used to demonstrate operations below:
+
+```
+key: 1
+
+key2:
+  nested:
+  	super_nested: 2
+  other: 3
+
+array: [4,5,6]
+
+items:
+- name: item7
+- name: item8
+- name: item8
+```
+
+There are two available operations: `replace` and `remove`.
+
+### Hash
+
+```yaml
+- type: replace
+  path: /key
+  value: 10
+```
+
+- sets `key` to `10`
+
+```yaml
+- type: replace
+  path: /key_not_there
+  value: 10
+```
+
+- errors because `key_not_there` is expected (does not have `?`)
+
+```yaml
+- type: replace
+  path: /new_key?
+  value: 10
+```
+
+- creates `new_key` because it ends with `?` and sets it to `10`
+
+```yaml
+- type: replace
+  path: /key2/nested/super_nested
+  value: 10
+```
+
+- requires that `key2` and `nested` hashes exist
+- sets `super_nested` to `10`
+
+```yaml
+- type: replace
+  path: /key2/nested?/another_nested/super_nested
+  value: 10
+```
+
+- 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`
+
+### Array
+
+```yaml
+- type: replace
+  path: /array/0
+  value: 10
+```
+
+- requires `array` to exist and be an array
+- replaces 0th item in `array` array with `10`
+
+```yaml
+- type: replace
+  path: /array/-
+  value: 10
+```
+
+- requires `array` to exist and be an array
+- appends `10` to the end of `array`
+
+```yaml
+- type: replace
+  path: /array2?/-
+  value: 10
+```
+
+- creates `array2` array since it does not exist
+- appends `10` to the end of `array2`
+
+### Arrays of hashes
+
+```yaml
+- type: replace
+  path: /items/name=item7/count
+  value: 10
+```
+
+- finds array item with matching key `name` with value `item7`
+- adds `count` key as a sibling of name, resulting in:
+
+	```
+	...
+	items:
+	- name: item7
+	  count: 10
+	- name: item8
+	```
+
+```yaml
+- type: replace
+  path: /items/name=item8/count
+  value: 10
+```
+
+- errors because there are two values that have `item8` as their `name`
+
+See full example in [patch/integration_test.go](../patch/integration_test.go).