/ 
Template-Plugin-ListUtil-0.02
River stage zero No dependents
/ Template::Plugin::ListUtil

NAME

Template::Plugin::ListUtil - List::Util functions for TT

SYNOPSIS

[% mylist = [ 1, 2, 3, 4, 4, 3, 2, 5, 2 ] %]

[% USE ListUtil %]
The largest value in our array is [% ListUtil.largest(mylist) %]

[% USE ListUtilVMethods %]
The largest value in our array is [% mylist.largest %]

DESCRIPTION

This module provides a selection of handy functions for dealing with lists in the Template Toolkit. Most of the functions are adapted from those provided by or documented in List::Util, though note these have been altered in name and function to work better with the template toolkit.

To access the functions like class methods, simply use the plugin from within a Template Toolkit template:

[% USE ListUtil %]

And then call the method against the ListUtil object.

[% max = ListUtil.largest(mylist) %]

Alternatively you can load the functions as vmethods:

[% USE ListUtilVMethods %]
[% max = mylist.largest %]

Using the VMethods plugin as above will cause the vmethods to be in effect for the current template and all templates called from that template. To allow all templates called from any instance of the Template module load the module from Perl with the 'install' parameter.

use Template::Plugin::ListUtilVMethods 'install';

FUNCTIONS PROVIDED

These are the functions that you can use once you've loaded the plugin.

Finding the largest/smallest

largest

Return the numerically largest value of the list.

largeststr

Return the largest value of the list, sorted by unicode value

smallest

Return the numerically smallest value of the list

smalleststr

Return the smallest value of the list, sorted by unicode value

Simple Statistics

total

The sum of adding up all the elements in the list

even

Returns true if and only if this list contains an even number of items, or the list is empty.

odd

Returns true if and only if this list contains an odd number of items.

mean

The mathematical mean (numerical average) of the list

mode

Mode returns a list of the most frequently occurring elements in a list. For example, for the list:

["buffy", "buffy", "willow", "willow", "buffy" ]

The list

["buffy"]

Would be returned because "Buffy" occurs more times in the list than any other element. However, for some lists have more than one element that could be consider the most frequent:

[ 1, 2, 3, 3, 2, 2, 3, 4, 5, 5 ]

In which case mode returns them all:

[ 2, 3 ]

You can use the virtual method first on the resulting list from mode to pick an arbitrary value, or the mean function (see above) to to take an average of the values.

median

Returns a list containing either the middle element of the list (if the list is odd in length) or the middle two elements of the list (if the list is even in length.) To get a mathematical median you should presort the list (probably with the nsort virtual method) before you pass it to median. Like with mode you can use the virtual method first on the resulting list from median to pick an arbitrary value, or the mean function (see above) to to take an average of the values.

Randomisation Functions

shuffle

Return a new list made up from randomly shuffled elements of the list passed.

random

Return a random item from the passed list.

Truth Functions

anytrue / anyfalse

Is at least one item in the list true / false?

alltrue / allfalse

Are all items (i.e. every single item) in the list true / false?

nonetrue / nonefalse

Is no element in the list true / false?

notalltrue / notallfalse

Is at least one element in the list false?

true

How many items are true?

false

How many items are false?

AUTHOR

Written by Mark Fowler <mark@twoshortplanks.com>

Uses the List::Util module, by Graham Barr <gbarr@pobox.com>.

Except as indicated in comments in the code, Copyright Mark Fowler 2003; All Rights Reserved. As indicated by comments in code some code Copyright Graham Barr (1997-2001).

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

BUGS

None known.

Bugs should be reported to me via the CPAN RT system. http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Template-Plugin-ListUtil.

SEE ALSO

List::Util (for doing this in Perl)

Template::Plugin::VMethods (details on how the vmethods are installed)