Command-Line Options - TOON JSON Converter

Overview

The TOON JSON Converter provides separate option sets for encoding (JSON → TOON) and decoding (TOON → JSON) operations.

Important: Encoding options only apply when converting TO TOON format. Decoding options only apply when converting TO JSON format.

General Options

Output Path

-o, --output

string

Specify the output file or folder path.Default: Auto-generated based on input filenameApplies to: All conversion modesSource: toon_json_converter.py:1204-1210

Usage

# Using short flag
python toon_json_converter.py input.json -o custom_output.toon

# Using long flag
python toon_json_converter.py input.toon --output result.json

# Positional argument (alternative)
python toon_json_converter.py input.json output.toon

Auto-Generated Paths

When output is omitted, the converter generates the path automatically:

Input Pattern	Generated Output	Example
`*.json`	`*.toon`	`data.json` → `data.toon`
`*.jsonl`	`*_toons/`	`logs.jsonl` → `logs_toons/`
`*.toon`	`*.json`	`config.toon` → `config.json`
`folder/`	`folder.jsonl`	`data_toons/` → `data_toons.jsonl`

Source reference: toon_json_converter.py:1061-1076

Encoding Options (JSON → TOON)

These options control how JSON data is encoded into TOON format.

Delimiter Options

--tab

flag

Use tab (\t) as the delimiter for tabular array values.Default: Comma (,)Applies to: Tabular arrays (arrays of objects with uniform keys)Source: toon_json_converter.py:1215-1216Data structure: Sets EncodeOptions.delimiter = Delimiter.TAB

Example: Default Comma Delimiter

Input JSON:

{
  "users": [
    {"name": "Alice", "age": 30, "city": "NYC"},
    {"name": "Bob", "age": 25, "city": "LA"}
  ]
}

Command:

python toon_json_converter.py users.json

Output:

users[2]{name,age,city}:
  Alice, 30, NYC
  Bob, 25, LA

Example: Tab Delimiter

Command:

python toon_json_converter.py users.json users_tab.toon --tab

Output:

users[2 ]{name,age,city}:
  Alice	30	NYC
  Bob	25	LA

Header marker: When using --tab, the header displays a space marker ( ) to indicate tab-separated values.

--pipe

flag

Use pipe (|) as the delimiter for tabular array values.Default: Comma (,)Applies to: Tabular arrays (arrays of objects with uniform keys)Source: toon_json_converter.py:1217-1218Data structure: Sets EncodeOptions.delimiter = Delimiter.PIPE

Example: Pipe Delimiter

Command:

python toon_json_converter.py users.json users_pipe.toon --pipe

Output:

users[2|]{name,age,city}:
  Alice|30|NYC
  Bob|25|LA

Header marker: When using --pipe, the header displays a pipe marker (|) inside the brackets.

Delimiter Comparison

Option	Delimiter Character	Header Marker	Use Case
Default	Comma (`,`)	None	Standard CSV-like data
`--tab`	Tab (`\t`)	Space ( )	Tab-separated values (TSV)
`--pipe`	Pipe (`\|`)	Pipe (`\|`)	Pipe-delimited data

Array Length Marker

--length-marker

flag

Add # prefix to array length indicators in headers.Default: No prefixApplies to: All array types (primitive, tabular, list)Source: toon_json_converter.py:1219-1220Data structure: Sets EncodeOptions.length_marker = True

Example: Without Length Marker (Default)

Input JSON:

{
  "tags": ["python", "json", "converter"],
  "scores": [95, 87, 92]
}

Command:

python toon_json_converter.py data.json

Output:

tags[3]: python, json, converter
scores[3]: 95, 87, 92

Example: With Length Marker

Command:

python toon_json_converter.py data.json data.toon --length-marker

Output:

tags[#3]: python, json, converter
scores[#3]: 95, 87, 92

Benefits

Improved readability: The # makes array lengths visually distinct from index notation
Parsing clarity: Helps distinguish array headers from potential index-based keys
Spec compliance: Follows TOON optional syntax for array length notation

Key Folding

--key-folding

flag

Enable key folding for nested single-key objects. Converts chains of objects with single keys into dotted path notation.Default: DisabledApplies to: Nested objects where each level has exactly one keyRequirements: Keys must match pattern [A-Za-z_][A-Za-z0-9_]* (alphanumeric + underscore, starting with letter/underscore)Source: toon_json_converter.py:1221-1222Data structure: Sets EncodeOptions.key_folding = TrueImplementation: KeyFolder class (toon_json_converter.py:278-306)

Example: Without Key Folding (Default)

Input JSON:

{
  "server": {
    "config": {
      "network": {
        "port": 8080
      }
    }
  }
}

Command:

python toon_json_converter.py config.json

Output:

server:
  config:
    network:
      port: 8080

Example: With Key Folding

Command:

python toon_json_converter.py config.json config.toon --key-folding

Output:

server.config.network.port: 8080

Key Folding Rules

Key folding applies when ALL of these conditions are met:

✅ Object has exactly one key
✅ Key matches pattern [A-Za-z_][A-Za-z0-9_]*
✅ Value is another object (continues the chain)

Key folding stops when:

❌ Object has multiple keys
❌ Key contains special characters (., -, etc.)
❌ Value is not an object (primitive, array, etc.)
❌ Max depth reached (default: infinite)

Example: Partial Key Folding

Input JSON:

{
  "database": {
    "connection": {
      "host": "localhost",
      "port": 5432
    }
  }
}

Command:

python toon_json_converter.py db.json db.toon --key-folding

Output:

database.connection:
  host: localhost
  port: 5432

Folding stops at connection because the next level has two keys (host and port).

Example: Invalid Keys for Folding

Input JSON:

{
  "app-config": {
    "api.endpoint": {
      "url": "https://api.example.com"
    }
  }
}

Command:

python toon_json_converter.py app.json app.toon --key-folding

Output:

"app-config":
  "api.endpoint":
    url: https://api.example.com

Key folding doesn’t apply because app-config contains a hyphen and api.endpoint contains a dot.

Source Code Reference

# toon_json_converter.py:281-290
class KeyFolder:
    SAFE_SEGMENT_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")

    @classmethod
    def can_fold(cls, key: str, value: Any, depth: int, max_depth: float) -> bool:
        return (
            depth < max_depth
            and cls.SAFE_SEGMENT_PATTERN.match(key) is not None
            and isinstance(value, dict)
            and len(value) == 1
        )

Combining Encoding Options

You can combine multiple encoding options:

python toon_json_converter.py data.json output.toon --pipe --length-marker --key-folding

Example result:

server.config.port: 8080
users[#3|]{name,age}:
  Alice|30
  Bob|25
  Carol|35

Decoding Options (TOON → JSON)

These options control how TOON data is decoded into JSON format.

Compact Output

--compact

flag

Output minified JSON without whitespace or indentation.Default: Pretty-printed with 2-space indentationApplies to: TOON → JSON and Folder → JSONL conversionsSource: toon_json_converter.py:1228-1229Data structure: Sets DecodeOptions.pretty = False

Example: Pretty Output (Default)

Input: data.toon

name: Alice
age: 30
active: true

Command:

python toon_json_converter.py data.toon

Output: data.json

{
  "name": "Alice",
  "age": 30,
  "active": true
}

Example: Compact Output

Command:

python toon_json_converter.py data.toon data.json --compact

Output: data.json (single line)

{"name":"Alice","age":30,"active":true}

Use Cases

Mode	Use Case
Pretty (default)	Human-readable output, debugging, configuration files
Compact	Minimal file size, API responses, log files, machine processing

Indentation

--indent

integer

Set the number of spaces for JSON indentation.Default: 2Range: Any positive integerIgnored when: Used with --compact flagSource: toon_json_converter.py:1232-1238Data structure: Sets DecodeOptions.indent

Example: Default 2-Space Indentation

Command:

python toon_json_converter.py data.toon data.json

Output:

{
  "server": {
    "port": 8080
  }
}

Example: 4-Space Indentation

Command:

python toon_json_converter.py data.toon data.json --indent 4

Output:

{
    "server": {
        "port": 8080
    }
}

Example: Tab Indentation

The converter does not support tab character indentation via a flag. Use --indent with space count only.

To achieve tab indentation, you would need to post-process the output:

python toon_json_converter.py data.toon temp.json --indent 1
sed 's/ /\t/g' temp.json > data.json

Path Expansion

--expand-paths

flag

Expand dotted keys into nested objects during TOON → JSON conversion.Default: Disabled (per TOON spec §13.4)Applies to: Keys containing dots (.) without bracketsSource: toon_json_converter.py:1230-1231Data structure: Sets DecodeOptions.expand_paths = TrueParser reference: toon_json_converter.py:656-657, 713-716

Example: Without Path Expansion (Default)

Input: config.toon

server.host: localhost
server.port: 8080
server.ssl.enabled: true

Command:

python toon_json_converter.py config.toon

Output: config.json

{
  "server.host": "localhost",
  "server.port": 8080,
  "server.ssl.enabled": true
}

By default, dotted keys are treated as literal string keys, not nested paths.

Example: With Path Expansion

Command:

python toon_json_converter.py config.toon config.json --expand-paths

Output: config.json

{
  "server": {
    "host": "localhost",
    "port": 8080,
    "ssl": {
      "enabled": true
    }
  }
}

Path Expansion Rules

Expansion applies when:

✅ Key contains dots (.)
✅ Key does NOT contain brackets ([, ])
✅ --expand-paths flag is set

Expansion does NOT apply to:

❌ Keys without dots
❌ Array notation like items[0]
❌ When --expand-paths is not set (default)

Example: Mixed Keys

Input: mixed.toon

app.name: MyApp
app.version: 2.0
metadata: {}
items[2]: a, b

Command:

python toon_json_converter.py mixed.toon --expand-paths

Output:

{
  "app": {
    "name": "MyApp",
    "version": "2.0"
  },
  "metadata": {},
  "items": ["a", "b"]
}

items[2] is NOT expanded because it contains brackets (array notation).

Source Code Reference

# toon_json_converter.py:713-716
if "." in key and "[" not in key and self.expand_paths:
    self._set_nested_key(obj, key, value)
else:
    obj[key] = value

# toon_json_converter.py:1005-1010
def _set_nested_key(self, obj: dict, key_path: str, value: Any) -> None:
    parts = key_path.split(".")
    current = obj
    for part in parts[:-1]:
        current = current.setdefault(part, {})
    current[parts[-1]] = value

Complementary with Key Folding

--key-folding (encoding) and --expand-paths (decoding) are complementary: Round-trip example:

# Start with nested JSON
echo '{"a":{"b":{"c":1}}}' > input.json

# Encode with key folding
python toon_json_converter.py input.json temp.toon --key-folding
# Result: a.b.c: 1

# Decode with path expansion
python toon_json_converter.py temp.toon output.json --expand-paths
# Result: {"a":{"b":{"c":1}}}

# Verify round-trip
diff input.json output.json  # Should be identical (ignoring whitespace)

Combining Decoding Options

You can combine decoding options:

python toon_json_converter.py data.toon output.json --indent 4 --expand-paths

Combining --compact with --indent will ignore the --indent value since compact mode removes all whitespace.

Option Scope Summary

Option	Applies When	Ignored When
`--tab`	Converting JSON/JSONL → TOON	Converting TOON → JSON
`--pipe`	Converting JSON/JSONL → TOON	Converting TOON → JSON
`--length-marker`	Converting JSON/JSONL → TOON	Converting TOON → JSON
`--key-folding`	Converting JSON/JSONL → TOON	Converting TOON → JSON
`--compact`	Converting TOON → JSON/JSONL	Converting JSON → TOON
`--indent`	Converting TOON → JSON/JSONL (without `--compact`)	Converting JSON → TOON, or with `--compact`
`--expand-paths`	Converting TOON → JSON/JSONL	Converting JSON → TOON

Next Steps

Batch Conversion

Learn batch processing workflows

Conversion Modes

Understand all four conversion modes

CLI Reference

Complete CLI command reference

TOON Format

Deep dive into TOON format specification

Get Started

Usage Guide

TOON Format

API Reference

​Overview

​General Options

​Output Path

​Usage

​Auto-Generated Paths

​Encoding Options (JSON → TOON)

​Delimiter Options

​Example: Default Comma Delimiter

​Example: Tab Delimiter

​Example: Pipe Delimiter

​Delimiter Comparison

​Array Length Marker

​Example: Without Length Marker (Default)

​Example: With Length Marker

​Benefits

​Key Folding

​Example: Without Key Folding (Default)

​Example: With Key Folding

​Key Folding Rules

​Example: Partial Key Folding

​Example: Invalid Keys for Folding

​Source Code Reference

​Combining Encoding Options

​Decoding Options (TOON → JSON)

​Compact Output

​Example: Pretty Output (Default)

​Example: Compact Output

​Use Cases

​Indentation

​Example: Default 2-Space Indentation

​Example: 4-Space Indentation

​Example: Tab Indentation

​Path Expansion

​Example: Without Path Expansion (Default)

​Example: With Path Expansion

​Path Expansion Rules

​Example: Mixed Keys

​Source Code Reference

​Complementary with Key Folding

​Combining Decoding Options

​Option Scope Summary

​Next Steps

Batch Conversion

Conversion Modes

CLI Reference

TOON Format

Build docs developers (and LLMs) love

Overview

General Options

Output Path

Usage

Auto-Generated Paths

Encoding Options (JSON → TOON)

Delimiter Options

Example: Default Comma Delimiter

Example: Tab Delimiter

Example: Pipe Delimiter

Delimiter Comparison

Array Length Marker

Example: Without Length Marker (Default)

Example: With Length Marker

Benefits

Key Folding

Example: Without Key Folding (Default)

Example: With Key Folding

Key Folding Rules

Example: Partial Key Folding

Example: Invalid Keys for Folding

Source Code Reference

Combining Encoding Options

Decoding Options (TOON → JSON)

Compact Output

Example: Pretty Output (Default)

Example: Compact Output

Use Cases

Indentation

Example: Default 2-Space Indentation

Example: 4-Space Indentation

Example: Tab Indentation

Path Expansion

Example: Without Path Expansion (Default)

Example: With Path Expansion

Path Expansion Rules

Example: Mixed Keys

Source Code Reference

Complementary with Key Folding

Combining Decoding Options

Option Scope Summary

Next Steps