docspec-json 1.21.9

JSON writing primitives for docspec writers
Documentation

docspec-json

JSON writing primitives for docspec writers

docspec-json is the toolkit the JSON-shaped DocSpec writers are built on. Its JsonEmitter drives a pluggable JsonBackend through valid JSON shapes only — write a key outside an object, or two values for one key, and you get an error before a single byte reaches the backend. The default StrusonBackend streams to any io::Write. Streaming, like the rest of DocSpec. (See the Manifesto for why.)

Reach for this crate when you are building your own JSON writer; the BlockNote and oxa.dev writers are built on it.

Add it

[dependencies]
docspec-json = "1"

Emit some JSON

Wrap a writer in StrusonBackend, hand it to a JsonEmitter, and build the document with the fluent closure API — objects, arrays, keys, and scalars:

use docspec_json::{JsonEmitter, StrusonBackend};

let mut emitter = JsonEmitter::new(StrusonBackend::new(Vec::new()));
emitter.object(|doc| {
    doc.key("type").value("heading")?;
    doc.key("level").value(1u32)?;
    doc.key("content").array(|c| c.value("Hello"))
})?;
let json: Vec<u8> = emitter.finish()?;

assert_eq!(json, br#"{"type":"heading","level":1,"content":["Hello"]}"#);
# Ok::<(), Box<dyn std::error::Error>>(())

Prefer to open and close frames yourself? The streaming form — open_object, close_object, open_array, close_array — shares the same state machine.

What's inside

  • JsonEmitter — the fluent and streaming API, with stack-based shape validation.
  • JsonBackend — the trait a backend implements; swap in your own.
  • StrusonBackend — the default backend, streaming to any io::Write via struson.
  • WriteVal — the scalar values the emitter accepts (&str, bool, u8, u32, Null).

Related