NAME
    Thesaurus - Maintains lists of associated items

SYNOPSIS
     use Thesaurus;

     my $th = Thesaurus->new( -files => [ 'file1', 'file2' ],
                              -ignore_case => 1 );

     @words = $th->find('vegan');

     %words = $th->find( 'Faye' );

     foreach $word ( @{ $words{Faye} } )
     {
         #something ...
     }

     $th->add_file( 'file1', 'file2' );

     $th->add( [ 'tofu', 'mock duck' ] );

     $th->delete( 'meat', 'vivisection' );

DESCRIPTION
    Thesaurus is a module that allows you to create lists of related things.
    It was created in order to facilitate searches of a database of Chinese
    names in Anglicized form. Because there are various schemes to create
    phonetic representations of Chinese words, the following can all
    represent the same Chinese character:

     Woo
     Wu
     Ng

    Thesaurus can be used for anything that fits into a scalar by using the
    "new" method with no parameters and then calling the "add" method to add
    data.

    Thesaurus also acts as the parent class to several child classes which
    implement various forms of persistence for the data structure. This
    module can be used on its own to instantiate an object that lives for
    the life of its scope.

METHODS
    * new( %params )
        The "new" method returns a Thesaurus object. It takes the following
        parameters:

        * ignore_case => $boolean
                If this parameter is true, then the object will be case
                insensitive. It is _always_ case-preservative for its data.

    * find( @items )
         @words = $th->find( 'Big Hat' );
         %words = $th->find( 'Big Hat', 'Faye Wong' );

        The "find" method returns either a list or a hash, depending on
        context. Given a single word to find, it returns the list of words
        that it is associated with, including the word that was given. If no
        matches are found then it returns an empty list.

        If it is given multiple words, it returns a hash. The keys of the
        has are the words given, and the keys are list references containing
        the associated words. If no words were found then the key has a
        value of 0. If none of the words match then an empty list is
        returned.

    * add( \@list1, \@list2 )
        The "add" method takes a list of list references. Each of these
        references should contain a set of associated scalars. Like the
        "add_files()" method, if an entry in a list matches an entry already
        in the object, then it is appended to the existing list, otherwise a
        new association is created.

    * delete( @items )
        The "delete" method takes a list of items to delete. All the
        associations for the given items will be removed.

    * all
        Returns a list of array references. Each one of these list
        references contains one set of associations. Each association list
        is returned once, not once per item it contains.

AUTHOR
    Dave Rolsky, <autarch@urth.org>

COPYRIGHT
    Copyright (c) 1999-2003 David Rolsky. All rights reserved. This program
    is free software; you can redistribute it and/or modify it under the
    same terms as Perl itself.

    The full text of the license can be found in the LICENSE file included
    with this module.

SEE ALSO
    Thesaurus::CSV, Thesaurus::BerkeleyDB

