/ 
TOON-XS-0.001
/ TOON::XS

NAME

TOON::XS - Token-Oriented Object Notation for Perl in XS

VERSION

version 0.001

SYNOPSIS

use TOON::XS qw(
    encode_toon
    decode_toon

    encode_line_toon
    decode_line_toon

    encode_brace_toon
    decode_brace_toon

    validate_line_toon
    validate_brace_toon
);

my $line = encode_line_toon({ id => 1 });
my $obj1 = decode_line_toon($line);

my $brace = encode_brace_toon({ answer => 42 }, canonical => 1);
my $obj2  = decode_brace_toon($brace);

my $explicit = encode_toon({ answer => 42 }, syntax => 'brace');

my $toon = TOON::XS->new(syntax => 'brace')->pretty->canonical;
my $text = $toon->encode({ answer => 42 });

DESCRIPTION

TOON::XS provides a super fast implementation of TOON that can handle both line-style and brace-style TOON syntax, meaning it could replace both TOON and Data::TOON. However, it's in XS (i.e., C). But it's only requiring 5.10.

It supports both functional interface and object-oriented interface. For funsies.

The generic encode_toon / decode_toon functions require an explicit syntax parameter and do not assume defaults.

PERFORMANCE

TOON vs. TOON::XS:

  • TOON brace encode: 4.178e-01 +/- 1.1e-03 (0.3%)

  • TOON brace decode: 1.7438e+00 +/- 3.1e-03 (0.2%)

  • TOON::XS brace encode: 9.873e-02 +/- 1.3e-04 (0.1%)

  • TOON::XS brace decode: 4.3244e-02 +/- 2.2e-05 (0.1%)

Data::TOON vs. TOON::XS:

  • Data::TOON line encode: 5.0582e-01 +/- 5.1e-04 (0.1%)

  • Data::TOON line decode: 8.479e-01 +/- 1.5e-03 (0.2%)

  • TOON::XS line encode: 1.2367e-01 +/- 2.9e-04 (0.2%)

  • TOON::XS line decode: 8.957e-02 +/- 1.7e-04 (0.2%)

Totals

So basically, encoding is >4x faster (whether brace-basedd or line-based).

  • If you're using line-based, decoding is almost 10x faster.

  • If you're using brace-based, decoding is about 40x faster.

I hope that's fast enough.

FUNCTIONS

encode_line_toon

my $text = encode_line_toon({'foo' => 'bar', 'baz' => [0..3]});

# baz[4]:
#   - 0
#   - 1
#   - 2
#   - 3
# foo: bar

Encodes a Perl data structure into line-style TOON.

Supports encoder options such as delimiter, column_priority, and max_depth.

Returns TOON text.

decode_line_toon

my $data = decode_line_toon($text);

Decodes line-style TOON text into Perl data.

May throw on invalid input.

validate_line_toon

my $ok = validate_line_toon($text);

Validates line-style TOON text.

Returns 1 for valid input and 0 for invalid input.

encode_brace_toon

my $text = encode_brace_toon({'foo' => 'bar', 'baz' => [0..3]});

# {foo: "bar", baz: [0, 1, 2, 3]}

Encodes a Perl data structure into brace-style TOON.

Supports encoder options such as pretty, canonical, and indent.

Returns TOON text.

decode_brace_toon

my $data = decode_brace_toon($text);

Decodes brace-style TOON text into Perl data.

May throw on invalid input.

validate_brace_toon

my $ok = validate_brace_toon($text);

Validates brace-style TOON text by attempting to decode it.

Returns 1 for valid input and 0 for invalid input.

encode_toon

my $data = encode_toon(
    { 'foo' => 'bar', 'baz' => [0..3] },
    'syntax' => 'line', # or 'brace',
);

Requires syntax => 'line' | 'brace'.

Dispatches to encode_line_toon or encode_brace_toon.

decode_toon

my $value = decode_toon($text, syntax => 'line');

Requires syntax => 'line' | 'brace'.

Dispatches to decode_line_toon or decode_brace_toon.

METHODS

new

my $toon = TOON::XS->new(
    syntax    => 'line', # required: 'line' or 'brace'
    pretty    => 0,
    canonical => 0,
    indent    => 2,
);

Constructs an encoder/decoder object with persistent defaults.

Unlike the function API, syntax is required here.

encode

my $text = $toon->encode($data, %overrides);

Object method only. Uses the object's syntax option.

Per-call %overrides are merged over object defaults.

decode

my $data = $toon->decode($text, %overrides);

Object method only. Uses the object's syntax option.

Per-call %overrides are merged over object defaults.

validate

my $ok = $toon->validate($text, %overrides);

Object method only. Uses the object's syntax option.

Per-call %overrides are merged over object defaults.

pretty

$toon->pretty;    # enable
$toon->pretty(0); # disable

Setter for the brace encoder pretty flag.

Returns $self.

canonical

$toon->canonical;    # enable
$toon->canonical(0); # disable

Setter for the brace encoder canonical flag.

Returns $self.

indent

$toon->indent(4);

Setter for the brace encoder indentation width.

Returns $self.

syntax

$toon->syntax('line'); # or 'brace'

Setter for object syntax mode used by encode, decode, and validate.

Returns $self.

AUTHOR

Sawyer X <xsawyerx@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2026 by Sawyer X.

This is free software, licensed under:

The MIT (X11) License