You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
json_dotpath/README.md

104 lines
3.4 KiB

5 years ago
# json_dotpath
Access members of nested JSON arrays and objects using "dotted paths".
Consider this example JSON:
```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
5 years ago
- `obj.dot_set("vegetables.onion.>", "aaa")` ... add `"vegetables": {"onion":["aaa"]}` to the outer object
(the parent map and array are created automatically)
5 years ago
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)`).
5 years ago
This crate is useful for tasks such as working with dynamic JSON API payloads,
parsing config files, or building a polymorphic data store.
5 years ago
## 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
5 years ago
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.
5 years ago
- `-` ... 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.