toon

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

Files

Dependencies

No Kit package dependencies.

Installation

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

Usage

import Kit.Toon

License

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

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

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

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

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

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])

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