
Please 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.


Note:
A simple "spellchecking" program is included in this distribution.
It is a perl program named "spellcheck".  It simply prints the
analysis of the input text; it provides no way to modify the text. 
It is simply given as a demonstration of the module.  Type 
    spellcheck -h
for a usage summary.  If no input files are specified, it will
read from stdin.  After each line of input, it will print the
analysis of the terms.  By default, it only gives output for
terms which are "incorrect".  Give it the -v option to have it
report on the "correct" terms as well.

Tests:
'make test' currently does nothing.  To test the installation,
try out the "spellcheck" program provided. 

__POD__


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.

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.  The line is parsed on non-wordchars
     into a sequence of	terms.	By default, the	set of wordchars
     is	defined	in ispell as letters, digits, and the apostrophe.
     In	other words, the line is subjected the equivalent of

       split /[^a-zA-Z0-9']+/

     (ispell has a means to add	characters to the default set,
     but currently Lingua::Ispell does not provide access to that
     feature.)

     The result	of ispell's analysis of	each term is a
     categorization of the term	into one of six	types: ok, root,
     miss, none, compound, and guess.  Some of these carry
     additional	information.

     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.

     A quickie 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/local/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)

     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'.

     ispell starts up in NON-terse mode, i.e. reports are
     produced for all terms, not just "incorrect" ones.

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/local/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.

