# `toon`

The `toon` library provides predicates for parsing and generating data in the TOON (Token-Oriented Object Notation) format. TOON is a compact, human-readable, line-oriented format that encodes the JSON data model while minimizing tokens. For more information on the TOON format, see:

https://github.com/toon-format/toon

## API documentation

Open the ../../apis/library_index.html#toon link in a web browser.

## Loading

To load all entities in this library, load the `loader.lgt` file:

    | ?- logtalk_load(toon(loader)).

## Testing

To test this library predicates, load the `tester.lgt` file:

    | ?- logtalk_load(toon(tester)).

## Representation

TOON objects are represented using the same conventions as the `json` library. The representation of TOON objects and TOON pairs can be controlled using the `toon/3` parametric object. The three parameters are:

- `ObjectRepresentation`: `curly` (default) or `list`

- `PairRepresentation`: `dash` (default), `equal`, or `colon`

- `StringRepresentation`: `atom` (default), `chars`, or `codes`

The `toon(StringRepresentation)` and `toon` objects use the default representations.

### Objects

TOON objects are represented using curly terms by default:

    {Key1-Value1, Key2-Value2, ...}

Or using lists when using `list` for the `ObjectRepresentation` parameter:

    toon([Key1-Value1, Key2-Value2, ...])

### Arrays

TOON arrays are represented as lists:

    [Element1, Element2, ...]

### Primitives

TOON primitive values are represented as follows:

- Strings: atoms (default), `chars(ListOfChars)`, or `codes(ListOfCodes)`

- Numbers: Prolog numbers

- Booleans: `@true` and `@false`

- Null: `@null`

## TOON format features

TOON is a line-oriented format with the following key features:

- Uses indentation (2 spaces) instead of braces for objects

- Arrays declare their length: `[N]:` for inline or `[N]{fields}:` for tabular

- Tabular form for uniform arrays of objects with primitive values

- Minimal quoting rules for strings

- Three delimiters: comma (default), tab, and pipe

- UTF-8 encoding with LF line endings

- File extension: `.toon`, media type: `text/toon`

## Usage examples

Parsing TOON from an atom:

    | ?- toon::parse(atom('name: John\nage: 30'), Term).
    Term = {name-'John', age-30}
    yes

Generating TOON to an atom:

    | ?- toon::generate(atom(Atom), {name-'John', age-30}).
    Atom = 'name: John\nage: 30'
    yes

Parsing TOON from a file:

    | ?- toon::parse(file('data.toon'), Term).
    ...

Generating TOON to a file:

    | ?- toon::generate(file('output.toon'), {name-'John', age-30}).
    ...

Using different representations:

    | ?- toon(list, dash, atom)::parse(atom('name: John'), Term).
    Term = toon([name-'John'])
    yes