1Text::Xslate::Manual::FUAsQe(r3)Contributed Perl DocumenTteaxtti:o:nXslate::Manual::FAQ(3)
2
3
4

NAME

6       Text::Xslate::Manual::FAQ - Frequently asked questions and answers
7

DESCRIPTION

9       This manual page lists FAQs, which we've heard for now.
10

QUESTIONS

12   General
13       How do you pronounce 'Xslate'?
14
15       We read it "/eks-leit/".
16
17       What 'Xslate' stands for?
18
19       It stands for XS template, a template engine written in XS, although
20       pure Perl implementations are also provided.
21
22       What are 'Kolon', 'Metakolon', and 'TTerse' ?
23
24       Xslate supports multiple template syntaxes. Kolon is the default
25       syntax, Metakolon is suitable to output Kolon templates, and TTerse is
26       compatible with Template-Toolkit 2. You can specify the template syntax
27       by passing "syntax" option to the Text::Xslate constructor.
28
29           my $tx = Text::Xslate->new(
30               syntax => 'TTerse', # by moniker
31           );
32
33           my $tx = Text::Xslate->new(
34               syntax => 'Text::Xslate::Syntax::TTerse', # by fully qualified name
35           );
36
37       What version of perl does Xslate require?
38
39       Xslate is tested on perl v5.8.1. No special settings should be
40       required.
41
42       How can I install the pure-Perl version of Xslate?
43
44       Pass "PUREPERL_ONLY=1" to Makefile.PL, which requests the Xslate build
45       system not to make XS parts.
46
47       Note that "cpanm 1.7" supports "--pp" option to install pure-Perl
48       alternatives, so you can type "cpanm --pp Text::Xslate".
49
50       What optimizations does Xslate employs?
51
52       Here are some optimizations worth noting that makes Text::Xslate run so
53       fast, in no particular order:
54
55       Pre-compiled templates
56           Text::Xslate is among the template engines that pre-compile the
57           templates.  This is similar to, say, Template::Toolkit, but
58           Text::Xslate compiles the templates to C structures and stores them
59           as binary data.
60
61       Built on top of a virtual machine
62           Text::Xslate is built on top of virtual machine that executes
63           bytecode, and this virtual machine is fine-tuned specifically for
64           template processing.
65
66           The virtual machine also employs optimizations such as direct-
67           threading style coding to shave off any extra milliseconds that the
68           engine might take otherwise
69
70       Custom byte codes for oft-used operations
71           Some operations which are used very often are optimized into its
72           own byte code. For example (as described elsewhere) Text::Xslate
73           automatically escapes HTML unless you tell it not to. Text::Xslate
74           implements this process which involves escaping the string while
75           appending the result to the output buffer in C, as a custom byte
76           code. This lets you avoid the penalties usually involved in such
77           operations.
78
79       Pre-allocation of output buffers
80           One of the main things to consider to reduce performance
81           degradation while processing a template is to avoid the number of
82           calls to malloc().  One of the tricks that Text::Xslate employs to
83           reduce the number of calls to malloc() is to pre-allocate the
84           output buffer in an intelligent manner: For example, Text::Xslate
85           assumes that most templates will be rendered to be about the same
86           as the previous run, so when a template is rendered it uses the
87           size allocated for the previous rendering as an approximation of
88           how much space the current rendering will require. This allows you
89           to greatly reduce the number of malloc() calls required to render a
90           template.
91
92       How can I throw errors in functions and/or methods?
93
94       Handle warnings by "warn_handler" and raises exceptions if needed.
95
96       That's because Xslate catches exceptions in templates and emits them as
97       warnings.
98
99   Configuration
100       When should I create the Xslate instance?
101
102       Xslate instances are reusable and creating the instance costs somewhat
103       so you're recommended to reuse them as much as possible.  That is, you
104       should make the instance global.
105
106       Consider a PSGI application:
107
108           # create Xslate here, not in psgi_app();
109           my $xslate = Text::Xslate->new(...);
110
111           sub psgi_app {
112               my($env) = @_;
113               # use $xslate and create $response
114               return $response;
115           }
116           return \&psgi_app; # as a PSGI app
117
118       Don't create the instance in each request. It's less efficient.
119
120       How can I change instance attributes dynamically?
121
122       Instance attributes, e.g. "include_path", "function", or "syntax", are
123       immutable, so you cannot change them dynamically.
124
125       Instead, you can create multiple instances by different options.
126       instance in order to avoid conflicts with cache directories.
127
128       For example:
129
130           my %common_config = ( cache_dir => $dir, module => \@module );
131           my %xslate = (
132               ja => Text::Xslate->new( path => [ $template_ja ], %common_config ),
133               en => Text::Xslate->new( path => [ $template_en ], %common_config ),
134               ro => Text::Xslate->new( path => [ $template_ro ], %common_config ),
135           );
136           $xslate{$lang}->render(...);
137
138   Templates
139       How can I changes template tags?
140
141       Use "start_tag", "end_tag", and "line_start" options to "new" method,
142       which can be joined together with "syntax" option:
143
144           my $tx = Text::Xslate->new(
145               syntax     => 'TTerse',
146               tag_start  => '{{',
147               tag_end    => '}}',
148               line_start => undef,
149           );
150           print $tx->render_string('Hello, {{lang}} world!', { lang => 'Xslate' });
151
152       Note that you'd better to avoid symbols which can be used for
153       operators.
154
155       How can I iterate over HASH references?
156
157       Convert HASH references into ARRAY references because "for" methods can
158       deal with just ARRAY references.
159
160           : # in Kolon
161           : # iterate $hash by keys
162           : for $hash.keys() -> $key {
163               <: $key :>
164           : }
165           : # by values
166           : for $hash.values() -> $value {
167               <: $value :>
168           : }
169           : # by key-value pairs
170           : for $hash.kv() -> $pair {
171               <: $pair.key :>=<: $pair.value :>
172           : }
173
174       Note that the above methods return ARRAY references sorted by the keys.
175
176       How can I use Template-Toolkit virtual methods and filters?
177
178       Xslate itself does not support these methods and filters, but there are
179       modules on CPAN that implement them.
180
181       Text::Xslate::Bridge::TT2 provides almost all the TT methods and
182       filters, but it requires Template-Toolkit installed.
183
184       Text::Xslate::Bridge::TT2Like provides the same features as
185       "T::X::Bridge::TT2", and it does not require the Template-Toolkit
186       runtime.
187
188       These bridge modules are useful not only for TTerse users, but also for
189       Kolon users.
190
191       How can I (write|get) plugins?
192
193       It is unlikely to need to write plugins for Xslate, because Xslate
194       allows you to export any functions to templates. Any function-based
195       modules are available by the "module" option.
196
197       Xslate also allows you to call methods for object instances, so you can
198       use any object-oriented modules, except for classes which only provide
199       class methods (they need wrappers).
200
201       If you want to add methods to builtin data types (nil, scalars, arrays
202       and hashes), you can write bridge modules. See Text::Xslate::Bridge for
203       details.
204
205       How to limit while-loop like Template-Toolkit?
206
207       While Template-Toolkit has a loop counter to prevent runaway "WHILE"
208       loop, Xslate has no arbitrary limitation.
209
210       Instead, you can use alarm() to limit any runaway code:
211
212           eval {
213               local $SIG{ALRM} = sub { die @_ };
214               alarm(1); # set timeout
215               $tx->render('<: while true { } :>', \%vars);
216           };
217           if($@ =~ /\b ALRM \b/xms) {
218               # timeout!
219           }
220
221       Does Xslate process text strings, or binary strings?
222
223       (The meaning of text string and binary string is that of Perl, see
224       perlunifaq.)
225
226       Xslate assumes template files to be encoded in "UTF-8" by default, so
227       the output is a text string and template parameters, including values
228       which registered functions return, must be text strings.
229
230       However, if you want to process binary strings, you can do so by
231       passing ":bytes" to "input_layer", although it's not recommended.
232
233       Why doesn't I cannot access $object.attr like TT2?
234
235       Template-Toolkit allows objects (i.e. blessed references) to access its
236       element if the object has no accessor methods, i.e. "[% object.attr %]"
237       might mean "$object->{attr}". This behavior breaks encapsulation and
238       hides typos, so Xslate doesn't allow such fallbacks.
239
240       If you want to access object attributes, define the accessors of them,
241       or prepare values as a non-object before calling render().
242
243       Can I load macros in other template files?
244
245       Not yet. Currently Xslate doesn't support external macros.
246
247   Functions, filters and macros
248       Where are the list of builtin functions?
249
250       See Text::Xslate::Manual::Builtin.
251
252       How can I use macros as a callback to high-level functions?
253
254       Macros are objects that overload "&{}", the CODE dereference operator,
255       so all you have to do is to call them simply, but don't check their
256       types because they are not a real CODE reference.
257
258           my $tx = Text::Xslate->new(
259               function => {
260                   count => sub {
261                       my($a, $cb) = @_;
262                       # Don't check the type of $cb!
263                       return scalar grep { $cb->($_) } @{$a};
264                   },
265               },
266           );
267
268           print $tx->render_string('<: count($a, -> $x { $x >= 50 }) :>',
269               { a => [ 0 .. 100 ] },
270           ); # => 50
271
272   Web Application Frameworks
273       How can I use Xslate in $my_favorite_WAF?
274
275       There are bridges that integrate Xslate into WAFs:
276
277       •   Catalyst::View::Xslate for Catalyst
278
279       •   MojoX::Renderer::Xslate for Mojolicious
280
281       •   Tiffany for general usage
282
283       There are WAFs which adopt Xslate as the default template engine:
284
285       •   Amon2
286
287       •   Pickles
288
289       Where are examples which use Xslate in Catalyst?
290
291       There is a real-world project that uses Xslate with Catalyst.
292
293       <https://github.com/duckduckgo/community-platform>
294
295       Initializing Xslate:
296       <https://github.com/duckduckgo/community-platform/blob/master/lib/DDGC.pm#L268>
297
298       Working on: <https://dukgo.com/>
299
300       Enjoy!
301
302   Development and support
303       How can I colorize Xslate templates?
304
305       For "vim" user, there is xslate.vim for Kolon:
306
307       <https://github.com/motemen/xslate-vim>
308
309       For "emacs" user, there are plugins:
310
311       <https://github.com/samvtran/kolon-mode>
312
313       <https://github.com/yoshiki/tx-mode>
314
315       Where can I ask questions?
316
317       The mailing list is recommended to ask questions.
318
319       <http://groups.google.com/group/xslate>
320
321       If you find a bug or have a request, creating github issues is better
322       because those tickets are less likely to disappear than the ports in
323       the mailing list.
324
325       <https://github.com/xslate/p5-Text-Xslate/issues>
326
327       I found a bug! What can I do for you?
328
329       Please make a minimal test case to show the problem clearly.  The code
330       is the common language both I and you speak fluently ;)
331

SEE ALSO

333       Text::Xslate
334
335       Text::Xslate::Manual
336
337       Text::Xslate::Manual::Cookbook
338
339
340
341perl v5.36.0                      2023-01-20      Text::Xslate::Manual::FAQ(3)
Impressum