#============================================================= -*-perl-*-
#
# Template::Modules
#
# DESCRIPTION
#
# AUTHOR
#   Andy Wardley  <abw@wardley.org>
#
# COPYRIGHT
#   Copyright (C) 1996-2022 Andy Wardley.  All Rights Reserved.
#
#   This module is free software; you can redistribute it and/or
#   modify it under the same terms as Perl itself.
#
#========================================================================

=head1 NAME

Template::Modules - Template Toolkit Modules

=head1 Template Toolkit Modules

This documentation provides an overview of the different modules that
comprise the Template Toolkit.

=head2 Template

The L<Template> module is the front-end to the Template Toolkit for
Perl programmers.

    use Template;
    my $tt = Template->new();
    $tt->process('hello.html', message => 'Hello World');

=head2 Template::Base

The L<Template::Base> module implements a base class from which the other
Template Toolkit modules are derived.  It implements common functionality
for creating objects, error reporting, debugging, and so on.

=head2 Template::Config

The L<Template::Config> module defines the configuration of the Template
Toolkit for your system. It is an example of a I<factory module> which is
responsible for instantiating the various other modules used in the Template
Toolkit.

For example, the L<Template::Config> module defines the C<$STASH> package
variable which indicates which version of the L<Template::Stash> you are
using by default.  If you elected to use the faster L<XS|Template::Stash::XS>
stash when you installed the Template Toolkit, then this will be set as:

    $STASH = 'Template::Stash::XS';

Otherwise you'll get the regular L<Perl|Template::Stash> stash:

    $STASH = 'Template::Stash';

This approach means that other parts of the Template Toolkit don't have to
worry about which stash you're using.  They just ask the L<Template::Config>
module to create a stash of the right kind.

=head2 Template::Constants

The L<Template::Constants> defines a number of constants that are used by
the Template Toolkit.

For example, the C<:chomp> tagset defines the C<CHOMP_???> constants that
can be used with the C<PRE_CHOMP> and C<POST_CHOMP> configuration options.

    use Template::Constants ':chomp';
    my $tt = Template->new({
        PRE_CHOMP => CHOMP_COLLAPSE,
    });

=head2 Template::Context

The L<Template::Context> module defines a runtime context in which templates
are processed. A context keeps track of all the templates, variables, plugins,
and other resources that are available (either directly or through delegate
objects) and provides methods to fetch, store, and perform various operations
on them.

=head2 Template::Document

The L<Template::Document> module implements a compiled template document
object.  This is generated by the L<Template::Parser> module.

=head2 Template::Exception

The L<Template::Exception> module implements an exception object which
is used for runtime error reporting.

=head2 Template::Filters

The L<Template::Filters> module implements a filter provider.  It includes
the core collection of filters that can be used via the C<FILTER> directive.

=head2 Template::Iterator

The L<Template::Iterator> module implements a data iterator which steps
through each item in a list in turn.  It is used by the C<FOREACH> directive.
Within a C<FOREACH> block, the C<loop> variable always references the
current iterator object.

    [%  FOREACH item IN list;
          IF loop.first;
             # first item in loop
          ELSIF loop.last;
             # last item in loop
          ELSE;
             # any other item in loop
          END;
        END
    %]

=head2 Template::Namespace::Constants

The L<Template::Namespace::Constants> module is used internally to represent
constants. These can be resolved immediately at the point that a template is
compiled.

=head2 Template::Parser

The L<Template::Parser> module is used to parse a source template and turn it
into Perl code which can be executed.

=head2 Template::Plugin

The L<Template::Plugin> module is a base class for Template Toolkit plugins
that can be loaded on demand from within a template using the C<USE> directive.

=head2 Template::Plugins

The L<Template::Plugins> module is the plugins provider.  It loads and prepares
plugins as and when they are requested from within a template.

=head2 Template::Provider

The L<Template::Provider> module is responsible for loading, compiling and
caching templates.

=head2 Template::Service

The L<Template::Service> module implements a service layer that sits just
behind the L<Template> module, and just in front of a L<Template::Context>. It
handles each request to process a template (forwarded from the L<Template>
module). It adds any headers and/or footers (specified via the C<PRE_PROCESS>
and C<POST_PROCESS> options), applies any wrapper (the C<WRAPPER> option) and
catches any errors returned (the C<ERRORS> option).

=head2 Template::Stash

The L<Template::Stash> module is used to fetch and store template variables.
It implements all of the magic associated with the dot operator.

=head2 Template::Stash::XS

The L<Template::Stash::XS> module is a high-speed implementation of
L<Template::Stash> written in C.

=head2 Template::Test

The L<Template::Test> module is used to automate the Template Toolkit
test scripts.

=cut

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