.. _library_toon:

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 <../../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