Text::Xslate::Syntax::TTerse(3pm)

1Text::Xslate::Syntax::TUTseerrseC(o3n)tributed Perl DocuTmeexntt:a:tXisolnate::Syntax::TTerse(3)
2
3
4

NAME

6       Text::Xslate::Syntax::TTerse - An alternative syntax compatible with
7       Template Toolkit 2
8

SYNOPSIS

10           use Text::Xslate;
11           my $tx = Text::Xslate->new(
12               syntax => 'TTerse',
13           );
14
15           print $tx->render_string(
16               'Hello, [% dialect %] world!',
17               { dialect => 'TTerse' }
18           );
19
20           # PRE_PROCESS/POST_PROCESS
21           $tx = Text::Xslate->new(
22               syntax => 'TTerse',
23               header => ['header.tt'],
24               footer => ['footer.tt'],
25           );
26

DESCRIPTION

28       TTerse is a subset of the Template-Toolkit 2 (and partially  3) syntax,
29       using "[% ... %]" tags and "%% ..." line code.
30
31       Note that TTerse itself has few methods and filters while Template-
32       Toolkit 2 has a lot. See "Text::Xslate::Bridge::*" modules on CPAN
33       which provide extra methods and filters if you want to use those
34       features.
35
36       (TODO: I should concentrate on the difference between Template-Toolkit
37       2 and TTerse)
38

SYNTAX

40       This supports a Template-Toolkit compatible syntax, although the
41       details might be different.
42
43       Note that lower-cased keywords, which are inspired in Template-Toolkit
44       3, are also allowed.
45
46   Variable access
47       Scalar access:
48
49           [%  var %]
50           [% $var %]
51           [% GET var # 'GET' is optional %]
52
53       Field access:
54
55           [% var.0 %]
56           [% var.field %]
57           [% var.accessor %]
58           [% var.$field ]%
59           [% var[$field] # TTerse specific %]
60
61       Variables may be HASH references, ARRAY references, or objects.
62
63       If $var is an object instance, you can call its methods.
64
65           [% $var.method() %]
66           [% $var.method(1, 2, 3) %]
67           [% $var.method(foo => [1, 2, 3]) %]
68           [% $var.method({ foo => 'bar' }) %]
69
70   Expressions
71       Almost the same as Text::Xslate::Syntax::Kolon, but "infix:<_>" for
72       concatenation is supported for compatibility.
73
74   Loops
75           [% FOREACH item IN arrayref %]
76               * [% item %]
77           [% END %]
78
79       Loop iterators are partially supported.
80
81           [% FOREACH item IN arrayref %]
82               [%- IF loop.is_first -%]
83               <first>
84               [%- END -%]
85               * [% loop.index %]  # 0 origin
86               * [% loop.count     # loop.index + 1 %]
87               * [% loop.body      # alias to arrayref %]
88               * [% loop.size      # loop.body.size %]
89               * [% loop.max_index # loop.size - 1 %]
90               * [% loop.peek_next # loop.body[ loop.index + 1 %]
91               * [% loop.peek_prev # loop.body[ loop.index - 1 %]
92               [%- IF loop.is_last -%]
93               <last>
94               [%- END -%]
95           [% END %]
96
97       Unlike Template-Toolkit, "FOREACH" doesn't accept a HASH reference, so
98       you must convert HASH references to ARRAY references by "keys()",
99       "values()", or "kv()" methods.
100
101       Template-Toolkit compatible names are also supported, but the use of
102       them is discouraged because they are not easy to understand:
103
104           loop.max   # for loop.max_index
105           loop.next  # for loop.peek_next
106           loop.prev  # for loop.peek_prev
107           loop.first # for loop.is_first
108           loop.last  # for loop.is_last
109
110       Loop control statements, namely "NEXT" and "LAST", are also supported
111       in both "FOR" and "WHILE" loops.
112
113           [% FOR item IN data -%]
114               [% LAST IF item == 42 -%]
115               ...
116           [% END -%]
117
118   Conditional statements
119           [% IF logical_expression %]
120               Case 1
121           [% ELSIF logical_expression %]
122               Case 2
123           [% ELSE %]
124               Case 3
125           [% END %]
126
127           [% UNLESS logical_expression %]
128               Case 1
129           [% ELSE %]
130               Case 2
131           [% END %]
132
133           [% SWITCH expression %]
134           [% CASE case1 %]
135               Case 1
136           [% CASE case2 %]
137               Case 2
138           [% CASE DEFAULT %]
139               Case 3
140           [% END %]
141
142   Functions and filters
143           [% var | f %]
144           [% f(var)  %]
145
146   Template inclusion
147       The "INCLUDE" statement is supported.
148
149           [% INCLUDE "file.tt" %]
150           [% INCLUDE $var %]
151
152       "WITH variables" syntax is also supported, although the "WITH" keyword
153       is optional in Template-Toolkit:
154
155           [% INCLUDE "file.tt" WITH foo = 42, bar = 3.14 %]
156           [% INCLUDE "file.tt" WITH
157               foo = 42
158               bar = 3.14
159           %]
160
161       The "WRAPPER" statement is also supported.  The argument of "WRAPPER",
162       however, must be string literals, because templates will be statically
163       linked while compiling.
164
165           [% WRAPPER "file.tt" %]
166           Hello, world!
167           [% END %]
168
169           %%# with variable
170           [% WRAPPER "file.tt" WITH title = "Foo!" %]
171           Hello, world!
172           [% END %]
173
174       The content will be set into "content", but you can specify its name
175       with the "INTO" keyword.
176
177           [% WRAPPER "foo.tt" INTO wrapped_content WITH title = "Foo!" %]
178           ...
179           [% END %]
180
181       This is a syntactic sugar to template cascading. Here is a counterpart
182       of the example in Kolon.
183
184           : macro my_content -> {
185               Hello, world!
186           : }
187           : cascade "file.tx" { content => my_content() }
188
189       Note that the WRAPPER option
190       (<http://template-toolkit.org/docs/manual/Config.html#section_WRAPPER>)
191       in Template-Toolkit is not supported directly. Instead, you can emulate
192       it with "header" and "footer" options as follows:
193
194           my %vpath = (
195               wrap_begin => '[% WRAPPER "base" %]',
196               wrap_end => '[% END %]',
197
198               base => 'Hello, [% content %] world!' . "\n",
199               content => 'Xslate',
200           );
201
202           my $tx = Text::Xslate->new(
203               syntax => 'TTerse',
204               path => \%vpath,
205
206               header => ['wrap_begin'],
207               footer => ['wrap_end'],
208           );
209
210           print $tx->render('content'); # => Hello, Xslate world!;
211
212   Macro blocks
213       Definition:
214
215           [% MACRO foo BLOCK -%]
216               This is a macro.
217           [% END -%]
218
219           [% MACRO add(a, b) BLOCK -%]
220           [%  a + b -%]
221           [% END -%]
222
223       Call:
224
225           [% foo()     %]
226           [% add(1, 2) %]
227
228       Unlike Template-Toolkit, calling macros requires parens ("()").
229
230   Virtual methods
231       A few methods are supported in the Xslate core.
232
233           %% a.size();
234           %% a.join(", ");
235           %% a.reverse();
236
237           %% h.size();
238           %% h.keys();
239           %% h.values();
240           %% h.kv();
241
242       However, there is a bridge mechanism that allows you to use external
243       methods.  For example, Text::Xslate::Bridge::TT2 provides the TT2
244       virtual methods for Xslate, which bridges Template::VMethods
245       implementation.
246
247           use Text::Xslate::Bridge::TT2;
248
249           my $tx = Text::Xslate->new(
250               syntax => 'TTerse',
251               module => [qw(Text::Xslate::Bridge::TT2)],
252           );
253
254          print $tx->render_string('[% "foo".length() %]'); # => 3
255
256       See Text::Xslate::Bridge, or search for "Text::Xslate::Bridge::*" on
257       CPAN.
258
259   Misc.
260       CALL evaluates expressions, but does not print it.
261
262           [% CALL expr %]
263
264       SET and assignments, although the use of them are strongly discouraged.
265
266           [% SET var1 = expr1, var2 = expr2 %]
267           [% var = expr %]
268
269       DEFAULT statements as a syntactic sugar to "SET var = var // expr":
270
271           [% DEFAULT lang = "TTerse" %]
272
273       FILTER blocks to apply filters to text sections:
274
275           [% FILTER html -%]
276           Hello, <Xslate> world!
277           [% END -%]
278

COMPATIBILITY

280       There are some differences between TTerse and Template-Toolkit.
281
282       ·   "INCLUDE" of TTerse requires an expression for the file name, while
283           that of Template-Toolkit allows a bare token:
284
285               [% INCLUDE  foo.tt  # doesn't work! %]
286               [% INCLUDE "foo.tt" # OK %]
287
288       ·   "FOREACH item = list" is forbidden in TTerse. It must be "FOREACH
289           item IN list".
290
291       ·   TTerse does not support plugins (i.e. "USE" directive), but
292           understands the "USE" keyword as an alias to "CALL", so you could
293           use some simple plugins which do not depend on the context object
294           of Template-Toolkit.
295
296               use Template::Plugin::Math;
297               use Template::Plugin::String;
298
299               my $tt = Text::Xslate->new(...);
300
301               mt %vars = (
302                   Math   => Template::Plugin::Math->new(),   # as a namespace
303                   String => Template::Plugin::String->new(), # as a prototype
304               );
305               print $tt->render_string(<<'T', \%vars);
306               [% USE Math # does nothing actually, only for compatibility %]
307               [% USE String %]
308               [% Math.abs(-100)          # => 100 %]
309               [% String.new("foo").upper # => FOO %]
310
311       ·   The following directives are not supported: "INSERT", "PROCESS",
312           "BLOCK" as a named blocks, "USE" (but see above), "PERL",
313           "RAWPERL", "TRY", "THROW", "RETURN", "STOP", "CLEAR", "META",
314           "TAGS", "DEBUG", and "VIEW".
315
316           Some might be supported in a future.
317

NAME

SYNOPSIS

DESCRIPTION

SYNTAX

COMPATIBILITY

SEE ALSO