jsonpointer

README

jsonpointer

golang implementation of IETF RFC6901: JSON Pointer defines a string syntax for identifying a specific value within a JavaScript Object Notation (JSON) document.

Installation

install with: go get -u github.com/qri-io/jsonpointer

Usage

Here's a quick example pulled from the godoc:

import (
  "encoding/json"
  "fmt"
  "github.com/qri-io/jsonpointer"
)

var document = []byte(`{ 
  "foo": {
    "bar": {
      "baz": [0,"hello!"]
    }
  }
}`)

func main() {
  parsed := map[string]interface{}{}
  // be sure to handle errors in real-world code!
  json.Unmarshal(document, &parsed)

  // parse a json pointer. Pointers can also be url fragments
  // the following are equivelent pointers:
  // "/foo/bar/baz/1"
  // "#/foo/bar/baz/1"
  // "http://example.com/document.json#/foo/bar/baz/1"
  ptr, _ := jsonpointer.Parse("/foo/bar/baz/1")

  // evaluate the pointer against the document
  // evaluation always starts at the root of the document
  got, _ := ptr.Eval(parsed)

  fmt.Println(got)
  // Output: hello!
}

License

MIT

Issues & Contributions

Contributions & Issues are more than welcome! Everything happens over on this repo's github page

Documentation

Overview

Package jsonpointer implements IETF rfc6901 JSON Pointers are a string syntax for identifying a specific value within a JavaScript Object Notation (JSON) document [RFC4627]. JSON Pointer is intended to be easily expressed in JSON string values as well as Uniform Resource Identifier (URI) [RFC3986] fragment identifiers.

this package is intended to work like net/url from the go standard library

Example

var document = []byte(`{ 
    "foo": {
      "bar": {
        "baz": [0,"hello!"]
      }
    }
  }`)

// unmarshal our document into generic go structs
parsed := map[string]interface{}{}
// be sure to handle errors in real-world code!
json.Unmarshal(document, &parsed)

// parse a json pointer. Pointers can also be url fragments
// the following are equivelent pointers:
// "/foo/bar/baz/1"
// "#/foo/bar/baz/1"
// "http://example.com/document.json#/foo/bar/baz/1"
ptr, _ := Parse("/foo/bar/baz/1")

// evaluate the pointer against the document
// evaluation always starts at the root of the document
got, _ := ptr.Eval(parsed)

fmt.Println(got)

Output:

hello!

Index

• func WalkJSON(tree interface{}, visit func(elem interface{}) error) error
• type JSONContainer
• type JSONParent
• type Pointer
  • func NewPointer() Pointer
  • func Parse(str string) (Pointer, error)
  • func (p Pointer) Descendant(path string) (Pointer, error)
  • func (p Pointer) Eval(data interface{}) (result interface{}, err error)
  • func (p Pointer) Head() *string
  • func (p Pointer) IsEmpty() bool
  • func (p Pointer) RawDescendant(path ...string) Pointer
  • func (p Pointer) String() (str string)
  • func (p Pointer) Tail() Pointer

Examples

• Package

Functions

func WalkJSON

func WalkJSON(tree interface{}, visit func(elem interface{}) error) error

WalkJSON calls visit on all elements in a tree of decoded json

Types

type JSONContainer

type JSONContainer interface {
	// JSONProp takes a string reference for a given JSON property.
	// implementations must return any matching property of that name,
	// nil if no such subproperty exists.
	// Note that implementations on slice-types are expected to convert
	// prop to an integer value
	JSONProp(prop string) interface{}
}

JSONContainer returns any existing child value for a given JSON property string

type JSONParent

type JSONParent interface {
	// JSONChildren should return all immidiate children of this element
	// with json property names as keys, go types as values
	// Note that implementations on slice-types are expected to convert
	// integers to string keys
	JSONProps() map[string]interface{}
}

JSONParent is an interface that enables tree traversal by listing all immediate children of an object

type Pointer

type Pointer []string

Pointer represents a parsed JSON pointer

func NewPointer

func NewPointer() Pointer

NewPointer creates a Pointer with a pre-allocated block of memory to avoid repeated slice expansions

func Parse

func Parse(str string) (Pointer, error)

Parse parses str into a Pointer structure. str may be a pointer or a url string. If a url string, Parse will use the URL's fragment component (the bit after the '#' symbol)

func (Pointer) Descendant

func (p Pointer) Descendant(path string) (Pointer, error)

Descendant returns a new pointer to a descendant of the current pointer parsing the input path into components

func (Pointer) Eval

func (p Pointer) Eval(data interface{}) (result interface{}, err error)

Eval evaluates a json pointer against a given root JSON document Evaluation of a JSON Pointer begins with a reference to the root value of a JSON document and completes with a reference to some value within the document. Each reference token in the JSON Pointer is evaluated sequentially.

func (Pointer) Head

func (p Pointer) Head() *string

Head returns the root of the Pointer

func (Pointer) IsEmpty

func (p Pointer) IsEmpty() bool

IsEmpty is a utility function to check if the Pointer is empty / nil equivalent

func (Pointer) RawDescendant

func (p Pointer) RawDescendant(path ...string) Pointer

RawDescendant extends the pointer with 1 or more path tokens The function itself is unsafe as it doesnt fully parse the input and assumes the user is directly managing the pointer This allows for much faster pointer management

func (Pointer) String

func (p Pointer) String() (str string)

String implements the stringer interface for Pointer, giving the escaped string

func (Pointer) Tail

func (p Pointer) Tail() Pointer

Tail returns everything after the Pointer head