NAME

tt - Preprocess Perl code with Template Toolkit and Module::Compile.

SYNOPSIS

        package Foo;

        # between 'use tt' and 'no tt' the source code will
        # be process by Template Toolkit.

        # This example generates source code for accessors.
        # the specific problem is best solved with L<Moose> or
        # L<Class::Accessor>, but the principal remains the same

        use tt ( fields => [qw/foo bar gorch/] );

        [% FOREACH fields IN fields %]

        sub [% field %] {
                my $self = shift;
                $self->{'[% field %]'} = shift if @_;
                return $self->{'[% field %]'};
        }

        [% END %]

        no tt;

        package main;

        my $obj = Foo->new;

        $obj->bar("moose");

DESCRIPTION

This module uses Module::Compile to help you generate Perl code without using BEGIN/eval tricks and reducing readability, but without having to repeat yourself either.

BUT SOURCE FILTERS BAD!!!!

Yeah, source filters suck (normally) for two reasons, neither of which tt suffers from:

1. They're kinda slow and may introduce fat dependencies for simple code. Module::Compile fixes this.
2. They break down on edge cases. This is true for source filters that try to parse Perl, pretending to implement syntax extensions. Since tt doesn't parse the perl code at all but operates on a very dumb string level it meets no edge cases.

That said, string level preprocessing of source code sucks. However, since Perl doesn't have a convenient AST to write Lisp-style macros and deeper templates (that are aware of Perl's own semantics), this module does fill a niche.

CONFIGURATION

To configure Template either subclass this module and override default_tt_config, or pass parameters in the use tt line.

Note that due to the way Module::Compile works you must put all the variables on one use line.

For example:

        use tt INCLUDE_PATH => "/foo";

The default configuration values are:

                INTERPOLATE        => 0,
                EVAL_PERL          => 1,
                INCLUDE_PATH       => [ @INC ],
                LOAD_PERL          => 1,
                DEBUG              => "undef",

This provides a default that is slightly more suitable for templating code than normal TT defaults. DEBUG_UNDEF ensures that no undef variables are interpolated, INTERPOLATE being off ensures that perl variables aren't treated as TT variables by accident, and the other options allow for a more permissive use of features.

VARIABLES

Like configuration parameters, you may pass variables on the use tt line.

Variables and configuration options are destingushed - anything that is all upper case in the use line is considered configuration.

A probably better way to declare variables is simply in the template itself:

        [% foo = "bar" %]

CAVEATS

Due to Module::Compile's semantics the use line is actually fudged and string-evaled by this module, so it might break and you can't refer to lexicals.

All uppercase parameters on the use line are treated as configuration options. I may add a list of TT configuration params later on.

TODO

Add all sorts of useful variables about the package that the template is processing, the file and line numbers, etc.

Currently Module::Compile doesn't provide enough facilities for this.

SEE ALSO

Template, Module::Compile, Filter::Simple

VERSION CONTROL

This module is maintained using Darcs. You can get the latest version from http://nothingmuch.woobling.org/Module-Compile-TT/, and use darcs send to commit changes.

AUTHOR

Yuval Kogman <nothingmuch@woobling.org>

COPYRIGHT & LICENSE

        Copyright (c) 2006 the aforementioned authors. All rights
        reserved. This program is free software; you can redistribute
        it and/or modify it under the same terms as Perl itself.