GeneralHowdoyoupronounce'Xslate'?
We read it "/eks-leit/".
What'Xslate'standsfor?
It stands for XStemplate, a template engine written in XS, although pure Perl implementations are also
provided.
Whatare'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 2. You can specify the template syntax by
passing "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
);
WhatversionofperldoesXslaterequire?
Xslate is tested on perl v5.8.1. No special settings should be required.
HowcanIinstallthepure-PerlversionofXslate?
Pass "PUREPERL_ONLY=1" to Makefile.PL, which requests the Xslate build system not to make XS parts.
Note that "cpanm 1.7" supports "--pp" option to install pure-Perl alternatives, so you can type "cpanm
--pp Text::Xslate".
WhatoptimizationsdoesXslateemploys?
Here are some optimizations worth noting that makes Text::Xslate run so fast, in no particular order:
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.
HowcanIthrowerrorsinfunctionsand/ormethods?
Handle warnings by "warn_handler" and raises exceptions if needed.
That's because Xslate catches exceptions in templates and emits them as warnings.
ConfigurationWhenshouldIcreatetheXslateinstance?
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.
HowcanIchangeinstanceattributesdynamically?
Instance attributes, e.g. "include_path", "function", or "syntax", are immutable, so you cannot change
them dynamically.
Instead, you can create multiple instances by different options. 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(...);
TemplatesHowcanIchangestemplatetags?
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.
HowcanIiterateoverHASHreferences?
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.
HowcanIuseTemplate-Toolkitvirtualmethodsandfilters?
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.
HowcanI(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.
Howtolimitwhile-looplikeTemplate-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!
}
DoesXslateprocesstextstrings,orbinarystrings?
(The meaning of textstring and binarystring 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.
Whydoesn'tIcannotaccess$object.attrlikeTT2?
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.
If you want to access object attributes, define the accessors of them, or prepare values as a non-object
before calling render().
CanIloadmacrosinothertemplatefiles?
Not yet. Currently Xslate doesn't support external macros.
Functions,filtersandmacrosWherearethelistofbuiltinfunctions?
See Text::Xslate::Manual::Builtin.
HowcanIusemacrosasacallbacktohigh-levelfunctions?
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
WebApplicationFrameworksHowcanIuseXslatein$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
WhereareexampleswhichuseXslateinCatalyst?
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!
DevelopmentandsupportHowcanIcolorizeXslatetemplates?
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>
WherecanIaskquestions?
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>
Ifoundabug!WhatcanIdoforyou?
Please make a minimal test case to show the problem clearly. The code is the common language both I and
you speak fluently ;)
Install Now
PNG Icons
Emojis