1Aspell(3)             User Contributed Perl Documentation            Aspell(3)
2
3
4

NAME

6       Text::Aspell - Perl interface to the GNU Aspell library
7

SYNOPSIS

9           use Text::Aspell;
10           my $speller = Text::Aspell->new;
11
12           die unless $speller;
13
14
15           # Set some options
16           $speller->set_option('lang','en_US');
17           $speller->set_option('sug-mode','fast');
18
19
20           # check a word
21           print $speller->check( $word )
22                 ? "$word found\n"
23                 : "$word not found!\n";
24
25           # lookup up words
26           my @suggestions = $speller->suggest( $misspelled );
27
28
29           # lookup config options
30           my $language = $speller->get_option('lang');
31           print $speller->errstr unless defined $language;
32
33           # fetch a config item that is a list
34           my @sgml_extensions = $speller->get_option_as_list('sgml-extension');
35
36
37           # fetch the configuration keys and their default settings
38           my $options = $speller->fetch_option_keys;
39
40           # or dump config settings to STDOUT
41           $speller->print_config || $speller->errstr;
42
43
44
45
46           # What dictionaries are installed as simple strings
47           my @dicts = $speller->list_dictionaries;
48
49           # or as an array of hashes
50           @dicts = $speller->dictionary_info;
51           print Data::Dumper::Dumper( \@dicts );
52
53       Here's an example how to create and use your own word list
54
55       Create a dictionary:
56
57           $ aspell --lang=en create master ./dictionary.local < space_separated_word_list
58
59       Then in your code:
60
61           use Text::Aspell;
62           my $speller = Text::Aspell->new;
63           die unless $speller;
64           $speller->set_option('master','./dictionary.local');
65           # check a word
66           print $speller->check( $word )
67                 ? "$word found\n"
68                 : "$word not found!\n";
69

DESCRIPTION

71       This module provides a Perl interface to the GNU Aspell library.  This
72       module is to meet the need of looking up many words, one at a time, in
73       a single session, such as spell-checking a document in memory.
74
75       The GNU C interface is described at:
76
77           http://aspell.net/man-html/Through-the-C-API.html#Through-the-C-API
78
79       It's worth looking over the way config and speller (manager) objects
80       are created when using the Aspell C API as some of that is hidden in
81       the Text::Aspell module.
82
83       For example, with Text::Aspell you do not have to explicitly create a
84       speller object.  The speller (manager) object is created automatically
85       the first time you call suggest() or check().
86
87       Note also that once the speller object is created some (all?) config
88       options cannot be changed.  For example, setting configuration options
89       such as "lang" are what determine what dictionary Aspell will use.
90       Once the speller object is created that dictionary will be used.  I.e.
91       setting "lang" after the speller object is created will have no effect.
92

DEPENDENCIES

94       You MUST have installed GNU Aspell library version 0.50.1 or higher on
95       your system before installing this Text::Aspell Perl module.  If
96       installing Aspell using your operating system's package management
97       system, you may need to install the Aspell development package (for
98       example, on Debian libaspell-dev).
99
100       Aspell can source can be downloaded from:
101
102           http://aspell.net
103
104       There have been a number of bug reports because people failed to
105       install aspell before installing this module.  This is an interface to
106       the aspell library installed on your system, not a replacement for
107       aspell.
108
109       You must also have the English dictionary installed when running the
110       module's test suite.
111
112       Also, please see the README and Changes files.  README may have
113       specific information about your platform.
114

METHODS

116       The following methods are available:
117
118       $speller = Text::Aspell->new;
119           Creates a new speller object.  New does not take any parameters
120           (future version may allow options set by passing in a hash
121           reference of options and value pairs).  Returns "undef" if the
122           object could not be created, which is unlikely.
123
124           Internally, new() creates an object to store Aspell structures
125           (AspellConfig, AspellSpeller, and a space for an error string and
126           then calls new_aspell_config();
127
128       $speller->set_option($option_name, $value);
129           Sets the configuration option $option_name to the value of $value.
130           Returns "undef" on error, and the error message can be printed with
131           $speller->errstr.
132
133           You should set configuration options before calling the
134           $speller->create_speller method.  See the GNU Aspell documentation
135           for the available configuration settings and how (and when) they
136           may be used.
137
138       $speller->remove_option($option_name);
139           Removes (sets to the default value) the configuration option
140           specified by $option_name.  Returns "undef" on error, and the error
141           message can be printed with $speller->errstr.  You may only set
142           configuration options before calling the $speller->create_speller
143           method.
144
145       $string = $speller->get_option($option_name);
146           Returns the current setting for the given configuration option.
147           The values are strings.  For configuration options that are lists
148           used the "get_option_as_list()" method.
149
150           Returns "undef" on error, and the error message can be printed with
151           $speller->errstr.
152
153           Note that this may return different results depending on if it's
154           called before or after $speller->create_speller is called.
155
156       @list = $speller->get_option_as_list($option_name);
157           Returns an array of list items for the given option.  Use this
158           method to fetch configuration values that are of type list.
159
160           Returns "undef" on error, and the error message can be printed with
161           $speller->errstr.
162
163           Note that this may return different results depending on if it's
164           called before or after $speller->create_speller is called.
165
166       $options = $speller->fetch_option_keys;
167           Returns a hash of hashes.  The keys are the possible configuration
168           options and the values is a hash with keys of:
169
170               desc    : A short description of the option
171               default : The default value for this option
172               type    : The data type of option (see aspell.h)
173
174       $speller->print_config;
175           Prints the current configuration to STDOUT.  Useful for debugging.
176           Note that this will return different results depending on if it's
177           called before or after $speller->create_speller is called.
178
179       $speller->errstr;
180           Returns the error string from the last error.  Check the previous
181           call for an "undef" return value before calling this method
182
183       $errnum = $speller->errnum;
184           Returns the error number from the last error.  Some errors may only
185           set the error string ($speller->errstr) on errors, so it's best to
186           check use the errstr method over this method.
187
188           This method is deprecated.
189
190       $found = $speller->check($word);
191           Checks if a word is found in the dictionary.  Returns true if the
192           word is found in the dictionary, false but defined if the word is
193           not in the dictionary.  Returns "undef" on error, and the error
194           message can be printed with $speller->errstr.
195
196           This calls $speller->create_speller if the speller has not been
197           created by an explicit call to $speller->create_speller.
198
199       @suggestions = $speller->suggest($word)
200           Returns an array of word suggestions for the specified word.  The
201           words are returned with the best guesses at the start of the list.
202
203       $speller->create_speller;
204           This method is normally not called by your program.  It is called
205           automatically the first time $speller->check() or
206           $speller->suggest() is called to create a spelling "speller".
207
208           You might want to call this when your program first starts up to
209           make the first access a bit faster, or if you need to read back
210           configuration settings before looking up words.
211
212           The creation of the speller builds a configuration profile in the
213           speller structure. Results from calling print_config() and
214           get_option() will change after calling create_speller().  In
215           general, it's best to read config settings back after calling
216           create_speller() or after calling spell() or suggest().  Returns
217           "undef" on error, and the error message can be printed with
218           $speller->errstr.
219
220       $speller->add_to_session($word)
221       $speller->add_to_personal($word)
222           Adds a word to the session or personal word lists.  Words added
223           will be offered as suggestions.
224
225       $speller->store_replacement($word, $replacement);
226           This method can be used to instruct the speller which word you used
227           as a replacement for a misspelled word.  This allows the speller to
228           offer up the replacement next time the word is misspelled.  See
229           section 6.3 of the GNU Aspell documentation for a better
230           description.
231
232           (July 2005 note: best to ignore any return value for now)
233
234       $speller->save_all_word_lists;
235           Writes any pending word lists to disk.
236
237       $speller->clear_session;
238           Clears the current session word list.
239
240       @dicts = $speller->list_dictionaries;
241           This returns an array of installed dictionary files.  Each is a
242           single string formatted as:
243
244               [name]:[code]:[jargon]:[size]:[module]
245
246           Name and code will often be the same, but name is the complete name
247           of the dictionary which can be used to directly select a
248           dictionary, and code is the language/region code only.
249
250       $array_ref = $speller->$speller->dictionary_info;
251           Like the "list_dictionaries()" method, this method returns an array
252           of hash references.  For example, an entry for a dictionary might
253           have the following hash reference:
254
255               {
256                   'module' => 'default',
257                   'code' => 'en_US',
258                   'size' => 60,
259                   'jargon' => 'w-accents',
260                   'name' => 'en_US-w-accents'
261               },
262
263           Not all hash keys will be available for every dictionary (e.g. the
264           dictionary may not have a "jargon" key).
265

Upgrading from Text::Pspell

267       Text::Aspell works with GNU Aspell and is a replacement for the module
268       Text::Pspell.  Text::Pspell is no longer supported.
269
270       Upgrading should be a simple process.  Only one method name has
271       changed: "create_manager" is now called "create_speller".  Code
272       designed to use the old Text::Pspell module may not even call the
273       "create_manager" method so this may not be an issue.
274
275       The "language_tag" configuration setting is now called "lang".
276
277       Diffs for code that uses Text::Pspell might look like:
278
279           -    use Text::Pspell;
280           +    use Text::Aspell;
281
282           -    $speller = Text::Pspell->new;
283           +    $speller = Text::Aspell->new;
284
285           -    $speller->create_manager || die "Failed to create speller: " . $speller->errstr;
286           +    $speller->create_speller || die "Failed to create speller: " . $speller->errstr;
287
288       If you used a custom dictionary installed in non-standard location and
289       indexed the dictionary with Aspell/Pspell .pwli files you will need to
290       change how you access your dictionary (e.g.  by setting the "master"
291       configuration setting with the path to the dictionary).  See the GNU
292       Aspell documentation for details.
293

BUGS

295       Probably.
296
298       This library is free software; you can redistribute it and/or modify it
299       under the same terms as Perl itself.
300

AUTHOR

302       Bill Moseley moseley@hank.org.
303
304       This module is based on a perl module written by Doru Theodor Petrescu
305       <pdoru@kappa.ro>.
306
307       Aspell is written and maintained by Kevin Atkinson.
308
309       Please see:
310
311           http://aspell.net
312
313
314
315perl v5.32.1                      2021-01-27                         Aspell(3)
Impressum