Provided by: liblingua-ispell-perl_0.07-8_all bug

NAME

       Lingua::Ispell.pm - a module encapsulating access to the Ispell program.

       Note: this module was previously known as Text::Ispell; if you have Text::Ispell installed
       on your system, it is now obsolete and should be replaced by Lingua::Ispell.

NOTA BENE

       ispell, when reporting on misspelled words, indicates the string it was unable to verify,
       as well as its starting offset in the input line.  No such information is returned for
       words which are deemed to be correctly spelled.  For example, in a line like "Can't buy a
       thrill", ispell simply reports that the line contained four correctly spelled words.

       Lingua::Ispell would like to identify which substrings of the input line are words --
       correctly spelled or otherwise.  It used to attempt to split the input line into words
       according to the same rules ispell uses; but that has proven to be very difficult,
       resulting in both slow and error-prone code.

   Consequences
       Lingua::Ispell now operates only in "terse" mode.  In this mode, only misspelled words are
       reported.  Words which ispell verifies as correctly spelled are silently accepted.

       In the report structures returned by "spellcheck()", the 'term' member is now always
       identical to the 'original' member; of the two, you should probably use the 'term' member.
       (Also consider the 'offset' member.)  ispell does not report this information for
       correctly spelled words; if at some point in the future this capability is added to
       ispell, Lingua::Ispell will be updated to take advantage of it.

       Use of the $word_chars variable has been removed; setting it no longer has any effect.

       "terse_mode()" now does nothing.

SYNOPSIS

        # Brief:
        use Lingua::Ispell;
        Lingua::Ispell::spellcheck( $string );
        # or
        use Lingua::Ispell qw( spellcheck ); # import the function
        spellcheck( $string );

        # Useful:
        use Lingua::Ispell qw( :all );  # import all symbols
        for my $r ( spellcheck( "hello hacking perl shrdlu 42" ) ) {
          print "$r->{'type'}: $r->{'term'}\n";
        }

DESCRIPTION

       Lingua::Ispell::spellcheck() takes one argument.  It must be a string, and it should
       contain only printable characters.  One allowable exception is a terminal newline, which
       will be chomped off anyway.  The line is fed to a coprocess running ispell for analysis.
       ispell parses the line into "terms" according to the language-specific rules in effect.

       The result of ispell's analysis of each term is a categorization of the term into one of
       six types: ok, compound, root, miss, none, and guess.  Some of these carry additional
       information.  The first three types are "correctly" spelled terms, and the last three are
       for "incorrectly" spelled terms.

       Lingua::Ispell::spellcheck returns a list of objects, each corresponding to a term in the
       spellchecked string.  Each object is a hash (hash-ref) with at least two entries: 'term'
       and 'type'.  The former contains the term ispell is reporting on, and the latter is
       ispell's determination of that term's type (see above).  For types 'ok' and 'none', that
       is all the information there is.  For the type 'root', an additional hash entry is
       present: 'root'.  Its value is the word which ispell identified in the dictionary as being
       the likely root of the current term.  For the type 'miss', an additional hash entry is
       present: 'misses'.  Its value is an ref to an array of words which ispell identified as
       being "near-misses" of the current term, when scanning the dictionary.

   NOTE
       As mentioned above, "Lingua::Ispell::spellcheck()" currently only reports on misspelled
       terms.

   EXAMPLE
        use Lingua::Ispell qw( spellcheck );
        Lingua::Ispell::allow_compounds(1);
        for my $r ( spellcheck( "hello hacking perl salmoning fruithammer shrdlu 42" ) ) {
          if ( $r->{'type'} eq 'ok' ) {
            # as in the case of 'hello'
            print "'$r->{'term'}' was found in the dictionary.\n";
          }
          elsif ( $r->{'type'} eq 'root' ) {
            # as in the case of 'hacking'
            print "'$r->{'term'}' can be formed from root '$r->{'root'}'\n";
          }
          elsif ( $r->{'type'} eq 'miss' ) {
            # as in the case of 'perl'
            print "'$r->{'term'}' was not found in the dictionary;\n";
            print "Near misses: @{$r->{'misses'}}\n";
          }
          elsif ( $r->{'type'} eq 'guess' ) {
            # as in the case of 'salmoning'
            print "'$r->{'term'}' was not found in the dictionary;\n";
            print "Root/affix Guesses: @{$r->{'guesses'}}\n";
          }
          elsif ( $r->{'type'} eq 'compound' ) {
            # as in the case of 'fruithammer'
            print "'$r->{'term'}' is a valid compound word.\n";
          }
          elsif ( $r->{'type'} eq 'none' ) {
            # as in the case of 'shrdlu'
            print "No match for term '$r->{'term'}'\n";
          }
          # and numbers are skipped entirely, as in the case of 42.
        }

   ERRORS
       "Lingua::Ispell::spellcheck()" starts the ispell coprocess if the coprocess seems not to
       exist.  Ordinarily this is simply the first time it's called.

       ispell is spawned via the "Open2::open2()" function, which throws an exception (i.e. dies)
       if the spawn fails.  The caller should be prepared to catch this exception -- unless, of
       course, the default behavior of die is acceptable.

   Nota Bene
       The full location of the ispell executable is stored in the variable
       $Lingua::Ispell::path.  The default value is /usr/bin/ispell.  If your ispell executable
       has some name other than this, then you must set $Lingua::Ispell::path accordingly before
       you call "Lingua::Ispell::spellcheck()" (or any other function in the module) for the
       first time!

AUX FUNCTIONS

   add_word(word)
       Adds a word to the personal dictionary.  Be careful of capitalization.  If you want the
       word to be added "case-insensitively", you should call "add_word_lc()"

   add_word_lc(word)
       Adds a word to the personal dictionary, in lower-case form.  This allows ispell to match
       it in a case-insensitive manner.

   accept_word(word)
       Similar to adding a word to the dictionary, in that it causes ispell to accept the word as
       valid, but it does not actually add it to the dictionary.  Presumably the effects of this
       only last for the current ispell session, which will mysteriously end if any of the
       coprocess-restarting functions are called...

   parse_according_to(formatter)
       Causes ispell to parse subsequent input lines according to the specified formatter.  As of
       ispell v. 3.1.20, only 'tex' and 'nroff' are supported.

   set_params_by_language(language)
       Causes ispell to set its internal operational parameters according to the given language.
       Legal arguments to this function, and its effects, are currently unknown by the author of
       Lingua::Ispell.

   save_dictionary()
       Causes ispell to save the current state of the dictionary to its disk file.  Presumably
       ispell would ordinarily only do this upon exit.

   terse_mode(bool:terse)
       NOTE: This function has been disabled!  Lingua::Ispell now always operates in terse mode.

       In terse mode, ispell will not produce reports for "correct" words.  This means that the
       calling program will not receive results of the types 'ok', 'root', and 'compound'.

FUNCTIONS THAT RESTART ISPELL

       The following functions cause the current ispell coprocess, if any, to terminate.  This
       means that all the changes to the state of ispell made by the above functions will be
       lost, and their respective values reset to their defaults.  The only function above whose
       effect is persistent is "save_dictionary()".

       Perhaps in the future we will figure out a good way to make this state information carry
       over from one instantiation of the coprocess to the next.

   allow_compounds(bool)
       When this value is set to True, compound words are accepted as legal -- as long as both
       words are found in the dictionary; more than two words are always illegal.  When this
       value is set to False, run-together words are considered spelling errors.

       The default value of this setting is dictionary-dependent, so the caller should set it
       explicitly if it really matters.

   make_wild_guesses(bool)
       This setting controls when ispell makes "wild" guesses.

       If False, ispell only makes "sane" guesses, i.e.  possible root/affix combinations that
       match the current dictionary; only if it can find none will it make "wild" guesses, which
       don't match the dictionary, and might in fact be illegal words.

       If True, wild guesses are always made, along with any "sane" guesses.  This feature can be
       useful if the dictionary has a limited word list, or a word list with few suffixes.

       The default value of this setting is dictionary-dependent, so the caller should set it
       explicitly if it really matters.

   use_dictionary([dictionary])
       Specifies what dictionary to use instead of the default.  Dictionary names are actually
       file names, and are searched for according to the following rule: if the name does not
       contain a slash, it is looked for in the directory containing the default dictionary,
       typically /usr/lib.  Otherwise, it is used as is: if it does not begin with a slash, it is
       construed from the current directory.

       If no argument is given, the default dictionary will be used.

   use_personal_dictionary([dictionary])
       Specifies what personal dictionary to use instead of the default.

       Dictionary names are actually file names, and are searched for according to the following
       rule: if the name begins with a slash, it is used as is (i.e. it is an absolute path
       name). Otherwise, it is construed as relative to the user's home directory ($HOME).

       If no argument is given, the default personal dictionary will be used.

FUTURE ENHANCEMENTS

       ispell options:

         -w chars
                Specify additional characters that can be part of a word.

DEPENDENCIES

       Lingua::Ispell uses the external program ispell, which is the "International Ispell",
       available at

         http://fmg-www.cs.ucla.edu/geoff/ispell.html

       as well as various archives and mirrors, such as

         ftp://ftp.math.orst.edu/pub/ispell-3.1/

       This is a very popular program, and may already be installed on your system.

       Lingua::Ispell also uses the standard perl modules FileHandle, IPC::Open2, and Carp.

AUTHOR

       jdporter@min.net (John Porter)

COPYRIGHT

       This module is free software; you may redistribute it and/or modify it under the same
       terms as Perl itself.