Petal::Utils(3pm)

💖 Petal::Utils — the user-contributed Perl doc page that's about to become your roman empire 💖

okay so this is Petal::Utils(3pm), straight out of the User Contributed Perl Documentation, and bestie, it is lowkey a whole treasure chest of template modifiers. no cap. let's get into it 🫶

---

✨ NAME ✨

Petal::Utils — useful template modifiers for Petal. that's it, that's the vibe. 🎀

---

🦋 SYNOPSIS 🦋

# install the default set of Petal modifiers:
use Petal::Utils;

# you can also install modifiers manually:
Petal::Utils->install( 'some_modifier', ':some_set' );

# see below for modifiers available & template syntax

like, look at that. iconic behaviour honestly 💅

---

🌸 DESCRIPTION 🌸

The Petal::Utils package is where all the commonly used Petal modifiers (aka plugins) live, and it bundles them up with an installation interface that's genuinely so easy to use. By default, a whole set of modifiers gets installed into Petal the moment you use this module. wanna change which ones show up? just name them after the use statement, periodt:

# use the default set:
use Petal::Utils qw( :default );

# use the date set of modifiers:
use Petal::Utils qw( :date );

# use only named modifiers, plus the debug set:
use Petal::Utils qw( UpperCase Date :debug );

# don't install any modifiers
use Petal::Utils qw();

There's a list of plugin sets all throughout this doc — keep scrolling, bestie. you can also get the complete list by peeking at this variable:

%Petal::Utils::PLUGIN_SET

and if you're the type who needs the lore on how plugins get installed, go read the "Advanced Petal" section of the Petal documentation. iykyk. 📚

---

🔥 MODIFIERS 🔥

every modifier is listed under the set it belongs to, no crumbs left behind. 👑

💜 :text

lowercase:, lc: $string

makes the entire string lowercase. lowercase era fr.

<p tal:content="lc: $string">lower</p>

uppercase:, uc: $string

makes the entire string uppercase. SCREAMING. 📣

<p tal:content="uc: $string">upper</p>

uc_first: $string

makes the first letter of the string uppercase. just the first one, she's the main character only at the start.

<p tal:content="uc_first: $string">uc_first</p>

substr: $string [offset] [length] [ellipsis]

extracts a substring from a string. optionally you can slap an ellipsis (...) on the end. also see, perldoc -f substr. 🍓

<span petal:content="substr:$str">string</span>       # does nothing
<span petal:content="substr:$str 2">string</span>     # cuts the first two chars
<span petal:content="substr:$str 2 5">string</span>   # extracts chars 2-7
<span petal:content="substr:$str 2 5 1">string with ellipsis</span>  # same as above and adds an ellipsis

printf: format list

the printf modifier acts exactly like Perl's sprintf function, printing formatted strings. same energy, no notes.

<p petal:content="printf:'%s' 'Astro'">Astro</p>
<p petal:content="printf:'$%0.2f' '2.5'">$2.50</p>

🎀 :date

date: $date

converts a time() integer into a date string using Date::Format.

<span tal:replace="date: $date">Jan  1 1970 01:00:01</span>

us_date: $date

converts an international date stamp (like yyyymmdd, yyyy-mm-dd, yyyy/mm/dd) into US format (mm/dd/yyyy). globalization who? we're going US format here.

<p tal:content="us_date: $date">2003-09-05</p>

🧚 :logic

if: $expr1 then: $expr2 else: $expr3

does an if/then/else test and returns the value of the expression that got executed. truthfulness of $expr1 follows Perl rules (so: non-zero, non-empty string — you know the drill).

<p tal:attributes="class if: on_a_page then: a_class else: another_class">
  Some text here...
</p>

or: $expr1 $expr2

does a logical or. truthfulness is, again, according to Perl (non-zero, non-empty string).

<p tal:if="or: $first $second">
  first or second = <span tal:replace="or: $first $second">or</span>
</p>

and: $expr1 $expr2

does a logical and. truthfulness: Perl rules, always Perl rules (non-zero, non-empty string).

first and second = <span tal:replace="and: $first $second">and</span>

equal:, eq: $expr1 $expr2

tests for equality. numbers get compared with ==, strings get compared with eq. truthfulness is according to Perl (non-zero, non-empty string).

first eq second = <span tal:replace="eq: $first $second">equal</span>

like: $expr $regex

tests for equality against a regular expression (see perlre). regex girlies rise up 🌈

name like regex = <span tal:replace="like: $name ^Will.+m">like</span>

decode, decode: expression search result [search result]... [default]

the decode function has the whole functionality of an IF-THEN-ELSE statement. a case-sensitive regex comparison is performed. and listen — all text strings must be enclosed in single quotes. no exceptions, bestie.

• 'expression' is the value to compare.
• 'search' is the value that is compared against expression.
• 'result' is the value returned, if expression is equal to search.
• default is optional. if no matches are found, the decode will return default. if default is omitted, then the decode statement will return null (if no matches are found).

<p petal:content="decode:$str 'dog' 'Satchel'">100</p>  # if $str = dog, returns Satchel
<p petal:content="decode:$str 'cat' 'Buckey' 'Satchel'">Astro</p>  # if $str = cat, returns Buckey, else Satchel

🦋 :list

sort: $list

sorts the values in a list before returning it. tidying up, we love to see it ✨

<ul>
  <li tal:repeat="item sort: $array_ref">$item</li>
</ul>

limit: $list count

limits the values in a list before returning it. boundaries? we're setting them.

<ul>
  <li tal:repeat="item limit: $array_ref 2">$item</li>
</ul>

limitr: $list count

shuffles the list and then limits the returned values to the specified count. chaotic AND controlled. 💀

<ul>
  <li tal:repeat="item limitr: $array_ref 2">$item</li>
</ul>

💅 :hash

keys: $hash

returns a list of keys for a hashref. note: it appears that values cannot be accessed with dynamic keys. if you need the keys and the values, use "each:" instead.

<ul>
  <li tal:repeat="key keys: $hash_ref"><span tal:replace="key">key</span></li>
</ul>

each: $hash

returns a list of key/value pairs for a hashref. the full package deal 🫶

<ul>
  <li tal:repeat="item each: $hash_ref">
    <span tal:replace="item/key">key</span> => <span tal:replace="item/val">value</span>
  </li>
</ul>

⭐ :uri

uri_escape: $expr

uses URI::Escape's uri_escape() to escape the return value of the expression. safety first, babes 🔒

<a href="http://foo/get.html?item=${uri_escape: item/key}">get $item/key</a>

create_href: $url [protocol]

creates an absolute uri from a url using the given protocol (like http, ftp — and do not include the protocol separators, okay?). if the url doesn't have the protocol included, it gets appended. if no protocol is given at all, 'http' will be used. default queen.

<a petal:attr="href create_href:$url">HTTP Link</a>
<a petal:attr="href create_href:$url ftp">FTP Link</a>

🐛 :debug

dump: $expr

dumps the data structure of the value you hand it. getting nosy, but productively.

dump name: <span tal:replace="dump: name">dump</span>

---

👑 SUPERSETS 👑

at the time of writing, these were the supersets available:

':none'    => [],
':all'     => [qw( :default :hash :debug )],
':default' => [qw( :text :date :logic :list )],

check %Petal::Utils::PLUGIN_SET for an up-to-date list. 💖

---

🌈 CONTRIBUTING 🌈

contributions to the modifiers are welcome, bestie!! you can suggest new modifiers to add to the suite, and honestly you'll have way better luck getting yours added if you bring:

• a module (peep lib/Petal/Utils/And.pm for an example),
• a patch to Utils.pm (with a modified PLUGIN_SET and documentation for your new modifier),
• and a test suite.

all modifiers are subject to the discretion of the authors. them's the rules. 🎀

---

💜 AUTHORS 💜

William McKee <william@knowmad.com>, and Steve Purkis <spurkis@cpan.org>

---

🌸 COPYRIGHT 🌸

Copyright (c) 2003-2004 William McKee & Steve Purkis.

this module is free software and is distributed under the same license as Perl itself. use it at your own risk. (yes, for real — that's a direct quote, protect yourself 🫶)

---

🙏 THANKS 🙏

thanks to Jean-Michel Hiver for making Petal available to the Perl community. king behaviour, we appreciate you 👑

---

🔗 SEE ALSO 🔗

Petal

---

and that's the whole page, no skips! 💅 this was Petal::Utils(3pm) from perl v5.36.0, dated 2022-12-12. go forth and modify your templates, you absolute icon. periodt. 💖✨🦋