- NAME
- SYNOPSIS
- DESCRIPTION

- Template Syntax
- parse
- parse_print
- parse_stream
- Parse Options

- Filename
- Variables
- Options
- Aliases

- vars

- EXAMPLES
- SEE ALSO
- COPYRIGHT
- VERSION

# NAME

GT::Template - Gossamer Threads template parser

# SYNOPSIS

        use GT::Template;
        my $var = GT::Template->parse('file.txt', { key => 'value' });
        ...
        print $var;

or

        use GT::Template;
        GT::Template->parse_print('file.txt', { key => 'value' });

or

        use GT::Template;
        GT::Template->parse_stream('file.txt', { key => 'value' });

# DESCRIPTION

GT::Template provides a simple way (one line) to parse a template (which can be either a file or a string) and make sophisticated replacements.

It supports simple replacements, conditionals, function calls, including other templates, and more.

Additionally, through using pre-compiled files, subsequent parses of a template will be very fast.

## Template Syntax

The template syntax documentation has moved - it is now documented in the GT::Template::Tutorial manpage.

## parse

This option parses a template, and returns the value of the parsed template. See Parse Options for a description of the possible parse parameters.

## parse_print

This option parses a template, and prints it. See Parse Options for a description of the possible parse_print parameters.

## parse_stream

This option parses a template, and prints each part of it as the parse occurs. It should only be used in situations where streaming content is required as it is measurably slower than the parse_print alternative. See Parse Options for a description of the possible parse_stream parameters.

## Parse Options

### Filename

The first argument to `parse()/parse_print()/parse_stream()` (hereafter referred to simply as `parse())` is the full or relative (to the current working directory) path to the file to parse.

### Variables

The second argument is a hash reference of template variables that will be available in the parsed template (see the GT::Template::Tutorial manpage). Arbitrary hash/array data structure access is supported (see Advanced variables using references in the GT::Template::Tutorial manpage).

Loops are supported by providing an array reference or code reference as a value; array reference loops are generally preferred as they enable the loop to be used multiple times and support the <%loopvar.length%> syntax.

### Options

The third argument (which is not required) takes additional options that change the way a parse is performed. The available options (there are more, however their use is discouraged) are as follows.

- string => $template
Passing in `string => $template` will use $template as for the template content instead of reading the file specified as the first `parse()` argument. If provided, the first argument to `parse()` (the filename) is ignored.

- compress => 1
Setting compress => 1 will compress all white space generated by the program. This is usually acceptable for HTML, reducing page sizes by typically 10-20%, but should not be used for non-HTML templates. The default is 0 (no compression). This option has no effect when using parse_stream().

- strict => 0
If set to 1, attempting to use a tag that does not exist will display an ``Unknown tag 'tagname''' error. If strict is set to 0, using an unset tag will not display anything.

- escape => 1
If enabled, this option will cause all variables to be HTML escaped before being included on a page. Enabling this option is strongly recommended. all variables before they are printed. Tag values that should not be escaped should be passed as scalar references (\$foo or \'<html>').

This option currently defaults to 0, but may eventually change to 1 - so passing an explicit 1 or 0 value is strongly recommended.

- disable => { ... }
This can be used to disable certain GT::Template functionality. To disable a particular feature, the hash reference passed to disable should contain a `feature_name` with a `1` value, unless otherwise indicated. Feature names are as follows:

- functions
This can be used to disable Package::function calls, such as `<%Some::Package::function%>`. Note, however, that this does _not_ disable aliased function calls (see below).

- function_args
This disables any function calls that specify arguments - for instance, `<%Some::Package::function(1)>`. Note that this does _not_ disable passing arguments to aliased function calls (see below).

- function_restrict
This can be used to restrict function calls by limiting the available functions. It takes a regular expression as an argument, which will be tested against the fully qualified function name - any function that does not match the regular expression will not be called. For example, to only allow functions in 'Package::One' and 'Second::Package' to be called, you could use:

        function_restrict => '^(?:Package::One|Second::Package)::\w+$'

Like the above options, this does not restrict aliased function calls.

- coderefs_args
This can be specified to disable the calling of code reference variables with arguments. Tags such as `<%coderefname%>` and `<%coderefname()%>` will be allowed, but `<%coderefname(1)%>` will not.

- alias_args
This option can be used to disable the passing of arguments to aliased function calls (see below).

- pkg_chop
When calling a function such as <%Package::A::B::function%>, GT::Template will first attempt to load Package/A/B.pm, then, if it fails, Package/A.pm, and so on down to Package.pm, looking for Package::A::B::function in each file. This behaviour is slow and often undesirable - it is recommended to properly split up packages (that is, putting Package::A::B inside Package/A/B.pm instead of Package/A.pm or Package.pm). The ``package chopping'' occurs if pkg_chop is set to 1 (currently the default, but may change), and does not occur if pkg_chop is set to 0 (recommended, but not the default for historic reasons).

- heap
If this is set, it will be added to the end of any other arguments passed to functions called.

- func_code
When calling a function such as <%Package::function%>, you can override the default behaviour of simply calling the function by providing a code reference to `func_code`. Instead of calling Package::function(), your code reference will be called with the string of the package to call (e.g. 'Package::function') and the arguments that would have been passed to the function. The return value of your code will be used as if it was the return value from the real function.

- begin
- end
`begin` and `end` can be used to change the characters that start and end a template tag. These default to `<%` for `begin`, and `%>` for `end`. For example, if you changed `begin` to `[*` and `end` to `*]`, you would use `[*tagname*]` for a normal tag, `[*-- comment --*]` for a comment, etc.

### Aliases

The forth option to parse is an optional hash of aliases to set up for functions. The key should be the alias name and the value should be the function to call when the alias is invoked. For example:

        print GT::Template->parse(
            'file.htm',
            { key => 'value' },
            { compress => 1 },
            { myfunc => 'Long::Package::Name::To::myfunc' }
        );

Now in your template you can do:

        <%myfunc('argument')%>

Which will call `Long::Package::Name::To::myfunc`.

## vars

Accessing variables from outside a template can be done by calling the `GT::Template->vars` method. For further details, please see the GT::Template::Vars manpage.

# EXAMPLES

Parse the string contained in $template, making the 'key' tag available.

        my $parsed = GT::Template->parse(undef, { key => 'value' }, { string => $template });

Parse file.txt, compress the result, and print it. This is equivelant to `print GT::Template->parse(...)`, but slightly faster.

        GT::Template->parse_print('file.txt', { key => 'value' }, { compress => 1 });

Print the output of the template it as it is parsed, not after entirely parsed. This will output the same as the above command would without the ``compress'' option, but is slower (unless, of course, streaming is needed).

        GT::Template->parse_stream('file.txt', { key => 'value' });

Don't display warnings on invalid keys:

        GT::Template->parse_print('file.txt', { key => 'value' }, { strict => 0 });

# SEE ALSO

the GT::Template::Tutorial manpage - Documentation/tutorial for GT::Template template tags.

the GT::Template::Vars manpage - Interface for accessing/manipulating template tags from Perl code.

the GT::Template::Inheritance manpage - Documentation for GT::Template template inheritance.

# COPYRIGHT

Copyright (c) 2005 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/

# VERSION

Revision: $Id: Template.pm,v 2.142 2005/07/05 00:39:40 jagerman Exp $