TOON Interactive TUI

Overview

The TOON Format includes a full-featured, interactive Terminal User Interface (TUI) powered by Ratatui. This provides a powerful, real-time environment for working with TOON format conversions.

Launching the TUI

# Launch interactive mode
toon --interactive

# Or use the short flag
toon -i

Features

Dual-Mode Conversion

• Encode Mode: JSON → TOON
• Decode Mode: TOON → JSON
• Toggle between modes with Ctrl+E or Ctrl+M

Split-Screen Editor

• Real-time conversion as you type
• Syntax highlighting support
• Input panel (left) and output panel (right)
• Switch between panels with Tab
• Line numbers for easy navigation

Live Statistics

• Token count comparison (JSON vs TOON)
• Byte size comparison
• Percentage savings calculation
• Real-time updates as you edit

Interactive Settings Panel (Ctrl+P)

Configure encoding and decoding options on-the-fly:

Encode Settings:

• Delimiter: Comma (,), Tab (\t), or Pipe (|) - Press d to cycle
• Indentation: Adjust spaces with + / - keys
• Key Folding: Toggle with f - Collapses {a:{b:1}} → a.b: 1
• Flatten Depth: Control folding depth with [ / ] keys, u for unlimited

Decode Settings:

• Strict Mode: Toggle with s - Enforce spec compliance
• Type Coercion: Toggle with c - Auto-convert strings to types
• Path Expansion: Toggle with p - Expand a.b:1 → {"a":{"b":1}}

File Browser (Ctrl+F)

• Visual file navigation
• File type indicators (JSON, TOON, directories)
• Navigate with arrow keys
• Open files with Enter
• Multi-file selection with Space

Conversion History (Ctrl+H)

• Track all conversions in the session
• View timestamps
• See token savings for each conversion
• File names and modes

Side-by-Side Diff Viewer (Ctrl+D)

• Compare input and output side-by-side
• Line numbers for easy reference
• Perfect for understanding transformations

File Operations

• Ctrl+O - Open file
• Ctrl+S - Save output to file
• Ctrl+N - New file (clear editor)
• Auto-detection of file types (.json, .toon)

Clipboard Integration

• Ctrl+K - Copy selection to clipboard
• Ctrl+Y - Copy output to clipboard
• Ctrl+V - Paste into input
• Seamless integration with system clipboard

Round-Trip Testing (Ctrl+B)

• Test conversion fidelity
• Automatically converts output back to input
• Toggles mode and re-converts
• Validates that data survives round-trip

REPL Mode (Ctrl+R)

• Interactive command-line interface
• Execute commands like encode, decode, help
• Store variables with let $var = data
• View command history with Up/Down arrows
• Scrollable output
• Full-screen mode for focused work

Theme Support (Ctrl+T)

• Dark Theme (default)
• Light Theme
• Toggle between themes on-the-fly

Built-in Help (F1)

• Complete keyboard shortcuts reference
• Feature documentation
• Quick examples

Keyboard Shortcuts

Global Commands

Shortcut	Action
Ctrl+C / Ctrl+Q	Quit application
Ctrl+E / Ctrl+M	Toggle mode (Encode ⇄ Decode)
Tab	Switch between input/output panels
F1	Show/hide help screen
Esc	Close overlays (help, settings, REPL, etc.)

File Operations

Shortcut	Action
Ctrl+O	Open file browser
Ctrl+S	Save output to file
Ctrl+N	New file (clear editor)

View Controls

Shortcut	Action
Ctrl+P	Toggle settings panel
Ctrl+F	Toggle file browser
Ctrl+H	Toggle conversion history
Ctrl+D	Toggle diff viewer
Ctrl+T	Toggle theme (Dark/Light)
Ctrl+R	Open REPL

Editing & Testing

Shortcut	Action
Ctrl+K	Copy selection to clipboard
Ctrl+Y	Copy output to clipboard
Ctrl+V	Paste into input
Ctrl+L	Clear input and output
Ctrl+B	Round-trip test

Settings Panel (when Ctrl+P is active)

Shortcut	Action
d	Cycle delimiter (Comma → Tab → Pipe)
+ / =	Increase indentation
- / _	Decrease indentation
f	Toggle key folding
[ / ]	Adjust flatten depth
u	Toggle unlimited flatten depth
p	Toggle path expansion
s	Toggle strict mode
c	Toggle type coercion

File Browser (when Ctrl+F is active)

Shortcut	Action
↑ / ↓	Navigate files
Enter	Open file
Space	Select/deselect file
Esc	Close browser

REPL (when Ctrl+R is active)

Shortcut	Action
↑ / ↓	Navigate command history
PageUp / PageDown	Scroll output
Enter	Execute command
Esc	Close REPL

REPL Commands

Command	Description	Example
encode <data>	Encode JSON to TOON	encode {"name": "Alice"}
decode <data>	Decode TOON to JSON	decode name: Alice
let $var = <data>	Store variable	let $config = {"port": 8080}
vars	List all variables	vars
clear	Clear output	clear
help	Show help	help
exit	Close REPL	exit

Variable Usage:

• Use $_ to reference the last result
• Use $varname to reference stored variables
• Example: let $data = {...} then encode $data

Example Workflow

1. Launch TUI: toon -i
2. Paste JSON into input panel (left side)
3. See TOON output instantly (right side)
4. View statistics at the bottom (tokens saved, bytes saved)
5. Adjust settings with Ctrl+P (try enabling key folding!)
6. Save output with Ctrl+S
7. Test round-trip with Ctrl+B to verify data fidelity
8. Switch to decode mode with Ctrl+E for manual testing

Requirements

The TUI is included in the standard toon binary with no additional setup required. Dependencies are handled automatically by Cargo.

Tips & Tricks

1. Quick Start: Use Ctrl+V to paste clipboard content directly
2. Settings Memory: Settings persist during your session
3. Theme Preference: Toggle theme with Ctrl+T for your environment
4. Learning Mode: Keep F1 (Help) open while learning shortcuts
5. Performance: The TUI handles large JSON files efficiently with scrolling
6. REPL Variables: Store frequently used data in variables for quick testing
7. Round-Trip: Always test with Ctrl+B to ensure your data survives conversion

Feedback & Contributions

Found a bug or have a feature request? Please open an issue on GitHub!