Text::...al::FAQ(3pm)

🦋 Text::Xslate::Manual::FAQ 🦋

okay bestie, you've got the Text::Xslate::Manual::FAQ(3pm) page pulled up — yes, that one, sitting under "User Contributed Perl Documentation" — and honestly? iconic. it's the FAQ, it's the lore, it's every question people keep asking, answered. let's get into it 💖

---

💖 NAME 💖

Text::Xslate::Manual::FAQ — Frequently asked questions and answers 🌸

✨ DESCRIPTION ✨

so this manual page lists FAQs, which we've heard for now. that's the whole description. short, sweet, main character energy 💅

❓ QUESTIONS ❓

🧚 General 🧚

🗣️ How do you pronounce 'Xslate'?

we read it /eks-leit/. that's it, that's the pronunciation 🎀

🧬 What 'Xslate' stands for?

it stands for XS template, a template engine written in XS — although pure Perl implementations are also provided. yes bestie, both 💖

🎭 What are 'Kolon', 'Metakolon', and 'TTerse' ?

Xslate supports multiple template syntaxes, and it's giving options:

• Kolon is the default syntax
• Metakolon is suitable to output Kolon templates
• TTerse is compatible with Template-Toolkit 2

you can specify the template syntax by passing the 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
);

🐪 What version of perl does Xslate require?

Xslate is tested on perl v5.8.1 🫶 no special settings should be required. lowkey ancient, highkey fine.

📦 How can I install the pure-Perl version of Xslate?

pass PUREPERL_ONLY=1 to Makefile.PL, which requests the Xslate build system not to make XS parts. no XS, no problem ✨

note that cpanm 1.7 supports --pp option to install pure-Perl alternatives, so you can type cpanm --pp Text::Xslate.

🔥 What optimizations does Xslate employs?

here are some optimizations worth noting that makes Text::Xslate run so fast, in no particular order (the page really said "in no particular order" and I respect that):

• Pre-compiled templates — Text::Xslate is among the template engines that pre-compile the templates. this is similar to, say, Template::Toolkit, but Text::Xslate compiles the templates to C structures and stores them as binary data. 💾
• Built on top of a virtual machine — Text::Xslate is built on top of virtual machine that executes bytecode, and this virtual machine is fine-tuned specifically for template processing. the virtual machine also employs optimizations such as direct-threading style coding to shave off any extra milliseconds that the engine might take otherwise ⚡
• Custom byte codes for oft-used operations — some operations which are used very often are optimized into its own byte code. for example (as described elsewhere) Text::Xslate automatically escapes HTML unless you tell it not to. Text::Xslate implements this process which involves escaping the string while appending the result to the output buffer in C, as a custom byte code. this lets you avoid the penalties usually involved in such operations 👑
• Pre-allocation of output buffers — one of the main things to consider to reduce performance degradation while processing a template is to avoid the number of calls to malloc(). one of the tricks that Text::Xslate employs to reduce the number of calls to malloc() is to pre-allocate the output buffer in an intelligent manner: for example, Text::Xslate assumes that most templates will be rendered to be about the same as the previous run, so when a template is rendered it uses the size allocated for the previous rendering as an approximation of how much space the current rendering will require. this allows you to greatly reduce the number of malloc() calls required to render a template 🧠

💀 How can I throw errors in functions and/or methods?

handle warnings by warn_handler and raises exceptions if needed.

that's because Xslate catches exceptions in templates and emits them as warnings. so yeah, that's the pipeline 🌈

⚙️ Configuration ⚙️

⏰ When should I create the Xslate instance?

Xslate instances are reusable and creating the instance costs somewhat so you're recommended to reuse them as much as possible. that is, you should make the instance global 🌍

consider a PSGI application:

# create Xslate here, not in psgi_app();
my $xslate = Text::Xslate->new(...);

sub psgi_app {
    my($env) = @_;
    # use $xslate and create $response
    return $response;
}
return \&psgi_app; # as a PSGI app

don't create the instance in each request. it's less efficient. bestie, please 😭

🚫 How can I change instance attributes dynamically?

instance attributes, e.g. include_path, function, or syntax, are immutable, so you cannot change them dynamically. no editing on the fly, sorry 🫠

instead, you can create multiple instances by different options — the page's phrasing is that you do this instance in order to avoid conflicts with cache directories.

for example:

my %common_config = ( cache_dir => $dir, module => \@module );
my %xslate = (
    ja => Text::Xslate->new( path => [ $template_ja ], %common_config ),
    en => Text::Xslate->new( path => [ $template_en ], %common_config ),
    ro => Text::Xslate->new( path => [ $template_ro ], %common_config ),
);
$xslate{$lang}->render(...);

📝 Templates 📝

🏷️ How can I changes template tags?

use start_tag, end_tag, and line_start options to new method, which can be joined together with 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' });

note that you'd better to avoid symbols which can be used for operators. fr fr, just don't 🙈

🔑 How can I iterate over HASH references?

convert HASH references into ARRAY references because for methods can deal with just 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 🌸

🧵 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 👀

• Text::Xslate::Bridge::TT2 provides almost all the TT methods and filters, but it requires Template-Toolkit installed.
• Text::Xslate::Bridge::TT2Like provides the same features as T::X::Bridge::TT2, and it does not require the Template-Toolkit runtime.

these bridge modules are useful not only for TTerse users, but also for Kolon users. everyone eats 🍓

🧩 How can I (write|get) plugins?

it is unlikely to need to write plugins for Xslate, because Xslate allows you to export any functions to templates. any function-based modules are available by the module option ✨

Xslate also allows you 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 Text::Xslate::Bridge for details 🫶

⏳ 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 alarm() to limit any runaway code:

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

yes, you're literally setting an alarm on your own code. do it, it's self care 💅

🔤 Does Xslate process text strings, or binary strings?

(the meaning of text string and binary string is that of Perl, see perlunifaq.)

Xslate assumes template files to be encoded in UTF-8 by default, so the output is a text string and template parameters, including values which registered functions return, must be text strings 🌈

however, if you want to process binary strings, you can do so by passing :bytes to input_layer, although it's not recommended. you've been warned 🚨

🙈 Why doesn't I cannot access $object.attr like TT2?

Template-Toolkit allows objects (i.e. blessed references) to access its element if the object has no accessor methods, i.e. [% object.attr %] might mean $object->{attr}. this behavior breaks encapsulation and hides typos, so Xslate doesn't allow such fallbacks. protective king behavior 👑

if you want to access object attributes, define the accessors of them, or prepare values as a non-object before calling render().

📂 Can I load macros in other template files?

not yet. currently Xslate doesn't support external macros 😔

🛠️ Functions, filters and macros 🛠️

📚 Where are the list of builtin functions?

see Text::Xslate::Manual::Builtin 📖

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

macros are objects that overload &{}, the CODE dereference operator, so all you have to do is to call them simply, but don't check their types because they are not a 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

see that # => 50? that's the payoff 💖

🌐 Web Application Frameworks 🌐

🕸️ How can I use Xslate in $my_favorite_WAF?

there are bridges that integrate Xslate into WAFs:

• Catalyst::View::Xslate for Catalyst
• MojoX::Renderer::Xslate for Mojolicious
• Tiffany for general usage

there are WAFs which adopt Xslate as the default template engine:

• Amon2
• Pickles

🦆 Where are examples which use Xslate in Catalyst?

there is a real-world project that uses Xslate with Catalyst.

https://github.com/duckduckgo/community-platform

Initializing Xslate: https://github.com/duckduckgo/community-platform/blob/master/lib/DDGC.pm#L268

Working on: https://dukgo.com/

Enjoy! 🎉

🫂 Development and support 🫂

🌈 How can I colorize Xslate templates?

for vim user, there is xslate.vim for Kolon:

https://github.com/motemen/xslate-vim

for emacs user, there are plugins:

https://github.com/samvtran/kolon-mode

https://github.com/yoshiki/tx-mode

🙋 Where can I ask questions?

the mailing list is recommended to ask questions.

http://groups.google.com/group/xslate

if you find a bug or have a request, creating github issues is better because those tickets are less likely to disappear than the ports in the mailing list.

https://github.com/xslate/p5-Text-Xslate/issues

🐛 I found a bug! What can I do for you?

please make a minimal test case to show the problem clearly. the code is the common language both I and you speak fluently ;)

✨ SEE ALSO ✨

okay bestie, you made it to the end, so here's your little reading list 💖 if you wanna go deeper (and you do, you're literally so curious, I love that for you), go check these out:

• Text::Xslate — the main character itself 👑 the module this whole FAQ is about
• Text::Xslate::Manual — the full manual, aka the extended director's cut 🎬
• Text::Xslate::Manual::Cookbook — recipes and how-tos for when you're like "okay but how do I actually do the thing" 🍓

---

like, go read them?? no cap, they're worth it 🦋

and that's a wrap on the FAQ, bestie!! you ate this whole page fr fr 💅 thanks for sticking with me to the very end 🫶

tiny footnote for the lore girlies: this page comes from perl v5.42.3, dated 2026-08-22, and it lives in the Perl docs under the Text::...al::FAQ(3pm) name 🌸 slay, iconic, periodt ✨