Any::Renderer - Common API for modules that convert data structures into strings
$renderer = new Any::Renderer ( $format, \%options ); $string = $renderer->render ( $structure ); $bool = Any::Renderer::requires_template ( $format ); $list_ref = Any::Renderer::available_formats (); $list_ref = Any::Renderer::failed_backends (); $string = Any::Renderer::failed_backend_message($backend_name);
A renderer in this context is something that turns a data structure into a string. This includes templating engines, serialisers etc.
This module provides a consistent API to these services so that your application can generate output in an extensible variety of formats. Formats currently supported include:
- XML (via XML::Simple) - XML+XSLT - Data::Dumper - Javascript, Javascript::Anon & JSON - UrlEncoded - The formats supported by Data::Serializer (e.g. Config::General and Config::Wrest) - Any templating language supported by Any::Template
The module will discover any backend modules and offer up their formats. Once loaded, Any::Renderer will look for a module to handle any new formats it doesn't know about, so adding new formats in a persistent environment won't require the module to be reloaded. However if you CHANGE which module provides a format you will need to reload Any::Renderer (e.g. send a SIGHUP to modperl).
Create a new instance of an Any::Render object using a rendering format of $format and the options listed in the hash %options (see individual rendering module documentation for details of which options various modules accept).
Render the data structure $data_structure with the Any::Renderer object $r. The resulting string will be returned.
Determine whether or not the rendering format $format requires a template to be passed as an option to the object constructor. If the format does require a template than 1 will be returned, otherwise 0.
Discover a list of all known rendering formats that the backend modules provide, e.g. ( 'HTML::Template', 'JavaScript' [, ...]).
Retuns all backends that failed to load
Return the error message for a backend
A list of backend providers which have lower precedence (if there is more than one module which provides a given format). The earlier things appear in this list, the lower the precedence.
Defaults to Data::Serializer as this provides both XML::Simple and Data::Dumper (which have native Any::Renderer backends).
Data::Serializer
Back-end modules should have the same public interface as Any::Renderer itself:
For example:
package Any::Renderer::MyFormat; sub new { my ( $class, $format, $options ) = @_; die("Invalid format $format") unless($format eq 'MyFormat'); return bless({}, $class); #More complex classes might stash away options and format } sub render { my ( $self, $data ) = @_; return _my_format($data); } sub requires_template { die("Invalid format") unless($_[0] eq 'MyFormat'); return 0; #No template required } sub handle_formats { return [ 'MyFormat' ]; #Just the one }
http://search.cpan.org/dist/Any-Renderer. Each module lists the formats it supports in the FORMATS section. Many of also include sample output fragments.
A templating engine is a special case of a renderer (one that uses a template, usually from a file or string, to control formatting). If you are considering exposing another templating language via Any::Renderer, instead consider exposing it via Any::Template. All the templating engines supported by Any::Template are automatically available via Any::Renderer.
A serializer is a special case of a renderer which offers bidirectional processing (rendering == serialization, deserialisation does not map to the renderer interface). If you are considering exposing another serialization mechanism via Any::Renderer, instead consider exposing it via Data::Serializer. All the serializers supported by Data::Serializer are automatically available via Any::Renderer.
Current: Kevin McGrath
Pre-v1.015 Matt Wilson (original version by John Alden) <cpan _at_ bbc _dot_ co _dot_ uk>
(c) BBC 2006. This program is free software; you can redistribute it and/or modify it under the GNU GPL.
See the file COPYING in this distribution, or http://www.gnu.org/licenses/gpl.txt
To install Any::Renderer, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Any::Renderer
CPAN shell
perl -MCPAN -e shell install Any::Renderer
For more information on module installation, please visit the detailed CPAN module installation guide.