NAME
    Text::Abbreviate - Perl extension for text abbreviations and ambiguities

SYNOPSIS
      use Text::Abbreviate;
  
      my @cmds = qw( help load list quit query save stop );
      my $abbr = Text::Abbreviate->new(\%OPTS, @cmds);
  
      while (my $c = <STDIN>) {
        chomp $c;
        my @full = $abbr->expand($c);
        if (@full == 0) {
          print "Command '$c' could not be found.\n";
        }
        elsif (@full > 1) {
          print "Command '$c' ambiguous; choose from [@full]\n";
        }
        else {
          print "Command $full[0] selected.\n";
        }
      }

DESCRIPTION
    Text::Abbreviate takes a list of words (most commonly, commands for a
    user interface) and provides a means for you to expand an abbreviation
    of one of them into the full word. In the case that such an expansion is
    ambiguous ('qu' in the code above is ambiguous, because it could expand
    to 'quit' or 'query'), all expansions are returned.

  Case Folding
    You can turn case folding on and off with the folding() method; you can
    also set it during the creation of the object, by passing a hash
    reference as the first argument:

      my $abbr = Text::Abbreviate->new({fold => 1}, @words);

    Case folding (that is, case insensitivity) is off by default ("{fold ="
    0}>). To change the setting later on, use the folding() method:

      $abbr->folding(1);        # make case insensitive
      $abbr->folding(0);        # make case sensitive
      $state = $abbr->folding;  # get state (true/false)

  Unambiguous Abbreviations
    You can retrieve a hash of the unambiguous abbreviations of each word
    with the unambiguous() method:

      my %abbrevs = $abbr->unambiguous;     # hash
      my $abbrev_ref = $abbr->unambiguous;  # hash ref

    The keys are the full words themselves, and the values are array
    references holding the abbreviations in order of length (smallest
    first). Thus, for any word $w, the shortest unambiguous abbreviation for
    it is "$abbrevs{$w}[0]". CAVEAT: each word is included in the value set,
    even if the entirety of the word is still ambiguous. Specifically, if
    the words "here" and "heresy" are both in the word list, unambiguous()
    will return a hash that includes these key-value pairs:

      here => ['here'],
      heresy => ['heres', 'heresy'],

    This is almost a replication of Text::Abbrev except that the hash is
    inverted. (The caveat is replicated as well!)

SEE ALSO
    Text::Abbrev in the Perl core.

AUTHOR
    Jeff Pinyan, <japhy.734@gmail.com>

COPYRIGHT AND LICENSE
    Copyright (C) 2006 by Jeff "japhy" Pinyan

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself, either Perl version 5.6.0 or, at
    your option, any later version of Perl 5 you may have available.

