Text::...Builtin(3pm)

📦

version 3.5.9 · 8 versions

🌸 NAME 🌸

Text::Xslate::Manual::Builtin — the builtin methods and filters/functions in Xslate, bestie 💖

✨ DESCRIPTION ✨

okay so this doc is literally the whole rundown of the builtin methods and filters/functions in Xslate. everything you can call, all in one place 🫶

heads up tho: the xslate engine is not context-aware, like at all. so every method and every filter/function hands back a single value, even when the Perl equivalent would return a whole list of values. so if you're out here expecting a list back, that's a you problem, not a xslate problem 💅

also, some functions are optional and they live over in Text::Xslate::Bridge::Star. iykyk ✨

👑 METHODS 👑

the xslate engine does auto-boxing, so you can call methods on primitive (non-object) values. no wrapping needed, it just works. here are the builtins fr fr:

🌙 For nil

nil has its own special namespace literally called nil, even though — plot twist — no builtin methods are provided for it. iconic of it to have a namespace and zero methods tbh 💀

💜 For SCALARs

the namespace of SCALARs is scalar, although — again — no builtin methods are provided. empty namespace, no notes 🎀

🦋 For ARRAY references

the namespace of ARRAY references is array. okay this one actually has contents, let's gooo:

$arrayref.first() — returns the first element of $arrayref. the main character of the list 👑
$arrayref.last() — returns the last element of $arrayref. the one that always shows up late 🐢
$arrayref.size() — returns the number of elements in $arrayref. the headcount fr fr
$arrayref.join($separator) — joins the elements of $arrayref into a single string, separated by $separator. glue but make it slay ✨
$arrayref.reverse() — returns an ARRAY reference consisting of the elements of $arrayref in the opposite order. backwards but make it fashion 💅
$arrayref.sort(?$callback) — sorts $arrayref and returns a new ARRAY reference. the optional $callback is the same as Perl's.

examples, because we love a demonstration:

: 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

🍓 For HASH references

the namespace of HASH references is hash. let's get into it:

$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. yes, those exact names, no i will not be taking questions 💅

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. not a scalar, not an array, a HASH. no cap.

🌀 LOOP VARIABLES 🌀

you can use special loop variables inside "for" loops, although the forms vary depending on which template syntax you're in — like "$~item" in Kolon and "loop" in TTerse. in this list, the loop variable is written 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 at 0. zero-indexed, the way the universe intended ✨
$~item.count — the current iterating count in the loop, which starts at 1. i.e. the same as $~item + 1.
$~item.cycle(...) — selects a value in the arguments in cycle. round and round, she goes 🎠

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. nostalgia-core 💖

$~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 and function call syntax. the following are the builtin functions, and you can invoke any of them as a filter. two ways, same energy 🫶

for example, the following two statements are the same:

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

⚠️ ngl some builtin functions, like "defined", are not a real function, which means you cannot use them as a filter. periodt.

mark_raw($str) — marks $str as a raw string to avoid auto HTML escaping.

🚨 you'd better avoid using 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) — removes the raw mark from $str. if $str is not a raw string, this function returns $str as is. no harm, no foul 💜
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. it's a vibe check for your data 🔍

defined($value) — returns true if $value is defined. this is not a real function, but a unary operator, so you can omit the parens like "defined $value". cursive writing, no training wheels 💫

🔗 SEE ALSO 🔗

Text::Xslate
Text::Xslate::Manual
Text::Xslate::Bridge::Star

okay that's the whole page bestie, you're officially fluent 💖 this was perl v5.42.3, dated 2026-08-22, straight outta the User Contributed Perl Documentation section of Text::...Builtin(3pm). go forth and template slay ✨👑🎀

📦 where this page comes from

ubuntu stonking: libtext-xslate-perl 3.5.9-2build2 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms