.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Text::Xslate::Manual::Builtin 3pm"
.TH Text::Xslate::Manual::Builtin 3pm "2017-01-21" "perl v5.24.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Text::Xslate::Manual::Builtin \- Builtin methods and filters/functions in Xslate
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This document describes builtin methods and filters/functions in Xslate.
.PP
Note that the xslate engine is not aware of \fBcontext\fR, so all the
methods and filters/functions return a single value, even when
the equivalent of Perl's returns a list of values.
.PP
Note that optional functions are defined in Text::Xslate::Bridge::Star.
.SH "METHODS"
.IX Header "METHODS"
The xslate engine supports auto-boxing, so you can call methods for
primitive (non-object) values.
The following are builtin methods.
.SS "For nil"
.IX Subsection "For nil"
\&\f(CW\*(C`nil\*(C'\fR has its specific namespace as \f(CW\*(C`nil\*(C'\fR, although no builtin methods are
provided.
.SS "For SCALARs"
.IX Subsection "For SCALARs"
The namespace of SCALARs is \f(CW\*(C`scalar\*(C'\fR, although no builtin methods are
provided.
.SS "For \s-1ARRAY\s0 references"
.IX Subsection "For ARRAY references"
The namespace of \s-1ARRAY\s0 references is \f(CW\*(C`array\*(C'\fR.
.PP
\fI\f(CI\*(C`$arrayref.first()\*(C'\fI\fR
.IX Subsection "$arrayref.first()"
.PP
Returns the first element of \fI\f(CI$arrayref\fI\fR.
.PP
\fI\f(CI\*(C`$arrayref.last()\*(C'\fI\fR
.IX Subsection "$arrayref.last()"
.PP
Returns the last element of \fI\f(CI$arrayref\fI\fR.
.PP
\fI\f(CI\*(C`$arrayref.size()\*(C'\fI\fR
.IX Subsection "$arrayref.size()"
.PP
Returns the number of elements in \fI\f(CI$arrayref\fI\fR.
.PP
\fI\f(CI\*(C`$arrayref.join($separator)\*(C'\fI\fR
.IX Subsection "$arrayref.join($separator)"
.PP
Joins the elements of \fI\f(CI$arrayref\fI\fR into a single string separated by
\&\fI\f(CI$separator\fI\fR.
.PP
\fI\f(CI\*(C`$arrayref.reverse()\*(C'\fI\fR
.IX Subsection "$arrayref.reverse()"
.PP
Returns an \s-1ARRAY\s0 reference consisting of the elements of \fI\f(CI$arrayref\fI\fR
in the opposite order.
.PP
\fI\f(CI\*(C`$arrayref.sort(?$callback)\*(C'\fI\fR
.IX Subsection "$arrayref.sort(?$callback)"
.PP
Sorts \fI\f(CI$arrayref\fI\fR and returns a new \s-1ARRAY\s0 reference.
The optional \fI\f(CI$callback\fI\fR is the same as Perl's.
.PP
Examples:
.PP
.Vb 7
\&    : my $arrayref = [2, 1, 10];
\&    : # alphabetic sort (default)
\&    : $arrayref.sort().join(" "); # 1 10 2
\&    : # explicitly alphabetic
\&    : $arrayref.sort(\-> $a, $b { $a cmp $b }).join(" "); # 1 10 2
\&    : # numeric sort
\&    : $arrayref.sort(\-> $a, $b { $a <=> $b }).join(" "); # 1 2 10
.Ve
.PP
See also \*(L"sort\*(R" in perlfunc.
.PP
\fI\f(CI\*(C`$arrayref.map($callback)\*(C'\fI\fR
.IX Subsection "$arrayref.map($callback)"
.PP
Evaluates \fI\f(CI$callback\fI\fR for each element of \fI\f(CI$arrayref\fI\fR and returns
a new \s-1ARRAY\s0 reference composed of the result of each such evaluation.
.PP
Examples:
.PP
.Vb 6
\&    : my $arrayref = [1, 2, 4, 8, 16];
\&    : # double
\&    : $arrayref.map(\-> $a { $a * 2 }).join(\*(Aq,\*(Aq); # 2,4,8,16,32
\&    : # sequence
\&    : my $hashref = {a => 1, b => 2, c => 3, d => 4};
\&    : [\*(Aqb\*(Aq, \*(Aqd\*(Aq, \*(Aqa\*(Aq].map(\-> $a {$hashref[$a]}).join(\*(Aq,\*(Aq); # 2,4,1
.Ve
.PP
See also \*(L"map\*(R" in perlfunc
.PP
\fI\f(CI\*(C`$arrayref.reduce($callback)\*(C'\fI\fR
.IX Subsection "$arrayref.reduce($callback)"
.PP
Reduces \fI\f(CI$arrayref\fI\fR by calling \fI\f(CI$callback\fI\fR multiple times.
If \fI\f(CI$arrayref\fI\fR is empty, this method returns \f(CW\*(C`nil\*(C'\fR.
.PP
Examples:
.PP
.Vb 9
\&    : my $arrayref = [10, 20, 30];
\&    : # sum
\&    : $arrayref.reduce(\-> $a, $b { $a + $b }); # 60
\&    : # concat
\&    : $arrayref.reduce(\-> $a, $b { $a ~ $b }); # 102030
\&    : # min
\&    : $arrayref.reduce(\-> $a, $b { $a min $b }); # 10
\&    : # max
\&    : $arrayref.reduce(\-> $a, $b { $a max $b }); # 30
.Ve
.PP
See also \*(L"reduce\*(R" in List::Util.
.PP
\fI\f(CI\*(C`$arrayref.merge($v)\*(C'\fI\fR
.IX Subsection "$arrayref.merge($v)"
.PP
Returns a new \s-1ARRAY\s0 reference consisting of \fI\f(CI$arrayref\fI\fR and \fI\f(CI$v\fI\fR.
.PP
\&\fI\f(CI$v\fI\fR may be an \s-1ARRAY\s0 reference or a scalar value.
.SS "For \s-1HASH\s0 references"
.IX Subsection "For HASH references"
The namespace of \s-1HASH\s0 references is \f(CW\*(C`hash\*(C'\fR.
.PP
\fI\f(CI\*(C`$hashref.size()\*(C'\fI\fR
.IX Subsection "$hashref.size()"
.PP
Returns the number of entries of \fI\f(CI$hashref\fI\fR.
.PP
.Vb 2
\&    : my $hashref = {a => 1, b => 2, c => 3, d => 4};
\&    : $hashref.size(); # 4
.Ve
.PP
\fI\f(CI\*(C`$hashref.keys()\*(C'\fI\fR
.IX Subsection "$hashref.keys()"
.PP
Returns an \s-1ARRAY\s0 reference consisting of the keys of \fI\f(CI$hashref\fI\fR, which are
sorted by the keys.
.PP
.Vb 2
\&    : my $hashref = {a => 1, b => 2, c => 3, d => 4};
\&    : $hashref.keys().join(\*(Aq \*(Aq); # a b c d
.Ve
.PP
\fI\f(CI\*(C`$hashref.values()\*(C'\fI\fR
.IX Subsection "$hashref.values()"
.PP
Returns an \s-1ARRAY\s0 reference consisting of the values of \fI\f(CI$hashref\fI\fR, which are
sorted by the keys.
.PP
.Vb 2
\&    : my $hashref = {a => 1, b => 2, c => 3, d => 4};
\&    : $hashref.values().join(\*(Aq \*(Aq); # 1 2 3 4
.Ve
.PP
\fI\f(CI\*(C`$hashref.kv()\*(C'\fI\fR
.IX Subsection "$hashref.kv()"
.PP
Returns an \s-1ARRAY\s0 reference consisting of the key-value pairs of \fI\f(CI$hashref\fI\fR,
which are sorted by the keys. Each pair is an object that has the \f(CW\*(C`keys\*(C'\fR and
\&\f(CW\*(C`value\*(C'\fR attributes.
.PP
For example:
.PP
.Vb 3
\&    : for $hashref.kv() \-> $pair {
\&        <: $pair.key :>=<: $pair.value :>
\&    : }
.Ve
.PP
Output:
.PP
.Vb 4
\&    a=1
\&    b=2
\&    c=3
\&    d=4
.Ve
.PP
\fI\f(CI\*(C`$hashref.merge($v)\*(C'\fI\fR
.IX Subsection "$hashref.merge($v)"
.PP
Returns a new \s-1HASH\s0 reference consisting of \fI\f(CI$hashref\fI\fR and \fI\f(CI$v\fI\fR.
.PP
.Vb 3
\&    : my $hashref = {a => 1, b => 2, c => 3, d => 4};
\&    : my $new = $hashref.merge({a => 0, e => 5});
\&    : # {a => 0, b => 2, c => 3, d => 4, e => 5}
.Ve
.PP
\&\fI\f(CI$v\fI\fR must be a \s-1HASH\s0 reference.
.SH "LOOP VARIABLES"
.IX Header "LOOP VARIABLES"
You can use special loop variables in \f(CW\*(C`for\*(C'\fR loops, although its forms vary in
template syntaxes, i.e. \f(CW\*(C`$~item\*(C'\fR in Kolon and \f(CW\*(C`loop\*(C'\fR in TTerse. In
this list, the name of the loop variable is represented as \f(CW\*(C`$~item\*(C'\fR.
.PP
See also \*(L"Loops\*(R" in Text::Xslate::Syntax::Kolon and \*(L"Loops\*(R" in Text::Xslate::Syntax::TTerse.
.ie n .SS """$~item / $~item.index"""
.el .SS "\f(CW$~item / $~item.index\fP"
.IX Subsection "$~item / $~item.index"
The current iterating index in the loop, which starts \fB0\fR.
.ie n .SS """$~item.count"""
.el .SS "\f(CW$~item.count\fP"
.IX Subsection "$~item.count"
The current iterating count in the loop, which starts \fB1\fR. i.e. the same as \f(CW\*(C`$~item + 1\*(C'\fR.
.ie n .SS """$~item.cycle(...)"""
.el .SS "\f(CW$~item.cycle(...)\fP"
.IX Subsection "$~item.cycle(...)"
Selects a value in the arguments in cycle.
.PP
For example:
.PP
.Vb 3
\&    : for $arrayref \-> $item {
\&        <: $~item.cycle(\*(Aqodd\*(Aq, \*(Aqeven\*(Aq) :>
\&    : }
.Ve
.PP
It will print \f(CW\*(C`odd even odd even ...\*(C'\fR.
.ie n .SS """$~item.is_first"""
.el .SS "\f(CW$~item.is_first\fP"
.IX Subsection "$~item.is_first"
True if the loop block is the first, false otherwise.
.PP
This is aliased to \f(CW\*(C`first\*(C'\fR in TTerse for compatibility with \s-1TT2.\s0
.ie n .SS """$~item.is_last"""
.el .SS "\f(CW$~item.is_last\fP"
.IX Subsection "$~item.is_last"
True if the loop block is the last, false otherwise.
.PP
This is aliased to \f(CW\*(C`last\*(C'\fR in TTerse for compatibility with \s-1TT2.\s0
.ie n .SS """$~item.peek_next"""
.el .SS "\f(CW$~item.peek_next\fP"
.IX Subsection "$~item.peek_next"
The next item of the looping array. \f(CW\*(C`nil\*(C'\fR if \f(CW\*(C`is_last\*(C'\fR. i.e. the same as \f(CW\*(C`$~item.is_last ? nil : $~item.body[$~item+1]\*(C'\fR.
.ie n .SS """$~item.peek_prev"""
.el .SS "\f(CW$~item.peek_prev\fP"
.IX Subsection "$~item.peek_prev"
The previous item of the looping array. \f(CW\*(C`nil\*(C'\fR if \f(CW\*(C`is_first\*(C'\fR. i.e. the same as \f(CW\*(C`$~item.is_first ? nil : $~item.body[$~item\-1]\*(C'\fR.
.ie n .SS """$~item.body"""
.el .SS "\f(CW$~item.body\fP"
.IX Subsection "$~item.body"
The reference of the looping array.
.ie n .SS """$~item.size"""
.el .SS "\f(CW$~item.size\fP"
.IX Subsection "$~item.size"
The size of the looping array. i.e. \f(CW\*(C`scalar(@{$arrayref})\*(C'\fR in Perl.
.ie n .SS """$~item.max_index"""
.el .SS "\f(CW$~item.max_index\fP"
.IX Subsection "$~item.max_index"
The maximum index of the looping array. i.e. \f(CW$#{$arrayref}\fR in Perl.
.SH "FILTERS/FUNCTIONS"
.IX Header "FILTERS/FUNCTIONS"
The xslate engine supports filter syntax as well as function call.
The following is the builtin functions, which can be invoked as filter syntax.
.PP
For example, the following two statements are the same:
.PP
.Vb 2
\&    <: $value | foo :>
\&    <: foo($value) :>
.Ve
.PP
Note that some builtin functions, such as \f(CW\*(C`defined\*(C'\fR, are not a real function
which you cannot use as a filter.
.ie n .SS """mark_raw($str)"""
.el .SS "\f(CWmark_raw($str)\fP"
.IX Subsection "mark_raw($str)"
Mark \fI\f(CI$str\fI\fR as a raw string to avoid auto \s-1HTML\s0 escaping.
You'd better avoid to use this function. Instead, you should use the
\&\f(CW\*(C`mark_raw()\*(C'\fR subroutine in programs, which you can import from
\&\f(CW\*(C`Text::Xslate::Util\*(C'\fR.
.PP
\&\f(CW\*(C`raw\*(C'\fR is an alias to \f(CW\*(C`mark_raw\*(C'\fR.
.ie n .SS """unmark_raw($str)"""
.el .SS "\f(CWunmark_raw($str)\fP"
.IX Subsection "unmark_raw($str)"
Remove the raw mark from \fI\f(CI$str\fI\fR. If \fI\f(CI$str\fI\fR is not a raw string, this function
returns \fI\f(CI$str\fI\fR as is.
.ie n .SS """html_escape($str)"""
.el .SS "\f(CWhtml_escape($str)\fP"
.IX Subsection "html_escape($str)"
Escapes html meta characters in \fI\f(CI$str\fI\fR. If \fI\f(CI$str\fI\fR is a raw string, this
function returns \fI\f(CI$str\fI\fR as is.
.PP
The html meta characters are \f(CW\*(C`/[<>"\*(Aq&]/\*(C'\fR.
.PP
\&\f(CW\*(C`html\*(C'\fR is an alias to \f(CW\*(C`html_escape\*(C'\fR.
.ie n .SS """uri_escape($str)"""
.el .SS "\f(CWuri_escape($str)\fP"
.IX Subsection "uri_escape($str)"
Escapes unsafe \s-1URI\s0 characters in \fI\f(CI$str\fI\fR which gets encoded to \s-1UTF\-8.\s0
.PP
The unsafe \s-1URI\s0 characters are characters not included in
the \f(CW\*(C`unreserved\*(C'\fR character class defined by \s-1RFC 3986,\s0
i.e. \f(CW\*(C`/[^A\-Za\-z0\-9\e\-\e._~]/\*(C'\fR.
.PP
\&\f(CW\*(C`uri\*(C'\fR is an alias to \f(CW\*(C`uri_escape\*(C'\fR.
.ie n .SS """is_array_ref(($value)"""
.el .SS "\f(CWis_array_ref(($value)\fP"
.IX Subsection "is_array_ref(($value)"
Returns true if \fI\f(CI$value\fI\fR is an \s-1ARRAY\s0 reference.
.ie n .SS """is_hash_ref(($value)"""
.el .SS "\f(CWis_hash_ref(($value)\fP"
.IX Subsection "is_hash_ref(($value)"
Returns true if \fI\f(CI$value\fI\fR is a \s-1HASH\s0 reference.
.ie n .SS """dump($value)"""
.el .SS "\f(CWdump($value)\fP"
.IX Subsection "dump($value)"
Inspects \fI\f(CI$value\fI\fR with \f(CW\*(C`Data::Dumper\*(C'\fR.
.PP
This function is provided for testing and debugging.
.ie n .SS """defined($value)"""
.el .SS "\f(CWdefined($value)\fP"
.IX Subsection "defined($value)"
Returns true if \fI\f(CI$value\fI\fR is defined. This is not a real function, but
an unary operator, so you can omit the parens like \f(CW\*(C`defined $value\*(C'\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Text::Xslate
.PP
Text::Xslate::Manual
.PP
Text::Xslate::Bridge::Star