JSN

A queryable, streaming, JSON pull-parser with low allocation overhead.

• 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, select::*};

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

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

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

Quick Explanation

Like traditional streaming parsers, the parser emits JSON tokens. The twist is that you can query them in a "fun" way. The best analogy is bitmasks.

If you can use a logical AND to extract a bit pattern:

input   : 0101 0101
AND
bitmask : 0000 1111
=
pattern : 0000 0101

Why can't you use a logical AND to extract a JSON token pattern?

input     : { "hello": { "name" : "world" } }
AND
json mask : {something that extracts a "hello" key}
=
pattern   : _ ________ { "name" : "world" } _

That {something that extracts a "hello" key} is what this crate provides.