.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Aspell 3pm"
.TH Aspell 3pm "2018-12-07" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Text::Aspell \- Perl interface to the GNU Aspell library
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use Text::Aspell;
\&    my $speller = Text::Aspell\->new;
\&
\&    die unless $speller;
\&
\&
\&    # Set some options
\&    $speller\->set_option(\*(Aqlang\*(Aq,\*(Aqen_US\*(Aq);
\&    $speller\->set_option(\*(Aqsug\-mode\*(Aq,\*(Aqfast\*(Aq);
\&
\&
\&    # check a word
\&    print $speller\->check( $word )
\&          ? "$word found\en"
\&          : "$word not found!\en";
\&
\&    # lookup up words
\&    my @suggestions = $speller\->suggest( $misspelled );
\&
\&
\&    # lookup config options
\&    my $language = $speller\->get_option(\*(Aqlang\*(Aq);
\&    print $speller\->errstr unless defined $language;
\&
\&    # fetch a config item that is a list
\&    my @sgml_extensions = $speller\->get_option_as_list(\*(Aqsgml\-extension\*(Aq);
\&
\&
\&    # fetch the configuration keys and their default settings
\&    my $options = $speller\->fetch_option_keys;
\&
\&    # or dump config settings to STDOUT
\&    $speller\->print_config || $speller\->errstr;
\&
\&
\&
\&
\&    # What dictionaries are installed as simple strings
\&    my @dicts = $speller\->list_dictionaries;
\&
\&    # or as an array of hashes
\&    @dicts = $speller\->dictionary_info;
\&    print Data::Dumper::Dumper( \e@dicts );
.Ve
.PP
Here's an example how to create and use your own word list
.PP
Create a dictionary:
.PP
.Vb 1
\&    $ aspell \-\-lang=en create master ./dictionary.local < space_separated_word_list
.Ve
.PP
Then in your code:
.PP
.Vb 8
\&    use Text::Aspell;
\&    my $speller = Text::Aspell\->new;
\&    die unless $speller;
\&    $speller\->set_option(\*(Aqmaster\*(Aq,\*(Aq./dictionary.local\*(Aq);
\&    # check a word
\&    print $speller\->check( $word )
\&          ? "$word found\en"
\&          : "$word not found!\en";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a Perl interface to the \s-1GNU\s0 Aspell library.  This module
is to meet the need of looking up many words, one at a time, in a single
session, such as spell-checking a document in memory.
.PP
The \s-1GNU C\s0 interface is described at:
.PP
.Vb 1
\&    http://aspell.net/man\-html/Through\-the\-C\-API.html#Through\-the\-C\-API
.Ve
.PP
It's worth looking over the way config and speller (manager) objects are
created when using the Aspell C \s-1API\s0 as some of that is hidden in the
Text::Aspell module.
.PP
For example, with Text::Aspell you do not have to explicitly create a speller
object.  The speller (manager) object is created automatically the first time
you call \fBsuggest()\fR or \fBcheck()\fR.
.PP
Note also that once the speller object is created some (all?) config options
cannot be changed.  For example, setting configuration options such as \*(L"lang\*(R"
are what determine what dictionary Aspell will use.  Once the speller object is
created that dictionary will be used.  I.e. setting \*(L"lang\*(R" after the speller
object is created will have no effect.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
You \s-1MUST\s0 have installed \s-1GNU\s0 Aspell library version 0.50.1 or higher on your
system before installing this Text::Aspell Perl module.  If installing Aspell
using your operating system's package management system, you may need to
install the Aspell development package (for example, on Debian libaspell-dev).
.PP
Aspell can source can be downloaded from:
.PP
.Vb 1
\&    http://aspell.net
.Ve
.PP
There have been a number of bug reports because people failed to install aspell
before installing this module.  This is an interface to the aspell library
installed on your system, not a replacement for aspell.
.PP
You must also have the English dictionary installed when running the module's
test suite.
.PP
Also, please see the \s-1README\s0 and Changes files.  \s-1README\s0 may have specific
information about your platform.
.SH "METHODS"
.IX Header "METHODS"
The following methods are available:
.ie n .IP "$speller = Text::Aspell\->new;" 4
.el .IP "\f(CW$speller\fR = Text::Aspell\->new;" 4
.IX Item "$speller = Text::Aspell->new;"
Creates a new speller object.  New does not take any parameters (future version
may allow options set by passing in a hash reference of options and value pairs).
Returns \f(CW\*(C`undef\*(C'\fR if the object could not be created, which is unlikely.
.Sp
Internally, \fBnew()\fR creates an object to store Aspell structures (AspellConfig,
AspellSpeller, and a space for an error string and then calls \fBnew_aspell_config()\fR;
.ie n .IP "$speller\->set_option($option_name, $value);" 4
.el .IP "\f(CW$speller\fR\->set_option($option_name, \f(CW$value\fR);" 4
.IX Item "$speller->set_option($option_name, $value);"
Sets the configuration option \f(CW$option_name\fR to the value of \f(CW$value\fR.
Returns \f(CW\*(C`undef\*(C'\fR on error, and the error message can be printed with \f(CW$speller\fR\->errstr.
.Sp
You should set configuration options before calling the \f(CW$speller\fR\->create_speller
method.  See the \s-1GNU\s0 Aspell documentation for the available configuration settings
and how (and when) they may be used.
.ie n .IP "$speller\->remove_option($option_name);" 4
.el .IP "\f(CW$speller\fR\->remove_option($option_name);" 4
.IX Item "$speller->remove_option($option_name);"
Removes (sets to the default value) the configuration option specified by \f(CW$option_name\fR.
Returns \f(CW\*(C`undef\*(C'\fR on error, and the error message can be printed with \f(CW$speller\fR\->errstr.
You may only set configuration options before calling the \f(CW$speller\fR\->create_speller
method.
.ie n .IP "$string = $speller\->get_option($option_name);" 4
.el .IP "\f(CW$string\fR = \f(CW$speller\fR\->get_option($option_name);" 4
.IX Item "$string = $speller->get_option($option_name);"
Returns the current setting for the given configuration option.  The values are strings.
For configuration options that are lists used the \f(CW\*(C`get_option_as_list()\*(C'\fR method.
.Sp
Returns \f(CW\*(C`undef\*(C'\fR on error, and the error message can be printed with \f(CW$speller\fR\->errstr.
.Sp
Note that this may return different results depending on if it's called before or after
\&\f(CW$speller\fR\->create_speller is called.
.ie n .IP "@list = $speller\->get_option_as_list($option_name);" 4
.el .IP "\f(CW@list\fR = \f(CW$speller\fR\->get_option_as_list($option_name);" 4
.IX Item "@list = $speller->get_option_as_list($option_name);"
Returns an array of list items for the given option.  Use this method to fetch configuration
values that are of type \fIlist\fR.
.Sp
Returns \f(CW\*(C`undef\*(C'\fR on error, and the error message can be printed with \f(CW$speller\fR\->errstr.
.Sp
Note that this may return different results depending on if it's called before or after
\&\f(CW$speller\fR\->create_speller is called.
.ie n .IP "$options = $speller\->fetch_option_keys;" 4
.el .IP "\f(CW$options\fR = \f(CW$speller\fR\->fetch_option_keys;" 4
.IX Item "$options = $speller->fetch_option_keys;"
Returns a hash of hashes.  The keys are the possible configuration options
and the values is a hash with keys of:
.Sp
.Vb 3
\&    desc    : A short description of the option
\&    default : The default value for this option
\&    type    : The data type of option (see aspell.h)
.Ve
.ie n .IP "$speller\->print_config;" 4
.el .IP "\f(CW$speller\fR\->print_config;" 4
.IX Item "$speller->print_config;"
Prints the current configuration to \s-1STDOUT.\s0  Useful for debugging.
Note that this will return different results depending on if it's called before or after
\&\f(CW$speller\fR\->create_speller is called.
.ie n .IP "$speller\->errstr;" 4
.el .IP "\f(CW$speller\fR\->errstr;" 4
.IX Item "$speller->errstr;"
Returns the error string from the last error.  Check the previous call for an \f(CW\*(C`undef\*(C'\fR return
value before calling this method
.ie n .IP "$errnum = $speller\->errnum;" 4
.el .IP "\f(CW$errnum\fR = \f(CW$speller\fR\->errnum;" 4
.IX Item "$errnum = $speller->errnum;"
Returns the error number from the last error.  Some errors may only set the
error string ($speller\->errstr) on errors, so it's best to check use the errstr method
over this method.
.Sp
This method is deprecated.
.ie n .IP "$found = $speller\->check($word);" 4
.el .IP "\f(CW$found\fR = \f(CW$speller\fR\->check($word);" 4
.IX Item "$found = $speller->check($word);"
Checks if a word is found in the dictionary.  Returns true if the word is found
in the dictionary, false but defined if the word is not in the dictionary.
Returns \f(CW\*(C`undef\*(C'\fR on error, and the error message can be printed with \f(CW$speller\fR\->errstr.
.Sp
This calls \f(CW$speller\fR\->create_speller if the speller has not been created by an
explicit call to \f(CW$speller\fR\->create_speller.
.ie n .IP "@suggestions = $speller\->suggest($word)" 4
.el .IP "\f(CW@suggestions\fR = \f(CW$speller\fR\->suggest($word)" 4
.IX Item "@suggestions = $speller->suggest($word)"
Returns an array of word suggestions for the specified word.  The words are returned
with the best guesses at the start of the list.
.ie n .IP "$speller\->create_speller;" 4
.el .IP "\f(CW$speller\fR\->create_speller;" 4
.IX Item "$speller->create_speller;"
This method is normally not called by your program.
It is called automatically the first time \f(CW$speller\fR\->\fBcheck()\fR or
\&\f(CW$speller\fR\->\fBsuggest()\fR is called to create a spelling \*(L"speller\*(R".
.Sp
You might want to call this when your program first starts up to make the first
access a bit faster, or if you need to read back configuration settings before
looking up words.
.Sp
The creation of the speller builds a configuration
profile in the speller structure. Results from calling \fBprint_config()\fR and \fBget_option()\fR will
change after calling \fBcreate_speller()\fR.  In general, it's best to read config settings back
after calling \fBcreate_speller()\fR or after calling \fBspell()\fR or \fBsuggest()\fR.
Returns \f(CW\*(C`undef\*(C'\fR on error, and the error message can be printed with \f(CW$speller\fR\->errstr.
.ie n .IP "$speller\->add_to_session($word)" 4
.el .IP "\f(CW$speller\fR\->add_to_session($word)" 4
.IX Item "$speller->add_to_session($word)"
.PD 0
.ie n .IP "$speller\->add_to_personal($word)" 4
.el .IP "\f(CW$speller\fR\->add_to_personal($word)" 4
.IX Item "$speller->add_to_personal($word)"
.PD
Adds a word to the session or personal word lists.
Words added will be offered as suggestions.
.ie n .IP "$speller\->store_replacement($word, $replacement);" 4
.el .IP "\f(CW$speller\fR\->store_replacement($word, \f(CW$replacement\fR);" 4
.IX Item "$speller->store_replacement($word, $replacement);"
This method can be used to instruct the speller which word you used as a replacement
for a misspelled word.  This allows the speller to offer up the replacement next time
the word is misspelled.  See section 6.3 of the \s-1GNU\s0 Aspell documentation for a better description.
.Sp
(July 2005 note: best to ignore any return value for now)
.ie n .IP "$speller\->save_all_word_lists;" 4
.el .IP "\f(CW$speller\fR\->save_all_word_lists;" 4
.IX Item "$speller->save_all_word_lists;"
Writes any pending word lists to disk.
.ie n .IP "$speller\->clear_session;" 4
.el .IP "\f(CW$speller\fR\->clear_session;" 4
.IX Item "$speller->clear_session;"
Clears the current session word list.
.ie n .IP "@dicts = $speller\->list_dictionaries;" 4
.el .IP "\f(CW@dicts\fR = \f(CW$speller\fR\->list_dictionaries;" 4
.IX Item "@dicts = $speller->list_dictionaries;"
This returns an array of installed dictionary files.  Each is a single string
formatted as:
.Sp
.Vb 1
\&    [name]:[code]:[jargon]:[size]:[module]
.Ve
.Sp
Name and code will often be the same, but
name is the complete name of the dictionary which can be used to directly
select a dictionary, and code is the language/region code only.
.ie n .IP "$array_ref = $speller\->$speller\->dictionary_info;" 4
.el .IP "\f(CW$array_ref\fR = \f(CW$speller\fR\->$speller\->dictionary_info;" 4
.IX Item "$array_ref = $speller->$speller->dictionary_info;"
Like the \f(CW\*(C`list_dictionaries()\*(C'\fR method, this method returns an array of
hash references.  For example, an entry for a dictionary might have the
following hash reference:
.Sp
.Vb 7
\&    {
\&        \*(Aqmodule\*(Aq => \*(Aqdefault\*(Aq,
\&        \*(Aqcode\*(Aq => \*(Aqen_US\*(Aq,
\&        \*(Aqsize\*(Aq => 60,
\&        \*(Aqjargon\*(Aq => \*(Aqw\-accents\*(Aq,
\&        \*(Aqname\*(Aq => \*(Aqen_US\-w\-accents\*(Aq
\&    },
.Ve
.Sp
Not all hash keys will be available for every dictionary
(e.g. the dictionary may not have a \*(L"jargon\*(R" key).
.SH "Upgrading from Text::Pspell"
.IX Header "Upgrading from Text::Pspell"
Text::Aspell works with \s-1GNU\s0 Aspell and is a replacement for the
module Text::Pspell.  Text::Pspell is no longer supported.
.PP
Upgrading should be a simple process.  Only one method name has changed:
\&\f(CW\*(C`create_manager\*(C'\fR is now called \f(CW\*(C`create_speller\*(C'\fR.
Code designed to use the old Text::Pspell module may not even call the
\&\f(CW\*(C`create_manager\*(C'\fR method so this may not be an issue.
.PP
The \f(CW\*(C`language_tag\*(C'\fR configuration setting is now called \f(CW\*(C`lang\*(C'\fR.
.PP
Diffs for code that uses Text::Pspell might look like:
.PP
.Vb 2
\&    \-    use Text::Pspell;
\&    +    use Text::Aspell;
\&
\&    \-    $speller = Text::Pspell\->new;
\&    +    $speller = Text::Aspell\->new;
\&
\&    \-    $speller\->create_manager || die "Failed to create speller: " . $speller\->errstr;
\&    +    $speller\->create_speller || die "Failed to create speller: " . $speller\->errstr;
.Ve
.PP
If you used a custom dictionary installed in non-standard location and indexed the dictionary with
Aspell/Pspell .pwli files you will need to change how you access your dictionary (e.g.
by setting the \*(L"master\*(R" configuration setting with the path to the dictionary).
See the \s-1GNU\s0 Aspell documentation for details.
.SH "BUGS"
.IX Header "BUGS"
Probably.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
.SH "AUTHOR"
.IX Header "AUTHOR"
Bill Moseley moseley@hank.org.
.PP
This module is based on a perl module written by Doru Theodor Petrescu <pdoru@kappa.ro>.
.PP
Aspell is written and maintained by Kevin Atkinson.
.PP
Please see:
.PP
.Vb 1
\&    http://aspell.net
.Ve