
=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 several 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
    );

=head2 Templates

=head3 How can I changes template tags?

Use C<start_tag>, C<end_tag>, and C<line_start> options, 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 itself.

L<Text::Xslate::Bridge::TT2Like> provides the same features as C<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.

=head2 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!
    }

=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

=head1 SEE ALSO

L<Text::Xslate>

L<Text::Xslate::Manual>

=cut
