NAME

Badger::Codec::TT - encode/decode data using TT data syntax

SYNOPSIS

    use Badger::Codec::TT;
    my $codec   = Badger::Codec::TT->new();
    my $encoded = $codec->encode({ msg => "Hello World" });
    my $decoded = $codec->decode($encoded);

DESCRIPTION

This module implements a subclass of Badger::Codec which encodes and decodes data to and from an extended form of the data definition syntax used in the Template Toolkit. It mainly exists for testing purposes (so that we don't require people to install YAML or JSON just to run some of the Badger tests) and to support some legacy systems that use data encoded in this way (mostly dating back to the days before YAML and JSON were around). If you're starting out afresh then you're probably better off using YAML or JSON unless you have good reason not to.

The syntax is similar to Perl in that it uses single quotes for literal strings, square brackets for list definitions and curly braces for hash definitions along with the "=>" "fat comma" operator to separate hash keys and values. Data structures can be nested indefinitely. The unquoted "undef" token can be used to explicitly represent the undefined value.

    {
        message => 'Hello World, this is some text',
        things  => ['a list', 'of some things'],
        stuff   => {
            pi  => 3.14,
            foo => [ { nested => 'hash' }, ['nested', 'list' ] ],
            nul => undef,
        },
    }

TT syntax is more liberal than Perl. It allows you to use "=" instead of "=>" to separate keys and values in hash arrays, and commas between items are optional.

    {
        message = 'Hello World, this is some text'
        things  = ['a list' 'of some things']
        stuff   = {
            pi  = 3.14
            foo = [ { nested = 'hash' } ['nested' 'list' ] ]
            nul = undef
        }
    }

It will also accept ":" as a delimiter between hash keys and values, thus providing an overlap with a useful subset of JSON syntax:

    {
        message: 'Hello World, this is some text',
        things: ['a list' 'of some things'],
        stuff: {
            pi:  3.14,
            foo: [ { nested: 'hash' }, ['nested', 'list' ] ],
            nul: undef
        }
    }

The decoder is very liberal in what it will accept for delimiters. You can mix and match any of the above styles in the same document if you really want to. However, you would be utterly batshit insane to do such a thing, let alone want for it. Just because we'll accept any of the commonly used formats doesn't mean that you should be using them all at once.

    {
        perl => 'Perl looks like this',
        tt   =  'TT looks like this'
        json: 'JSON looks like this
    }

Note that while the syntax may be more liberal than either Perl or JSON, the semantics are decidedly stricter. It is not possible to embed arbitrary Perl code, instantiate Javascript objects, or do anything else outside of defining vanilla data structures.

The encoder generates TT syntax by default ("=" for assignment, with a single space to delimiter items). You can change these options using the "assign" and "comma" configuration options.

    my $codec = Badger::Codec::TT->new( assign => '=>', comma => ',' );
    print $codec->encode($some_data);

METHODS

encode($data)

Encodes the Perl data in $data to a TT string.

    $encoded = Badger::Codec::TT->encode($data);

decode($tt)

Decodes the encoded TT string in $tt back into a Perl data structure.

    $decoded = Badger::Codec::TT->decode($encoded);

encoder()

This method returns a reference to an encoding subroutine.

    my $sub = Badger::Codec::TT->encoder;
    $encoded = $sub->($data);

decoder()

This method returns a reference to a decoding subroutine.

    my $sub = Badger::Codec::TT->decoder;
    $decoded = $sub->($encoded);

INTERNAL SUBROUTINES

_encode($data)

This internal subroutine performs the recursive encoding of the data.

_decode($tt)

This internal subroutine performs the recursive decoding of the data.

AUTHOR

Andy Wardley <http://wardley.org/>