Quick Start

This guide walks through the core TeaLeaf workflow: write text, compile to binary, and convert to/from JSON.

1. Write a TeaLeaf File

Create example.tl:

# Define schemas
@struct address (street: string, city: string, zip: string)
@struct user (
  id: int,
  name: string,
  email: string?,
  address: address,
  active: bool,
)

# Data uses schemas -- field names defined once, not repeated
users: @table user [
  (1, "Alice", "alice@example.com", ("123 Main St", "Seattle", "98101"), true),
  (2, "Bob", ~, ("456 Oak Ave", "Austin", "78701"), false),
]

# Plain key-value pairs
app_version: "2.0.0-beta.2"
debug: false

2. Validate

Check that the file is syntactically correct:

tealeaf validate example.tl

3. Compile to Binary

Compile to the compact binary format:

tealeaf compile example.tl -o example.tlbx

4. Inspect

View information about either format:

tealeaf info example.tl
tealeaf info example.tlbx

5. Convert to JSON

# Text to JSON
tealeaf to-json example.tl -o example.json

# Binary to JSON
tealeaf tlbx-to-json example.tlbx -o example_from_binary.json

6. Convert from JSON

# JSON to TeaLeaf text (with automatic schema inference)
tealeaf from-json example.json -o reconstructed.tl

# JSON to TeaLeaf binary
tealeaf json-to-tlbx example.json -o direct.tlbx

7. Decompile

Convert binary back to text:

tealeaf decompile example.tlbx -o decompiled.tl

Complete Workflow

example.tl ──compile──> example.tlbx ──decompile──> decompiled.tl
    │                       │
    ├──to-json──> example.json <──tlbx-to-json──┘
    │                │
    └──from-json─────┘

Using the Rust API

use tealeaf::TeaLeaf;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Parse text format
    let doc = TeaLeaf::load("example.tl")?;

    // Access values
    if let Some(users) = doc.get("users") {
        println!("Users: {:?}", users);
    }

    // Compile to binary
    doc.compile("example.tlbx", true)?;

    // Convert to JSON
    let json = doc.to_json()?;
    println!("{}", json);

    Ok(())
}

With Derive Macros

use tealeaf::{TeaLeaf, ToTeaLeaf, FromTeaLeaf, ToTeaLeafExt};

#[derive(ToTeaLeaf, FromTeaLeaf)]
struct User {
    id: i32,
    name: String,
    #[tealeaf(optional)]
    email: Option<String>,
    active: bool,
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let user = User {
        id: 1,
        name: "Alice".into(),
        email: Some("alice@example.com".into()),
        active: true,
    };

    // Serialize to TeaLeaf text
    let text = user.to_tl_string("user");
    println!("{}", text);

    // Compile directly to binary
    user.to_tlbx("user", "user.tlbx", false)?;

    // Deserialize from binary
    let reader = tealeaf::Reader::open("user.tlbx")?;
    let loaded = User::from_tealeaf_value(&reader.get("user")?)?;

    Ok(())
}

Using the .NET API

Source Generator (Compile-Time)

using TeaLeaf;
using TeaLeaf.Annotations;

[TeaLeaf]
public partial class User
{
    public int Id { get; set; }
    public string Name { get; set; } = "";

    [TLOptional]
    public string? Email { get; set; }

    public bool Active { get; set; }
}

// Serialize
var user = new User { Id = 1, Name = "Alice", Active = true };
string text = user.ToTeaLeafText();
string json = user.ToTeaLeafJson();
user.CompileToTeaLeaf("user.tlbx");

// Deserialize
using var doc = TLDocument.ParseFile("user.tlbx");
var loaded = User.FromTeaLeaf(doc);

Reflection Serializer (Runtime)

using TeaLeaf;

var user = new User { Id = 1, Name = "Alice", Active = true };

// Serialize
string docText = TeaLeafSerializer.ToDocument(user);
TeaLeafSerializer.Compile(user, "user.tlbx");

// Deserialize
var loaded = TeaLeafSerializer.FromText<User>(docText);

Next Steps

• Core Concepts – understand schemas, types, and the text format
• CLI Reference – all available commands
• Rust Guide – Rust API in depth
• .NET Guide – .NET bindings in depth