Provided by: libpetal-utils-perl_0.06-4_all bug


       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

             <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

             <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

             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 string).

             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

               '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 count.

               <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 expression.

             <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 community.