view release on metacpan or  search on metacpan

lib/Data/TOON.pm  view on Meta::CPAN

package Data::TOON;
use 5.014;
use strict;
use warnings;

use Data::TOON::Encoder;
use Data::TOON::Decoder;
use Data::TOON::Validator;

our $VERSION = "0.03";

=encoding utf-8

=head1 NAME

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

=head1 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

=head1 DESCRIPTION

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

TOON provides:

=over 4

=item * B<Human-readable syntax> - Indentation-based, similar to YAML, with minimal quoting

=item * B<Multiple array formats> - Compact tabular, explicit list, or inline primitive arrays

=item * B<Flexible delimiters> - Support for comma, tab, and pipe delimiters

=item * B<Security> - DoS protection via depth limits and circular reference detection

=item * B<Canonical numbers> - Automatic number normalization (removes trailing zeros, etc.)

=item * B<Full TOON compliance> - 95%+ coverage of TOON specification v1.0

=back

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

=head1 METHODS

=head2 encode( $data, %options )

Encodes a Perl data structure to TOON format string.

B<Parameters:>

=over 4