NAME
Text::Ispell.pm - a class encapsulating access to the Ispell program.
SYNOPSIS
# Brief:
use Text::Ispell;
Text::Ispell::spellcheck( $string );
# or
use Text::Ispell qw( spellcheck ); # import the function
spellcheck( $string );
# Useful:
use Text::Ispell qw( spellcheck );
for my $r ( spellcheck( "hello hacking perl shrdlu 42" ) ) {
print "$r->{'type'}: $r->{'term'}\n";
}DESCRIPTION
Text::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 Text::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.
Text::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 a string of words, comma-separated, which ispell identified as being "near-misses" of the current term, when scanning the dictionary.
A quickie example:
use Text::Ispell qw( spellcheck );
for my $r ( spellcheck( "hello hacking perl 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 'none' ) {
# as in the case of 'shrdlu'
print "No match for term '$r->{'term'}'\n";
}
}According to the ispell man page, there should be two more types: compound and guess. However, I have not figured out how to elicit responses of these types from ispell.
ERRORS
Text::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 $Text::Ispell::path. The default value is /usr/local/bin/ispell. If your ispell executable has some name other than this, then you must set $Text::Ispell::path accordingly before you call Text::Ispell::spellcheck() for the first time.
AUX FUNCTIONS
add_word(word)
Adds a word to the 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 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.
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 Text::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()
nonterse_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'.
ispell starts up in NON-terse mode, i.e. reports are produced for all terms, not just "incorrect" ones.
LIMITATIONS
Currently this package assumes, and only supports, the default language, i.e. English. It does not provide access to the features of ispell which allow the selection of alternate languages or dictionaries.
FUTURE ENHANCEMENTS
Take advantage of these ispell options:
-d file
Specify an alternate dictionary file.
For example, use -d deutsch to choose a German dictionary.
-p file
Specify an alternate personal dictionary.
-w chars
Specify additional characters that can be part of a word.
-B Report run-together words with missing blanks as
spelling errors.
-C Consider run-together words as legal compounds.
-P Don't generate extra root/affix combinations.
-m Make possible root/affix combinations that aren't
in the dictionary.I should consider allowing these kinds of options to be set at any time; this would entail stopping and restarting the coprocess.
DEPENDENCIES
Text::Ispell uses the external program ispell, which is the "International Ispell", available at
http://fmg-www.cs.ucla.edu/geoff/ispell.htmlas 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.
Text::Ispell also uses the standard perl modules FileHandle, IPC::Open2, and Carp.
AUTHOR
jdporter@min.net (John Porter)
This module is free software; you may redistribute it and/or modify it under the same terms as Perl itself.