# jqesque
A Rust library to parse simplified JSON assignments in a jq-like syntax and convert them into JSON structures.
Sometimes you want to express simplified JSON assignments as strings without writing the full JSON syntax. This library borrows syntax from [jq](https://jqlang.github.io/jq/) and JSONPath to create a simplified way to represent JSON assignments.
## Features
- **Nested Objects:** Supports nested objects (e.g., `foo.bar.baz=true`).
- **Arrays with Indices:** Supports arrays with indices (e.g., `foo[0].bar=zoot`, where the index must be a positive number).
- **Boolean, Number, and Null Values:** Automatically parses values as booleans, numbers, or null if possible. By default, the value is a string unless serde can parse it as a boolean, number, or null.
- **Custom Separators:** Scopes can be separated by `Separator::Dot` (`.`), `Separator::Slash` (`/`), or `Separator::Custom(char)` (custom character).
Values can be anything that serde_json can parse, including strings, numbers, booleans, null, objects, and arrays.
## Syntax
The syntax is inspired by [jq](https://jqlang.github.io/jq/) and JSONPath [RFC9535](https://datatracker.ietf.org/doc/html/rfc9535) and is as follows:
```text
[<operation>]<path>=[<value>]
```
- `<operation>`: An optional operation to perform. Supported operations are Add (+), Replace (=), Remove (-), Test (?), Insert (>), and Merge (~).
- `<path>`: The path to the JSON key. The path can be nested and can include array indices. The path can be separated by a dot (`.`), a slash (`/`), or a custom character.
- `<value>`: A JSON value. Note that the Remove operation does not require a value.
### Operations
Add, Remove, Replace, and Test operations are done as per the JSON Patch specification in [RFC6902](https://datatracker.ietf.org/doc/html/rfc6902/).
- **Add (+):** 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 (-):** Removes the key or element from the JSON structure.
- **Replace (=):** Replaces the value of an existing key. If the key does not exist, the operation fails. Equivalent to a “remove” followed by an “add”.
- **Test (?):** Tests if the key-value pair exists in the JSON structure.
- **Insert (>):** Inserts a new key-value pair into the JSON structure. If the key already exists, the operation overwrites the value.
- **Merge (~):** Preforms a deep merge of the value into the existing JSON structure. null values are preserved in the existing structure. Note that this behavior **differs** from from JSON Merge Patch defined in [RFC7396](https://datatracker.ietf.org/doc/html/rfc7396).
For more information, see the Operation enum itself.
### Paths
Paths can be nested and can include array indices. The path can be separated by a dot (`.`), a slash (`/`), or a custom character.
### Values
Values are parsed by serde_json. The library will attempt to parse the value as a JSON value, defaulting to string.
## Examples
### Basic Usage
```rust
use jqesque::Jqesque;
use serde_json::json;
fn main() {
let input = ">foo.bar[0].baz=hello";
let jqesque = input.parse::<Jqesque>().unwrap();
// Without using turbofish syntax:
// let jqesque: Jqesque = input.parse().unwrap();
// Alternatively, if you want to specify the separator:
// let jqesque = Jqesque::from_str_with_separator(input, Separator::Dot).unwrap();
let json_output = jqesque.as_json();
assert_eq!(json_output, json!({
"foo": {
"bar": [
{
"baz": "hello"
}
]
}
}));
}
```
### Specifying the separator
```rust
use jqesque::{Jqesque, Separator};
use serde_json::json;
fn main() {
let input = ">foo/bar[0]/baz=true";
let jqesque = Jqesque::from_str_with_separator(input, Separator::Slash).unwrap();
let json_output = jqesque.as_json();
assert_eq!(json_output, json!({
"foo": {
"bar": [
{
"baz": true
}
]
}
}));
}
```
### Inserting into an existing JSON structure
```rust
use serde_json::json;
use jqesque::{Jqesque, Separator};
let mut json_obj = json!({
"settings": {
"theme": {
"color": "red",
"font": "Arial",
"size": 12
}
}
});
let input = ">settings.theme={\"color\":\"blue\",\"font\":\"Helvetica\"}";
let jqesque = Jqesque::from_str_with_separator(input, Separator::Dot).unwrap();
jqesque.apply_to(&mut json_obj);
let expected = json!({
"settings": {
"theme": {
"color": "blue",
"font": "Helvetica"
}
}
});
assert_eq!(json_obj, expected);
// Note that the "size" key in the original "theme" object is removed.
```
### Merging into an existing JSON structure
```rust
use serde_json::json;
use jqesque::{Jqesque, Separator};
let mut json_obj = json!({
"settings": {
"theme": {
"color": "red",
"font": "Arial",
"size": 12
}
}
});
let input = "~settings.theme={\"color\":\"blue\",\"font\":\"Helvetica\"}";
let jqesque = Jqesque::from_str_with_separator(input, Separator::Dot).unwrap();
jqesque.apply_to(&mut json_obj);
let expected = json!({
"settings": {
"theme": {
"color": "blue",
"font": "Helvetica",
"size": 12
}
}
});
assert_eq!(json_obj, expected);
// Note that the "size" key in the original "theme" object is preserved.
```
## License
See the [LICENSE](LICENSE) file for details.