json_dotpath/README.md

json_dotpath

Access members of nested JSON arrays and objects using "dotted paths".

Consider this example JSON:

{
  "fruit": [
    {"name": "lemon", "color":  "yellow"},
    {"name": "apple", "color":  "green"},
    {"name": "cherry", "color":  "red"}
  ]
}

The following can be used to access its parts:

• obj.dot_get("fruit") ... get the fruits array
• obj.dot_get("fruit.0.name") ... 0th fruit name, "lemon"
• obj.dot_get("fruit.>.color") ... last fruit's color, "red"

The JSON can also be manipulated:

• obj.dot_take("fruit.1") ... extract the "apple" object, removing it from the JSON
• obj.dot_set("fruit.<1", json!({"name":"plum","color":"blue"}) ... insert before the 1st element, shifting the rest
• obj.dot_set("fruit.>1", json!({"name":"plum","color":"blue"}) ... insert after the 1st element, shifting the rest
• obj.dot_set("fruit.>.name", "tangerine") ... set the last fruit's name
• obj.dot_set("fruit.>", Value::Null) ... append a JSON null
• obj.dot_set("fruit.<", true) ... prepend a JSON true
• obj.dot_set("vegetables.onion.>", "aaa") ... add {"vegetables":{"onion":["aaa"]}} to the object

Any serializable type or serde_json::Value can be stored to or retrieved from the nested object (Value::Object, Value::Array, Value::Null).

Any value stored in the object can also be modified in place, without deserialization, by getting a mutable reference (dot_get_mut(path)).

This crate is useful for tasks such as working with dynamic JSON API payloads, parsing config files, or building a polymorphic data store.

Supported Operations

Object and Array

• Set (dropping the original value, if any)
• Remove (remove and drop a value)
• Take (remove a value and deserialize it)
• Replace (take and set)
• Get (find & deserialize)
• Get a mutable reference to a Value

Array

Array is an ordered sequence backed by a Vec. It has these additional operations:

• Prepend
• Append
• Insert, shifting the following elements
• Get the last element

Null

JSON null can become an array or object by setting it's members (even nested), as if it was an array or object. It becomes an array or object of the appropriate type based on the root key.

Dotted Path Syntax

Map Patterns

To avoid ambiguity, it's not allowed to use numeric keys (or keys starting with a number) as map keys. Map keys must start with an ASCII letter or underscore and must not contain a dot (.).

Examples:

• abc
• _123
• key with spaces

If a numeric key or a key nonconforming in other way must be used, prefix it with #. It will be taken literally as a string, excluding the prefix.

e.g. to get 456 from {"foo":{"123":456}}, use foo.#123 instead of foo.123

Array Patterns

Array keys must be numeric (integer), or one of the special patterns listed below.

• - ... prepend
• < ... prepend (or get first)
• + ... append
• > ... append (or get last)
• <n, e.g. <5 ... insert before the n-th element
• >n, e.g. >5 ... insert after the n-th element

Path Examples

• Empty path ... access the root element
• 5 ... get the element "five" from [0,1,2,3,4,"five"]
• a.b.c ... get 1 from { "a": { "b": { "c": 1 } } }
• a.0.x ... get 1 from { "a": [ { "x": 1 } ] }

It's possible to create nested arrays or objects by setting a non-existent path, provided the key syntax rules are maintained.

See unit tests for more examples.