NAME

Text::Xslate - High performance template engine

VERSION

This document describes Text::Xslate version 0.1000.

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 multiple files
    my $tx = Text::Xslate->new();
    print $tx->render_file('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.

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. Accordingly, Xslate is much faster than other template engines.

Note that this software is under development.

INTERFACE

Methods

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

Creates a new xslate template code.

Options:

string => $template_string

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

file => $template_file | \@template_files

Specifies file(s) to be preloaded.

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

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

function => \%functions

Specifies functions.

cache => $level // 1

Sets the cache level. If $level >= 2, modified times will not be checked.

input_layer => $perliolayers // ":utf8"

Specifies PerlIO layers for reading.

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

Renders a template with variables, and returns the result.

Exportable functions

escaped_string($str :Str) -> EscapedString

Mark $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

TODO

EXAMPLES

Variable access

    <:= $var :>
    <:= $var.field :>
    <:= $var["field"] :>
    <:= $var[0] :>

Variables may be HASH references, ARRAY references, or objects.

Loop (for)

    : for $data ->($item) {
        [<:= $item.field =>]
    : }

Iterating data may be ARRAY references.

Conditional statement (if)

    : if $var == nil {
        $var is nil.
    : }
    : else if $var != "foo" {
        $var is not nil nor "foo".
    : }
    : else {
        $var is "foo".
    : }

    : if( $var >= 1 && $var <= 10 ) {
        $var is 1 .. 10
    : }

    := $var.value == nil ? "nil" : $var.value

Expressions

Relational operators (== != < <= > >=):

    := $var == 10 ? "10"     : "not 10"
    := $var != 10 ? "not 10" : "10"

Arithmetic operators (+ - * / %):

    := $var + 10
    := ($var % 10) == 0

Logical operators (|| && //)

    := $var >= 0 && $var <= 10 ? "ok" : "too smaller or too larger"
    := $var // "foo" # as a default value

Operator precedence:

    (TODO)

Template inclusion

    : include "foo.tx"

Xslate templates may be recursively included, but including depth is limited to 100.

Template cascading

Base templates mytmpl/base.tx:

    : block title -> { # with default
        [My Template!]
    : }

    : block body -> {;} # without default

Another derived template mytmpl/foo.tx:

    : cascade mytmpl::base
    : # use default title
    : around body -> {
        My Template Body!
    : }

Yet another derived template mytmpl/bar.tx:

    : cascade mytmpl::foo
    : around title -> {
        --------------
        : super
        --------------
    : }
    : before body -> {
        Before body!
    : }
    : after body -> {
        After body!
    : }

Then, Perl code:

    my $tx = Text::Xslate->new( file => 'mytmpl/bar.tx' );
    $tx->render({});

Output:

        --------------
        [My Template!]
        --------------

        Before body!
        My Template Body!
        After Body!

This is also called as template inheritance.

Macro blocks

    : macro add ->($x, $y) {
    :   x + $y;
    : }
    := add(10, 20)

    : macro signeture -> {
        This is foo version <:= $VERSION :>
    : }
    : signeture()

TODO

• Template-Toolkit-like syntax

• HTML::Template-like syntax

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

Text::MicroTemplate

Text::ClearSilver

Template-Toolkit

HTML::Template

HTML::Template::Pro

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