Text::Xslate::Manual::FAQ - Frequently asked questions and answers
We read it /eks-leit/.
/eks-leit/
It stands for XS template, a template engine written in XS, although pure Perl implementations are also provided.
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.
syntax
my $tx = Text::Xslate->new( syntax => 'TTerse', # by moniker ); my $tx = Text::Xslate->new( syntax => 'Text::Xslate::Syntax::TTerse', # by fully qualified name );
Xslate is tested on perl v5.8.1. No special settings should be required.
Here are some optimizations worth noting that makes Text::Xslate run so fast, in no particular order:
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.
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
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.
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 to greatly reduce the number of malloc() calls required to render a template.
malloc()
Use start_tag, end_tag, and line_start options to new method, which can be joined together with syntax option:
start_tag
end_tag
line_start
new
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.
Convert HASH references into ARRAY references because for methods can deal with ARRAY references.
for
: # 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.
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, but it does not require the Template-Toolkit distribution.
T::X::Bridge::TT2
These bridge modules are useful not only for TTerse users, but also for Kolon users.
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.
module
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 Text::Xslate::Bridge for details.
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:
alarm()
eval { local $SIG{ALRM} = sub { die @_ }; alarm(1); # set timeout $tx->render('<: while true { } :>', \%vars); }; if($@ =~ /\b ALRM \b/xms) { # timeout! }
(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 must be text strings. (however, if you want to process binary strings, you can do by passing :bytes for input_layer). Thus, parameters which you give render() and values which registered functions return must be text strings.
UTF-8
:bytes
input_layer
render()
Template-Toolkit allows objects (i.e. blessed references) to access its element, i.e. [% object.attr %] means $object->{attr} if the object has no attr method. This behavior breaks encapsulation and hides typos, so Xslate doesn't allow such fallbacks.
[% object.attr %]
$object->{attr}
attr
If you want to access hash elements, define the accessor of them, or prepare values before calling render().
See Text::Xslate::Manual::Builtin.
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
If you are a vim user, there is xslate.vim for Kolon: https://github.com/motemen/xslate-vim
vim
There are bridges that integrate Xslate into WAFs:
Catalyst::View::Xslate for Catalyst
MojoX::Renderer::Xslate for Mojolicious
Tiffany for general
Text::Xslate
Text::Xslate::Manual
To install Text::Xslate, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Text::Xslate
CPAN shell
perl -MCPAN -e shell install Text::Xslate
For more information on module installation, please visit the detailed CPAN module installation guide.