Array::Lookup(3)

       Array::Lookup - Lookup strings in arrays or hash tables
       with abbreviation.

SYNOPSIS

           use Array::Lookup;

           $value = lookup $key, \@keywords, \&notfound, \&toomany;

           $value = lookup $key, \%keywords, \&notfound, \&toomany;

           lookup_error $key, $keywords, $err, $msg;

DESCRIPTION

       lookup

       Lookup $key in the table @keywords and return the
       unambiguously matching keyword, if any.  If the second
       argument is given as a hash array, %keywords, then lookup
       a matching key, with abbreviation, and return the value
       corresponding to the unambiguously matching key.

       If there are no matches, invoke &notfound like this:

           &$notfound( $key, \@keywords, '');

       If there are two or more matches, invoke &toomany like
       this:

           &$toomany( $key, \@keywords, \@matches);

       If either subroutine is omitted or null, then no special
       action is taken except that undef is returned for the
       failed lookup.

       Note that the third argument, the array of ambiguous
       matches, allows a common subroutine to be used for both
       error conditions and still distinguish the error.

       See the section on lookup_error for a standard method of
       handling lookup failures.

       lookup_error

       Handle an error for the lookup subroutine.  The arguments:

       $key      The search key which failed the lookup.

       $keywords The hash or array reference containing the
                 keywords none of which matched the $key.

       $err      A flag indicating if the lookup failed because

       $msg      A format string used to format and print the
                 error message.  It should contain two printf
                 substitution sequences: %s.  The first will be
                 substituted with the failed lookup key; the
                 second with one of the phrases: "not found" or
                 "is ambiguous", depending upon $err.

                 If $msg is omitted or null, a default message
                 will be used:

                   "lookup failed: %s %s; use one of:\n"

                 followed by a listing of the strings in the
                 $keywords array.

EXAMPLES

       Using arrays


           use Array::Lookup;
           ...
           @keywords = qw(quit find get set show);
           ...
           $command = <STDIN>;
           $command = lookup $command, \@keywords,
               sub { lookup_error @_, "Unknown command '%s'; use one of:\n"; },
               sub { lookup_error @_, "Command '%s' %s; use one of:\n"; };


       Using hashes


           use Array::Lookup;
           ...
           %Commands = ( 'quit' => \&quit,  'get' => \&get,  'set' => \&set,
                         'find' => \&find,  'show' => \&show );
           ...
           $input = <STDIN>;
           $command_sub = lookup $input, \%Commands,
               sub { lookup_error @_, "Unknown command '%s'; use one of:\n"; },
               sub { lookup_error @_, "Command '%s' %s; use one of:\n"; };

SEE ALSO

       the Array::PrintCols manpage

AUTHOR

       Alan K. Stebbens <aks@sgi.com>