Skip to main content

Crate jsontape

Crate jsontape 

Source
Expand description

§JsonTape

A minimalistic, allocator-aware JSON parser in pure Rust, offered in two complementary flavors that share one strict, RFC 8259-conformant scanner.

  • Json is an owned, mutable document and the default. Strings are eagerly unescaped into the document’s allocator at parse time, so Json::as_str needs no source and the tree can be freely edited or built from scratch. Produce one with parse or parse_in.
  • JsonView is an immutable, zero-copy document. String values and object keys are kept as Spans into the original source rather than decoded, so parsing copies nothing, and lookups compare against those still-escaped spans with an escape-aware, allocation-free comparison. Produce one with view or view_in.

Both containers allocate through any allocator_api2::alloc::Allocator, so the whole document can live in a bump arena and free in one step.

use jsontape::parse;

let document = parse(br#"{ "metric": "ip", "nodes": 20000000, "peers": [1, 2, 3] }"#).unwrap();

// Navigate with indexing; a miss anywhere in the chain yields Null, not a panic.
assert_eq!(document["metric"].as_str(), Some("ip"));
assert_eq!(document["nodes"].as_u64(), Some(20_000_000));
assert_eq!(document["peers"][0].as_u64(), Some(1));
assert!(document["absent"].is_null());

§Reading a view without threading source

A JsonView resolves its spans against the source you parsed. Bind the two together with JsonView::bind to get a Resolved cursor that reads strings and navigates by key or index with no source argument:

use jsontape::view_bound;

let source = br#"{ "a": { "b": [10, 20] } }"#;
let document = view_bound(source).unwrap();
assert_eq!(document.get("a").get("b").get(1).as_u64(), Some(20));

§Beyond parsing

§Cargo features

  • std (default) — enables the std::error::Error impl; without it the crate is no_std (still requiring alloc).
  • serde — serde::Serialize/serde::Deserialize for the document types plus to_value/from_value for converting to and from any serde type without a text round trip.

Structs§

ArrayBody
The backing storage for a Json::Array: its elements plus optional comment trivia. With no comments trivia is None and adds no heap allocation. It dereferences to the element Vec, so it indexes, iterates, and pushes like one — array.len(), array[0], for item in &array all work.
BoundJsonView
A zero-copy JsonView permanently paired with the source it was parsed from. Prefer this type when exposing a view beyond the immediate parse site: its navigation and serialization APIs cannot accidentally receive a mismatched source slice.
Comment
A comment preserved from JSON5 source, attached to a container element in the owned Json tree. The zero-copy JsonView never carries comments.
FormatOptions
Controls how a document is rendered back to JSON text.
JsonString
An owned, decoded UTF-8 string used for keys and string values in Json. Its bytes are always valid UTF-8, so JsonString::as_str never fails.
Location
A resolved source position: byte offset plus 1-based line and column. The column counts bytes since the last newline.
ObjectBody
The backing storage for a Json::Object: its (key, value) entries plus optional comment trivia. Like ArrayBody, it dereferences to the entry Vec and carries no heap when there are no comments.
ParseLimits
Optional resource limits for parsing untrusted documents. Limits other than nesting depth are disabled by default, so valid in-memory JSON remains accepted unless an application opts into a bounded profile.
ParseOptions
Knobs for a parse: the nesting limit, the duplicate-key policy, and a set of opt-in lenient extensions toward JSON5. Every lenient flag defaults to false so the default is strict RFC 8259; enable them individually, or start from the jsonc or json5 preset. Build from ParseOptions::default and adjust, then pass to a *_with parser.
Resolved
A JsonView node paired with the source it was parsed from, so string values resolve and keyed navigation work without threading source through every call. Copy, so it chains freely: view.bind(src).get("a").get(0).
Span
A span into the source bytes: a byte offset and a length. String values and object keys are stored this way, undecoded, so parsing copies nothing.

Enums§

CommentStyle
Whether a preserved comment was written as a // line or /* */ block comment.
DuplicateKeys
How to handle repeated keys within a single object.
Indent
Indentation style for pretty-printing: a fixed number of spaces per nesting level, or a single tab per level.
Json
An owned, mutable JSON document. Unlike JsonView, strings are decoded at parse time, so Json::as_str needs no source and the tree can be edited freely. Numbers keep their width past the 2^53 float boundary.
JsonError
Why parsing failed. No code path panics on bad input.
JsonView
An immutable JSON document that borrows its text from the parsed source. String values and object keys are stored as Spans, so nothing is copied; resolve them against the same source you parsed. Numbers keep their width, so large integers survive past the 2^53 float boundary.
SyntaxKind
What kind of syntax fault occurred. Non-exhaustive so new categories can be added without a breaking change.

Traits§

Lookup
Types that can index a Json value: a &str object key or a usize array position. Powers Json::get, Json::get_mut, and the infix core::ops::Index operators.
ResolveKey
A key or index that resolves a child of a Resolved cursor: a &str object key (escape-aware) or a usize array position.

Functions§

from_value
Deserializes any T: Deserialize directly from a borrowed Json. Strings are borrowed from the document, so &str fields need no copy.
parse
Parses source into an owned, mutable Json on the global heap.
parse_in
Parses source into an owned, mutable Json allocated in allocator, decoding every string’s escapes. The result borrows nothing from source.
parse_in_with
Parses source into an owned, mutable Json allocated in allocator, under options. The result borrows nothing from source.
parse_with
Parses source into an owned, mutable Json on the global heap under options.
to_value
Serializes any T: Serialize into an owned Json on the global heap, without going through a text representation.
unescape_into
Decodes a JSON string span from source, appending the resulting UTF-8 bytes to output. Spans produced by this crate’s parser are always well-formed; a hand-built or mismatched span is reported, never panicked on.
view
Parses source into an immutable JsonView on the global heap.
view_bound
Parses a source-bound, zero-copy document on the global heap. Unlike view, the returned value retains its source reference and therefore cannot be navigated or serialized with a mismatched byte slice.
view_in
Parses source into an immutable JsonView allocated in allocator. Spans in the result are offsets into source, so keep source alive.
view_in_bound
Parses a source-bound, zero-copy document with allocator.
view_in_bound_with
Parses a source-bound, zero-copy document with allocator under options.
view_in_with
Parses source into an immutable JsonView allocated in allocator, under options. Spans in the result are offsets into source.
view_with
Parses source into an immutable JsonView on the global heap under options.
write_escaped_str
Writes text as a quoted JSON string, escaping what the grammar requires.
write_number
Writes a finite JSON number straight to writer. Non-finite floats become null, and integral floats keep a trailing .0 so their type survives a round trip. f64’s formatter never uses exponent notation, so writing directly and appending .0 when integral needs no intermediate buffer. Public alongside write_escaped_str, for the same incremental callers.