jsonpak

Packed ASTs for compact and efficient JSON representation, with JSON Pointer, JSON Patch support.


Keywords
json, json-patch, json-pointer, data-structure, nim, nim-lang
License
MIT
Install
nimble install jsonpak

Documentation

jsonpak - Yet another JSON library

jsonpak is JSON library that implements the JSON Patch RFC which is specified in RFC 6902 from the IETF.

It uses Packed ASTs for compact and efficient JSON representation. Based on Araq's idea.

Documentation

For more information visit: https://jsonpatch.com/ or the linked RFC documents.

JSON Pointer

type
  JsonPtr* = distinct string

JSON Pointer (IETF RFC 6901) defines a string format for identifying a specific value within a JSON document. It is used by all operations in JSON Patch to specify the part of the document to operate on.

A JSON Pointer is a string of tokens separated by / characters, these tokens either specify keys in objects or indexes into arrays. For example, given the JSON

{
  "a": [1, 2, 3],
  "b": 4,
  "c": [5, 6],
  "d": {"e": [7, 8], "f": 9}
}

/d/e would point to the array of ints [7, 8] and /d/e/0 would point to 7.

To point to the root of the document use an empty string for the pointer. The pointer / doesn’t point to the root, it points to a key of "" on the root (which is totally valid in JSON).

If you need to refer to a key with ~ or / in its name, you must escape the characters with ~0 and ~1 respectively. For example, to get "baz" from {"foo/bar~": "baz" } you’d use the pointer /foo~1bar~0.

Finally, if you need to refer to the end of an array you can use - instead of an index. For example, to refer to the end of the array above you would use /a/-. This is useful when you need to insert a value at the end of an array.

Operations

Add
proc add(x: var JsonTree; path: JsonPtr; value: JsonTree)

Adds a value to an object or inserts it into an array. In the case of an array, the value is inserted before the given index. The - character can be used instead of an index to insert at the end of an array.

Remove
proc remove(x: var JsonTree; path: JsonPtr)

Removes a value from an object or array.

Replace
proc replace(x: var JsonTree; path: JsonPtr, value: JsonTree)

Replaces a value. Equivalent to a remove followed by an add.

Copy
proc copy(x: var JsonTree; `from`, path: JsonPtr)

Copies a value from one location to another within the JSON document. Both from and path are JSON Pointers.

Move
proc move(x: var JsonTree; `from`, path: JsonPtr)

Moves a value from one location to the other. Both from and path are JSON Pointers.

Test
proc test(x: JsonTree; path: JsonPtr, value: JsonTree): bool

Tests that the specified value is set in the document. If the test fails, then the patch as a whole should not apply.

Misc

# basic usage
proc len(x: JsonTree; path: JsonPtr): int
proc kind(x: JsonTree; path: JsonPtr): JsonNodeKind
proc contains(x: JsonTree; path: JsonPtr): bool
proc extract(x: JsonTree; path: JsonPtr): JsonTree
# (de)serialize
proc fromJson[T](x: JsonTree; path: JsonPtr; t: typedesc[T]): T
proc toJson[T](x: T): JsonTree
macro %*(x: untyped): JsonTree
# iterators
iterator items(x: JsonTree; path: JsonPtr; t: typedesc[T]): T
iterator pairs(x: JsonTree; path: JsonPtr; t: typedesc[T]): (lent string, T)

Examples

import jsonpak, jsonpak/[patch, jsonptr, extra, builder, mapper, dollar]

var x = %*{
  "a": [1, 2, 3],
  "b": 4,
  "c": [5, 6],
  "d": {"e": [7, 8], "f": 9}
}

# Basic usage
assert len(x, JsonPtr"") == 4
assert contains(x, JsonPtr"/a")
assert kind(x, JsonPtr"/a") == JArray

add x, JsonPtr"/a/-", %*[5, 6]
# """{"a":[1,2,3,[5,6]],"b":4,"c":[5,6],"d":{"e":[7,8],"f":9}}"""

remove x, JsonPtr"/d/e/1"
# """{"a":[1,2,3,[5,6]],"b":4,"c":[5,6],"d":{"e":[7],"f":9}}"""

replace x, JsonPtr"/b", %*"foo"
# """{"a":[1,2,3,[5,6]],"b":"foo","c":[5,6],"d":{"e":[7],"f":9}}"""

copy x, JsonPtr"/b", JsonPtr"/d/f"
# """{"a":[1,2,3,[5,6]],"b":"foo","c":[5,6],"d":{"e":[7],"f":"foo"}}"""

move x, JsonPtr"/c", JsonPtr"/b"
# """{"a":[1,2,3,[5,6]],"b":[5,6],"d":{"e":[7],"f":"foo"}}"""

# Comparing, copying, deserializing
assert test(x, JsonPtr"/d", %*{"e": [7], "f": "foo"})
assert $extract(x, JsonPtr"/d") == """{"e":[7,8],"f":9}"""
assert fromJson(x, JsonPtr"/d/e", seq[int]) == @[7, 8]
assert toJson(@[1, 2, 3]) == extract(x, JsonPtr"/a")
# Iterating
for x in items(x, JsonPtr"/a", int): echo x, " "
# 1 2 3
for k, v in pairs(x, JsonPtr"/d", JsonTree): echo (k, v), " "
# ("e", [7, 8]) ("f", 9)