1Text::Xslate::Syntax::KUosleorn(C3o)ntributed Perl DocumTeenxtta:t:iXosnlate::Syntax::Kolon(3)
2
3
4
6 Text::Xslate::Syntax::Kolon - The default template syntax
7
9 use Text::Xslate;
10 my $tx = Text::Xslate->new(
11 syntax => 'Kolon', # optional
12 );
13
14 print $tx->render_string(
15 'Hello, <: $dialect :> world!',
16 { dialect => 'Kolon' }
17 );
18
20 Kolon is the default syntax, using "<: ... :>" tags and ": ..." line
21 code. In this syntax all the features in Xslate are available.
22
24 Variable access
25 Variable access:
26
27 <: $var :>
28
29 Field access:
30
31 <: $var.0 :>
32 <: $var.field :>
33 <: $var.accessor :>
34
35 <: $var["field"] :>
36 <: $var[0] :>
37
38 Variables may be HASH references, ARRAY references, or objects.
39 Because "$var.field" and $var["field"] are the same semantics,
40 $obj["accessor"] syntax may be call object methods.
41
42 Literals
43 Special:
44
45 : nil # as undef, indicating "nothing"
46 : true # as the integer 1
47 : false # as the integer 0
48
49 String:
50
51 : "foo\n" # the same as perl
52 : 'foo\n' # the same as perl
53
54 Number:
55
56 : 42
57 : 3.14
58 : 0xFF # hex
59 : 0777 # octal
60 : 0b1010 # binary
61
62 Array:
63
64 : for [1, 2, 3] -> $i { ... }
65
66 Hash:
67
68 : foo({ foo => "bar" })
69
70 Note that "{ ... }" is always parsed as hash literals, so you don't
71 need to use the <+> prefix as Perl sometimes requires:
72
73 : {}.kv(); # ok
74 : +{}.kv(); # also ok
75
76 Expressions
77 Conditional operator ("?:"):
78
79 : $var.value == nil ? "nil" : $var.value
80
81 Relational operators ("== != < <= > >="):
82
83 : $var == 10 ? "10" : "not 10"
84 : $var != 10 ? "not 10" : "10"
85
86 Note that "==" and "!=" are similar to Perl's "eq" and "ne" except that
87 "$var == nil" is true iff $var is uninitialized, while other relational
88 operators are numerical.
89
90 Arithmetic operators ("+ - * / % min max"):
91
92 : $var * 10_000
93 : ($var % 10) == 0
94 : 10 min 20 min 30 # 10
95 : 10 max 20 max 30 # 30
96
97 Bitwise operators ("prefix:<+^> +& +| +^")
98
99 : 0x1010 +| 0x3200 # bitwise or: 0x3210
100 : 0x1010 +& 0x3200 # bitwise and: 0x1000
101 : 0x1010 +^ 0x3200 # bitwise xor: 0x0210
102 : +^0x1010 # bitwise neg: 0xFFFFEFEF (on 32 bit system)
103
104 Logical operators ("! && || // not and or")
105
106 : $var >= 0 && $var <= 10 ? "ok" : "too smaller or too larger"
107 : $var // "foo" # as a default value
108
109 String operators ("~")
110
111 : "[" ~ $var ~ "]" # concatenation
112
113 The operator precedence is very like Perl's:
114
115 . () []
116 prefix:<!> prefix:<+> prefix:<-> prefix:<+^>
117 * / % x +&
118 + - ~ +| +^
119 prefix:<defined>
120 < <= > >=
121 == !=
122 |
123 &&
124 || // min max
125 ?:
126 not
127 and
128 or
129
130 Constants (or binding)
131 You can define lexical constants with "constant", which requires a bare
132 word, and "my", which requires a variable name.
133
134 : constant FOO = 42;
135 : my $foo = 42;
136
137 These two statements has the same semantics, so you cannot modify $foo.
138
139 : my $foo = 42; $foo = 3.14; # compile error!
140
141 Loops
142 There are "for" loops that are like Perl's "foreach".
143
144 : # iterate over an ARRAY reference
145 : for $data -> $item {
146 [<: $item.field :>]
147 : }
148
149 : # iterate over a HASH reference
150 : # You must specify how to iterate it (.keys(), .values() or .kv())
151 : for $data.keys() -> $key {
152 <: $key :>=<: $data[$key] :>
153 : }
154
155 And the "for" statement can take an "else" block:
156
157 : for $data -> $item {
158 [<: $item.field :>]
159 : }
160 : else {
161 Nothing in data
162 : }
163
164 The "else" block is executed if $data is an empty array or nil.
165
166 You can get the iterator index in "for" statements as "$~ITERATOR_VAR":
167
168 : for $data -> $item {
169 : if ($~item % 2) == 0 {
170 Even (0, 2, 4, ...)
171 : }
172 : else {
173 Odd (1, 3, 5, ...)
174 : }
175 : }
176
177 "$~ITERATOR_VAR" is a pseudo object, so you can access its elements via
178 the dot-name syntax.
179
180 : for $data -> $i {
181 : $~i # 0-origin iterator index (0, 1, 2, ...)
182 : $~i.index # the same as $~i
183 : $~i.count # the same as $~i + 1
184
185 : if ($~i.index % 2) == 0 {
186 even
187 : }
188 : else {
189 odd
190 : }
191 : $~i.cycle("even", "odd") # => "even" -> "odd" -> "even" -> "odd" ...
192 : }
193
194 Supported iterator elements are "index :Int", "count :Int", "body :
195 ArrayRef", "size : Int", "max_index :Int", "is_first :Bool", "is_last
196 :Bool", "peek_next :Any", "peek_prev :Any", "cycle(...) :Any".
197
198 "while" loops are also supported in the same semantics as Perl's:
199
200 : # $obj might be an iteratable object
201 : while $dbh.fetch() -> $item {
202 [<: $item.field :>]
203 : }
204
205 "while defined expr -> $item" is interpreted as "while defined(my $item
206 = expr)" for convenience.
207
208 : while defined $dbh.fetch() -> $item {
209 [<: $item # $item can be false-but-defined :>]
210 : }
211
212 Loop control statements, namely "next" and "last", are also supported
213 in both "for" and "while" loops.
214
215 : for $data -> $item {
216 : last if $item == 42
217 ...
218 : }
219
220 Conditional statements
221 There are "if-else" and "given-when" conditional statements.
222
223 "if-else":
224
225 : if $var == nil {
226 $var is nil.
227 : }
228 : else if $var != "foo" { # elsif is okay
229 $var is not nil nor "foo".
230 : }
231 : else {
232 $var is "foo".
233 : }
234
235 : if( $var >= 1 && $var <= 10 ) {
236 $var is 1 .. 10
237 : }
238
239 Note that "if" doesn't require parens, so the following code is okay:
240
241 : if ($var + 10) == 20 { } # OK
242
243 "given-when"(also known as switch statement):
244
245 : given $var {
246 : when "foo" {
247 it is foo.
248 : }
249 : when ["bar", "baz" ] {
250 it is either bar or baz.
251 : }
252 : default {
253 it is not foo nor bar.
254 }
255 : }
256
257 You can specify the topic variable.
258
259 : given $var -> $it {
260 : when "foo" {
261 it is foo.
262 : }
263 : when $it == "bar" or $it == "baz" {
264 it is either bar or baz.
265 : }
266 : }
267
268 Functions and filters
269 You can register functions via "function" or "module" options for
270 "Text::Xslate->new()".
271
272 Once you have registered functions, you can call them with the "()"
273 operator. "infix:<|>" is also supported as a syntactic sugar to "()".
274
275 : f() # without args
276 : f(1, 2, 3) # with args
277 : 42 | f # the same as f(42)
278
279 Functions are just Perl's subroutines, so you can define dynamic
280 functions (a.k.a. dynamic filters), which is a subroutine that returns
281 another subroutine:
282
283 # code
284 sub mk_indent {
285 my($prefix) = @_;
286 return sub {
287 my($str) = @_;
288 $str =~ s/^/$prefix/xmsg;
289 return $str;
290 }
291 }
292 my $tx = Text::Xslate->new(
293 function => {
294 indent => \&mk_indent,
295 },
296 );
297
298 :# template
299 : $value | indent("> ") # Template-Toolkit like
300 : indent("> ")($value) # This is also valid
301
302 "example/dynamic_functions.tx" has examples of dynamic functions being
303 used with block, function and filter syntax, and with scalar, hash and
304 array objects.
305
306 There are several builtin functions, which you cannot redefine:
307
308 : $var | mark_raw # marks it as a raw string
309 : $var | raw # synonym to mark_raw
310 : $var | unmark_raw # removes "raw" marker from it
311 : $var | html # does html-escape to it and marks it as raw
312 : $var | dump # dumps it with Data::Dumper
313
314 Note that you should not use "mark_raw" in templates because it can
315 make security hole easily just like as type casts in C. If you want to
316 generate HTML components dynamically, e.g. by HTML form builders,
317 application code should be responsible to make strings as marked "raw".
318
319 Methods
320 When $var is an object instance, you can call its methods with the dot
321 operator.
322
323 <: $var.method() :>
324 <: $var.method(1, 2, 3) :>
325 <: $var.method( foo => [ 1, 2, 3 ] ) :>
326
327 There is an autoboxing mechanism that provides primitive types with
328 builtin methods. See Text::Xslate::Manual::Builtin for details.
329
330 You can define more primitive methods with the "function" option. See
331 Text::Xslate.
332
333 Template inclusion
334 Template inclusion is a traditional way to extend templates.
335
336 : include "foo.tx";
337 : include "foo.tx" { var1 => value1, var2 => value2, ... };
338 : include "foo.tx" {$vars}; # use $vars as the params
339
340 if a var exist in the {$vars} and __ROOT__, the one in {$vars} will
341 win.
342
343 also, be careful about the order of vars.
344
345 : include "foo.tx" { var1 => $id, id => $var, var2 => $id }
346
347 var1 and var2 will be replaced by $id, var2 will be replaced by $var,
348 because the value of id is changed
349
350 As "cascade" does, "include" allows barewords:
351
352 : include foo # the same as 'foo.tx'
353 : include foo::bar # the same as 'foo/bar.tx'
354
355 Xslate templates may be recursively included, but the including depth
356 is limited to 100.
357
358 Template cascading
359 Template cascading is another way to extend templates other than
360 "include".
361
362 First, make base templates myapp/base.tx:
363
364 : block title -> { # with default
365 [My Template!]
366 : }
367
368 : block body -> { } # without default
369
370 Then extend from base templates with the "cascade" keyword:
371
372 : cascade myapp::base
373 : cascade myapp::base { var1 => value1, var2 => value2, ...}
374 : cascade myapp::base with myapp::role1, myapp::role2
375 : cascade with myapp::role1, myapp::role2
376
377 In derived templates, you may extend templates (e.g. myapp/foo.tx) with
378 block modifiers "before", "around" (or "override") and "after".
379
380 : # cascade "myapp/base.tx" is also okay
381 : cascade myapp::base
382 : # use default title
383 : around body -> {
384 My template body!
385 : }
386
387 And, make yet another derived template myapp/bar.tx:
388
389 : cascade myapp::foo
390 : around title -> {
391 --------------
392 : super
393 --------------
394 : }
395 : before body -> {
396 Before body!
397 : }
398 : after body -> {
399 After body!
400 : }
401
402 Then render it as usual.
403
404 my $tx = Text::Xslate->new( file => 'myapp/bar.tx' );
405 $tx->render({});
406
407 The result is something like this:
408
409 --------------
410 [My Template!]
411 --------------
412
413 Before body!
414 My template body!
415 After body!
416
417 You can also cascade templates just like Moose's roles:
418
419 : cascade myapp::base with myapp::role1, myapp::role2
420
421 You can omit the base template.
422
423 Given a file myapp/hello.tx:
424
425 : around hello -> {
426 --------------
427 : super
428 --------------
429 : }
430
431 Then the main template:
432
433 : cascade with myapp::hello
434
435 : block hello -> {
436 Hello, world!
437 : }
438
439 Output:
440
441 --------------
442 Hello, world!
443 --------------
444
445 In fact, you can omit the base template, and components can include any
446 macros.
447
448 Given a file common.tx
449
450 : macro hello -> $lang {
451 Hello, <: $lang :> world!
452 : }
453
454 : around title -> {
455 --------------
456 : super
457 --------------
458 : }
459
460 The main template:
461
462 : cascade with common
463
464 : block title -> {
465 Hello, world!
466 : }
467 : hello("Xslate")
468
469 Output:
470
471 --------------
472 Hello, world!
473 --------------
474 Hello, Xslate world!
475
476 There is a limitation that you cannot pass variables to the "cascade"
477 keyword, because template cascading is statically processed.
478
479 Macro blocks
480 Macros are supported, which are called in the same way as functions and
481 return a "raw" string. Macros return what their bodies render, so they
482 cannot return references or objects, including other macros.
483
484 : macro add ->($x, $y) {
485 : $x + $y;
486 : }
487 : add(10, 20)
488
489 : macro signature -> {
490 This is foo version <: $VERSION :>
491 : }
492 : signature()
493
494 : macro factorial -> $x {
495 : $x == 0 ? 1 : $x * factorial($x-1)
496 : }
497 : factorial(1) # as a function
498 : 1 | factorial # as a filter
499
500 If you want to html-escape the return values of macros, you can use
501 "unmark_raw" to remove "raw-ness" from the values.
502
503 : macro em -> $s {
504 <em><: $s :></em>
505 : }
506 : em("foo") # renders "<em>foo</em>"
507 : em("foo") | unmark_raw # renders "<em>foo<em>"
508
509 Because macros are first-class objects, you can bind them to symbols.
510
511 <: macro foo -> { "foo" }
512 macro bar -> { "bar" }
513 my $dispatcher = {
514 foo => foo,
515 bar => bar,
516 }; -:>
517 : $dispatcher{$key}()
518
519 Anonymous macros are also supported, although they can return only
520 strings. They might be useful for callbacks to high-level functions or
521 methods.
522
523 <: -> $x, $y { $x + $y }(1, 2) # => 3 :>
524
525 The "block" keyword is used to make a group of template code, and you
526 can apply filters to that block with "infix:<|>". Here is an example
527 to embed HTML source code into templates.
528
529 Template:
530
531 : block source | unmark_raw -> {
532 <em>Hello, world!</em>
533 : }
534
535 Output:
536
537 <em>Hello, world!</em>
538
539 See also "Using FillInForm" in Text::Xslate::Manual::Cookbook for
540 another example to use this block filter syntax.
541
542 Note that closures are not supported.
543
544 Chomping newlines
545 You can add "-" to the immediate start or end of a directive tag to
546 control the newline chomping options to keep the output clean. The
547 starting "-" removes leading newlines and the ending "-" removes
548 trailing ones.
549
550 Special keywords
551 There are special keywords:
552
553 __FILE__
554 Indicates the current file name. Equivalent to
555 "Text::Xslate->current_file".
556
557 __LINE__
558 Indicates the current line number. Equivalent to
559 "Text::Xslate->current_line".
560
561 __ROOT__
562 Means the root of the parameters. Equivalent to
563 "Text::Xslate->current_vars".
564
565 Comments
566 Comments start from "#" to a new line or semicolon.
567
568 :# this is a comment
569 <:
570 # this is also a comment
571 $foo # $foo is rendered
572 :>
573
574 <: $bar # this is ok :>
575 <: # this is comment; $baz # $baz is rendered :>
576
578 Text::Xslate
579
580
581
582perl v5.30.1 2019-11-26 Text::Xslate::Syntax::Kolon(3)