Readme

JSON Pointer

A simple library for creating and using json-pointer (See [rfc6901:https://tools.ietf.org/html/rfc6901]).

Examples

compose(['one', 'two']) // '/one/two'
compose(['one/two']) // '/one~1two'
compose([]) // ''
compose(['', '', '']) // '///'

// Split is the opposite of compose
split('/one/two') // ['one', 'two']
split('/one~1two') // ['one/two'] 
split('') // []
split('///') // ['', '', '']

// Other helpers
parent('/one/two') // '/one'
parent('/one') // ''
parent('') // null

append('/one', 'two') // '/one/two'
append('/one', '~')   // '/one/~0'  append escapes the appended item 


// Get and Set values
get$('', [{'foo': 'bar'}]) // [{'foo': 'bar'}]
get$('/0', [{'foo': 'bar'}] // {'foo': 'bar'}
get$('/0/foo', [{'foo': 'bar'}] // 'bar'

set$('', [{'foo': 'bar'}], 'baz') // 'baz'
set$('/0', [{'foo': 'bar'}], 'baz') // ['baz']
set$('/0/foo', [{'foo': 'bar'}], 'baz') // [{'foo': 'baz'}]

// Contains
contains('', [{'foo': 'bar'}]) // true
contains('/0', [{'foo': 'bar'}] // true
contains('/0/foo', [{'foo': 'bar'}] // true

contains('/a/5', [{'foo': 'bar'}]) // false
contains('/1', [{'foo': 'bar'}] // false
contains('/0/foo/baz', [{'foo': 'bar'}] // false

// Escape part of a path
escape('one/two') // 'one~1two'
escape('name') // 'name'

unescape('name') // 'name'
unescape('one~1two') // 'one/two'

// Validation
isValid('one/two') // true
isValid('') // true
isValid('one~1two') // true

isValid(null) // false: null pointer
isValid('~2') // false: '~' must be followed by either '0' or '1'
isValid('0/foo') // false: should start with '/'

Valid 'json' parameter for Get, Set, and Contains

The 'root' parameter passed to 'get', 'set', and 'contains' should generally be a json-like object (e.g. composed of list, map, int, double, String, bool, and null). However the library doesn't check the whole object tree and it may contain objects of other types. However, the library is only able to index into Maps and Lists. Get and Set will throw BadRouteError when attempting to index into other types. Contains will return false.

contains('/x', Point(0, 0)) // false
contains('/2/0', [WierdType0, WierdType1, [WierdType2]] // true

BadRouteError

Get and Set throw BadRouteError if the given pointer doesn't refer to an object in the 'root' parameter (e.g. contains(path, root) == false). Set can only be used to change an existing value. It will not attempt to insert into a list or dictionary if a value doesn't exist.

get('/3', [0, 1, 2]) // BadRouteError
set('/3', [0, 1, 2], 'three') // BadRouteError
set('/foo', {}, 'bar') // BadRouteError

PointerFormatError

All functions that accept a pointer argument will throw PointerFormatError if isValid(pointer) is false. Similarly, unescape checks for a valid reference-token, (see standard for details).

split('0/foo') // PointerFormatError
split('~2/foo') // PointerFormatError: 
split(null) // PointerFormatError: null pointer
unescape('/') // PointerFormatError: part cannot contain the '/' character