Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Petal::Utils(3)	      User Contributed Perl Documentation      Petal::Utils(3)

       Petal::Utils - Useful template modifiers	for Petal.

	 # 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

       The Petal::Utils	package	contains commonly used Petal modifiers (or
       plugins), and bundles them with an easy-to-use installation interface.
       By default, a set of modifiers are installed into Petal when you	use
       this module.  You can change which modifiers are	installed by naming
       them after the use statement:

	 # 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();

       You'll find a list of plugin sets throughout this document.  You	can
       also get	a complete list	by looking at the variable:


       For details on how the plugins are installed, see the "Advanced Petal"
       section of the Petal documentation.

       Each modifier is	listed under the set it	belongs	to.

       lowercase:, lc: $string
	   Make	the entire string lowercase.

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

       uppercase:, uc: $string
	   Make	the entire string uppercase.

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

       uc_first: $string
	   Make	the first letter of the	string uppercase.

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

       substr: $string [offset]	[length] [ellipsis]
	   Extract a substring from a string. Optionally add an	ellipsis (...)
	   to the end. See also, 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 to
	   print formatted strings.

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

       date: $date
	   Convert a time() integer to a date string using Date::Format.

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

       us_date:	$date
	   Convert an international date stamp (e.g., yyyymmdd,	yyyy-mm-dd,
	   yyyy/mm/dd) to US format (mm/dd/yyyy).

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

       if: $expr1 then:	$expr2 else: $expr3
	   Do an if/then/else test and return the value	of the expression
	   executed.  Truthfulness of $expr1 is	according to Perl (e.g., non-
	   zero, non-empty string).

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

       or: $expr1 $expr2
	   Do a	logical	or.  Truthfulness is according to Perl (e.g., non-
	   zero, non-empty string).

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

       and: $expr1 $expr2
	   Do a	logical	and.  Truthfulness is according	to Perl	(e.g., non-
	   zero, non-empty string).

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

       equal:, eq: $expr1 $expr2
	   Test	for equality.  Numbers are compared with "==", strings with
	   "eq".  Truthfulness is according to Perl (e.g., non-zero, non-empty

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

       like: $expr $regex
	   Test	for equality to	a regular expression (see perlre).

	     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 functionality of	an IF-THEN-ELSE
	   statement. A	case-sensitive regex comparison	is performed. All text
	   strings must	be enclosed in single quotes.

	       '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

       sort: $list
	   Sort	the values in a	list before returning it.

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

       limit: $list count
	   Limit the values in a list before returning it.

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

       limitr: $list count
	   Shuffle the list then limit the returned values to the specified

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

       keys: $hash
	   Return a list of keys for a hashref.	Note: It appears that values
	   cannot be accessed with dynamic keys. If you	need the keys and
	   values, use "each:".

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

       each: $hash
	   Return a list of key/value pairs for	a hashref.

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

       uri_escape: $expr
	   Use URI::Escape's uri_escape() to escape the	return value of	the

	     <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 with the given protocol (e.g.,
	   http, ftp --	do not include the protocol separators). If the	url
	   does	not have the protocol included,	it will	be appended. If	no
	   protocol is given, 'http' will be used.

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

       dump: $expr
	   Dump	the data strcture of the value given.

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

       At the time of writing, the following supersets were available:

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

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

       Contributions to	the modifiers are welcome! You can suggest new
       modifiers to add	to the suite. You will have better luck	getting	your
       modifier	added by providing a module (see lib/Petal/Utils/	for an
       example), a patch to (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.

       William McKee <>, and	Steve Purkis

       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.

       Thanks to Jean-Michel Hiver for making Petal available to the Perl


perl v5.32.1			  2021-02-28		       Petal::Utils(3)


Want to link to this manual page? Use this URL:

home | help