* Update installation list with required modules

* Remove unused/doubled provided external perl moduls

1 files changed, 0 insertions, 1448 deletions

diff --git a/lib/Template/Filters.pm b/lib/Template/Filters.pm
deleted file mode 100644
index a9c4846..0000000
--- a/lib/Template/Filters.pm
+++ /dev/null
@@ -1,1448 +0,0 @@
-#============================================================= -*-Perl-*-
-#
-# Template::Filters
-#
-# DESCRIPTION
-#   Defines filter plugins as used by the FILTER directive.
-#
-# AUTHORS
-#   Andy Wardley <abw@kfs.org>, with a number of filters contributed
-#   by Leslie Michael Orchard <deus_x@nijacode.com>
-#
-# COPYRIGHT
-#   Copyright (C) 1996-2000 Andy Wardley.  All Rights Reserved.
-#   Copyright (C) 1998-2000 Canon Research Centre Europe Ltd.
-#
-#   This module is free software; you can redistribute it and/or
-#   modify it under the same terms as Perl itself.
-#
-#----------------------------------------------------------------------------
-#
-# $Id: Filters.pm,v 2.77 2004/01/13 16:19:10 abw Exp $
-#
-#============================================================================
-
-package Template::Filters;
-
-require 5.004;
-
-use strict;
-use base qw( Template::Base );
-use vars qw( $VERSION $DEBUG $FILTERS $URI_ESCAPES $PLUGIN_FILTER );
-use Template::Constants;
-
-$VERSION = sprintf("%d.%02d", q$Revision: 2.77 $ =~ /(\d+)\.(\d+)/);
-
-
-#------------------------------------------------------------------------
-# standard filters, defined in one of the following forms:
-#   name =>   \&static_filter
-#   name => [ \&subref, $is_dynamic ]
-# If the $is_dynamic flag is set then the sub-routine reference 
-# is called to create a new filter each time it is requested;  if
-# not set, then it is a single, static sub-routine which is returned
-# for every filter request for that name.
-#------------------------------------------------------------------------
-
-$FILTERS = {
-    # static filters 
-    'html'            => \&html_filter,
-    'html_para'       => \&html_paragraph,
-    'html_break'      => \&html_para_break,
-    'html_para_break' => \&html_para_break,
-    'html_line_break' => \&html_line_break,
-    'uri'             => \&uri_filter,
-    'upper'           => sub { uc $_[0] },
-    'lower'           => sub { lc $_[0] },
-    'ucfirst'         => sub { ucfirst $_[0] },
-    'lcfirst'         => sub { lcfirst $_[0] },
-    'stderr'          => sub { print STDERR @_; return '' },
-    'trim'            => sub { for ($_[0]) { s/^\s+//; s/\s+$// }; $_[0] },
-    'null'            => sub { return '' },
-    'collapse'        => sub { for ($_[0]) { s/^\s+//; s/\s+$//; s/\s+/ /g };
-                               $_[0] },
-
-    # dynamic filters
-    'html_entity' => [ \&html_entity_filter_factory, 1 ],
-    'indent'      => [ \&indent_filter_factory,      1 ],
-    'format'      => [ \&format_filter_factory,      1 ],
-    'truncate'    => [ \&truncate_filter_factory,    1 ],
-    'repeat'      => [ \&repeat_filter_factory,      1 ],
-    'replace'     => [ \&replace_filter_factory,     1 ],
-    'remove'      => [ \&remove_filter_factory,      1 ],
-    'eval'        => [ \&eval_filter_factory,        1 ],
-    'evaltt'      => [ \&eval_filter_factory,        1 ],  # alias
-    'perl'        => [ \&perl_filter_factory,        1 ],
-    'evalperl'    => [ \&perl_filter_factory,        1 ],  # alias
-    'redirect'    => [ \&redirect_filter_factory,    1 ],
-    'file'        => [ \&redirect_filter_factory,    1 ],  # alias
-    'stdout'      => [ \&stdout_filter_factory,      1 ],
-    'latex'       => [ \&latex_filter_factory,       1 ],
-};
-
-# name of module implementing plugin filters
-$PLUGIN_FILTER = 'Template::Plugin::Filter';
-
-
-#========================================================================
-#                         -- PUBLIC METHODS --
-#========================================================================
-
-#------------------------------------------------------------------------
-# fetch($name, \@args, $context)
-#
-# Attempts to instantiate or return a reference to a filter sub-routine 
-# named by the first parameter, $name, with additional constructor 
-# arguments passed by reference to a list as the second parameter, 
-# $args.  A reference to the calling Template::Context object is 
-# passed as the third paramter.
-#
-# Returns a reference to a filter sub-routine or a pair of values
-# (undef, STATUS_DECLINED) or ($error, STATUS_ERROR) to decline to
-# deliver the filter or to indicate an error.
-#------------------------------------------------------------------------
-
-sub fetch {
-    my ($self, $name, $args, $context) = @_;
-    my ($factory, $is_dynamic, $filter, $error);
-
-    $self->debug("fetch($name, ", 
-                 defined $args ? ('[ ', join(', ', @$args), ' ]') : '<no args>', ', ',
-                 defined $context ? $context : '<no context>', 
-                 ')') if $self->{ DEBUG };
-
-    # allow $name to be specified as a reference to 
-    # a plugin filter object;  any other ref is 
-    # assumed to be a coderef and hence already a filter;
-    # non-refs are assumed to be regular name lookups
-
-    if (ref $name) {
-        if (UNIVERSAL::isa($name, $PLUGIN_FILTER)) {
-            $factory = $name->factory()
-                || return $self->error($name->error());
-        }
-        else {
-            return $name;
-        }
-    }
-    else {
-        return (undef, Template::Constants::STATUS_DECLINED)
-            unless ($factory = $self->{ FILTERS }->{ $name }
-                    || $FILTERS->{ $name });
-    }
-
-    # factory can be an [ $code, $dynamic ] or just $code
-    if (ref $factory eq 'ARRAY') {
-        ($factory, $is_dynamic) = @$factory;
-    }
-    else {
-        $is_dynamic = 0;
-    }
-
-    if (ref $factory eq 'CODE') {
-        if ($is_dynamic) {
-            # if the dynamic flag is set then the sub-routine is a 
-            # factory which should be called to create the actual 
-            # filter...
-            eval {
-                ($filter, $error) = &$factory($context, $args ? @$args : ());
-            };
-            $error ||= $@;
-            $error = "invalid FILTER for '$name' (not a CODE ref)"
-                unless $error || ref($filter) eq 'CODE';
-        }
-        else {
-            # ...otherwise, it's a static filter sub-routine
-            $filter = $factory;
-        }
-    }
-    else {
-        $error = "invalid FILTER entry for '$name' (not a CODE ref)";
-    }
-
-    if ($error) {
-        return $self->{ TOLERANT } 
-               ? (undef,  Template::Constants::STATUS_DECLINED) 
-               : ($error, Template::Constants::STATUS_ERROR) ;
-    }
-    else {
-        return $filter;
-    }
-}
-
-
-#------------------------------------------------------------------------
-# store($name, \&filter)
-#
-# Stores a new filter in the internal FILTERS hash.  The first parameter
-# is the filter name, the second a reference to a subroutine or 
-# array, as per the standard $FILTERS entries.
-#------------------------------------------------------------------------
-
-sub store {
-    my ($self, $name, $filter) = @_;
-
-    $self->debug("store($name, $filter)") if $self->{ DEBUG };
-
-    $self->{ FILTERS }->{ $name } = $filter;
-    return 1;
-}
-
-
-#========================================================================
-#                        -- PRIVATE METHODS --
-#========================================================================
-
-#------------------------------------------------------------------------
-# _init(\%config)
-#
-# Private initialisation method.
-#------------------------------------------------------------------------
-
-sub _init {
-    my ($self, $params) = @_;
-
-    $self->{ FILTERS  } = $params->{ FILTERS } || { };
-    $self->{ TOLERANT } = $params->{ TOLERANT }  || 0;
-    $self->{ DEBUG    } = ( $params->{ DEBUG } || 0 )
-                          & Template::Constants::DEBUG_FILTERS;
-
-
-    return $self;
-}
-
-
-
-#------------------------------------------------------------------------
-# _dump()
-# 
-# Debug method
-#------------------------------------------------------------------------
-
-sub _dump {
-    my $self = shift;
-    my $output = "[Template::Filters] {\n";
-    my $format = "    %-16s => %s\n";
-    my $key;
-
-    foreach $key (qw( TOLERANT )) {
-        my $val = $self->{ $key };
-        $val = '<undef>' unless defined $val;
-        $output .= sprintf($format, $key, $val);
-    }
-
-    my $filters = $self->{ FILTERS };
-    $filters = join('', map { 
-        sprintf("    $format", $_, $filters->{ $_ });
-    } keys %$filters);
-    $filters = "{\n$filters    }";
-    
-    $output .= sprintf($format, 'FILTERS (local)' => $filters);
-
-    $filters = $FILTERS;
-    $filters = join('', map { 
-        my $f = $filters->{ $_ };
-        my ($ref, $dynamic) = ref $f eq 'ARRAY' ? @$f : ($f, 0);
-        sprintf("    $format", $_, $dynamic ? 'dynamic' : 'static');
-    } sort keys %$filters);
-    $filters = "{\n$filters    }";
-    
-    $output .= sprintf($format, 'FILTERS (global)' => $filters);
-
-    $output .= '}';
-    return $output;
-}
-
-
-#========================================================================
-#                         -- STATIC FILTER SUBS --
-#========================================================================
-
-#------------------------------------------------------------------------
-# uri_filter()                                           [% FILTER uri %]
-#
-# URI escape a string.  This code is borrowed from Gisle Aas' URI::Escape
-# module.  For something so simple, I can't see any validation in making
-# the user install the URI modules just for this, so we cut and paste.
-#
-# URI::Escape is Copyright 1995-2000 Gisle Aas.
-#------------------------------------------------------------------------
-
-sub uri_filter {
-    my $text = shift;
-
-    # construct and cache a lookup table for escapes (faster than
-    # doing a sprintf() for every character in every string each 
-    # time)
-    $URI_ESCAPES ||= {
-        map { ( chr($_), sprintf("%%%02X", $_) ) } (0..255),
-    };
-    
-    $text =~ s/([^;\/?:@&=+\$,A-Za-z0-9\-_.!~*'()])/$URI_ESCAPES->{$1}/g;
-    $text;
-}
-
-
-#------------------------------------------------------------------------
-# html_filter()                                         [% FILTER html %]
-#
-# Convert any '<', '>' or '&' characters to the HTML equivalents, '&lt;',
-# '&gt;' and '&amp;', respectively. 
-#------------------------------------------------------------------------
-
-sub html_filter {
-    my $text = shift;
-    for ($text) {
-        s/&/&amp;/g;
-        s/</&lt;/g;
-        s/>/&gt;/g;
-        s/"/&quot;/g;
-    }
-    return $text;
-}
-
-
-#------------------------------------------------------------------------
-# html_paragraph()                                 [% FILTER html_para %]
-#
-# Wrap each paragraph of text (delimited by two or more newlines) in the
-# <p>...</p> HTML tags.
-#------------------------------------------------------------------------
-
-sub html_paragraph  {
-    my $text = shift;
-    return "<p>\n" 
-           . join("\n</p>\n\n<p>\n", split(/(?:\r?\n){2,}/, $text))
-           . "</p>\n";
-}
-
-
-#------------------------------------------------------------------------
-# html_para_break()                          [% FILTER html_para_break %]
-#                                               
-# Join each paragraph of text (delimited by two or more newlines) with
-# <br><br> HTML tags.
-#------------------------------------------------------------------------
-
-sub html_para_break  {
-    my $text = shift;
-    $text =~ s|(\r?\n){2,}|$1<br />$1<br />$1|g;
-    return $text;
-}
-
-#------------------------------------------------------------------------
-# html_line_break()                          [% FILTER html_line_break %]
-#
-# replaces any newlines with <br> HTML tags.
-#------------------------------------------------------------------------
-
-sub html_line_break  {
-    my $text = shift;
-    $text =~ s|(\r?\n)|<br />$1|g;
-    return $text;
-}
-
-#========================================================================
-#                    -- DYNAMIC FILTER FACTORIES --
-#========================================================================
-
-#------------------------------------------------------------------------
-# html_entity_filter_factory(\%options)                 [% FILTER html %]
-#
-# Dynamic version of the static html filter which attempts to locate the
-# Apache::Util or HTML::Entities modules to perform full entity encoding
-# of the text passed.  Returns an exception if one or other of the 
-# modules can't be located.
-#------------------------------------------------------------------------
-
-sub html_entity_filter_factory {
-    my $context = shift;
-
-    # if Apache::Util is installed then we use it
-    eval { 
-        require Apache::Util;
-        Apache::Util::escape_html('');
-    };
-    return \&Apache::Util::escape_html
-        unless $@;
-
-    # otherwise if HTML::Entities is installed then we use that
-    eval {
-        require HTML::Entities;
-    };
-    return \&HTML::Entities::encode_entities
-        unless $@;
-
-    return (undef, Template::Exception->new( html_entity => 
-                    'cannot locate Apache::Util or HTML::Entities' ));
-
-}
-
-
-#------------------------------------------------------------------------
-# indent_filter_factory($pad)                    [% FILTER indent(pad) %]
-#
-# Create a filter to indent text by a fixed pad string or when $pad is
-# numerical, a number of space. 
-#------------------------------------------------------------------------
-
-sub indent_filter_factory {
-    my ($context, $pad) = @_;
-    $pad = 4 unless defined $pad;
-    $pad = ' ' x $pad if $pad =~ /^\d+$/;
-
-    return sub {
-        my $text = shift;
-        $text = '' unless defined $text;
-        $text =~ s/^/$pad/mg;
-        return $text;
-    }
-}
-
-#------------------------------------------------------------------------
-# format_filter_factory()                     [% FILTER format(format) %]
-#
-# Create a filter to format text according to a printf()-like format
-# string.
-#------------------------------------------------------------------------
-
-sub format_filter_factory {
-    my ($context, $format) = @_;
-    $format = '%s' unless defined $format;
-
-    return sub {
-        my $text = shift;
-        $text = '' unless defined $text;
-        return join("\n", map{ sprintf($format, $_) } split(/\n/, $text));
-    }
-}
-
-
-#------------------------------------------------------------------------
-# repeat_filter_factory($n)                        [% FILTER repeat(n) %]
-#
-# Create a filter to repeat text n times.
-#------------------------------------------------------------------------
-
-sub repeat_filter_factory {
-    my ($context, $iter) = @_;
-    $iter = 1 unless defined $iter and length $iter;
-
-    return sub {
-        my $text = shift;
-        $text = '' unless defined $text;
-        return join('\n', $text) x $iter;
-    }
-}
-
-
-#------------------------------------------------------------------------
-# replace_filter_factory($s, $r)    [% FILTER replace(search, replace) %]
-#
-# Create a filter to replace 'search' text with 'replace'
-#------------------------------------------------------------------------
-
-sub replace_filter_factory {
-    my ($context, $search, $replace) = @_;
-    $search = '' unless defined $search;
-    $replace = '' unless defined $replace;
-
-    return sub {
-        my $text = shift;
-        $text = '' unless defined $text;
-        $text =~ s/$search/$replace/g;
-        return $text;
-    }
-}
-
-
-#------------------------------------------------------------------------
-# remove_filter_factory($text)                  [% FILTER remove(text) %]
-#
-# Create a filter to remove 'search' string from the input text.
-#------------------------------------------------------------------------
-
-sub remove_filter_factory {
-    my ($context, $search) = @_;
-
-    return sub {
-        my $text = shift;
-        $text = '' unless defined $text;
-        $text =~ s/$search//g;
-        return $text;
-    }
-}
-
-
-#------------------------------------------------------------------------
-# truncate_filter_factory($n)                    [% FILTER truncate(n) %]
-#
-# Create a filter to truncate text after n characters.
-#------------------------------------------------------------------------
-
-sub truncate_filter_factory {
-    my ($context, $len) = @_;
-    $len = 32 unless defined $len;
-
-    return sub {
-        my $text = shift;
-        return $text if length $text < $len;
-        return substr($text, 0, $len - 3) . "...";
-    }
-}
-
-
-#------------------------------------------------------------------------
-# eval_filter_factory                                   [% FILTER eval %]
-# 
-# Create a filter to evaluate template text.
-#------------------------------------------------------------------------
-
-sub eval_filter_factory {
-    my $context = shift;
-
-    return sub {
-        my $text = shift;
-        $context->process(\$text);
-    }
-}
-
-
-#------------------------------------------------------------------------
-# perl_filter_factory                                   [% FILTER perl %]
-# 
-# Create a filter to process Perl text iff the context EVAL_PERL flag 
-# is set.
-#------------------------------------------------------------------------
-
-sub perl_filter_factory {
-    my $context = shift;
-    my $stash = $context->stash;
-
-    return (undef, Template::Exception->new('perl', 'EVAL_PERL is not set'))
-        unless $context->eval_perl();
-
-    return sub {
-        my $text = shift;
-        local($Template::Perl::context) = $context;
-        local($Template::Perl::stash)   = $stash;
-        my $out = eval <<EOF;
-package Template::Perl; 
-\$stash = \$context->stash(); 
-$text
-EOF
-        $context->throw($@) if $@;
-        return $out;
-    }
-}
-
-
-#------------------------------------------------------------------------
-# redirect_filter_factory($context, $file)    [% FILTER redirect(file) %]
-#
-# Create a filter to redirect the block text to a file.
-#------------------------------------------------------------------------
-
-sub redirect_filter_factory {
-    my ($context, $file, $options) = @_;
-    my $outpath = $context->config->{ OUTPUT_PATH };
-
-    return (undef, Template::Exception->new('redirect', 
-                                            'OUTPUT_PATH is not set'))
-        unless $outpath;
-
-    $options = { binmode => $options } unless ref $options;
-
-    sub {
-        my $text = shift;
-        my $outpath = $context->config->{ OUTPUT_PATH }
-            || return '';
-        $outpath .= "/$file";
-        my $error = Template::_output($outpath, \$text, $options);
-        die Template::Exception->new('redirect', $error)
-            if $error;
-        return '';
-    }
-}
-
-
-#------------------------------------------------------------------------
-# stdout_filter_factory($context, $binmode)    [% FILTER stdout(binmode) %]
-#
-# Create a filter to print a block to stdout, with an optional binmode.
-#------------------------------------------------------------------------
-
-sub stdout_filter_factory {
-    my ($context, $options) = @_;
-
-    $options = { binmode => $options } unless ref $options;
-
-    sub {
-        my $text = shift;
-        binmode(STDOUT) if $options->{ binmode };
-        print STDOUT $text;
-        return '';
-    }
-}
-
-
-#------------------------------------------------------------------------
-# latex_filter_factory($context, $outputType)   [% FILTER latex(outputType) %]
-#
-# Return a filter sub that converts a (hopefully) complete LaTeX source
-# file to either "ps", "dvi", or "pdf".  Output type should be "ps", "dvi"
-# or "pdf" (pdf is default).
-#
-# Creates a temporary directory below File::Spec->tmpdir() (often /tmp)
-# and writes the text into doc.tex. It then runs either pdflatex or
-# latex and optionally dvips. Based on the exit status either returns
-# the entire doc.(pdf|ps|dvi) output or throws an error with a summary
-# of the error messages from doc.log.
-#
-# Written by Craig Barratt, Apr 28 2001.
-# Win32 additions by Richard Tietjen.
-#------------------------------------------------------------------------
-use File::Path;
-use File::Spec;
-use Cwd;
-
-sub latex_filter_factory
-{
-    my($context, $output) = @_;
-
-    $output = lc($output);
-    my $fName = "latex";
-    my($LaTeXPath, $PdfLaTeXPath, $DviPSPath)
-                        = @{Template::Config->latexpaths()};
-    if ( $output eq "ps" || $output eq "dvi" ) {
-        $context->throw($fName,
-                "latex not installed (see Template::Config::LATEX_PATH)")
-                                if ( $LaTeXPath eq "" );
-    } else {
-        $output = "pdf";
-        $LaTeXPath = $PdfLaTeXPath;
-        $context->throw($fName,
-                "pdflatex not installed (see Template::Config::PDFLATEX_PATH)")
-                                if ( $LaTeXPath eq "" );
-    }
-    if ( $output eq "ps" && $DviPSPath eq "" ) {
-        $context->throw($fName,
-                "dvips not installed (see Template::Config::DVIPS_PATH)");
-    }
-    if ( $^O !~ /^(MacOS|os2|VMS)$/i ) {
-        return sub {
-            local(*FH);
-            my $text = shift;
-            my $tmpRootDir = File::Spec->tmpdir();
-            my $cnt = 0;
-            my($tmpDir, $fileName, $devnull);
-            my $texDoc = 'doc';
-
-            do {
-                $tmpDir = File::Spec->catdir($tmpRootDir,
-                                             "tt2latex$$" . "_$cnt");
-                $cnt++;
-            } while ( -e $tmpDir );
-            mkpath($tmpDir, 0, 0700);
-            $context->throw($fName, "can't create temp dir $tmpDir")
-                    if ( !-d $tmpDir );
-            $fileName = File::Spec->catfile($tmpDir, "$texDoc.tex");
-            $devnull  = File::Spec->devnull();
-            if ( !open(FH, ">$fileName") ) {
-                rmtree($tmpDir);
-                $context->throw($fName, "can't open $fileName for output");
-            }
-            print(FH $text);
-            close(FH);
-
-            # latex must run in tmpDir directory
-            my $currDir = cwd();
-            if ( !chdir($tmpDir) ) {
-                rmtree($tmpDir);
-                $context->throw($fName, "can't chdir $tmpDir");
-            }
-            #
-            # We don't need to quote the backslashes on windows, but we
-            # do on other OSs
-            #
-            my $LaTeX_arg = "\\nonstopmode\\input{$texDoc}";
-            $LaTeX_arg = "'$LaTeX_arg'" if ( $^O ne 'MSWin32' );
-            if ( system("$LaTeXPath $LaTeX_arg"
-                   . " 1>$devnull 2>$devnull 0<$devnull") ) {
-                my $texErrs = "";
-                $fileName = File::Spec->catfile($tmpDir, "$texDoc.log");
-                if ( open(FH, "<$fileName") ) {
-                    my $state = 0;
-                    #
-                    # Try to extract just the interesting errors from
-                    # the verbose log file
-                    #
-                    while ( <FH> ) {
-                        #
-                        # TeX errors seems to start with a "!" at the
-                        # start of the line, and are followed several
-                        # lines later by a line designator of the
-                        # form "l.nnn" where nnn is the line number.
-                        # We make sure we pick up every /^!/ line, and
-                        # the first /^l.\d/ line after each /^!/ line.
-                        #
-                        if ( /^(!.*)/ ) {
-                            $texErrs .= $1 . "\n";
-                            $state = 1;
-                        }
-                        if ( $state == 1 && /^(l\.\d.*)/ ) {
-                            $texErrs .= $1 . "\n";
-                            $state = 0;
-                        }
-                    }
-                    close(FH);
-                } else {
-                    $texErrs = "Unable to open $fileName\n";
-                }
-                my $ok = chdir($currDir);
-                rmtree($tmpDir);
-                $context->throw($fName, "can't chdir $currDir") if ( !$ok );
-                $context->throw($fName, "latex exited with errors:\n$texErrs");
-            }
-            if ( $output eq "ps" ) {
-                $fileName = File::Spec->catfile($tmpDir, "$texDoc.dvi");
-                if ( system("$DviPSPath $texDoc -o"
-                       . " 1>$devnull 2>$devnull 0<$devnull") ) {
-                    my $ok = chdir($currDir);
-                    rmtree($tmpDir);
-                    $context->throw($fName, "can't chdir $currDir") if ( !$ok );
-                    $context->throw($fName, "can't run $DviPSPath $fileName");
-                }
-            }
-            if ( !chdir($currDir) ) {
-                rmtree($tmpDir);
-                $context->throw($fName, "can't chdir $currDir");
-            }
-
-            my $retStr;
-            $fileName = File::Spec->catfile($tmpDir, "$texDoc.$output");
-            if ( open(FH, $fileName) ) {
-                local $/ = undef;       # slurp file in one go
-                binmode(FH);
-                $retStr = <FH>;
-                close(FH);
-            } else {
-                rmtree($tmpDir);
-                $context->throw($fName, "Can't open output file $fileName");
-            }
-            rmtree($tmpDir);
-            return $retStr;
-        }
-    } else {
-        $context->throw("$fName not yet supported on $^O OS."
-                      . "  Please contribute code!!");
-    }
-}
-
-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::Filters - Post-processing filters for template blocks
-
-=head1 SYNOPSIS
-
-    use Template::Filters;
-
-    $filters = Template::Filters->new(\%config);
-
-    ($filter, $error) = $filters->fetch($name, \@args, $context);
-
-=head1 DESCRIPTION
-
-The Template::Filters module implements a provider for creating and/or
-returning subroutines that implement the standard filters.  Additional 
-custom filters may be provided via the FILTERS options.
-
-=head1 METHODS
-
-=head2 new(\%params) 
-
-Constructor method which instantiates and returns a reference to a
-Template::Filters object.  A reference to a hash array of configuration
-items may be passed as a parameter.  These are described below.  
-
-    my $filters = Template::Filters->new({
-        FILTERS => { ... },
-    });
-
-    my $template = Template->new({
-        LOAD_FILTERS => [ $filters ],
-    });
-
-A default Template::Filters module is created by the Template.pm module
-if the LOAD_FILTERS option isn't specified.  All configuration parameters
-are forwarded to the constructor.
-
-    $template = Template->new({
-        FILTERS => { ... },
-    });
-
-=head2 fetch($name, \@args, $context)
-
-Called to request that a filter of a given name be provided.  The name
-of the filter should be specified as the first parameter.  This should
-be one of the standard filters or one specified in the FILTERS
-configuration hash.  The second argument should be a reference to an
-array containing configuration parameters for the filter.  This may be
-specified as 0, or undef where no parameters are provided.  The third
-argument should be a reference to the current Template::Context
-object.
-
-The method returns a reference to a filter sub-routine on success.  It
-may also return (undef, STATUS_DECLINE) to decline the request, to allow
-delegation onto other filter providers in the LOAD_FILTERS chain of 
-responsibility.  On error, ($error, STATUS_ERROR) is returned where $error
-is an error message or Template::Exception object indicating the error
-that occurred. 
-
-When the TOLERANT option is set, errors are automatically downgraded to
-a STATUS_DECLINE response.
-
-
-=head1 CONFIGURATION OPTIONS
-
-The following list details the configuration options that can be provided
-to the Template::Filters new() constructor.
-
-=over 4
-
-
-
-
-=item FILTERS
-
-The FILTERS option can be used to specify custom filters which can
-then be used with the FILTER directive like any other.  These are
-added to the standard filters which are available by default.  Filters
-specified via this option will mask any standard filters of the same
-name.
-
-The FILTERS option should be specified as a reference to a hash array
-in which each key represents the name of a filter.  The corresponding
-value should contain a reference to an array containing a subroutine
-reference and a flag which indicates if the filter is static (0) or
-dynamic (1).  A filter may also be specified as a solitary subroutine
-reference and is assumed to be static.
-
-    $filters = Template::Filters->new({
-        FILTERS => {
-            'sfilt1' =>   \&static_filter,      # static
-            'sfilt2' => [ \&static_filter, 0 ], # same as above
-            'dfilt1' => [ \&dyanamic_filter_factory, 1 ],
-        },
-    });
-
-Additional filters can be specified at any time by calling the 
-define_filter() method on the current Template::Context object.
-The method accepts a filter name, a reference to a filter 
-subroutine and an optional flag to indicate if the filter is 
-dynamic.
-
-    my $context = $template->context();
-    $context->define_filter('new_html', \&new_html);
-    $context->define_filter('new_repeat', \&new_repeat, 1);
-
-Static filters are those where a single subroutine reference is used
-for all invocations of a particular filter.  Filters that don't accept
-any configuration parameters (e.g. 'html') can be implemented
-statically.  The subroutine reference is simply returned when that
-particular filter is requested.  The subroutine is called to filter
-the output of a template block which is passed as the only argument.
-The subroutine should return the modified text.
-
-    sub static_filter {
-        my $text = shift;
-        # do something to modify $text...
-        return $text;
-    }
-
-The following template fragment:
-
-    [% FILTER sfilt1 %]
-    Blah blah blah.
-    [% END %]
-
-is approximately equivalent to:
-
-    &static_filter("\nBlah blah blah.\n");
-
-Filters that can accept parameters (e.g. 'truncate') should be
-implemented dynamically.  In this case, the subroutine is taken to be
-a filter 'factory' that is called to create a unique filter subroutine
-each time one is requested.  A reference to the current
-Template::Context object is passed as the first parameter, followed by
-any additional parameters specified.  The subroutine should return
-another subroutine reference (usually a closure) which implements the
-filter.
-
-    sub dynamic_filter_factory {
-        my ($context, @args) = @_;
-
-        return sub {
-            my $text = shift;
-            # do something to modify $text...
-            return $text;           
-        }
-    }
-
-The following template fragment:
-
-    [% FILTER dfilt1(123, 456) %] 
-    Blah blah blah
-    [% END %]              
-
-is approximately equivalent to:
-
-    my $filter = &dynamic_filter_factory($context, 123, 456);
-    &$filter("\nBlah blah blah.\n");
-
-See the FILTER directive for further examples.
-
-
-
-
-=item TOLERANT
-
-The TOLERANT flag is used by the various Template Toolkit provider
-modules (Template::Provider, Template::Plugins, Template::Filters) to
-control their behaviour when errors are encountered.  By default, any
-errors are reported as such, with the request for the particular
-resource (template, plugin, filter) being denied and an exception
-raised.  When the TOLERANT flag is set to any true values, errors will
-be silently ignored and the provider will instead return
-STATUS_DECLINED.  This allows a subsequent provider to take
-responsibility for providing the resource, rather than failing the
-request outright.  If all providers decline to service the request,
-either through tolerated failure or a genuine disinclination to
-comply, then a 'E<lt>resourceE<gt> not found' exception is raised.
-
-
-
-
-=item DEBUG
-
-The DEBUG option can be used to enable debugging messages from the
-Template::Filters module by setting it to include the DEBUG_FILTERS
-value.
-
-    use Template::Constants qw( :debug );
-
-    my $template = Template->new({
-	DEBUG => DEBUG_FILTERS | DEBUG_PLUGINS,
-    });
-
-
-
-
-=back
-
-=head1 TEMPLATE TOOLKIT FILTERS
-
-The following standard filters are distributed with the Template Toolkit.
-
-
-
-=head2 format(format)
-
-The 'format' filter takes a format string as a parameter (as per
-printf()) and formats each line of text accordingly.
-
-    [% FILTER format('<!-- %-40s -->') %]
-    This is a block of text filtered 
-    through the above format.
-    [% END %]
-
-output:
-
-    <!-- This is a block of text filtered        -->
-    <!-- through the above format.               -->
-
-=head2 upper
-
-Folds the input to UPPER CASE.
-
-    [% "hello world" FILTER upper %]
-
-output:
-
-    HELLO WORLD
-
-=head2 lower
-
-Folds the input to lower case.
-
-    [% "Hello World" FILTER lower %]
-
-output:
-
-    hello world
-
-=head2 ucfirst
-
-Folds the first character of the input to UPPER CASE.
-
-    [% "hello" FILTER ucfirst %]
-
-output:
-
-    Hello
-
-=head2 lcfirst
-
-Folds the first character of the input to lower case.
-
-    [% "HELLO" FILTER lcfirst %]
-
-output:
-
-    hELLO
-
-=head2 trim
-
-Trims any leading or trailing whitespace from the input text.  Particularly 
-useful in conjunction with INCLUDE, PROCESS, etc., having the same effect
-as the TRIM configuration option.
-
-    [% INCLUDE myfile | trim %]
-
-=head2 collapse
-
-Collapse any whitespace sequences in the input text into a single space.
-Leading and trailing whitespace (which would be reduced to a single space)
-is removed, as per trim.
-
-    [% FILTER collapse %]
-
-       The   cat
-
-       sat    on
-
-       the   mat
-
-    [% END %]
-
-output:
-
-    The cat sat on the mat
-
-=head2 html
-
-Converts the characters 'E<lt>', 'E<gt>' and '&' to '&lt;', '&gt;' and
-'&amp;', respectively, protecting them from being interpreted as
-representing HTML tags or entities.
-
-    [% FILTER html %]
-    Binary "<=>" returns -1, 0, or 1 depending on...
-    [% END %]
-
-output:
-
-    Binary "&lt;=&gt;" returns -1, 0, or 1 depending on...
-
-=head2 html_entity
-
-The html filter is fast and simple but it doesn't encode the full
-range of HTML entities that your text may contain.  The html_entity
-filter uses either the Apache::Util module (which is written in C and
-is therefore faster) or the HTML::Entities module (written in Perl but
-equally as comprehensive) to perform the encoding.  If one or other of
-these modules are installed on your system then the text will be
-encoded (via the escape_html() or encode_entities() subroutines
-respectively) to convert all extended characters into their
-appropriate HTML entities (e.g. converting 'é' to '&eacute;').  If
-neither module is available on your system then an 'html_entity' exception
-will be thrown reporting an appropriate message.   
-
-For further information on HTML entity encoding, see
-http://www.w3.org/TR/REC-html40/sgml/entities.html.
-
-=head2 html_para
-
-This filter formats a block of text into HTML paragraphs.  A sequence of 
-two or more newlines is used as the delimiter for paragraphs which are 
-then wrapped in HTML E<lt>pE<gt>...E<lt>/pE<gt> tags.
-
-    [% FILTER html_para %]
-    The cat sat on the mat.
-
-    Mary had a little lamb.
-    [% END %]
-
-output:
-
-    <p>
-    The cat sat on the mat.
-    </p>
-
-    <p>
-    Mary had a little lamb.
-    </p>
-
-=head2 html_break / html_para_break
-
-Similar to the html_para filter described above, but uses the HTML tag
-sequence E<lt>brE<gt>E<lt>brE<gt> to join paragraphs.
-
-    [% FILTER html_break %]
-    The cat sat on the mat.
-
-    Mary had a little lamb.
-    [% END %]
-
-output:
-
-    The cat sat on the mat.
-    <br>
-    <br>
-    Mary had a little lamb.
-
-=head2 html_line_break
-
-This filter replaces any newlines with E<lt>brE<gt> HTML tags,
-thus preserving the line breaks of the original text in the 
-HTML output.
-
-    [% FILTER html_line_break %]
-    The cat sat on the mat.
-    Mary had a little lamb.
-    [% END %]
-
-output:
-
-    The cat sat on the mat.<br>
-    Mary had a little lamb.<br>
-
-=head2 uri
-
-This filter URI escapes the input text, converting any characters 
-outside of the permitted URI character set (as defined by RFC 2396)
-into a C<%nn> hex escape.
-
-    [% 'my file.html' | uri %]
-
-output:
-
-    my%20file.html
-
-Note that URI escaping isn't always enough when generating hyperlinks in
-an HTML document.  The C<&> character, for example, is valid in a URI and
-will not be escaped by the URI filter.  In this case you should also filter
-the text through the 'html' filter.
-
-    <a href="[% filename | uri | html %]">click here</a>
-
-=head2 indent(pad)
-
-Indents the text block by a fixed pad string or width.  The 'pad' argument
-can be specified as a string, or as a numerical value to indicate a pad
-width (spaces).  Defaults to 4 spaces if unspecified.
-
-    [% FILTER indent('ME> ') %]
-    blah blah blah
-    cabbages, rhubard, onions
-    [% END %]
-
-output:
-
-    ME> blah blah blah
-    ME> cabbages, rhubard, onions
-
-=head2 truncate(length)
-
-Truncates the text block to the length specified, or a default length of
-32.  Truncated text will be terminated with '...' (i.e. the '...' falls
-inside the required length, rather than appending to it).
-
-    [% FILTER truncate(21) %]
-    I have much to say on this matter that has previously 
-    been said on more than one occasion.
-    [% END %]
-
-output:
-
-    I have much to say...
-
-=head2 repeat(iterations)
-
-Repeats the text block for as many iterations as are specified (default: 1).
-
-    [% FILTER repeat(3) %]
-    We want more beer and we want more beer,
-    [% END %]
-    We are the more beer wanters!
-
-output:
-
-    We want more beer and we want more beer,
-    We want more beer and we want more beer,
-    We want more beer and we want more beer,
-    We are the more beer wanters!
-
-=head2 remove(string) 
-
-Searches the input text for any occurrences of the specified string and 
-removes them.  A Perl regular expression may be specified as the search 
-string.
-
-    [% "The  cat  sat  on  the  mat" FILTER remove('\s+') %]
-
-output: 
-
-    Thecatsatonthemat
-
-=head2 replace(search, replace) 
-
-Similar to the remove filter described above, but taking a second parameter
-which is used as a replacement string for instances of the search string.
-
-    [% "The  cat  sat  on  the  mat" | replace('\s+', '_') %]
-
-output: 
-
-    The_cat_sat_on_the_mat
-
-=head2 redirect(file, options)
-
-The 'redirect' filter redirects the output of the block into a separate
-file, specified relative to the OUTPUT_PATH configuration item.
-
-    [% FOREACH user = myorg.userlist %]
-       [% FILTER redirect("users/${user.id}.html") %]
-          [% INCLUDE userinfo %]
-       [% END %]
-    [% END %]
-
-or more succinctly, using side-effect notation:
-
-    [% INCLUDE userinfo 
-         FILTER redirect("users/${user.id}.html")
-	   FOREACH user = myorg.userlist 
-    %]
-
-A 'file' exception will be thrown if the OUTPUT_PATH option is undefined.
-
-An optional 'binmode' argument can follow the filename to explicitly set
-the output file to binary mode.
-
-    [% PROCESS my/png/generator 
-         FILTER redirect("images/logo.png", binmode=1) %]
-
-For backwards compatibility with earlier versions, a single true/false
-value can be used to set binary mode.
-
-    [% PROCESS my/png/generator 
-         FILTER redirect("images/logo.png", 1) %]
-
-For the sake of future compatibility and clarity, if nothing else, we
-would strongly recommend you explicitly use the named 'binmode' option
-as shown in the first example.
-
-=head2 eval / evaltt
-
-The 'eval' filter evaluates the block as template text, processing
-any directives embedded within it.  This allows template variables to
-contain template fragments, or for some method to be provided for
-returning template fragments from an external source such as a
-database, which can then be processed in the template as required.
-
-    my $vars  = {
-	fragment => "The cat sat on the [% place %]",
-    };
-    $template->process($file, $vars);
-
-The following example:
-
-    [% fragment | eval %]
-
-is therefore equivalent to 
-
-    The cat sat on the [% place %]
-
-The 'evaltt' filter is provided as an alias for 'eval'.
-
-=head2 perl / evalperl
-
-The 'perl' filter evaluates the block as Perl code.  The EVAL_PERL
-option must be set to a true value or a 'perl' exception will be
-thrown.
-
-    [% my_perl_code | perl %]
-
-In most cases, the [% PERL %] ... [% END %] block should suffice for 
-evaluating Perl code, given that template directives are processed 
-before being evaluate as Perl.  Thus, the previous example could have
-been written in the more verbose form:
-
-    [% PERL %]
-    [% my_perl_code %]
-    [% END %]
-
-as well as
-
-    [% FILTER perl %]
-    [% my_perl_code %]
-    [% END %]
-
-The 'evalperl' filter is provided as an alias for 'perl' for backwards
-compatibility.
-
-=head2 stdout(options)
-
-The stdout filter prints the output generated by the enclosing block to
-STDOUT.  The 'binmode' option can be passed as either a named parameter
-or a single argument to set STDOUT to binary mode (see the
-binmode perl function).
-
-    [% PROCESS something/cool
-           FILTER stdout(binmode=1) # recommended %]
-
-    [% PROCESS something/cool
-           FILTER stdout(1)         # alternate %]
-
-The stdout filter can be used to force binmode on STDOUT, or also inside
-redirect, null or stderr blocks to make sure that particular output goes
-to stdout. See the null filter below for an example.
-
-=head2 stderr
-
-The stderr filter prints the output generated by the enclosing block to
-STDERR.
-
-=head2 null
-
-The null filter prints nothing.  This is useful for plugins whose
-methods return values that you don't want to appear in the output.
-Rather than assigning every plugin method call to a dummy variable
-to silence it, you can wrap the block in a null filter:
-
-    [% FILTER null;
-        USE im = GD.Image(100,100);
-        black = im.colorAllocate(0,   0, 0);
-        red   = im.colorAllocate(255,0,  0);
-        blue  = im.colorAllocate(0,  0,  255);
-        im.arc(50,50,95,75,0,360,blue);
-        im.fill(50,50,red);
-        im.png | stdout(1);
-       END;
-    -%]
-
-Notice the use of the stdout filter to ensure that a particular expression
-generates output to stdout (in this case in binary mode).
-
-=head2 latex(outputType)
-
-Passes the text block to LaTeX and produces either PDF, DVI or
-PostScript output.  The 'outputType' argument determines the output
-format and it should be set to one of the strings: "pdf" (default),
-"dvi", or "ps".
-
-The text block should be a complete LaTeX source file.
-
-    [% FILTER latex("pdf") -%]
-    \documentclass{article}
-
-    \begin{document}
-
-    \title{A Sample TT2 \LaTeX\ Source File}
-    \author{Craig Barratt}
-    \maketitle
-
-    \section{Introduction}
-    This is some text.
-
-    \end{document}
-    [% END -%]
-
-The output will be a PDF file. You should be careful not to prepend or
-append any extraneous characters or text outside the FILTER block,
-since this text will wrap the (binary) output of the latex filter.
-Notice the END directive uses '-%]' for the END_TAG to remove the
-trailing new line.
-
-One example where you might prepend text is in a CGI script where
-you might include the Content-Type before the latex output, eg:
-
-    Content-Type: application/pdf
-
-    [% FILTER latex("pdf") -%]
-    \documentclass{article}
-    \begin{document}
-    ...
-    \end{document}
-    [% END -%]
-
-In other cases you might use the redirect filter to put the output
-into a file, rather than delivering it to stdout.  This might be
-suitable for batch scripts:
-
-    [% output = FILTER latex("pdf") -%]
-    \documentclass{article}
-    \begin{document}
-    ...
-    \end{document}
-    [% END; output | redirect("document.pdf", 1) -%]
-
-(Notice the second argument to redirect to force binary mode.)
-
-Note that the latex filter runs one or two external programs, so it
-isn't very fast.  But for modest documents the performance is adequate,
-even for interactive applications.
-
-A error of type 'latex' will be thrown if there is an error reported
-by latex, pdflatex or dvips.
-
-=head1 AUTHOR
-
-Andy Wardley E<lt>abw@andywardley.comE<gt>
-
-L<http://www.andywardley.com/|http://www.andywardley.com/>
-
-
-
-
-=head1 VERSION
-
-2.77, distributed as part of the
-Template Toolkit version 2.13, released on 30 January 2004.
-
-=head1 COPYRIGHT
-
-  Copyright (C) 1996-2004 Andy Wardley.  All Rights Reserved.
-  Copyright (C) 1998-2002 Canon Research Centre Europe Ltd.
-
-This module is free software; you can redistribute it and/or
-modify it under the same terms as Perl itself.
-
-=head1 SEE ALSO
-
-L<Template|Template>, L<Template::Context|Template::Context>, L<Template::Manual::Filters|Template::Manual::Filters>
-
-=cut
-
-# Local Variables:
-# mode: perl
-# perl-indent-level: 4
-# indent-tabs-mode: nil
-# End:
-#
-# vim: expandtab shiftwidth=4: