Crate jsn

This crate implements a queryable, streaming, JSON pull parser.

• Pull parser?: The parser is implemented as an iterator that emits tokens.
• Streaming?: The JSON document being parsed is never fully loaded into memory. It is read & validated byte by byte. This makes it ideal for dealing with large JSON documents
• Queryable? You can configure the iterator to only emit & allocate tokens for the parts of the input you are interested in.

JSON is expected to conform to RFC 8259. It can come from any source that implements the Read trait (e.g. a file, byte slice, network socket etc..)

Basic Usage

use jsn::{Tokens, mask::*};

let data = r#"
    {
        "name": "John Doe",
        "age": 43,
        "phones": [
            "+44 1234567",
            "+44 2345678",
        ]
    }
"#;

let mut iter = Tokens::new(data.as_bytes())
    .with_mask(key("age") | index(0));

assert_eq!(iter.next().unwrap(), 43);
assert_eq!(iter.next().unwrap(), "+44 1234567");
assert_eq!(iter.next(), None);

A few things to notice and whet your appetite:

• The only JSON-related heap allocations are for the “age” and phone number tokens.
• You can compare tokens to native rust types directly
• Token masks match anywhere in json; Though the top-level value was an object, we used the index mask to match a value that was at index 0 in an array nested in the “phones” object.

Modules

• mask
  Token masks are to JSON tokens what bitmasks are to bits.

Structs

• DryRun
  Result of calling Tokens::dry_run
• JsonError
  Bundles the reason & location of a parsing error
• Tokens
  A queryable, streaming JSON pull parser

Enums

• Reason
  All the possible reasons parsing json might fail
• Token
  A token in a JSON stream. You can convert a token to a Rust type using Token::get().

Traits

• FromJson
  A trait for types that can be created from a JSON token