/ 
Template-Sandbox-1.00_01
River stage one • 2 direct dependents • 2 total dependents
/ Template::Sandbox::Library

NAME

Template::Sandbox::Library - Base library object for Template::Sandbox functions.

SYNOPSIS

package MyApp::TemplateMaths;

use base qw/Template::Sandbox::Library/;

use Template::Sandbox qw/:function_sugar/;

__PACKAGE__->set_library_functions(
      tan     => ( one_arg sub { sin( $_[ 0 ] ) / cos( $_[ 0 ] ) } ),
      atan    => ( two_args sub { atan2( $_[ 0 ], $_[ 1 ] ) } ),
      sin     => ( one_arg sub { sin( $_[ 0 ] ) } ),
      cos     => ( one_arg sub { cos( $_[ 0 ] ) } ),

      exp     => ( one_arg sub { exp( $_[ 0 ] ) } ),
      log     => ( one_arg sub { log( $_[ 0 ] ) } ),
      pow     => ( two_args sub { $_[ 0 ] ** $_[ 1 ] } ),
      sqrt    => ( one_arg sub { sqrt( $_[ 0 ] ) } ),
      );
__PACKAGE__->set_library_tags(
      trig => [ qw/tan atan sin cos/ ],
      );

1;

#  Elsewhere in your app.

#  Registers all my trig template functions (tan, tan sig cos)
#  with Template::Sandbox at the class level (for every template)
use Template::Sandbox;
use MyApp::TemplateMaths qw/:trig/;

#  or for registering to a template instance individually:
use Template::Sandbox;
use MyApp::TemplateMaths;

my $template = Template::Sandbox->new();
MyApp::TemplateMaths->export_template_functions(
    $template, qw/:trig/ );

#  or more conveniently:
my $template = Template::Sandbox->new(
    library => [ MyApp::TemplateMaths => qw/:trig/ ],
    );

#  or for several libraries:
my $template = Template::Sandbox->new(
    library => [ MyApp::TemplateMaths => qw/:trig/ ],
    library => [ MyApp::TemplateHTML  => qw/uri_escape html_escape/ ],
    );

#  but NOT this:
my $template = Template::Sandbox->new(
    library => [
        #  WRONG!  Everything after this next => will be taken as
        #  a function name or tag to try to export to your template.
        MyApp::TemplateMaths => qw/:trig/,
        MyApp::TemplateHTML  => qw/uri_escape html_escape/,
      ],
    );

DESCRIPTION

Template::Sandbox::Library is a base class for easily defining libraries of template functions to add to the sandbox your Template::Sandbox runs in.

It works by storing a hash of function names to functions definitions, and a hash of tag names to function names, then you can export individual functions or groups of functions into a Template::Sandbox instance (or the entire class) in a similar way to importing functions into a package via Exporter.

FUNCTIONS AND METHODS

Note that these functions and methods are not to be called directly on Template::Sandbox::Library, they should be called on subclasses of it.

import()

Called automatically by use, this will take the Exporter style arguments to use and build a list of functions to register with Template::Sandbox at the class level (global to all templates.)

You probably shouldn't call import() directly yourself, you should only access it via use, if you want to manually export template functions, use export_template_functions() detailed below.

$library->export_template_functions( $template, @names )

Exports the given names into $template as template functions.

Each entry in @names should follow a form familiar to users of Exporter, it's either a literal function name, or if it starts with a ':' it's a tag name for a list of functions, or if it starts with a '!' it means to remove the name from the list of things to export, some examples make this clearer:

'atan'     #  The function named 'atan'
':trig'    #  The functions in the group tagged 'trig'
'!atan'    #  Remove the function named 'atan' from the list to export
'!:trig'   #  Remove the 'trig' group of functions from the list

So to import all trig functions except atan you could do the following:

MyApp::TemplateMaths->export_template_functions(
    $template, qw/:trig !atan/,
    );

Or for all functions, except trig functions, but including atan:

MyApp::TemplateMaths->export_template_functions(
    $template, qw/:all !:trig atan/,
    );
$library->set_library_functions( %functions )

Sets the template functions that this library knows about, overwriting any previous definitions and removing any existing functions from the library that don't exist in the new hash.

The %functions hash should be a list of function names to function definitions, either as subroutine references or, preferably, as function definitions produced by the function sugar functions provided by Template::Sandbox.

See the "SYNOPSIS" for some examples.

$library->set_library_tags( %tags )

Sets the export tags that this library knows about, overwriting any previous definitions and removing any existing tags from the library that don't exist in the new hash.

The %tags hash should be a hash of tag names to a list of function names that exist in the %functions passed to $library->set_library_functions().

The 'all' group is automatically created for you if you haven't set it already.

KNOWN ISSUES AND BUGS

None currently known.

SEE ALSO

Template::Sandbox

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Template::Sandbox::Library

You can also look for information at:

AUTHORS

Original author: Sam Graham <libtemplate-sandbox-perl BLAHBLAH illusori.co.uk>

Last author: $Author: illusori $

COPYRIGHT & LICENSE

Copyright 2005-2009 Sam Graham, all rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.