NAME

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

DESCRIPTION

       This document describes builtin methods and filters/functions in Xslate.

       Note that the xslate engine is not aware of context, so all the methods and
       filters/functions return a single value, even when the equivalent of Perl's returns a list
       of values.

       Note that optional functions are defined in Text::Xslate::Bridge::Star.

METHODS

       The xslate engine supports auto-boxing, so you can call methods for primitive (non-object)
       values.  The following are builtin methods.

   For nil
       "nil" has its specific namespace as "nil", although no builtin methods are provided.

   For SCALARs
       The namespace of SCALARs is "scalar", although no builtin methods are provided.

   For ARRAY references
       The namespace of ARRAY references is "array".

       "$arrayref.first()"

       Returns the first element of $arrayref.

       "$arrayref.last()"

       Returns the last element of $arrayref.

       "$arrayref.size()"

       Returns the number of elements in $arrayref.

       "$arrayref.join($separator)"

       Joins the elements of $arrayref into a single string separated by $separator.

       "$arrayref.reverse()"

       Returns an ARRAY reference consisting of the elements of $arrayref in the opposite order.

       "$arrayref.sort(?$callback)"

       Sorts $arrayref and returns a new ARRAY reference.  The optional $callback is the same as
       Perl's.

       Examples:

           : 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

       See also "sort" in perlfunc.

       "$arrayref.map($callback)"

       Evaluates $callback for each element of $arrayref and returns a new ARRAY reference
       composed of the result of each such evaluation.

       Examples:

           : my $arrayref = [1, 2, 4, 8, 16];
           : # double
           : $arrayref.map(-> $a { $a * 2 }).join(','); # 2,4,8,16,32
           : # sequence
           : my $hashref = {a => 1, b => 2, c => 3, d => 4};
           : ['b', 'd', 'a'].map(-> $a {$hashref[$a]}).join(','); # 2,4,1

       See also "map" in perlfunc

       "$arrayref.reduce($callback)"

       Reduces $arrayref by calling $callback multiple times.  If $arrayref is empty, this method
       returns "nil".

       Examples:

           : 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

       See also "reduce" in List::Util.

       "$arrayref.merge($v)"

       Returns a new ARRAY reference consisting of $arrayref and $v.

       $v may be an ARRAY reference or a scalar value.

   For HASH references
       The namespace of HASH references is "hash".

       "$hashref.size()"

       Returns the number of entries of $hashref.

           : my $hashref = {a => 1, b => 2, c => 3, d => 4};
           : $hashref.size(); # 4

       "$hashref.keys()"

       Returns an ARRAY reference consisting of the keys of $hashref, which are sorted by the
       keys.

           : my $hashref = {a => 1, b => 2, c => 3, d => 4};
           : $hashref.keys().join(' '); # a b c d

       "$hashref.values()"

       Returns an ARRAY reference consisting of the values of $hashref, which are sorted by the
       keys.

           : my $hashref = {a => 1, b => 2, c => 3, d => 4};
           : $hashref.values().join(' '); # 1 2 3 4

       "$hashref.kv()"

       Returns an ARRAY reference consisting of the key-value pairs of $hashref, which are sorted
       by the keys. Each pair is an object that has the "keys" and "value" attributes.

       For example:

           : for $hashref.kv() -> $pair {
               <: $pair.key :>=<: $pair.value :>
           : }

       Output:

           a=1
           b=2
           c=3
           d=4

       "$hashref.merge($v)"

       Returns a new HASH reference consisting of $hashref and $v.

           : 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}

       $v must be a HASH reference.

LOOP VARIABLES

       You can use special loop variables in "for" loops, although its forms vary in template
       syntaxes, i.e. "$~item" in Kolon and "loop" in TTerse. In this list, the name of the loop
       variable is represented as "$~item".

       See also "Loops" in Text::Xslate::Syntax::Kolon and "Loops" in
       Text::Xslate::Syntax::TTerse.

   "$~item / $~item.index"
       The current iterating index in the loop, which starts 0.

   "$~item.count"
       The current iterating count in the loop, which starts 1. i.e. the same as "$~item + 1".

   "$~item.cycle(...)"
       Selects a value in the arguments in cycle.

       For example:

           : for $arrayref -> $item {
               <: $~item.cycle('odd', 'even') :>
           : }

       It will print "odd even odd even ...".

   "$~item.is_first"
       True if the loop block is the first, false otherwise.

       This is aliased to "first" in TTerse for compatibility with TT2.

   "$~item.is_last"
       True if the loop block is the last, false otherwise.

       This is aliased to "last" in TTerse for compatibility with TT2.

   "$~item.peek_next"
       The next item of the looping array. "nil" if "is_last". i.e. the same as "$~item.is_last ?
       nil : $~item.body[$~item+1]".

   "$~item.peek_prev"
       The previous item of the looping array. "nil" if "is_first". i.e. the same as
       "$~item.is_first ? nil : $~item.body[$~item-1]".

   "$~item.body"
       The reference of the looping array.

   "$~item.size"
       The size of the looping array. i.e. "scalar(@{$arrayref})" in Perl.

   "$~item.max_index"
       The maximum index of the looping array. i.e. $#{$arrayref} in Perl.

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.

       For example, the following two statements are the same:

           <: $value | foo :>
           <: foo($value) :>

       Note that some builtin functions, such as "defined", are not a real function which you
       cannot use as a filter.

   "mark_raw($str)"
       Mark $str as a raw string to avoid auto HTML escaping.  You'd better avoid to use this
       function. Instead, you should use the "mark_raw()" subroutine in programs, which you can
       import from "Text::Xslate::Util".

       "raw" is an alias to "mark_raw".

   "unmark_raw($str)"
       Remove the raw mark from $str. If $str is not a raw string, this function returns $str as
       is.

   "html_escape($str)"
       Escapes html meta characters in $str. If $str is a raw string, this function returns $str
       as is.

       The html meta characters are "/[<>"'&]/".

       "html" is an alias to "html_escape".

   "uri_escape($str)"
       Escapes unsafe URI characters in $str which gets encoded to UTF-8.

       The unsafe URI characters are characters not included in the "unreserved" character class
       defined by RFC 3986, i.e. "/[^A-Za-z0-9\-\._~]/".

       "uri" is an alias to "uri_escape".

   "is_array_ref(($value)"
       Returns true if $value is an ARRAY reference.

   "is_hash_ref(($value)"
       Returns true if $value is a HASH reference.

   "dump($value)"
       Inspects $value with "Data::Dumper".

       This function is provided for testing and debugging.

   "defined($value)"
       Returns true if $value is defined. This is not a real function, but an unary operator, so
       you can omit the parens like "defined $value".

SEE ALSO

       Text::Xslate

       Text::Xslate::Manual

       Text::Xslate::Bridge::Star