Text::Xslate::Manual::User3Contributed Perl DocuText::Xslate::Manual::FAQ(3pm)
NAME
Text::Xslate::Manual::FAQ - Frequently asked questions and answers
DESCRIPTION
This manual page lists FAQs, which we've heard for now.
QUESTIONS
General
How do you pronounce 'Xslate'?
We read it "/eks-leit/".
What 'Xslate' stands for?
It stands for XS template, a template engine written in XS, although
pure Perl implementations are also provided.
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 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
);
What version of perl does Xslate require?
Xslate is tested on perl v5.8.1. No special settings should be
required.
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.
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:
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.
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.
How can I change instance attributes dynamically?
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(...);
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.
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.
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!
}
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.
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.
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
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
Text::Xslate
Text::Xslate::Manual
Text::Xslate::Manual::Cookbook
perl v5.36.0 2022-10-20 Text::Xslate::Manual::FAQ(3pm)
Generated by dwww version 1.15 on Wed Jun 26 18:12:41 CEST 2024.