Crate jsonptr

jsonptr - JSON Pointers for Rust

Data structures and logic for resolving, assigning, and deleting by JSON Pointers (RFC 6901).

Usage

Resolve

JSON Pointers can be created either with a slice of strings or directly from a properly encoded string representing a JSON Pointer.

use jsonptr::{Pointer, Resolve, ResolveMut};
use serde_json::json;

fn main() {
    let mut data = json!({
        "foo": {
            "bar": "baz"
        }
    });

    let ptr = Pointer::new(&["foo", "bar"]);
    ptr.resolve(&data);
    let bar = data.resolve(&ptr).unwrap();
    assert_eq!(bar, "baz");

    let ptr = Pointer::try_from("/foo/bar").unwrap();
    let mut bar = data.resolve_mut(&ptr).unwrap(); // alternatively: ptr.resolve_mut(&mut data);
    assert_eq!(bar, "baz");
}

Assign

use jsonptr::{Pointer, Assign};
use serde_json::json;

fn main() {
    let ptr = Pointer::try_from("/foo/bar").unwrap();
    let mut data = json!({});
    let val = json!("qux");
    let assignment = data.assign(&ptr, val);
    assert_eq!(data, json!({ "foo": { "bar": "qux" }}))
}

Delete

    use jsonptr::{Pointer, Delete};
    use serde_json::json;
fn main() {
    let mut data = json!({ "foo": { "bar": { "baz": "qux" } } });
    let ptr = Pointer::new(&["foo", "bar", "baz"]);
    assert_eq!(data.delete(&ptr), Ok(Some("qux".into())));
    assert_eq!(data, json!({ "foo": { "bar": {} } }));

    // unresolved pointers return Ok(None)
    let mut data = json!({});
    let ptr = Pointer::new(&["foo", "bar", "baz"]);
    assert_eq!(ptr.delete(&mut data), Ok(None));
    assert_eq!(data, json!({}));

    // replacing a root pointer replaces data with `Value::Null`
    let mut data = json!({ "foo": { "bar": "baz" } });
    let ptr = Pointer::default();
    assert_eq!(data.delete(&ptr), Ok(Some(json!({ "foo": { "bar": "baz" } }))));
    assert!(data.is_null());
}

Contributions / Issues

Contributions and feedback are always welcome and appreciated.

If you find an issue, please open a ticket or a pull request.

License

MIT or Apache 2.0.

Modules

prelude

Exposes the traits Assign, Delete, Resolve, ResolveMut

Structs

Assignment

The data structure returned from a successful call to assign.

NotFoundError

NotFoundError indicates that a Pointer was not found in the data.

NotUtf8Error

Pointer was not in UTF-8 format.

OutOfBoundsError

Indicates that the Pointer contains an index of an array that is out of bounds.

ParseError

ParseError represents an that an error occurred when parsing an index.

Pointer

A JSON Pointer is a string containing a sequence of zero or more reference tokens, each prefixed by a ‘/’ character.

ReplaceTokenError

Returned from Pointer::replace_token when the provided index is out of bounds.

Token

A Token is a segment of a JSON Pointer, seperated by ‘/’ (%x2F). It can represent a key in a JSON object or an index in a JSON array.

Tokens

An iterator over the tokens in a Pointer.

UnresolvableError

Represents an error that occurs when attempting to resolve a Pointer that encounters a leaf node (i.e. a scalar / null value) which is not the root of the Pointer.

Enums

Error

An enum representing possible errors that can occur when resolving or mutating by a JSON Pointer.

IndexError

Indicates an error occurred while parsing a usize (ParseError) or the parsed value was out of bounds for the targeted array.

MalformedPointerError

Indicates that a Pointer was malformed.

Traits

Assign

Assign is implemented by types which can internally assign a serde_json::Value by a JSON Pointer.

Delete

Delete is implemented by types which can internally remove a value based on a JSON Pointer

Resolve

Resolve is implemented by types which can resolve a reference to a serde_json::Value from the path in a JSON Pointer.

ResolveMut

ResolveMut is implemented by types which can resolve a mutable reference to a serde_json::Value from the path in a JSON Pointer.