1Aspell(3) User Contributed Perl Documentation Aspell(3)
2
3
4
6 Text::Aspell - Perl interface to the GNU Aspell library
7
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
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
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
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
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
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
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)