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.

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.