view release on metacpan or  search on metacpan

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

=item B<Number> - Integer or float (canonicalized)

    count: 42
    ratio: 3.14

=item B<Boolean> - true or false

    active: true
    deleted: false

=item B<Null> - Null value

    optional_field: null

=back

=head2 Delimiters

Three delimiter options for array values:

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

B<Tab:>
    data[3<TAB>]: a<TAB>b<TAB>c

B<Pipe:>
    data[3|]: a|b|c

Use tab or pipe delimiters when values might contain commas.

=head2 String Escaping

Standard escape sequences are supported:

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

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

=head1 PERFORMANCE CONSIDERATIONS

=over 4

=item * Encoding is O(n) in data size
=item * Decoding is O(n) in text size
=item * Memory usage is proportional to data complexity
=item * Large documents (>100MB) may require streaming parser

=back

=head1 SECURITY

Data::TOON includes several security features:

=over 4

=item B<Depth Limiting> - Prevents stack overflow from deeply nested structures
    Default max_depth: 100 levels
    Configurable via encode/decode options

=item B<Circular Reference Detection> - Prevents infinite loops during encoding
    Automatically detects and rejects circular references

=item B<Input Validation> - Strict parsing rules prevent injection attacks
    All strings are treated as literal values
    No code evaluation or command injection possible

=back

=head1 COMPATIBILITY

=over 4

=item * Perl 5.14 or later
=item * No external dependencies
=item * Pure Perl implementation (portable)

=back

=head1 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 L<TOON Specification|https://github.com/toon-format/spec/blob/main/SPEC.md> for complete specification.

=head1 COMMON ERRORS AND TROUBLESHOOTING

=head2 "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);

=head2 "Circular reference detected"

Your data structure contains a reference to itself: