### Install @toon-format/cli

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

Install the CLI globally using npm, pnpm, or yarn. Alternatively, use npx for direct execution without global installation.

```bash
npm install -g @toon-format/cli
```

```bash
pnpm add -g @toon-format/cli
```

```bash
yarn global add @toon-format/cli
```

```bash
npx @toon-format/cli [options] [input]
```

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

### Install @toon-format/toon with yarn

Source: https://github.com/toon-format/toon/blob/main/docs/reference/api.md

Install the package using yarn.

```bash
yarn add @toon-format/toon
```

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

### Install @toon-format/toon with pnpm

Source: https://github.com/toon-format/toon/blob/main/docs/reference/api.md

Install the package using pnpm.

```bash
pnpm add @toon-format/toon
```

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

### Install @toon-format/toon with npm

Source: https://github.com/toon-format/toon/blob/main/docs/reference/api.md

Install the package using npm.

```bash
npm install @toon-format/toon
```

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

### Install @toon-format/cli globally with pnpm

Source: https://github.com/toon-format/toon/blob/main/docs/cli/index.md

Install the CLI package globally using pnpm for repeated use.

```bash
pnpm add -g @toon-format/cli
```

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

### Install @toon-format/cli globally with npm

Source: https://github.com/toon-format/toon/blob/main/docs/cli/index.md

Install the CLI package globally using npm for repeated use.

```bash
npm install -g @toon-format/cli
```

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

### Install @toon-format/cli globally with yarn

Source: https://github.com/toon-format/toon/blob/main/docs/cli/index.md

Install the CLI package globally using yarn for repeated use.

```bash
yarn global add @toon-format/cli
```

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

### Install TOON CLI Globally

Source: https://github.com/toon-format/toon/blob/main/docs/guide/getting-started.md

Install the TOON CLI globally using npm, pnpm, or yarn for command-line use.

```bash
npm install -g @toon-format/cli
```

```bash
pnpm add -g @toon-format/cli
```

```bash
yarn global add @toon-format/cli
```

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

### Install TOON TypeScript Library

Source: https://github.com/toon-format/toon/blob/main/docs/guide/getting-started.md

Install the TOON TypeScript library using npm, pnpm, or yarn.

```bash
npm install @toon-format/toon
```

```bash
pnpm add @toon-format/toon
```

```bash
yarn add @toon-format/toon
```

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

### Install TOON VS Code Extension

Source: https://github.com/toon-format/toon/blob/main/docs/ecosystem/tools-and-playgrounds.md

Install the TOON Language Support extension for VS Code via the command line.

```bash
code --install-extension vishalraut.vscode-toon
```

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

### Set Up API Keys

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

Copy the example environment file to `.env` and populate it with your necessary API keys before running benchmarks that require external model access.

```bash
cp .env.example .env
```

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

### CLI Conversion Example

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

Demonstrates converting JSON to TOON using the TOON CLI and piping data via stdin.

```bash
# Convert JSON to TOON
npx @toon-format/cli input.json -o output.toon

# Pipe from stdin
echo '{"name": "Ada", "role": "dev"}' | npx @toon-format/cli
```

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

### Basic Key Folding Example

Source: https://github.com/toon-format/toon/blob/main/docs/guide/format-overview.md

Illustrates standard nested object structure in TOON.

```yaml
data:
  metadata:
    items[2]: a,b
```

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

### Use TOON CLI without Installation

Source: https://github.com/toon-format/toon/blob/main/docs/guide/getting-started.md

Execute the TOON CLI command using npx without needing to install it globally.

```bash
npx @toon-format/cli input.json -o output.toon
```

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

### YAML Example

Source: https://github.com/toon-format/toon/blob/main/docs/guide/getting-started.md

A YAML representation demonstrating indentation for structure, reducing redundancy compared to JSON.

```yaml
users:
  - id: 1
    name: Alice
    role: admin
  - id: 2
    name: Bob
    role: user
```

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

### TOON Example

Source: https://github.com/toon-format/toon/blob/main/docs/guide/getting-started.md

TOON format representing the same data as JSON and YAML, but with declared structure and row-based data for compactness.

```yaml
users[2]{id,name,role}:
  1,Alice,admin
  2,Bob,user
```

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

### Simple Object Example

Source: https://github.com/toon-format/toon/blob/main/docs/guide/format-overview.md

Represents a simple TOON object with primitive values. Each key-value pair is on a new line, with a single space after the colon.

```yaml
id: 123
name: Ada
active: true
```

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

### TOON Array Delimiter Examples

Source: https://github.com/toon-format/toon/blob/main/docs/guide/format-overview.md

Demonstrates the use of comma, tab, and pipe delimiters within TOON array headers and data.

```yaml
items[2]{sku,name,qty,price}:
  A1,Widget,2,9.99
  B2,Gadget,1,14.5
```

```yaml
items[2	]{sku	name	qty	price}:
  A1	Widget	2	9.99
  B2	Gadget	1	14.5
```

```yaml
items[2|]{sku|name|qty|price}:
  A1|Widget|2|9.99
  B2|Gadget|1|14.5
```

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

### Example TOON Input Prompt

Source: https://github.com/toon-format/toon/blob/main/docs/guide/llm-prompts.md

Demonstrates how to include TOON data within a prompt for an LLM. Labeling the code block as 'toon' helps models recognize the format.

```markdown
Data is in TOON format (2-space indent, arrays show length and fields).

```toon
users[3]{id,name,role,lastLogin}:
  1,Alice,admin,"2025-01-15T10:30:00Z"
  2,Bob,user,"2025-01-14T15:22:00Z"
  3,Charlie,user,"2025-01-13T09:45:00Z"
```

Task: Summarize the user roles and their last activity.
```

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

### Complex JSON Example

Source: https://github.com/toon-format/toon/blob/main/docs/guide/getting-started.md

The JSON equivalent of the complex TOON example, illustrating its verbosity for uniform arrays.

```json
{
  "context": {
    "task": "Our favorite hikes together",
    "location": "Boulder",
    "season": "spring_2025"
  },
  "friends": ["ana", "luis", "sam"],
  "hikes": [
    {
      "id": 1,
      "name": "Blue Lake Trail",
      "distanceKm": 7.5,
      "elevationGain": 320,
      "companion": "ana",
      "wasSunny": true
    },
    {
      "id": 2,
      "name": "Ridge Overlook",
      "distanceKm": 9.2,
      "elevationGain": 540,
      "companion": "luis",
      "wasSunny": false
    },
    {
      "id": 3,
      "name": "Wildflower Loop",
      "distanceKm": 5.1,
      "elevationGain": 180,
      "companion": "sam",
      "wasSunny": true
    }
  ]
}
```

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

### Tab Delimited Data Example

Source: https://github.com/toon-format/toon/blob/main/docs/reference/api.md

Illustrates data structured with tab characters as delimiters, suitable for efficient tokenization.

```yaml
items[2	]{sku	name	qty	price}:
  A1	Widget	2	9.99
  B2	Gadget	1	14.5
```

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

### Example TOON Output from LLM

Source: https://github.com/toon-format/toon/blob/main/docs/guide/llm-prompts.md

Illustrates the expected TOON output from an LLM when prompted to filter data. The array length `[N]` is correctly adjusted.

```toon
users[2]{id,name,role,lastLogin}:
  2,Bob,user,"2025-01-14T15:22:00Z"
  3,Charlie,user,"2025-01-13T09:45:00Z"
```

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

### Time-series Analytics Data TOON Example

Source: https://github.com/toon-format/toon/blob/main/benchmarks/results/token-efficiency.md

Example of time-series analytics data represented in TOON format. This format is optimized for token efficiency.

```text
metrics[5]{date,views,clicks,conversions,revenue,bounceRate}:
  2025-01-01,6138,174,12,2712.49,0.35
  2025-01-02,4616,274,34,9156.29,0.56
  2025-01-03,4460,143,8,1317.98,0.59
  2025-01-04,4740,125,13,2934.77,0.37
  2025-01-05,6428,369,19,1317.24,0.3
```

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

### Basic Tabular Array Example

Source: https://github.com/toon-format/toon/blob/main/docs/guide/format-overview.md

Illustrates a basic tabular array format for objects with the same set of primitive keys. The header defines the array length and field names.

```yaml
items[2]{sku,qty,price}:
  A1,2,9.99
  B2,1,14.5
```

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

### Complex TOON Example

Source: https://github.com/toon-format/toon/blob/main/docs/guide/getting-started.md

Demonstrates TOON's ability to handle mixed data structures, including nested objects, primitive arrays, and tabular arrays.

```yaml
context:
  task: Our favorite hikes together
  location: Boulder
  season: spring_2025
friends[3]: ana,luis,sam
hikes[3]{id,name,distanceKm,elevationGain,companion,wasSunny}:
  1,Blue Lake Trail,7.5,320,ana,true
  2,Ridge Overlook,9.2,540,luis,false
  3,Wildflower Loop,5.1,180,sam,true
```

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

### Mixed Array Example

Source: https://github.com/toon-format/toon/blob/main/docs/guide/format-overview.md

Shows a mixed array containing different types of elements, including primitives and objects. Hyphen markers indicate list items.

```yaml
items[3]:
  - 1
  - a: 1
  - text
```

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

### Encode data to TOON format with example

Source: https://github.com/toon-format/toon/blob/main/docs/reference/api.md

Demonstrates encoding a list of items into TOON format. The output shows the structure with keys and nested data.

```typescript
import { encode } from '@toon-format/toon'

const items = [
  { sku: 'A1', qty: 2, price: 9.99 },
  { sku: 'B2', qty: 1, price: 14.5 }
]

console.log(encode({ items }))
```

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

### Decode TOON to JSON using npx

Source: https://github.com/toon-format/toon/blob/main/docs/cli/index.md

Run the CLI without global installation to decode a TOON file back to JSON format.

```bash
npx @toon-format/cli data.toon -o output.json
```

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

### TOON Key Folding Example

Source: https://github.com/toon-format/toon/blob/main/docs/reference/syntax-cheatsheet.md

Demonstrates TOON's key folding feature, where nested keys are represented using dot notation instead of indentation. This is an optional feature for more compact representations.

```yaml
data:
  metadata:
    items[2]: a,b
```

```yaml
data.metadata.items[2]: a,b
```

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

### Empty Array Example

Source: https://github.com/toon-format/toon/blob/main/docs/guide/format-overview.md

Represents an empty array. For fields, it's shown as 'key: []'. An empty root array is represented as '[]'.

```yaml
items: []
```

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

### JSON Example

Source: https://github.com/toon-format/toon/blob/main/docs/guide/getting-started.md

A standard JSON representation of nested objects, a primitive array, and a uniform array of objects.

```json
{
  "users": [
    { "id": 1, "name": "Alice", "role": "admin" },
    { "id": 2, "name": "Bob", "role": "user" }
  ]
}
```

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

### Array Element as Object

Source: https://github.com/toon-format/toon/blob/main/docs/guide/format-overview.md

Illustrates an array where elements are objects. Each object is represented as a list item starting with a hyphen.

```yaml
items[2]:
  - id: 1
    name: First
  - id: 2
    name: Second
    extra: true
```

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

### Combined Toon CLI Options

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

Utilize multiple Toon CLI options simultaneously, such as key folding, custom delimiters, and statistics gathering. This example uses tab as a delimiter and enables stats.

```bash
# Key folding + tab delimiter + stats
toon data.json --keyFolding safe --delimiter $'	' --stats -o output.toon
```

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

### Nested Object Example

Source: https://github.com/toon-format/toon/blob/main/docs/guide/format-overview.md

Demonstrates a nested object structure in TOON. Indentation signifies nesting, with nested fields appearing at a deeper indentation level.

```yaml
user:
  id: 123
  name: Ada
```

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

### Primitive Array Inline Example

Source: https://github.com/toon-format/toon/blob/main/docs/guide/format-overview.md

Shows an array of primitive values rendered inline. Values are separated by a delimiter (comma by default). Strings containing the delimiter must be quoted.

```yaml
tags[3]: admin,ops,dev
```

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

### Prompt LLM with TOON Input and Validate Response

Source: https://github.com/toon-format/toon/blob/main/docs/guide/llm-prompts.md

This example demonstrates sending TOON formatted data to an LLM and then validating the model's TOON output using `decode` with strict validation.

```markdown
System logs in TOON format (tab-separated):

```toon
events[4\t]{id\tlevel\tmessage\ttimestamp}:
  1\terror\tConnection timeout\t"2025-01-15T10:00:00Z"
  2\twarn\tSlow query\t"2025-01-15T10:05:00Z"
  3\tinfo\tUser login\t"2025-01-15T10:10:00Z"
  4\terror\tDatabase error\t"2025-01-15T10:15:00Z"
```

Task: Return only error-level events as TOON. Use the same format.
```

```typescript
import { decode } from '@toon-format/toon'

const modelResponse = "
events[2\t]{id\tlevel\tmessage\ttimestamp}:
  1\terror\tConnection timeout\t\"2025-01-15T10:00:00Z\"
  4\terror\tDatabase error\t\"2025-01-15T10:15:00Z\"
"

const filtered = decode(modelResponse, { strict: true })
// ✓ Validated – model correctly filtered and adjusted [N] to 2
```

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

### Dry Run Retrieval Accuracy Benchmark

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

Perform a dry run of the retrieval accuracy benchmark using only 10 questions for quick testing of your setup. Set the `DRY_RUN` environment variable to `true`.

```bash
DRY_RUN=true pnpm benchmark:accuracy
```

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

### Basic CLI Usage

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

Run the toon CLI with options and an input file. Omit the input argument or use '-' to read from standard input.

```bash
toon [options] [input]
```

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

### Time-series Analytics Data JSON Example

Source: https://github.com/toon-format/toon/blob/main/benchmarks/results/token-efficiency.md

Example of time-series analytics data represented in JSON format. This format is used for comparison with the TOON format.

```json
{
  "metrics": [
    {
      "date": "2025-01-01",
      "views": 6138,
      "clicks": 174,
      "conversions": 12,
      "revenue": 2712.49,
      "bounceRate": 0.35
    },
    {
      "date": "2025-01-02",
      "views": 4616,
      "clicks": 274,
      "conversions": 34,
      "revenue": 9156.29,
      "bounceRate": 0.56
    },
    {
      "date": "2025-01-03",
      "views": 4460,
      "clicks": 143,
      "conversions": 8,
      "revenue": 1317.98,
      "bounceRate": 0.59
    },
    {
      "date": "2025-01-04",
      "views": 4740,
      "clicks": 125,
      "conversions": 13,
      "revenue": 2934.77,
      "bounceRate": 0.37
    },
    {
      "date": "2025-01-05",
      "views": 6428,
      "clicks": 369,
      "conversions": 19,
      "revenue": 1317.24,
      "bounceRate": 0.3
    }
  ]
}
```

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

### Combined Options for Maximum Efficiency

Source: https://github.com/toon-format/toon/blob/main/docs/cli/index.md

Shows how to combine multiple TOON CLI options, including key folding, tab delimiter, and statistics reporting, for maximum token efficiency during encoding.

```bash
toon data.json --keyFolding safe --delimiter $'	' --stats -o output.toon
```

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

### Prompt for Generating TOON Output

Source: https://github.com/toon-format/toon/blob/main/docs/guide/llm-prompts.md

Shows how to instruct an LLM to generate TOON data. Explicitly stating the header format and rules helps the model produce correct output.

```markdown
Data is in TOON format (2-space indent, arrays show length and fields).

```toon
users[3]{id,name,role,lastLogin}:
  1,Alice,admin,"2025-01-15T10:30:00Z"
  2,Bob,user,"2025-01-14T15:22:00Z"
  3,Charlie,user,"2025-01-13T09:45:00Z"
```

Task: Return only users with role "user" as TOON. Use the same header format. Set [N] to match the row count. Output only the code block.
```

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

### Encode JSON to TOON via stdin using npx

Source: https://github.com/toon-format/toon/blob/main/docs/cli/index.md

Pipe JSON data to the CLI via stdin for encoding when not installed globally.

```bash
echo '{"name": "Ada"}' | npx @toon-format/cli
```

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

### Process Large Dataset with Streaming

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

Read a large JSON dataset from a file, convert it to TOON using a tab delimiter, and stream the output to a file with minimal memory usage.

```bash
cat large-dataset.json | toon --delimiter $'	' > output.toon
```

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

### Deeply Nested Configuration (TOON vs JSON)

Source: https://github.com/toon-format/toon/blob/main/benchmarks/results/token-efficiency.md

Compares token counts for deeply nested configurations between TOON and various JSON formats. TOON is more token-efficient than standard JSON.

```text
🧩 Deeply nested configuration  ┊  Tabular: 0%
   │
   TOON                ██████████████░░░░░░       620 tokens
   ├─ vs JSON          (−31.9%)                   911 tokens
   ├─ vs JSON compact  (+11.1%)                   558 tokens
   ├─ vs YAML          (−6.3%)                    662 tokens
   └─ vs XML           (−38.2%)                 1,003 tokens
```

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

### Run Retrieval Accuracy Benchmark

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

Initiate the retrieval accuracy benchmark, which tests LLM performance on data in different formats. This benchmark requires API keys to be set up in the `.env` file.

```bash
pnpm benchmark:accuracy
```

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

### TOON Unicode and Emoji Example

Source: https://github.com/toon-format/toon/blob/main/docs/reference/syntax-cheatsheet.md

Demonstrates that TOON supports unquoted strings containing Unicode characters and emoji, provided they do not violate other quoting rules.

```yaml
message: Hello 世界 👋
note: This has inner spaces
```

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

### Top GitHub Repositories (CSV vs TOON)

Source: https://github.com/toon-format/toon/blob/main/benchmarks/results/token-efficiency.md

Compares token counts for GitHub repository data between CSV and TOON. TOON uses slightly more tokens than CSV.

```text
⭐ Top 100 GitHub repositories  ┊  Tabular: 100%
   │
   CSV                 ███████████████████░     8,512 tokens
   TOON                ████████████████████     8,744 tokens   (+2.7% vs CSV)
   ├─ vs JSON          (−42.3%)                15,144 tokens
   ├─ vs JSON compact  (−23.7%)                11,454 tokens
   ├─ vs YAML          (−33.4%)                13,128 tokens
   └─ vs XML           (−48.9%)                17,095 tokens
```

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

### Benchmark Comparison: Flat-Only Track

Source: https://github.com/toon-format/toon/blob/main/docs/guide/benchmarks.md

Compares token counts for CSV and Toon against JSON, YAML, and XML for uniform employee records, time-series analytics, and GitHub repositories. Shows percentage differences and token counts.

```text
👥 Uniform employee records  ┊  Tabular: 100%
   │
   CSV                 ███████████████████░    47,102 tokens
   TOON                ████████████████████    49,919 tokens   (+6.0% vs CSV)
   ├─ vs JSON          (−60.7%)               127,063 tokens
   ├─ vs JSON compact  (−36.9%)                79,059 tokens
   ├─ vs YAML          (−50.1%)               100,011 tokens
   └─ vs XML           (−65.9%)               146,579 tokens

📈 Time-series analytics data  ┊  Tabular: 100%
   │
   CSV                 ██████████████████░░     8,383 tokens
   TOON                ████████████████████     9,115 tokens   (+8.7% vs CSV)
   ├─ vs JSON          (−59.0%)                22,245 tokens
   ├─ vs JSON compact  (−35.9%)                14,211 tokens
   ├─ vs YAML          (−49.0%)                17,858 tokens
   └─ vs XML           (−65.8%)                26,616 tokens

⭐ Top 100 GitHub repositories  ┊  Tabular: 100%
   │
   CSV                 ███████████████████░     8,512 tokens
   TOON                ████████████████████     8,744 tokens   (+2.7% vs CSV)
   ├─ vs JSON          (−42.3%)                15,144 tokens
   ├─ vs JSON compact  (−23.7%)                11,454 tokens
   ├─ vs YAML          (−33.4%)                13,128 tokens
   └─ vs XML           (−48.9%)                17,095 tokens

──────────────────────────────────── Total ────────────────────────────────────
   CSV                 ███████████████████░    63,997 tokens
   TOON                ████████████████████    67,778 tokens   (+5.9% vs CSV)
   ├─ vs JSON          (−58.8%)               164,452 tokens
   ├─ vs JSON          (−58.8%)               164,452 tokens
   ├─ vs JSON compact  (−35.3%)               104,724 tokens
   ├─ vs YAML          (−48.3%)               130,997 tokens
   └─ vs XML           (−64.4%)               190,290 tokens
```

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

### Run Token Efficiency Benchmark

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

Execute the token efficiency benchmark to measure token count reduction across various formats. Results are saved to `results/token-efficiency.md`.

```bash
pnpm benchmark:tokens
```

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

### Limit Key Folding Depth

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

Control the maximum depth of key folding during encoding to manage token reduction. This example folds a maximum of 2 levels deep.

```bash
# Fold maximum 2 levels deep
toon input.json --keyFolding safe --flattenDepth 2 -o output.toon
```

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

### Total Token Comparison (TOON vs JSON)

Source: https://github.com/toon-format/toon/blob/main/benchmarks/results/token-efficiency.md

Aggregated token comparison for all dataset types between TOON and various JSON formats. TOON demonstrates overall token efficiency.

```text
──────────────────────────────────── Total ────────────────────────────────────
   TOON                ████████████████░░░░   227,830 tokens
   ├─ vs JSON          (−21.9%)               291,711 tokens
   ├─ vs JSON compact  (+14.7%)               198,546 tokens
   ├─ vs YAML          (−5.7%)                241,474 tokens
   └─ vs XML           (−31.0%)               330,206 tokens
```

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

### Round-trip Workflow with Folding and Expansion

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

Perform a complete round-trip conversion: encode with key folding, then decode with path expansion to restore the original structure. Verify the integrity of the round-trip using a diff command.

```bash
# Encode with folding
toon input.json --keyFolding safe -o compressed.toon

# Decode with expansion (restores original structure)
toon compressed.toon --expandPaths safe -o output.json

# Verify round-trip
diff input.json output.json
```

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

### Stream large dataset to file using encodeLines

Source: https://github.com/toon-format/toon/blob/main/docs/reference/api.md

Example of streaming a large dataset to a file using encodeLines with tab delimiters. This method avoids loading the entire dataset into memory.

```typescript
import { createWriteStream } from 'node:fs'
import { encodeLines } from '@toon-format/toon'

const data = {
  items: Array.from({ length: 100000 }, (_, i) => ({
    id: i,
    name: `Item ${i}`,
    value: Math.random()
  }))
}

// Stream large dataset to file
const stream = createWriteStream('output.toon')
for (const line of encodeLines(data, { delimiter: '\t' })) {
  stream.write(`${line}\n`)
}
stream.end()
```

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

### Semi-uniform Event Logs (TOON vs JSON)

Source: https://github.com/toon-format/toon/blob/main/benchmarks/results/token-efficiency.md

Compares token counts for semi-uniform event logs between TOON and various JSON formats. TOON shows a moderate reduction compared to standard JSON.

```text
🧾 Semi-uniform event logs  ┊  Tabular: 50%
   │
   TOON                █████████████████░░░   154,084 tokens
   ├─ vs JSON          (−15.0%)               181,201 tokens
   ├─ vs JSON compact  (+19.9%)               128,529 tokens
   ├─ vs YAML          (−0.8%)                155,397 tokens
   └─ vs XML           (−25.2%)               205,859 tokens
```

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

### Show Token Savings with TOON CLI

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

Use the TOON CLI with the --stats flag to display token savings information for a given JSON file.

```bash
npx @toon-format/cli data.json --stats
```

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

### Key Folding Applied

Source: https://github.com/toon-format/toon/blob/main/docs/guide/format-overview.md

Shows how key folding collapses nested objects into a single dotted path.

```yaml
data.metadata.items[2]: a,b
```

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

### Import Delimiters and Defaults

Source: https://github.com/toon-format/toon/blob/main/docs/reference/api.md

Imports default delimiter and available delimiter configurations from the TOON library. Useful for understanding or customizing delimiter usage.

```typescript
import { DEFAULT_DELIMITER, DELIMITERS } from '@toon-format/toon'

DEFAULT_DELIMITER // ','
DELIMITERS // { comma: ',', tab: '	', pipe: '|' }
```

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

### Semi-uniform Event Logs Token Comparison

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

Compares token counts for semi-uniform event logs in TOON format against JSON, compact JSON, YAML, and XML. Demonstrates TOON's performance with semi-uniform data.

```text
🧾 Semi-uniform event logs  ┊  Tabular: 50%
   │
   TOON                █████████████████░░░   154,084 tokens
   ├─ vs JSON          (−15.0%)               181,201 tokens
   ├─ vs JSON compact  (+19.9%)               128,529 tokens
   ├─ vs YAML          (−0.8%)                155,397 tokens
   └─ vs XML           (−25.2%)               205,859 tokens
```

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

### Convert JSON to TOON using CLI

Source: https://github.com/toon-format/toon/blob/main/docs/ecosystem/tools-and-playgrounds.md

Use the TOON CLI to convert JSON input files to TOON format and display statistics.

```bash
npx @toon-format/cli input.json --stats -o output.toon
```

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

### Deeply Nested Configuration Token Comparison

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

Compares token counts for deeply nested configurations in TOON format against JSON, compact JSON, YAML, and XML. Useful for assessing TOON's efficiency with highly nested data.

```text
🧩 Deeply nested configuration  ┊  Tabular: 0%
   │
   TOON                ██████████████░░░░░░       620 tokens
   ├─ vs JSON          (−31.9%)                   911 tokens
   ├─ vs JSON compact  (+11.1%)                   558 tokens
   ├─ vs YAML          (−6.3%)                    662 tokens
   └─ vs XML           (−38.2%)                 1,003 tokens
```

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

### Performance by Dataset: E-commerce Orders

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

Compares accuracy and token usage for TOON, JSON (compact and pretty), YAML, and XML on e-commerce orders with nested structures.

```markdown
| Format | Accuracy | Tokens | Correct/Total |
| ------ | -------- | ------ | ------------- |
| `toon` | 82.3% | 7,458 | 135/164 |
| `json-compact` | 78.7% | 7,110 | 129/164 |
| `yaml` | 79.9% | 8,755 | 131/164 |
| `json-pretty` | 79.3% | 11,234 | 130/164 |
| `xml` | 77.4% | 12,649 | 127/164 |
```

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

### Top 100 GitHub Repositories Token Comparison

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

Compares token counts for top GitHub repositories data in CSV, TOON, JSON, compact JSON, YAML, and XML. Shows TOON's efficiency for tabular data like repository lists.

```text
⭐ Top 100 GitHub repositories  ┊  Tabular: 100%
   │
   CSV                 ███████████████████░     8,512 tokens
   TOON                ████████████████████     8,744 tokens   (+2.7% vs CSV)
   ├─ vs JSON          (−42.3%)                15,144 tokens
   ├─ vs JSON compact  (−23.7%)                11,454 tokens
   ├─ vs YAML          (−33.4%)                13,128 tokens
   └─ vs XML           (−48.9%)                17,095 tokens
```

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

### CLI Streaming for JSON to TOON Conversion

Source: https://github.com/toon-format/toon/blob/main/docs/guide/llm-prompts.md

The TOON CLI supports streaming for memory-efficient conversion of JSON files to TOON format.

```bash
toon large-dataset.json -o output.toon
```

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

### Performance by Dataset: Top 100 GitHub Repositories

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

Compares accuracy and token usage for TOON, CSV, JSON (compact and pretty), YAML, and XML on data for the top 100 GitHub repositories.

```markdown
| Format | Accuracy | Tokens | Correct/Total |
| ------ | -------- | ------ | ------------- |
| `csv` | 65.9% | 8,527 | 87/132 |
| `toon` | 66.7% | 8,779 | 88/132 |
| `yaml` | 65.2% | 13,141 | 86/132 |
| `json-compact` | 59.8% | 11,464 | 79/132 |
| `json-pretty` | 63.6% | 15,157 | 84/132 |
| `xml` | 56.1% | 17,105 | 74/132 |
```

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

### Show Token Statistics

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

Encode a JSON file to TOON and display token count estimates and savings. This helps in analyzing the compression efficiency of TOON.

```bash
toon data.json --stats -o output.toon
```

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

### Output to Standard Output

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

Encode a JSON file to TOON and print the result directly to standard output.

```bash
toon input.json
```

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

### Total Flat-Only Token Comparison (CSV vs TOON)

Source: https://github.com/toon-format/toon/blob/main/benchmarks/results/token-efficiency.md

Aggregated token comparison for flat-only datasets between CSV and TOON. TOON shows a modest increase in token usage compared to CSV.

```text
──────────────────────────────────── Total ────────────────────────────────────
   CSV                 ███████████████████░    63,997 tokens
   TOON                ████████████████████    67,778 tokens   (+5.9% vs CSV)
   ├─ vs JSON          (−58.8%)               164,452 tokens
   ├─ vs JSON compact  (−35.3%)               104,724 tokens
   ├─ vs YAML          (−48.3%)               130,997 tokens
   └─ vs XML           (−64.4%)               190,290 tokens
```

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

### Round-Trip with Path Expansion

Source: https://github.com/toon-format/toon/blob/main/docs/guide/format-overview.md

Demonstrates encoding with key folding and decoding with path expansion to restore nested structures.

```typescript
import { decode, encode } from '@toon-format/toon'

const original = { data: { metadata: { items: ['a', 'b'] } } }

// Encode with folding
const toon = encode(original, { keyFolding: 'safe' })
// → "data.metadata.items[2]: a,b"

// Decode with expansion
const restored = decode(toon, { expandPaths: 'safe' })
// → { data: { metadata: { items: ['a', 'b'] } } }
```

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

### Decode with Path Expansion

Source: https://github.com/toon-format/toon/blob/main/docs/reference/api.md

Demonstrates how path expansion reconstructs nested objects from a flattened TOON string. This is the inverse operation of key folding.

```typescript
import { decode } from '@toon-format/toon'

const toon = 'data.metadata.items[2]: a,b'

const data = decode(toon, { expandPaths: 'safe' })
console.log(data)
// { data: { metadata: { items: ['a', 'b'] } } }
```

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

### Output TOON CLI Conversion to Stdout

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

Direct the output of the TOON CLI conversion to standard output.

```bash
npx @toon-format/cli input.json
```