Documentation
¶
Overview ¶
Package yptr is a JSONPointer implementation that can walk though a yaml.Node tree.
yaml.Nodes preserve comments and locations in the source and can be useful to implement editing in-place functionality that uses JSONPointer to locate the fields to be edited.
It also implements a simple extension to the JSONPointers standard that handles pointers into k8s manifests which usually contain arrays whose elements are objects with a field that uniquely specifies the array entry (e.g. "name").
For example, given a JSON/YAML input document:
{"a": [{"k":"x", "v": 42}, {"k":"y", "v": 77}]}
If "k" is a field that contains a key that uniquiely identifies an element in a given array, we can select the node with the scalar 42 by first selecting the array element for which "k" has the value of "x", and then by walking to the field "v":
/a/~{"k":"x"}/v
The "~" token accepts an argument which is interpreted as JSON value to be used as "query-by-example" filter against elements of an array. The array element is selected if the query-by-example object is a (recursive) subset of the element.
The ~{...} extension can potentially locate multiple matches. For example, "~{}" effectively acts as a wildcard. This library offers an API to retrieve multiple matches ("FindAll") or to fetch only one match and error if multiple matches are found ("Find").
JSONPointer is designed to locate exactly one node in the tree. This can be achieved only if the effective schema of the JSON/YAML document mandates that there is an identifying key in each array element you want to point to. Using the "Find" function effectively performs a dynamic check of that invariant.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrTooManyResults means a pointer matches too many results (usually more than one expected result). ErrTooManyResults = fmt.Errorf("too many results") // ErrNotFound a pointer failed to find a match. ErrNotFound = fmt.Errorf("not found") )
Functions ¶
func Find ¶
Find is like FindAll but returns ErrTooManyResults if multiple matches are located.
Example ¶
package main import ( "fmt" yptr "github.com/vmware-labs/yaml-jsonpointer" yaml "gopkg.in/yaml.v3" ) func main() { src := ` a: b: c: 42 d: - e - f ` var n yaml.Node yaml.Unmarshal([]byte(src), &n) r, _ := yptr.Find(&n, `/a/b/c`) fmt.Printf("Scalar %q at %d:%d\n", r.Value, r.Line, r.Column) r, _ = yptr.Find(&n, `/d/0`) fmt.Printf("Scalar %q at %d:%d\n", r.Value, r.Line, r.Column) }
Output: Scalar "42" at 4:8 Scalar "e" at 6:3
Example (Extension) ¶
package main import ( "fmt" yptr "github.com/vmware-labs/yaml-jsonpointer" yaml "gopkg.in/yaml.v3" ) func main() { src := `kind: Deployment apiVersion: apps/v1 metadata: name: foo spec: template: spec: replicas: 1 containers: - name: app image: nginx - name: sidecar image: mysidecar ` var n yaml.Node yaml.Unmarshal([]byte(src), &n) r, _ := yptr.Find(&n, `/spec/template/spec/containers/1/image`) fmt.Printf("Scalar %q at %d:%d\n", r.Value, r.Line, r.Column) r, _ = yptr.Find(&n, `/spec/template/spec/containers/~{"name":"app"}/image`) fmt.Printf("Scalar %q at %d:%d\n", r.Value, r.Line, r.Column) }
Output: Scalar "mysidecar" at 13:16 Scalar "nginx" at 11:16
Example (JsonPointerCompat) ¶
package main import ( "fmt" yptr "github.com/vmware-labs/yaml-jsonpointer" yaml "gopkg.in/yaml.v3" ) func main() { // the array item match syntax doesn't accidentally match a field that just happens // to contain the same characters. src := `a: "{\"b\":\"c\"}": d ` var n yaml.Node yaml.Unmarshal([]byte(src), &n) r, _ := yptr.Find(&n, `/a/{"b":"c"}`) fmt.Printf("Scalar %q at %d:%d\n", r.Value, r.Line, r.Column) }
Output: Scalar "d" at 2:20
Types ¶
This section is empty.