Gecko [ www.vortexaion.com ]

Name	Size	Permission	Date
Algorithm	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Alien	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Alt	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Apache	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
App	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
AppConfig	[ DIR ]	drwxrwxrwx	2024-07-26 17:40
Archive	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Authen	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
B	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
BerkeleyDB	[ DIR ]	drwxrwxrwx	2024-07-26 17:40
Bundle	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Bytes	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
CGI	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
CPAN	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
CPANPLUS	[ DIR ]	drwxrwxrwx	2024-07-26 17:40
Canary	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Capture	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Carp	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Class	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Clone	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Compress	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Config	[ DIR ]	drwxrwxrwx	2024-07-26 17:40
Context	[ DIR ]	drwxrwxrwx	2024-07-26 17:40
Convert	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Cpanel	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Crypt	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
DBD	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
DBI	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
DBIx	[ DIR ]	drwxrwxrwx	2024-07-26 17:40
DBM	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Dancer	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Dancer2	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Data	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Date	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
DateTime	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Devel	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Digest	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Dist	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Email	[ DIR ]	drwxrwxrwx	2024-07-26 17:40
Encode	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Eval	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Excel	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Exception	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Exporter	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
ExtUtils	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
FFI	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
File	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
GD	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Graphics	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
HTML	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
HTTP	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Hash	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Hook	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
IO	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
IPC	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Imager	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
JSON	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
LWP	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
List	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Log	[ DIR ]	drwxrwxrwx	2024-07-26 17:40
MIME	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Mail	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Math	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Method	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Mock	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Modern	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Module	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Mojo	[ DIR ]	drwxrwxrwx	2024-07-26 17:40
MojoX	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Mojolicious	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Moo	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
MooX	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Moose	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
MooseX	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Mozilla	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Net	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Number	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
OLE	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Object	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
OpenGL	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
PAR	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
POD2	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
PPI	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
PPM	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Package	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Params	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Parse	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Path	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Perl	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
PerlIO	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Pod	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Portable	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Probe	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Role	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
SOAP	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
SQL	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Scope	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Sort	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Specio	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Spiffy	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Spreadsheet	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
StackTrace	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
String	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Sub	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Syntax	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Sys	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
TAP	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Task	[ DIR ]	drwxrwxrwx	2024-07-26 17:40
Template	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Term	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Test	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Test2	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Text	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Throwable	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Tie	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Time	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Tree	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Types	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
Unicode	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Variable	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
WWW	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Win32	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
Win32API	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
XML	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
YAML	[ DIR ]	drwxrwxrwx	2024-07-26 17:40
auto	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
common	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
lib	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
libwww	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
local	[ DIR ]	drwxrwxrwx	2024-07-26 17:38
namespace	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
odern	[ DIR ]	drwxrwxrwx	2024-07-26 17:39
AppConfig.pm	31.7 KB	-rw-rw-rw-	2015-03-02 00:23
BerkeleyDB.pm	42.09 KB	-rw-rw-rw-	2020-09-17 12:21
BerkeleyDB.pod	80.17 KB	-rw-rw-rw-	2020-09-17 11:57
CGI.pm	122.63 KB	-rw-rw-rw-	2020-09-25 17:21
CGI.pod	66.13 KB	-rw-rw-rw-	2020-06-22 11:29
CPANPLUS.pm	7.05 KB	-rw-rw-rw-	2020-12-19 12:30
Clone.pm	2.29 KB	-rw-rw-rw-	2020-04-24 00:46
CryptX.pm	4.69 KB	-rw-rw-rw-	2020-08-25 11:02
DBI.pm	310.74 KB	-rw-rw-rw-	2020-01-31 17:27
DB_File.pm	67.74 KB	-rw-rw-rw-	2021-01-24 16:36
DDP.pm	530 B	-rw-rw-rw-	2015-05-30 02:50
DateTime.pm	132.7 KB	-rw-rw-rw-	2020-12-05 00:20
FCGI.pm	5.72 KB	-rw-rw-rw-	2019-12-14 20:22
Fh.pm	166 B	-rw-rw-rw-	2020-09-25 17:20
GD.pm	67.49 KB	-rw-rw-rw-	2020-09-24 16:52
Imager.pm	124.3 KB	-rw-rw-rw-	2020-06-14 07:15
Importer.pm	41.53 KB	-rw-rw-rw-	2020-08-17 01:24
JSON.pm	61.08 KB	-rw-rw-rw-	2021-01-24 02:09
LWP.pm	21.17 KB	-rw-rw-rw-	2021-01-07 23:21
MailTools.pm	458 B	-rw-rw-rw-	2019-05-21 18:26
MailTools.pod	2.24 KB	-rw-rw-rw-	2019-05-21 18:26
Mojo.pm	1.61 KB	-rw-rw-rw-	2021-01-17 16:56
Mojolicious.pm	29.21 KB	-rw-rw-rw-	2021-01-17 16:57
Moo.pm	33.61 KB	-rw-rw-rw-	2020-11-25 02:58
Moose.pm	38.63 KB	-rw-rw-rw-	2020-12-19 02:06
OLE.pm	4.28 KB	-rw-rw-rw-	2013-11-28 21:21
OpenGL.pm	140.62 KB	-rw-rw-rw-	2016-10-08 23:11
OpenGL.pod	37.33 KB	-rw-rw-rw-	2016-10-08 23:12
PAR.pm	40.34 KB	-rw-rw-rw-	2019-05-25 01:14
PPI.pm	29.52 KB	-rw-rw-rw-	2019-07-09 19:15
PPM.pm	75.77 KB	-rw-rw-rw-	2020-02-07 11:26
PadWalker.pm	4.1 KB	-rw-rw-rw-	2020-09-27 16:22
PkgConfig.pm	46.95 KB	-rw-rw-rw-	2020-11-11 12:32
Portable.pm	6.49 KB	-rw-rw-rw-	2020-02-07 22:46
Socket6.pm	9.55 KB	-rw-rw-rw-	2018-09-30 08:22
Specio.pm	14.83 KB	-rw-rw-rw-	2020-03-14 19:47
Spiffy.pm	15.12 KB	-rw-rw-rw-	2014-08-16 23:19
Spiffy.pod	17.75 KB	-rw-rw-rw-	2014-08-16 23:19
Template.pm	24.46 KB	-rw-rw-rw-	2020-07-14 01:47
Throwable.pm	4.4 KB	-rw-rw-rw-	2015-07-01 17:46
TimeDate.pm	267 B	-rw-rw-rw-	2020-05-19 21:30
V.pm	4.18 KB	-rw-rw-rw-	2007-11-07 02:08
XString.pm	1.76 KB	-rw-rw-rw-	2020-10-20 21:56
YAML.pm	3.12 KB	-rw-rw-rw-	2020-01-28 00:10
YAML.pod	22.62 KB	-rw-rw-rw-	2020-01-28 00:10
aliased.pm	9.98 KB	-rw-rw-rw-	2015-01-03 22:39
alienfile.pm	15.78 KB	-rw-rw-rw-	2021-01-11 23:36
dbixs_rev.pl	1.5 KB	-rw-rw-rw-	2013-04-05 02:17
enum.pm	10.63 KB	-rw-rw-rw-	2015-10-27 23:37
metaclass.pm	3.23 KB	-rw-rw-rw-	2020-12-19 02:06
mkconsts.pl	38.4 KB	-rw-rw-rw-	2019-02-05 22:12
ntheory.pm	14.33 KB	-rw-rw-rw-	2018-11-15 20:49
ojo.pm	7.04 KB	-rw-rw-rw-	2021-01-17 16:57
oo.pm	1.19 KB	-rw-rw-rw-	2020-09-02 14:16
oose.pm	2.62 KB	-rw-rw-rw-	2020-12-19 02:06
pler.pm	9.76 KB	-rw-rw-rw-	2010-11-29 09:50
ppm.xml	600 B	-rw-rw-rw-	2023-11-19 11:41
scan.pl	5.68 KB	-rw-rw-rw-	2019-02-05 22:12
superclass.pm	3.71 KB	-rw-rw-rw-	2014-03-11 12:54
syntax.pm	4.24 KB	-rw-rw-rw-	2012-05-18 22:47

Rename

#============================================================= -*-perl-*-
#
# Template
#
# DESCRIPTION
#   Module implementing a simple, user-oriented front-end to the Template
#   Toolkit.
#
# AUTHOR
#   Andy Wardley   <abw@wardley.org>
#
# COPYRIGHT
#   Copyright (C) 1996-2020 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.
#
#========================================================================

package Template;

use strict;
use warnings;
use 5.006;
use base 'Template::Base';

use Template::Config;
use Template::Constants;
use Template::Provider;
use Template::Service;
use File::Basename;
use File::Path;
use Scalar::Util qw(blessed);

our $VERSION = '3.009';
our $ERROR   = '';
our $DEBUG   = 0;
our $BINMODE = 0 unless defined $BINMODE;
our $AUTOLOAD;

# preload all modules if we're running under mod_perl
Template::Config->preload() if $ENV{ MOD_PERL };

#------------------------------------------------------------------------
# process($input, \%replace, $output)
#
# Main entry point for the Template Toolkit.  The Template module
# delegates most of the processing effort to the underlying SERVICE
# object, an instance of the Template::Service class.
#------------------------------------------------------------------------

sub process {
    my ($self, $template, $vars, $outstream, @opts) = @_;
    my ($output, $error);
    my $options = (@opts == 1) && ref($opts[0]) eq 'HASH'
        ? shift(@opts) : { @opts };

$options->{ binmode } = $BINMODE
        unless defined $options->{ binmode };

# we're using this for testing in t/output.t and t/filter.t so
    # don't remove it if you don't want tests to fail...
    $self->DEBUG("set binmode\n") if $DEBUG && $options->{ binmode };

$output = $self->{ SERVICE }->process($template, $vars);

if (defined $output) {
        $outstream ||= $self->{ OUTPUT };
        unless (ref $outstream) {
            my $outpath = $self->{ OUTPUT_PATH };
            $outstream = "$outpath/$outstream" if $outpath;
        }

# send processed template to output stream, checking for error
        return ($self->error($error))
            if ($error = &_output($outstream, \$output, $options));

return 1;
    }
    else {
        return $self->error($self->{ SERVICE }->error);
    }
}

#------------------------------------------------------------------------
# service()
#
# Returns a reference to the internal SERVICE object which handles
# all requests for this Template object
#------------------------------------------------------------------------

sub service {
    my $self = shift;
    return $self->{ SERVICE };
}

#------------------------------------------------------------------------
# context()
#
# Returns a reference to the CONTEXT object within the SERVICE
# object.
#------------------------------------------------------------------------

sub context {
    my $self = shift;
    return $self->{ SERVICE }->{ CONTEXT };
}

sub template {
    shift->context->template(@_);
}

#========================================================================
#                     -- PRIVATE METHODS --
#========================================================================

#------------------------------------------------------------------------
# _init(\%config)
#------------------------------------------------------------------------
sub _init {
    my ($self, $config) = @_;

# convert any textual DEBUG args to numerical form
    my $debug = $config->{ DEBUG };
    $config->{ DEBUG } = Template::Constants::debug_flags($self, $debug)
        || return if defined $debug && $debug !~ /^\d+$/;

# prepare a namespace handler for any CONSTANTS definition
    if (my $constants = $config->{ CONSTANTS }) {
        my $ns  = $config->{ NAMESPACE } ||= { };
        my $cns = $config->{ CONSTANTS_NAMESPACE } || 'constants';
        $constants = Template::Config->constants($constants)
            || return $self->error(Template::Config->error);
        $ns->{ $cns } = $constants;
    }

$self->{ SERVICE } = $config->{ SERVICE }
        || Template::Config->service($config)
        || return $self->error(Template::Config->error);

$self->{ OUTPUT      } = $config->{ OUTPUT } || \*STDOUT;
    $self->{ OUTPUT_PATH } = $config->{ OUTPUT_PATH };

return $self;
}

#------------------------------------------------------------------------
# _output($where, $text)
#------------------------------------------------------------------------

sub _output {
    my ($where, $textref, $options) = @_;
    my $reftype;
    my $error = 0;

# call a CODE reference
    if (($reftype = ref($where)) eq 'CODE') {
        &$where($$textref);
    }
    # print to a glob (such as \*STDOUT)
    elsif ($reftype eq 'GLOB') {
        print $where $$textref;
    }
    # append output to a SCALAR ref
    elsif ($reftype eq 'SCALAR') {
        $$where .= $$textref;
    }
    # push onto ARRAY ref
    elsif ($reftype eq 'ARRAY') {
        push @$where, $$textref;
    }
    # call the print() method on an object that implements the method
    # (e.g. IO::Handle, Apache::Request, etc)
    elsif (blessed($where) && $where->can('print')) {
        $where->print($$textref);
    }
    # a simple string is taken as a filename
    elsif (! $reftype) {
        local *FP;
        # make destination directory if it doesn't exist
        my $dir = dirname($where);
        eval { mkpath($dir) unless -d $dir; };
        if ($@) {
            # strip file name and line number from error raised by die()
            ($error = $@) =~ s/ at \S+ line \d+\n?$//;
        }
        elsif (open(FP, '>', $where)) {
            # binmode option can be 1 or a specific layer, e.g. :utf8
            my $bm = $options->{ binmode  };
            if ($bm && $bm eq 1) {
                binmode FP;
            }
            elsif ($bm){
                binmode FP, $bm;
            }
            print FP $$textref;
            close FP;
        }
        else {
            $error  = "$where: $!";
        }
    }
    # give up, we've done our best
    else {
        $error = "output_handler() cannot determine target type ($where)\n";
    }

return $error;
}

__END__

=head1 NAME

Template - Front-end module to the Template Toolkit

=head1 SYNOPSIS

use Template;

# some useful options (see below for full list)
    my $config = {
        INCLUDE_PATH => '/search/path',  # or list ref
        INTERPOLATE  => 1,               # expand "$var" in plain text
        POST_CHOMP   => 1,               # cleanup whitespace
        PRE_PROCESS  => 'header',        # prefix each template
        EVAL_PERL    => 1,               # evaluate Perl code blocks
    };

# create Template object
    my $template = Template->new($config);

# define template variables for replacement
    my $vars = {
        var1  => $value,
        var2  => \%hash,
        var3  => \@list,
        var4  => \&code,
        var5  => $object,
    };

# specify input filename, or file handle, text reference, etc.
    my $input = 'myfile.html';

# process input template, substituting variables
    $template->process($input, $vars)
        || die $template->error();

=head1 DESCRIPTION

This documentation describes the Template module which is the direct
Perl interface into the Template Toolkit.  It covers the use of the
module and gives a brief summary of configuration options and template
directives.  Please see L<Template::Manual> for the complete reference
manual which goes into much greater depth about the features and use
of the Template Toolkit.  The L<Template::Tutorial> is also available
as an introductory guide to using the Template Toolkit.

=head1 METHODS

=head2 new(\%config)

The C<new()> constructor method (implemented by the
L<Template::Base|Template::Base#new()> base class) instantiates a new
C<Template> object. A reference to a hash array of configuration items may be
passed as a parameter.

my $tt = Template->new({
        INCLUDE_PATH => '/usr/local/templates',
        EVAL_PERL    => 1,
    }) || die $Template::ERROR, "\n";

A reference to a new C<Template> object is returned, or undef on error. In the
latter case, the error message can be retrieved by calling L<error()> as a
class method or by examining the C<$Template::ERROR> package variable
directly.

my $tt = Template->new(\%config)
        || die Template->error(), "\n";

my $tt = Template->new(\%config)
        || die $Template::ERROR, "\n";

For convenience, configuration items may also be specified as a list
of items instead of a hash array reference.  These are automatically
folded into a hash array by the constructor.

my $tt = Template->new(INCLUDE_PATH => '/tmp', POST_CHOMP => 1)
        || die $Template::ERROR, "\n";

=head2 process($template, \%vars, $output, %options)

The C<process()> method is called to process a template. The first parameter
indicates the input template as one of: a filename relative to
C<INCLUDE_PATH>, if defined; a reference to a text string containing the
template text; or a file handle reference (e.g. C<IO::Handle> or sub-class) or
C<GLOB> (e.g. C<\*STDIN>), from which the template can be read. A reference to
a hash array may be passed as the second parameter, containing definitions of
template variables.

# filename
    $tt->process('welcome.tt2')
        || die $tt->error(), "\n";

# text reference
    $text = "[% INCLUDE header %]\nHello world!\n[% INCLUDE footer %]";
    $tt->process(\$text)
        || die $tt->error(), "\n";

# file handle (GLOB)
    $tt->process(\*DATA)
        || die $tt->error(), "\n";

__END__
    [% INCLUDE header %]
    This is a template defined in the __END__ section which is
    accessible via the DATA "file handle".
    [% INCLUDE footer %]

By default, the processed template output is printed to C<STDOUT>. The
C<process()> method then returns C<1> to indicate success. A third parameter
may be passed to the C<process()> method to specify a different output location.
This value may be one of: a plain string indicating a filename which will be
opened (relative to C<OUTPUT_PATH>, if defined) and the output written to; a file
GLOB opened ready for output; a reference to a scalar (e.g. a text string) to
which output/error is appended; a reference to a subroutine which is called,
passing the output as a parameter; or any object reference which implements a
C<print()> method (e.g. C<IO::Handle>, C<Apache::Request>, etc.) which will be called,
passing the generated output as a parameter.

Examples:

# output filename
    $tt->process('welcome.tt2', $vars, 'welcome.html')
        || die $tt->error(), "\n";

# reference to output subroutine
    sub myout {
        my $output = shift;
        ...
    }
    $tt->process('welcome.tt2', $vars, \&myout)
        || die $tt->error(), "\n";

# reference to output text string
    my $output = '';
    $tt->process('welcome.tt2', $vars, \$output)
        || die $tt->error(), "\n";

print "output: $output\n";

In an Apache/mod_perl handler:

sub handler {
        my $req = shift;

# ...your code here...

# direct output to Apache::Request via $req->print($output)
        $tt->process($file, $vars, $req) || do {
            $req->log_reason($tt->error());
            return SERVER_ERROR;
        };
        return OK;
    }

After the optional third output argument can come an optional
reference to a hash or a list of C<(name, value)> pairs providing further
options for the output.  The only option currently supported is
C<binmode> which, when set to any true value will ensure that files
created (but not any existing file handles passed) will be set to
binary mode.

# either: hash reference of options
    $tt->process($infile, $vars, $outfile, { binmode => 1 })
        || die $tt->error(), "\n";

# or: list of name, value pairs
    $tt->process($infile, $vars, $outfile, binmode => 1)
        || die $tt->error(), "\n";

Alternately, the C<binmode> argument can specify a particular IO layer such
as C<:utf8>.

$tt->process($infile, $vars, $outfile, binmode => ':utf8')
        || die $tt->error(), "\n";

The C<OUTPUT> configuration item can be used to specify a default output
location other than C<\*STDOUT>.  The C<OUTPUT_PATH> specifies a directory
which should be prefixed to all output locations specified as filenames.

my $tt = Template->new({
        OUTPUT      => sub { ... },       # default
        OUTPUT_PATH => '/tmp',
    ...
    }) || die Template->error(), "\n";

# use default OUTPUT (sub is called)
    $tt->process('welcome.tt2', $vars)
        || die $tt->error(), "\n";

# write file to '/tmp/welcome.html'
    $tt->process('welcome.tt2', $vars, 'welcome.html')
        || die $tt->error(), "\n";

The C<process()> method returns C<1> on success or C<undef> on error. The
error message generated in the latter case can be retrieved by calling the
L<error()> method. See also L<CONFIGURATION SUMMARY> which describes how error
handling may be further customised.

=head2 error()

When called as a class method, it returns the value of the C<$ERROR> package
variable.  Thus, the following are equivalent.

my $tt = Template->new()
        || die Template->error(), "\n";

my $tt = Template->new()
        || die $Template::ERROR, "\n";

When called as an object method, it returns the value of the internal
C<_ERROR> variable, as set by an error condition in a previous call to
process().

$tt->process('welcome.tt2')
        || die $tt->error(), "\n";

Errors are represented in the Template Toolkit by objects of the
L<Template::Exception> class. If the L<process()> method returns a false value
then the C<error()> method can be called to return an object of this class.
The L<type()|Template::Exception#type()> and
L<info()|Template::Exception#info()> methods can called on the object to
retrieve the error type and information string, respectively. The
L<as_string()|Template::Exception#as_string()>
method can be called to return a string of the form C<$type - $info>. This
method is also overloaded onto the stringification operator allowing the
object reference itself to be printed to return the formatted error string.

$tt->process('somefile') || do {
        my $error = $tt->error();
        print "error type: ", $error->type(), "\n";
        print "error info: ", $error->info(), "\n";
        print $error, "\n";
    };

=head2 service()

The C<Template> module delegates most of the effort of processing templates
to an underlying L<Template::Service> object.  This method returns a reference
to that object.

=head2 context()

The L<Template::Service> module uses a core L<Template::Context> object for
runtime processing of templates.  This method returns a reference to
that object and is equivalent to C<< $template-E<gt>service-E<gt>context() >>.

=head2 template($name)

This method is a simple wrapper around the L<Template::Context> method of the
same name.  It returns a compiled template for the source provided as an
argument.

=head1 CONFIGURATION SUMMARY

The following list gives a short summary of each Template Toolkit
configuration option.  See L<Template::Manual::Config> for full details.

=head2 Template Style and Parsing Options

=head3 ENCODING

Specifies the character encoding.

=head3 START_TAG, END_TAG

Define tokens that indicate start and end of directives
(default: 'C<[%>' and 'C<%]>').

=head3 TAG_STYLE

Set C<START_TAG> and C<END_TAG> according to a pre-defined style (default:
'C<template>', as above).

=head3 PRE_CHOMP, POST_CHOMP

Removes whitespace before/after directives (default: 0/0).

=head3 TRIM

Remove leading and trailing whitespace from template output (default: 0).

=head3 INTERPOLATE

Interpolate variables embedded like C<$this> or C<${this}> (default: 0).

=head3 ANYCASE

Allow directive keywords in lower case (default: 0 - UPPER only).

=head2 Template Files and Blocks

=head3 INCLUDE_PATH

One or more directories to search for templates.

=head3 DELIMITER

Delimiter for separating paths in C<INCLUDE_PATH> (default: 'C<:>').

=head3 ABSOLUTE

Allow absolute file names, e.g. C</foo/bar.html> (default: 0).

=head3 RELATIVE

Allow relative filenames, e.g. C<../foo/bar.html> (default: 0).

=head3 DEFAULT

Default template to use when another not found.

=head3 BLOCKS

Hash array pre-defining template blocks.

=head3 AUTO_RESET

Enabled by default causing C<BLOCK> definitions to be reset each time a
template is processed.  Disable to allow C<BLOCK> definitions to persist.

=head3 RECURSION

Flag to permit recursion into templates (default: 0).

=head2 Template Variables

=head3 VARIABLES

Hash array of variables and values to pre-define in the stash.

=head2 Runtime Processing Options

=head3 EVAL_PERL

Flag to indicate if C<PERL>/C<RAWPERL> blocks should be processed (default: 0).

=head3 PRE_PROCESS, POST_PROCESS

Name of template(s) to process before/after main template.

=head3 PROCESS

Name of template(s) to process instead of main template.

=head3 ERROR

Name of error template or reference to hash array mapping error types to
templates.

=head3 OUTPUT

Default output location or handler.

=head3 OUTPUT_PATH

Directory into which output files can be written.

=head3 DEBUG

Enable debugging messages.

=head2 Caching and Compiling Options

=head3 CACHE_SIZE

Maximum number of compiled templates to cache in memory (default:
undef - cache all)

=head3 COMPILE_EXT

Filename extension for compiled template files (default: undef - don't
compile).

=head3 COMPILE_DIR

Root of directory in which compiled template files should be written
(default: undef - don't compile).

=head2 Plugins and Filters

=head3 PLUGINS

Reference to a hash array mapping plugin names to Perl packages.

=head3 PLUGIN_BASE

One or more base classes under which plugins may be found.

=head3 LOAD_PERL

Flag to indicate regular Perl modules should be loaded if a named plugin
can't be found  (default: 0).

=head3 FILTERS

Hash array mapping filter names to filter subroutines or factories.

=head2 Customisation and Extension

=head3 LOAD_TEMPLATES

List of template providers.

=head3 LOAD_PLUGINS

List of plugin providers.

=head3 LOAD_FILTERS

List of filter providers.

=head3 TOLERANT

Set providers to tolerate errors as declinations (default: 0).

=head3 SERVICE

Reference to a custom service object (default: L<Template::Service>).

=head3 CONTEXT

Reference to a custom context object (default: L<Template::Context>).

=head3 STASH

Reference to a custom stash object (default: L<Template::Stash>).

=head3 PARSER

Reference to a custom parser object (default: L<Template::Parser>).

=head3 GRAMMAR

Reference to a custom grammar object (default: L<Template::Grammar>).

=head1 DIRECTIVE SUMMARY

The following list gives a short summary of each Template Toolkit directive.
See L<Template::Manual::Directives> for full details.

=head2 GET

Evaluate and print a variable or value.

[%   GET variable %]    # 'GET' keyword is optional
    [%       variable %]
    [%       hash.key %]
    [%         list.n %]
    [%     code(args) %]
    [% obj.meth(args) %]
    [%  "value: $var" %]

=head2 CALL

As per L<GET> but without printing result (e.g. call code)

[%  CALL variable %]

=head2 SET

Assign a values to variables.

[% SET variable = value %]    # 'SET' also optional
    [%     variable = other_variable
           variable = 'literal text @ $100'
           variable = "interpolated text: $var"
           list     = [ val, val, val, val, ... ]
           list     = [ val..val ]
           hash     = { var => val, var => val, ... }
    %]

=head2 DEFAULT

Like L<SET>, but variables are only set if currently unset (i.e. have no
true value).

[% DEFAULT variable = value %]

=head2 INSERT

Insert a file without any processing performed on the contents.

[% INSERT legalese.txt %]

=head2 PROCESS

Process another template file or block and insert the generated output.
Any template L<BLOCK>s or variables defined or updated in the C<PROCESS>ed
template will thereafter be defined in the calling template.

[% PROCESS template %]
    [% PROCESS template  var = val, ... %]

=head2 INCLUDE

Similar to C<PROCESS>, but using a local copy of the current variables.
Any template C<BLOCK>s or variables defined in the C<INCLUDE>d template
remain local to it.

[% INCLUDE template %]
    [% INCLUDE template  var = val, ... %]

=head2 WRAPPER

The content between the C<WRAPPER> and corresponding C<END> directives is first
evaluated, with the output generated being stored in the C<content> variable.
The named template is then process as per C<INCLUDE>.

[% WRAPPER layout %]
       Some template markup [% blah %]...
    [% END %]

A simple F<layout> template might look something like this:

Your header here...
    [% content %]
    Your footer here...

=head2 BLOCK

Define a named template block for L<INCLUDE>, L<PROCESS> and L<WRAPPER>
to use.

[% BLOCK hello %]
       Hello World
    [% END %]

[% INCLUDE hello %]

=head2 FOREACH

Repeat the enclosed C<FOREACH> ... C<END> block for each value in the list.

[% FOREACH variable IN [ val, val, val ] %]    # either
    [% FOREACH variable IN list %]                 # or
       The variable is set to [% variable %]
    [% END %]

=head2 WHILE

The block enclosed between C<WHILE> and C<END> block is processed while
the specified condition is true.

[% WHILE condition %]
       content
    [% END %]

=head2 IF / UNLESS / ELSIF / ELSE

The enclosed block is processed if the condition is true / false.

[% IF condition %]
       content
    [% ELSIF condition %]
     content
    [% ELSE %]
     content
    [% END %]

[% UNLESS condition %]
       content
    [% # ELSIF/ELSE as per IF, above %]
       content
    [% END %]

=head2 SWITCH / CASE

Multi-way switch/case statement.

[% SWITCH variable %]
    [%   CASE val1 %]
           content
    [%   CASE [ val2, val3 ] %]
           content
    [%   CASE %]         # or [% CASE DEFAULT %]
           content
    [% END %]

=head2 MACRO

Define a named macro.

[% MACRO name <directive> %]
    [% MACRO name(arg1, arg2) <directive> %]
    ...
    [% name %]
    [% name(val1, val2) %]

=head2 FILTER

Process enclosed C<FILTER> ... C<END> block then pipe through a filter.

[% FILTER name %]                       # either
    [% FILTER name( params ) %]             # or
    [% FILTER alias = name( params ) %]     # or
       content
    [% END %]

=head2 USE

Load a plugin module (see C<Template::<Manual::Plugins>), or any regular Perl
module when the C<LOAD_PERL> option is set.

[% USE name %]                      # either
    [% USE name( params ) %]            # or
    [% USE var = name( params ) %]      # or
    ...
    [% name.method %]
    [% var.method %]

=head2 PERL / RAWPERL

Evaluate enclosed blocks as Perl code (requires the C<EVAL_PERL> option to be
set).

[% PERL %]
     # perl code goes here
     $stash->set('foo', 10);
     print "set 'foo' to ", $stash->get('foo'), "\n";
     print $context->include('footer', { var => $val });
    [% END %]

[% RAWPERL %]
       # raw perl code goes here, no magic but fast.
       $output .= 'some output';
    [% END %]

=head2 TRY / THROW / CATCH / FINAL

Exception handling.

[% TRY %]
     content
       [% THROW type info %]
    [% CATCH type %]
     catch content
       [% error.type %] [% error.info %]
    [% CATCH %] # or [% CATCH DEFAULT %]
     content
    [% FINAL %]
       this block is always processed
    [% END %]

=head2 NEXT

Jump straight to the next item in a C<FOREACH> or C<WHILE> loop.

[% NEXT %]

=head2 LAST

Break out of C<FOREACH> or C<WHILE> loop.

[% LAST %]

=head2 RETURN

Stop processing current template and return to including templates.

[% RETURN %]

=head2 STOP

Stop processing all templates and return to caller.

[% STOP %]

=head2 TAGS

Define new tag style or characters (default: C<[%> C<%]>).

[% TAGS html %]
    [% TAGS  %]

=head2 COMMENTS

Ignored and deleted.

[% # this is a comment to the end of line
       foo = 'bar'
    %]

[%# placing the '#' immediately inside the directive
        tag comments out the entire directive
    %]

=head1 SOURCE CODE REPOSITORY

The source code for the Template Toolkit is held in a public git repository
on Github: L<https://github.com/abw/Template2>

=head1 AUTHOR

Andy Wardley E<lt>abw@wardley.orgE<gt> L<http://wardley.org/>

=head1 VERSION

Template Toolkit version 3.009, released on July 13 2020.

=head1 COPYRIGHT

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

=cut

# Local Variables:
# mode: perl
# perl-indent-level: 4
# indent-tabs-mode: nil
# End:
#
# vim: expandtab shiftwidth=4: