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.
64 lines
2.1 KiB
64 lines
2.1 KiB
5 years ago
|
# json_dotpath
|
||
|
|
|
||
|
|
Access members of nested JSON arrays and objects using "dotted paths".
|
||
|
|
|
||
|
|
The `DotPaths` trait is implemented for `serde_json::Value`,
|
||
|
|
`serde_json::Map<String, serde_json::Value>`, and `Vec<serde_json::Value>`.
|
||
|
|
|
||
|
|
Any serializable type or `serde_json::Value` can be stored to or retrieved from
|
||
|
|
the nested object. Any value stored in the object can also be modified in place
|
||
|
|
by getting a mutable reference.
|
||
|
|
|
||
|
|
This crate is useful for tasks such as working with dynamic JSON API payloads,
|
||
|
|
parsing config files, or 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
|
||
|
|
|
||
|
|
Array keys must be numeric (integer), or one of the special patterns listed below.
|
||
|
|
|
||
|
|
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 (`.`).
|
||
|
|
|
||
|
|
### Array Index Patterns
|
||
|
|
|
||
|
|
- `-` ... 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.
|