NAME
    JSON::T - transform JSON using JsonT

SYNOPSIS
     my $jsont = slurp('foo/bar.js');
     my $input = slurp('foo/quux.json');
     my $JSONT = JSON::T->new($jsont);
     print $JSONT->transform($input);

DESCRIPTION
    This module implements JsonT, a language for transforming JSON-like
    structures, analogous to XSLT in the XML world.

    JsonT is described at <http://goessner.net/articles/jsont/>. JsonT is a
    profile of Javascript; so JsonT needs a Javascript engine to actually
    work. This module provides the engine-neutral stuff, while JSON::T::JE
    and JSON::T::SpiderMonkey provide the necessary glue to hook it up to a
    couple of Javascript engines.

    JSON::T::JE uses the pure Perl Javascript implementation JE.

    JSON::T::SpiderMonkey uses JavaScript::SpiderMonkey which in turn is
    backed by Mozilla's libjs C library.

    This module tries to provide a similar API to XML::Saxon::XSLT2.

  Constructor
    "new($code, $name)"
        Constructs a new JSON::T transformation. $code is the JsonT
        Javascript code. As a JsonT file can contain multiple (potentially
        unrelated) transformations, the name of the particular
        transformation you want to use should also be provided. If $name is
        omitted, then the name "_main" is assumed.

        If you wish to use a particular Javascript implementation, you can
        use, for example:

          JSON::T::SpiderMonkey->new($code, $name)

        Otherwise

          JSON::T->new($code, $name)

        will try to pick a working implementation for you.

  Methods
    "parameters(param1=>$arg1, param2=>$arg2, ...)"
        Sets global variables available to the Javascript code. All
        arguments are treated as strings.

    "transform($input)"
        Run the transformation. The input may be a JSON string, a
        JSON::JOM::Node or a native Perl nested arrayref/hashref structure,
        in which case it will be stringified using the JSON module's to_json
        function. The output (return value) will be a string.

    "transform_structure($input)"
        Like "transform", but attempts to parse the output as a JSON string
        and return a native Perl arrayref/hashref structure. This method
        will fail if the output is not a JSON string.

    "DOES($role)"
        Like UNIVERSAL's DOES method, but returns true for:

          JSON::T->DOES('XML::Saxon::XSLT2')

        as an aid for polymorphism.

    The following methods also exist for compatibility with
    XML::Saxon::XSLT2, but are mostly useless:

    "transform_document"
    "messages"
    "media_type"
    "version"
    "doctype_system"
    "doctype_public"
    "encoding"

  Javascript Execution Environment
    JSON::T is a profile of Javascript, so is evaluated in an execution
    environment. As this is not a browser environment, many global objects
    familiar to browser Javascript developers are not available. (For
    example, "window", "document", "navigator", etc.)

    A single global object called "JSON" is provided with methods
    "stringify" and "parse" compatible with the well-known json2.js library
    (<http://www.JSON.org/json2.js>), and a method "transform(obj,jsont)"
    that provides a Javascript JsonT implementation.

    A function "print_to_perl" is provided which prints to Perl's STDOUT
    stream.

SUBCLASSING
    Two subclasses are provided: JSON::T::JE and JSON::T::SpiderMonkey, but
    if you need to hook JSON::T up to another Javascript engine, it is
    relatively simple. Just create a Perl class which is a subclass of
    JSON::T. This subclass must implement two required methods and should
    implement one optional method.

    "init"
        Will be passed a newly created object (let's call it $self). It is
        expected to initialise a Javascript execution context for $self, and
        define two Javascript functions: "return_to_perl" (which acts as a
        shim to "$self->_accept_return_value()") and "print_to_perl" (which
        acts as a shim to "print"). It must then call "SUPER::init".

    "engine_eval"
        Will be passed an object ($self) and a Javascript string. Must
        evaluate the string in the object's Javascript execution context.

    "parameters"
        This one is optional to implement it. If you don't implement it,
        then users will get a warning message if they try to call
        "parameters" on your subclass.

        Will be passed an object ($self) and a hash of parameters, using the
        following format:

          (
            name1  => 'value1',
            name2  => [ type2 => 'value2' ],
            name3  => [ type3 => 'value3', hint => 'hint value' ],
          )

        This should have the effect of setting:

          var name1 = 'value1';
          var name2 = 'value2';
          var name3 = 'value3';

        in the object's Javascript execution context. Parameter types and
        additional hints may be used to set the correct types in Javascript.

    You are unlikely to need to do anything else when subclassing.

    If you wish "JSON::T->new" to know about your subclass, then push its
    name onto @JSON::T::Implementations.

BUGS
    Please report any bugs to <http://rt.cpan.org/>.

SEE ALSO
    Specification: <http://goessner.net/articles/jsont/>.

    Related modules: JSON, JSON::Path, JSON::GRDDL, JSON::Hyper,
    JSON::Schema.

    JOM version: JSON::JOM, JSON::JOM::Plugins::JsonT.

AUTHOR
    Toby Inkster <tobyink@cpan.org>.

    This module is embeds Stefan Goessner's Javascript implementation of
    JsonT (version 0.9) to do the heavy lifting.

COPYRIGHT AND LICENCE
    Copyright 2006 Stefan Goessner.

    Copyright 2008-2011 Toby Inkster.

    Licensed under the Lesser GPL:
    <http://creativecommons.org/licenses/LGPL/2.1/>.

DISCLAIMER OF WARRANTIES
    THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
    WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
    MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.