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, 2013 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.