Text::Xslate::Manual::Builtin(3pm)

1Text::Xslate::Manual::BUusielrtiCno(n3t)ributed Perl DocTuemxetn:t:aXtsiloante::Manual::Builtin(3)
2
3
4

NAME

6       Text::Xslate::Manual::Builtin - Builtin methods and filters/functions
7       in Xslate
8

DESCRIPTION

10       This document describes builtin methods and filters/functions in
11       Xslate.
12
13       Note that the xslate engine is not aware of context, so all the methods
14       and filters/functions return a single value, even when the equivalent
15       of Perl's returns a list of values.
16
17       Note that optional functions are defined in Text::Xslate::Bridge::Star.
18

METHODS

20       The xslate engine supports auto-boxing, so you can call methods for
21       primitive (non-object) values.  The following are builtin methods.
22
23   For nil
24       "nil" has its specific namespace as "nil", although no builtin methods
25       are provided.
26
27   For SCALARs
28       The namespace of SCALARs is "scalar", although no builtin methods are
29       provided.
30
31   For ARRAY references
32       The namespace of ARRAY references is "array".
33
34       "$arrayref.first()"
35
36       Returns the first element of $arrayref.
37
38       "$arrayref.last()"
39
40       Returns the last element of $arrayref.
41
42       "$arrayref.size()"
43
44       Returns the number of elements in $arrayref.
45
46       "$arrayref.join($separator)"
47
48       Joins the elements of $arrayref into a single string separated by
49       $separator.
50
51       "$arrayref.reverse()"
52
53       Returns an ARRAY reference consisting of the elements of $arrayref in
54       the opposite order.
55
56       "$arrayref.sort(?$callback)"
57
58       Sorts $arrayref and returns a new ARRAY reference.  The optional
59       $callback is the same as Perl's.
60
61       Examples:
62
63           : my $arrayref = [2, 1, 10];
64           : # alphabetic sort (default)
65           : $arrayref.sort().join(" "); # 1 10 2
66           : # explicitly alphabetic
67           : $arrayref.sort(-> $a, $b { $a cmp $b }).join(" "); # 1 10 2
68           : # numeric sort
69           : $arrayref.sort(-> $a, $b { $a <=> $b }).join(" "); # 1 2 10
70
71       See also "sort" in perlfunc.
72
73       "$arrayref.map($callback)"
74
75       Evaluates $callback for each element of $arrayref and returns a new
76       ARRAY reference composed of the result of each such evaluation.
77
78       Examples:
79
80           : my $arrayref = [1, 2, 4, 8, 16];
81           : # double
82           : $arrayref.map(-> $a { $a * 2 }).join(','); # 2,4,8,16,32
83           : # sequence
84           : my $hashref = {a => 1, b => 2, c => 3, d => 4};
85           : ['b', 'd', 'a'].map(-> $a {$hashref[$a]}).join(','); # 2,4,1
86
87       See also "map" in perlfunc
88
89       "$arrayref.reduce($callback)"
90
91       Reduces $arrayref by calling $callback multiple times.  If $arrayref is
92       empty, this method returns "nil".
93
94       Examples:
95
96           : my $arrayref = [10, 20, 30];
97           : # sum
98           : $arrayref.reduce(-> $a, $b { $a + $b }); # 60
99           : # concat
100           : $arrayref.reduce(-> $a, $b { $a ~ $b }); # 102030
101           : # min
102           : $arrayref.reduce(-> $a, $b { $a min $b }); # 10
103           : # max
104           : $arrayref.reduce(-> $a, $b { $a max $b }); # 30
105
106       See also "reduce" in List::Util.
107
108       "$arrayref.merge($v)"
109
110       Returns a new ARRAY reference consisting of $arrayref and $v.
111
112       $v may be an ARRAY reference or a scalar value.
113
114   For HASH references
115       The namespace of HASH references is "hash".
116
117       "$hashref.size()"
118
119       Returns the number of entries of $hashref.
120
121           : my $hashref = {a => 1, b => 2, c => 3, d => 4};
122           : $hashref.size(); # 4
123
124       "$hashref.keys()"
125
126       Returns an ARRAY reference consisting of the keys of $hashref, which
127       are sorted by the keys.
128
129           : my $hashref = {a => 1, b => 2, c => 3, d => 4};
130           : $hashref.keys().join(' '); # a b c d
131
132       "$hashref.values()"
133
134       Returns an ARRAY reference consisting of the values of $hashref, which
135       are sorted by the keys.
136
137           : my $hashref = {a => 1, b => 2, c => 3, d => 4};
138           : $hashref.values().join(' '); # 1 2 3 4
139
140       "$hashref.kv()"
141
142       Returns an ARRAY reference consisting of the key-value pairs of
143       $hashref, which are sorted by the keys. Each pair is an object that has
144       the "keys" and "value" attributes.
145
146       For example:
147
148           : for $hashref.kv() -> $pair {
149               <: $pair.key :>=<: $pair.value :>
150           : }
151
152       Output:
153
154           a=1
155           b=2
156           c=3
157           d=4
158
159       "$hashref.merge($v)"
160
161       Returns a new HASH reference consisting of $hashref and $v.
162
163           : my $hashref = {a => 1, b => 2, c => 3, d => 4};
164           : my $new = $hashref.merge({a => 0, e => 5});
165           : # {a => 0, b => 2, c => 3, d => 4, e => 5}
166
167       $v must be a HASH reference.
168

LOOP VARIABLES

170       You can use special loop variables in "for" loops, although its forms
171       vary in template syntaxes, i.e. "$~item" in Kolon and "loop" in TTerse.
172       In this list, the name of the loop variable is represented as "$~item".
173
174       See also "Loops" in Text::Xslate::Syntax::Kolon and "Loops" in
175       Text::Xslate::Syntax::TTerse.
176
177   "$~item / $~item.index"
178       The current iterating index in the loop, which starts 0.
179
180   "$~item.count"
181       The current iterating count in the loop, which starts 1. i.e. the same
182       as "$~item + 1".
183
184   "$~item.cycle(...)"
185       Selects a value in the arguments in cycle.
186
187       For example:
188
189           : for $arrayref -> $item {
190               <: $~item.cycle('odd', 'even') :>
191           : }
192
193       It will print "odd even odd even ...".
194
195   "$~item.is_first"
196       True if the loop block is the first, false otherwise.
197
198       This is aliased to "first" in TTerse for compatibility with TT2.
199
200   "$~item.is_last"
201       True if the loop block is the last, false otherwise.
202
203       This is aliased to "last" in TTerse for compatibility with TT2.
204
205   "$~item.peek_next"
206       The next item of the looping array. "nil" if "is_last". i.e. the same
207       as "$~item.is_last ? nil : $~item.body[$~item+1]".
208
209   "$~item.peek_prev"
210       The previous item of the looping array. "nil" if "is_first". i.e. the
211       same as "$~item.is_first ? nil : $~item.body[$~item-1]".
212
213   "$~item.body"
214       The reference of the looping array.
215
216   "$~item.size"
217       The size of the looping array. i.e. "scalar(@{$arrayref})" in Perl.
218
219   "$~item.max_index"
220       The maximum index of the looping array. i.e. $#{$arrayref} in Perl.
221

FILTERS/FUNCTIONS

223       The xslate engine supports filter syntax as well as function call.  The
224       following is the builtin functions, which can be invoked as filter
225       syntax.
226
227       For example, the following two statements are the same:
228
229           <: $value | foo :>
230           <: foo($value) :>
231
232       Note that some builtin functions, such as "defined", are not a real
233       function which you cannot use as a filter.
234
235   "mark_raw($str)"
236       Mark $str as a raw string to avoid auto HTML escaping.  You'd better
237       avoid to use this function. Instead, you should use the "mark_raw()"
238       subroutine in programs, which you can import from "Text::Xslate::Util".
239
240       "raw" is an alias to "mark_raw".
241
242   "unmark_raw($str)"
243       Remove the raw mark from $str. If $str is not a raw string, this
244       function returns $str as is.
245
246   "html_escape($str)"
247       Escapes html meta characters in $str. If $str is a raw string, this
248       function returns $str as is.
249
250       The html meta characters are "/[<>"'&]/".
251
252       "html" is an alias to "html_escape".
253
254   "uri_escape($str)"
255       Escapes unsafe URI characters in $str which gets encoded to UTF-8.
256
257       The unsafe URI characters are characters not included in the
258       "unreserved" character class defined by RFC 3986, i.e.
259       "/[^A-Za-z0-9\-\._~]/".
260
261       "uri" is an alias to "uri_escape".
262
263   "is_array_ref(($value)"
264       Returns true if $value is an ARRAY reference.
265
266   "is_hash_ref(($value)"
267       Returns true if $value is a HASH reference.
268
269   "dump($value)"
270       Inspects $value with "Data::Dumper".
271
272       This function is provided for testing and debugging.
273
274   "defined($value)"
275       Returns true if $value is defined. This is not a real function, but an
276       unary operator, so you can omit the parens like "defined $value".
277

NAME

DESCRIPTION

METHODS

LOOP VARIABLES

FILTERS/FUNCTIONS

SEE ALSO