/ 
Data-TOON-0.03
/ README.md

Actions Status

NAME

Data::TOON - Complete Perl implementation of TOON (Token-Oriented Object Notation)

SYNOPSIS

use Data::TOON;

# Basic usage
my $data = { name => 'Alice', age => 30, active => 1 };
my $toon = Data::TOON->encode($data);
print $toon;
# Output:
#   active: true
#   age: 30
#   name: Alice

my $decoded = Data::TOON->decode($toon);

# Tabular arrays
my $users = {
    users => [
        { id => 1, name => 'Alice', role => 'admin' },
        { id => 2, name => 'Bob', role => 'user' }
    ]
};

print Data::TOON->encode($users);
# Output:
#   users[2]{id,name,role}:
#     1,Alice,admin
#     2,Bob,user

# Alternative delimiters
my $encoder = Data::TOON::Encoder->new(delimiter => '|');
print $encoder->encode($users);
# Or with tabs:
my $tab_encoder = Data::TOON::Encoder->new(delimiter => "\t");

# Root primitives and arrays
print Data::TOON->encode(42);           # Output: 42
print Data::TOON->encode('hello');      # Output: hello
print Data::TOON->encode([1, 2, 3]);    # Output: [3]: 1,2,3

DESCRIPTION

Data::TOON is a complete Perl implementation of TOON (Token-Oriented Object Notation), a human-friendly, line-oriented data serialization format.

TOON provides:

The format is particularly useful for configuration files, data interchange, and human-editable data storage.

METHODS

encode( $data, %options )

Encodes a Perl data structure to TOON format string.

Parameters:

Returns:

TOON format string. Can encode to: - Object (most common): key: value pairs - Tabular array: Compact name[N]{fields}: row format - List array: Explicit name[N]: - item format
- Root primitive: Single value (42, "hello", true, false, null) - Root array: [N]: value,value,...

Examples:

# Simple object
my $toon = Data::TOON->encode({ name => 'Alice', age => 30 });
# Output:
#   age: 30
#   name: Alice

# Nested object
my $toon = Data::TOON->encode({
    user => {
        name => 'Alice',
        age => 30
    }
});
# Output:
#   user:
#     age: 30
#     name: Alice

# Tabular array (uniform objects)
my $toon = Data::TOON->encode({
    users => [
        { id => 1, name => 'Alice' },
        { id => 2, name => 'Bob' }
    ]
});
# Output:
#   users[2]{id,name}:
#     1,Alice
#     2,Bob

# Tabular array with column priority
my $toon = Data::TOON->encode({
    users => [
        { id => 1, name => 'Alice', role => 'admin' },
        { id => 2, name => 'Bob', role => 'user' }
    ]
}, column_priority => ['id', 'name']);
# Output:
#   users[2]{id,name,role}:
#     1,Alice,admin
#     2,Bob,user

# List array (non-uniform objects)
my $toon = Data::TOON->encode({
    items => [
        { id => 1, name => 'Alice', extra => 'data' },
        { id => 2, name => 'Bob' }
    ]
});
# Output:
#   items[2]:
#     - extra: data
#       id: 1
#       name: Alice
#     - id: 2
#       name: Bob

# Root array
my $toon = Data::TOON->encode([1, 2, 3]);
# Output: [3]: 1,2,3

# Root primitive
my $toon = Data::TOON->encode(42);
# Output: 42

EXAMPLES AND PATTERNS

Configuration File

TOON is well-suited for configuration files:

app_name: MyApp
version: 1.0.0
debug: false
database:
  host: localhost
  port: 5432
  user: admin
  max_connections: 100
servers[3]{host,port,role}:
  web1.example.com,8080,primary
  web2.example.com,8080,secondary
  web3.example.com,8080,secondary

Data Exchange Format

For APIs and data interchange where readability matters:

response:
  status: success
  code: 200
  data[2]:
    - id: 1001
      name: Product A
      price: 29.99
      in_stock: true
    - id: 1002
      name: Product B
      price: 49.99
      in_stock: false

Handling Nested Structures

organization:
  name: Example Corp
  departments[2]:
    - name: Engineering
      teams[2]:
        - name: Backend
          members: 5
        - name: Frontend
          members: 3
    - name: Sales
      teams[1]:
        - name: Enterprise
          members: 8

TOON FORMAT FEATURES

Data Types

TOON supports JSON data types:

Delimiters

Three delimiter options for array values:

Comma (default): data[3]: a,b,c

Tab: data[3]: abc

Pipe: data[3|]: a|b|c

Use tab or pipe delimiters when values might contain commas.

String Escaping

Standard escape sequences are supported:

text: "Line 1\nLine 2"
path: "C:\\Program Files\\App"
json: "Use \" to escape quotes"

Root Forms

Documents can start with different root types:

# Root object (default)
name: Alice
age: 30

# Root primitive
42

# Root array
[3]: a,b,c

PERFORMANCE CONSIDERATIONS

SECURITY

Data::TOON includes several security features:

COMPATIBILITY

TOON SPECIFICATION COMPLIANCE

This implementation achieves 95%+ compliance with TOON Specification v1.0:

✓ Complete object support ✓ Complete array support (all 3 formats) ✓ All delimiters (comma, tab, pipe) ✓ Root forms (object, array, primitive) ✓ String escaping ✓ Canonical number form ✓ Security measures ✓ Full type inference

See TOON Specification for complete specification.

COMMON ERRORS AND TROUBLESHOOTING

"Maximum nesting depth exceeded"

If you encounter this error, your data is nested more than 100 levels deep:

# Increase max_depth
my $encoded = Data::TOON->encode($data, max_depth => 200);

"Circular reference detected"

Your data structure contains a reference to itself:

my $obj = { name => 'Alice' };
$obj->{self} = $obj;  # This creates a circle!

Solution: Remove the circular reference before encoding.

Inconsistent type inference

If values aren't being parsed as expected, use explicit quoting:

# Without quotes - might be interpreted as number
value: 42

# With quotes - definitely a string
value: "42"

SEE ALSO

LICENSE

Copyright (C) ytnobody.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

ytnobody ytnobody@gmail.com