Thanks to visit codestin.com
Credit goes to github.com

Skip to content

[pull] main from toon-format:main #49

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pull merged 3 commits into from
Dec 7, 2025
Merged

[pull] main from toon-format:main #49

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
19f9a55
docs: fix CLI options naming (fixes #241)
johannschopplich Dec 7, 2025
2474685
docs: add Kotlin community implementations (#236)
lukelast Dec 7, 2025
bbd7e8c
docs: add Swift implementation to official and community lists
johannschopplich Dec 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions docs/cli/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
- Streams JSON tokens to output.
- 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:

Expand Down Expand Up @@ -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`) |
| `--stats` | Show token count estimates and savings (encode only) |
| `--no-strict` | Disable strict validation when decoding |
| `--key-folding <mode>` | Key folding mode: `off`, `safe` (default: `off`) |
| `--flatten-depth <number>` | Maximum segments to fold (default: `Infinity`) – requires `--key-folding safe` |
| `--expand-paths <mode>` | Path expansion mode: `off`, `safe` (default: `off`) |
| `--keyFolding <mode>` | Key folding mode: `off`, `safe` (default: `off`) |
| `--flattenDepth <number>` | Maximum segments to fold (default: `Infinity`) – requires `--keyFolding safe` |
| `--expandPaths <mode>` | Path expansion mode: `off`, `safe` (default: `off`) |

## Advanced Examples

Expand Down Expand Up @@ -247,11 +247,11 @@ Collapse nested wrapper chains to reduce tokens (since spec v1.5):
::: code-group

```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]
toon input.json --key-folding safe --flatten-depth 2 -o output.toon
toon input.json --keyFolding safe --flattenDepth 2 -o output.toon
```

:::
Expand All @@ -270,7 +270,7 @@ For data like:
}
```

With `--key-folding safe`, output becomes:
With `--keyFolding safe`, output becomes:

```yaml
data.metadata.items[2]: a,b
Expand All @@ -289,19 +289,19 @@ data:
Reconstruct nested structure from folded keys when decoding:

```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

```bash
# 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)
toon compressed.toon --expand-paths safe -o output.json
toon compressed.toon --expandPaths safe -o output.json

# Verify round-trip
diff input.json output.json
Expand All @@ -313,5 +313,5 @@ Combine multiple options for maximum efficiency:

```bash
# 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
```
4 changes: 2 additions & 2 deletions docs/ecosystem/implementations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ These implementations are actively being developed by dedicated teams. Contribut
| **Julia** | [ToonFormat.jl](https://github.com/toon-format/ToonFormat.jl) | ✅ Stable | Official Team |
| **Python** | [toon-python](https://github.com/toon-format/toon-python) | ✅ Stable | Official Team |
| **Rust** | [toon-rust](https://github.com/toon-format/toon-rust) | ✅ Stable | Official Team |
| **Swift** | [toon-swift](https://github.com/toon-format/toon-swift) | ✅ Stable | Official Team |
| **TypeScript/JavaScript** | [toon](https://github.com/toon-format/toon/tree/main/packages/toon) | ✅ Stable | Official Team |

## Community Implementations
Expand All @@ -35,7 +36,7 @@ Community members have created implementations in additional languages:
| **Elixir** | [toon_ex](https://github.com/kentaro/toon_ex) | [@kentaro](https://github.com/kentaro) |
| **Gleam** | [toon_codec](https://github.com/axelbellec/toon_codec) | [@axelbellec](https://github.com/axelbellec) |
| **Go** | [gotoon](https://github.com/alpkeskin/gotoon) | [@alpkeskin](https://github.com/alpkeskin) |
| **Kotlin** | [kotlin-toon](https://github.com/vexpera-br/kotlin-toon) | [@vexpera-br](https://github.com/vexpera-br) |
| **Kotlin** | [ktoon](https://github.com/lukelast/ktoon)| [@lukelast](https://github.com/lukelast) |
| **Laravel Framework** | [laravel-toon](https://github.com/jobmetric/laravel-toon) | [@jobmetric](https://github.com/jobmetric) |
| **Lua/Neovim** | [toon.nvim](https://github.com/thalesgelinger/toon.nvim) | [@thalesgelinger](https://github.com/thalesgelinger) |
| **OCaml** | [ocaml-toon](https://github.com/davesnx/ocaml-toon) | [@davesnx](https://github.com/davesnx) |
Expand All @@ -44,7 +45,6 @@ Community members have created implementations in additional languages:
| **R** | [toon](https://github.com/laresbernardo/toon) | [@laresbernardo](https://github.com/laresbernardo) |
| **Ruby** | [toon-ruby](https://github.com/andrepcg/toon-ruby) | [@andrepcg](https://github.com/andrepcg) |
| **Scala** | [toon4s](https://github.com/vim89/toon4s) | [@vim89](https://github.com/vim89) |
| **Swift** | [TOONEncoder](https://github.com/mattt/TOONEncoder) | [@mattt](https://github.com/mattt) |

## Contributing an Implementation

Expand Down
20 changes: 10 additions & 10 deletions packages/cli/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,9 +64,9 @@ cat data.toon | toon --decode
| `--indent <number>` | Indentation size (default: `2`) |
| `--stats` | Show token count estimates and savings (encode only) |
| `--no-strict` | Disable strict validation when decoding |
| `--key-folding <mode>` | Enable key folding: `off`, `safe` (default: `off`) |
| `--flatten-depth <number>` | Maximum folded segment count when key folding is enabled (default: `Infinity`) |
| `--expand-paths <mode>` | Enable path expansion: `off`, `safe` (default: `off`) |
| `--keyFolding <mode>` | Enable key folding: `off`, `safe` (default: `off`) |
| `--flattenDepth <number>` | Maximum folded segment count when key folding is enabled (default: `Infinity`) |
| `--expandPaths <mode>` | Enable path expansion: `off`, `safe` (default: `off`) |

## Advanced Examples

Expand Down Expand Up @@ -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
- **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
- 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]
> 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.
Expand All @@ -149,7 +149,7 @@ Collapse nested wrapper chains to reduce tokens:

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

For data like:
Expand Down Expand Up @@ -179,24 +179,24 @@ data:

```bash
# 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

```bash
# 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

```bash
# 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)
toon compressed.toon --expand-paths safe -o output.json
toon compressed.toon --expandPaths safe -o output.json

# Verify round-trip
diff input.json output.json
Expand All @@ -206,7 +206,7 @@ diff input.json output.json

```bash
# 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?
Expand Down
8 changes: 4 additions & 4 deletions packages/cli/test/index.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -306,7 +306,7 @@ describe('toon CLI', () => {
})

describe('encode options', () => {
it('encodes with --key-folding safe', async () => {
it('encodes with --keyFolding safe', async () => {
const data = {
data: {
metadata: {
Expand All @@ -332,7 +332,7 @@ describe('toon CLI', () => {
}
})

it('encodes with --flatten-depth', async () => {
it('encodes with --flattenDepth', async () => {
const data = {
level1: {
level2: {
Expand Down Expand Up @@ -362,7 +362,7 @@ describe('toon CLI', () => {
})

describe('decode options', () => {
it('decodes with --expand-paths safe', async () => {
it('decodes with --expandPaths safe', async () => {
const data = {
data: {
metadata: {
Expand Down Expand Up @@ -715,7 +715,7 @@ describe('toon CLI', () => {
}
})

it('rejects invalid --key-folding value', async () => {
it('rejects invalid --keyFolding value', async () => {
const context = await createCliTestContext({
'input.json': JSON.stringify({ value: 1 }),
})
Expand Down
4 changes: 2 additions & 2 deletions packages/toon/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -924,6 +924,7 @@ Comprehensive guides, references, and resources to help you get the most out of
- **Julia:** [ToonFormat.jl](https://github.com/toon-format/ToonFormat.jl)
- **Python:** [toon_format](https://github.com/toon-format/toon-python)
- **Rust:** [toon_format](https://github.com/toon-format/toon-rust)
- **Swift:** [toon-swift](https://github.com/toon-format/toon-swift)

### Community Implementations

Expand All @@ -942,8 +943,7 @@ Comprehensive guides, references, and resources to help you get the most out of
- **Laravel Framework:** [laravel-toon](https://github.com/jobmetric/laravel-toon)
- **R**: [toon](https://github.com/laresbernardo/toon)
- **Ruby:** [toon-ruby](https://github.com/andrepcg/toon-ruby)
- **Swift:** [TOONEncoder](https://github.com/mattt/TOONEncoder)
- **Kotlin:** [Kotlin-Toon Encoder/Decoder](https://github.com/vexpera-br/kotlin-toon)
- **Kotlin:** [ktoon (using kotlinx.serialization)](https://github.com/lukelast/ktoon)

## Credits

Expand Down
Loading