Struct TeaLeaf 

pub struct TeaLeaf {
    pub schemas: IndexMap<String, Schema>,
    pub unions: IndexMap<String, Union>,
    pub data: IndexMap<String, Value>,
    /* private fields */
}

A parsed TeaLeaf document

Fields

schemas: IndexMap<String, Schema>

unions: IndexMap<String, Union>

data: IndexMap<String, Value>

Implementations

impl TeaLeaf

pub fn new( schemas: IndexMap<String, Schema>, data: IndexMap<String, Value>, ) -> Self

Create a new TeaLeaf document from data and schemas.

This constructor is primarily for programmatic document creation. For parsing from formats, use parse(), load(), or from_json().

pub fn parse(input: &str) -> Result<Self>

Parse TeaLeaf text format

pub fn load<P: AsRef<Path>>(path: P) -> Result<Self>

Load from text file

Include paths are resolved relative to the loaded file’s directory.

pub fn get(&self, key: &str) -> Option<&Value>

Get a value by key

pub fn schema(&self, name: &str) -> Option<&Schema>

Get a schema by name

pub fn union(&self, name: &str) -> Option<&Union>

Get a union by name

pub fn compile<P: AsRef<Path>>(&self, path: P, compress: bool) -> Result<()>

Compile to binary format

pub fn from_json(json: &str) -> Result<Self>

Parse from JSON string.

Stability Policy

This function follows a “plain JSON only” policy:

• JSON is parsed as-is with no magic conversion
• {"$ref": "x"} stays as an Object, NOT a Ref
• {"$tag": "ok", "$value": 200} stays as an Object, NOT a Tagged
• "0xcafef00d" stays as a String, NOT Bytes
• "2024-01-15T10:30:00Z" stays as a String, NOT a Timestamp
• [[1, "one"], [2, "two"]] stays as an Array, NOT a Map

To create special TeaLeaf types, use the text format or binary API directly.

Number Type Inference

• Integers that fit i64 → Value::Int
• Large positive integers that fit u64 → Value::UInt
• Numbers with decimals or scientific notation → Value::Float

pub fn from_json_with_schemas(json: &str) -> Result<Self>

Parse from JSON string with automatic schema inference.

This variant analyzes the JSON structure and automatically:

• Detects arrays of uniformly-structured objects
• Infers schema names from parent keys (e.g., “products” → “product”)
• Generates @struct definitions for uniform arrays
• Enables @table format output when serialized

Use to_tl_with_schemas() to serialize with the inferred schemas.

pub fn to_tl_with_schemas(&self) -> String

Serialize to TeaLeaf text format with schemas.

If schemas are present (either from parsing or inference), outputs @struct definitions and uses @table format for matching arrays.

If this document represents a root-level JSON array (from from_json), the output will include @root-array directive for round-trip fidelity.

pub fn to_json(&self) -> Result<String>

Convert to JSON string (pretty-printed).

Stability Policy - TeaLeaf→JSON Fixed Representations

Special TeaLeaf types serialize to JSON with these stable formats:

TeaLeaf Type	JSON Format
Bytes	"0xcafef00d" (lowercase hex with 0x prefix)
Timestamp	"2024-01-15T10:30:00.123Z" (ISO 8601 UTC)
Ref	{"$ref": "key_name"}
Tagged	{"$tag": "tag_name", "$value": <value>}
Map	[[key1, val1], [key2, val2], ...]
Float NaN	null (JSON has no NaN)
Float ±Inf	null (JSON has no Infinity)

These representations are contractually stable and will not change.

pub fn to_json_compact(&self) -> Result<String>

Convert to compact JSON string (no pretty printing)

pub fn set_root_array(&mut self, is_root_array: bool)

Set whether the document represents a root-level array.

pub fn from_reader(reader: &Reader) -> Result<Self>

Create a TeaLeaf document from a binary Reader.

Reads all sections from the reader and carries schemas and unions through.

pub fn from_dto<T: ToTeaLeaf>(key: &str, dto: &T) -> Self

Create a TeaLeaf document from a single DTO.

The DTO is placed under the given key in the document data map. Schemas are automatically collected from the DTO type.

pub fn from_dto_array<T: ToTeaLeaf>(key: &str, items: &[T]) -> Self

Create a TeaLeaf document from a slice of DTOs.

The array is placed under the given key and schemas are collected from the element type.

pub fn to_dto<T: FromTeaLeaf>(&self, key: &str) -> Result<T>

Extract a DTO from this document by key.

pub fn to_dto_vec<T: FromTeaLeaf>(&self, key: &str) -> Result<Vec<T>>

Extract all values under a key as Vec<T>.