oracular (3) Badger::Codec::TT.3pm.gz

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/>

COPYRIGHT

       Copyright (C) 2005-2009 Andy Wardley. All rights reserved.

SEE ALSO

       Badger::Codecs, Badger::Codec, Template