
=head1 NAME

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

=head1 DESCRIPTION

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

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

=head1 METHODS

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

=head2 For nil

C<nil> has its specific namespace as C<nil>, although no builtin methods are
provided.

=head2 For SCALARs

The namespace of SCALARs is C<scalar>, although no builtin methods are
provided.

=head2 For ARRAY references

The namespace of ARRAY references is C<array>.

Returns true;

=head3 C<$a.size()>

Returns the number of elements of I<$a>.

=head3 C<$a.join($separator)>

Joins the elements of I<$a> into a single string separated by
I<$separator>.

=head3 C<$a.reverse()>

Returns an ARRAY reference consisting of the elements of I<$a>
in the opposite order.

=head3 C<$a.sort(?$callback)>

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

Examples:

    : my $a = [2, 1, 10];
    : # alphabetic sort (default)
    : $a.sort().join(" "); # 1 10, 2
    : # explicitly alphabetic
    : $a.sort(-> $a, $b { $a cmp $b }).join(" "); # 1, 10, 2
    : # numeric sort
    : $a.sort(-> $a, $b { $a <=> $b }).join(" "); # 1, 2, 10

See also L<perlfunc/"sort">.

=head3 C<$a.map($callback)>

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

See also L<perlfunc/"map">

=head3 C<$a.reduce($callback)>

Reduces I<$a> by calling I<$callback> multiple times.
If I<$a> is empty, this method returns C<nil>.

Examples:

    : my $a = [10, 20, 30];
    : # sum
    : $a.reduce(-> $a, $b { $a + $b }); # 60
    : # concat
    : $a.reduce(-> $a, $b { $a ~ $b }); # 102030
    : # min
    : $a.reduce(-> $a, $b { $a min $b }); # 10
    : # max
    : $a.reduce(-> $a, $b { $a max $b }); # 30

See also L<List::Util/"reduce">.

=head2 For HASH references

The namespace of HASH references is C<hash>.

=head3 C<$h.size()>

Returns the number of entries of I<$h>.

=head3 C<$h.keys()>

Returns an ARRAY reference consisting of the keys of I<$h>, which are sorted
by the keys.

=head3 C<$h.values()>

Returns an ARRAY reference consisting of the values of I<$h>, which are
sorted by the keys.

=head3 C<$h.kv()>

Returns an ARRAY reference consisting of the key-value pairs of I<$h>, which
are sorted by the keys.
Each pair is an object that has the C<keys> and C<value> attributes.

For example:

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

=head1 LOOP VARIABLES

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

See also L<Text::Xslate::Syntax::Kolon/Loops> and L<Text::Xslate::Syntax::TTerse/Loops>.

=head2 C<< $~item / $~item.index >>

The current iterating index in the loop, which starts B<0>.

=head2 C<< $~item.count >>

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

=head2 C<< $~item.cycle(...) >>

Selects a value in the arguments in cycle.

For example:

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

It will print C<< odd even odd even ... >>.

=head2 C<< $~item.is_first >>

True if the loop block is the first, false otherwise.

This is aliased to C<first> in TTerse for compatibility with TT2.

=head2 C<< $~item.last >>

True if the loop block is the last, false otherwise.

This is aliased to C<last> in TTerse for compatibility with TT2.

=head2 C<< $~item.peek_next >>

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

=head2 C<< $~item.peek_prev >>

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

=head2 C<< $~item.body >>

The reference of the looping array.

=head2 C<< $~item.size >>

The size of the looping array. i.e. C<< scalar(@{$arrayref}) >> in Perl.

=head2 C<< $~item.max_index >>

The maximum index of the looping array. i.e. C<< $#{$arrayref} >> in Perl.

=head1 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.
=head2 C<< mark_raw($str) >>

Mark I<$str> as a raw string to avoid auto HTML escaping.

C<raw> is an alias to C<mark_raw>.

=head2 C<< unmark_raw($str) >>

Remove the raw mark from I<str>. If I<str> is not a raw string, this function
returns I<str> as is.

=head2 C<< html($str) >>

Escapes html meta characters in I<str>. If I<str> is a raw string, this
function returns I<str> as is.

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

=head2 C<< uri($str) >>

Escapes unsafe URI characters in I<$str>.

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

See also RFC 3986.

=head2 C<< is_array_ref(($value) >>

Returns true if I<$value> is an ARRAY reference.

=head2 C<< is_hash_ref(($value) >>

Returns true if I<$value> is a HASH reference.

=head2 C<< dump($value) >>

Inspects I<$value> with C<Data::Dumper>.

This function is provided for testing and debugging.

=head1 SEE ALSO

L<Text::Xslate>

L<Text::Xslate::Manual>

=cut

