json_slabs/lib.rs
1//! A crate for reading and writing JsonSlabs (JSLB) files — a binary
2//! container format for JSON-shaped data with embedded typed-array slabs.
3//!
4//! JSON slabs use placeholder objects of the form `{ "$s": <slab-index> }`
5//! to refer to data that's stored in other slabs.
6//!
7//! This crate does not include any JSON parsing or JSON writing code; for JSON
8//! slabs, this crate only works with raw bytes and leaves the parsing /
9//! placeholder substitution to the consumer.
10//!
11//! See [`FORMAT.md`][format] in the repo root for the on-disk layout.
12//!
13//! Use [`Builder`] for writing and [`ParsedFile`] for reading.
14//!
15//! [format]: https://github.com/mstange/json-slabs/blob/main/FORMAT.md
16//!
17//! # Writing
18//!
19//! ```
20//! use json_slabs::Builder;
21//!
22//! let mut b = Builder::new();
23//! let numbers = b.add_slab(&[10i32, 20, 30]);
24//! let sub_json = b.add_json_slab(br#"["hello", "world"]"#.to_vec());
25//! // `{:#}` on a placeholder prints the whole `{"$s": N}` reference.
26//! let skeleton = format!(r#"{{"numbers":{numbers:#},"splitOutArray":{sub_json:#}}}"#);
27//! let bytes = b.finish(skeleton.as_bytes());
28//! # assert!(bytes.starts_with(&json_slabs::MAGIC));
29//! ```
30//!
31//! # Reading
32//!
33//! ```
34//! use json_slabs::{ParsedFile, SlabPlaceholder};
35//!
36//! # let mut b = json_slabs::Builder::new();
37//! # let numbers = b.add_slab(&[10i32, 20, 30]);
38//! # let skeleton = format!(r#"{{"numbers":{numbers:#}}}"#);
39//! # let bytes = b.finish(skeleton.as_bytes());
40//! let parsed = ParsedFile::parse(&bytes).unwrap();
41//! // The root JSON slab (as raw JSON bytes).
42//! let _root: &[u8] = parsed.root_json_bytes();
43//! // Read a typed slab back. `SlabPlaceholder(1)` here matches the
44//! // `{"$s": 1}` placeholder found in the root JSON; in practice
45//! // you'd parse the JSON and get the slab index from the parsed
46//! // placeholder.
47//! let numbers_back: Vec<i32> = parsed.read(SlabPlaceholder(1)).unwrap();
48//! assert_eq!(numbers_back, vec![10, 20, 30]);
49//! ```
50//!
51
52mod read;
53mod types;
54mod write;
55
56pub use read::*;
57pub use types::*;
58pub use write::*;