1Text::Xslate::Manual::FUAsQe(r3)Contributed Perl DocumenTteaxtti:o:nXslate::Manual::FAQ(3)
2
6 Text::Xslate::Manual::FAQ - Frequently asked questions and answers
7
9 This manual page lists FAQs, which we've heard for now.
10
12 General
13 How do you pronounce 'Xslate'?
14 We read it "/eks-leit/".
16 What 'Xslate' stands for?
18 It stands for XS template, a template engine written in XS, although
20 pure Perl implementations are also provided.
21 What are 'Kolon', 'Metakolon', and 'TTerse' ?
23 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 my $tx = Text::Xslate->new(
30 syntax => 'TTerse', # by moniker
31 );
32 my $tx = Text::Xslate->new(
34 syntax => 'Text::Xslate::Syntax::TTerse', # by fully qualified name
35 );
36 What version of perl does Xslate require?
38 Xslate is tested on perl v5.8.1. No special settings should be
40 required.
41 How can I install the pure-Perl version of Xslate?
43 Pass "PUREPERL_ONLY=1" to Makefile.PL, which requests the Xslate build
45 system not to make XS parts.
46 Note that "cpanm 1.7" supports "--pp" option to install pure-Perl
48 alternatives, so you can type "cpanm --pp Text::Xslate".
49 What optimizations does Xslate employs?
51 Here are some optimizations worth noting that makes Text::Xslate run so
53 fast, in no particular order:
54 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 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 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 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 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
83 to 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
90 a template.
91 How can I throw errors in functions and/or methods?
93 Handle warnings by "warn_handler" and raises exceptions if needed.
95 That's because Xslate catches exceptions in templates and emits them as
97 warnings.
98 Configuration
100 When should I create the Xslate instance?
101 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 Consider a PSGI application:
107 # create Xslate here, not in psgi_app();
109 my $xslate = Text::Xslate->new(...);
110 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 Don't create the instance in each request. It's less efficient.
119 How can I change instance attributes dynamically?
121 Instance attributes, e.g. "include_path", "function", or "syntax", are
123 immutable, so you cannot change them dynamically.
124 Instead, you can create multiple instances by different options.
126 instance in order to avoid conflicts with cache directories.
127 For example:
129 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 Templates
139 How can I changes template tags?
140 Use "start_tag", "end_tag", and "line_start" options to "new" method,
142 which can be joined together with "syntax" option:
143 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 Note that you'd better to avoid symbols which can be used for
153 operators.
154 How can I iterate over HASH references?
156 Convert HASH references into ARRAY references because "for" methods can
158 deal with just ARRAY references.
159 : # 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 Note that the above methods return ARRAY references sorted by the keys.
175 How can I use Template-Toolkit virtual methods and filters?
177 Xslate itself does not support these methods and filters, but there are
179 modules on CPAN that implement them.
180 Text::Xslate::Bridge::TT2 provides almost all the TT methods and
182 filters, but it requires Template-Toolkit installed.
183 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 These bridge modules are useful not only for TTerse users, but also for
189 Kolon users.
190 How can I (write|get) plugins?
192 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 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 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 How to limit while-loop like Template-Toolkit?
206 While Template-Toolkit has a loop counter to prevent runaway "WHILE"
208 loop, Xslate has no arbitrary limitation.
209 Instead, you can use "alarm()" to limit any runaway code:
211 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 Does Xslate process text strings, or binary strings?
222 (The meaning of text string and binary string is that of Perl, see
224 perlunifaq.)
225 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 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 Why doesn't I cannot access $object.attr like TT2?
234 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 If you want to access object attributes, define the accessors of them,
241 or prepare values as a non-object before calling "render()".
242 Can I load macros in other template files?
244 Not yet. Currently Xslate doesn't support external macros.
246 Functions, filters and macros
248 Where are the list of builtin functions?
249 See Text::Xslate::Manual::Builtin.
251 How can I use macros as a callback to high-level functions?
253 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 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 print $tx->render_string('<: count($a, -> $x { $x >= 50 }) :>',
269 { a => [ 0 .. 100 ] },
270 ); # => 50
271 Web Application Frameworks
273 How can I use Xslate in $my_favorite_WAF?
274 There are bridges that integrate Xslate into WAFs:
276 • Catalyst::View::Xslate for Catalyst
278 • MojoX::Renderer::Xslate for Mojolicious
280 • Tiffany for general usage
282 There are WAFs which adopt Xslate as the default template engine:
284 • Amon2
286 • Pickles
288 Where are examples which use Xslate in Catalyst?
290 There is a real-world project that uses Xslate with Catalyst.
292 <https://github.com/duckduckgo/community-platform>
294 Initializing Xslate:
296 <https://github.com/duckduckgo/community-platform/blob/master/lib/DDGC.pm#L268>
297 Working on: <https://dukgo.com/>
299 Enjoy!
301 Development and support
303 How can I colorize Xslate templates?
304 For "vim" user, there is xslate.vim for Kolon:
306 <https://github.com/motemen/xslate-vim>
308 For "emacs" user, there are plugins:
310 <https://github.com/samvtran/kolon-mode>
312 <https://github.com/yoshiki/tx-mode>
314 Where can I ask questions?
316 The mailing list is recommended to ask questions.
318 <http://groups.google.com/group/xslate>
320 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 <https://github.com/xslate/p5-Text-Xslate/issues>
326 I found a bug! What can I do for you?
328 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
333 Text::Xslate
334 Text::Xslate::Manual
336 Text::Xslate::Manual::Cookbook
338perl v5.34.0 2022-01-21 Text::Xslate::Manual::FAQ(3)