[Templates-svn] r1082 - in trunk/lib/Template: . Manual Plugin
svn@template-toolkit.org
svn@template-toolkit.org
Author: abw
Date: 2007-05-26 16:43:31 +0100 (Sat, 26 May 2007)
New Revision: 1082
Modified:
trunk/lib/Template/Manual.pod
trunk/lib/Template/Manual/Plugins.pod
trunk/lib/Template/Modules.pod
trunk/lib/Template/Plugin/Autoformat.pm
trunk/lib/Template/Plugin/CGI.pm
trunk/lib/Template/Plugin/Datafile.pm
trunk/lib/Template/Plugin/Date.pm
trunk/lib/Template/Plugin/Directory.pm
trunk/lib/Template/Plugin/Dumper.pm
trunk/lib/Template/Plugin/File.pm
trunk/lib/Template/Plugin/Filter.pm
trunk/lib/Template/Plugin/Format.pm
trunk/lib/Template/Plugin/HTML.pm
trunk/lib/Template/Plugin/Image.pm
trunk/lib/Template/Plugin/Iterator.pm
trunk/lib/Template/Plugin/List.pm
trunk/lib/Template/Plugin/Math.pm
trunk/lib/Template/Plugin/Pod.pm
trunk/lib/Template/Plugin/Procedural.pm
trunk/lib/Template/Plugin/String.pm
trunk/lib/Template/Plugin/Table.pm
trunk/lib/Template/Plugin/URL.pm
trunk/lib/Template/Plugin/View.pm
trunk/lib/Template/Plugin/Wrap.pm
trunk/lib/Template/Provider.pm
trunk/lib/Template/Service.pm
trunk/lib/Template/Stash.pm
trunk/lib/Template/Test.pm
trunk/lib/Template/Tools.pod
trunk/lib/Template/Tutorial.pod
Log:
cleaned up docs in plugins and various other modules
Modified: trunk/lib/Template/Manual/Plugins.pod
===================================================================
--- trunk/lib/Template/Manual/Plugins.pod 2007-05-26 15:42:40 UTC (rev 1081)
+++ trunk/lib/Template/Manual/Plugins.pod 2007-05-26 15:43:31 UTC (rev 1082)
@@ -27,15 +27,15 @@
=head2 Autoformat
The L<Template::Plugin::Autoformat|Autoformat> plugin is an interface to
-Damian Conway's Text::Autoformat Perl module which provides advanced text
+Damian Conway's L<Text::Autoformat> Perl module which provides advanced text
wrapping and formatting. See L<Template::Plugin::Autoformat> and
-C<Text::Autoformat> for further details.
+L<Text::Autoformat> for further details.
[% USE autoformat(left=10, right=20) %]
[% autoformat(mytext) %] # call autoformat sub
[% mytext FILTER autoformat %] # or use autoformat filter
-The C<Text::Autoformat> module is available from CPAN:
+The L<Text::Autoformat> module is available from CPAN:
L<http://www.cpan.org/modules/by-module/Text/>
@@ -43,7 +43,7 @@
The L<Template::Plugin::CGI|CGI> plugin is a wrapper around Lincoln Stein's
CGI.pm module. The plugin is distributed with the Template Toolkit (see
-L<Template::Plugin::CGI>) and the C<CGI> module itself is distributed with
+L<Template::Plugin::CGI>) and the L<CGI> module itself is distributed with
recent versions Perl, or is available from CPAN.
[% USE CGI %]
@@ -81,7 +81,7 @@
=head2 Date
The L<Template::Plugin::Date|Date> plugin provides an easy way to generate
-formatted time and date strings by delegating to the POSIX C<strftime()>
+formatted time and date strings by delegating to the L<POSIX> C<strftime()>
routine. See L<Template::Plugin::Date> and L<POSIX> for further details.
[% USE date %]
@@ -169,7 +169,7 @@
=head2 GD
The C<GD> plugins are no longer part of the core Template Toolkit distribution.
-They are now available in a separate C<Template-GD> distribution.
+They are now available in a separate L<Template-GD> distribution.
=head2 HTML
@@ -259,7 +259,7 @@
=head2 Wrap
-The L<Template::Plugin::Wrap|Wrap> plugin uses the C<Text::Wrap> module to
+The L<Template::Plugin::Wrap|Wrap> plugin uses the L<Text::Wrap> module to
provide simple paragraph formatting. See L<Template::Plugin::Wrap> and
L<Text::Wrap> for further details.
@@ -276,7 +276,7 @@
The C<XML::DOM>, C<XML::RSS>, C<XML::Simple> and C<XML::XPath> plugins are no
longer distributed with the Template Toolkit as of version 2.15
-They are now available in a separate C<Template-XML> distribution.
+They are now available in a separate L<Template-XML> distribution.
=cut
Modified: trunk/lib/Template/Manual.pod
===================================================================
--- trunk/lib/Template/Manual.pod 2007-05-26 15:42:40 UTC (rev 1081)
+++ trunk/lib/Template/Manual.pod 2007-05-26 15:43:31 UTC (rev 1082)
@@ -3,7 +3,7 @@
# Template::Manual
#
# DESCRIPTION
-
+# Front-page for the TT manual.
#
# AUTHOR
# Andy Wardley <abw@wardley.org>
@@ -14,132 +14,68 @@
# This module is free software; you can redistribute it and/or
# modify it under the same terms as Perl itself.
#
-# REVISION
-#
-#
#========================================================================
+=head1 Template Toolkit Manual
-#------------------------------------------------------------------------
-# 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.
-#------------------------------------------------------------------------
+The Template Toolkit manual contains documentation on using and extending
+the Template Toolkit.
-=head1 NAME
+=head2 Template::Manual::Intro
-Template::Manual - User guide and reference manual for the Template Toolkit
+The L<Template::Manual::Intro> page provides an introduction to the Template Toolkit
-=head1 DESCRIPTION
+=head2 Template::Manual::Syntax
+The L<Template::Manual::Syntax> desribes the syntax and structure of
+templates and the directive tags embedded within them.
+=head2 Template::Manual::Directives
-=over 4
+The L<Template::Manual::Directives> page lists all the Template Toolkit
+directives and gives examples of their use.
-=item L<Template::Manual::Intro|Template::Manual::Intro>
+=head2 Template::Manual::Variables
-Introduction to the Template Toolkit
+The L<Template::Manual::Variables> page describes the use of variables
+in templates.
+=head2 Template::Manual::VMethods
+The L<Template::Manual::VMethods> page provides a full list of virtual
+methods that can be used in conjunction with variables, and gives examples
+of their use.
-=item L<Template::Manual::Syntax|Template::Manual::Syntax>
+=head2 Template::Manual::Config
-Directive syntax, structure and semantics
+The L<Template::Manual::Config> page describes all of the Template Toolkit
+configuration options.
+=head2 Template::Manual::Filters
+The L<Template::Manual::Filters> page lists all of the Template Toolkit
+filters and gives examples of their use.
-=item L<Template::Manual::Directives|Template::Manual::Directives>
+=head2 Template::Manual::Plugins
-Template directives
+The L<Template::Manual::Plugins> page lists all of the standard plugins
+distributed with Template Toolkit and gives examples of their use.
+=head2 Template::Manual::Internals
+The L<Template::Manual::Internals> page describes the internal workings of the
+Template Toolkit. It is aimed at developers who wish to extend or modify the
-=item L<Template::Manual::Variables|Template::Manual::Variables>
+=head2 Template::Manual::Views
-Template variables and code bindings
+The L<Template::Manual::Views> page describes the experimental C<VIEW>
+directive.
+=head2 Template::Manual::Credits
+The L<Template::Manual::Credits> page lists the people who have contributed to
+the Template Toolkit.
-=item L<Template::Manual::VMethods|Template::Manual::VMethods>
-
-Virtual Methods
-
-
-
-=item L<Template::Manual::Config|Template::Manual::Config>
-
-Configuration options
-
-
-
-=item L<Template::Manual::Filters|Template::Manual::Filters>
-
-Standard filters
-
-
-
-=item L<Template::Manual::Plugins|Template::Manual::Plugins>
-
-Standard plugins
-
-
-
-=item L<Template::Manual::Internals|Template::Manual::Internals>
-
-Template Toolkit internals
-
-
-
-=item L<Template::Manual::Views|Template::Manual::Views>
-
-Template Toolkit views (experimental)
-
-
-
-=item L<Template::Manual::Refs|Template::Manual::Refs>
-
-Related modules, projects and other resources
-
-
-
-=item L<Template::Manual::Credits|Template::Manual::Credits>
-
-Author and contributor credits
-
-
-
-
-
-=back
-
-=head1 AUTHOR
-
-Andy Wardley E<lt>abw@wardley.orgE<gt>
-
-L<http://wardley.org/|http://wardley.org/>
-
-
-
-
-=head1 VERSION
-
-Template Toolkit version 2.19, released on 27 April 2007.
-
-=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.
-
-
-
=cut
# Local Variables:
Modified: trunk/lib/Template/Modules.pod
===================================================================
--- trunk/lib/Template/Modules.pod 2007-05-26 15:42:40 UTC (rev 1081)
+++ trunk/lib/Template/Modules.pod 2007-05-26 15:43:31 UTC (rev 1082)
@@ -3,7 +3,6 @@
# Template::Modules
#
# DESCRIPTION
-
#
# AUTHOR
# Andy Wardley <abw@wardley.org>
@@ -14,300 +13,154 @@
# This module is free software; you can redistribute it and/or
# modify it under the same terms as Perl itself.
#
-# REVISION
-#
-#
#========================================================================
+=head1 Template Toolkit Modules
-#------------------------------------------------------------------------
-# 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.
-#------------------------------------------------------------------------
+This documentation provides an overview of the different modules that
+comprise the Template Toolkit.
-=head1 NAME
+=head2 Template
-Template::Modules - Core modules comprising the Template Toolkit
+The L<Template> module is the front-end to the Template Toolkit for
+Perl programmers.
-=head1 DESCRIPTION
+ use Template;
+ my $tt = Template->new();
+ $tt->process('hello.html', message => 'Hello World');
+=head2 Template::Base
+The L<Template::Base> module implements a base class from which the other
+Template Toolkit modules are derived. It implements common functionality
+for creating objects, error reporting, debugging, and so on.
-=over 4
+=head2 Template::Config
-=item L<Template|Template>
+The L<Template::Config> module defines the configuration of the Template
+Toolkit for your system. It is an example of a I<factory module> which is
+responsible for instantiating the various other modules used in the Template
+Toolkit.
-Front-end module to the Template Toolkit
+For example, the L<Template::Config> module defines the C<$STASH> package
+variable which indicates which version of the L<Template::Stash> you are
+using by default. If you elected to use the faster L<Template::Stash::XS|XS>
+stash when you installed the Template Toolkit, then this will be set as:
+ $STASH = 'Template::Stash::XS';
+Otherwise you'll get the regular L<Template::Stash|Perl> stash:
-=item L<Template::Base|Template::Base>
+ $STASH = 'Template::Stash';
-Base class module implementing common functionality
+This approach means that other parts of the Template Toolkit don't have to
+worry about which stash you're using. They just ask the L<Template::Config>
+module to create a stash of the right kind.
+=head2 Template::Constants
+The L<Template::Constants> defines a number of constants that are used by
+the Template Toolkit.
-=item L<Template::Config|Template::Config>
+For example, the C<:chomp> tagset defines the C<CHOMP_???> constants that
+can be used with the C<PRE_CHOMP> and C<POST_CHOMP> configuration options.
-Factory module for instantiating other TT2 modules
+ use Template::Constants ':chomp';
+ my $tt = Template->new({
+ PRE_CHOMP => CHOMP_COLLAPSE,
+ });
+=head2 Template::Context
+The L<Template::Context> module defines a runtime context in which templates
+are processed. A context keeps track of all the templates, variables, plugins,
+and other resources that are available (either directly or through delegate
+objects) and provides methods to fetch, store, and perform various operations
+on them.
-=item L<Template::Constants|Template::Constants>
+=head2 Template::Document
-Defines constants for the Template Toolkit
+The L<Template::Document> module implements a compiled template document
+object. This is generated by the L<Template::Parser|parser>.
+=head2 Template::Exception
+The L<Template::Exception> module implements an exception object which
+is used for runtime error reporting.
-=item L<Template::Context|Template::Context>
+=head2 Template::Filters
-Runtime context in which templates are processed
+The L<Template::Filters> module implements a filter provider. It includes
+the core collection of filters that can be used via the C<FILTER> directive.
+=head2 Template::Iterator
+The L<Template::Iterator> module implements a data iterator which steps
+through each item in a list in turn. It is used by the C<FOREACH> directive.
+Within a C<FOREACH> block, the C<loop> variable always references the
+current iterator object.
-=item L<Template::Document|Template::Document>
+ [% FOREACH item IN list;
+ IF loop.first;
+ # first item in loop
+ ELSIF loop.last;
+ # last item in loop
+ ELSE;
+ # any other item in loop
+ END;
+ END
+ %]
-Compiled template document object
+=head2 Template::Namespace::Constants
+The L<Template::Namespace::Constants> module is used internally to represent
+constants. These can be resolved immediately at the point that a template is
+compiled.
+=head2 Template::Parser
-=item L<Template::Exception|Template::Exception>
+The L<Template::Parser> module is used to parse a source template and turn it
+into Perl code which can be executed.
-Exception handling class module
+=head2 Template::Plugin
+The L<Template::Plugin> module is a base class for Template Toolkit plugins
+that can be loaded on demand from within a template using the C<USE> directive.
+=head2 Template::Plugins
-=item L<Template::Filters|Template::Filters>
+The L<Template::Plugins> module is the plugins provider. It loads and prepares
+plugins as and when they are requested from within a template.
-Post-processing filters for template blocks
+=head2 Template::Provider
+The L<Template::Provider> module is responsible for loading, compiling and
+caching templates.
+=head2 Template::Service
-=item L<Template::Iterator|Template::Iterator>
+The L<Template::Service> module implements a service layer that sits just
+behind the L<Template> module, and just in front of a L<Template::Context>. It
+handles each request to process a template (forwarded from the L<Template>
+module). It adds any headers and/or footers (specified via the C<PRE_PROCESS>
+and C<POST_PROCESS> options), applies any wrapper (the C<WRAPPER> option) and
+catches any errors returned (the C<ERRORS> option).
-Data iterator used by the FOREACH directive
+=head2 Template::Stash
+The L<Template::Stash> module is used to fetch and store template variables.
+It implements all of the magic associated with the dot operator.
+=head2 Template::Stash::XS
-=item L<Template::Namespace::Constants|Template::Namespace::Constants>
+The L<Template::Stash::XS> module is a high-speed implementation of
+L<Template::Stash> written in C.
-Compile time constant folding
+=head2 Template::Test
+The L<Template::Test> module is used to automate the Template Toolkit
+test scripts.
-
-=item L<Template::Parser|Template::Parser>
-
-LALR(1) parser for compiling template documents
-
-
-
-=item L<Template::Plugin|Template::Plugin>
-
-Base class for Template Toolkit plugins
-
-
-
-=item L<Template::Plugins|Template::Plugins>
-
-Plugin provider module
-
-
-
-=item L<Template::Provider|Template::Provider>
-
-Provider module for loading/compiling templates
-
-
-
-=item L<Template::Service|Template::Service>
-
-General purpose template processing service
-
-
-
-=item L<Template::Stash|Template::Stash>
-
-Magical storage for template variables
-
-
-
-=item L<Template::Stash::Context|Template::Stash::Context>
-
-Experimetal stash allowing list/scalar context definition
-
-
-
-=item L<Template::Stash::XS|Template::Stash::XS>
-
-High-speed variable stash written in C
-
-
-
-=item L<Template::Test|Template::Test>
-
-Module for automating TT2 test scripts
-
-
-
-=item L<Template::Toolkit|Template::Toolkit>
-
-Template processing system
-
-
-
-=item L<Template::Plugin::Autoformat|Template::Plugin::Autoformat>
-
-Interface to Text::Autoformat module
-
-
-
-=item L<Template::Plugin::CGI|Template::Plugin::CGI>
-
-Interface to the CGI module
-
-
-
-=item L<Template::Plugin::Datafile|Template::Plugin::Datafile>
-
-Plugin to construct records from a simple data file
-
-
-
-=item L<Template::Plugin::Date|Template::Plugin::Date>
-
-Plugin to generate formatted date strings
-
-
-
-=item L<Template::Plugin::Directory|Template::Plugin::Directory>
-
-Plugin for generating directory listings
-
-
-
-=item L<Template::Plugin::Dumper|Template::Plugin::Dumper>
-
-Plugin interface to Data::Dumper
-
-
-
-=item L<Template::Plugin::File|Template::Plugin::File>
-
-Plugin providing information about files
-
-
-
-=item L<Template::Plugin::Filter|Template::Plugin::Filter>
-
-Base class for plugin filters
-
-
-
-=item L<Template::Plugin::Format|Template::Plugin::Format>
-
-Plugin to create formatting functions
-
-
-
-=item L<Template::Plugin::HTML|Template::Plugin::HTML>
-
-Plugin to create HTML elements
-
-
-
-=item L<Template::Plugin::Image|Template::Plugin::Image>
-
-Plugin access to image sizes
-
-
-
-=item L<Template::Plugin::Iterator|Template::Plugin::Iterator>
-
-Plugin to create iterators (Template::Iterator)
-
-
-
-=item L<Template::Plugin::Math|Template::Plugin::Math>
-
-Plugin interface to mathematical functions
-
-
-
-=item L<Template::Plugin::Pod|Template::Plugin::Pod>
-
-Plugin interface to Pod::POM (Pod Object Model)
-
-
-
-=item L<Template::Plugin::Procedural|Template::Plugin::Procedural>
-
-Base class for procedural plugins
-
-
-
-=item L<Template::Plugin::String|Template::Plugin::String>
-
-Object oriented interface for string manipulation
-
-
-
-=item L<Template::Plugin::Table|Template::Plugin::Table>
-
-Plugin to present data in a table
-
-
-
-=item L<Template::Plugin::URL|Template::Plugin::URL>
-
-Plugin to construct complex URLs
-
-
-
-=item L<Template::Plugin::View|Template::Plugin::View>
-
-Plugin to create views (Template::View)
-
-
-
-=item L<Template::Plugin::Wrap|Template::Plugin::Wrap>
-
-Plugin interface to Text::Wrap
-
-
-
-
-
-=back
-
-=head1 AUTHOR
-
-Andy Wardley E<lt>abw@wardley.orgE<gt>
-
-L<http://wardley.org/|http://wardley.org/>
-
-
-
-
-=head1 VERSION
-
-Template Toolkit version 2.19, released on 27 April 2007.
-
-=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.
-
-
-
=cut
# Local Variables:
Modified: trunk/lib/Template/Plugin/Autoformat.pm
===================================================================
--- trunk/lib/Template/Plugin/Autoformat.pm 2007-05-26 15:42:40 UTC (rev 1081)
+++ trunk/lib/Template/Plugin/Autoformat.pm 2007-05-26 15:43:31 UTC (rev 1082)
@@ -14,15 +14,12 @@
# documentation
#
# COPYRIGHT
-# Copyright (C) 2000-2006 Robert McArthur, Andy Wardley.
+# Copyright (C) 2000-2007 Robert McArthur, 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::Plugin::Autoformat;
@@ -40,35 +37,35 @@
my $plugin;
if ($options) {
- # create a closure to generate filters with additional options
- $filter_factory = sub {
- my $context = shift;
- my $filtopt = ref $_[-1] eq 'HASH' ? pop : { };
- @$filtopt{ keys %$options } = values %$options;
- return sub {
- tt_autoformat(@_, $filtopt);
- };
- };
+ # create a closure to generate filters with additional options
+ $filter_factory = sub {
+ my $context = shift;
+ my $filtopt = ref $_[-1] eq 'HASH' ? pop : { };
+ @$filtopt{ keys %$options } = values %$options;
+ return sub {
+ tt_autoformat(@_, $filtopt);
+ };
+ };
- # and a closure to represent the plugin
- $plugin = sub {
- my $plugopt = ref $_[-1] eq 'HASH' ? pop : { };
- @$plugopt{ keys %$options } = values %$options;
- tt_autoformat(@_, $plugopt);
- };
+ # and a closure to represent the plugin
+ $plugin = sub {
+ my $plugopt = ref $_[-1] eq 'HASH' ? pop : { };
+ @$plugopt{ keys %$options } = values %$options;
+ tt_autoformat(@_, $plugopt);
+ };
}
else {
- # simple filter factory closure (no legacy options from constructor)
- $filter_factory = sub {
- my $context = shift;
- my $filtopt = ref $_[-1] eq 'HASH' ? pop : { };
- return sub {
- tt_autoformat(@_, $filtopt);
- };
- };
+ # simple filter factory closure (no legacy options from constructor)
+ $filter_factory = sub {
+ my $context = shift;
+ my $filtopt = ref $_[-1] eq 'HASH' ? pop : { };
+ return sub {
+ tt_autoformat(@_, $filtopt);
+ };
+ };
- # plugin without options can be static
- $plugin = \&tt_autoformat;
+ # plugin without options can be static
+ $plugin = \&tt_autoformat;
}
# now define the filter and return the plugin
@@ -80,24 +77,12 @@
my $options = ref $_[-1] eq 'HASH' ? pop : { };
my $form = $options->{ form };
my $out = $form ? Text::Autoformat::form($options, $form, @_)
- : Text::Autoformat::autoformat(join('', @_), $options);
+ : Text::Autoformat::autoformat(join('', @_), $options);
return $out;
}
__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::Plugin::Autoformat - Interface to Text::Autoformat module
@@ -105,9 +90,9 @@
=head1 SYNOPSIS
[% USE autoformat(options) %]
-
+
[% autoformat(text, more_text, ..., options) %]
-
+
[% FILTER autoformat(options) %]
a block of text
[% END %]
@@ -123,7 +108,7 @@
# pass options to constructor...
[% USE autoformat(case => 'upper') %]
[% autoformat(text) %]
-
+
# and/or pass options to the autoformat subroutine itself
[% USE autoformat %]
[% autoformat(text, case => 'upper') %]
@@ -141,11 +126,11 @@
Be not afeard. The isle is full of noises, sounds and sweet
airs that give delight but hurt not.
[% END %]
-
+
# another FILTER example, defining a 'poetry' filter alias
[% USE autoformat %]
[% text FILTER poetry = autoformat(left => 20, right => 40) %]
-
+
# reuse the 'poetry' filter alias
[% text FILTER poetry %]
@@ -158,11 +143,11 @@
=head1 DESCRIPTION
-The autoformat plugin is an interface to Damian Conway's Text::Autoformat
+The autoformat plugin is an interface to Damian Conway's C<Text::Autoformat>
Perl module which provides advanced text wrapping and formatting.
Configuration options may be passed to the plugin constructor via the
-USE directive.
+C<USE> directive.
[% USE autoformat(right => 30) %]
@@ -177,20 +162,20 @@
[% autoformat(text, left => 20) %]
-Configuration options are passed directly to the Text::Autoformat plugin.
+Configuration options are passed directly to the C<Text::Autoformat> plugin.
At the time of writing, the basic configuration items are:
- left left margin (default: 1)
- right right margin (default 72)
- justify justification as one of 'left', 'right', 'full'
+ left left margin (default: 1)
+ right right margin (default 72)
+ justify justification as one of 'left', 'right', 'full'
or 'centre' (default: left)
case case conversion as one of 'lower', 'upper',
'sentence', 'title', or 'highlight' (default: none)
- squeeze squeeze whitespace (default: enabled)
+ squeeze squeeze whitespace (default: enabled)
-The plugin also accepts a 'form' item which can be used to define a
+The plugin also accepts a C<form> item which can be used to define a
format string. When a form is defined, the plugin will call the
-underlying form() subroutine in preference to autoformat().
+underlying C<form()> subroutine in preference to C<autoformat()>.
[% USE autoformat(form => '>>>>.<<') %]
[% autoformat(123.45, 666, 3.14) %]
@@ -204,35 +189,28 @@
[% USE autoformat %]
[% autoformat( 123.45, 666, 3.14,
- form => '>>>>.<<',
- numeric => 'AllPlaces' )
+ form => '>>>>.<<',
+ numeric => 'AllPlaces' )
%]
See L<Text::Autoformat> for further details.
=head1 AUTHORS
-Robert McArthur E<lt>mcarthur@dstc.edu.auE<gt> wrote the original plugin
-code, with some modifications and additions from Andy Wardley
-E<lt>abw@wardley.orgE<gt>.
+Robert McArthur wrote the original plugin code, with some modifications and
+additions from Andy Wardley.
-Damian Conway E<lt>damian@conway.orgE<gt> wrote the Text::Autoformat
-module (in his copious spare time :-) which does all the clever stuff.
+Damian Conway wrote the L<Text::Autoformat> module which does all the clever
+stuff.
-=head1 VERSION
-
-Template Toolkit version 2.19, released on 27 April 2007.
-
-
-
=head1 COPYRIGHT
-Copyright (C) 2000 Robert McArthur & Andy Wardley. All Rights Reserved.
+Copyright (C) 2000-2007 Robert McArthur & 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::Plugin|Template::Plugin>, L<Text::Autoformat|Text::Autoformat>
+L<Template::Plugin>, L<Text::Autoformat>
Modified: trunk/lib/Template/Plugin/CGI.pm
===================================================================
--- trunk/lib/Template/Plugin/CGI.pm 2007-05-26 15:42:40 UTC (rev 1081)
+++ trunk/lib/Template/Plugin/CGI.pm 2007-05-26 15:43:31 UTC (rev 1082)
@@ -3,22 +3,17 @@
# Template::Plugin::CGI
#
# DESCRIPTION
-#
# Simple Template Toolkit plugin interfacing to the CGI.pm module.
#
# AUTHOR
# 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::Plugin::CGI;
@@ -60,18 +55,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::Plugin::CGI - Interface to the CGI module
@@ -80,7 +63,7 @@
[% USE CGI %]
[% CGI.param('parameter') %]
-
+
[% USE things = CGI %]
[% things.param('name') %]
@@ -88,12 +71,12 @@
=head1 DESCRIPTION
-This is a very simple Template Toolkit Plugin interface to the CGI module.
-A CGI object will be instantiated via the following directive:
+This is a very simple Template Toolkit Plugin interface to the C<CGI> module.
+A C<CGI> object will be instantiated via the following directive:
[% USE CGI %]
-CGI methods may then be called as follows:
+C<CGI> methods may then be called as follows:
[% CGI.header %]
[% CGI.param('parameter') %]
@@ -104,26 +87,25 @@
[% USE mycgi = CGI %]
[% mycgi.start_form %]
[% mycgi.popup_menu({ Name => 'Color'
- Values => [ 'Green' 'Black' 'Brown' ] }) %]
+ Values => [ 'Green' 'Black' 'Brown' ] }) %]
-Parenthesised parameters to the USE directive will be passed to the plugin
+Parenthesised parameters to the C<USE> directive will be passed to the plugin
constructor:
-
+
[% USE cgiprm = CGI('uid=abw&name=Andy+Wardley') %]
[% cgiprm.param('uid') %]
=head1 METHODS
-In addition to all the methods supported by the CGI module, this
+In addition to all the methods supported by the C<CGI> module, this
plugin defines the following.
=head2 params()
-This method returns a reference to a hash of all the CGI parameters.
+This method returns a reference to a hash of all the C<CGI> parameters.
Any parameters that have multiple values will be returned as lists.
[% USE CGI('user=abw&item=foo&item=bar') %]
-
[% CGI.params.user %] # abw
[% CGI.params.item.join(', ') %] # foo, bar
@@ -131,27 +113,18 @@
Andy Wardley E<lt>abw@wardley.orgE<gt>
-L<http://wardley.org/|http://wardley.org/>
+L<http://wardley.org/>
-
-
-
-=head1 VERSION
-
-2.7, 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::Plugin|Template::Plugin>, L<CGI|CGI>
+L<Template::Plugin>, L<CGI>
=cut
Modified: trunk/lib/Template/Plugin/Datafile.pm
===================================================================
--- trunk/lib/Template/Plugin/Datafile.pm 2007-05-26 15:42:40 UTC (rev 1081)
+++ trunk/lib/Template/Plugin/Datafile.pm 2007-05-26 15:43:31 UTC (rev 1082)
@@ -3,7 +3,6 @@
# Template::Plugin::Datafile
#
# DESCRIPTION
-#
# Template Toolkit Plugin which reads a datafile and constructs a
# list object containing hashes representing records in the file.
#
@@ -11,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::Plugin::Datafile;
@@ -42,42 +37,42 @@
$delim = quotemeta($delim);
return $class->fail("No filename specified")
- unless $filename;
+ unless $filename;
open(FD, $filename)
- || return $class->fail("$filename: $!");
+ || return $class->fail("$filename: $!");
# first line of file should contain field definitions
while (! $line || $line =~ /^#/) {
- $line = <FD>;
- chomp $line;
+ $line = <FD>;
+ chomp $line;
$line =~ s/\r$//;
}
(@fields = split(/\s*$delim\s*/, $line))
- || return $class->fail("first line of file must contain field names");
+ || return $class->fail("first line of file must contain field names");
# read each line of the file
while (<FD>) {
- chomp;
- s/\r$//;
+ chomp;
+ s/\r$//;
- # ignore comments and blank lines
- next if /^#/ || /^\s*$/;
+ # ignore comments and blank lines
+ next if /^#/ || /^\s*$/;
- # split line into fields
- @data = split(/\s*$delim\s*/);
+ # split line into fields
+ @data = split(/\s*$delim\s*/);
- # create hash record to represent data
- my %record;
- @record{ @fields } = @data;
+ # create hash record to represent data
+ my %record;
+ @record{ @fields } = @data;
- push(@$self, \%record);
+ push(@$self, \%record);
}
# return $self;
bless $self, $class;
-}
+}
sub as_list {
@@ -89,18 +84,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::Plugin::Datafile - Plugin to construct records from a simple data file
@@ -109,7 +92,7 @@
[% USE mydata = datafile('/path/to/datafile') %]
[% USE mydata = datafile('/path/to/datafile', delim = '|') %]
-
+
[% FOREACH record = mydata %]
[% record.this %] [% record.that %]
[% END %]
@@ -123,8 +106,8 @@
[% USE datafile(filename) %]
A absolute filename must be specified (for this initial implementation at
-least - in a future version it might also use the INCLUDE_PATH). An
-optional 'delim' parameter may also be provided to specify an alternate
+least - in a future version it might also use the C<INCLUDE_PATH>). An
+optional C<delim> parameter may also be provided to specify an alternate
delimiter character.
[% USE userlist = datafile('/path/to/file/users') %]
@@ -136,8 +119,8 @@
items, also delimited by colons. e.g.
id : name : email : tel
- abw : Andy Wardley : abw@cre.canon.co.uk : 555-1234
- neilb : Neil Bowers : neilb@cre.canon.co.uk : 555-9876
+ abw : Andy Wardley : abw@tt2.org : 555-1234
+ sam : Simon Matthews : sam@tt2.org : 555-9876
Each line is read, split into composite fields, and then used to
initialise a hash array containing the field names as relevant keys.
@@ -150,38 +133,29 @@
The first line of the file B<must> contain the field definitions.
After the first line, blank lines will be ignored, along with comment
-line which start with a '#'.
+line which start with a 'C<#>'.
=head1 BUGS
-Should handle file names relative to INCLUDE_PATH.
-Doesn't permit use of ':' in a field. Some escaping mechanism is required.
+Should handle file names relative to C<INCLUDE_PATH>.
+Doesn't permit use of 'C<:>' in a field. Some escaping mechanism is required.
=head1 AUTHOR
Andy Wardley E<lt>abw@wardley.orgE<gt>
-L<http://wardley.org/|http://wardley.org/>
+L<http://wardley.org/>
-
-
-
-=head1 VERSION
-
-2.72, 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::Plugin|Template::Plugin>
+L<Template::Plugin>
=cut
Modified: trunk/lib/Template/Plugin/Date.pm
===================================================================
--- trunk/lib/Template/Plugin/Date.pm 2007-05-26 15:42:40 UTC (rev 1081)
+++ trunk/lib/Template/Plugin/Date.pm 2007-05-26 15:43:31 UTC (rev 1082)
@@ -11,14 +11,11 @@
# Andy Wardley <abw@wardley.org>
#
# COPYRIGHT
-# Copyright (C) 2000-2006 Thierry-Michel Barral, Andy Wardley.
+# Copyright (C) 2000-2007 Thierry-Michel Barral, Andy Wardley.
#
# This module is free software; you can redistribute it and/or
# modify it under the same terms as Perl itself.
#
-# REVISION
-# $Id$
-#
#============================================================================
package Template::Plugin::Date;
@@ -41,7 +38,7 @@
sub new {
my ($class, $context, $params) = @_;
bless {
- $params ? %$params : ()
+ $params ? %$params : ()
}, $class;
}
@@ -78,11 +75,11 @@
my $self = shift;
my $params = ref($_[$#_]) eq 'HASH' ? pop(@_) : { };
my $time = shift(@_) || $params->{ time } || $self->{ time }
- || $self->now();
+ || $self->now();
my $format = @_ ? shift(@_)
- : ($params->{ format } || $self->{ format } || $FORMAT);
+ : ($params->{ format } || $self->{ format } || $FORMAT);
my $locale = @_ ? shift(@_)
- : ($params->{ locale } || $self->{ locale });
+ : ($params->{ locale } || $self->{ locale });
my $gmt = @_ ? shift(@_)
: ($params->{ gmt } || $self->{ gmt });
my (@date, $datestr);
@@ -109,14 +106,14 @@
}
if ($locale) {
- # format the date in a specific locale, saving and subsequently
+ # format the date in a specific locale, saving and subsequently
# restoring the current locale.
my $old_locale = &POSIX::setlocale(&POSIX::LC_ALL);
# some systems expect locales to have a particular suffix
for my $suffix ('', @LOCALE_SUFFIX) {
my $try_locale = $locale.$suffix;
- my $setlocale = &POSIX::setlocale(&POSIX::LC_ALL, $try_locale);
+ my $setlocale = &POSIX::setlocale(&POSIX::LC_ALL, $try_locale);
if (defined $setlocale && $try_locale eq $setlocale) {
$locale = $try_locale;
last;
@@ -167,7 +164,7 @@
my $sub = \&{"Date::Calc::$method"};
$self->throw("no such Date::Calc method: $method")
- unless $sub;
+ unless $sub;
&$sub(@_);
}
@@ -196,18 +193,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::Plugin::Date - Plugin to generate formatted date strings
@@ -215,70 +200,70 @@
=head1 SYNOPSIS
[% USE date %]
-
+
# use current time and default format
[% date.format %]
-
+
# specify time as seconds since epoch or 'h:m:s d-m-y' string
[% date.format(960973980) %]
[% date.format('4:20:36 21/12/2000') %]
-
+
# specify format
[% date.format(mytime, '%H:%M:%S') %]
-
+
# specify locale
[% date.format(date.now, '%a %d %b %y', 'en_GB') %]
-
+
# named parameters
[% date.format(mytime, format = '%H:%M:%S') %]
[% date.format(locale = 'en_GB') %]
[% date.format(time = date.now,
- format = '%H:%M:%S',
+ format = '%H:%M:%S',
locale = 'en_GB) %]
-
+
# specify default format to plugin
[% USE date(format = '%H:%M:%S', locale = 'de_DE') %]
-
+
[% date.format %]
...
=head1 DESCRIPTION
-The Date plugin provides an easy way to generate formatted time and date
-strings by delegating to the POSIX strftime() routine.
+The C<Date> plugin provides an easy way to generate formatted time and date
+strings by delegating to the C<POSIX> C<strftime()> routine.
The plugin can be loaded via the familiar USE directive.
[% USE date %]
-This creates a plugin object with the default name of 'date'. An alternate
+This creates a plugin object with the default name of 'C<date>'. An alternate
name can be specified as such:
[% USE myname = date %]
-The plugin provides the format() method which accepts a time value, a
+The plugin provides the C<format()> method which accepts a time value, a
format string and a locale name. All of these parameters are optional
-with the current system time, default format ('%H:%M:%S %d-%b-%Y') and
+with the current system time, default format ('C<%H:%M:%S %d-%b-%Y>') and
current locale being used respectively, if undefined. Default values
for the time, format and/or locale may be specified as named parameters
-in the USE directive.
+in the C<USE> directive.
[% USE date(format = '%a %d-%b-%Y', locale = 'fr_FR') %]
-When called without any parameters, the format() method returns a string
-representing the current system time, formatted by strftime() according
+When called without any parameters, the C<format()> method returns a string
+representing the current system time, formatted by C<strftime()> according
to the default format and for the default locale (which may not be the
-current one, if locale is set in the USE directive).
+current one, if locale is set in the C<USE> directive).
[% date.format %]
The plugin allows a time/date to be specified as seconds since the epoch,
-as is returned by time().
+as is returned by C<time()>.
File last modified: [% date.format(filemod_time) %]
-The time/date can also be specified as a string of the form 'h:m:s d/m/y'.
-Any of the characters : / - or space may be used to delimit fields.
+The time/date can also be specified as a string of the form 'C<h:m:s d/m/y>'.
+Any of the characters C<: / -> or space may be used to delimit fields.
[% USE day = date(format => '%A', locale => 'en_GB') %]
[% day.format('4:20:00 9-13-2000') %]
@@ -287,7 +272,7 @@
Tuesday
-A format string can also be passed to the format() method, and a locale
+A format string can also be passed to the C<format()> method, and a locale
specification may follow that.
[% date.format(filemod, '%d-%b-%Y') %]
@@ -299,11 +284,11 @@
[% date.format(filemod, '%d-%b-%Y', 'en_GB', 1) %]
Note that in this case, if the local time is not GMT, then also specifying
-'%Z' (time zone) in the format parameter will lead to an extremely
+'C<%Z>' (time zone) in the format parameter will lead to an extremely
misleading result.
Any or all of these parameters may be named. Positional parameters
-should always be in the order ($time, $format, $locale).
+should always be in the order C<($time, $format, $locale)>.
[% date.format(format => '%H:%M:%S') %]
[% date.format(time => filemod, format => '%H:%M:%S') %]
@@ -312,18 +297,18 @@
[% date.format(mytime, format => '%H:%M:%S', gmt => 1) %]
...etc...
-The now() method returns the current system time in seconds since the
+The C<now()> method returns the current system time in seconds since the
epoch.
[% date.format(date.now, '%A') %]
-The calc() method can be used to create an interface to the Date::Calc
+The C<calc()> method can be used to create an interface to the C<Date::Calc>
module (if installed on your system).
[% calc = date.calc %]
[% calc.Monday_of_Week(22, 2001).join('/') %]
-The manip() method can be used to create an interface to the Date::Manip
+The C<manip()> method can be used to create an interface to the C<Date::Manip>
module (if installed on your system).
[% manip = date.manip %]
@@ -331,30 +316,21 @@
=head1 AUTHORS
-Thierry-Michel Barral E<lt>kktos@electron-libre.comE<gt> wrote the original
-plugin.
+Thierry-Michel Barral wrote the original plugin.
-Andy Wardley E<lt>abw@cre.canon.co.ukE<gt> provided some minor
+Andy Wardley provided some minor
fixups/enhancements, a test script and documentation.
-Mark D. Mills E<lt>mark@hostile.orgE<gt> cloned Date::Manip from the
-cute Date::Calc sub-plugin.
+Mark D. Mills cloned C<Date::Manip> from the C<Date::Calc> sub-plugin.
-=head1 VERSION
-
-2.77, distributed as part of the
-Template Toolkit version 2.19, released on 27 April 2007.
-
-
-
=head1 COPYRIGHT
-Copyright (C) 2000 Thierry-Michel Barral, Andy Wardley.
+Copyright (C) 2000-2007 Thierry-Michel Barral, Andy Wardley.
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::Plugin|Template::Plugin>, L<POSIX|POSIX>
+L<Template::Plugin>, L<POSIX>
Modified: trunk/lib/Template/Plugin/Directory.pm
===================================================================
--- trunk/lib/Template/Plugin/Directory.pm 2007-05-26 15:42:40 UTC (rev 1081)
+++ trunk/lib/Template/Plugin/Directory.pm 2007-05-26 15:43:31 UTC (rev 1082)
@@ -10,12 +10,11 @@
# Andy Wardley <abw@wardley.org>.
#
# COPYRIGHT
+# Copyright (C) 2000-2007 Michael Stevens, Andy Wardley.
+#
# This module is free software; you can redistribute it and/or
# modify it under the same terms as Perl itself.
#
-# REVISION
-# $Id$
-#
#============================================================================
package Template::Plugin::Directory;
@@ -41,7 +40,7 @@
my ($class, $context, $path) = @_;
return $class->throw('no directory specified')
- unless defined $path and length $path;
+ unless defined $path and length $path;
my $self = $class->SUPER::new($context, $path, $config);
my ($dir, @files, $name, $item, $abs, $rel, $check);
@@ -54,7 +53,7 @@
return $self if $config->{ nostat } || $config->{ noscan };
$self->throw("$path: not a directory")
- unless $self->{ isdir };
+ unless $self->{ isdir };
$self->scan($config);
@@ -83,26 +82,26 @@
@files = readdir DH;
closedir(DH)
- or return $self->throw("$dir close: $!");
+ or return $self->throw("$dir close: $!");
my ($path, $files, $dirs, $list) = @$self{ qw( path files dirs list ) };
@$files = @$dirs = @$list = ();
foreach $name (sort @files) {
- next if $name =~ /^\./;
- $abs = File::Spec->catfile($dir, $name);
- $rel = File::Spec->catfile($path, $name);
+ next if $name =~ /^\./;
+ $abs = File::Spec->catfile($dir, $name);
+ $rel = File::Spec->catfile($path, $name);
- if (-d $abs) {
- $item = Template::Plugin::Directory->new(undef, $rel, $config);
- push(@$dirs, $item);
- }
- else {
- $item = Template::Plugin::File->new(undef, $rel, $config);
- push(@$files, $item);
- }
- push(@$list, $item);
- $self->{ _dir }->{ $name } = $item;
+ if (-d $abs) {
+ $item = Template::Plugin::Directory->new(undef, $rel, $config);
+ push(@$dirs, $item);
+ }
+ else {
+ $item = Template::Plugin::File->new(undef, $rel, $config);
+ push(@$files, $item);
+ }
+ push(@$list, $item);
+ $self->{ _dir }->{ $name } = $item;
}
return '';
@@ -144,7 +143,7 @@
return $self->{ list } unless $view;
my $output = '';
foreach my $file (@{ $self->{ list } }) {
- $output .= $file->present($view);
+ $output .= $file->present($view);
}
return $output;
}
@@ -163,18 +162,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::Plugin::Directory - Plugin for generating directory listings
@@ -182,48 +169,48 @@
=head1 SYNOPSIS
[% USE dir = Directory(dirpath) %]
-
+
# files returns list of regular files
[% FOREACH file = dir.files %]
[% file.name %] [% file.path %] ...
[% END %]
-
+
# dirs returns list of sub-directories
[% FOREACH subdir = dir.dirs %]
[% subdir.name %] [% subdir.path %] ...
[% END %]
-
+
# list returns both interleaved in order
[% FOREACH item = dir.list %]
[% IF item.isdir %]
- Directory: [% item.name %]
+ Directory: [% item.name %]
[% ELSE
File: [% item.name %]
[% END %]
[% END %]
-
+
# define a VIEW to display dirs/files
[% VIEW myview %]
[% BLOCK file %]
File: [% item.name %]
[% END %]
-
+
[% BLOCK directory %]
Directory: [% item.name %]
[% item.content(myview) | indent -%]
[% END %]
[% END %]
-
+
# display directory content using view
[% myview.print(dir) %]
=head1 DESCRIPTION
This Template Toolkit plugin provides a simple interface to directory
-listings. It is derived from the Template::Plugin::File module and
-uses Template::Plugin::File object instances to represent files within
+listings. It is derived from the L<Template::Plugin::File> module and
+uses L<Template::Plugin::File> object instances to represent files within
a directory. Sub-directories within a directory are represented by
-further Template::Plugin::Directory instances.
+further C<Template::Plugin::Directory> instances.
The constructor expects a directory name as an argument.
@@ -233,37 +220,35 @@
the directory.
# regular files (not directories)
- [% FOREACH file = dir.files %]
+ [% FOREACH file IN dir.files %]
[% file.name %]
[% END %]
# directories only
- [% FOREACH file = dir.dirs %]
+ [% FOREACH file IN dir.dirs %]
[% file.name %]
[% END %]
# files and/or directories
- [% FOREACH file = dir.list %]
+ [% FOREACH file IN dir.list %]
[% file.name %] ([% file.isdir ? 'directory' : 'file' %])
[% END %]
- [% USE Directory('foo/baz') %]
-
-The plugin constructor will throw a 'Directory' error if the specified
-path does not exist, is not a directory or fails to stat() (see
+The plugin constructor will throw a C<Directory> error if the specified
+path does not exist, is not a directory or fails to C<stat()> (see
L<Template::Plugin::File>). Otherwise, it will scan the directory and
-create lists named 'files' containing files, 'dirs' containing
-directories and 'list' containing both files and directories combined.
-The 'nostat' option can be set to disable all file/directory checks
+create lists named 'C<files>' containing files, 'C<dirs>' containing
+directories and 'C<list>' containing both files and directories combined.
+The C<nostat> option can be set to disable all file/directory checks
and directory scanning.
Each file in the directory will be represented by a
-Template::Plugin::File object instance, and each directory by another
-Template::Plugin::Directory. If the 'recurse' flag is set, then those
+L<Template::Plugin::File> object instance, and each directory by another
+C<Template::Plugin::Directory>. If the C<recurse> flag is set, then those
directories will contain further nested entries, and so on. With the
-'recurse' flag unset, as it is by default, then each is just a place
+C<recurse> flag unset, as it is by default, then each is just a place
marker for the directory and does not contain any further content
-unless its scan() method is explicitly called. The 'isdir' flag can
+unless its C<scan()> method is explicitly called. The C<isdir> flag can
be tested against files and/or directories, returning true if the item
is a directory or false if it is a regular file.
@@ -277,19 +262,19 @@
This example shows how you might walk down a directory tree, displaying
content as you go. With the recurse flag disabled, as is the default,
-we need to explicitly call the scan() method on each directory, to force
+we need to explicitly call the C<scan()> method on each directory, to force
it to lookup files and further sub-directories contained within.
[% USE dir = Directory(dirpath) %]
* [% dir.path %]
[% INCLUDE showdir %]
-
+
[% BLOCK showdir -%]
[% FOREACH file = dir.list -%]
[% IF file.isdir -%]
* [% file.name %]
[% file.scan -%]
- [% INCLUDE showdir dir=file FILTER indent(4) -%]
+ [% INCLUDE showdir dir=file FILTER indent(4) -%]
[% ELSE -%]
- [% f.name %]
[% END -%]
@@ -300,34 +285,34 @@
a test in F<t/directry.t> which produces the following output:
* test/dir
- - file1
- - file2
- * sub_one
- - bar
- - foo
- * sub_two
- - waz.html
- - wiz.html
- - xyzfile
+ - file1
+ - file2
+ * sub_one
+ - bar
+ - foo
+ * sub_two
+ - waz.html
+ - wiz.html
+ - xyzfile
-The 'recurse' flag can be set (disabled by default) to cause the
+The C<recurse> flag can be set (disabled by default) to cause the
constructor to automatically recurse down into all sub-directories,
-creating a new Template::Plugin::Directory object for each one and
+creating a new C<Template::Plugin::Directory> object for each one and
filling it with any further content. In this case there is no need
-to explicitly call the scan() method.
+to explicitly call the C<scan()> method.
[% USE dir = Directory(dirpath, recurse=1) %]
...
-
+
[% IF file.isdir -%]
* [% file.name %]
- [% INCLUDE showdir dir=file FILTER indent(4) -%]
+ [% INCLUDE showdir dir=file FILTER indent(4) -%]
[% ELSE -%]
...
-From version 2.01, the Template Toolkit provides support for views.
-A view can be defined as a VIEW ... END block and should contain
-BLOCK definitions for files ('file') and directories ('directory').
+The directory plugin also provides support for views. A view can be defined as
+a C<VIEW ... END> block and should contain C<BLOCK> definitions for files
+('C<file>') and directories ('C<directory>').
[% VIEW myview %]
[% BLOCK file %]
@@ -340,28 +325,29 @@
[% END %]
[% END %]
-Then the view print() method can be called, passing the
-Directory object as an argument.
+The view C<print()> method can then be called, passing the
+C<Directory> object as an argument.
[% USE dir = Directory(dirpath, recurse=1) %]
[% myview.print(dir) %]
-When a directory is presented to a view, either as [% myview.print(dir) %]
-or [% dir.present(view) %], then the 'directory' BLOCK within the 'myview'
-VIEW is processed, with the 'item' variable set to alias the Directory object.
+When a directory is presented to a view, either as C<[% myview.print(dir) %]>
+or C<[% dir.present(view) %]>, then the C<directory> C<BLOCK> within the
+C<myview> C<VIEW> is processed. The C<item> variable will be set to alias the
+C<Directory> object.
[% BLOCK directory %]
* [% item.name %]
[% item.content(myview) FILTER indent %]
[% END %]
-The directory name is first printed and the content(view) method is
-then called to present each item within the directory to the view.
-Further directories will be mapped to the 'directory' block, and files
-will be mapped to the 'file' block.
+In this example, the directory name is first printed and the content(view)
+method is then called to present each item within the directory to the view.
+Further directories will be mapped to the C<directory> block, and files will be
+mapped to the C<file> block.
-With the recurse option disabled, as it is by default, the 'directory'
-block should explicitly call a scan() on each directory.
+With the recurse option disabled, as it is by default, the C<directory>
+block should explicitly call a C<scan()> on each directory.
[% VIEW myview %]
[% BLOCK file %]
@@ -370,39 +356,29 @@
[% BLOCK directory %]
* [% item.name %]
- [% item.scan %]
+ [% item.scan %]
[% item.content(myview) FILTER indent %]
[% END %]
[% END %]
-
+
[% USE dir = Directory(dirpath) %]
[% myview.print(dir) %]
-=head1 TODO
-
-Might be nice to be able to specify accept/ignore options to catch
-a subset of files.
-
=head1 AUTHORS
-Michael Stevens E<lt>michael@etla.orgE<gt> wrote the original Directory plugin
-on which this is based. Andy Wardley E<lt>abw@wardley.orgE<gt> split it into
-separate File and Directory plugins, added some extra code and documentation
-for VIEW support, and made a few other minor tweaks.
+Michael Stevens wrote the original Directory plugin on which this is based.
+Andy Wardley split it into separate L<Template::Plugin::File|File> and
+L<Template::Plugin::Directory|Directory> plugins, added some extra code and
+documentation for C<VIEW> support, and made a few other minor tweaks.
-=head1 VERSION
-
-2.7, distributed as part of the
-Template Toolkit version 2.19, released on 27 April 2007.
-
-
-
=head1 COPYRIGHT
+Copyright (C) 2000-2007 Michael Stevens, Andy Wardley.
+
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::Plugin|Template::Plugin>, L<Template::Plugin::File|Template::Plugin::File>, L<Template::View|Template::View>
+L<Template::Plugin>, L<Template::Plugin::File>, L<Template::View>
Modified: trunk/lib/Template/Plugin/Dumper.pm
===================================================================
--- trunk/lib/Template/Plugin/Dumper.pm 2007-05-26 15:42:40 UTC (rev 1081)
+++ trunk/lib/Template/Plugin/Dumper.pm 2007-05-26 15:43:31 UTC (rev 1082)
@@ -7,7 +7,7 @@
# A Template Plugin to provide a Template Interface to Data::Dumper
#
# AUTHOR
-# Simon Matthews <sam@knowledgepool.com>
+# Simon Matthews <sam@tt2.org>
#
# COPYRIGHT
# Copyright (C) 2000 Simon Matthews. All Rights Reserved
@@ -15,9 +15,6 @@
# This module is free software; you can redistribute it and/or
# modify it under the same terms as Perl itself.
#
-# REVISION
-# $Id$
-#
#==============================================================================
package Template::Plugin::Dumper;
@@ -48,15 +45,15 @@
foreach my $arg (@DUMPER_ARGS) {
- no strict 'refs';
- if (defined ($val = $params->{ lc $arg })
- or defined ($val = $params->{ $arg })) {
- ${"Data\::Dumper\::$arg"} = $val;
- }
+ no strict 'refs';
+ if (defined ($val = $params->{ lc $arg })
+ or defined ($val = $params->{ $arg })) {
+ ${"Data\::Dumper\::$arg"} = $val;
+ }
}
bless {
- _CONTEXT => $context,
+ _CONTEXT => $context,
}, $class;
}
@@ -71,10 +68,10 @@
my $self = shift;
my $content = Dumper @_;
for ($content) {
- s/&/&/g;
- s/</</g;
- s/>/>/g;
- s/\n/<br>\n/g;
+ s/&/&/g;
+ s/</</g;
+ s/>/>/g;
+ s/\n/<br>\n/g;
}
return $content;
}
@@ -83,18 +80,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::Plugin::Dumper - Plugin interface to Data::Dumper
@@ -102,14 +87,14 @@
=head1 SYNOPSIS
[% USE Dumper %]
-
+
[% Dumper.dump(variable) %]
[% Dumper.dump_html(variable) %]
=head1 DESCRIPTION
-This is a very simple Template Toolkit Plugin Interface to the Data::Dumper
-module. A Dumper object will be instantiated via the following directive:
+This is a very simple Template Toolkit Plugin Interface to the L<Data::Dumper>
+module. A C<Dumper> object will be instantiated via the following directive:
[% USE Dumper %]
@@ -117,7 +102,7 @@
[% USE dumper %]
-The Data::Dumper 'Pad', 'Indent' and 'Varname' options are supported
+The C<Data::Dumper> C<Pad>, C<Indent> and C<Varname> options are supported
as constructor arguments to affect the output generated. See L<Data::Dumper>
for further details.
@@ -129,7 +114,7 @@
=head1 METHODS
-There are two methods supported by the Dumper object. Each will
+There are two methods supported by the C<Dumper> object. Each will
output into the template the contents of the variables passed to the
object method.
@@ -143,7 +128,7 @@
=head2 dump_html()
-Generates a dump of the data structures, as per dump(), but with the
+Generates a dump of the data structures, as per L<dump()>, but with the
characters E<lt>, E<gt> and E<amp> converted to their equivalent HTML
entities and newlines converted to E<lt>brE<gt>.
@@ -152,23 +137,16 @@
=head1 AUTHOR
-Simon Matthews E<lt>sam@knowledgepool.comE<gt>
+Simon Matthews E<lt>sam@tt2.orgE<gt>
-=head1 VERSION
-
-2.7, distributed as part of the
-Template Toolkit version 2.19, released on 27 April 2007.
-
-
-
=head1 COPYRIGHT
-Copyright (C) 2000 Simon Matthews All Rights Reserved.
+Copyright (C) 2000 Simon Matthews. 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::Plugin|Template::Plugin>, L<Data::Dumper|Data::Dumper>
+L<Template::Plugin>, L<Data::Dumper>
Modified: trunk/lib/Template/Plugin/File.pm
===================================================================
--- trunk/lib/Template/Plugin/File.pm 2007-05-26 15:42:40 UTC (rev 1081)
+++ trunk/lib/Template/Plugin/File.pm 2007-05-26 15:43:31 UTC (rev 1082)
@@ -12,12 +12,11 @@
# code for working with views, etc.
#
# COPYRIGHT
+# Copyright 2000-2007 Michael Stevens, Andy Wardley.
+#
# This module is free software; you can redistribute it and/or
# modify it under the same terms as Perl itself.
#
-# REVISION
-# $Id$
-#
#============================================================================
package Template::Plugin::File;
@@ -49,7 +48,7 @@
my ($root, $home, @stat, $abs);
return $class->throw('no file specified')
- unless defined $path and length $path;
+ unless defined $path and length $path;
# path, dir, name, root, home
@@ -144,18 +143,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::Plugin::File - Plugin providing information about files
@@ -164,7 +151,7 @@
[% USE File(filepath) %]
[% File.path %] # full path
- [% File.name %] # filename
+ [% File.name %] # filename
[% File.dir %] # directory
=head1 DESCRIPTION
@@ -180,10 +167,10 @@
[% USE File('foo/bar/baz.html') %]
[% USE File('/foo/bar/baz.html') %]
-The file should exist on the current file system (unless 'nostat'
+The file should exist on the current file system (unless C<nostat>
option set, see below) as an absolute file when specified with as
-leading '/' as per '/foo/bar/baz.html', or otherwise as one relative
-to the current working directory. The constructor performs a stat()
+leading 'C</>' as per 'C</foo/bar/baz.html>', or otherwise as one relative
+to the current working directory. The constructor performs a C<stat()>
on the file and makes the 13 elements returned available as the plugin
items:
@@ -193,35 +180,35 @@
e.g.
[% USE File('/foo/bar/baz.html') %]
-
+
[% File.mtime %]
[% File.mode %]
...
-In addition, the 'user' and 'group' items are set to contain the user
-and group names as returned by calls to getpwuid() and getgrgid() for
-the file 'uid' and 'gid' elements, respectively. On Win32 platforms
-on which getpwuid() and getgrid() are not available, these values are
+In addition, the C<user> and C<group> items are set to contain the user
+and group names as returned by calls to C<getpwuid()> and C<getgrgid()> for
+the file C<uid> and C<gid> elements, respectively. On Win32 platforms
+on which C<getpwuid()> and C<getgrid()> are not available, these values are
undefined.
[% USE File('/tmp/foo.html') %]
- [% File.uid %] # e.g. 500
+ [% File.uid %] # e.g. 500
[% File.user %] # e.g. abw
-This user/group lookup can be disabled by setting the 'noid' option.
+This user/group lookup can be disabled by setting the C<noid> option.
[% USE File('/tmp/foo.html', noid=1) %]
- [% File.uid %] # e.g. 500
+ [% File.uid %] # e.g. 500
[% File.user %] # nothing
-The 'isdir' flag will be set if the file is a directory.
+The C<isdir> flag will be set if the file is a directory.
[% USE File('/tmp') %]
- [% File.isdir %] # 1
+ [% File.isdir %] # 1
-If the stat() on the file fails (e.g. file doesn't exists, bad
-permission, etc) then the constructor will throw a 'File' exception.
-This can be caught within a TRY...CATCH block.
+If the C<stat()> on the file fails (e.g. file doesn't exists, bad
+permission, etc) then the constructor will throw a C<File> exception.
+This can be caught within a C<TRY...CATCH> block.
[% TRY %]
[% USE File('/tmp/myfile') %]
@@ -230,12 +217,12 @@
File error: [% error.info %]
[% END %]
-Note the capitalisation of the exception type, 'File' to indicate an
-error thrown by the 'File' plugin, to distinguish it from a regular
-'file' exception thrown by the Template Toolkit.
+Note the capitalisation of the exception type, 'C<File>', to indicate an
+error thrown by the C<File> plugin, to distinguish it from a regular
+C<file> exception thrown by the Template Toolkit.
-Note that the 'File' plugin can also be referenced by the lower case
-name 'file'. However, exceptions are always thrown of the 'File'
+Note that the C<File> plugin can also be referenced by the lower case
+name 'C<file>'. However, exceptions are always thrown of the C<File>
type, regardless of the capitalisation of the plugin named used.
[% USE file('foo.html') %]
@@ -247,104 +234,96 @@
[% USE foo = file('foo.html') %]
[% foo.mtime %]
-The 'nostat' option can be specified to prevent the plugin constructor
-from performing a stat() on the file specified. In this case, the
+The C<nostat> option can be specified to prevent the plugin constructor
+from performing a C<stat()> on the file specified. In this case, the
file does not have to exist in the file system, no attempt will be made
to verify that it does, and no error will be thrown if it doesn't.
-The entries for the items usually returned by stat() will be set
+The entries for the items usually returned by C<stat()> will be set
empty.
[% USE file('/some/where/over/the/rainbow.html', nostat=1)
[% file.mtime %] # nothing
-All File plugins, regardless of the nostat option, have set a number
+=head1 METHODS
+
+All C<File> plugins, regardless of the C<nostat> option, have set a number
of items relating to the original path specified.
-=over 4
+=head2 path
-=item path
-
The full, original file path specified to the constructor.
[% USE file('/foo/bar.html') %]
- [% file.path %] # /foo/bar.html
+ [% file.path %] # /foo/bar.html
-=item name
+=head2 name
The name of the file without any leading directories.
[% USE file('/foo/bar.html') %]
- [% file.name %] # bar.html
+ [% file.name %] # bar.html
-=item dir
+=head2 dir
The directory element of the path with the filename removed.
[% USE file('/foo/bar.html') %]
- [% file.name %] # /foo
+ [% file.name %] # /foo
-=item ext
+=head2 ext
The file extension, if any, appearing at the end of the path following
-a '.' (not included in the extension).
+a 'C<.>' (not included in the extension).
[% USE file('/foo/bar.html') %]
- [% file.ext %] # html
+ [% file.ext %] # html
-=item home
+=head2 home
-This contains a string of the form '../..' to represent the upward path
+This contains a string of the form 'C<../..>' to represent the upward path
from a file to its root directory.
[% USE file('bar.html') %]
- [% file.home %] # nothing
-
+ [% file.home %] # nothing
+
[% USE file('foo/bar.html') %]
- [% file.home %] # ..
-
+ [% file.home %] # ..
+
[% USE file('foo/bar/baz.html') %]
- [% file.home %] # ../..
+ [% file.home %] # ../..
-=item root
+=head2 root
-The 'root' item can be specified as a constructor argument, indicating
+The C<root> item can be specified as a constructor argument, indicating
a root directory in which the named file resides. This is otherwise
set empty.
[% USE file('foo/bar.html', root='/tmp') %]
- [% file.root %] # /tmp
+ [% file.root %] # /tmp
-=item abs
+=head2 abs
This returns the absolute file path by constructing a path from the
-'root' and 'path' options.
+C<root> and C<path> options.
[% USE file('foo/bar.html', root='/tmp') %]
- [% file.path %] # foo/bar.html
- [% file.root %] # /tmp
- [% file.abs %] # /tmp/foo/bar.html
+ [% file.path %] # foo/bar.html
+ [% file.root %] # /tmp
+ [% file.abs %] # /tmp/foo/bar.html
-=back
+=head2 rel(path)
-In addition, the following method is provided:
-
-=over 4
-
-=item rel(path)
-
This returns a relative path from the current file to another path specified
-as an argument. It is constructed by appending the path to the 'home'
+as an argument. It is constructed by appending the path to the 'C<home>'
item.
[% USE file('foo/bar/baz.html') %]
- [% file.rel('wiz/waz.html') %] # ../../wiz/waz.html
+ [% file.rel('wiz/waz.html') %] # ../../wiz/waz.html
-=back
-
=head1 EXAMPLES
[% USE file('/foo/bar/baz.html') %]
-
+
[% file.path %] # /foo/bar/baz.html
[% file.dir %] # /foo/bar
[% file.name %] # baz.html
@@ -352,65 +331,59 @@
[% file.root %] # ''
[% file.abs %] # /foo/bar/baz.html
[% file.ext %] # html
- [% file.mtime %] # 987654321
+ [% file.mtime %] # 987654321
[% file.atime %] # 987654321
[% file.uid %] # 500
[% file.user %] # abw
[% USE file('foo.html') %]
-
- [% file.path %] # foo.html
+
+ [% file.path %] # foo.html
[% file.dir %] # ''
- [% file.name %] # foo.html
+ [% file.name %] # foo.html
[% file.root %] # ''
[% file.home %] # ''
[% file.abs %] # foo.html
[% USE file('foo/bar/baz.html') %]
-
- [% file.path %] # foo/bar/baz.html
+
+ [% file.path %] # foo/bar/baz.html
[% file.dir %] # foo/bar
- [% file.name %] # baz.html
+ [% file.name %] # baz.html
[% file.root %] # ''
[% file.home %] # ../..
[% file.abs %] # foo/bar/baz.html
[% USE file('foo/bar/baz.html', root='/tmp') %]
-
- [% file.path %] # foo/bar/baz.html
+
+ [% file.path %] # foo/bar/baz.html
[% file.dir %] # foo/bar
- [% file.name %] # baz.html
+ [% file.name %] # baz.html
[% file.root %] # /tmp
[% file.home %] # ../..
[% file.abs %] # /tmp/foo/bar/baz.html
# calculate other file paths relative to this file and its root
[% USE file('foo/bar/baz.html', root => '/tmp/tt2') %]
-
- [% file.path('baz/qux.html') %] # ../../baz/qux.html
+
+ [% file.path('baz/qux.html') %] # ../../baz/qux.html
[% file.dir('wiz/woz.html') %] # ../../wiz/woz.html
-
=head1 AUTHORS
-Michael Stevens E<lt>michael@etla.orgE<gt> wrote the original Directory plugin
-on which this is based. Andy Wardley E<lt>abw@wardley.orgE<gt> split it into
-separate File and Directory plugins, added some extra code and documentation
-for VIEW support, and made a few other minor tweaks.
+Michael Stevens wrote the original C<Directory> plugin on which this is based.
+Andy Wardley split it into separate C<File> and C<Directory> plugins, added
+some extra code and documentation for C<VIEW> support, and made a few other
+minor tweaks.
-=head1 VERSION
-
-2.71, distributed as part of the
-Template Toolkit version 2.19, released on 27 April 2007.
-
-
-
=head1 COPYRIGHT
+Copyright 2000-2007 Michael Stevens, Andy Wardley.
+
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::Plugin|Template::Plugin>, L<Template::Plugin::Directory|Template::Plugin::Directory>, L<Template::View|Template::View>
+L<Template::Plugin>, L<Template::Plugin::Directory>, L<Template::View>
Modified: trunk/lib/Template/Plugin/Filter.pm
===================================================================
--- trunk/lib/Template/Plugin/Filter.pm 2007-05-26 15:42:40 UTC (rev 1081)
+++ trunk/lib/Template/Plugin/Filter.pm 2007-05-26 15:43:31 UTC (rev 1082)
@@ -11,14 +11,11 @@
# Andy Wardley <abw@wardley.org>
#
# COPYRIGHT
-# Copyright (C) 2001,2006 Andy Wardley. All Rights Reserved.
+# Copyright (C) 2001-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::Plugin::Filter;
@@ -38,16 +35,16 @@
# look for $DYNAMIC
my $dynamic;
{
- no strict 'refs';
- $dynamic = ${"$class\::DYNAMIC"};
+ no strict 'refs';
+ $dynamic = ${"$class\::DYNAMIC"};
}
$dynamic = $DYNAMIC unless defined $dynamic;
my $self = bless {
- _CONTEXT => $context,
- _DYNAMIC => $dynamic,
- _ARGS => \@args,
- _CONFIG => $config,
+ _CONTEXT => $context,
+ _DYNAMIC => $dynamic,
+ _ARGS => \@args,
+ _CONFIG => $config,
}, $class;
return $self->init($config)
@@ -65,19 +62,19 @@
my $self = shift;
if ($self->{ _DYNAMIC }) {
- return $self->{ _DYNAMIC_FILTER } ||= [ sub {
- my ($context, @args) = @_;
- my $config = ref $args[-1] eq 'HASH' ? pop(@args) : { };
-
- return sub {
- $self->filter(shift, \@args, $config);
- };
- }, 1 ];
+ return $self->{ _DYNAMIC_FILTER } ||= [ sub {
+ my ($context, @args) = @_;
+ my $config = ref $args[-1] eq 'HASH' ? pop(@args) : { };
+
+ return sub {
+ $self->filter(shift, \@args, $config);
+ };
+ }, 1 ];
}
else {
- return $self->{ _STATIC_FILTER } ||= sub {
- $self->filter(shift);
- };
+ return $self->{ _STATIC_FILTER } ||= sub {
+ $self->filter(shift);
+ };
}
}
@@ -116,18 +113,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::Plugin::Filter - Base class for plugin filters
@@ -135,21 +120,21 @@
=head1 SYNOPSIS
package MyOrg::Template::Plugin::MyFilter;
-
+
use Template::Plugin::Filter;
use base qw( Template::Plugin::Filter );
-
+
sub filter {
- my ($self, $text) = @_;
-
- # ...mungify $text...
-
- return $text;
+ my ($self, $text) = @_;
+
+ # ...mungify $text...
+
+ return $text;
}
# now load it...
[% USE MyFilter %]
-
+
# ...and use the returned object as a filter
[% FILTER $MyFilter %]
...
@@ -162,49 +147,49 @@
that get defined and made available by loading a plugin.
To use the module, simply create your own plugin module that is
-inherited from the Template::Plugin::Filter class.
+inherited from the C<Template::Plugin::Filter> class.
package MyOrg::Template::Plugin::MyFilter;
-
+
use Template::Plugin::Filter;
use base qw( Template::Plugin::Filter );
-Then simply define your filter() method. When called, you get
-passed a reference to your plugin object ($self) and the text
+Then simply define your C<filter()> method. When called, you get
+passed a reference to your plugin object (C<$self>) and the text
to be filtered.
sub filter {
- my ($self, $text) = @_;
-
- # ...mungify $text...
-
- return $text;
+ my ($self, $text) = @_;
+
+ # ...mungify $text...
+
+ return $text;
}
To use your custom plugin, you have to make sure that the Template
Toolkit knows about your plugin namespace.
my $tt2 = Template->new({
- PLUGIN_BASE => 'MyOrg::Template::Plugin',
+ PLUGIN_BASE => 'MyOrg::Template::Plugin',
});
Or for individual plugins you can do it like this:
my $tt2 = Template->new({
- PLUGINS => {
- MyFilter => 'MyOrg::Template::Plugin::MyFilter',
- },
+ PLUGINS => {
+ MyFilter => 'MyOrg::Template::Plugin::MyFilter',
+ },
});
-Then you USE your plugin in the normal way.
+Then you C<USE> your plugin in the normal way.
[% USE MyFilter %]
The object returned is stored in the variable of the same name,
-'MyFilter'. When you come to use it as a FILTER, you should add
+'C<MyFilter>'. When you come to use it as a C<FILTER>, you should add
a dollar prefix. This indicates that you want to use the filter
-stored in the variable 'MyFilter' rather than the filter named
-'MyFilter', which is an entirely different thing (see later for
+stored in the variable 'C<MyFilter>' rather than the filter named
+'C<MyFilter>', which is an entirely different thing (see later for
information on defining filters by name).
[% FILTER $MyFilter %]
@@ -214,68 +199,64 @@
You can, of course, assign it to a different variable.
[% USE blat = MyFilter %]
-
+
[% FILTER $blat %]
...text to be filtered...
[% END %]
Any configuration parameters passed to the plugin constructor from the
-USE directive are stored internally in the object for inspection by
-the filter() method (or indeed any other method). Positional
-arguments are stored as a reference to a list in the _ARGS item while
+C<USE> directive are stored internally in the object for inspection by
+the C<filter()> method (or indeed any other method). Positional
+arguments are stored as a reference to a list in the C<_ARGS> item while
named configuration parameters are stored as a reference to a hash
-array in the _CONFIG item.
+array in the C<_CONFIG> item.
For example, loading a plugin as shown here:
[% USE blat = MyFilter 'foo' 'bar' baz = 'blam' %]
-would allow the filter() method to do something like this:
+would allow the C<filter()> method to do something like this:
sub filter {
- my ($self, $text) = @_;
-
- my $args = $self->{ _ARGS }; # [ 'foo', 'bar' ]
- my $conf = $self->{ _CONFIG }; # { baz => 'blam' }
-
- # ...munge $text...
-
- return $text;
+ my ($self, $text) = @_;
+
+ my $args = $self->{ _ARGS }; # [ 'foo', 'bar' ]
+ my $conf = $self->{ _CONFIG }; # { baz => 'blam' }
+
+ # ...munge $text...
+
+ return $text;
}
By default, plugins derived from this module will create static
filters. A static filter is created once when the plugin gets
-loaded via the USE directive and re-used for all subsequent
-FILTER operations. That means that any argument specified with
-the FILTER directive are ignored.
+loaded via the C<USE> directive and re-used for all subsequent
+C<FILTER> operations. That means that any argument specified with
+the C<FILTER> directive are ignored.
Dynamic filters, on the other hand, are re-created each time
-they are used by a FILTER directive. This allows them to act
-on any parameters passed from the FILTER directive and modify
+they are used by a C<FILTER> directive. This allows them to act
+on any parameters passed from the C<FILTER> directive and modify
their behaviour accordingly.
There are two ways to create a dynamic filter. The first is to
-define a $DYNAMIC class variable set to a true value.
+define a C<$DYNAMIC> class variable set to a true value.
package MyOrg::Template::Plugin::MyFilter;
+ use base 'Template::Plugin::Filter';
+ our $DYNAMIC = 1;
- use Template::Plugin::Filter;
- use base qw( Template::Plugin::Filter );
- use vars qw( $DYNAMIC );
+The other way is to set the internal C<_DYNAMIC> value within the C<init()>
+method which gets called by the C<new()> constructor.
- $DYNAMIC = 1;
-
-The other way is to set the internal _DYNAMIC value within the init()
-method which gets called by the new() constructor.
-
sub init {
- my $self = shift;
- $self->{ _DYNAMIC } = 1;
- return $self;
+ my $self = shift;
+ $self->{ _DYNAMIC } = 1;
+ return $self;
}
When this is set to a true value, the plugin will automatically
-create a dynamic filter. The outcome is that the filter() method
+create a dynamic filter. The outcome is that the C<filter()> method
will now also get passed a reference to an array of postional
arguments and a reference to a hash array of named parameters.
@@ -283,65 +264,64 @@
[% FILTER $blat 'foo' 'bar' baz = 'blam' %]
-would allow the filter() method to work like this:
+would allow the C<filter()> method to work like this:
sub filter {
- my ($self, $text, $args, $conf) = @_;
-
- # $args = [ 'foo', 'bar' ]
- # $conf = { baz => 'blam' }
-
+ my ($self, $text, $args, $conf) = @_;
+
+ # $args = [ 'foo', 'bar' ]
+ # $conf = { baz => 'blam' }
}
In this case can pass parameters to both the USE and FILTER directives,
so your filter() method should probably take that into account.
[% USE MyFilter 'foo' wiz => 'waz' %]
-
+
[% FILTER $MyFilter 'bar' biz => 'baz' %]
...
[% END %]
-You can use the merge_args() and merge_config() methods to do a quick
-and easy job of merging the local (e.g. FILTER) parameters with the
-internal (e.g. USE) values and returning new sets of conglomerated
+You can use the C<merge_args()> and C<merge_config()> methods to do a quick
+and easy job of merging the local (e.g. C<FILTER>) parameters with the
+internal (e.g. C<USE>) values and returning new sets of conglomerated
data.
sub filter {
- my ($self, $text, $args, $conf) = @_;
-
- $args = $self->merge_args($args);
- $conf = $self->merge_config($conf);
-
- # $args = [ 'foo', 'bar' ]
- # $conf = { wiz => 'waz', biz => 'baz' }
- ...
+ my ($self, $text, $args, $conf) = @_;
+
+ $args = $self->merge_args($args);
+ $conf = $self->merge_config($conf);
+
+ # $args = [ 'foo', 'bar' ]
+ # $conf = { wiz => 'waz', biz => 'baz' }
+ ...
}
You can also have your plugin install itself as a named filter by
-calling the install_filter() method from the init() method. You
+calling the C<install_filter()> method from the C<init()> method. You
should provide a name for the filter, something that you might
like to make a configuration option.
sub init {
- my $self = shift;
- my $name = $self->{ _CONFIG }->{ name } || 'myfilter';
- $self->install_filter($name);
- return $self;
+ my $self = shift;
+ my $name = $self->{ _CONFIG }->{ name } || 'myfilter';
+ $self->install_filter($name);
+ return $self;
}
This allows the plugin filter to be used as follows:
[% USE MyFilter %]
-
+
[% FILTER myfilter %]
...
[% END %]
-or
+or
[% USE MyFilter name = 'swipe' %]
-
+
[% FILTER swipe %]
...
[% END %]
@@ -350,10 +330,10 @@
first positional argument.
sub init {
- my $self = shift;
- my $name = $self->{ _ARGS }->[0] || 'myfilter';
- $self->install_filter($name);
- return $self;
+ my $self = shift;
+ my $name = $self->{ _ARGS }->[0] || 'myfilter';
+ $self->install_filter($name);
+ return $self;
}
[% USE MyFilter 'swipe' %]
@@ -369,57 +349,47 @@
package My::Template::Plugin::Change;
use Template::Plugin::Filter;
use base qw( Template::Plugin::Filter );
-
+
sub init {
- my $self = shift;
-
- $self->{ _DYNAMIC } = 1;
-
- # first arg can specify filter name
- $self->install_filter($self->{ _ARGS }->[0] || 'change');
-
- return $self;
+ my $self = shift;
+
+ $self->{ _DYNAMIC } = 1;
+
+ # first arg can specify filter name
+ $self->install_filter($self->{ _ARGS }->[0] || 'change');
+
+ return $self;
}
-
-
+
sub filter {
- my ($self, $text, $args, $config) = @_;
-
- $config = $self->merge_config($config);
- my $regex = join('|', keys %$config);
-
- $text =~ s/($regex)/$config->{ $1 }/ge;
-
- return $text;
+ my ($self, $text, $args, $config) = @_;
+
+ $config = $self->merge_config($config);
+ my $regex = join('|', keys %$config);
+
+ $text =~ s/($regex)/$config->{ $1 }/ge;
+
+ return $text;
}
-
+
1;
=head1 AUTHOR
Andy Wardley E<lt>abw@wardley.orgE<gt>
-L<http://wardley.org/|http://wardley.org/>
+L<http://wardley.org/>
-
-
-
-=head1 VERSION
-
-1.36, 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::Plugin|Template::Plugin>, L<Template::Filters|Template::Filters>, L<Template::Manual::Filters|Template::Manual::Filters>
+L<Template::Plugin>, L<Template::Filters>, L<Template::Manual::Filters>
=cut
Modified: trunk/lib/Template/Plugin/Format.pm
===================================================================
--- trunk/lib/Template/Plugin/Format.pm 2007-05-26 15:42:40 UTC (rev 1081)
+++ trunk/lib/Template/Plugin/Format.pm 2007-05-26 15:43:31 UTC (rev 1082)
@@ -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::Plugin::Format;
@@ -33,8 +29,8 @@
sub new {
my ($class, $context, $format) = @_;;
return defined $format
- ? make_formatter($format)
- : \&make_formatter;
+ ? make_formatter($format)
+ : \&make_formatter;
}
@@ -42,9 +38,9 @@
my $format = shift;
$format = '%s' unless defined $format;
return sub {
- my @args = @_;
- push(@args, '') unless @args;
- return sprintf($format, @args);
+ my @args = @_;
+ push(@args, '') unless @args;
+ return sprintf($format, @args);
}
}
@@ -53,18 +49,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::Plugin::Format - Plugin to create formatting functions
@@ -81,33 +65,24 @@
=head1 DESCRIPTION
The format plugin constructs sub-routines which format text according to
-a printf()-like format string.
+a C<printf()>-like format string.
=head1 AUTHOR
Andy Wardley E<lt>abw@wardley.orgE<gt>
-L<http://wardley.org/|http://wardley.org/>
+L<http://wardley.org/>
-
-
-
-=head1 VERSION
-
-2.7, 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::Plugin|Template::Plugin>
+L<Template::Plugin>
=cut
Modified: trunk/lib/Template/Plugin/HTML.pm
===================================================================
--- trunk/lib/Template/Plugin/HTML.pm 2007-05-26 15:42:40 UTC (rev 1081)
+++ trunk/lib/Template/Plugin/HTML.pm 2007-05-26 15:43:31 UTC (rev 1082)
@@ -3,7 +3,6 @@
# Template::Plugin::HTML
#
# DESCRIPTION
-#
# Template Toolkit plugin providing useful functionality for generating
# HTML.
#
@@ -11,15 +10,11 @@
# Andy Wardley <abw@wardley.org>
#
# COPYRIGHT
-# Copyright (C) 1996-2006 Andy Wardley. All Rights Reserved.
-# Copyright (C) 1998-2001 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::Plugin::HTML;
@@ -34,7 +29,7 @@
my ($class, $context, @args) = @_;
my $hash = ref $args[-1] eq 'HASH' ? pop @args : { };
bless {
- _SORTED => $hash->{ sorted } || 0,
+ _SORTED => $hash->{ sorted } || 0,
}, $class;
}
@@ -55,17 +50,17 @@
@keys = sort @keys if $self->{ _SORTED };
join(' ', map {
- "$_=\"" . $self->escape( $hash->{ $_ } ) . '"';
+ "$_=\"" . $self->escape( $hash->{ $_ } ) . '"';
} @keys);
}
sub escape {
my ($self, $text) = @_;
for ($text) {
- s/&/&/g;
- s/</</g;
- s/>/>/g;
- s/"/"/g;
+ s/&/&/g;
+ s/</</g;
+ s/>/>/g;
+ s/"/"/g;
}
$text;
}
@@ -82,18 +77,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::Plugin::HTML - Plugin to create HTML elements
@@ -101,26 +84,24 @@
=head1 SYNOPSIS
[% USE HTML %]
-
+
[% HTML.escape("if (a < b && c > d) ..." %]
-
+
[% HTML.element(table => { border => 1, cellpadding => 2 }) %]
-
+
[% HTML.attributes(border => 1, cellpadding => 2) %]
=head1 DESCRIPTION
-The HTML plugin is very new and very basic, implementing a few useful
-methods for generating HTML. It is likely to be extended in the future
-or integrated with a larger project to generate HTML elements in a generic
-way (as discussed recently on the mod_perl mailing list).
+The C<HTML> plugin is a very basic plugin, implementing a few useful
+methods for generating HTML.
=head1 METHODS
=head2 escape(text)
Returns the source text with any HTML reserved characters such as
-E<lt>, E<gt>, etc., correctly esacped to their entity equivalents.
+C<E<lt>>, C<E<gt>>, etc., correctly esacped to their entity equivalents.
=head2 attributes(hash)
@@ -140,9 +121,9 @@
=head1 DEBUGGING
-The HTML plugin accepts a 'sorted' option as a constructor argument
+The HTML plugin accepts a C<sorted> option as a constructor argument
which, when set to any true value, causes the attributes generated by
-the attributes() method (either directly or via element()) to be
+the C<attributes()> method (either directly or via C<element()>) to be
returned in sorted order. Order of attributes isn't important in
HTML, but this is provided mainly for the purposes of debugging where
it is useful to have attributes generated in a deterministic order
@@ -160,27 +141,18 @@
Andy Wardley E<lt>abw@wardley.orgE<gt>
-L<http://wardley.org/|http://wardley.org/>
+L<http://wardley.org/>
-
-
-
-=head1 VERSION
-
-2.62, 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::Plugin|Template::Plugin>
+L<Template::Plugin>
=cut
Modified: trunk/lib/Template/Plugin/Image.pm
===================================================================
--- trunk/lib/Template/Plugin/Image.pm 2007-05-26 15:42:40 UTC (rev 1081)
+++ trunk/lib/Template/Plugin/Image.pm 2007-05-26 15:43:31 UTC (rev 1082)
@@ -12,9 +12,6 @@
# This module is free software; you can redistribute it and/or
# modify it under the same terms as Perl itself.
#
-# REVISION
-# $Id$
-#
#============================================================================
package Template::Plugin::Image;
@@ -207,18 +204,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::Plugin::Image - Plugin access to image sizes
@@ -234,10 +219,10 @@
=head1 DESCRIPTION
-This plugin provides an interface to the Image::Info or Image::Size
+This plugin provides an interface to the L<Image::Info> or L<Image::Size>
modules for determining the size of image files.
-You can specify the plugin name as either 'Image' or 'image'. The
+You can specify the plugin name as either 'C<Image>' or 'C<image>'. The
plugin object created will then have the same name. The file name of
the image should be specified as a positional or named argument.
@@ -248,7 +233,7 @@
[% USE image(name='baz.gif') %]
[% USE Image name='pong.gif' %]
-A "root" parameter can be used to specify the location of the image file:
+A C<root> parameter can be used to specify the location of the image file:
[% USE Image(root='/path/to/root', name='images/home.png') %]
# image path: /path/to/root/images/home.png
@@ -259,23 +244,23 @@
[% USE Image(file='/path/to/home.png', name='/images/home.png') %]
-The "alt" parameter can be used to specify an alternate name for the
-image, for use in constructing an XHTML element (see the tag() method
+The C<alt> parameter can be used to specify an alternate name for the
+image, for use in constructing an XHTML element (see the C<tag()> method
below).
[% USE Image('home.png', alt="Home") %]
-You can also provide an alternate name for an Image plugin object.
+You can also provide an alternate name for an C<Image> plugin object.
[% USE img1 = image 'foo.gif' %]
[% USE img2 = image 'bar.gif' %]
-The 'name' method returns the image file name.
+The C<name> method returns the image file name.
[% img1.name %] # foo.gif
-The 'width' and 'height' methods return the width and height of the
-image, respectively. The 'size' method returns a reference to a 2
+The C<width> and C<height> methods return the width and height of the
+image, respectively. The C<size> method returns a reference to a 2
element list containing the width and height.
[% USE image 'foo.gif' %]
@@ -283,14 +268,14 @@
height: [% image.height %]
size: [% image.size.join(', ') %]
-The 'modtime' method returns the ctime of the file in question, suitable
-for use with date.format:
+The C<modtime> method returns the modification time of the file in question,
+suitable for use with the L<Template::Plugin::Date|Date> plugin, for example:
[% USE image 'foo.gif' %]
[% USE date %]
[% date.format(image.modtime, "%B, %e %Y") %]
-The 'attr' method returns the height and width as HTML/XML attributes.
+The C<attr> method returns the height and width as HTML/XML attributes.
[% USE image 'foo.gif' %]
[% image.attr %]
@@ -299,7 +284,7 @@
width="60" height="20"
-The 'tag' method returns a complete XHTML tag referencing the image.
+The C<tag> method returns a complete XHTML tag referencing the image.
[% USE image 'foo.gif' %]
[% image.tag %]
@@ -318,18 +303,18 @@
<img src="foo.gif" width="60" height="20" alt="Logo" class="logo" />
-Note that the 'alt' attribute is mandatory in a strict XHTML 'img'
+Note that the C<alt> attribute is mandatory in a strict XHTML C<img>
element (even if it's empty) so it is always added even if you don't
explicitly provide a value for it. You can do so as an argument to
-the 'tag' method, as shown in the previous example, or as an argument
+the C<tag> method, as shown in the previous example, or as an argument
[% USE image('foo.gif', alt='Logo') %]
=head1 CATCHING ERRORS
If the image file cannot be found then the above methods will throw an
-'Image' error. You can enclose calls to these methods in a
-TRY...CATCH block to catch any potential errors.
+C<Image> error. You can enclose calls to these methods in a
+C<TRY...CATCH> block to catch any potential errors.
[% TRY;
image.width;
@@ -340,50 +325,47 @@
=head1 USING Image::Info
-At run time, the plugin tries to load Image::Info in preference to
-Image::Size. If Image::Info is found, then some additional methods are
-available, in addition to 'size', 'width', 'height', 'attr', and 'tag'.
-These additional methods are named after the elements that Image::Info
-retrieves from the image itself; see L<Image::Info> for more details
--- the types of methods available depend on the type of image.
-These additional methods will always include the following:
+At run time, the plugin tries to load L<Image::Info> in preference to
+L<Image::Size>. If L<Image::Info> is found, then some additional methods are
+available, in addition to C<size>, C<width>, C<height>, C<attr>, and C<tag>.
+These additional methods are named after the elements that L<Image::Info>
+retrieves from the image itself. The types of methods available depend on the
+type of image (see L<Image::Info> for more details). These additional methods
+will always include the following:
-=over 4
+=head2 file_media_type
-=item file_media_type
-
This is the MIME type that is appropriate for the given file format.
-The corresponding value is a string like: "image/png" or "image/jpeg".
+The corresponding value is a string like: "C<image/png>" or "C<image/jpeg>".
-=item file_ext
+=head2 file_ext
The is the suggested file name extention for a file of the given
file format. The value is a 3 letter, lowercase string like
-"png", "jpg".
+"C<png>", "C<jpg>".
+=head2 color_type
-=item color_type
-
The value is a short string describing what kind of values the pixels
encode. The value can be one of the following:
- Gray
- GrayA
- RGB
- RGBA
- CMYK
- YCbCr
- CIELab
+ Gray
+ GrayA
+ RGB
+ RGBA
+ CMYK
+ YCbCr
+ CIELab
-These names can also be prefixed by "Indexed-" if the image is
-composed of indexes into a palette. Of these, only "Indexed-RGB" is
+These names can also be prefixed by "C<Indexed->" if the image is
+composed of indexes into a palette. Of these, only "C<Indexed-RGB>" is
likely to occur.
(It is similar to the TIFF field PhotometricInterpretation, but this
name was found to be too long, so we used the PNG inpired term
instead.)
-=item resolution
+=head2 resolution
The value of this field normally gives the physical size of the image
on screen or paper. When the unit specifier is missing then this field
@@ -395,68 +377,55 @@
<xres> "/" <yres> <unit>
<xres> "/" <yres>
-The E<lt>resE<gt>, E<lt>xresE<gt> and E<lt>yresE<gt> fields are
-numbers. The E<lt>unitE<gt> is a string like C<dpi>, C<dpm> or
+The C<E<lt>resE<gt>>, C<E<lt>xresE<gt>> and C<E<lt>yresE<gt>> fields are
+numbers. The C<E<lt>unitE<gt>> is a string like C<dpi>, C<dpm> or
C<dpcm> (denoting "dots per inch/cm/meter).
-=item SamplesPerPixel
+=head2 SamplesPerPixel
This says how many channels there are in the image. For some image
formats this number might be higher than the number implied from the
C<color_type>.
-=item BitsPerSample
+=head2 BitsPerSample
This says how many bits are used to encode each of samples. The value
is a reference to an array containing numbers. The number of elements
in the array should be the same as C<SamplesPerPixel>.
-=item Comment
+=head2 Comment
Textual comments found in the file. The value is a reference to an
array if there are multiple comments found.
-=item Interlace
+=head2 Interlace
-If the image is interlaced, then this tell which interlace method is
-used.
+If the image is interlaced, then this returns the interlace type.
-=item Compression
+=head2 Compression
-This tell which compression algorithm is used.
+This returns the name of the compression algorithm is used.
-=item Gamma
+=head2 Gamma
-A number.
+A number indicating the gamma curve of the image (e.g. 2.2)
-
-=back
-
=head1 AUTHOR
Andy Wardley E<lt>abw@wardley.orgE<gt>
-L<http://wardley.org/|http://wardley.org/>
+L<http://wardley.org/>
-
-
-
-=head1 VERSION
-
-1.21, 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::Plugin|Template::Plugin>
+L<Template::Plugin>, L<Image::Info>
=cut
Modified: trunk/lib/Template/Plugin/Iterator.pm
===================================================================
--- trunk/lib/Template/Plugin/Iterator.pm 2007-05-26 15:42:40 UTC (rev 1081)
+++ trunk/lib/Template/Plugin/Iterator.pm 2007-05-26 15:43:31 UTC (rev 1082)
@@ -11,14 +11,11 @@
# Andy Wardley <abw@wardley.org>
#
# COPYRIGHT
-# Copyright (C) 2000-2006 Andy Wardley. All Rights Reserved.
+# Copyright (C) 2000-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::Plugin::Iterator;
@@ -44,18 +41,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::Plugin::Iterator - Plugin to create iterators (Template::Iterator)
@@ -63,7 +48,7 @@
=head1 SYNOPSIS
[% USE iterator(list, args) %]
-
+
[% FOREACH item = iterator %]
[% '<ul>' IF iterator.first %]
<li>[% item %]
@@ -72,36 +57,27 @@
=head1 DESCRIPTION
-The iterator plugin provides a way to create a Template::Iterator object
+The iterator plugin provides a way to create a L<Template::Iterator> object
to iterate over a data set. An iterator is implicitly automatically by the
-FOREACH directive. This plugin allows the iterator to be explicitly created
+L<FOREACH> directive. This plugin allows the iterator to be explicitly created
with a given name.
=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::Plugin|Template::Plugin>, L<Template::Iterator|Template::Iterator>
+L<Template::Plugin>, L<Template::Iterator>
=cut
Modified: trunk/lib/Template/Plugin/List.pm
===================================================================
--- trunk/lib/Template/Plugin/List.pm 2007-05-26 15:42:40 UTC (rev 1081)
+++ trunk/lib/Template/Plugin/List.pm 2007-05-26 15:43:31 UTC (rev 1082)
@@ -4,19 +4,17 @@
#
# DESCRIPTION
# Template Toolkit plugin to implement an OO List object.
+# (work in progress)
#
# AUTHOR
# Andy Wardley <abw@wardley.org>
#
# COPYRIGHT
-# Copyright (C) 2001-2006 Andy Wardley. All Rights Reserved.
+# Copyright (C) 2001-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::Plugin::List;
@@ -44,9 +42,9 @@
$class = ref($class) || $class;
my $list = defined $config->{ list }
- ? $config->{ list }
+ ? $config->{ list }
: (scalar @args == 1 && ref $args[0] eq 'ARRAY' ? CORE::shift(@args)
- : [ @_ ]);
+ : [ @_ ]);
print STDERR " list: [ @$list ]\n";
print STDERR "class: [$class]\n";
@@ -56,9 +54,9 @@
: ', ';
bless {
- list => $text,
- joint => $joint,
- _CONTEXT => $context,
+ list => $text,
+ joint => $joint,
+ _CONTEXT => $context,
}, $class;
}
@@ -141,523 +139,9 @@
return $#$list + 1;
}
- 'first' => sub { my $list = shift; $list->[0] },
- 'last' => sub { my $list = shift; $list->[$#$list] },
- 'reverse' => sub { my $list = shift; [ reverse @$list ] },
- 'join' => sub {
- my ($list, $joint) = @_;
- join(defined $joint ? $joint : ' ',
- map { defined $_ ? $_ : '' } @$list)
- },
- 'sort' => sub {
- my ($list, $field) = @_;
- return $list unless $#$list; # no need to sort 1 item lists
- return $field # Schwartzian Transform
- ? map { $_->[0] } # for case insensitivity
- sort { $a->[1] cmp $b->[1] }
- map { [ $_, lc $_->{ $field } ] }
- @$list
- : map { $_->[0] }
- sort { $a->[1] cmp $b->[1] }
- map { [ $_, lc $_ ] }
- @$list
- },
- 'nsort' => sub {
- my ($list, $field) = @_;
- return $list unless $#$list; # no need to sort 1 item lists
- return $field # Schwartzian Transform
- ? map { $_->[0] } # for case insensitivity
- sort { $a->[1] <=> $b->[1] }
- map { [ $_, lc $_->{ $field } ] }
- @$list
- : map { $_->[0] }
- sort { $a->[1] <=> $b->[1] }
- map { [ $_, lc $_ ] }
- @$list
- },
- defined $LIST_OPS ? %$LIST_OPS : (),
-
-#------------------------------------------------------------------------
-
-
-#------------------------------------------------------------------------
-
-sub length {
- my $self = CORE::shift;
- return length $self->{ text };
-}
-
-
-sub truncate {
- my ($self, $length, $suffix) = @_;
- return $self unless defined $length;
- $suffix ||= '';
- $self->{ text } = substr($self->{ text }, 0,
- $length - CORE::length($suffix)) . $suffix;
- return $self;
-}
-
-
-sub repeat {
- my ($self, $n) = @_;
- return $self unless defined $n;
- $self->{ text } = $self->{ text } x $n;
- return $self;
-}
-
-
-sub replace {
- my ($self, $search, $replace) = @_;
- return $self unless defined $search;
- $replace = '' unless defined $replace;
- $self->{ text } =~ s/$search/$replace/g;
- return $self;
-}
-
-
-sub remove {
- my ($self, $search) = @_;
- $search = '' unless defined $search;
- $self->{ text } =~ s/$search//g;
- return $self;
-}
-
-
-sub split {
- my $self = CORE::shift;
- my $split = CORE::shift;
- my $limit = CORE::shift || 0;
- $split = '\s+' unless defined $split;
- return [ split($split, $self->{ text }, $limit) ];
-}
-
-
-sub search {
- my ($self, $pattern) = @_;
- return $self->{ text } =~ /$pattern/;
-}
-
-
-sub equals {
- my ($self, $comparison) = @_;
- return $self->{ text } eq $comparison;
-}
-
-
1;
__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::Plugin::String - Object oriented interface for string manipulation
-
-=head1 SYNOPSIS
-
- # create String objects via USE directive
- [% USE String %]
- [% USE String 'initial text' %]
- [% USE String text => 'initial text' %]
-
- # or from an existing String via new()
- [% newstring = String.new %]
- [% newstring = String.new('newstring text') %]
- [% newstring = String.new( text => 'newstring text' ) %]
-
- # or from an existing String via copy()
- [% newstring = String.copy %]
-
- # append text to string
- [% String.append('text to append') %]
-
- # format left, right or center/centre padded
- [% String.left(20) %]
- [% String.right(20) %]
- [% String.center(20) %] # American spelling
- [% String.centre(20) %] # European spelling
-
- # and various other methods...
-
-=head1 DESCRIPTION
-
-This module implements a String class for doing stringy things to
-text in an object-oriented way.
-
-You can create a String object via the USE directive, adding any
-initial text value as an argument or as the named parameter 'text'.
-
- [% USE String %]
- [% USE String 'initial text' %]
- [% USE String text='initial text' %]
-
-The object created will be referenced as 'String' by default, but you
-can provide a different variable name for the object to be assigned
-to:
-
- [% USE greeting = String 'Hello World' %]
-
-Once you've got a String object, you can use it as a prototype to
-create other String objects with the new() method.
-
- [% USE String %]
- [% greeting = String.new('Hello World') %]
-
-The new() method also accepts an initial text string as an argument
-or the named parameter 'text'.
-
- [% greeting = String.new( text => 'Hello World' ) %]
-
-You can also call copy() to create a new String as a copy of the
-original.
-
- [% greet2 = greeting.copy %]
-
-The String object has a text() method to return the content of the
-string.
-
- [% greeting.text %]
-
-However, it is sufficient to simply print the string and let the
-overloaded stringification operator call the text() method
-automatically for you.
-
- [% greeting %]
-
-Thus, you can treat String objects pretty much like any regular piece
-of text, interpolating it into other strings, for example:
-
- [% msg = "It printed '$greeting' and then dumped core\n" %]
-
-You also have the benefit of numerous other methods for manipulating
-the string.
-
- [% msg.append("PS Don't eat the yellow snow") %]
-
-Note that all methods operate on and mutate the contents of the string
-itself. If you want to operate on a copy of the string then simply
-take a copy first:
-
- [% msg.copy.append("PS Don't eat the yellow snow") %]
-
-These methods return a reference to the String object itself. This
-allows you to chain multiple methods together.
-
- [% msg.copy.append('foo').right(72) %]
-
-It also means that in the above examples, the String is returned which
-causes the text() method to be called, which results in the new value of
-the string being printed. To suppress printing of the string, you can
-use the CALL directive.
-
- [% foo = String.new('foo') %]
-
- [% foo.append('bar') %] # prints "foobar"
-
- [% CALL foo.append('bar') %] # nothing
-
-=head1 METHODS
-
-=head2 Construction Methods
-
-The following methods are used to create new String objects.
-
-=over 4
-
-=item new()
-
-Creates a new string using an initial value passed as a positional
-argument or the named parameter 'text'.
-
- [% USE String %]
- [% msg = String.new('Hello World') %]
- [% msg = String.new( text => 'Hello World' ) %]
-
-=item copy()
-
-Creates a new String object which contains a copy of the original string.
-
- [% msg2 = msg.copy %]
-
-=back
-
-=head2 Inspection Methods
-
-These methods are used to inspect the string content or other parameters
-relevant to the string.
-
-=over 4
-
-=item text()
-
-Returns the internal text value of the string. The stringification
-operator is overloaded to call this method. Thus the following are
-equivalent:
-
- [% msg.text %]
- [% msg %]
-
-=item length()
-
-Returns the length of the string.
-
- [% USE String("foo") %]
-
- [% String.length %] # => 3
-
-=item search($pattern)
-
-Searches the string for the regular expression specified in $pattern
-returning true if found or false otherwise.
-
- [% item = String.new('foo bar baz wiz waz woz') %]
-
- [% item.search('wiz') ? 'WIZZY! :-)' : 'not wizzy :-(' %]
-
-=item split($pattern, $limit)
-
-Splits the string based on the delimiter $pattern and optional $limit.
-Delegates to Perl's internal split() so the parameters are exactly the same.
-
- [% FOREACH item.split %]
- ...
- [% END %]
-
- [% FOREACH item.split('baz|waz') %]
- ...
- [% END %]
-
-=back
-
-=head2 Mutation Methods
-
-These methods modify the internal value of the string. For example:
-
- [% USE str=String('foobar') %]
-
- [% str.append('.html') %] # str => 'foobar.html'
-
-The value of the String 'str' is now 'foobar.html'. If you don't want
-to modify the string then simply take a copy first.
-
- [% str.copy.append('.html') %]
-
-These methods all return a reference to the String object itself. This
-has two important benefits. The first is that when used as above, the
-String object 'str' returned by the append() method will be stringified
-with a call to its text() method. This will return the newly modified
-string content. In other words, a directive like:
-
- [% str.append('.html') %]
-
-will update the string and also print the new value. If you just want
-to update the string but not print the new value then use CALL.
-
- [% CALL str.append('.html') %]
-
-The other benefit of these methods returning a reference to the String
-is that you can chain as many different method calls together as you
-like. For example:
-
- [% String.append('.html').trim.format(href) %]
-
-Here are the methods:
-
-=over 4
-
-=item push($suffix, ...) / append($suffix, ...)
-
-Appends all arguments to the end of the string. The
-append() method is provided as an alias for push().
-
- [% msg.push('foo', 'bar') %]
- [% msg.append('foo', 'bar') %]
-
-=item pop($suffix)
-
-Removes the suffix passed as an argument from the end of the String.
-
- [% USE String 'foo bar' %]
- [% String.pop(' bar') %] # => 'foo'
-
-=item unshift($prefix, ...) / prepend($prefix, ...)
-
-Prepends all arguments to the beginning of the string. The
-prepend() method is provided as an alias for unshift().
-
- [% msg.unshift('foo ', 'bar ') %]
- [% msg.prepend('foo ', 'bar ') %]
-
-=item shift($prefix)
-
-Removes the prefix passed as an argument from the start of the String.
-
- [% USE String 'foo bar' %]
- [% String.shift('foo ') %] # => 'bar'
-
-=item left($pad)
-
-If the length of the string is less than $pad then the string is left
-formatted and padded with spaces to $pad length.
-
- [% msg.left(20) %]
-
-=item right($pad)
-
-As per left() but right padding the String to a length of $pad.
-
- [% msg.right(20) %]
-
-=item center($pad) / centre($pad)
-
-As per left() and right() but formatting the String to be centered within
-a space padded string of length $pad. The centre() method is provided as
-an alias for center() to keep Yanks and Limeys happy.
-
- [% msg.center(20) %] # American spelling
- [% msg.centre(20) %] # European spelling
-
-=item format($format)
-
-Apply a format in the style of sprintf() to the string.
-
- [% USE String("world") %]
- [% String.format("Hello %s\n") %] # => "Hello World\n"
-
-=item upper()
-
-Converts the string to upper case.
-
- [% USE String("foo") %]
-
- [% String.upper %] # => 'FOO'
-
-=item lower()
-
-Converts the string to lower case
-
- [% USE String("FOO") %]
-
- [% String.lower %] # => 'foo'
-
-=item capital()
-
-Converts the first character of the string to upper case.
-
- [% USE String("foo") %]
-
- [% String.capital %] # => 'Foo'
-
-The remainder of the string is left untouched. To force the string to
-be all lower case with only the first letter capitalised, you can do
-something like this:
-
- [% USE String("FOO") %]
-
- [% String.lower.capital %] # => 'Foo'
-
-=item chop()
-
-Removes the last character from the string.
-
- [% USE String("foop") %]
-
- [% String.chop %] # => 'foo'
-
-=item chomp()
-
-Removes the trailing newline from the string.
-
- [% USE String("foo\n") %]
-
- [% String.chomp %] # => 'foo'
-
-=item trim()
-
-Removes all leading and trailing whitespace from the string
-
- [% USE String(" foo \n\n ") %]
-
- [% String.trim %] # => 'foo'
-
-=item collapse()
-
-Removes all leading and trailing whitespace and collapses any sequences
-of multiple whitespace to a single space.
-
- [% USE String(" \n\r \t foo \n \n bar \n") %]
-
- [% String.collapse %] # => "foo bar"
-
-=item truncate($length, $suffix)
-
-Truncates the string to $length characters.
-
- [% USE String('long string') %]
- [% String.truncate(4) %] # => 'long'
-
-If $suffix is specified then it will be appended to the truncated
-string. In th