NAME

PTools::List - Create lists of things indexed by a label

VERSION

This document describes version 1.04, released October, 2004

SYNOPSIS

use PTools::List;

$notice = new PTools::List;               # start Notices
$notice->add("Error","Err1","Err2");      # add two Errors

$warn = new PTools::List("Warning","A warning");

$warn->add("Warning","Another warning");  # add to Warnings
$notice->add($warn);                      # add to Notices

print $notice->dump;                      # view contents

print $notice->format();                  # format output

print $notice->summary();                 # format summary

DESCRIPTION

Constructor

new ( Label [, Value [,Value...] ] )

The new method is called to create a new object that is used to collect various lists of things. Each list will have a unique label name and zero or more items in the list. Initial values are optional and may be added at any time.

Label

The required Label is used to identify a unique list.

Value

An optional list of Values can be added during object creation. Perl references can be included in any list, but make sure to read the warning in the return method.

Methods

add ( Label [, Value [, Value... ] ] )

This method is used to add items to an existing list.

Label

An identifier for a list. If an existing Label name is used here any Values will be added to that list. If the name does not yet exist, a new list is created.

Value

The Values are added to the named list.

reset ( Label )

Reset the list named by Label to an empty value.

get ( Label )

return ( Label )

The get and return method will return any value(s) contained in the list named by Label.

Warning: Perl references may be stored in any list. However, if you do so, make sure to invoke this method in list context, or you will be very disappointed by the result. (In scalar context, you will get a string that looks like a reference, and it will be extremely frustrating spending time debugging that!)

For example:

$hashRef = { foo => "bar", abc => "xyzzy" };

$list = new PTools::List( 'test', $hashRef );

(@items) = $list->return();       # MUST set "(@items) = " here.

occurred ( Label )

Check to see if any items are in the list indicated by Label.

format ( [ Label [, Label...] ] )

Returns a formatted string of the current contents. An optional list of one or more Labels can be added to limit the output to only contain one or some Label identifiers.

summary ( [ Title ] [, Label [, Label...] ] )

Returns a formatted summary of the current contents. An optional list of one or more Labels can be added to limit the output to only contain one or some Label identifiers. An optional Title can be added to the output.

dump ()

During testing or debugging this method will return a string showing the raw contents of the current object. Output includes where the method was called from, and the class and object where the method resides.

WARNINGS

Perl references may be stored in any list. However, if you do so, make sure to invoke this method in list context, or you will be very disappointed by the result.

In scalar context, you will get a string that looks like a reference, and it will be extremely frustrating spending time debugging that!

AUTHOR

Chris Cobb, <nospamplease@ccobb.net>

COPYRIGHT

Copyright (c) 1998-2007 by Chris Cobb. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.