Set/CheckList version 1.00
========================

NAME
    Set::CheckList - Keep track of a list of "to do" items

SYNOPSIS
     use Set::CheckList;
     my ($checklist, $item);

     $checklist = Set::CheckList->new();
     $checklist->set('Fred');

     while (defined($item = $cl->next())) {
        # items can be set in the middle of a loop
        $checklist->set('Wilma');
    
        # setting an item again doesn't change its done status
        $checklist->set('Fred');
    
        print $item, "\n"
     }

INSTALLATION
    Set::CheckList can be installed with the usual routine:

            perl Makefile.PL
            make
            make test
            make install

    You can also just copy CheckList.pm into the Set/ directory of one of
    your library trees.

DESCRIPTION
    Set::CheckList provides a mechanism for tracking a list of "to do"
    items. Each item can be added to the list any number of times, but is
    returned only once by the next() command.

    Items are added using "set()". The first argument for "set()" is the
    name (i.e. the key) of the item. If "set()" is called w/o any further
    arguments then CheckList only adds the item if it is not already in the
    list. If the second argument is "0", then the item in the list is marked
    as false (not done). If the second argument is "1", then the item in the
    list is marked as true (done).

METHODS
  Set::CheckList->new()

    The "new" method returns a new Set::CheckList object. "new" uses no
    arguments.

       $checklist = Set::CheckList->new;

  $checklist->set(key [, value])

    Ensures that the given name is in the list. If a value is not given as
    the first argument, and the item is already in the list, the item's done
    status is not changed, otherwise the item is added with a done status of
    false. If value is given, sets the item to the given value (true or
    false).

     # ensure the item is in the list,
     # but don't change its value if is
     # already there
     $checklist->set('Larry');

     # ensure the item is in the list,
     # and set its value to done
     $checklist->set('Larry', 1);

  $checklist->next([autocheck])

    Returns the next not-done value in the list. Returns undef if all are
    done. By default, "next" automatically marks the returned item as true.
    Therefore you can simply loop through the list by repeatedly calling
    next:

     while (defined($item = $cl->next()))
        {print $item, "\n"}

    If the first argument is defined but false, "next" does not mark the
    next item as done. If you send true as the first argument then the item
    is marked as done.

    "next" does not return items in any particular order.

  $checklist->clear()

    "clear" clears out all items from the list:

      $checklist->clear();

  $checklist->reset([status])

    "reset" resets the done status of all items in the list.

      $checklist->reset

    The first and only argument indicates if they should be set to done
    (true) or not done (false). So, for example, the following command
    resets all items to done:

      $checklist->reset(1);

TERMS AND CONDITIONS
    Copyright (c) 2002 by Miko O'Sullivan. All rights reserved. This program
    is free software; you can redistribute it and/or modify it under the
    same terms as Perl itself.

    This software comes with NO WARRANTY of any kind.

AUTHOR
    Miko O'Sullivan miko@idocs.com

VERSION
    Version 1.00 July 10, 2002