toon

TOON (Token-Oriented Object Notation) encoder/decoder for Kit - reduces token usage by 30-60% compared to JSON

token-efficient serialization compared with JSON.

Files

Dependencies

No Kit package dependencies.

Installation

kit add gitlab.com/kit-lang/packages/kit-toon.git

Usage

import Kit.Toon as Toon

main = fn =>
  data = {name: "Kit", version: 1, active: true}

  # Encode primitive and structured Kit values.
  encoded = Toon.encode data
  println "Encoded: ${encoded}"

  # Decode currently returns the parsed value wrapped in a list.
  decoded = Toon.decode "hello"
  match decoded
    | [value | _] -> println "Decoded: ${value}"
    | [] -> panic "Decoded value was empty"

  # Use predefined delimiter constants when building encoder config.
  pipe-config = Toon.default-config
    |> Toon.with-indent "    "
    |> Toon.with-delimiter Toon.delimiter-pipe

  pipe-encoder = Toon.encode-with-config pipe-config
  println "Custom encoded: ${pipe-encoder [1, 2, 3]}"

  # Tab delimiters are available without relying on escape literal parsing.
  tab-config = Toon.default-config |> Toon.with-delimiter Toon.delimiter-tab
  tab-encoder = Toon.encode-with-config tab-config
  println "Tab encoded: ${tab-encoder {a: 1, b: 2}}"

main

API

Core functions:

Configuration helpers:

Implementation Notes

The encoder currently delegates most structured output to Kit's to-string

representation. The configuration API is present and tested, but

encode-with-config currently delegates to encode.

The decoder is intentionally minimal today: it returns the input string wrapped

in a list, e.g. Toon.decode "42" returns ["42"]. This keeps the public shape

stable while fuller TOON parsing is developed.

delimiter-tab is constructed with String.from-bytes [9] instead of a "\t"

literal so compiled and interpreted runs agree on the exact tab byte.

Development

Running Examples

Run an example with the interpreter:

kit run examples/basic-usage.kit

Compile an example to a native binary:

kit build examples/basic-usage.kit && ./basic-usage

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

1. Check formatting for source, tests, and examples
2. Type check src/
3. Type check examples/
4. Run tests with coverage

Running Parity

Check interpreter/compiler parity for examples:

kit parity --failures-only

This builds and runs the examples with both execution paths and reports output

mismatches.

Generating Documentation

Generate API documentation from doc comments:

kit doc src/main.kit -o docs/main.html

Note: Kit sources with doc comments (##) can generate HTML documents in

docs/*.html.

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/toon/, making it available

for import as Kit.Toon in other projects.

License

This package is released under the MIT License - see LICENSE for

details.

Exported Functions & Types

encode

Encode a Kit value to TOON format string.

Converts any Kit value (unit, bool, int, float, string, list, or record) into its TOON string representation using default configuration settings.

Parameters:

• value - The Kit value to encode (any type)

Returns: A string containing the TOON representation of the value

a -> String

encode 42          # => "42"
encode "hello"     # => "hello"
encode [1, 2, 3]   # => "[1, 2, 3]"

encode-pretty

Encode a Kit value with pretty formatting.

Converts a Kit value to TOON format with human-readable formatting, including proper indentation and spacing for nested structures.

Parameters:

• value - The Kit value to encode (any type)

Returns: A formatted string containing the TOON representation of the value

a -> String

encode-pretty {name: "Alice", items: [1, 2, 3]}
# => Pretty formatted output with indentation

encode-with-config

Encode a Kit value with custom configuration.

Returns a function that encodes values using the provided configuration. This allows you to customize indentation, delimiters, and other formatting options for the TOON output.

Parameters:

• config - A record containing encoding configuration -
• {indent - String, delimiter: String}

Returns: A function that takes a value and returns its TOON string representation

{indent: String, delimiter: String} -> a -> String

config = default-config |> with-indent "    " |> with-delimiter delimiter-pipe
encoder = encode-with-config config
result = encoder {x: 1, y: 2}

decode

Decode a TOON format string to Kit value.

Parses a TOON format string and converts it back to the original Kit value. This is the inverse operation of encode.

Parameters:

• toon-str - A string in TOON format to decode

Returns: The Kit value represented by the TOON string

String -> [String]

decode "42"              # => 42
decode "[1, 2, 3]"       # => [1, 2, 3]
decode "{x: 1, y: 2}"    # => {x: 1, y: 2}

default-config

Default encoding configuration.

with-indent

Set custom indentation string for encoding.

{indent: String, delimiter: String} -> String -> {indent: String, delimiter: String}

with-delimiter

Set custom delimiter for arrays in encoding.

{indent: String, delimiter: String} -> String -> {indent: String, delimiter: String}

delimiter-comma

Comma delimiter constant for array encoding.

delimiter-tab

Tab delimiter constant for array encoding.

delimiter-pipe

Pipe delimiter constant for array encoding.

delimiter-comma

Comma delimiter constant.

Standard comma separator for TOON list and record elements.

config = default-config |> with-delimiter delimiter-comma

delimiter-tab

Tab delimiter constant.

Tab character separator for TOON list and record elements.

config = default-config |> with-delimiter delimiter-tab

delimiter-pipe

Pipe delimiter constant.

Pipe character separator for TOON list and record elements.

config = default-config |> with-delimiter delimiter-pipe

default-config

Default encoding configuration with two-space indentation and comma delimiter.

Standard configuration record for TOON encoding with sensible defaults.

Fields: indent - String used for each indentation level (default: two spaces) delimiter - String used to separate list/record elements (default: comma)

config = default-config
# config = {indent: "  ", delimiter: ","}

with-indent

Set custom indentation string in the configuration.

Returns a curried function that creates a new configuration with the specified indentation string while preserving the delimiter.

Parameters:

• config - Existing encoder configuration record

Returns: Function that takes new-indent string and returns updated config

{indent: String, delimiter: String} -> String -> {indent: String, delimiter: String}

config = default-config |> with-indent "    "
# config = {indent: "    ", delimiter: ","}

with-delimiter

Set custom delimiter in the configuration.

Returns a curried function that creates a new configuration with the specified delimiter while preserving the indentation.

Parameters:

• config - Existing encoder configuration record

Returns: Function that takes delim string and returns updated config

{indent: String, delimiter: String} -> String -> {indent: String, delimiter: String}

config = default-config |> with-delimiter delimiter-pipe
# config = {indent: "  ", delimiter: "|"}

encode

Encode a Kit value to TOON format string.

Converts any Kit value into a TOON-formatted string representation. Handles primitive types (unit, bool, int, float, string) and collections (lists, records) by converting them to their string representations.

Parameters:

• value - Any Kit value to encode

Returns: String containing TOON representation of the value

a -> String

encode ()
# Returns: "null"

encode true
# Returns: "true"

encode 42
# Returns: "42"

encode "hello"
# Returns: "hello"

encode [1, 2, 3]
# Returns: "[1, 2, 3]"

encode {x: 10, y: 20}
# Returns: "{x: 10, y: 20}"

encode-pretty

Encode a Kit value with pretty formatting.

Converts a Kit value to TOON format with human-readable formatting, including proper indentation and line breaks for nested structures. Currently delegates to the standard encode function.

Parameters:

• value - Any Kit value to encode with pretty formatting

Returns: Pretty-formatted TOON string representation

a -> String

data = {user: {name: "Alice", age: 30}, active: true}
pretty = encode-pretty data
# Returns formatted string with indentation

encode-with-config

Encode a Kit value with custom configuration.

Returns a curried function that encodes Kit values using the specified configuration settings for indentation and delimiters. Currently delegates to the standard encode function.

Parameters:

• config - Configuration record with indent and delimiter fields

Returns: Function that takes a value and returns configured TOON string

{indent: String, delimiter: String} -> a -> String

config = default-config
  |> with-indent "    "
  |> with-delimiter delimiter-pipe

encoder = encode-with-config config
result = encoder {a: 1, b: 2}
# Returns: "{a: 1 | b: 2}" (with custom delimiter)

decode

Decode a TOON format string to Kit value.

Parses a TOON-formatted string and converts it to the corresponding Kit value. Currently returns the input wrapped in a list as a minimal implementation.

Parameters:

• toon-str - String containing TOON-formatted data

Returns: Kit value corresponding to the TOON input (currently [toon-str])

String -> List String

result = decode "123"
# Returns: ["123"]