1Aspell(3) User Contributed Perl Documentation Aspell(3)
2
6 Text::Aspell - Perl interface to the GNU Aspell library
7
9 use Text::Aspell;
10 my $speller = Text::Aspell->new;
11 die unless $speller;
13 # Set some options
16 $speller->set_option('lang','en_US');
17 $speller->set_option('sug-mode','fast');
18 # check a word
21 print $speller->check( $word )
22 ? "$word found\n"
23 : "$word not found!\n";
24 # lookup up words
26 my @suggestions = $speller->suggest( $misspelled );
27 # lookup config options
30 my $language = $speller->get_option('lang');
31 print $speller->errstr unless defined $language;
32 # fetch a config item that is a list
34 my @sgml_extensions = $speller->get_option_as_list('sgml-extension');
35 # fetch the configuration keys and their default settings
38 my $options = $speller->fetch_option_keys;
39 # or dump config settings to STDOUT
41 $speller->print_config || $speller->errstr;
42 # What dictionaries are installed as simple strings
47 my @dicts = $speller->list_dictionaries;
48 # or as an array of hashes
50 @dicts = $speller->dictionary_info;
51 print Data::Dumper::Dumper( \@dicts );
52 Here's an example how to create and use your own word list
54 Create a dictionary:
56 $ aspell --lang=en create master ./dictionary.local < space_separated_word_list
58 Then in your code:
60 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 The GNU C interface is described at:
76 http://aspell.net/man-html/Through-the-C-API.html#Through-the-C-API
78 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 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 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 Aspell can source can be downloaded from:
101 http://aspell.net
103 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 You must also have the English dictionary installed when running the
110 module's test suite.
111 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 $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 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 $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 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 $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 $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 Returns "undef" on error, and the error message can be printed with
151 $speller->errstr.
152 Note that this may return different results depending on if it's
154 called before or after $speller->create_speller is called.
155 @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 Returns "undef" on error, and the error message can be printed with
161 $speller->errstr.
162 Note that this may return different results depending on if it's
164 called before or after $speller->create_speller is called.
165 $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 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 $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 $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 $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 This method is deprecated.
189 $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 This calls $speller->create_speller if the speller has not been
197 created by an explicit call to $speller->create_speller.
198 @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 $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 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 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 $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 $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 (July 2005 note: best to ignore any return value for now)
233 $speller->save_all_word_lists;
235 Writes any pending word lists to disk.
236 $speller->clear_session;
238 Clears the current session word list.
239 @dicts = $speller->list_dictionaries;
241 This returns an array of installed dictionary files. Each is a
242 single string formatted as:
243 [name]:[code]:[jargon]:[size]:[module]
245 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 $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 {
256 'module' => 'default',
257 'code' => 'en_US',
258 'size' => 60,
259 'jargon' => 'w-accents',
260 'name' => 'en_US-w-accents'
261 },
262 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 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 The "language_tag" configuration setting is now called "lang".
276 Diffs for code that uses Text::Pspell might look like:
278 - use Text::Pspell;
280 + use Text::Aspell;
281 - $speller = Text::Pspell->new;
283 + $speller = Text::Aspell->new;
284 - $speller->create_manager || die "Failed to create speller: " . $speller->errstr;
286 + $speller->create_speller || die "Failed to create speller: " . $speller->errstr;
287 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 This module is based on a perl module written by Doru Theodor Petrescu
305 <pdoru@kappa.ro>.
306 Aspell is written and maintained by Kevin Atkinson.
308 Please see:
310 http://aspell.net
312perl v5.32.0 2020-07-28 Aspell(3)