NAME

Text::Xslate - High performance template engine

VERSION

This document describes Text::Xslate version 0.1007.

SYNOPSIS

    use Text::Xslate;
    use FindBin qw($Bin);

    my %vars = (
        title => 'A list of books',
        books => [
            { title => 'Islands in the stream' },
            { title => 'Programming Perl'      },
            { title => 'River out of Eden'     },
            { title => 'Beautiful code'        },
        ],
    );

    # for files
    my $tx = Text::Xslate->new();
    print $tx->render('hello.tx', \%vars);

    # for strings
    my $template = q{
        <h1><: $title :></h1>
        <ul>
        : for $books ->($book) {
            <li><: $book.title :></li>
        : } # for
        </ul>
    };

    $tx = Text::Xslate->new(
        string => $template,
    );

    print $tx->render(\%vars);

    # you can tell the engine that some strings are already escaped.
    use Text::Xslate qw(escaped_string);

    $vars{email} = escaped_string('gfx &lt;gfuji at cpan.org&gt;');
    # or
    $vars{email} = Text::Xslate::EscapedString->new(
        'gfx &lt;gfuji at cpan.org&gt;',
    ); # if you don't want to pollute your namespace.


    # if you want Template-Toolkit syntx:
    $tx = Text::Xslate->new(syntax => 'TTerse');
    # ...

DESCRIPTION

Text::Xslate is a template engine tuned for persistent applications. This engine introduces the virtual machine paradigm. That is, templates are compiled into xslate opcodes, and then executed by the xslate virtual machine just like as Perl does.

This software is under development. Version 0.1xxx is a developing stage, which may include radical changes. Version 0.2xxx and more will be somewhat stable.

Features

High performance

Xslate has an virtual machine written in XS, which is highly optimized. According to benchmarks, Xslate is 2-10 times faster than other template engines (Template-Toolkit, HTML::Template::Pro, Text::MicroTemplate, etc).

Template cascading

Xslate supports template cascading, which allows one to extend templates with block modifiers.

This mechanism is also called as template inheritance.

Syntax alternation

The Xslate engine and parser/compiler are completely separated so that one can use alternative parsers.

Currently, TTerse, a Template-Toolkit-like parser, is supported as an alternative.

INTERFACE

Methods

Text::Xslate->new(%options) :XslateEngine

Creates a new xslate template engine.

Possible options ares:

string => $template_string

Specifies the template string, which is called <input> internally.

path => \@path // ["."]

Specifies the include paths. Default to <["."]>.

function => \%functions

Specifies functions.

Functions may be called as f($arg) or $arg | f.

cache => $level // 1

Sets the cache level.

If $level == 1 (default), Xslate caches compiled templates on the disk, and checks the freshness of the original templates every time.

If $level >= 2, caches will be created but the freshness will not be checked.

$level == 0 creates no caches. It's only for testing.

input_layer => $perliolayers // ":utf8"

Specifies PerlIO layers for reading templates.

syntax => $moniker

Specifies the template syntax.

If $moniker is undefined, the default parser will be used.

$tx->render($file, \%vars) :Str

Renders a template with variables, and returns the result.

If $file is omitted, <input> is used. See the string option for new.

Note that $file may be cached according to the cache level.

$tx->load_file($file) :Void

Loads $file for following render($file, \%vars). Compiles and caches it if needed.

This method may be used for pre-compiling template files.

Exportable functions

escaped_string($str :Str) -> EscapedString

Marks $str as escaped. Escaped strings will not be escaped by the engine, so you have to escape these strings.

For example:

    my $tx = Text::Xslate->new(
        string => 'Mailaddress: <: $email :>',
    );
    my %vars = (
        email => "Foo &lt;foo@example.com&gt;",
    );
    print $tx->render(\%email);
    # => Mailaddress: Foo &lt;foo@example.com&gt;

TEMPLATE SYNTAX

There are syntaxes you can use:

Kolon

Kolon is the default syntax, using <: ... :> tags and : ... line code, which is explained in Text::Xslate::Syntax::Kolon.

Metakolon

Metakolon is the same as Kolon except for using [% ... %] tags and % ... line code, instead of <: ... :> and : ....

TTerse

TTerse is a syntax that is a subset of Template-Toolkit 2, which is explained in Text::Xslate::Syntax::TTerse.

NOTES

In Xslate templates, you cannot use undef as a valid value. The use of undef will cause fatal errors as if use warnings FALTAL = "all"> was specified. However, unlike Perl, you can use equal operators to check whether the value is defined or not:

    : if $value == nil { ; }
    : if $value != nil { ; }

    [% # on TTerse syntax -%]
    [% IF $value == nil %] [% END %]
    [% IF $value != nil %] [% END %]

Or, you can also use defined-or operator (//):

    : # on Kolon syntax
    Hello, <: $value // "Xslate" :> world!

    [% # on TTerse syntax %]
    Hello, [% $value // "Xslate" %] world!

DEPENDENCIES

Perl 5.10.0 or later, and a C compiler.

BUGS

All complex software has bugs lurking in it, and this module is no exception. If you find a bug please either email me, or add the bug to cpan-RT. Patches are welcome :)

SEE ALSO

Xslate template syntaxes:

Text::Xslate::Syntax::Kolon

Text::Xslate::Syntax::Metakolon

Text::Xslate::Syntax::TTerse

Other template modules:

Text::MicroTemplate

Text::MicroTemplate::Extended

Text::ClearSilver

Template-Toolkit

HTML::Template

HTML::Template::Pro

Benchmarks:

Template::Benchmark

ACKNOWLEDGEMENTS

Thanks to lestrrat for the suggestion to the interface of render().

Thanks to tokuhirom for the ideas, feature requests, encouragement, and bug-finding.

AUTHOR

Fuji, Goro (gfx) <gfuji(at)cpan.org>

LICENSE AND COPYRIGHT

Copyright (c) 2010, Fuji, Goro (gfx). All rights reserved.

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

cpanm Text::Xslate

perl -MCPAN -e shell
install Text::Xslate