Expand description
§TOON Format for Rust
Token-Oriented Object Notation (TOON) is a compact, human-readable format designed for passing structured data to Large Language Models with significantly reduced token usage.
This crate is the official Rust implementation of TOON, targeting
specification v4.4 (toon-spec: 4.4).
Documented implementation-defined behavior:
- Numeric out-of-range policy (§4): integral tokens preserve full
i64/u64precision. An integral token outside that domain decodes asf64when it is that float’s canonical spelling – the form the encoder writes for anf64such as1e20, which therefore round-trips – and as a string otherwise, so-9223372036854775809and18446744073709551616decode as strings rather than as a nearby number. Fractional and exponent forms parse asf64, with integer-valued results normalized to integers (-1E+03decodes as the integer-1000). A token whose value is not finite inf64decodes as a string. - Host-type normalization (§3) follows
serde::Serialize; Rust strings are always well-formed UTF-8, so unpaired surrogates cannot occur. - Decoded objects preserve document key order (
serde_jsonwithpreserve_order), and every key — including__proto__,constructor, andprototype— is an ordinary map entry (§15). - Nesting depth limit (§15): encoding and decoding recurse over nesting, so both impose the documented limit of 256 levels — including nested field groups in headers — and report exceeding it as an error rather than exhausting the host stack.
§Resources
§Example Usage
use serde_json::{json, Value};
use toon_format::{encode_default, decode_default};
let data = json!({"users": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]});
let toon = encode_default(&data)?;
assert_eq!(toon, "users[2]{id,name}:\n 1,Alice\n 2,Bob");
let decoded: Value = decode_default(&toon)?;
assert_eq!(decoded, data);Re-exports§
pub use decode::decode;pub use decode::decode_default;pub use decode::decode_strict;pub use decode::decode_strict_with_options;pub use encode::encode;pub use encode::encode_array;pub use encode::encode_default;pub use encode::encode_object;pub use types::DecodeOptions;pub use types::Delimiter;pub use types::EncodeOptions;pub use types::Indent;pub use types::ToonError;pub use utils::literal::is_keyword;pub use utils::literal::is_literal_like;pub use utils::normalize;pub use utils::string::escape_string;pub use utils::string::is_valid_unquoted_key;pub use utils::string::needs_quoting;pub use utils::string::unescape_string;