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