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

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.