/ 
Template-Sandbox-1.04
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):

use Template::Sandbox::NumberFunctions qw/:all/;

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/,
    );

For convenience this method can automatically be called as part of your template constructor with the library option, for example the previous example could be written as:

use Template::Sandbox;
use MyApp::TemplateMaths;

$template = Template::Sandbox->new(
    library => [ 'MyApp::TemplateMaths' => 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, Template::Sandbox::StringFunctions, Template::Sandbox::NumberFunctions

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-2010 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.