The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Template-Sandbox-1.04_01
River stage one • 2 direct dependents • 2 total dependents
++
/ Template::Sandbox::Library

NAME

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

VERSION

version 1.04_01

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:

AUTHOR

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

COPYRIGHT AND LICENSE

This software is copyright (c) 2005-2010 by Sam Graham <libtemplate-sandbox-perl BLAHBLAH illusori.co.uk>.

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