Template::Plugin::ListUtil(3)

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)