jsonp

jsonp[ointer] is a library for efficiently dereferencing nested Json structures in Rust, using serde and serde_json.

This library was split out of another project as I felt it would be useful as a standalone crate.

License

lib.rs:

jsonp

Fast, zero copy Json pointers.

This library leverages serde and serde_json to provide fast, easy to use, on demand deserialization of Json.

Ever wanted to retrieve some deeply nested data without all the hassle of defining the required Rust structures, or allocating multiple times into a serde_json::Value? No problem:

{
  "some": {
    "deeply": [
      {
        "nested": {
          "truth": "the cake is a lie"
        }
      }
    ]
  }
}

fn deeply_nested(json: &str) -> Result {
    let p = Pointer::default();

    let truth: &str = p.dotted(json, ".some.deeply.0.nested.truth")?;

    assert_eq!(truth, "the cake is a lie");

    Ok(())
}

Leveraging serde's zero copy deserialization we borrow the deeply nested truth right out of the backing Json data.

Pointer

The core structure of this library is the jsonp::Pointer. It provides several methods of dereferencing into Json:

• Pointer::with_segments
• Pointer::with_pattern
• Pointer::dotted

While Pointer::with_segments provides the most control over exactly how each Segment is generated, the other two -- Pointer::with_pattern and Pointer::dotted -- make some assumptions about how the pointer string is handled. These are:

1. Passing in an empty pointer (or pattern) string will default to deserializing the entire backing Json.
2. If the pointer and pattern are equal, same as above.
3. A pointer starting with a pattern is equivalent to one that doesn't. For example, dotted(".foo") and dotted("foo") both result in foo being dereferenced.

Mode

jsonp::Mode controls how jsonp interprets pointer segments. It has two settings, Late -- the default -- and Early.

Late

Lazily attempts to coerce pointer segments to map keys or array indexes during deserialization. This provides maximum flexibility and allows one to deserialize numeric map keys, i.e "42": "...", but also has the potential to improperly deserialize an array where a map was expected, or vice versa.

Early

Decides on initialization whether a given pointer segment is a numeric index or string key. Guarantees that backing Json object agrees with its expected layout, erroring out otherwise.

Helpers

This library also provides a few convenience wrapper structs around jsonp::Pointer. These provide pleasant interfaces if you're planning on using a Pointer to repeatedly dereference from a single backing Json structure, and reduce some of the generics and lifetime noise in function signatures.

• jsonp::BackingStr
• jsonp::BackingJson
• jsonp::BackingBytes