
=head1 NAME

Text::Xslate::Manual::FAQ - Frequently asked questions and answers

=head1 QUESTIONS

=head2 General

=head3 How do you pronounce Xslate?

We read it C</eks-leit/>.

=head3 What Xslate stands for?

It stands for I<XS template>, a template engine written in XS, although
pure Perl implementations are also provided.

=head3 What are 'Kolon', 'Metakolon', and 'TTerse' ?

Xslate supports multiple template syntaxes. Kolon is the default syntax,
Metakolon is suitable to output Kolon templates, and TTerse is compatible
with Template-Toolkit. You can specify the template syntax by passing
C<syntax> option to the Text::Xslate constructor.

    my $tx = Text::Xslate->new(
        syntax => 'TTerse', # by moniker
    );

    my $tx = Text::Xslate->new(
        syntax => 'Text::Xslate::Syntax::TTerse', # by fully qualified name
    );

=head3 What version of perl does Xslate require?

Xslate is tested on perl v5.8.1. No special settings should be required.

=head2 Templates

=head3 How can I changes template tags?

Use C<start_tag>, C<end_tag>, and C<line_start> options to C<new> method,
which can be joined together with C<syntax> option:

    my $tx = Text::Xslate->new(
        syntax     => 'TTerse',
        tag_start  => '{',
        tag_end    => '}',
        line_start => undef,
    );
    print $tx->render_string('Hello, {lang} world!', { lang => 'Xslate' });

=head3 How can I iterate over HASH references?

Convert HASH references into ARRAY references because C<for> methods can deal
with ARRAY references.

    : # in Kolon
    : # iterate $hash by keys
    : for $hash.keys() -> $key {
        <: $key :>
    : }
    : # by values
    : for $hash.values() -> $value {
        <: $value :>
    : }
    : # by key-value pairs
    : for $hash.kv() -> $pair {
        <: $pair.key :>=<: $pair.value :>
    : }

Note that the above methods return ARRAY references sorted by the keys.

=head3 How can I use Template-Toolkit virtual methods and filters?

Xslate itself does not support these methods and filters, but there
are modules on CPAN that implement them.

L<Text::Xslate::Bridge::TT2> provides almost all the TT methods and filters,
but it requires Template-Toolkit installed.

L<Text::Xslate::Bridge::TT2Like> provides the same features as
C<T::X::Bridge::TT2>, but it does not require the Template-Toolkit distribution.

These bridge modules are useful not only for TTerse users, but
also for Kolon users.

=head3 How can I (write|get) plugins?

It is unlikely to write plugins for Xslate, because Xslate allows
you to export any functions to templates. Any function-based modules
are available by the C<module> option to the C<new> method.

Xslate also allows to call methods for object instances, so you can
use any object-oriented modules, except for classes which only provide
class methods (they need wrappers).

If you want to add methods to builtin data types (nil, scalars, arrays and
hashes), you can write bridge modules. See L<Text::Xslate::Bridge> for details.

=head3 How to limit while-loop like Template-Toolkit?

While Template-Toolkit has a loop counter to prevent runaway WHILE loop,
Xslate has no arbitrary limitation.

Instead, you can use C<alarm()> to limit B<any> runaway code:

    eval {
        local $SIG{ALRM} = sub { die @_ };
        alarm(1); # set timeout
        $tx->render('<: while true { } :>', \%vars);
    };
    if($@ =~ /\b ALRM \b/xms) {
        # timeout!
    }

=head3 Does Xslate process text strings, or binary strings?
X<utf8> X<UTF-8> X<utf8 flagged string> X<unicode>

(The meaning of I<text string> and I<binary string> is that of Perl,
see L<perlunifaq>.)

Xslate assumes template files to be encoded in C<UTF-8> by default, so the
output is a text string and template parameters must be text strings.
However, if you want to process binary strings, you can do by passing C<:raw>
for C<input_encoding>.

=head2 Functions, filters and macros

=head3 How can I use macros as a callback to high-level functions?

Macros are objects that overload C<&{}>, the CODE dereference operator, so
all you have to do is to call them, but don't check their types because
they are not a I<real> CODE reference.

    my $tx = Text::Xslate->new(
        function => {
            count => sub {
                my($a, $cb) = @_;
                # Don't check the type of $cb!
                return scalar grep { $cb->($_) } @{$a};
            },
        },
    );

    print $tx->render_string('<: count($a, -> $x { $x >= 50 }) :>',
        { a => [ 0 .. 100 ] },
    ); # => 50

=head2 Development

=head3 How can I colorize Xslate templates?

If you are a C<vim> user, there is F<xslate.vim> for Kolon:
L<https://github.com/motemen/xslate-vim>

=head2 Web Application Frameworks

=head3 How can I use Xslate into my favorite WAF?

There are bridges that integrate Xslate into WAFs:

=over

=item *

L<Catalyst::View::Xslate> for L<Catalyst>

=item *

L<MojoX::Renderer::Xslate> for L<Mojolicious>

=item *

L<Tiffany> for general

=back

=head1 SEE ALSO

L<Text::Xslate>

L<Text::Xslate::Manual>

=cut
