github/toon
1
0
Fork 0
mirror of https://github.com/voson-wang/toon.git synced 2026-01-29 15:24:10 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: fix CLI options naming (fixes #241)

Browse Source
This commit is contained in:
Johann Schopplich
2025-12-07 13:10:09 +01:00
parent 8a2c7e6715
commit 19f9a5527f
3 changed files with 26 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
docs/cli/index.md
View File

@@ -120,7 +120,7 @@ Both encoding and decoding operations use streaming output, writing incrementall
- Uses the same event-based streaming decoder as the `decodeStream` API in `@toon-format/toon`. - Uses the same event-based streaming decoder as the `decodeStream` API in `@toon-format/toon`.
- Streams JSON tokens to output. - Streams JSON tokens to output.
- No full JSON string in memory. - No full JSON string in memory.
- When `--expand-paths safe` is enabled, falls back to non-streaming decode internally to apply deep-merge expansion before writing JSON. - When `--expandPaths safe` is enabled, falls back to non-streaming decode internally to apply deep-merge expansion before writing JSON.
Process large files with minimal memory usage: Process large files with minimal memory usage:
@@ -153,9 +153,9 @@ When using the `--stats` flag with encode, the CLI builds the full TOON string o
| `--indent <number>` | Indentation size (default: `2`) | | `--indent <number>` | Indentation size (default: `2`) |
| `--stats` | Show token count estimates and savings (encode only) | | `--stats` | Show token count estimates and savings (encode only) |
| `--no-strict` | Disable strict validation when decoding | | `--no-strict` | Disable strict validation when decoding |
| `--key-folding <mode>` | Key folding mode: `off`, `safe` (default: `off`) | | `--keyFolding <mode>` | Key folding mode: `off`, `safe` (default: `off`) |
| `--flatten-depth <number>` | Maximum segments to fold (default: `Infinity`) – requires `--key-folding safe` | | `--flattenDepth <number>` | Maximum segments to fold (default: `Infinity`) – requires `--keyFolding safe` |
| `--expand-paths <mode>` | Path expansion mode: `off`, `safe` (default: `off`) | | `--expandPaths <mode>` | Path expansion mode: `off`, `safe` (default: `off`) |
## Advanced Examples ## Advanced Examples
@@ -247,11 +247,11 @@ Collapse nested wrapper chains to reduce tokens (since spec v1.5):
::: code-group ::: code-group
```bash [Basic key folding] ```bash [Basic key folding]
toon input.json --key-folding safe -o output.toon toon input.json --keyFolding safe -o output.toon
``` ```
```bash [Limit folding depth] ```bash [Limit folding depth]
toon input.json --key-folding safe --flatten-depth 2 -o output.toon toon input.json --keyFolding safe --flattenDepth 2 -o output.toon
``` ```
::: :::
@@ -270,7 +270,7 @@ For data like:
} }
``` ```
With `--key-folding safe`, output becomes: With `--keyFolding safe`, output becomes:
```yaml ```yaml
data.metadata.items[2]: a,b data.metadata.items[2]: a,b
@@ -289,19 +289,19 @@ data:
Reconstruct nested structure from folded keys when decoding: Reconstruct nested structure from folded keys when decoding:
```bash ```bash
toon data.toon --expand-paths safe -o output.json toon data.toon --expandPaths safe -o output.json
``` ```
This pairs with `--key-folding safe` for lossless round-trips. This pairs with `--keyFolding safe` for lossless round-trips.
### Round-Trip Workflow ### Round-Trip Workflow
```bash ```bash
# Encode with folding # Encode with folding
toon input.json --key-folding safe -o compressed.toon toon input.json --keyFolding safe -o compressed.toon
# Decode with expansion (restores original structure) # Decode with expansion (restores original structure)
toon compressed.toon --expand-paths safe -o output.json toon compressed.toon --expandPaths safe -o output.json
# Verify round-trip # Verify round-trip
diff input.json output.json diff input.json output.json
@@ -313,5 +313,5 @@ Combine multiple options for maximum efficiency:
```bash ```bash
# Key folding + tab delimiter + stats # Key folding + tab delimiter + stats
toon data.json --key-folding safe --delimiter "\t" --stats -o output.toon toon data.json --keyFolding safe --delimiter "\t" --stats -o output.toon
``` ```

20
packages/cli/README.md
View File

@@ -64,9 +64,9 @@ cat data.toon | toon --decode
| `--indent <number>` | Indentation size (default: `2`) | | `--indent <number>` | Indentation size (default: `2`) |
| `--stats` | Show token count estimates and savings (encode only) | | `--stats` | Show token count estimates and savings (encode only) |
| `--no-strict` | Disable strict validation when decoding | | `--no-strict` | Disable strict validation when decoding |
| `--key-folding <mode>` | Enable key folding: `off`, `safe` (default: `off`) | | `--keyFolding <mode>` | Enable key folding: `off`, `safe` (default: `off`) |
| `--flatten-depth <number>` | Maximum folded segment count when key folding is enabled (default: `Infinity`) | | `--flattenDepth <number>` | Maximum folded segment count when key folding is enabled (default: `Infinity`) |
| `--expand-paths <mode>` | Enable path expansion: `off`, `safe` (default: `off`) | | `--expandPaths <mode>` | Enable path expansion: `off`, `safe` (default: `off`) |
## Advanced Examples ## Advanced Examples
@@ -136,7 +136,7 @@ cat million-records.toon | toon --decode > output.json
- **Encode (JSON → TOON)**: Streams TOON lines to output without full string in memory - **Encode (JSON → TOON)**: Streams TOON lines to output without full string in memory
- **Decode (TOON → JSON)**: Uses the same event-based streaming decoder as the `decodeStream` API in `@toon-format/toon`, streaming JSON tokens to output without full string in memory - **Decode (TOON → JSON)**: Uses the same event-based streaming decoder as the `decodeStream` API in `@toon-format/toon`, streaming JSON tokens to output without full string in memory
- Peak memory usage scales with data depth, not total size - Peak memory usage scales with data depth, not total size
- When `--expand-paths safe` is enabled, decode falls back to non-streaming mode internally to apply deep-merge expansion before writing JSON - When `--expandPaths safe` is enabled, decode falls back to non-streaming mode internally to apply deep-merge expansion before writing JSON
> [!NOTE] > [!NOTE]
> When using `--stats` with encode, the full output string is kept in memory for token counting. Omit `--stats` for maximum memory efficiency with very large datasets. > When using `--stats` with encode, the full output string is kept in memory for token counting. Omit `--stats` for maximum memory efficiency with very large datasets.
@@ -149,7 +149,7 @@ Collapse nested wrapper chains to reduce tokens:
```bash ```bash
# Encode with key folding # Encode with key folding
toon input.json --key-folding safe -o output.toon toon input.json --keyFolding safe -o output.toon
``` ```
For data like: For data like:
@@ -179,24 +179,24 @@ data:
```bash ```bash
# Fold maximum 2 levels deep # Fold maximum 2 levels deep
toon input.json --key-folding safe --flatten-depth 2 -o output.toon toon input.json --keyFolding safe --flattenDepth 2 -o output.toon
``` ```
#### Path expansion on decode #### Path expansion on decode
```bash ```bash
# Reconstruct nested structure from folded keys # Reconstruct nested structure from folded keys
toon data.toon --expand-paths safe -o output.json toon data.toon --expandPaths safe -o output.json
``` ```
#### Round-trip workflow #### Round-trip workflow
```bash ```bash
# Encode with folding # Encode with folding
toon input.json --key-folding safe -o compressed.toon toon input.json --keyFolding safe -o compressed.toon
# Decode with expansion (restores original structure) # Decode with expansion (restores original structure)
toon compressed.toon --expand-paths safe -o output.json toon compressed.toon --expandPaths safe -o output.json
# Verify round-trip # Verify round-trip
diff input.json output.json diff input.json output.json
@@ -206,7 +206,7 @@ diff input.json output.json
```bash ```bash
# Key folding + tab delimiter + stats # Key folding + tab delimiter + stats
toon data.json --key-folding safe --delimiter "\t" --stats -o output.toon toon data.json --keyFolding safe --delimiter "\t" --stats -o output.toon
``` ```
## Why Use the CLI? ## Why Use the CLI?

8
packages/cli/test/index.test.ts
View File

@@ -306,7 +306,7 @@ describe('toon CLI', () => {
}) })
describe('encode options', () => { describe('encode options', () => {
it('encodes with --key-folding safe', async () => { it('encodes with --keyFolding safe', async () => {
const data = { const data = {
data: { data: {
metadata: { metadata: {
@@ -332,7 +332,7 @@ describe('toon CLI', () => {
} }
}) })
it('encodes with --flatten-depth', async () => { it('encodes with --flattenDepth', async () => {
const data = { const data = {
level1: { level1: {
level2: { level2: {
@@ -362,7 +362,7 @@ describe('toon CLI', () => {
}) })
describe('decode options', () => { describe('decode options', () => {
it('decodes with --expand-paths safe', async () => { it('decodes with --expandPaths safe', async () => {
const data = { const data = {
data: { data: {
metadata: { metadata: {
@@ -715,7 +715,7 @@ describe('toon CLI', () => {
} }
}) })
it('rejects invalid --key-folding value', async () => { it('rejects invalid --keyFolding value', async () => {
const context = await createCliTestContext({ const context = await createCliTestContext({
'input.json': JSON.stringify({ value: 1 }), 'input.json': JSON.stringify({ value: 1 }),
}) })