--- /dev/null
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sh \" Subsection heading
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. | will give a
+.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
+.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
+.\" expand to `' in nroff, nothing in troff, for use with C<>.
+.tr \(*W-|\(bv\*(Tr
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'br\}
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.\"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.hy 0
+.if n .na
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "Template::Manual::Plugins 3"
+.TH Template::Manual::Plugins 3 "2008-11-13" "perl v5.8.7" "User Contributed Perl Documentation"
+.SH "NAME"
+Template::Manual::Plugins \- Standard plugins
+.SH "TEMPLATE TOOLKIT PLUGINS"
+.IX Header "TEMPLATE TOOLKIT PLUGINS"
+The following plugin modules are distributed with the Template
+Toolkit. Some of the plugins interface to external modules (detailed
+below) which should be downloaded from any \s-1CPAN\s0 site and installed
+before using the plugin.
+.Sh "Assert"
+.IX Subsection "Assert"
+New in 2.20! The Assert plugin adds an
+\&\f(CW\*(C`assert\*(C'\fR virtual method that you can use to catch undefined values.
+.PP
+For example, consider this dotop:
+.PP
+.Vb 1
+\& [% user.name %]
+.Ve
+.PP
+If \f(CW\*(C`user.name\*(C'\fR is an undefined value then \s-1TT\s0 will silently ignore the
+fact and print nothing. If you \f(CW\*(C`USE\*(C'\fR the \f(CW\*(C`assert\*(C'\fR plugin then you
+can add the \f(CW\*(C`assert\*(C'\fR vmethod between the \f(CW\*(C`user\*(C'\fR and \f(CW\*(C`name\*(C'\fR elements,
+like so:
+.PP
+.Vb 1
+\& [% user.assert.name %]
+.Ve
+.PP
+Now, if \f(CW\*(C`user.name\*(C'\fR is an undefined value, an exception will be thrown:
+.PP
+.Vb 1
+\& assert error \- undefined value for name
+.Ve
+.Sh "Autoformat"
+.IX Subsection "Autoformat"
+The Autoformat plugin is an interface to
+Damian Conway's Text::Autoformat Perl module which provides advanced text
+wrapping and formatting. See Template::Plugin::Autoformat and
+Text::Autoformat for further details.
+.PP
+.Vb 3
+\& [% USE autoformat(left=10, right=20) %]
+\& [% autoformat(mytext) %] # call autoformat sub
+\& [% mytext FILTER autoformat %] # or use autoformat filter
+.Ve
+.PP
+The Text::Autoformat module is available from \s-1CPAN:\s0
+.PP
+.Vb 1
+\& L<http://www.cpan.org/modules/by\-module/Text/>
+.Ve
+.Sh "\s-1CGI\s0"
+.IX Subsection "CGI"
+The \s-1CGI\s0 plugin is a wrapper around Lincoln Stein's
+\&\s-1CGI\s0.pm module. The plugin is distributed with the Template Toolkit (see
+Template::Plugin::CGI) and the \s-1CGI\s0 module itself is distributed with
+recent versions Perl, or is available from \s-1CPAN\s0.
+.PP
+.Vb 6
+\& [% USE CGI %]
+\& [% CGI.param('param_name') %]
+\& [% CGI.start_form %]
+\& [% CGI.popup_menu( Name => 'color',
+\& Values => [ 'Green', 'Brown' ] ) %]
+\& [% CGI.end_form %]
+.Ve
+.Sh "Datafile"
+.IX Subsection "Datafile"
+Provides an interface to data stored in a plain text file in a simple
+delimited format. The first line in the file specifies field names
+which should be delimiter by any non-word character sequence.
+Subsequent lines define data using the same delimiter as in the first
+line. Blank lines and comments (lines starting '#') are ignored. See
+Template::Plugin::Datafile for further details.
+.PP
+/tmp/mydata:
+.PP
+.Vb 5
+\& # define names for each field
+\& id : email : name : tel
+\& # here's the data
+\& fred : fred@here.com : Fred Smith : 555\-1234
+\& bill : bill@here.com : Bill White : 555\-5678
+.Ve
+.PP
+example:
+.PP
+.Vb 1
+\& [% USE userlist = datafile('/tmp/mydata') %]
+.Ve
+.PP
+.Vb 3
+\& [% FOREACH user = userlist %]
+\& [% user.name %] ([% user.id %])
+\& [% END %]
+.Ve
+.Sh "Date"
+.IX Subsection "Date"
+The Date plugin provides an easy way to generate
+formatted time and date strings by delegating to the \s-1POSIX\s0 \f(CW\*(C`strftime()\*(C'\fR
+routine. See Template::Plugin::Date and \s-1POSIX\s0 for further details.
+.PP
+.Vb 2
+\& [% USE date %]
+\& [% date.format %] # current time/date
+.Ve
+.PP
+.Vb 1
+\& File last modified: [% date.format(template.modtime) %]
+.Ve
+.Sh "Directory"
+.IX Subsection "Directory"
+The Directory plugin provides a simple
+interface to a directory and the files within it. See
+Template::Plugin::Directory for further details.
+.PP
+.Vb 7
+\& [% USE dir = Directory('/tmp') %]
+\& [% FOREACH file = dir.files %]
+\& # all the plain files in the directory
+\& [% END %]
+\& [% FOREACH file = dir.dirs %]
+\& # all the sub\-directories
+\& [% END %]
+.Ve
+.Sh "\s-1DBI\s0"
+.IX Subsection "DBI"
+The \f(CW\*(C`DBI\*(C'\fR plugin is no longer distributed as part of the Template Toolkit
+(as of version 2.15). It is now available as a separate Template::DBI
+distribution from \s-1CPAN\s0.
+.Sh "Dumper"
+.IX Subsection "Dumper"
+The Dumper plugin provides an interface to the
+Data::Dumper module. See Template::Plugin::Dumper and Data::Dumper for
+futher details.
+.PP
+.Vb 2
+\& [% USE dumper(indent=0, pad="<br>") %]
+\& [% dumper.dump(myvar, yourvar) %]
+.Ve
+.Sh "File"
+.IX Subsection "File"
+The File plugin provides a general abstraction for
+files and can be used to fetch information about specific files within a
+filesystem. See Template::Plugin::File for further details.
+.PP
+.Vb 4
+\& [% USE File('/tmp/foo.html') %]
+\& [% File.name %] # foo.html
+\& [% File.dir %] # /tmp
+\& [% File.mtime %] # modification time
+.Ve
+.Sh "Filter"
+.IX Subsection "Filter"
+This module implements a base class plugin which can be subclassed
+to easily create your own modules that define and install new filters.
+.PP
+.Vb 1
+\& package MyOrg::Template::Plugin::MyFilter;
+.Ve
+.PP
+.Vb 2
+\& use Template::Plugin::Filter;
+\& use base qw( Template::Plugin::Filter );
+.Ve
+.PP
+.Vb 5
+\& sub filter {
+\& my ($self, $text) = @_;
+\& # ...mungify $text...
+\& return $text;
+\& }
+.Ve
+.PP
+Example of use:
+.PP
+.Vb 2
+\& # now load it...
+\& [% USE MyFilter %]
+.Ve
+.PP
+.Vb 4
+\& # ...and use the returned object as a filter
+\& [% FILTER $MyFilter %]
+\& ...
+\& [% END %]
+.Ve
+.PP
+See Template::Plugin::Filter for further details.
+.Sh "Format"
+.IX Subsection "Format"
+The Format plugin provides a simple way to format
+text according to a \f(CW\*(C`printf()\*(C'\fR\-like format. See Template::Plugin::Format for
+further details.
+.PP
+.Vb 2
+\& [% USE bold = format('<b>%s</b>') %]
+\& [% bold('Hello') %]
+.Ve
+.Sh "\s-1GD\s0"
+.IX Subsection "GD"
+The \f(CW\*(C`GD\*(C'\fR plugins are no longer part of the core Template Toolkit distribution.
+They are now available from \s-1CPAN\s0 in a separate Template::GD distribution.
+.Sh "\s-1HTML\s0"
+.IX Subsection "HTML"
+The \s-1HTML\s0 plugin is very basic, implementing a few
+useful methods for generating \s-1HTML\s0. It is likely to be extended in the future
+or integrated with a larger project to generate \s-1HTML\s0 elements in a generic way.
+.PP
+.Vb 4
+\& [% USE HTML %]
+\& [% HTML.escape("if (a < b && c > d) ..." %]
+\& [% HTML.attributes(border => 1, cellpadding => 2) %]
+\& [% HTML.element(table => { border => 1, cellpadding => 2 }) %]
+.Ve
+.PP
+See Template::Plugin::HTML for further details.
+.Sh "Iterator"
+.IX Subsection "Iterator"
+The Iterator plugin provides a way to create a
+Template::Iterator object to iterate over a data set. An iterator is
+created automatically by the \f(CW\*(C`FOREACH\*(C'\fR directive and is aliased to the \f(CW\*(C`loop\*(C'\fR
+variable. This plugin allows an iterator to be explicitly created with a given
+name, or the default plugin name, \f(CW\*(C`iterator\*(C'\fR. See
+Template::Plugin::Iterator for further details.
+.PP
+.Vb 1
+\& [% USE iterator(list, args) %]
+.Ve
+.PP
+.Vb 5
+\& [% FOREACH item = iterator %]
+\& [% '<ul>' IF iterator.first %]
+\& <li>[% item %]
+\& [% '</ul>' IF iterator.last %]
+\& [% END %]
+.Ve
+.Sh "Pod"
+.IX Subsection "Pod"
+This plugin provides an interface to the Pod::POM module
+which parses \s-1POD\s0 documents into an internal object model which can
+then be traversed and presented through the Template Toolkit.
+.PP
+.Vb 1
+\& [% USE Pod(podfile) %]
+.Ve
+.PP
+.Vb 6
+\& [% FOREACH head1 = Pod.head1;
+\& FOREACH head2 = head1/head2;
+\& ...
+\& END;
+\& END
+\& %]
+.Ve
+.Sh "Scalar"
+.IX Subsection "Scalar"
+The Template Toolkit calls user-defined subroutines and object methods
+using Perl's array context by default.
+.PP
+.Vb 2
+\& # TT2 calls object methods in array context by default
+\& [% object.method %]
+.Ve
+.PP
+This plugin module provides a way for you to call subroutines and methods
+in scalar context.
+.PP
+.Vb 1
+\& [% USE scalar %]
+.Ve
+.PP
+.Vb 2
+\& # force it to use scalar context
+\& [% object.scalar.method %]
+.Ve
+.PP
+.Vb 2
+\& # also works with subroutine references
+\& [% scalar.my_sub_ref %]
+.Ve
+.Sh "String"
+.IX Subsection "String"
+The String plugin implements an object-oriented
+interface for manipulating strings. See Template::Plugin::String for
+further details.
+.PP
+.Vb 2
+\& [% USE String 'Hello' %]
+\& [% String.append(' World') %]
+.Ve
+.PP
+.Vb 2
+\& [% msg = String.new('Another string') %]
+\& [% msg.replace('string', 'text') %]
+.Ve
+.PP
+.Vb 1
+\& The string "[% msg %]" is [% msg.length %] characters long.
+.Ve
+.Sh "Table"
+.IX Subsection "Table"
+The Table plugin allows you to format a list of
+data items into a virtual table by specifying a fixed number of rows or
+columns, with an optional overlap. See Template::Plugin::Table for further
+details.
+.PP
+.Vb 1
+\& [% USE table(list, rows=10, overlap=1) %]
+.Ve
+.PP
+.Vb 3
+\& [% FOREACH item = table.col(3) %]
+\& [% item %]
+\& [% END %]
+.Ve
+.Sh "\s-1URL\s0"
+.IX Subsection "URL"
+The \s-1URL\s0 plugin provides a simple way of contructing
+URLs from a base part and a variable set of parameters. See
+Template::Plugin::URL for further details.
+.PP
+.Vb 1
+\& [% USE mycgi = url('/cgi\-bin/bar.pl', debug=1) %]
+.Ve
+.PP
+.Vb 2
+\& [% mycgi %]
+\& # ==> /cgi/bin/bar.pl?debug=1
+.Ve
+.PP
+.Vb 2
+\& [% mycgi(mode='submit') %]
+\& # ==> /cgi/bin/bar.pl?mode=submit&debug=1
+.Ve
+.Sh "Wrap"
+.IX Subsection "Wrap"
+The Wrap plugin uses the Text::Wrap module to
+provide simple paragraph formatting. See Template::Plugin::Wrap and
+Text::Wrap for further details.
+.PP
+.Vb 3
+\& [% USE wrap %]
+\& [% wrap(mytext, 40, '* ', ' ') %] # use wrap sub
+\& [% mytext FILTER wrap(40) \-%] # or wrap FILTER
+.Ve
+.PP
+The \f(CW\*(C`Text::Wrap\*(C'\fR module is available from \s-1CPAN:\s0
+.PP
+.Vb 1
+\& http://www.cpan.org/modules/by\-module/Text/
+.Ve
+.Sh "\s-1XML\s0"
+.IX Subsection "XML"
+The \f(CW\*(C`XML::DOM\*(C'\fR, \f(CW\*(C`XML::RSS\*(C'\fR, \f(CW\*(C`XML::Simple\*(C'\fR and \f(CW\*(C`XML::XPath\*(C'\fR plugins are no
+longer distributed with the Template Toolkit as of version 2.15
+.PP
+They are now available in a separate Template::XML distribution.
projects / catagits/Gitalist.git / blobdiff