### JSON Streaming Encode Example

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/configuration.md

Demonstrates how to use `encode_json_stream` with custom `StreamingEncodeOptions`. This example requires the 'json_stream' feature to be enabled.

```rust
#[cfg(feature = "json_stream")]
{
    use std::io::Cursor;
    use toon_format::{encode_json_stream, EncodeOptions, StreamingEncodeOptions};

    let input = Cursor::new(br#"{"users": [{"id": 1, "name": "Alice"}]}"#);
    let mut output = Vec::new();

    let stream_opts = StreamingEncodeOptions::new()
        .with_streaming_depth(1);

    encode_json_stream(
        input,
        &mut output,
        &EncodeOptions::default(),
        &stream_opts,
    )?;
}
```

--------------------------------

### Application Configuration Example

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/usage-patterns.md

Use TOON for managing application configuration by encoding and decoding structured data to/from files. This demonstrates a practical integration scenario.

```rust
use serde::{Serialize, Deserialize};
use toon_format::{encode_default, decode_default};
use std::fs;

#[derive(Serialize, Deserialize, Debug)]
struct AppConfig {
    app_name: String,
    version: String,
    database: DatabaseConfig,
    features: Vec<String>,
}

#[derive(Serialize, Deserialize, Debug)]
struct DatabaseConfig {
    host: String,
    port: u16,
    pool_size: u32,
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create configuration
    let config = AppConfig {
        app_name: "MyApp".to_string(),
        version: "1.0.0".to_string(),
        database: DatabaseConfig {
            host: "localhost".to_string(),
            port: 5432,
            pool_size: 10,
        },
        features: vec!["auth".to_string(), "logging".to_string()],
    };

    // Save to file
    let toon = encode_default(&config)?;
    fs::write("config.toon", &toon)?;

    // Load from file
    let contents = fs::read_to_string("config.toon")?;
    let loaded: AppConfig = decode_default(&contents)?;

    println!("Loaded config: {:?}", loaded);
    Ok(())
}
```

--------------------------------

### Delimiter Usage Examples

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/types.md

Demonstrates how to use the Delimiter enum, including getting character representations, parsing from characters, and checking if a delimiter exists within a string.

```rust
use toon_format::Delimiter;

let delim = Delimiter::Pipe;
assert_eq!(delim.as_char(), '|');
assert_eq!(delim.as_metadata_str(), "|");

// Parse from character
assert_eq!(Delimiter::from_char(','), Some(Delimiter::Comma));
assert_eq!(Delimiter::from_char('x'), None);

// Check containment
assert!(Delimiter::Comma.contains_in("a,b,c"));
```

--------------------------------

### Add TOON Format with JSON Stream Feature

Source: https://github.com/toon-format/toon-rust/blob/main/README.md

Install the toon-format crate with the json_stream feature enabled to handle large JSON inputs efficiently.

```bash
cargo add toon-format --features json_stream
```

--------------------------------

### Common EncodeOptions Presets

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/configuration.md

Provides examples of common `EncodeOptions` presets for different use cases, including minimal, pretty-printed, and tab-separated with folding.

```rust
// Minimal (most compact)
let opts = EncodeOptions::new();

// Pretty with 4-space indent
let opts = EncodeOptions::new().with_spaces(4);

// Tab-separated with folding
let opts = EncodeOptions::new()
    .with_delimiter(Delimiter::Tab)
    .with_key_folding(KeyFoldingMode::Safe);
```

--------------------------------

### Full Example: Fold Keys, Show Stats, and Pipe Input

Source: https://github.com/toon-format/toon-rust/blob/main/README.md

Combines multiple CLI options: piping JSON input, enabling key folding, displaying statistics, and showing the resulting TOON output with calculated savings.

```bash
$ echo '{"data":{"meta":{"items":["x","y"]}}}' | toon --fold-keys --stats

data.meta.items[2]: x,y

Stats:
+--------------+------+------+---------+
| Metric       | JSON | TOON | Savings |
+======================================+
| Tokens       | 13   | 8    | 38.46%  |
|--------------+------+------+---------|
| Size (bytes) | 38   | 23   | 39.47%  |
+--------------+------+------+---------+
```

--------------------------------

### Variable Usage Example

Source: https://github.com/toon-format/toon-rust/blob/main/docs/TUI.md

Demonstrates referencing the last result with '$_' and stored variables with '$varname' in the REPL. This is key for chaining operations and testing.

```bash
let $data = {...}
encode $data
```

--------------------------------

### Using ErrorContext for Diagnostics

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/errors.md

Example showing how to extract and utilize the ErrorContext when a LengthMismatch error occurs, printing the source line and any provided suggestion.

```rust
match toon_format::decode_strict::<serde_json::Value>("items[3]: a,b") {
    Err(ToonError::LengthMismatch { context: Some(ctx), .. }) => {
        println!("Error context:");
        println!("  Line: {}", ctx.source_line);
        if let Some(suggestion) = &ctx.suggestion {
            println!("  Suggestion: {}", suggestion);
        }
    }
    _ => {}
}
```

--------------------------------

### PathExpansionMode Decoding Example

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/types.md

Illustrates decoding TOON strings with PathExpansionMode::Safe, showing expansion of dotted keys into nested objects and handling of quoted keys.

```rust
use toon_format::{DecodeOptions, PathExpansionMode};
use serde_json::json;

let toon = "a.b.c: 1
a.b.d: 2";

let opts = DecodeOptions::new()
    .with_expand_paths(PathExpansionMode::Safe);
let result = toon_format::decode::<serde_json::Value>(toon, &opts)?;
// Result: {"a": {"b": {"c": 1, "d": 2}}}

// Quoted keys remain literal
let toon2 = r#"a.b: 1
"c.d": 2"#;
let result2 = toon_format::decode::<serde_json::Value>(toon2, &opts)?;
// Result: {"a": {"b": 1}, "c.d": 2}
```

--------------------------------

### Indent Usage Examples

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/types.md

Shows how to use the Indent enum to generate indentation strings based on nesting depth. Defaults to 2 spaces per level.

```rust
use toon_format::Indent;

let indent = Indent::Spaces(4);
assert_eq!(indent.get_string(0), "");
assert_eq!(indent.get_string(1), "    ");
assert_eq!(indent.get_string(2), "        ");
```

--------------------------------

### Launch Interactive TUI

Source: https://github.com/toon-format/toon-rust/blob/main/README.md

Starts the TOON Terminal User Interface for interactive conversions. This tool allows real-time editing, statistics, and option adjustments.

```bash
# Launch interactive mode
toon --interactive
# or
toon -i
```

--------------------------------

### KeyFoldingMode Encoding Example

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/types.md

Demonstrates encoding TOON data with and without KeyFoldingMode::Safe. Safe mode collapses nested single-key objects into dotted paths.

```rust
use toon_format::{EncodeOptions, KeyFoldingMode};
use serde_json::json;

let data = json!({"user": {"profile": {"name": "Alice"}}});

// With folding
let opts = EncodeOptions::new()
    .with_key_folding(KeyFoldingMode::Safe);
// Output: user.profile.name: Alice

// Without folding (default)
let opts = EncodeOptions::new();
// Output:
// user:
//   profile:
//     name: Alice
```

--------------------------------

### Handling LengthMismatch Errors

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/errors.md

Example of decoding a TOON string and handling a potential LengthMismatch error using pattern matching. It prints the expected and found lengths if the error occurs.

```rust
use toon_format::{decode_strict, ToonError};
use serde_json::Value;

match decode_strict::<Value>("items[3]: a,b") {
    Err(ToonError::LengthMismatch { expected, found, .. }) => {
        eprintln!("Expected {} items, found {}", expected, found);
    }
    _ => {}
}
```

--------------------------------

### Set Indentation Style

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/configuration.md

Specifies the indentation strategy for nested structures in the encoded TOON format. This example sets indentation to 4 spaces.

```rust
use toon_format::{EncodeOptions, Indent};

let opts = EncodeOptions::new()
    .with_indent(Indent::Spaces(4));

// Nested output gets 4-space indentation
```

--------------------------------

### Build Documentation

Source: https://github.com/toon-format/toon-rust/blob/main/README.md

Generate and open the project's documentation using Cargo.

```bash
cargo doc --open
```

--------------------------------

### Handle ToonError Variants

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/QUICKREF.md

Example of matching and handling specific ToonError variants like LengthMismatch and ParseError.

```rust
match result {
    Ok(v) => { /* ... */ } 
    Err(ToonError::LengthMismatch { expected, found, .. }) => {
        eprintln!("Expected {} items, got {}", expected, found);
    }
    Err(ToonError::ParseError { line, column, message, .. }) => {
        eprintln!("Line {}:{}: {}", line, column, message);
    }
    Err(e) => eprintln!("Error: {}", e),
}
```

--------------------------------

### Show Help in REPL

Source: https://github.com/toon-format/toon-rust/blob/main/docs/TUI.md

Use the 'help' command to display the help information within the REPL. This is useful for quickly referencing available commands.

```bash
help
```

--------------------------------

### Handling SerializationError Errors

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/errors.md

Example of encoding a JSON Value to TOON format and handling a potential SerializationError, printing the error message.

```rust
use toon_format::{encode_default, ToonError};

match encode_default(&serde_json::Value::Number(
    serde_json::Number::from_f64(f64::NAN).unwrap()
)) {
    Err(ToonError::SerializationError(msg)) => {
        eprintln!("Serialization failed: {}", msg);
    }
    _ => {}
}
```

--------------------------------

### Build and Test toon-rust Project

Source: https://github.com/toon-format/toon-rust/blob/main/CONTRIBUTING.md

Clone the repository, build the project, initialize spec submodule, and run tests using Cargo.

```bash
git clone https://github.com/toon-format/toon-rust.git
cd toon-rust
cargo build
git submodule update --init --recursive
cargo test
```

--------------------------------

### Common DecodeOptions Presets

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/configuration.md

Illustrates common presets for DecodeOptions, showing how to create instances for strict, relaxed, no type coercion, and path expansion scenarios.

```rust
// Strict (default)
let opts = DecodeOptions::new();
```

```rust
// Relaxed (lenient validation)
let opts = DecodeOptions::new().with_strict(false);
```

```rust
// No type coercion
let opts = DecodeOptions::new().with_coerce_types(false);
```

```rust
// With path expansion
let opts = DecodeOptions::new()
    .with_expand_paths(PathExpansionMode::Safe);
```

```rust
// Combined
let opts = DecodeOptions::new()
    .with_strict(false)
    .with_coerce_types(false)
    .with_expand_paths(PathExpansionMode::Safe);
```

--------------------------------

### Creating an ErrorContext Instance

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/types.md

Shows how to instantiate and configure an ErrorContext with specific details like the source line, a suggestion for resolution, and an indicator for the error position.

```rust
use toon_format::types::ErrorContext;

let ctx = ErrorContext::new("items[3]: a,b")
    .with_suggestion("Expected 3 items but found 2")
    .with_indicator(7);
```

--------------------------------

### Handle Decoding Errors

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/README.md

Use a `match` statement to handle potential `ToonError` variants during decoding. This example specifically catches and reports `ParseError` details.

```rust
use toon_format::{decode_default, ToonError};

match decode_default::<serde_json::Value>("invalid") {
    Ok(v) => println!("Success: {:?}", v),
    Err(ToonError::ParseError { line, column, message, .. }) => {
        eprintln!("Parse error at {}:{}: {}", line, column, message);
    }
    Err(e) => eprintln!("Error: {}", e),
}
```

--------------------------------

### Clone Repository and Run Tests

Source: https://github.com/toon-format/toon-rust/blob/main/README.md

Clone the TOON Rust repository and execute tests using Cargo.

```bash
git clone https://github.com/your-org/toon-rust.git
cd toon-rust

cargo test --all
```

--------------------------------

### Run Lints and Format Code

Source: https://github.com/toon-format/toon-rust/blob/main/README.md

Apply lints and format the code using Cargo.

```bash
cargo clippy -- -D warnings

cargo fmt
```

--------------------------------

### Launch TUI

Source: https://github.com/toon-format/toon-rust/blob/main/docs/TUI.md

Launches the Text User Interface (TUI) for the toon-format project. This is the entry point for interactive JSON to TOON conversion and testing.

```bash
toon -i
```

--------------------------------

### Cargo.toml Configuration

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/QUICKREF.md

Add this to your Cargo.toml file to include the toon-format crate with specific features.

```toml
# In Cargo.toml
toon-format = { version = "0.5", features = ["json_stream", "layout"] }
```

--------------------------------

### Create and Check Number Variants

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/types.md

Shows how to create Number variants from different types and check their specific numeric types. Requires importing Number.

```rust
use toon_format::types::Number;

let pos = Number::from(42u64);
assert!(pos.is_u64());

let float = Number::from(3.14);
assert!(float.is_f64());
assert_eq!(float.as_f64(), Some(3.14));
```

--------------------------------

### Auto-detect Encoding/Decoding

Source: https://github.com/toon-format/toon-rust/blob/main/README.md

Demonstrates basic CLI usage for encoding and decoding files based on their extensions. The tool automatically infers the operation.

```bash
# Auto-detect from extension
toon data.json        # Encode
toon data.toon        # Decode
```

--------------------------------

### is_identifier_segment Function

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/types.md

Checks if a given string conforms to the rules of a valid identifier segment for TOON, which must start with a letter or underscore and contain only alphanumeric characters or underscores.

```rust
pub fn is_identifier_segment(s: &str) -> bool
```

--------------------------------

### Run All Tests in toon-rust

Source: https://github.com/toon-format/toon-rust/blob/main/CONTRIBUTING.md

Execute the full test suite for the toon-rust project using Cargo.

```bash
cargo test
```

--------------------------------

### Decode TOON with Layout Metadata

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/api-reference/decoding.md

Use `decode_with_layout` when the `layout` feature is enabled to get both the decoded value and structural metadata. The `Layout` object provides details about the TOON schema.

```rust
#[cfg(feature = "layout")]
{
    use serde_json::Value;
    use toon_format::decode_with_layout;

    let toon = "users[2]{id,name}:\n  1,Alice\n  2,Bob";
    let (data, layout): (Value, _) = decode_with_layout(toon, &DecodeOptions::default())?;
    // layout contains metadata about the tabular structure
}
```

--------------------------------

### Import Core Types

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/QUICKREF.md

Import necessary types and functions from the toon_format crate for encoding and decoding.

```rust
use toon_format::{
    encode, encode_default, decode, decode_default,
    EncodeOptions, DecodeOptions,
    Delimiter, Indent, ToonError,
};
```

--------------------------------

### is_identifier_segment

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/api-reference/utilities.md

Validates if a string segment is a proper identifier for path expansion. Identifiers must start with a letter or underscore, followed by letters, digits, or underscores, and cannot contain dots or special characters.

```APIDOC
## is_identifier_segment

### Description
Check if string is a valid identifier segment for path expansion.

Valid identifier segments:
- Start with letter or underscore
- Followed by letters, digits, or underscores
- Cannot contain dots or other special characters

Used by path expansion to determine if dotted keys can be safely expanded.

### Method Signature
`pub fn is_identifier_segment(s: &str) -> bool`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- `s` (`&str`) - Required - String to validate.

### Return Type
`bool`

### Examples
```rust
use toon_format::is_identifier_segment;

assert!(is_identifier_segment("user"));
assert!(is_identifier_segment("_private"));
assert!(is_identifier_segment("user123"));
assert!(!is_identifier_segment("123"));    // Starts with digit
assert!(!is_identifier_segment("user-name")); // Contains hyphen
assert!(!is_identifier_segment("user.name")); // Contains dot
```
```

--------------------------------

### Pipe Input to TOON

Source: https://github.com/toon-format/toon-rust/blob/main/README.md

Illustrates how to use TOON with standard input (stdin) for encoding or decoding data piped from other commands. This enables seamless integration into shell pipelines.

```bash
# Pipe from stdin
cat data.json | toon
echo '{"name": "Alice"}' | toon -e
```

--------------------------------

### Validate Unquoted Key Format

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/api-reference/utilities.md

Checks if a string is a valid TOON unquoted key. Valid keys must start with a letter or underscore, followed by alphanumeric characters, underscores, or dots, and cannot be empty.

```rust
use toon_format::is_valid_unquoted_key;

assert!(is_valid_unquoted_key("normal_key"));
assert!(is_valid_unquoted_key("key.nested.value"));
assert!(is_valid_unquoted_key("_private"));
assert!(!is_valid_unquoted_key("123"));
assert!(!is_valid_unquoted_key("key-name"));
```

--------------------------------

### Encode with Depth Limit Check

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/errors.md

Encodes a JSON Value using default settings. This example demonstrates a scenario that will trigger a `SerializationError` or `DeserializationError` if the nesting depth exceeds the `MAX_DEPTH` constant (256 levels).

```rust
// Will error if nesting > 256 levels
let deeply_nested = json!({"a": {"b": {"c": ... }}});
let result = toon_format::encode_default(&deeply_nested);
```

--------------------------------

### Delimiter Enum

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/types.md

Defines the characters used to separate array elements in TOON output. Includes methods to get the character, its metadata string representation, parse from a character, and check for containment within a string.

```rust
pub enum Delimiter {
    Comma,    // Default
    Tab,
    Pipe,
}
```

--------------------------------

### Check if String is a Valid Identifier Segment

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/api-reference/utilities.md

Use `is_identifier_segment` to validate if a string can be used as a segment in path expansion. It checks for valid starting characters and allowed subsequent characters, ensuring no dots or special symbols are present.

```rust
use toon_format::is_identifier_segment;

assert!(is_identifier_segment("user"));
assert!(is_identifier_segment("_private"));
assert!(is_identifier_segment("user123"));
assert!(!is_identifier_segment("123"));    // Starts with digit
assert!(!is_identifier_segment("user-name")); // Contains hyphen
assert!(!is_identifier_segment("user.name")); // Contains dot
```

--------------------------------

### List Variables in REPL

Source: https://github.com/toon-format/toon-rust/blob/main/docs/TUI.md

Use the 'vars' command to display all variables currently stored in the REPL session. This helps in managing your stored data.

```bash
vars
```

--------------------------------

### Create an Object

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/types.md

Demonstrates creating a JsonValue::Object by inserting key-value pairs into an IndexMap. Requires importing JsonValue and IndexMap.

```rust
use toon_format::types::JsonValue;
use indexmap::IndexMap;

let mut obj = IndexMap::new();
obj.insert("name".to_string(), JsonValue::String("Alice".to_string()));
obj.insert("age".to_string(), JsonValue::Number(30.into()));

let json_obj = JsonValue::Object(obj);
```

--------------------------------

### Enable Path Expansion in Decoder

Source: https://github.com/toon-format/toon-rust/blob/main/README.md

Demonstrates how to enable safe path expansion when decoding TOON strings into JSON values. This is useful for automatically converting dotted keys into nested objects.

```rust
use serde_json::Value;
use toon_format::{decode, DecodeOptions, PathExpansionMode};

let toon = "a.b.c: 1
a.b.d: 2";

// Enable path expansion
let opts = DecodeOptions::new()
    .with_expand_paths(PathExpansionMode::Safe);

let json: Value = decode(toon, &opts)?;
// {"a": {"b": {"c": 1, "d": 2}}}
```

--------------------------------

### Re-export All Utilities

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/api-reference/utilities.md

Imports all available utility functions from the main toon_format crate. This is useful for accessing all utilities with a single import statement.

```rust
use toon_format::{
    escape_string,
    unescape_string,
    is_keyword,
    is_literal_like,
    is_structural_char,
    is_valid_unquoted_key,
    needs_quoting,
    is_identifier_segment,
    normalize,
};
```

--------------------------------

### StreamingEncodeOptions Methods

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/configuration.md

Shows the available methods for StreamingEncodeOptions, including a constructor and a method to set the streaming depth.

```rust
impl StreamingEncodeOptions {
    pub fn new() -> Self>
    pub fn with_streaming_depth(mut self, depth: usize) -> Self
}
```

--------------------------------

### Launch TOON Interactive TUI

Source: https://github.com/toon-format/toon-rust/blob/main/docs/TUI.md

Launches the interactive TUI mode for TOON format conversions. Use the short flag `-i` for the same functionality.

```bash
# Launch interactive mode
toon --interactive

# Or use the short flag
toon -i
```

--------------------------------

### EncodeOptions Configuration

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/QUICKREF.md

Configure encoding options for delimiter, indentation, key folding, and flattening depth.

```rust
EncodeOptions::new()
    .with_delimiter(d)           // Comma | Tab | Pipe
    .with_spaces(n)              // Indentation spaces
    .with_indent(Indent::Spaces(n))
    .with_key_folding(mode)      // Off | Safe
    .with_flatten_depth(n)       // Max folding depth
```

--------------------------------

### Basic Encode and Decode with Default Settings

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/README.md

Use `encode_default` to serialize a serde_json::Value into TOON format and `decode_default` to deserialize it back. Ensure you have `serde_json` and `toon_format` in your dependencies.

```rust
use toon_format::{encode_default, decode_default};
use serde_json::json;

// Encode
let data = json!({"name": "Alice", "age": 30});
let toon = encode_default(&data)?;

// Decode
let result = decode_default::<serde_json::Value>(&toon)?;
assert_eq!(data, result);
```

--------------------------------

### EncodeOptions Constructor

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/configuration.md

Creates a new `EncodeOptions` instance with default values.

```rust
impl EncodeOptions {
    pub fn new() -> Self  // Creates with defaults
}
```

--------------------------------

### General Error Handling with Pattern Matching

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/errors.md

Demonstrates comprehensive error handling for TOON decoding using a match statement that covers specific error types like LengthMismatch, ParseError, and TypeMismatch, as well as a general catch-all for other errors.

```rust
use toon_format::ToonError;

match toon_format::decode_default::<serde_json::Value>(input) {
    Ok(value) => println!("Success: {:?}", value),
    Err(ToonError::LengthMismatch { expected, found, .. }) => {
        eprintln!("Length mismatch: expected {}, found {}", expected, found);
    }
    Err(ToonError::ParseError { line, column, message, .. }) => {
        eprintln!("Parse error at {}:{}: {}", line, column, message);
    }
    Err(ToonError::TypeMismatch { expected, found }) => {
        eprintln!("Type mismatch: expected {}, found {}", expected, found);
    }
    Err(e) => eprintln!("Error: {}", e),
}
```

--------------------------------

### DecodeOptions Configuration

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/QUICKREF.md

Configure decoding options for strictness, delimiter, type coercion, and path expansion.

```rust
DecodeOptions::new()
    .with_strict(bool)           // true = validate array lengths
    .with_delimiter(d)           // Comma | Tab | Pipe (or None = auto)
    .with_coerce_types(bool)     // true = "123" → 123
    .with_expand_paths(mode)     // Off | Safe
```

--------------------------------

### String Utility Functions

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/QUICKREF.md

Utilities for escaping, unescaping, quoting, and validating strings for toon-format.

```rust
// String operations
escape_string(s)                 // → escaped string
unescape_string(s)               // → Result<String, String>
quote_string(s)                  // → "quoted and escaped"
is_valid_unquoted_key(s)         // → bool
needs_quoting(s, delimiter)      // → bool
```

--------------------------------

### Encode and Decode JSON Values with TOON

Source: https://github.com/toon-format/toon-rust/blob/main/README.md

Shows how to encode and decode `serde_json::Value` using the TOON format. This is useful for handling dynamic JSON data.

```rust
use serde_json::{json, Value};
use toon_format::{encode_default, decode_default};

fn main() -> Result<(), toon_format::ToonError> {
    let data = json!({
        "users": [
            {"id": 1, "name": "Alice"},
            {"id": 2, "name": "Bob"}
        ]
    });

    // Encode to TOON
    let toon_str = encode_default(&data)?;
    println!("{}", toon_str);
    // Output:
    // users[2]{id,name}:
    //   1,Alice
    //   2,Bob

    // Decode back to JSON
    let decoded: Value = decode_default(&toon_str)?;
    assert_eq!(decoded, data);

    Ok(())
}
```

--------------------------------

### Force Encoding/Decoding Mode

Source: https://github.com/toon-format/toon-rust/blob/main/README.md

Shows how to explicitly force the TOON tool into encoding or decoding mode, regardless of file extensions. Useful for processing files with unknown or missing extensions.

```bash
# Force mode
toon -e data.txt      # Force encode
toon -d output.txt    # Force decode
```

--------------------------------

### DecodeOptions Presets: Path Expansion

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/configuration.md

Configures DecodeOptions for strict validation, type coercion, and enables safe path expansion.

```rust
DecodeOptions::new().with_expand_paths(PathExpansionMode::Safe)
```

--------------------------------

### Decoding API

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/api-reference/index.md

Offers functions and options for converting TOON format strings back into Rust values. Supports decoding with custom options, default decoding (strict + coercion), strict validation, and options for no type coercion.

```APIDOC
## Decoding API

### Description
Functions and options for converting TOON format strings to Rust values.

### Key Exports
- `decode<T>(&input, &options)` — Decode with custom options
- `decode_default<T>(&input)` — Decode with defaults (strict + coercion)
- `decode_strict<T>(&input)` — Strict validation
- `decode_strict_with_options<T>(&input, &options)` — Strict + custom
- `decode_no_coerce<T>(&input)` — No type coercion
- `decode_no_coerce_with_options<T>(&input, &options)` — No coercion + custom
- `DecodeOptions` — Configuration builder

### Layout Functions (layout feature)
- `decode_with_layout<T>(&input, &options)` — Return decoded value + metadata
```

--------------------------------

### Common Defaults Table

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/QUICKREF.md

Summary of default values for toon-format options including delimiter, indent, key folding, strictness, coercion, and path expansion.

```text
Option | Default
|--------|--------|
| `delimiter` | Comma |
| `indent` | Spaces(2) |
| `key_folding` | Off |
| `flatten_depth` | usize::MAX |
| `strict` | true |
| `coerce_types` | true |
| `expand_paths` | Off |
```

--------------------------------

### Exit REPL

Source: https://github.com/toon-format/toon-rust/blob/main/docs/TUI.md

Use the 'exit' command to close the REPL session. This is the standard way to terminate the interactive tool.

```bash
exit
```

--------------------------------

### Show Statistics During Encoding

Source: https://github.com/toon-format/toon-rust/blob/main/README.md

Activates the display of conversion statistics, including token and byte counts, along with savings percentages, after encoding a file. This helps in evaluating compression efficiency.

```bash
# Show statistics
toon data.json --stats
```

--------------------------------

### Enable Path Expansion via CLI

Source: https://github.com/toon-format/toon-rust/blob/main/README.md

Activates path expansion during decoding directly from the command line. This automatically converts dotted keys into nested JSON objects.

```bash
# Path expansion (v1.5)
toon data.toon --expand-paths
```

--------------------------------

### Decode with Default Options

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/api-reference/index.md

Decodes a TOON string into a serde_json::Value using default options. The input TOON string is provided.

```rust
use toon_format::decode_default;
use serde_json::Value;

let toon = "name: Alice\nitems[3]: 1,2,3";
let data: Value = decode_default(toon)?;
println!("{}", data["name"]);
```

--------------------------------

### Enable Path Expansion for Nested Objects

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/configuration.md

Configures TOON decoding to expand dotted keys into nested JSON objects. Supports 'Safe' expansion mode with specific safety requirements.

```rust
pub fn with_expand_paths(mut self, mode: PathExpansionMode) -> Self
```

```rust
use toon_format::{DecodeOptions, PathExpansionMode, decode};
use serde_json::Value;

let toon = "a.b.c: 1
a.b.d: 2";

// With expansion
let opts = DecodeOptions::new()
    .with_expand_paths(PathExpansionMode::Safe);
let result: Value = decode(toon, &opts)?;
// Result: {"a": {"b": {"c": 1, "d": 2}}}

// Without expansion (default)
let opts = DecodeOptions::new();
let result: Value = decode(toon, &opts)?;
// Result: {"a.b.c": 1, "a.b.d": 2}

// Quoted keys always remain literal
let toon2 = r"a.b: 1";
let opts = DecodeOptions::new()
    .with_expand_paths(PathExpansionMode::Safe);
let result: Value = decode(&format!(r"{}
"c.d": 2", toon2), &opts)?;
// Result: {"a": {"b": 1}, "c.d": 2}
```

--------------------------------

### Store Variable in REPL

Source: https://github.com/toon-format/toon-rust/blob/main/docs/TUI.md

Use the 'let' command to store data in a variable within the REPL session. This allows for easy reuse of complex data structures.

```bash
let $config = {"port": 8080}
```

--------------------------------

### Default DecodeOptions Implementation

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/configuration.md

Provides the default configuration for decoding options, including settings for delimiter, strict validation, type coercion, indentation, and path expansion.

```rust
impl Default for DecodeOptions {
    fn default() -> Self {
        Self {
            delimiter: None,           // Auto-detect
            strict: true,              // Strict validation
            coerce_types: true,        // Enable type coercion
            indent: Indent::Spaces(2), // Expect 2-space indent
            expand_paths: PathExpansionMode::Off,  // No path expansion
        }
    }
}
```

--------------------------------

### TOON Format Module Map

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/api-reference/index.md

Provides a hierarchical overview of the TOON format's Rust module structure, indicating the purpose of each module and its associated features.

```text
toon-format/
├── lib.rs                    [Public re-exports]
├── encode/
│   ├── mod.rs               [encode, encode_default, encode_object, encode_array]
│   ├── json_stream.rs       [Streaming encoding - json_stream feature]
│   ├── writer.rs            [Internal writer]
│   ├── folding.rs           [Key folding implementation]
│   └── primitives.rs        [Internal value writing]
├── decode/
│   ├── mod.rs               [decode, decode_strict, decode_no_coerce, etc.]
│   ├── parser.rs            [TOON parser]
│   ├── scanner.rs           [Tokenizer]
│   ├── validation.rs        [Validation logic]
│   ├── expansion.rs         [Path expansion implementation]
│   └── layout_builder.rs    [Layout metadata - layout feature]
├── types/
│   ├── mod.rs               [Type re-exports]
│   ├── options.rs           [EncodeOptions, DecodeOptions]
│   ├── delimiter.rs         [Delimiter enum]
│   ├── errors.rs            [ToonError, ErrorContext]
│   ├── folding.rs           [KeyFoldingMode, PathExpansionMode]
│   └── value.rs             [JsonValue, Number, Object]
├── utils/
│   ├── mod.rs               [normalize, QuotingContext]
│   ├── string.rs            [String escaping, quoting]
│   ├── literal.rs           [Type checking utilities]
│   ├── number.rs            [Number formatting]
│   └── validation.rs        [Depth validation]
├── constants.rs             [Constants and keyword checking]
├── tui/                     [Terminal UI - cli feature]
└── layout/                  [Layout metadata types - layout feature]
```

--------------------------------

### Convert and Access JsonValue

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/types.md

Demonstrates converting from a serde_json::Value and accessing elements within a JsonValue object. Requires importing JsonValue and serde_json::json.

```rust
use toon_format::types::JsonValue;
use serde_json::json;

// Convert from serde_json::Value
let serde_val = json!({"name": "Alice", "items": [1, 2, 3]});
let toon_val: JsonValue = serde_val.into();

// Type checking
assert!(toon_val.is_object());

// Access
if let Some(items) = toon_val["items"].as_array() {
    assert_eq!(items.len(), 3);
}
```

--------------------------------

### EncodeOptions Structure

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/configuration.md

Defines the configuration for encoding values to TOON format. It includes settings for delimiters, indentation, key folding, and flattening depth.

```rust
pub struct EncodeOptions {
    pub delimiter: Delimiter,
    pub indent: Indent,
    pub key_folding: KeyFoldingMode,
    pub flatten_depth: usize,
}
```

--------------------------------

### EncodeOptions Presets: Pretty Print

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/configuration.md

Configures EncodeOptions for pretty printing with a comma separator and 4-space indentation.

```rust
EncodeOptions::new().with_spaces(4)
```

--------------------------------

### Add Toon Format to Cargo.toml

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/README.md

Specify the toon-format dependency in your Cargo.toml file. Enable features like `json_stream` for streaming JSON or `layout` for decoder metadata.

```toml
[dependencies]
toon-format = "0.5"

# With streaming
toon-format = { version = "0.5", features = ["json_stream"] }

# With layout analysis
toon-format = { version = "0.5", features = ["layout"] }

# Without CLI
toon-format = { version = "0.5", default-features = false }
```

--------------------------------

### Encode JSON to TOON

Source: https://github.com/toon-format/toon-rust/blob/main/docs/TUI.md

Use the 'encode' command in the REPL to convert JSON data into the TOON format. This is useful for data compression and efficient storage.

```bash
encode {"name": "Alice"}
```

--------------------------------

### Utilities API

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/api-reference/index.md

Provides helper functions for string manipulation, validation, and normalization within the TOON format. Includes functions for escaping/unescaping strings, checking quoting requirements, and validating identifier segments.

```APIDOC
## Utilities API

### Description
Helper functions for string handling, validation, and normalization.

### String Functions
- `escape_string(&str)` — Escape special characters
- `unescape_string(&str)` — Unescape special characters
- `is_valid_unquoted_key(&str)` — Check if key needs quotes
- `needs_quoting(&str, char)` — Check if value needs quotes
- `quote_string(&str)` — Quote and escape

### Type Checking
- `is_keyword(&str)` — Check for reserved keywords
- `is_literal_like(&str)` — Check if looks like literal
- `is_structural_char(char)` — Check if structural character
- `is_identifier_segment(&str)` — Check for identifier validity

### Normalization
- `normalize(Value)` — Handle NaN, Infinity, -0
```

--------------------------------

### Encode and Decode Custom Structs with TOON

Source: https://github.com/toon-format/toon-rust/blob/main/README.md

Demonstrates encoding a custom Rust struct to TOON format and decoding it back. Ensure the struct derives Serialize and Deserialize.

```rust
use serde::{Serialize, Deserialize};
use toon_format::{encode_default, decode_default};

#[derive(Serialize, Deserialize, Debug, PartialEq)]
struct User {
    name: String,
    age: u32,
    email: String,
}

fn main() -> Result<(), toon_format::ToonError> {
    let user = User {
        name: "Alice".to_string(),
        age: 30,
        email: "alice@example.com".to_string(),
    };

    // Encode to TOON
    let toon = encode_default(&user)?;
    println!("{}", toon);
    // Output:
    // name: Alice
    // age: 30
    // email: alice@example.com

    // Decode back to struct
    let decoded: User = decode_default(&toon)?;
    assert_eq!(user, decoded);

    Ok(())
}
```

--------------------------------

### EncodeOptions Presets: Compact

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/configuration.md

Configures EncodeOptions for compact output with a comma separator and no indentation.

```rust
EncodeOptions::new().with_spaces(0)
```

--------------------------------

### Encode with Default Options

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/api-reference/index.md

Encodes a serde_json::Value into TOON format using default options. Ensure 'serde_json' is a dependency.

```rust
use toon_format::encode_default;
use serde_json::json;

let data = json!({"name": "Alice", "items": [1, 2, 3]});
let toon = encode_default(&data)?;
println!("{}", toon);
```

--------------------------------

### Encoding API

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/api-reference/index.md

Provides functions and options for converting Rust values to TOON format. Supports encoding with custom options, default encoding, and specific encoding for objects and arrays. Also includes streaming capabilities for JSON to TOON conversion.

```APIDOC
## Encoding API

### Description
Functions and options for converting Rust values to TOON format.

### Key Exports
- `encode<T>(&value, &options)` — Encode with custom options
- `encode_default<T>(&value)` — Encode with defaults
- `encode_object<V>(&value, &options)` — Encode object only
- `encode_array<V>(&value, &options)` — Encode array only
- `EncodeOptions` — Configuration builder
- `StreamingEncodeOptions` — Streaming-specific options (json_stream feature)

### Streaming Functions (json_stream feature)
- `encode_json_stream<R, W>()` — Stream JSON to TOON
- `encode_json_reader<R>()` — Stream JSON and return string
- `encode_json_stream_default<R, W>()` — Stream with defaults
- `encode_json_reader_default<R>()` — Stream reader with defaults
```

--------------------------------

### Error Handling using Display/Debug

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/errors.md

Illustrates a simple error handling approach where the `Display` implementation of `ToonError` is used to print the error message when decoding fails.

```rust
use toon_format::decode_default;

match decode_default::<serde_json::Value>("invalid") {
    Ok(v) => println!("{:?}", v),
    Err(e) => eprintln!("Error: {}", e), // Uses Display impl
}
```

--------------------------------

### decode

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/api-reference/decoding.md

Decodes a TOON format string into any type that implements `serde::Deserialize`. It accepts custom configurations via `DecodeOptions`.

```APIDOC
## decode

### Description
Decodes TOON format into any deserializable type `T`. Allows for custom decoding behavior via `DecodeOptions`.

### Method
Rust Function

### Signature
```rust
pub fn decode<T: serde::de::DeserializeOwned>(
    input: &str,
    options: &DecodeOptions
) -> ToonResult<T>
```

### Parameters
#### Arguments
- **input** (`&str`) - Required - The TOON format string to decode.
- **options** (`&DecodeOptions`) - Required - Configuration for decoding behavior including validation strictness and type coercion.

### Return Type
`ToonResult<T>` — The decoded value of type `T`, or `ToonError` on failure.

### Errors
- `ParseError` — Syntax errors with line/column information.
- `LengthMismatch` — Array length declaration doesn't match actual elements (in strict mode).
- `TypeMismatch` — Unexpected value type during deserialization.
- `DeserializationError` — Serde deserialization failure.
- `UnexpectedEof` — Input ends prematurely.
- `InvalidStructure` — Malformed TOON structure.

### Examples
```rust
use serde::Deserialize;
use toon_format::{decode, DecodeOptions};

#[derive(Deserialize, Debug)]
struct Config {
    host: String,
    port: u16,
}

let toon = "host: localhost\nport: 8080";
let config: Config = decode(toon, &DecodeOptions::default())?;
assert_eq!(config.host, "localhost");
assert_eq!(config.port, 8080);

// With JSON
use serde_json::Value;
let json: Value = decode(toon, &DecodeOptions::default())?;
assert_eq!(json["host"], "localhost");
```
```

--------------------------------

### Clear Output in REPL

Source: https://github.com/toon-format/toon-rust/blob/main/docs/TUI.md

Use the 'clear' command to clear the output screen in the REPL. This helps in maintaining a clean workspace.

```bash
clear
```

--------------------------------

### encode

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/api-reference/encoding.md

Encodes any serializable value to a TOON format string with customizable options.

```APIDOC
## encode

### Description
Encode any serializable value to TOON format string.

### Method
Rust Function

### Signature
```rust
pub fn encode<T: serde::Serialize>(
    value: &T,
    options: &EncodeOptions
) -> ToonResult<String>
```

### Parameters
#### Value Parameter
- **value** (`&T` where `T: Serialize`) - Required - The value to encode. Works with custom structs, JSON values, collections, and primitives.

#### Options Parameter
- **options** (`&EncodeOptions`) - Required - Configuration for encoding behavior including delimiter, indentation, and key folding.

### Return Type
`ToonResult<String>` — A string in TOON format, or `ToonError` on failure.

### Errors
- `SerializationError` — If the value cannot be serialized.
- `InvalidStructure` — If the nested structure exceeds maximum depth.

### Examples
```rust
use serde::Serialize;
use toon_format::{encode, EncodeOptions};

#[derive(Serialize)]
struct User {
    name: String,
    age: u32,
}

let user = User {
    name: "Alice".to_string(),
    age: 30,
};

// Encode with default options
let toon = encode(&user, &EncodeOptions::default())?;
assert!(toon.contains("name: Alice"));

// Encode with custom delimiter
let opts = EncodeOptions::new()
    .with_delimiter(toon_format::Delimiter::Pipe);
let toon_pipe = encode(&user, &opts)?;

// Works with JSON
use serde_json::json;
let data = json!({"items": ["a", "b", "c"]});
let toon = encode(&data, &EncodeOptions::default())?;
```
```

--------------------------------

### Decode TOON to JSON (Strict Mode)

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/usage-patterns.md

Parse a TOON format string into a serde_json::Value using default decoding options.

```rust
use serde_json::Value;
use toon_format::decode_default;

let toon = "user: Alice\nage: 30\nactive: true";
let data: Value = decode_default(toon)?;

println!("User: {}", data["user"]);  // Alice
println!("Age: {}", data["age"]);    // 30
```

--------------------------------

### Toon Format Constants

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/README.md

Overview of constants defined in the toon-format crate, including maximum nesting depth, default indentation, default delimiter, structural characters, and keywords.

```rust
pub const MAX_DEPTH: usize = 256;              // Max nesting (stack safety)
pub const DEFAULT_INDENT: usize = 2;           // Default indent spaces
pub const DEFAULT_DELIMITER: Delimiter = Comma; // Default separator
pub const STRUCTURAL_CHARS: &[char] = &['[', ']', '{', '}', ':', '-'];
pub const KEYWORDS: &[&str] = &["null", "true", "false"];
```

--------------------------------

### Set Spaces Indentation

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/configuration.md

A convenience method to set indentation using a specific number of spaces. This is equivalent to using `with_indent` with `Indent::Spaces`.

```rust
use toon_format::EncodeOptions;

let opts = EncodeOptions::new().with_spaces(4);
// Equivalent to .with_indent(Indent::Spaces(4))
```

--------------------------------

### TOON Error Handling

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/api-reference/index.md

Demonstrates how to handle potential errors during TOON decoding, specifically catching LengthMismatch errors and other ToonError variants.

```rust
use toon_format::{decode_default, ToonError};
use serde_json::Value;

match decode_default::<Value>("invalid") {
    Ok(data) => println!("{:?}", data),
    Err(ToonError::LengthMismatch { expected, found, .. }) => {
        eprintln!("Length: expected {}, found {}", expected, found);
    }
    Err(e) => eprintln!("Error: {}", e),
}
```

--------------------------------

### Compact Encoding

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/usage-patterns.md

Minimize the output size of TOON data by using compact encoding options. This is achieved by removing unnecessary whitespace and applying key folding.

```rust
use toon_format::{encode, EncodeOptions, KeyFoldingMode};
use serde_json::json;

let data = json!({"data": {"values": [1, 2, 3]}});

let opts = EncodeOptions::new()
    .with_spaces(0)  // No indentation
    .with_key_folding(KeyFoldingMode::Safe);

let toon = encode(&data, &opts)?;
println!("{}", toon);
// Compact output on minimal lines
```

--------------------------------

### Decode TOON with Default Options

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/api-reference/decoding.md

Use `decode_default` for a quick decode using default settings: strict mode and type coercion enabled. This is suitable for common use cases where strict validation is desired.

```rust
use serde_json::json;
use toon_format::decode_default;

let toon = "items[2]: a,b";
let json = decode_default(toon)?;
// Strict mode enforces array length matches actual elements
```

--------------------------------

### EncodeOptions Default Values

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/configuration.md

Shows the default configuration for `EncodeOptions`, which uses comma delimiters, 2-space indentation, no key folding, and unlimited flattening depth.

```rust
impl Default for EncodeOptions {
    fn default() -> Self {
        Self {
            delimiter: Delimiter::Comma,
            indent: Indent::Spaces(2),
            key_folding: KeyFoldingMode::Off,
            flatten_depth: usize::MAX,
        }
    }
}
```

--------------------------------

### Normalization Utility

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/QUICKREF.md

Normalize numeric values, converting NaN and Infinity to null, and -0 to 0.

```rust
// Normalization
normalize(value)                 // NaN → null, ∞ → null, -0 → 0
```

--------------------------------

### DecodeOptions Constructor

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/configuration.md

Creates a new DecodeOptions instance with default settings. Defaults include strict validation and type coercion enabled.

```rust
impl DecodeOptions {
    pub fn new() -> Self  // Creates with defaults (strict + coercion)
}
```

--------------------------------

### Decode TOON to Any Deserializable Type

Source: https://github.com/toon-format/toon-rust/blob/main/_autodocs/api-reference/decoding.md

Use `decode` for general TOON string parsing into any type that implements `serde::Deserialize`. It accepts custom configurations via `DecodeOptions`.

```rust
use serde::Deserialize;
use toon_format::{decode, DecodeOptions};

#[derive(Deserialize, Debug)]
struct Config {
    host: String,
    port: u16,
}

let toon = "host: localhost\nport: 8080";
let config: Config = decode(toon, &DecodeOptions::default())?;
assert_eq!(config.host, "localhost");
assert_eq!(config.port, 8080);

// With JSON
use serde_json::Value;
let json: Value = decode(toon, &DecodeOptions::default())?;
assert_eq!(json["host"], "localhost");
```