[Templates-svn] r1078 - in trunk/lib: . Template Template/Manual
svn@template-toolkit.org
svn@template-toolkit.org
Author: abw
Date: 2007-05-14 20:20:05 +0100 (Mon, 14 May 2007)
New Revision: 1078
Modified:
trunk/lib/Template.pm
trunk/lib/Template/Base.pm
trunk/lib/Template/Config.pm
trunk/lib/Template/Constants.pm
trunk/lib/Template/Context.pm
trunk/lib/Template/Directive.pm
trunk/lib/Template/Document.pm
trunk/lib/Template/Exception.pm
trunk/lib/Template/Filters.pm
trunk/lib/Template/Grammar.pm
trunk/lib/Template/Iterator.pm
trunk/lib/Template/Manual/Config.pod
trunk/lib/Template/Map.pm
trunk/lib/Template/Parser.pm
trunk/lib/Template/Plugin.pm
trunk/lib/Template/Plugins.pm
trunk/lib/Template/Provider.pm
Log:
big documentation cleanup - no longer using docsrc
Modified: trunk/lib/Template/Base.pm
===================================================================
--- trunk/lib/Template/Base.pm 2007-05-07 08:22:43 UTC (rev 1077)
+++ trunk/lib/Template/Base.pm 2007-05-14 19:20:05 UTC (rev 1078)
@@ -10,15 +10,11 @@
# Andy Wardley <abw@wardley.org>
#
# COPYRIGHT
-# Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
-# Copyright (C) 1998-2000 Canon Research Centre Europe Ltd.
+# Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
#
# This module is free software; you can redistribute it and/or
# modify it under the same terms as Perl itself.
#
-# REVISION
-# $Id$
-#
#========================================================================
package Template::Base;
@@ -27,7 +23,7 @@
use warnings;
use Template::Constants;
-our $VERSION = 2.77;
+our $VERSION = 2.78;
#------------------------------------------------------------------------
@@ -43,9 +39,9 @@
sub new {
my $class = shift;
my ($argnames, @args, $arg, $cfg);
-# $class->error(''); # always clear package $ERROR var?
+# $class->error(''); # always clear package $ERROR var?
- { no strict qw( refs );
+ { no strict qw( refs );
$argnames = \@{"$class\::BASEARGS"} || [ ];
}
@@ -151,18 +147,6 @@
__END__
-
-#------------------------------------------------------------------------
-# IMPORTANT NOTE
-# This documentation is generated automatically from source
-# templates. Any changes you make here may be lost.
-#
-# The 'docsrc' documentation source bundle is available for download
-# from http://www.template-toolkit.org/docs.html and contains all
-# the source templates, XML files, scripts, etc., from which the
-# documentation for the Template Toolkit is built.
-#------------------------------------------------------------------------
-
=head1 NAME
Template::Base - Base class module implementing common functionality
@@ -171,16 +155,16 @@
package My::Module;
use base qw( Template::Base );
-
+
sub _init {
- my ($self, $config) = @_;
- $self->{ doodah } = $config->{ doodah }
- || return $self->error("No 'doodah' specified");
- return $self;
+ my ($self, $config) = @_;
+ $self->{ doodah } = $config->{ doodah }
+ || return $self->error("No 'doodah' specified");
+ return $self;
}
-
+
package main;
-
+
my $object = My::Module->new({ doodah => 'foobar' })
|| die My::Module->error();
@@ -195,10 +179,10 @@
Constructor method which accepts a reference to a hash array or a list
of C<name =E<gt> value> parameters which are folded into a hash. The
-_init() method is then called, passing the configuration hash and should
+C<_init()> method is then called, passing the configuration hash and should
return true/false to indicate success or failure. A new object reference
is returned, or undef on error. Any error message raised can be examined
-via the error() class method or directly via the package variable ERROR
+via the L<error()> class method or directly via the C<$ERROR> package variable
in the derived class.
my $module = My::Module->new({ ... })
@@ -209,63 +193,63 @@
=head2 error($msg, ...)
-May be called as an object method to get/set the internal _ERROR member
-or as a class method to get/set the $ERROR variable in the derived class's
+May be called as an object method to get/set the internal C<_ERROR> member
+or as a class method to get/set the C<$ERROR> variable in the derived class's
package.
my $module = My::Module->new({ ... })
|| die My::Module->error(), "\n";
$module->do_something()
- || die $module->error(), "\n";
+ || die $module->error(), "\n";
When called with parameters (multiple params are concatenated), this
method will set the relevant variable and return undef. This is most
often used within object methods to report errors to the caller.
package My::Module;
-
+
sub foobar {
- my $self = shift;
-
- # some other code...
-
- return $self->error('some kind of error...')
- if $some_condition;
+ my $self = shift;
+
+ # some other code...
+
+ return $self->error('some kind of error...')
+ if $some_condition;
}
=head2 debug($msg, ...)
Generates a debugging message by concatenating all arguments
-passed into a string and printing it to STDERR. A prefix is
+passed into a string and printing it to C<STDERR>. A prefix is
added to indicate the module of the caller.
package My::Module;
-
+
sub foobar {
- my $self = shift;
-
- $self->debug('called foobar()');
-
- # some other code...
+ my $self = shift;
+
+ $self->debug('called foobar()');
+
+ # some other code...
}
-When the foobar() method is called, the following message
-is sent to STDERR:
+When the C<foobar()> method is called, the following message
+is sent to C<STDERR>:
[My::Module] called foobar()
-Objects can set an internal DEBUG value which the debug()
+Objects can set an internal C<DEBUG> value which the C<debug()>
method will examine. If this value sets the relevant bits
-to indicate DEBUG_CALLER then the file and line number of
+to indicate C<DEBUG_CALLER> then the file and line number of
the caller will be appened to the message.
use Template::Constants qw( :debug );
-
+
my $module = My::Module->new({
DEBUG => DEBUG_SERVICE | DEBUG_CONTEXT | DEBUG_CALLER,
});
-
+
$module->foobar();
This generates an error message such as:
@@ -276,27 +260,18 @@
Andy Wardley E<lt>abw@wardley.orgE<gt>
-L<http://wardley.org/|http://wardley.org/>
+L<http://wardley.org/>
-
-
-
-=head1 VERSION
-
-2.77, distributed as part of the
-Template Toolkit version 2.19, released on 27 April 2007.
-
=head1 COPYRIGHT
- Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
+Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
-
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
=head1 SEE ALSO
-L<Template|Template>
+L<Template>
=cut
Modified: trunk/lib/Template/Config.pm
===================================================================
--- trunk/lib/Template/Config.pm 2007-05-07 08:22:43 UTC (rev 1077)
+++ trunk/lib/Template/Config.pm 2007-05-14 19:20:05 UTC (rev 1078)
@@ -9,14 +9,11 @@
# Andy Wardley <abw@wardley.org>
#
# COPYRIGHT
-# Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
+# Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
#
# This module is free software; you can redistribute it and/or
# modify it under the same terms as Perl itself.
#
-# REVISION
-# $Id$
-#
#========================================================================
package Template::Config;
@@ -29,7 +26,7 @@
$LATEX_PATH $PDFLATEX_PATH $DVIPS_PATH
$STASH $SERVICE $CONTEXT $CONSTANTS @PRELOAD );
-$VERSION = 2.74;
+$VERSION = 2.75;
$DEBUG = 0 unless defined $DEBUG;
$ERROR = '';
$CONTEXT = 'Template::Context';
@@ -82,11 +79,7 @@
my ($class, $module) = @_;
$module =~ s[::][/]g;
$module .= '.pm';
-# print STDERR "loading $module\n"
-# if $DEBUG;
- eval {
- require $module;
- };
+ eval { require $module; };
return $@ ? $class->error("failed to load $module: $@") : 1;
}
@@ -104,11 +97,11 @@
sub parser {
my $class = shift;
my $params = defined($_[0]) && UNIVERSAL::isa($_[0], 'HASH')
- ? shift : { @_ };
+ ? shift : { @_ };
return undef unless $class->load($PARSER);
return $PARSER->new($params)
- || $class->error("failed to create parser: ", $PARSER->error);
+ || $class->error("failed to create parser: ", $PARSER->error);
}
@@ -122,7 +115,7 @@
sub provider {
my $class = shift;
my $params = defined($_[0]) && UNIVERSAL::isa($_[0], 'HASH')
- ? shift : { @_ };
+ ? shift : { @_ };
return undef unless $class->load($PROVIDER);
return $PROVIDER->new($params)
@@ -141,12 +134,12 @@
sub plugins {
my $class = shift;
my $params = defined($_[0]) && UNIVERSAL::isa($_[0], 'HASH')
- ? shift : { @_ };
+ ? shift : { @_ };
return undef unless $class->load($PLUGINS);
return $PLUGINS->new($params)
- || $class->error("failed to create plugin provider: ",
- $PLUGINS->error);
+ || $class->error("failed to create plugin provider: ",
+ $PLUGINS->error);
}
@@ -160,12 +153,12 @@
sub filters {
my $class = shift;
my $params = defined($_[0]) && UNIVERSAL::isa($_[0], 'HASH')
- ? shift : { @_ };
+ ? shift : { @_ };
return undef unless $class->load($FILTERS);
return $FILTERS->new($params)
- || $class->error("failed to create filter provider: ",
- $FILTERS->error);
+ || $class->error("failed to create filter provider: ",
+ $FILTERS->error);
}
@@ -182,7 +175,7 @@
return undef unless $class->load($ITERATOR);
return $ITERATOR->new($list, @_)
- || $class->error("failed to create iterator: ", $ITERATOR->error);
+ || $class->error("failed to create iterator: ", $ITERATOR->error);
}
@@ -196,11 +189,11 @@
sub stash {
my $class = shift;
my $params = defined($_[0]) && UNIVERSAL::isa($_[0], 'HASH')
- ? shift : { @_ };
+ ? shift : { @_ };
return undef unless $class->load($STASH);
return $STASH->new($params)
- || $class->error("failed to create stash: ", $STASH->error);
+ || $class->error("failed to create stash: ", $STASH->error);
}
@@ -214,11 +207,11 @@
sub context {
my $class = shift;
my $params = defined($_[0]) && UNIVERSAL::isa($_[0], 'HASH')
- ? shift : { @_ };
+ ? shift : { @_ };
return undef unless $class->load($CONTEXT);
return $CONTEXT->new($params)
- || $class->error("failed to create context: ", $CONTEXT->error);
+ || $class->error("failed to create context: ", $CONTEXT->error);
}
@@ -232,11 +225,11 @@
sub service {
my $class = shift;
my $params = defined($_[0]) && UNIVERSAL::isa($_[0], 'HASH')
- ? shift : { @_ };
+ ? shift : { @_ };
return undef unless $class->load($SERVICE);
return $SERVICE->new($params)
- || $class->error("failed to create context: ", $SERVICE->error);
+ || $class->error("failed to create context: ", $SERVICE->error);
}
@@ -251,12 +244,12 @@
sub constants {
my $class = shift;
my $params = defined($_[0]) && UNIVERSAL::isa($_[0], 'HASH')
- ? shift : { @_ };
+ ? shift : { @_ };
return undef unless $class->load($CONSTANTS);
return $CONSTANTS->new($params)
- || $class->error("failed to create constants namespace: ",
- $CONSTANTS->error);
+ || $class->error("failed to create constants namespace: ",
+ $CONSTANTS->error);
}
@@ -270,7 +263,7 @@
sub instdir {
my ($class, $dir) = @_;
my $inst = $INSTDIR
- || return $class->error("no installation directory");
+ || return $class->error("no installation directory");
$inst =~ s[/$][]g;
$inst .= "/$dir" if $dir;
return $inst;
@@ -306,18 +299,6 @@
__END__
-
-#------------------------------------------------------------------------
-# IMPORTANT NOTE
-# This documentation is generated automatically from source
-# templates. Any changes you make here may be lost.
-#
-# The 'docsrc' documentation source bundle is available for download
-# from http://www.template-toolkit.org/docs.html and contains all
-# the source templates, XML files, scripts, etc., from which the
-# documentation for the Template Toolkit is built.
-#------------------------------------------------------------------------
-
=head1 NAME
Template::Config - Factory module for instantiating other TT2 modules
@@ -333,64 +314,64 @@
way to create toolkit components and allows custom modules to be used in
place of the regular ones.
-Package variables such as $STASH, $SERVICE, $CONTEXT, etc., contain
-the default module/package name for each component (Template::Stash,
-Template::Service and Template::Context, respectively) and are used by
-the various factory methods (stash(), service() and context()) to load
-the appropriate module. Changing these package variables will cause
-subsequent calls to the relevant factory method to load and instantiate
-an object from the new class.
+Package variables such as C<$STASH>, C<$SERVICE>, C<$CONTEXT>, etc., contain
+the default module/package name for each component (L<Template::Stash>,
+L<Template::Service> and L<Template::Context>, respectively) and are used by
+the various factory methods (L<stash()>, L<service()> and L<context()>) to
+load the appropriate module. Changing these package variables will cause
+subsequent calls to the relevant factory method to load and instantiate an
+object from the new class.
=head1 PUBLIC METHODS
=head2 load($module)
-Load a module via require(). Any occurences of '::' in the module name
-are be converted to '/' and '.pm' is appended. Returns 1 on success
-or undef on error. Use $class-E<gt>error() to examine the error string.
+Load a module using Perl's L<require()>. Any occurences of 'C<::>' in the module
+name are be converted to 'C</>', and 'C<.pm>' is appended. Returns 1 on success or
+undef on error. Use C<$class-E<gt>error()> to examine the error string.
=head2 preload()
-This method preloads all the other Template::* modules that are likely
-to be used. It is called by the Template module when running under
-mod_perl ($ENV{MOD_PERL} is set).
+This method preloads all the other C<Template::*> modules that are likely to
+be used. It is called automatically by the L<Template> module when running
+under mod_perl (C<$ENV{MOD_PERL}> is set).
=head2 parser(\%config)
Instantiate a new parser object of the class whose name is denoted by
-the package variable $PARSER (default: Template::Parser). Returns
+the package variable C<$PARSER> (default: L<Template::Parser>). Returns
a reference to a newly instantiated parser object or undef on error.
=head2 provider(\%config)
-Instantiate a new template provider object (default: Template::Provider).
+Instantiate a new template provider object (default: L<Template::Provider>).
Returns an object reference or undef on error, as above.
=head2 plugins(\%config)
-Instantiate a new plugins provider object (default: Template::Plugins).
+Instantiate a new plugins provider object (default: L<Template::Plugins>).
Returns an object reference or undef on error, as above.
=head2 filters(\%config)
-Instantiate a new filter provider object (default: Template::Filters).
+Instantiate a new filter provider object (default: L<Template::Filters>).
Returns an object reference or undef on error, as above.
=head2 stash(\%vars)
-Instantiate a new stash object (Template::Stash or Template::Stash::XS
-depending on the default set at installation time) using the contents
-of the optional hash array passed by parameter as initial variable
-definitions. Returns an object reference or undef on error, as above.
+Instantiate a new stash object (L<Template::Stash> or L<Template::Stash::XS>
+depending on the default set at installation time) using the contents of the
+optional hash array passed by parameter as initial variable definitions.
+Returns an object reference or undef on error, as above.
=head2 context(\%config)
-Instantiate a new template context object (default: Template::Context).
+Instantiate a new template context object (default: L<Template::Context>).
Returns an object reference or undef on error, as above.
=head2 service(\%config)
-Instantiate a new template service object (default: Template::Service).
+Instantiate a new template service object (default: L<Template::Service>).
Returns an object reference or undef on error, as above.
=head2 instdir($dir)
@@ -401,40 +382,31 @@
# e.g. returns '/usr/local/tt2'
my $ttroot = Template::Config->instdir()
- || die "$Template::Config::ERROR\n";
+ || die "$Template::Config::ERROR\n";
# e.g. returns '/usr/local/tt2/templates'
my $template = Template::Config->instdir('templates')
- || die "$Template::Config::ERROR\n";
+ || die "$Template::Config::ERROR\n";
-Returns undef and sets $Template::Config::ERROR appropriately if the
+Returns C<undef> and sets C<$Template::Config::ERROR> appropriately if the
optional components of the Template Toolkit have not been installed.
=head1 AUTHOR
Andy Wardley E<lt>abw@wardley.orgE<gt>
-L<http://wardley.org/|http://wardley.org/>
+L<http://wardley.org/>
-
-
-
-=head1 VERSION
-
-2.74, distributed as part of the
-Template Toolkit version 2.19, released on 27 April 2007.
-
=head1 COPYRIGHT
- Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
+Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
-
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
=head1 SEE ALSO
-L<Template|Template>
+L<Template>
=cut
Modified: trunk/lib/Template/Constants.pm
===================================================================
--- trunk/lib/Template/Constants.pm 2007-05-07 08:22:43 UTC (rev 1077)
+++ trunk/lib/Template/Constants.pm 2007-05-14 19:20:05 UTC (rev 1078)
@@ -9,21 +9,16 @@
# Andy Wardley <abw@wardley.org>
#
# COPYRIGHT
-# Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
-# Copyright (C) 1998-2000 Canon Research Centre Europe Ltd.
+# Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
#
# This module is free software; you can redistribute it and/or
# modify it under the same terms as Perl itself.
#
-# REVISION
-# $Id$
-#
#============================================================================
package Template::Constants;
require Exporter;
-
use strict;
use warnings;
use base 'Exporter';
@@ -31,7 +26,7 @@
use vars qw( @EXPORT_OK %EXPORT_TAGS );
use vars qw( $DEBUG_OPTIONS @STATUS @ERROR @CHOMP @DEBUG);
-our $VERSION = 2.74;
+our $VERSION = 2.75;
#========================================================================
@@ -160,18 +155,6 @@
__END__
-
-#------------------------------------------------------------------------
-# IMPORTANT NOTE
-# This documentation is generated automatically from source
-# templates. Any changes you make here may be lost.
-#
-# The 'docsrc' documentation source bundle is available for download
-# from http://www.template-toolkit.org/docs.html and contains all
-# the source templates, XML files, scripts, etc., from which the
-# documentation for the Template Toolkit is built.
-#------------------------------------------------------------------------
-
=head1 NAME
Template::Constants - Defines constants for the Template Toolkit
@@ -182,103 +165,93 @@
=head1 DESCRIPTION
-The Template::Constants modules defines, and optionally exports into the
-caller's namespace, a number of constants used by the Template package.
+The C<Template::Constants> modules defines, and optionally exports into the
+caller's namespace, a number of constants used by the L<Template> package.
-Constants may be used by specifying the Template::Constants package
+Constants may be used by specifying the C<Template::Constants> package
explicitly:
use Template::Constants;
-
print Template::Constants::STATUS_DECLINED;
Constants may be imported into the caller's namespace by naming them as
options to the C<use Template::Constants> statement:
use Template::Constants qw( STATUS_DECLINED );
-
print STATUS_DECLINED;
Alternatively, one of the following tagset identifiers may be specified
-to import sets of constants; :status, :error, :all.
+to import sets of constants: 'C<:status>', 'C<:error>', 'C<:all>'.
use Template::Constants qw( :status );
-
print STATUS_DECLINED;
-See L<Exporter> for more information on exporting variables.
+Consult the documentation for the C<Exporter> module for more information
+on exporting variables.
=head1 EXPORTABLE TAG SETS
The following tag sets and associated constants are defined:
- :status
- STATUS_OK # no problem, continue
- STATUS_RETURN # ended current block then continue (ok)
- STATUS_STOP # controlled stop (ok)
- STATUS_DONE # iterator is all done (ok)
- STATUS_DECLINED # provider declined to service request (ok)
- STATUS_ERROR # general error condition (not ok)
+ :status
+ STATUS_OK # no problem, continue
+ STATUS_RETURN # ended current block then continue (ok)
+ STATUS_STOP # controlled stop (ok)
+ STATUS_DONE # iterator is all done (ok)
+ STATUS_DECLINED # provider declined to service request (ok)
+ STATUS_ERROR # general error condition (not ok)
- :error
- ERROR_RETURN # return a status code (e.g. 'stop')
- ERROR_FILE # file error: I/O, parse, recursion
- ERROR_UNDEF # undefined variable value used
- ERROR_PERL # error in [% PERL %] block
- ERROR_FILTER # filter error
- ERROR_PLUGIN # plugin error
+ :error
+ ERROR_RETURN # return a status code (e.g. 'stop')
+ ERROR_FILE # file error: I/O, parse, recursion
+ ERROR_UNDEF # undefined variable value used
+ ERROR_PERL # error in [% PERL %] block
+ ERROR_FILTER # filter error
+ ERROR_PLUGIN # plugin error
- :chomp # for PRE_CHOMP and POST_CHOMP
- CHOMP_NONE # do not remove whitespace
- CHOMP_ONE # remove whitespace to newline
- CHOMP_ALL # old name for CHOMP_ONE (deprecated)
- CHOMP_COLLAPSE # collapse whitespace to a single space
- CHOMP_GREEDY # remove all whitespace including newlines
+ :chomp # for PRE_CHOMP and POST_CHOMP
+ CHOMP_NONE # do not remove whitespace
+ CHOMP_ONE # remove whitespace to newline
+ CHOMP_ALL # old name for CHOMP_ONE (deprecated)
+ CHOMP_COLLAPSE # collapse whitespace to a single space
+ CHOMP_GREEDY # remove all whitespace including newlines
- :debug
- DEBUG_OFF # do nothing
- DEBUG_ON # basic debugging flag
- DEBUG_UNDEF # throw undef on undefined variables
- DEBUG_VARS # general variable debugging
- DEBUG_DIRS # directive debugging
- DEBUG_STASH # general stash debugging
- DEBUG_CONTEXT # context debugging
- DEBUG_PARSER # parser debugging
- DEBUG_PROVIDER # provider debugging
- DEBUG_PLUGINS # plugins debugging
- DEBUG_FILTERS # filters debugging
- DEBUG_SERVICE # context debugging
- DEBUG_ALL # everything
- DEBUG_CALLER # add caller file/line info
- DEBUG_FLAGS # bitmap used internally
+ :debug
+ DEBUG_OFF # do nothing
+ DEBUG_ON # basic debugging flag
+ DEBUG_UNDEF # throw undef on undefined variables
+ DEBUG_VARS # general variable debugging
+ DEBUG_DIRS # directive debugging
+ DEBUG_STASH # general stash debugging
+ DEBUG_CONTEXT # context debugging
+ DEBUG_PARSER # parser debugging
+ DEBUG_PROVIDER # provider debugging
+ DEBUG_PLUGINS # plugins debugging
+ DEBUG_FILTERS # filters debugging
+ DEBUG_SERVICE # context debugging
+ DEBUG_ALL # everything
+ DEBUG_CALLER # add caller file/line info
+ DEBUG_FLAGS # bitmap used internally
- :all All the above constants.
+ :all
+ All the above constants.
=head1 AUTHOR
Andy Wardley E<lt>abw@wardley.orgE<gt>
-L<http://wardley.org/|http://wardley.org/>
+L<http://wardley.org/>
-
-
-
-=head1 VERSION
-
-2.74, distributed as part of the
-Template Toolkit version 2.19, released on 27 April 2007.
-
=head1 COPYRIGHT
- Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
+Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
-
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
=head1 SEE ALSO
-L<Template|Template>, L<Exporter|Exporter>
+L<Template>, C<Exporter>
=cut
Modified: trunk/lib/Template/Context.pm
===================================================================
--- trunk/lib/Template/Context.pm 2007-05-07 08:22:43 UTC (rev 1077)
+++ trunk/lib/Template/Context.pm 2007-05-14 19:20:05 UTC (rev 1078)
@@ -11,15 +11,11 @@
# Andy Wardley <abw@wardley.org>
#
# COPYRIGHT
-# Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
-# Copyright (C) 1998-2000 Canon Research Centre Europe Ltd.
+# Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
#
# This module is free software; you can redistribute it and/or
# modify it under the same terms as Perl itself.
#
-# REVISION
-# $Id$
-#
#============================================================================
package Template::Context;
@@ -893,18 +889,6 @@
__END__
-
-#------------------------------------------------------------------------
-# IMPORTANT NOTE
-# This documentation is generated automatically from source
-# templates. Any changes you make here may be lost.
-#
-# The 'docsrc' documentation source bundle is available for download
-# from http://www.template-toolkit.org/docs.html and contains all
-# the source templates, XML files, scripts, etc., from which the
-# documentation for the Template Toolkit is built.
-#------------------------------------------------------------------------
-
=head1 NAME
Template::Context - Runtime context in which templates are processed
@@ -912,41 +896,41 @@
=head1 SYNOPSIS
use Template::Context;
-
+
# constructor
$context = Template::Context->new(\%config)
- || die $Template::Context::ERROR;
-
+ || die $Template::Context::ERROR;
+
# fetch (load and compile) a template
$template = $context->template($template_name);
-
+
# fetch (load and instantiate) a plugin object
$plugin = $context->plugin($name, \@args);
-
+
# fetch (return or create) a filter subroutine
$filter = $context->filter($name, \@args, $alias);
-
+
# process/include a template, errors are thrown via die()
$output = $context->process($template, \%vars);
$output = $context->include($template, \%vars);
-
+
# raise an exception via die()
$context->throw($error_type, $error_message, \$output_buffer);
-
+
# catch an exception, clean it up and fix output buffer
$exception = $context->catch($exception, \$output_buffer);
-
+
# save/restore the stash to effect variable localisation
$new_stash = $context->localise(\%vars);
$old_stash = $context->delocalise();
-
+
# add new BLOCK or FILTER definitions
$context->define_block($name, $block);
$context->define_filter($name, \&filtersub, $is_dynamic);
-
+
# reset context, clearing any imported BLOCK definitions
$context->reset();
-
+
# methods for accessing internal items
$stash = $context->stash();
$tflag = $context->trim();
@@ -958,471 +942,272 @@
=head1 DESCRIPTION
-The Template::Context module defines an object class for representing
+The C<Template::Context> module defines an object class for representing
a runtime context in which templates are processed. It provides an
interface to the fundamental operations of the Template Toolkit
processing engine through which compiled templates (i.e. Perl code
constructed from the template source) can process templates, load
plugins and filters, raise exceptions and so on.
-A default Template::Context object is created by the Template module.
-Any Template::Context options may be passed to the Template new()
-constructor method and will be forwarded to the Template::Context
-constructor.
+A default C<Template::Context> object is created by the L<Template> module.
+Any C<Template::Context> options may be passed to the L<Template>
+L<Template#new()|new()> constructor method and will be forwarded to the
+C<Template::Context> constructor.
use Template;
my $template = Template->new({
- TRIM => 1,
- EVAL_PERL => 1,
- BLOCKS => {
- header => 'This is the header',
- footer => 'This is the footer',
- },
+ TRIM => 1,
+ EVAL_PERL => 1,
+ BLOCKS => {
+ header => 'This is the header',
+ footer => 'This is the footer',
+ },
});
-Similarly, the Template::Context constructor will forward all configuration
-parameters onto other default objects (e.g. Template::Provider, Template::Plugins,
-Template::Filters, etc.) that it may need to instantiate.
+Similarly, the C<Template::Context> constructor will forward all configuration
+parameters onto other default objects (e.g. L<Template::Provider>,
+L<Template::Plugins>, L<Template::Filters>, etc.) that it may need to
+instantiate.
$context = Template::Context->new({
- INCLUDE_PATH => '/home/abw/templates', # provider option
- TAG_STYLE => 'html', # parser option
+ INCLUDE_PATH => '/home/abw/templates', # provider option
+ TAG_STYLE => 'html', # parser option
});
-A Template::Context object (or subclass/derivative) can be explicitly
-instantiated and passed to the Template new() constructor method as
-the CONTEXT item.
+A C<Template::Context> object (or subclass) can be explicitly instantiated and
+passed to the L<Template> L<Template#new()|new()> constructor method as the
+C<CONTEXT> configuration item.
use Template;
use Template::Context;
-
+
my $context = Template::Context->new({ TRIM => 1 });
my $template = Template->new({ CONTEXT => $context });
-The Template module uses the Template::Config context() factory method
-to create a default context object when required. The
-$Template::Config::CONTEXT package variable may be set to specify an
-alternate context module. This will be loaded automatically and its
-new() constructor method called by the context() factory method when
-a default context object is required.
+The L<Template> module uses the L<Template::Config>
+L<Template::Config#context()|context()> factory method to create a default
+context object when required. The C<$Template::Config::CONTEXT> package
+variable may be set to specify an alternate context module. This will be
+loaded automatically and its L<new()> constructor method called by the
+L<Template::Config#context()|context()> factory method when a default context
+object is required.
use Template;
-
+
$Template::Config::CONTEXT = 'MyOrg::Template::Context';
-
+
my $template = Template->new({
- EVAL_PERL => 1,
- EXTRA_MAGIC => 'red hot', # your extra config items
- ...
+ EVAL_PERL => 1,
+ EXTRA_MAGIC => 'red hot', # your extra config items
+ ...
});
=head1 METHODS
=head2 new(\%params)
-The new() constructor method is called to instantiate a Template::Context
-object. Configuration parameters may be specified as a HASH reference or
-as a list of (name =E<gt> value) pairs.
+The C<new()> constructor method is called to instantiate a
+C<Template::Context> object. Configuration parameters may be specified as a
+HASH reference or as a list of C<name =E<gt> value> pairs.
my $context = Template::Context->new({
- INCLUDE_PATH => 'header',
- POST_PROCESS => 'footer',
+ INCLUDE_PATH => 'header',
+ POST_PROCESS => 'footer',
});
-
+
my $context = Template::Context->new( EVAL_PERL => 1 );
-The new() method returns a Template::Context object (or sub-class) or
-undef on error. In the latter case, a relevant error message can be
-retrieved by the error() class method or directly from the
-$Template::Context::ERROR package variable.
+The C<new()> method returns a C<Template::Context> object or C<undef> on
+error. In the latter case, a relevant error message can be retrieved by the
+L<Template::Base#error()|error()> class method or directly from the
+C<$Template::Context::ERROR> package variable.
my $context = Template::Context->new(\%config)
- || die Template::Context->error();
-
+ || die Template::Context->error();
+
my $context = Template::Context->new(\%config)
- || die $Template::Context::ERROR;
+ || die $Template::Context::ERROR;
-The following configuration items may be specified.
+The following configuration items may be specified. Please see
+L<Template::Manual::Config> for further details.
-=over 4
+=head3 VARIABLES
+The L<Template::Manual::Config#VARIABLES|VARIABLES> option can be used to
+specify a hash array of template variables.
-=item VARIABLES, PRE_DEFINE
-
-The VARIABLES option (or PRE_DEFINE - they're equivalent) can be used
-to specify a hash array of template variables that should be used to
-pre-initialise the stash when it is created. These items are ignored
-if the STASH item is defined.
-
my $context = Template::Context->new({
- VARIABLES => {
- title => 'A Demo Page',
- author => 'Joe Random Hacker',
- version => 3.14,
- },
+ VARIABLES => {
+ title => 'A Demo Page',
+ author => 'Joe Random Hacker',
+ version => 3.14,
+ },
};
-or
+=head3 BLOCKS
- my $context = Template::Context->new({
- PRE_DEFINE => {
- title => 'A Demo Page',
- author => 'Joe Random Hacker',
- version => 3.14,
- },
- };
+The L<Template::Manual::Config#BLOCKS|BLOCKS> option can be used to pre-define
+a default set of template blocks.
-
-
-
-
-=item BLOCKS
-
-The BLOCKS option can be used to pre-define a default set of template
-blocks. These should be specified as a reference to a hash array
-mapping template names to template text, subroutines or Template::Document
-objects.
-
my $context = Template::Context->new({
- BLOCKS => {
- header => 'The Header. [% title %]',
- footer => sub { return $some_output_text },
- another => Template::Document->new({ ... }),
- },
+ BLOCKS => {
+ header => 'The Header. [% title %]',
+ footer => sub { return $some_output_text },
+ another => Template::Document->new({ ... }),
+ },
});
+=head3 TRIM
+The L<Template::Manual::Config#TRIM|TRIM> option can be set to have any
+leading and trailing whitespace automatically removed from the output of all
+template files and C<BLOCK>s.
+example:
-
-=item TRIM
-
-The TRIM option can be set to have any leading and trailing whitespace
-automatically removed from the output of all template files and BLOCKs.
-
-By example, the following BLOCK definition
-
[% BLOCK foo %]
+
Line 1 of foo
+
[% END %]
-
-will be processed is as "\nLine 1 of foo\n". When INCLUDEd, the surrounding
-newlines will also be introduced.
-
+
before
[% INCLUDE foo %]
after
output:
- before
- Line 1 of foo
-
- after
-
-With the TRIM option set to any true value, the leading and trailing
-newlines (which count as whitespace) will be removed from the output
-of the BLOCK.
-
before
Line 1 of foo
after
-The TRIM option is disabled (0) by default.
+=head3 EVAL_PERL
+The L<Template::Manual::Config#EVAL_PERL|EVAL_PERL> is used to indicate if
+C<PERL> and/or C<RAWPERL> blocks should be evaluated. It is disabled by
+default.
+=head3 RECURSION
+The L<Template::Manual::Config#RECURSION|RECURSION> can be set to
+allow templates to recursively process themselves, either directly
+(e.g. template C<foo> calls C<INCLUDE foo>) or indirectly (e.g.
+C<foo> calls C<INCLUDE bar> which calls C<INCLUDE foo>).
+=head3 LOAD_TEMPLATES
+The L<Template::Manual::Config#LOAD_TEMPLATES|LOAD_TEMPLATES> option can be
+used to provide a reference to a list of L<Template::Provider> objects or
+sub-classes thereof which will take responsibility for loading and compiling
+templates.
-=item EVAL_PERL
-
-This flag is used to indicate if PERL and/or RAWPERL blocks should be
-evaluated. By default, it is disabled and any PERL or RAWPERL blocks
-encountered will raise exceptions of type 'perl' with the message
-'EVAL_PERL not set'. Note however that any RAWPERL blocks should
-always contain valid Perl code, regardless of the EVAL_PERL flag. The
-parser will fail to compile templates that contain invalid Perl code
-in RAWPERL blocks and will throw a 'file' exception.
-
-When using compiled templates (see
-L<COMPILE_EXT|Template::Manual::Config/Caching_and_Compiling_Options> and
-L<COMPILE_DIR|Template::Manual::Config/Caching_and_Compiling_Options>),
-the EVAL_PERL has an affect when the template is compiled, and again
-when the templates is subsequently processed, possibly in a different
-context to the one that compiled it.
-
-If the EVAL_PERL is set when a template is compiled, then all PERL and
-RAWPERL blocks will be included in the compiled template. If the
-EVAL_PERL option isn't set, then Perl code will be generated which
-B<always> throws a 'perl' exception with the message 'EVAL_PERL not
-set' B<whenever> the compiled template code is run.
-
-Thus, you must have EVAL_PERL set if you want your compiled templates
-to include PERL and RAWPERL blocks.
-
-At some point in the future, using a different invocation of the
-Template Toolkit, you may come to process such a pre-compiled
-template. Assuming the EVAL_PERL option was set at the time the
-template was compiled, then the output of any RAWPERL blocks will be
-included in the compiled template and will get executed when the
-template is processed. This will happen regardless of the runtime
-EVAL_PERL status.
-
-Regular PERL blocks are a little more cautious, however. If the
-EVAL_PERL flag isn't set for the I<current> context, that is, the
-one which is trying to process it, then it will throw the familiar 'perl'
-exception with the message, 'EVAL_PERL not set'.
-
-Thus you can compile templates to include PERL blocks, but optionally
-disable them when you process them later. Note however that it is
-possible for a PERL block to contain a Perl "BEGIN { # some code }"
-block which will always get run regardless of the runtime EVAL_PERL
-status. Thus, if you set EVAL_PERL when compiling templates, it is
-assumed that you trust the templates to Do The Right Thing. Otherwise
-you must accept the fact that there's no bulletproof way to prevent
-any included code from trampling around in the living room of the
-runtime environment, making a real nuisance of itself if it really
-wants to. If you don't like the idea of such uninvited guests causing
-a bother, then you can accept the default and keep EVAL_PERL disabled.
-
-
-
-
-
-
-
-=item RECURSION
-
-The template processor will raise a file exception if it detects
-direct or indirect recursion into a template. Setting this option to
-any true value will allow templates to include each other recursively.
-
-
-
-=item LOAD_TEMPLATES
-
-The LOAD_TEMPLATE option can be used to provide a reference to a list
-of Template::Provider objects or sub-classes thereof which will take
-responsibility for loading and compiling templates.
-
my $context = Template::Context->new({
- LOAD_TEMPLATES => [
- MyOrg::Template::Provider->new({ ... }),
- Template::Provider->new({ ... }),
- ],
+ LOAD_TEMPLATES => [
+ MyOrg::Template::Provider->new({ ... }),
+ Template::Provider->new({ ... }),
+ ],
});
-When a PROCESS, INCLUDE or WRAPPER directive is encountered, the named
-template may refer to a locally defined BLOCK or a file relative to
-the INCLUDE_PATH (or an absolute or relative path if the appropriate
-ABSOLUTE or RELATIVE options are set). If a BLOCK definition can't be
-found (see the Template::Context template() method for a discussion of
-BLOCK locality) then each of the LOAD_TEMPLATES provider objects is
-queried in turn via the fetch() method to see if it can supply the
-required template. Each provider can return a compiled template, an
-error, or decline to service the request in which case the
-responsibility is passed to the next provider. If none of the
-providers can service the request then a 'not found' error is
-returned. The same basic provider mechanism is also used for the
-INSERT directive but it bypasses any BLOCK definitions and doesn't
-attempt is to parse or process the contents of the template file.
+=head3 LOAD_PLUGINS
-This is an implementation of the 'Chain of Responsibility'
-design pattern as described in
-"Design Patterns", Erich Gamma, Richard Helm, Ralph Johnson, John
-Vlissides), Addision-Wesley, ISBN 0-201-63361-2, page 223
-.
+The L<Template::Manual::Config#LOAD_PLUGINS|LOAD_PLUGINS> options can be used
+to specify a list of provider objects responsible for loading and
+instantiating template plugin objects.
-If LOAD_TEMPLATES is undefined, a single default provider will be
-instantiated using the current configuration parameters. For example,
-the Template::Provider INCLUDE_PATH option can be specified in the Template::Context configuration and will be correctly passed to the provider's
-constructor method.
-
my $context = Template::Context->new({
- INCLUDE_PATH => '/here:/there',
+ LOAD_PLUGINS => [
+ MyOrg::Template::Plugins->new({ ... }),
+ Template::Plugins->new({ ... }),
+ ],
});
+=head3 LOAD_FILTERS
+The L<Template::Manual::Config#LOAD_FILTERS|LOAD_FILTERS> option can be used
+to specify a list of provider objects for returning and/or creating filter
+subroutines.
-
-
-=item LOAD_PLUGINS
-
-The LOAD_PLUGINS options can be used to specify a list of provider
-objects (i.e. they implement the fetch() method) which are responsible
-for loading and instantiating template plugin objects. The
-Template::Content plugin() method queries each provider in turn in a
-"Chain of Responsibility" as per the template() and filter() methods.
-
my $context = Template::Context->new({
- LOAD_PLUGINS => [
- MyOrg::Template::Plugins->new({ ... }),
- Template::Plugins->new({ ... }),
- ],
+ LOAD_FILTERS => [
+ MyTemplate::Filters->new(),
+ Template::Filters->new(),
+ ],
});
-By default, a single Template::Plugins object is created using the
-current configuration hash. Configuration items destined for the
-Template::Plugins constructor may be added to the Template::Context
-constructor.
+=head3 STASH
- my $context = Template::Context->new({
- PLUGIN_BASE => 'MyOrg::Template::Plugins',
- LOAD_PERL => 1,
- });
-
-
-
-
-
-=item LOAD_FILTERS
-
-The LOAD_FILTERS option can be used to specify a list of provider
-objects (i.e. they implement the fetch() method) which are responsible
-for returning and/or creating filter subroutines. The
-Template::Context filter() method queries each provider in turn in a
-"Chain of Responsibility" as per the template() and plugin() methods.
-
- my $context = Template::Context->new({
- LOAD_FILTERS => [
- MyTemplate::Filters->new(),
- Template::Filters->new(),
- ],
- });
-
-By default, a single Template::Filters object is created for the
-LOAD_FILTERS list.
-
-
-
-=item STASH
-
-A reference to a Template::Stash object or sub-class which will take
+The L<Template::Manual::Config#STASH|STASH> option can be used to
+specify a L<Template::Stash> object or sub-class which will take
responsibility for managing template variables.
my $stash = MyOrg::Template::Stash->new({ ... });
my $context = Template::Context->new({
- STASH => $stash,
+ STASH => $stash,
});
-If unspecified, a default stash object is created using the VARIABLES
-configuration item to initialise the stash variables. These may also
-be specified as the PRE_DEFINE option for backwards compatibility with
-version 1.
+=head3 DEBUG
- my $context = Template::Context->new({
- VARIABLES => {
- id => 'abw',
- name => 'Andy Wardley',
- },
- };
+The L<Template::Manual::Config#DEBUG|DEBUG> option can be used to enable
+various debugging features of the L<Template::Context> module.
-
-
-=item DEBUG
-
-The DEBUG option can be used to enable various debugging features
-of the Template::Context module.
-
use Template::Constants qw( :debug );
-
+
my $template = Template->new({
- DEBUG => DEBUG_CONTEXT | DEBUG_DIRS,
+ DEBUG => DEBUG_CONTEXT | DEBUG_DIRS,
});
-The DEBUG value can include any of the following. Multiple values
-should be combined using the logical OR operator, '|'.
-
-=over 4
-
-=item DEBUG_CONTEXT
-
-Enables general debugging messages for the
-L<Template::Context|Template::Context> module.
-
-=item DEBUG_DIRS
-
-This option causes the Template Toolkit to generate comments
-indicating the source file, line and original text of each directive
-in the template. These comments are embedded in the template output
-using the format defined in the DEBUG_FORMAT configuration item, or a
-simple default format if unspecified.
-
-For example, the following template fragment:
-
-
- Hello World
-
-would generate this output:
-
- ## input text line 1 : ##
- Hello
- ## input text line 2 : World ##
- World
-
-
-=back
-
-
-
-
-
-=back
-
=head2 template($name)
-Returns a compiled template by querying each of the LOAD_TEMPLATES providers
-(instances of Template::Provider, or sub-class) in turn.
+Returns a compiled template by querying each of the L<LOAD_TEMPLATES> providers
+(instances of L<Template::Provider>, or sub-class) in turn.
$template = $context->template('header');
-On error, a Template::Exception object of type 'file' is thrown via
-die(). This can be caught by enclosing the call to template() in an
-eval block and examining $@.
+On error, a L<Template::Exception> object of type 'C<file>' is thrown via
+C<die()>. This can be caught by enclosing the call to C<template()> in an
+C<eval> block and examining C<$@>.
- eval {
- $template = $context->template('header');
- };
+ eval { $template = $context->template('header') };
if ($@) {
- print "failed to fetch template: $@\n";
+ print "failed to fetch template: $@\n";
}
=head2 plugin($name, \@args)
-Instantiates a plugin object by querying each of the LOAD_PLUGINS
-providers. The default LOAD_PLUGINS provider is a Template::Plugins
+Instantiates a plugin object by querying each of the L<LOAD_PLUGINS>
+providers. The default L<LOAD_PLUGINS> provider is a L<Template::Plugins>
object which attempts to load plugin modules, according the various
-configuration items such as PLUGIN_BASE, LOAD_PERL, etc., and then
-instantiate an object via new(). A reference to a list of constructor
-arguments may be passed as the second parameter. These are forwarded
-to the plugin constructor.
+configuration items such as L<Template::Plugins#PLUGIN_BASE|PLUGIN_BASE>,
+L<Template::Plugins#LOAD_PERL|LOAD_PERL>, etc., and then instantiate an object
+via L<Template::Plugin#new()|new()>. A reference to a list of constructor
+arguments may be passed as the second parameter. These are forwarded to the
+plugin constructor.
Returns a reference to a plugin (which is generally an object, but
-doesn't have to be). Errors are thrown as Template::Exception objects
-of type 'plugin'.
+doesn't have to be). Errors are thrown as L<Template::Exception> objects
+with the type set to 'C<plugin>'.
$plugin = $context->plugin('DBI', 'dbi:msql:mydbname');
=head2 filter($name, \@args, $alias)
-Instantiates a filter subroutine by querying the LOAD_FILTERS providers.
-The default LOAD_FILTERS providers is a Template::Filters object.
-Additional arguments may be passed by list reference along with an
-optional alias under which the filter will be cached for subsequent
-use. The filter is cached under its own $name if $alias is undefined.
-Subsequent calls to filter($name) will return the cached entry, if
-defined. Specifying arguments bypasses the caching mechanism and
-always creates a new filter. Errors are thrown as Template::Exception
-objects of typre 'filter'.
+Instantiates a filter subroutine by querying the L<LOAD_FILTERS> providers.
+The default L<LOAD_FILTERS> provider is a L<Template::Filters> object.
+Additional arguments may be passed by list reference along with an optional
+alias under which the filter will be cached for subsequent use. The filter is
+cached under its own C<$name> if C<$alias> is undefined. Subsequent calls to
+C<filter($name)> will return the cached entry, if defined. Specifying arguments
+bypasses the caching mechanism and always creates a new filter. Errors are
+thrown as L<Template::Exception> objects with the type set to 'C<filter>'.
+
# static filter (no args)
$filter = $context->filter('html');
-
+
# dynamic filter (args) aliased to 'padright'
$filter = $context->filter('format', '%60s', 'padright');
-
+
# retrieve previous filter via 'padright' alias
$filter = $context->filter('padright');
@@ -1433,25 +1218,25 @@
as the second parameter, containing variable definitions which will be set
before the template is processed. The template is processed in the current
context, with no localisation of variables performed. Errors are thrown
-as Template::Exception objects via die().
+as L<Template::Exception> objects via C<die()>.
$output = $context->process('header', { title => 'Hello World' });
=head2 include($template, \%vars)
-Similar to process() above, but using localised variables. Changes made to
-any variables will only persist until the include() method completes.
+Similar to L<process()>, but using localised variables. Changes made to
+any variables will only persist until the C<include()> method completes.
$output = $context->include('header', { title => 'Hello World' });
=head2 throw($error_type, $error_message, \$output)
-Raises an exception in the form of a Template::Exception object by
-calling die(). This method may be passed a reference to an existing
-Template::Exception object; a single value containing an error message
-which is used to instantiate a Template::Exception of type 'undef'; or
-a pair of values representing the exception type and info from which a
-Template::Exception object is instantiated. e.g.
+Raises an exception in the form of a L<Template::Exception> object by calling
+C<die()>. This method may be passed a reference to an existing
+L<Template::Exception> object; a single value containing an error message
+which is used to instantiate a L<Template::Exception> of type 'C<undef>'; or a
+pair of values representing the exception C<type> and C<info> from which a
+L<Template::Exception> object is instantiated. e.g.
$context->throw($exception);
$context->throw("I'm sorry Dave, I can't do that");
@@ -1468,37 +1253,38 @@
=head2 catch($exception, \$output)
-Catches an exception thrown, either as a reference to a
-Template::Exception object or some other value. In the latter case,
-the error string is promoted to a Template::Exception object of
-'undef' type. This method also accepts a reference to the current
-output buffer which is passed to the Template::Exception constructor,
-or is appended to the output buffer stored in an existing
-Template::Exception object, if unique (i.e. not the same reference).
-By this process, the correct state of the output buffer can be
+Catches an exception thrown, either as a reference to a L<Template::Exception>
+object or some other value. In the latter case, the error string is promoted
+to a L<Template::Exception> object of 'C<undef>' type. This method also
+accepts a reference to the current output buffer which is passed to the
+L<Template::Exception> constructor, or is appended to the output buffer stored
+in an existing L<Template::Exception> object, if unique (i.e. not the same
+reference). By this process, the correct state of the output buffer can be
reconstructed for simple or nested throws.
=head2 define_block($name, $block)
-Adds a new block definition to the internal BLOCKS cache. The first
+Adds a new block definition to the internal L<BLOCKS> cache. The first
argument should contain the name of the block and the second a reference
-to a Template::Document object or template sub-routine, or template text
-which is automatically compiled into a template sub-routine. Returns
-a true value (the sub-routine or Template::Document reference) on
-success or undef on failure. The relevant error message can be
-retrieved by calling the error() method.
+to a L<Template::Document> object or template sub-routine, or template text
+which is automatically compiled into a template sub-routine.
+Returns a true value (the sub-routine or L<Template::Document> reference) on
+success or undef on failure. The relevant error message can be retrieved by
+calling the L<Template::Base#error()|error()> method.
+
=head2 define_filter($name, \&filter, $is_dynamic)
-Adds a new filter definition by calling the store() method on each of
-the LOAD_FILTERS providers until accepted (in the usual case, this is
-accepted straight away by the one and only Template::Filters
-provider). The first argument should contain the name of the filter
-and the second a reference to a filter subroutine. The optional
-third argument can be set to any true value to indicate that the
-subroutine is a dynamic filter factory. Returns a true value or
-throws a 'filter' exception on error.
+Adds a new filter definition by calling the
+L<Template::Filters#store()|store()> method on each of the L<LOAD_FILTERS>
+providers until accepted (in the usual case, this is accepted straight away by
+the one and only L<Template::Filters> provider). The first argument should
+contain the name of the filter and the second a reference to a filter
+subroutine. The optional third argument can be set to any true value to
+indicate that the subroutine is a dynamic filter factory.
+Returns a true value or throws a 'C<filter>' exception on error.
+
=head2 localise(\%vars)
Clones the stash to create a context with localised variables. Returns a
@@ -1515,24 +1301,24 @@
=head2 visit(\%blocks)
-This method is called by Template::Document objects immediately before
-they process their content. It is called to register any local BLOCK
+This method is called by L<Template::Document> objects immediately before
+they process their content. It is called to register any local C<BLOCK>
definitions with the context object so that they may be subsequently
delivered on request.
=head2 leave()
-Compliment to visit(), above. Called by Template::Document objects
+Compliment to the L<visit()> method. Called by L<Template::Document> objects
immediately after they process their content.
=head2 reset()
-Clears the local BLOCKS cache of any BLOCK definitions. Any initial set of
-BLOCKS specified as a configuration item to the constructor will be reinstated.
+Clears the local L<BLOCKS> cache of any C<BLOCK> definitions. Any initial set of
+L<BLOCKS> specified as a configuration item to the constructor will be reinstated.
=head2 AUTOLOAD
-An AUTOLOAD method provides access to context configuration items.
+An C<AUTOLOAD> method provides access to context configuration items.
$stash = $context->stash();
$tflag = $context->trim();
@@ -1543,27 +1329,20 @@
Andy Wardley E<lt>abw@wardley.orgE<gt>
-L<http://wardley.org/|http://wardley.org/>
+L<http://wardley.org/>
-
-
-
-=head1 VERSION
-
-2.98, distributed as part of the
-Template Toolkit version 2.19, released on 27 April 2007.
-
=head1 COPYRIGHT
- Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
+Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
-
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
=head1 SEE ALSO
-L<Template|Template>, L<Template::Document|Template::Document>, L<Template::Exception|Template::Exception>, L<Template::Filters|Template::Filters>, L<Template::Plugins|Template::Plugins>, L<Template::Provider|Template::Provider>, L<Template::Service|Template::Service>, L<Template::Stash|Template::Stash>
+L<Template>, L<Template::Document>, L<Template::Exception>,
+L<Template::Filters>, L<Template::Plugins>, L<Template::Provider>,
+L<Template::Service>, L<Template::Stash>
=cut
Modified: trunk/lib/Template/Directive.pm
===================================================================
--- trunk/lib/Template/Directive.pm 2007-05-07 08:22:43 UTC (rev 1077)
+++ trunk/lib/Template/Directive.pm 2007-05-14 19:20:05 UTC (rev 1078)
@@ -17,15 +17,11 @@
# debugging.
#
# COPYRIGHT
-# Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
-# Copyright (C) 1998-2000 Canon Research Centre Europe Ltd.
+# Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
#
# This module is free software; you can redistribute it and/or
# modify it under the same terms as Perl itself.
#
-# REVISION
-# $Id$
-#
#============================================================================
package Template::Directive;
@@ -997,3 +993,46 @@
__END__
+=head1 NAME
+
+Template::Directive - Perl code generator for template directives
+
+=head1 SYNOPSIS
+
+ # no user serviceable parts inside
+
+=head1 DESCRIPTION
+
+The C<Template::Directive> module defines a number of methods that
+generate Perl code for the runtime representation of the various
+Template Toolkit directives.
+
+It is used internally by the L<Template::Parser> module.
+
+=head1 AUTHOR
+
+Andy Wardley E<lt>abw@wardley.orgE<gt>
+
+L<http://wardley.org/>
+
+=head1 COPYRIGHT
+
+Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
+
+This module is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+
+=head1 SEE ALSO
+
+L<Template::Parser>
+
+=cut
+
+# Local Variables:
+# mode: perl
+# perl-indent-level: 4
+# indent-tabs-mode: nil
+# End:
+#
+# vim: expandtab shiftwidth=4:
+
Modified: trunk/lib/Template/Document.pm
===================================================================
--- trunk/lib/Template/Document.pm 2007-05-07 08:22:43 UTC (rev 1077)
+++ trunk/lib/Template/Document.pm 2007-05-14 19:20:05 UTC (rev 1078)
@@ -9,18 +9,14 @@
# template content.
#
# AUTHOR
-# Andy Wardley <abw@kfs.org>
+# Andy Wardley <abw@wardley.org>
#
# COPYRIGHT
-# Copyright (C) 1996-2000 Andy Wardley. All Rights Reserved.
-# Copyright (C) 1998-2000 Canon Research Centre Europe Ltd.
+# Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
#
# This module is free software; you can redistribute it and/or
# modify it under the same terms as Perl itself.
#
-# REVISION
-# $Id$
-#
#============================================================================
package Template::Document;
@@ -160,7 +156,7 @@
die $context->catch($@)
if $@;
-
+
return $output;
}
@@ -204,9 +200,9 @@
$output .= "BLOCK: $self->{ _BLOCK }\nDEFBLOCKS:\n";
if ($dblks = $self->{ _DEFBLOCKS }) {
- foreach my $b (keys %$dblks) {
- $output .= " $b: $dblks->{ $b }\n";
- }
+ foreach my $b (keys %$dblks) {
+ $output .= " $b: $dblks->{ $b }\n";
+ }
}
return $output;
@@ -287,7 +283,7 @@
my ($fh, $tmpfile);
return $class->error("invalid filename: $file")
- unless $file =~ /^(.+)$/s;
+ unless $file =~ /^(.+)$/s;
eval {
require File::Temp;
@@ -325,18 +321,6 @@
__END__
-
-#------------------------------------------------------------------------
-# IMPORTANT NOTE
-# This documentation is generated automatically from source
-# templates. Any changes you make here may be lost.
-#
-# The 'docsrc' documentation source bundle is available for download
-# from http://www.template-toolkit.org/docs.html and contains all
-# the source templates, XML files, scripts, etc., from which the
-# documentation for the Template Toolkit is built.
-#------------------------------------------------------------------------
-
=head1 NAME
Template::Document - Compiled template document object
@@ -344,57 +328,60 @@
=head1 SYNOPSIS
use Template::Document;
-
+
$doc = Template::Document->new({
- BLOCK => sub { # some perl code; return $some_text },
- DEFBLOCKS => {
- header => sub { # more perl code; return $some_text },
- footer => sub { # blah blah blah; return $some_text },
- },
- METADATA => {
- author => 'Andy Wardley',
- version => 3.14,
- }
+ BLOCK => sub { # some perl code; return $some_text },
+ DEFBLOCKS => {
+ header => sub { # more perl code; return $some_text },
+ footer => sub { # blah blah blah; return $some_text },
+ },
+ METADATA => {
+ author => 'Andy Wardley',
+ version => 3.14,
+ }
}) || die $Template::Document::ERROR;
-
+
print $doc->process($context);
=head1 DESCRIPTION
This module defines an object class whose instances represent compiled
-template documents. The Template::Parser module creates a
-Template::Document instance to encapsulate a template as it is compiled
+template documents. The L<Template::Parser> module creates a
+C<Template::Document> instance to encapsulate a template as it is compiled
into Perl code.
-The constructor method, new(), expects a reference to a hash array
-containing the BLOCK, DEFBLOCKS and METADATA items. The BLOCK item
-should contain a reference to a Perl subroutine or a textual
-representation of Perl code, as generated by the Template::Parser
-module, which is then evaluated into a subroutine reference using
-eval(). The DEFLOCKS item should reference a hash array containing
-further named BLOCKs which may be defined in the template. The keys
-represent BLOCK names and the values should be subroutine references
-or text strings of Perl code as per the main BLOCK item. The METADATA
-item should reference a hash array of metadata items relevant to the
-document.
+The constructor method, L<new()>, expects a reference to a hash array
+containing the C<BLOCK>, C<DEFBLOCKS> and C<METADATA> items.
-The process() method can then be called on the instantiated
-Template::Document object, passing a reference to a Template::Content
-object as the first parameter. This will install any locally defined
-blocks (DEFBLOCKS) in the the contexts() BLOCKS cache (via a call to
-visit()) so that they may be subsequently resolved by the context. The
-main BLOCK subroutine is then executed, passing the context reference
-on as a parameter. The text returned from the template subroutine is
-then returned by the process() method, after calling the context leave()
-method to permit cleanup and de-registration of named BLOCKS previously
-installed.
+The C<BLOCK> item should contain a reference to a Perl subroutine or a textual
+representation of Perl code, as generated by the L<Template::Parser> module.
+This is then evaluated into a subroutine reference using C<eval()>.
-An AUTOLOAD method provides access to the METADATA items for the document.
-The Template::Service module installs a reference to the main
-Template::Document object in the stash as the 'template' variable.
-This allows metadata items to be accessed from within templates,
-including PRE_PROCESS templates.
+The C<DEFLOCKS> item should reference a hash array containing further named
+C<BLOCK>s which may be defined in the template. The keys represent C<BLOCK>
+names and the values should be subroutine references or text strings of Perl
+code as per the main C<BLOCK> item.
+The C<METADATA> item should reference a hash array of metadata items relevant
+to the document.
+
+The L<process()> method can then be called on the instantiated
+C<Template::Document> object, passing a reference to a L<Template::Context>
+object as the first parameter. This will install any locally defined blocks
+(C<DEFBLOCKS>) in the C<BLOCKS> cache in the context (via a call to
+L<Template::Context#visit()|visit()>) so that they may be subsequently
+resolved by the context. The main C<BLOCK> subroutine is then executed,
+passing the context reference on as a parameter. The text returned from the
+template subroutine is then returned by the L<process()> method, after calling
+the context L<Template::Context#leave()|leave()> method to permit cleanup and
+de-registration of named C<BLOCKS> previously installed.
+
+An C<AUTOLOAD> method provides access to the C<METADATA> items for the
+document. The L<Template::Service> module installs a reference to the main
+C<Template::Document> object in the stash as the C<template> variable. This allows
+metadata items to be accessed from within templates, including C<PRE_PROCESS>
+templates.
+
header:
<html>
@@ -403,7 +390,7 @@
</head>
...
-Template::Document objects are usually created by the Template::Parser
+C<Template::Document> objects are usually created by the L<Template::Parser>
but can be manually instantiated or sub-classed to provide custom
template components.
@@ -415,50 +402,51 @@
structure as shown in this example:
$doc = Template::Document->new({
- BLOCK => sub { # some perl code; return $some_text },
- DEFBLOCKS => {
- header => sub { # more perl code; return $some_text },
- footer => sub { # blah blah blah; return $some_text },
- },
- METADATA => {
- author => 'Andy Wardley',
- version => 3.14,
- }
+ BLOCK => sub { # some perl code; return $some_text },
+ DEFBLOCKS => {
+ header => sub { # more perl code; return $some_text },
+ footer => sub { # blah blah blah; return $some_text },
+ },
+ METADATA => {
+ author => 'Andy Wardley',
+ version => 3.14,
+ }
}) || die $Template::Document::ERROR;
-BLOCK and DEFBLOCKS items may be expressed as references to Perl subroutines
+C<BLOCK> and C<DEFBLOCKS> items may be expressed as references to Perl subroutines
or as text strings containing Perl subroutine definitions, as is generated
-by the Template::Parser module. These are evaluated into subroutine references
-using eval().
+by the L<Template::Parser> module. These are evaluated into subroutine references
+using C<eval()>.
-Returns a new Template::Document object or undef on error. The error() class
-method can be called, or the $ERROR package variable inspected to retrieve
-the relevant error message.
+Returns a new C<Template::Document> object or C<undef> on error. The
+L<Template::Base#error()|error()> class method can be called, or the C<$ERROR>
+package variable inspected to retrieve the relevant error message.
=head2 process($context)
-Main processing routine for the compiled template document. A reference to
-a Template::Context object should be passed as the first parameter. The
-method installs any locally defined blocks via a call to the context
-visit() method, processes it's own template, passing the context reference
-by parameter and then calls leave() in the context to allow cleanup.
+Main processing routine for the compiled template document. A reference to a
+L<Template::Context> object should be passed as the first parameter. The
+method installs any locally defined blocks via a call to the context
+L<Template::Context#visit()|visit()> method, processes its own template,
+(passing the context reference as a parameter) and then calls
+L<Template::Context#leave()|leave()> in the context to allow cleanup.
print $doc->process($context);
Returns a text string representing the generated output for the template.
-Errors are thrown via die().
+Errors are thrown via C<die()>.
=head2 block()
-Returns a reference to the main BLOCK subroutine.
+Returns a reference to the main C<BLOCK> subroutine.
=head2 blocks()
-Returns a reference to the hash array of named DEFBLOCKS subroutines.
+Returns a reference to the hash array of named C<DEFBLOCKS> subroutines.
=head2 AUTOLOAD
-An autoload method returns METADATA items.
+An autoload method returns C<METADATA> items.
print $doc->author();
@@ -467,40 +455,31 @@
=head2 write_perl_file(\%config)
This package subroutine is provided to effect persistence of compiled
-templates. If the COMPILE_EXT option (to indicate a file extension
-for saving compiled templates) then the Template::Parser module calls
-this subroutine before calling the new() constructor. At this stage,
+templates. If the C<COMPILE_EXT> option (to indicate a file extension
+for saving compiled templates) then the L<Template::Parser> module calls
+this subroutine before calling the L<new()> constructor. At this stage,
the parser has a representation of the template as text strings
containing Perl code. We can write that to a file, enclosed in a
-small wrapper which will allow us to susequently require() the file
-and have Perl parse and compile it into a Template::Document. Thus we
+small wrapper which will allow us to susequently C<require()> the file
+and have Perl parse and compile it into a C<Template::Document>. Thus we
have persistence of compiled templates.
=head1 AUTHOR
Andy Wardley E<lt>abw@wardley.orgE<gt>
-L<http://wardley.org/|http://wardley.org/>
+L<http://wardley.org/>
-
-
-
-=head1 VERSION
-
-2.79, distributed as part of the
-Template Toolkit version 2.19, released on 27 April 2007.
-
=head1 COPYRIGHT
- Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
+Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
-
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
=head1 SEE ALSO
-L<Template|Template>, L<Template::Parser|Template::Parser>
+L<Template>, L<Template::Parser>
=cut
Modified: trunk/lib/Template/Exception.pm
===================================================================
--- trunk/lib/Template/Exception.pm 2007-05-07 08:22:43 UTC (rev 1077)
+++ trunk/lib/Template/Exception.pm 2007-05-14 19:20:05 UTC (rev 1078)
@@ -7,18 +7,14 @@
# in the Template Toolkit.
#
# AUTHOR
-# Andy Wardley <abw@kfs.org>
+# Andy Wardley <abw@wardley.org>
#
# COPYRIGHT
-# Copyright (C) 1996-2000 Andy Wardley. All Rights Reserved.
-# Copyright (C) 1998-2000 Canon Research Centre Europe Ltd.
+# Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
#
# This module is free software; you can redistribute it and/or
# modify it under the same terms as Perl itself.
#
-# REVISION
-# $Id$
-#
#========================================================================
package Template::Exception;
@@ -30,7 +26,7 @@
use constant TEXT => 2;
use overload q|""| => "as_string", fallback => 1;
-our $VERSION = 2.69;
+our $VERSION = 2.70;
#------------------------------------------------------------------------
@@ -146,18 +142,6 @@
__END__
-
-#------------------------------------------------------------------------
-# IMPORTANT NOTE
-# This documentation is generated automatically from source
-# templates. Any changes you make here may be lost.
-#
-# The 'docsrc' documentation source bundle is available for download
-# from http://www.template-toolkit.org/docs.html and contains all
-# the source templates, XML files, scripts, etc., from which the
-# documentation for the Template Toolkit is built.
-#------------------------------------------------------------------------
-
=head1 NAME
Template::Exception - Exception handling class module
@@ -165,77 +149,77 @@
=head1 SYNOPSIS
use Template::Exception;
-
+
my $exception = Template::Exception->new($type, $info);
$type = $exception->type;
$info = $exception->info;
($type, $info) = $exception->type_info;
-
+
print $exception->as_string();
-
+
$handler = $exception->select_handler(\@candidates);
=head1 DESCRIPTION
-The Template::Exception module defines an object class for
+The C<Template::Exception> module defines an object class for
representing exceptions within the template processing life cycle.
Exceptions can be raised by modules within the Template Toolkit, or
can be generated and returned by user code bound to template
variables.
+Exceptions can be raised in a template using the C<THROW> directive,
-Exceptions can be raised in a template using the THROW directive,
-
[% THROW user.login 'no user id: please login' %]
-or by calling the throw() method on the current Template::Context object,
+or by calling the L<Template::Context#throw()|throw()> method on the current
+L<Template::Context> object,
$context->throw('user.passwd', 'Incorrect Password');
$context->throw('Incorrect Password'); # type 'undef'
-or from Perl code by calling die() with a Template::Exception object,
+or from Perl code by calling C<die()> with a C<Template::Exception> object,
die (Template::Exception->new('user.denied', 'Invalid User ID'));
-or by simply calling die() with an error string. This is
-automagically caught and converted to an exception of 'undef'
-type which can then be handled in the usual way.
+or by simply calling C<die()> with an error string. This is
+automagically caught and converted to an exception of 'C<undef>'
+type (that's the literal string 'C<undef>' rather than Perl's
+undefined value) which can then be handled in the usual way.
die "I'm sorry Dave, I can't do that";
-
-
Each exception is defined by its type and a information component
(e.g. error message). The type can be any identifying string and may
-contain dotted components (e.g. 'foo', 'foo.bar', 'foo.bar.baz').
-Exception types are considered to be hierarchical such that 'foo.bar'
-would be a specific type of the more general 'foo' type.
+contain dotted components (e.g. 'C<foo>', 'C<foo.bar>', 'C<foo.bar.baz>').
+Exception types are considered to be hierarchical such that 'C<foo.bar>'
+would be a specific type of the more general 'C<foo>' type.
-=head1 AUTHOR
+=head1 METHODS
-Andy Wardley E<lt>abw@wardley.orgE<gt>
+=head2 type()
-L<http://wardley.org/|http://wardley.org/>
+Returns the exception type.
+=head2 info()
+Returns the exception information.
+=head1 AUTHOR
-=head1 VERSION
+Andy Wardley E<lt>abw@wardley.orgE<gt>
-2.69, distributed as part of the
-Template Toolkit version 2.19, released on 27 April 2007.
+L<http://wardley.org/>
=head1 COPYRIGHT
- Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
+Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
-
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
=head1 SEE ALSO
-L<Template|Template>, L<Template::Context|Template::Context>
+L<Template>, L<Template::Context>
=cut
Modified: trunk/lib/Template/Filters.pm
===================================================================
--- trunk/lib/Template/Filters.pm 2007-05-07 08:22:43 UTC (rev 1077)
+++ trunk/lib/Template/Filters.pm 2007-05-14 19:20:05 UTC (rev 1078)
@@ -615,18 +615,6 @@
__END__
-
-#------------------------------------------------------------------------
-# IMPORTANT NOTE
-# This documentation is generated automatically from source
-# templates. Any changes you make here may be lost.
-#
-# The 'docsrc' documentation source bundle is available for download
-# from http://www.template-toolkit.org/docs.html and contains all
-# the source templates, XML files, scripts, etc., from which the
-# documentation for the Template Toolkit is built.
-#------------------------------------------------------------------------
-
=head1 NAME
Template::Filters - Post-processing filters for template blocks
@@ -634,35 +622,42 @@
=head1 SYNOPSIS
use Template::Filters;
-
+
$filters = Template::Filters->new(\%config);
-
+
($filter, $error) = $filters->fetch($name, \@args, $context);
+
+ if ($filter) {
+ print &$filter("some text");
+ }
+ else {
+ print "Could not fetch $name filter: $error\n";
+ }
=head1 DESCRIPTION
-The Template::Filters module implements a provider for creating and/or
-returning subroutines that implement the standard filters. Additional
-custom filters may be provided via the FILTERS options.
+The C<Template::Filters> module implements a provider for creating subroutines
+that implement the standard filters. Additional custom filters may be provided
+via the L<FILTERS> configuration option.
=head1 METHODS
=head2 new(\%params)
Constructor method which instantiates and returns a reference to a
-Template::Filters object. A reference to a hash array of configuration
+C<Template::Filters> object. A reference to a hash array of configuration
items may be passed as a parameter. These are described below.
my $filters = Template::Filters->new({
FILTERS => { ... },
});
-
+
my $template = Template->new({
LOAD_FILTERS => [ $filters ],
});
-A default Template::Filters module is created by the Template.pm module
-if the LOAD_FILTERS option isn't specified. All configuration parameters
+A default C<Template::Filters> module is created by the L<Template> module
+if the L<LOAD_FILTERS> option isn't specified. All configuration parameters
are forwarded to the constructor.
$template = Template->new({
@@ -673,645 +668,80 @@
Called to request that a filter of a given name be provided. The name
of the filter should be specified as the first parameter. This should
-be one of the standard filters or one specified in the FILTERS
+be one of the standard filters or one specified in the L<FILTERS>
configuration hash. The second argument should be a reference to an
array containing configuration parameters for the filter. This may be
specified as 0, or undef where no parameters are provided. The third
-argument should be a reference to the current Template::Context
+argument should be a reference to the current L<Template::Context>
object.
The method returns a reference to a filter sub-routine on success. It
-may also return (undef, STATUS_DECLINE) to decline the request, to allow
-delegation onto other filter providers in the LOAD_FILTERS chain of
-responsibility. On error, ($error, STATUS_ERROR) is returned where $error
-is an error message or Template::Exception object indicating the error
+may also return C<(undef, STATUS_DECLINE)> to decline the request, to allow
+delegation onto other filter providers in the L<LOAD_FILTERS> chain of
+responsibility. On error, C<($error, STATUS_ERROR)> is returned where $error
+is an error message or L<Template::Exception> object indicating the error
that occurred.
-When the TOLERANT option is set, errors are automatically downgraded to
-a STATUS_DECLINE response.
+When the C<TOLERANT> option is set, errors are automatically downgraded to
+a C<STATUS_DECLINE> response.
-
=head1 CONFIGURATION OPTIONS
-The following list details the configuration options that can be provided
-to the Template::Filters new() constructor.
+The following list summarises the configuration options that can be provided
+to the C<Template::Filters> L<new()> constructor. Please see
+L<Template::Manual::Config> for further information about each option.
-=over 4
+=head2 FILTERS
+The L<Template::Manual::Config#FILTERS|FILTERS> option can be used to specify
+custom filters which can then be used with the
+L<Template::Manual::Directives#FILTER|FILTER> directive like any other. These
+are added to the standard filters which are available by default.
-
-
-=item FILTERS
-
-The FILTERS option can be used to specify custom filters which can
-then be used with the FILTER directive like any other. These are
-added to the standard filters which are available by default. Filters
-specified via this option will mask any standard filters of the same
-name.
-
-The FILTERS option should be specified as a reference to a hash array
-in which each key represents the name of a filter. The corresponding
-value should contain a reference to an array containing a subroutine
-reference and a flag which indicates if the filter is static (0) or
-dynamic (1). A filter may also be specified as a solitary subroutine
-reference and is assumed to be static.
-
$filters = Template::Filters->new({
FILTERS => {
- 'sfilt1' => \&static_filter, # static
- 'sfilt2' => [ \&static_filter, 0 ], # same as above
+ 'sfilt1' => \&static_filter,
'dfilt1' => [ \&dyanamic_filter_factory, 1 ],
},
});
-Additional filters can be specified at any time by calling the
-define_filter() method on the current Template::Context object.
-The method accepts a filter name, a reference to a filter
-subroutine and an optional flag to indicate if the filter is
-dynamic.
+=head2 TOLERANT
- my $context = $template->context();
- $context->define_filter('new_html', \&new_html);
- $context->define_filter('new_repeat', \&new_repeat, 1);
+The L<Template::Manual::Config#TOLERANT|TOLERANT> flag can be set to indicate
+that the C<Template::Filters> module should ignore any errors and instead
+return C<STATUS_DECLINED>.
-Static filters are those where a single subroutine reference is used
-for all invocations of a particular filter. Filters that don't accept
-any configuration parameters (e.g. 'html') can be implemented
-statically. The subroutine reference is simply returned when that
-particular filter is requested. The subroutine is called to filter
-the output of a template block which is passed as the only argument.
-The subroutine should return the modified text.
+=head2 DEBUG
- sub static_filter {
- my $text = shift;
- # do something to modify $text...
- return $text;
- }
+The L<Template::Manual::Config#DEBUG|DEBUG> option can be used to enable
+debugging messages for the Template::Filters module by setting it to include
+the C<DEBUG_FILTERS> value.
-The following template fragment:
-
- [% FILTER sfilt1 %]
- Blah blah blah.
- [% END %]
-
-is approximately equivalent to:
-
- &static_filter("\nBlah blah blah.\n");
-
-Filters that can accept parameters (e.g. 'truncate') should be
-implemented dynamically. In this case, the subroutine is taken to be
-a filter 'factory' that is called to create a unique filter subroutine
-each time one is requested. A reference to the current
-Template::Context object is passed as the first parameter, followed by
-any additional parameters specified. The subroutine should return
-another subroutine reference (usually a closure) which implements the
-filter.
-
- sub dynamic_filter_factory {
- my ($context, @args) = @_;
-
- return sub {
- my $text = shift;
- # do something to modify $text...
- return $text;
- }
- }
-
-The following template fragment:
-
- [% FILTER dfilt1(123, 456) %]
- Blah blah blah
- [% END %]
-
-is approximately equivalent to:
-
- my $filter = &dynamic_filter_factory($context, 123, 456);
- &$filter("\nBlah blah blah.\n");
-
-See the FILTER directive for further examples.
-
-
-
-
-=item TOLERANT
-
-The TOLERANT flag is used by the various Template Toolkit provider
-modules (Template::Provider, Template::Plugins, Template::Filters) to
-control their behaviour when errors are encountered. By default, any
-errors are reported as such, with the request for the particular
-resource (template, plugin, filter) being denied and an exception
-raised. When the TOLERANT flag is set to any true values, errors will
-be silently ignored and the provider will instead return
-STATUS_DECLINED. This allows a subsequent provider to take
-responsibility for providing the resource, rather than failing the
-request outright. If all providers decline to service the request,
-either through tolerated failure or a genuine disinclination to
-comply, then a 'E<lt>resourceE<gt> not found' exception is raised.
-
-
-
-
-=item DEBUG
-
-The DEBUG option can be used to enable debugging messages from the
-Template::Filters module by setting it to include the DEBUG_FILTERS
-value.
-
use Template::Constants qw( :debug );
-
+
my $template = Template->new({
- DEBUG => DEBUG_FILTERS | DEBUG_PLUGINS,
+ DEBUG => DEBUG_FILTERS | DEBUG_PLUGINS,
});
+=head1 STANDARD FILTERS
+Please see L<Template::Manual::Filters> for a list of the filters provided
+with the Template Toolkit, complete with examples of use.
-
-=back
-
-=head1 TEMPLATE TOOLKIT FILTERS
-
-The following standard filters are distributed with the Template Toolkit.
-
-
-
-=head2 format(format)
-
-The 'format' filter takes a format string as a parameter (as per
-printf()) and formats each line of text accordingly.
-
- [% FILTER format('<!-- %-40s -->') %]
- This is a block of text filtered
- through the above format.
- [% END %]
-
-output:
-
- <!-- This is a block of text filtered -->
- <!-- through the above format. -->
-
-=head2 upper
-
-Folds the input to UPPER CASE.
-
- [% "hello world" FILTER upper %]
-
-output:
-
- HELLO WORLD
-
-=head2 lower
-
-Folds the input to lower case.
-
- [% "Hello World" FILTER lower %]
-
-output:
-
- hello world
-
-=head2 ucfirst
-
-Folds the first character of the input to UPPER CASE.
-
- [% "hello" FILTER ucfirst %]
-
-output:
-
- Hello
-
-=head2 lcfirst
-
-Folds the first character of the input to lower case.
-
- [% "HELLO" FILTER lcfirst %]
-
-output:
-
- hELLO
-
-=head2 trim
-
-Trims any leading or trailing whitespace from the input text. Particularly
-useful in conjunction with INCLUDE, PROCESS, etc., having the same effect
-as the TRIM configuration option.
-
- [% INCLUDE myfile | trim %]
-
-=head2 collapse
-
-Collapse any whitespace sequences in the input text into a single space.
-Leading and trailing whitespace (which would be reduced to a single space)
-is removed, as per trim.
-
- [% FILTER collapse %]
-
- The cat
-
- sat on
-
- the mat
-
- [% END %]
-
-output:
-
- The cat sat on the mat
-
-=head2 html
-
-Converts the characters 'E<lt>', 'E<gt>', '&' and '"' to '<',
-'>', '&', and '"' respectively, protecting them from being
-interpreted as representing HTML tags or entities.
-
- [% FILTER html %]
- Binary "<=>" returns -1, 0, or 1 depending on...
- [% END %]
-
-output:
-
- Binary "<=>" returns -1, 0, or 1 depending on...
-
-=head2 html_entity
-
-The html filter is fast and simple but it doesn't encode the full
-range of HTML entities that your text may contain. The html_entity
-filter uses either the Apache::Util module (which is written in C and
-is therefore faster) or the HTML::Entities module (written in Perl but
-equally as comprehensive) to perform the encoding. If one or other of
-these modules are installed on your system then the text will be
-encoded (via the escape_html() or encode_entities() subroutines
-respectively) to convert all extended characters into their
-appropriate HTML entities (e.g. converting 'é' to 'é'). If
-neither module is available on your system then an 'html_entity' exception
-will be thrown reporting an appropriate message.
-
-For further information on HTML entity encoding, see
-http://www.w3.org/TR/REC-html40/sgml/entities.html.
-
-=head2 html_para
-
-This filter formats a block of text into HTML paragraphs. A sequence of
-two or more newlines is used as the delimiter for paragraphs which are
-then wrapped in HTML E<lt>pE<gt>...E<lt>/pE<gt> tags.
-
- [% FILTER html_para %]
- The cat sat on the mat.
-
- Mary had a little lamb.
- [% END %]
-
-output:
-
- <p>
- The cat sat on the mat.
- </p>
-
- <p>
- Mary had a little lamb.
- </p>
-
-=head2 html_break / html_para_break
-
-Similar to the html_para filter described above, but uses the HTML tag
-sequence E<lt>brE<gt>E<lt>brE<gt> to join paragraphs.
-
- [% FILTER html_break %]
- The cat sat on the mat.
-
- Mary had a little lamb.
- [% END %]
-
-output:
-
- The cat sat on the mat.
- <br>
- <br>
- Mary had a little lamb.
-
-=head2 html_line_break
-
-This filter replaces any newlines with E<lt>brE<gt> HTML tags,
-thus preserving the line breaks of the original text in the
-HTML output.
-
- [% FILTER html_line_break %]
- The cat sat on the mat.
- Mary had a little lamb.
- [% END %]
-
-output:
-
- The cat sat on the mat.<br>
- Mary had a little lamb.<br>
-
-=head2 uri
-
-This filter URI escapes the input text, converting any characters
-outside of the permitted URI character set (as defined by RFC 2396)
-into a C<%nn> hex escape.
-
- [% 'my file.html' | uri %]
-
-output:
-
- my%20file.html
-
-The uri filter correctly encodes all reserved characters, including
-C<&>, C<@>, C</>, C<;>, C<:>, C<=>, C<+>, C<?> and C<$>. This filter
-is typically used to encode parameters in a URL that could otherwise
-be interpreted as part of the URL. Here's an example:
-
- [% path = 'http://tt2.org/example'
- back = '/other?foo=bar&baz=bam'
- title = 'Earth: "Mostly Harmless"'
- %]
- <a href="[% path %]?back=[% back | uri %]&title=[% title | uri %]">
-
-The output generated is rather long so we'll show it split across two
-lines:
-
- <a href="http://tt2.org/example?back=%2Fother%3Ffoo%3Dbar%26
- baz%3Dbam&title=Earth%3A%20%22Mostly%20Harmless%22">
-
-Without the uri filter the output would look like this (also split across
-two lines).
-
- <a href="http://tt2.org/example?back=/other?foo=bar
- &baz=bam&title=Earth: "Mostly Harmless"">
-
-In this rather contrived example we've manage to generate both a broken URL
-(the repeated C<?> is not allowed) and a broken HTML element (the href
-attribute is terminated by the first C<"> after C<Earth: > leaving C<Mostly
-Harmless"> dangling on the end of the tag in precisely the way that harmless
-things shouldn't dangle). So don't do that. Always use the uri filter to
-encode your URL parameters.
-
-However, you should B<not> use the uri filter to encode an entire URL.
-
- <a href="[% page_url | uri %]"> # WRONG!
-
-This will incorrectly encode any reserved characters like C<:> and C</>
-and that's almost certainly not what you want in this case. Instead
-you should use the B<url> (note spelling) filter for this purpose.
-
- <a href="[% page_url | url %]"> # CORRECT
-
-Please note that this behaviour was changed in version 2.16 of the
-Template Toolkit. Prior to that, the uri filter did not encode the
-reserved characters, making it technically incorrect according to the
-RFC 2396 specification. So we fixed it in 2.16 and provided the url
-filter to implement the old behaviour of not encoding reserved
-characters.
-
-=head2 url
-
-The url filter is a less aggressive version of the uri filter. It encodes
-any characters outside of the permitted URI character set (as defined by RFC 2396)
-into C<%nn> hex escapes. However, unlike the uri filter, the url filter does
-B<not> encode the reserved characters C<&>, C<@>, C</>, C<;>, C<:>, C<=>, C<+>,
-C<?> and C<$>.
-
-=head2 indent(pad)
-
-Indents the text block by a fixed pad string or width. The 'pad' argument
-can be specified as a string, or as a numerical value to indicate a pad
-width (spaces). Defaults to 4 spaces if unspecified.
-
- [% FILTER indent('ME> ') %]
- blah blah blah
- cabbages, rhubard, onions
- [% END %]
-
-output:
-
- ME> blah blah blah
- ME> cabbages, rhubard, onions
-
-=head2 truncate(length,dots)
-
-Truncates the text block to the length specified, or a default length
-of 32. Truncated text will be terminated with '...' (i.e. the '...'
-falls inside the required length, rather than appending to it).
-
- [% FILTER truncate(21) %]
- I have much to say on this matter that has previously
- been said on more than one occasion.
- [% END %]
-
-output:
-
- I have much to say...
-
-If you want to use something other than '...' you can pass that as a
-second argument.
-
- [% FILTER truncate(26, '…') %]
- I have much to say on this matter that has previously
- been said on more than one occasion.
- [% END %]
-
-output:
-
- I have much to say…
-
-=head2 repeat(iterations)
-
-Repeats the text block for as many iterations as are specified (default: 1).
-
- [% FILTER repeat(3) %]
- We want more beer and we want more beer,
- [% END %]
- We are the more beer wanters!
-
-output:
-
- We want more beer and we want more beer,
- We want more beer and we want more beer,
- We want more beer and we want more beer,
- We are the more beer wanters!
-
-=head2 remove(string)
-
-Searches the input text for any occurrences of the specified string and
-removes them. A Perl regular expression may be specified as the search
-string.
-
- [% "The cat sat on the mat" FILTER remove('\s+') %]
-
-output:
-
- Thecatsatonthemat
-
-=head2 replace(search, replace)
-
-Similar to the remove filter described above, but taking a second parameter
-which is used as a replacement string for instances of the search string.
-
- [% "The cat sat on the mat" | replace('\s+', '_') %]
-
-output:
-
- The_cat_sat_on_the_mat
-
-=head2 redirect(file, options)
-
-The 'redirect' filter redirects the output of the block into a separate
-file, specified relative to the OUTPUT_PATH configuration item.
-
- [% FOREACH user = myorg.userlist %]
- [% FILTER redirect("users/${user.id}.html") %]
- [% INCLUDE userinfo %]
- [% END %]
- [% END %]
-
-or more succinctly, using side-effect notation:
-
- [% INCLUDE userinfo
- FILTER redirect("users/${user.id}.html")
- FOREACH user = myorg.userlist
- %]
-
-A 'file' exception will be thrown if the OUTPUT_PATH option is undefined.
-
-An optional 'binmode' argument can follow the filename to explicitly set
-the output file to binary mode.
-
- [% PROCESS my/png/generator
- FILTER redirect("images/logo.png", binmode=1) %]
-
-For backwards compatibility with earlier versions, a single true/false
-value can be used to set binary mode.
-
- [% PROCESS my/png/generator
- FILTER redirect("images/logo.png", 1) %]
-
-For the sake of future compatibility and clarity, if nothing else, we
-would strongly recommend you explicitly use the named 'binmode' option
-as shown in the first example.
-
-=head2 eval / evaltt
-
-The 'eval' filter evaluates the block as template text, processing
-any directives embedded within it. This allows template variables to
-contain template fragments, or for some method to be provided for
-returning template fragments from an external source such as a
-database, which can then be processed in the template as required.
-
- my $vars = {
- fragment => "The cat sat on the [% place %]",
- };
- $template->process($file, $vars);
-
-The following example:
-
- [% fragment | eval %]
-
-is therefore equivalent to
-
- The cat sat on the [% place %]
-
-The 'evaltt' filter is provided as an alias for 'eval'.
-
-=head2 perl / evalperl
-
-The 'perl' filter evaluates the block as Perl code. The EVAL_PERL
-option must be set to a true value or a 'perl' exception will be
-thrown.
-
- [% my_perl_code | perl %]
-
-In most cases, the [% PERL %] ... [% END %] block should suffice for
-evaluating Perl code, given that template directives are processed
-before being evaluate as Perl. Thus, the previous example could have
-been written in the more verbose form:
-
- [% PERL %]
- [% my_perl_code %]
- [% END %]
-
-as well as
-
- [% FILTER perl %]
- [% my_perl_code %]
- [% END %]
-
-The 'evalperl' filter is provided as an alias for 'perl' for backwards
-compatibility.
-
-=head2 stdout(options)
-
-The stdout filter prints the output generated by the enclosing block to
-STDOUT. The 'binmode' option can be passed as either a named parameter
-or a single argument to set STDOUT to binary mode (see the
-binmode perl function).
-
- [% PROCESS something/cool
- FILTER stdout(binmode=1) # recommended %]
-
- [% PROCESS something/cool
- FILTER stdout(1) # alternate %]
-
-The stdout filter can be used to force binmode on STDOUT, or also inside
-redirect, null or stderr blocks to make sure that particular output goes
-to stdout. See the null filter below for an example.
-
-=head2 stderr
-
-The stderr filter prints the output generated by the enclosing block to
-STDERR.
-
-=head2 null
-
-The null filter prints nothing. This is useful for plugins whose
-methods return values that you don't want to appear in the output.
-Rather than assigning every plugin method call to a dummy variable
-to silence it, you can wrap the block in a null filter:
-
- [% FILTER null;
- USE im = GD.Image(100,100);
- black = im.colorAllocate(0, 0, 0);
- red = im.colorAllocate(255,0, 0);
- blue = im.colorAllocate(0, 0, 255);
- im.arc(50,50,95,75,0,360,blue);
- im.fill(50,50,red);
- im.png | stdout(1);
- END;
- -%]
-
-Notice the use of the stdout filter to ensure that a particular expression
-generates output to stdout (in this case in binary mode).
-
-=head2 latex(outputType)
-
-The latex() filter is no longer part of the core Template Toolkit
-distribution as of version 2.15. You can download it as a
-separate Template-Latex distribution from CPAN.
-
=head1 AUTHOR
-Andy Wardley E<lt>abw@wardley.orgE<gt>
+Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/>
-L<http://wardley.org/|http://wardley.org/>
-
-
-
-
-=head1 VERSION
-
-2.86, distributed as part of the
-Template Toolkit version 2.19, released on 27 April 2007.
-
=head1 COPYRIGHT
- Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
+Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
-
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
=head1 SEE ALSO
-L<Template|Template>, L<Template::Context|Template::Context>, L<Template::Manual::Filters|Template::Manual::Filters>
+L<Template::Manual::Filters>, L<Template>, L<Template::Context>
=cut
Modified: trunk/lib/Template/Grammar.pm
===================================================================
--- trunk/lib/Template/Grammar.pm 2007-05-07 08:22:43 UTC (rev 1077)
+++ trunk/lib/Template/Grammar.pm 2007-05-14 19:20:05 UTC (rev 1078)
@@ -6199,14 +6199,60 @@
1;
+__END__
+=head1 NAME
+Template::Grammar - Parser state/rule tables for the TT grammar
+=head1 SYNOPSIS
+ # no user serviceable parts inside
+=head1 DESCRIPTION
+This module defines the state and rule tables that the L<Template::Parser>
+module uses to parse templates. It is generated from a YACC-like grammar
+using the C<Parse::Yapp> module. The F<parser> sub-directory of the
+Template Toolkit source distribution contains the grammar and other
+files required to generate this module.
+But you don't need to worry about any of that unless you're planning to
+modify the Template Toolkit language.
+=head1 AUTHOR
+Andy Wardley E<lt>abw@wardley.orgE<gt>
+L<http://wardley.org/>
+=head1 COPYRIGHT
+
+Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
+
+This module is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+
+=head1 SEE ALSO
+
+L<Template::Parser>
+
+=cut
+
+# Local Variables:
+# mode: perl
+# perl-indent-level: 4
+# indent-tabs-mode: nil
+# End:
+#
+# vim: expandtab shiftwidth=4:
+
+
+
+
+
+
+
+
+
+
Modified: trunk/lib/Template/Iterator.pm
===================================================================
--- trunk/lib/Template/Iterator.pm 2007-05-07 08:22:43 UTC (rev 1077)
+++ trunk/lib/Template/Iterator.pm 2007-05-14 19:20:05 UTC (rev 1078)
@@ -8,39 +8,15 @@
# directive for iterating through data sets. This may be
# sub-classed to define more specific iterator types.
#
-# An iterator is an object which provides a consistent way to
-# navigate through data which may have a complex underlying form.
-# This implementation uses the get_first() and get_next() methods to
-# iterate through a dataset. The get_first() method is called once
-# to perform any data initialisation and return the first value,
-# then get_next() is called repeatedly to return successive values.
-# Both these methods return a pair of values which are the data item
-# itself and a status code. The default implementation handles
-# iteration through an array (list) of elements which is passed by
-# reference to the constructor. An empty list is used if none is
-# passed. The module may be sub-classed to provide custom
-# implementations which iterate through any kind of data in any
-# manner as long as it can conforms to the get_first()/get_next()
-# interface. The object also implements the get_all() method for
-# returning all remaining elements as a list reference.
-#
-# For further information on iterators see "Design Patterns", by the
-# "Gang of Four" (Erich Gamma, Richard Helm, Ralph Johnson, John
-# Vlissides), Addision-Wesley, ISBN 0-201-63361-2.
-#
# AUTHOR
-# Andy Wardley <abw@kfs.org>
+# Andy Wardley <abw@wardley.org>
#
# COPYRIGHT
-# Copyright (C) 1996-2000 Andy Wardley. All Rights Reserved.
-# Copyright (C) 1998-2000 Canon Research Centre Europe Ltd.
+# Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
#
# This module is free software; you can redistribute it and/or
# modify it under the same terms as Perl itself.
#
-# REVISION
-# $Id$
-#
#============================================================================
package Template::Iterator;
@@ -54,7 +30,6 @@
our $DEBUG = 0 unless defined $DEBUG;
our $AUTOLOAD;
-
#========================================================================
# ----- CLASS METHODS -----
#========================================================================
@@ -118,7 +93,7 @@
# initialise various counters, flags, etc.
@$self{ qw( SIZE MAX INDEX COUNT FIRST LAST ) }
- = ( $size, $size - 1, $index, 1, 1, $size > 1 ? 0 : 1, undef );
+ = ( $size, $size - 1, $index, 1, 1, $size > 1 ? 0 : 1, undef );
@$self{ qw( PREV NEXT ) } = ( undef, $self->{ _DATASET }->[ $index + 1 ]);
return $self->{ _DATASET }->[ $index ];
@@ -153,7 +128,7 @@
@$self{ qw( INDEX COUNT FIRST LAST ) }
= ( $index, $index + 1, 0, $index == $max ? 1 : 0 );
@$self{ qw( PREV NEXT ) } = @$data[ $index - 1, $index + 1 ];
- return $data->[ $index ]; ## RETURN ##
+ return $data->[ $index ]; ## RETURN ##
}
else {
return (undef, Template::Constants::STATUS_DONE); ## RETURN ##
@@ -185,7 +160,7 @@
@$self{ qw( INDEX COUNT FIRST LAST ) }
= ( $max, $max + 1, 0, 1 );
- return \@data; ## RETURN ##
+ return \@data; ## RETURN ##
}
else {
return (undef, Template::Constants::STATUS_DONE); ## RETURN ##
@@ -242,18 +217,6 @@
__END__
-
-#------------------------------------------------------------------------
-# IMPORTANT NOTE
-# This documentation is generated automatically from source
-# templates. Any changes you make here may be lost.
-#
-# The 'docsrc' documentation source bundle is available for download
-# from http://www.template-toolkit.org/docs.html and contains all
-# the source templates, XML files, scripts, etc., from which the
-# documentation for the Template Toolkit is built.
-#------------------------------------------------------------------------
-
=head1 NAME
Template::Iterator - Data iterator used by the FOREACH directive
@@ -264,8 +227,8 @@
=head1 DESCRIPTION
-The Template::Iterator module defines a generic data iterator for use
-by the FOREACH directive.
+The C<Template::Iterator> module defines a generic data iterator for use
+by the C<FOREACH> directive.
It may be used as the base class for custom iterators.
@@ -274,25 +237,25 @@
=head2 new($data)
Constructor method. A reference to a list of values is passed as the
-first parameter. Subsequent calls to get_first() and get_next() calls
+first parameter. Subsequent calls to L<get_first()> and L<get_next()> calls
will return each element from the list.
my $iter = Template::Iterator->new([ 'foo', 'bar', 'baz' ]);
The constructor will also accept a reference to a hash array and will
expand it into a list in which each entry is a hash array containing
-a 'key' and 'value' item, sorted according to the hash keys.
+a 'C<key>' and 'C<value>' item, sorted according to the hash keys.
my $iter = Template::Iterator->new({
- foo => 'Foo Item',
- bar => 'Bar Item',
+ foo => 'Foo Item',
+ bar => 'Bar Item',
});
This is equivalent to:
my $iter = Template::Iterator->new([
- { key => 'bar', value => 'Bar Item' },
- { key => 'foo', value => 'Foo Item' },
+ { key => 'bar', value => 'Bar Item' },
+ { key => 'foo', value => 'Foo Item' },
]);
When passed a single item which is not an array reference, the constructor
@@ -315,18 +278,18 @@
my $iter = Template::Iterator->new([ $list ]);
-If the object provides an as_list() method then the Template::Iterator
+If the object provides an C<as_list()> method then the L<Template::Iterator>
constructor will call that method to return the list of data. For example:
package MyListObject;
-
+
sub new {
- my $class = shift;
- bless [ @_ ], $class;
+ my $class = shift;
+ bless [ @_ ], $class;
}
package main;
-
+
my $list = MyListObject->new('foo', 'bar');
my $iter = Template::Iterator->new($list);
@@ -334,47 +297,47 @@
my $iter = Template::Iterator->new([ $list ]);
-The iterator will return only one item, a reference to the MyListObject
-object, $list.
+The iterator will return only one item, a reference to the C<MyListObject>
+object, C<$list>.
-By adding an as_list() method to the MyListObject class, we can force
-the Template::Iterator constructor to treat the object as a list and
+By adding an C<as_list()> method to the C<MyListObject> class, we can force
+the C<Template::Iterator> constructor to treat the object as a list and
use the data contained within.
package MyListObject;
-
+
...
-
+
sub as_list {
- my $self = shift;
- return $self;
+ my $self = shift;
+ return $self;
}
-
+
package main;
-
+
my $list = MyListObject->new('foo', 'bar');
my $iter = Template::Iterator->new($list);
-The iterator will now return the two item, 'foo' and 'bar', which the
-MyObjectList encapsulates.
+The iterator will now return the two items, 'C<foo>' and 'C<bar>', which the
+C<MyObjectList> encapsulates.
=head2 get_first()
-Returns a ($value, $error) pair for the first item in the iterator set.
-The $error returned may be zero or undefined to indicate a valid datum
-was successfully returned. Returns an error of STATUS_DONE if the list
+Returns a C<($value, $error)> pair for the first item in the iterator set.
+The C<$error> returned may be zero or undefined to indicate a valid datum
+was successfully returned. Returns an error of C<STATUS_DONE> if the list
is empty.
=head2 get_next()
-Returns a ($value, $error) pair for the next item in the iterator set.
-Returns an error of STATUS_DONE if all items in the list have been
+Returns a C<($value, $error)> pair for the next item in the iterator set.
+Returns an error of C<STATUS_DONE> if all items in the list have been
visited.
=head2 get_all()
-Returns a (\@values, $error) pair for all remaining items in the iterator
-set. Returns an error of STATUS_DONE if all items in the list have been
+Returns a C<(\@values, $error)> pair for all remaining items in the iterator
+set. Returns an error of C<STATUS_DONE> if all items in the list have been
visited.
=head2 size()
@@ -384,17 +347,16 @@
=head2 max()
Returns the maximum index number (i.e. the index of the last element)
-which is equivalent to size() - 1.
+which is equivalent to L<size()> - C<1>.
=head2 index()
-Returns the current index number which is in the range 0 to max().
+Returns the current index number which is in the range C<0> to L<max()>.
=head2 count()
-Returns the current iteration count in the range 1 to size(). This is
-equivalent to index() + 1. Note that number() is supported as an alias
-for count() for backwards compatability.
+Returns the current iteration count in the range C<1> to L<size()>. This is
+equivalent to L<index()> + C<1>.
=head2 first()
@@ -408,39 +370,30 @@
=head2 prev()
-Returns the previous item in the data set, or undef if the iterator is
+Returns the previous item in the data set, or C<undef> if the iterator is
on the first item.
=head2 next()
-Returns the next item in the data set or undef if the iterator is on the
+Returns the next item in the data set or C<undef> if the iterator is on the
last item.
=head1 AUTHOR
Andy Wardley E<lt>abw@wardley.orgE<gt>
-L<http://wardley.org/|http://wardley.org/>
+L<http://wardley.org/>
-
-
-
-=head1 VERSION
-
-2.68, distributed as part of the
-Template Toolkit version 2.19, released on 27 April 2007.
-
=head1 COPYRIGHT
- Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
+Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
-
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
=head1 SEE ALSO
-L<Template|Template>
+L<Template>
=cut
Modified: trunk/lib/Template/Manual/Config.pod
===================================================================
--- trunk/lib/Template/Manual/Config.pod 2007-05-07 08:22:43 UTC (rev 1077)
+++ trunk/lib/Template/Manual/Config.pod 2007-05-14 19:20:05 UTC (rev 1078)
@@ -497,7 +497,7 @@
=head1 Template Variables
-=head2 VARIABLES, PRE_DEFINE
+=head2 VARIABLES
The C<VARIABLES> option (or C<PRE_DEFINE> - they're equivalent) can be used
to specify a hash array of template variables that should be used to
@@ -1299,6 +1299,24 @@
multiple providers, ensuring that the request is passed down through the
providers as quickly as possible.
+=head2 STAT_TTL
+
+This value can be set to control how long the L<Template::Provider> will keep a
+template cached in memory before checking to see if the source template has
+changed.
+
+ my $provider = Template::Provider->new({
+ STAT_TTL => 60, # one minute
+ });
+
+The default value is 1 (second). You'll probably want to set this to a higher
+value if you're running the Template Toolkit inside a persistent web server
+application (e.g. mod_perl). For example, set it to 60 and the provider will
+only look for changes to templates once a minute at most. However, during
+development (or any time you're making frequent changes to templates) you'll
+probably want to keep it set to a low value so that you don't have to wait
+for the provider to notice that your templates have changed.
+
=head2 COMPILE_EXT
From version 2 onwards, the Template Toolkit has the ability to
@@ -1729,7 +1747,7 @@
"compiled" template documents. Template subroutines make callbacks into the
context object to access Template Toolkit functionality, for example, to to
C<INCLUDE> or C<PROCESS> another template
-(L<L<Template::Context#include()|include()> and
+(L<Template::Context#include()|include()> and
L<Template::Context#process()|process()> methods, respectively), to C<USE> a
plugin (L<Template::Context#plugin()|plugin()>) or instantiate a filter
(L<Template::Context#filter()|filter()>) or to access the stash
Modified: trunk/lib/Template/Map.pm
===================================================================
--- trunk/lib/Template/Map.pm 2007-05-07 08:22:43 UTC (rev 1077)
+++ trunk/lib/Template/Map.pm 2007-05-14 19:20:05 UTC (rev 1078)
@@ -12,17 +12,14 @@
# distribution and may never be.
#
# AUTHOR
-# Andy Wardley <abw@kfs.org>
+# Andy Wardley <abw@wardley.org>
#
# COPYRIGHT
-# Copyright (C) 2000 Andy Wardley. All Rights Reserved.
+# Copyright (C) 2007 Andy Wardley. All Rights Reserved.
#
# This module is free software; you can redistribute it and/or
# modify it under the same terms as Perl itself.
#
-# REVISION
-# $Id$
-#
#============================================================================
package Template::Map;
Modified: trunk/lib/Template/Parser.pm
===================================================================
--- trunk/lib/Template/Parser.pm 2007-05-07 08:22:43 UTC (rev 1077)
+++ trunk/lib/Template/Parser.pm 2007-05-14 19:20:05 UTC (rev 1078)
@@ -12,8 +12,7 @@
# Andy Wardley <abw@wardley.org>
#
# COPYRIGHT
-# Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
-# Copyright (C) 1998-2000 Canon Research Centre Europe Ltd.
+# Copyright (C) 1996-2007 Andy Wardley. All Rights Reserved.
#
# This module is free software; you can redistribute it and/or
# modify it under the same terms as Perl itself.
@@ -29,9 +28,6 @@
# the GNU General Public License or the Artistic License, as
# specified in the Perl README file.
#
-# REVISION
-# $Id$
-#
#============================================================================
package Template::Parser;
@@ -85,9 +81,9 @@
};
our $QUOTED_ESCAPES = {
- n => "\n",
- r => "\r",
- t => "\t",
+ n => "\n",
+ r => "\r",
+ t => "\t",
};
# note that '-' must come first so Perl doesn't think it denotes a range
@@ -169,7 +165,7 @@
$self->new_style($config)
|| return $class->error($self->error());
-
+
return $self;
}
@@ -237,7 +233,7 @@
my ($tokens, $block);
$info->{ DEBUG } = $self->{ DEBUG_DIRS }
- unless defined $info->{ DEBUG };
+ unless defined $info->{ DEBUG };
# print "info: { ", join(', ', map { "$_ => $info->{ $_ }" } keys %$info), " }\n";
@@ -250,7 +246,7 @@
# split file into TEXT/DIRECTIVE chunks
$tokens = $self->split_text($text)
- || return undef; ## RETURN ##
+ || return undef; ## RETURN ##
push(@{ $self->{ FILEINFO } }, $info);
@@ -259,7 +255,7 @@
pop(@{ $self->{ FILEINFO } });
- return undef unless $block; ## RETURN ##
+ return undef unless $block; ## RETURN ##
$self->debug("compiled main template document block:\n$block")
if $self->{ DEBUG } & Template::Constants::DEBUG_PARSER;
@@ -289,8 +285,8 @@
my @tokens = ();
my $line = 1;
- return \@tokens ## RETURN ##
- unless defined $text && length $text;
+ return \@tokens ## RETURN ##
+ unless defined $text && length $text;
# extract all directives from the text
while ($text =~ s/
@@ -401,7 +397,7 @@
: ( 'TEXT', $text) )
if length $text;
- return \@tokens; ## RETURN ##
+ return \@tokens; ## RETURN ##
}
@@ -423,32 +419,32 @@
/
( (?: \\. | [^\$] ){1,3000} ) # escaped or non-'$' character [$1]
|
- ( \$ (?: # embedded variable [$2]
- (?: \{ ([^\}]*) \} ) # ${ ... } [$3]
- |
- ([\w\.]+) # $word [$4]
- )
- )
- /gx) {
+ ( \$ (?: # embedded variable [$2]
+ (?: \{ ([^\}]*) \} ) # ${ ... } [$3]
+ |
+ ([\w\.]+) # $word [$4]
+ )
+ )
+ /gx) {
- ($pre, $var, $dir) = ($1, $3 || $4, $2);
+ ($pre, $var, $dir) = ($1, $3 || $4, $2);
- # preceding text
- if (defined($pre) && length($pre)) {
- $line += $pre =~ tr/\n//;
- $pre =~ s/\\\$/\$/g;
- push(@tokens, 'TEXT', $pre);
- }
- # $variable reference
+ # preceding text
+ if (defined($pre) && length($pre)) {
+ $line += $pre =~ tr/\n//;
+ $pre =~ s/\\\$/\$/g;
+ push(@tokens, 'TEXT', $pre);
+ }
+ # $variable reference
if ($var) {
- $line += $dir =~ tr/\n/ /;
- push(@tokens, [ $dir, $line, $self->tokenise_directive($var) ]);
- }
- # other '$' reference - treated as text
- elsif ($dir) {
- $line += $dir =~ tr/\n//;
- push(@tokens, 'TEXT', $dir);
- }
+ $line += $dir =~ tr/\n/ /;
+ push(@tokens, [ $dir, $line, $self->tokenise_directive($var) ]);
+ }
+ # other '$' reference - treated as text
+ elsif ($dir) {
+ $line += $dir =~ tr/\n//;
+ push(@tokens, 'TEXT', $dir);
+ }
}
return \@tokens;
@@ -488,114 +484,114 @@
my @tokens = ( );
while ($text =~
- /
- # strip out any comments
- (\#[^\n]*)
- |
- # a quoted phrase matches in $3
- (["']) # $2 - opening quote, ' or "
- ( # $3 - quoted text buffer
- (?: # repeat group (no backreference)
- \\\\ # an escaped backslash \\
- | # ...or...
- \\\2 # an escaped quote \" or \' (match $1)
- | # ...or...
- . # any other character
- | \n
- )*? # non-greedy repeat
- ) # end of $3
- \2 # match opening quote
- |
- # an unquoted number matches in $4
- (-?\d+(?:\.\d+)?) # numbers
- |
- # filename matches in $5
- ( \/?\w+(?:(?:\/|::?)\w*)+ | \/\w+)
- |
- # an identifier matches in $6
- (\w+) # variable identifier
- |
- # an unquoted word or symbol matches in $7
- ( [(){}\[\]:;,\/\\] # misc parenthesis and symbols
-# | \-> # arrow operator (for future?)
- | [+\-*] # math operations
- | \$\{? # dollar with option left brace
- | => # like '='
- | [=!<>]?= | [!<>] # eqality tests
- | &&? | \|\|? # boolean ops
- | \.\.? # n..n sequence
- | \S+ # something unquoted
- ) # end of $7
- /gmxo) {
+ /
+ # strip out any comments
+ (\#[^\n]*)
+ |
+ # a quoted phrase matches in $3
+ (["']) # $2 - opening quote, ' or "
+ ( # $3 - quoted text buffer
+ (?: # repeat group (no backreference)
+ \\\\ # an escaped backslash \\
+ | # ...or...
+ \\\2 # an escaped quote \" or \' (match $1)
+ | # ...or...
+ . # any other character
+ | \n
+ )*? # non-greedy repeat
+ ) # end of $3
+ \2 # match opening quote
+ |
+ # an unquoted number matches in $4
+ (-?\d+(?:\.\d+)?) # numbers
+ |
+ # filename matches in $5
+ ( \/?\w+(?:(?:\/|::?)\w*)+ | \/\w+)
+ |
+ # an identifier matches in $6
+ (\w+) # variable identifier
+ |
+ # an unquoted word or symbol matches in $7
+ ( [(){}\[\]:;,\/\\] # misc parenthesis and symbols
+# | \-> # arrow operator (for future?)
+ | [+\-*] # math operations
+ | \$\{? # dollar with option left brace
+ | => # like '='
+ |