1package Text::Aspell; 2 3require DynaLoader; 4 5use vars qw/ @ISA $VERSION /; 6@ISA = 'DynaLoader'; 7 8$VERSION = '0.09'; 9 10bootstrap Text::Aspell $VERSION; 11 12# Preloaded methods go here. 13 141; 15__END__ 16 17=head1 NAME 18 19Text::Aspell - Perl interface to the GNU Aspell library 20 21=head1 SYNOPSIS 22 23 use Text::Aspell; 24 my $speller = Text::Aspell->new; 25 26 die unless $speller; 27 28 29 # Set some options 30 $speller->set_option('lang','en_US'); 31 $speller->set_option('sug-mode','fast'); 32 33 34 # check a word 35 print $speller->check( $word ) 36 ? "$word found\n" 37 : "$word not found!\n"; 38 39 # lookup up words 40 my @suggestions = $speller->suggest( $misspelled ); 41 42 43 # lookup config options 44 my $language = $speller->get_option('lang'); 45 print $speller->errstr unless defined $language; 46 47 # fetch a config item that is a list 48 my @sgml_extensions = $speller->get_option_as_list('sgml-extension'); 49 50 51 # fetch the configuration keys and their default settings 52 my $options = $speller->fetch_option_keys; 53 54 # or dump config settings to STDOUT 55 $speller->print_config || $speller->errstr; 56 57 58 59 60 # What dictionaries are installed as simple strings 61 my @dicts = $speller->list_dictionaries; 62 63 # or as an array of hashes 64 @dicts = $speller->dictionary_info; 65 print Data::Dumper::Dumper( \@dicts ); 66 67 68 69Here's an example how to create and use your own word list 70 71Create a dictionary: 72 73 $ aspell --lang=en create master ./dictionary.local < space_separated_word_list 74 75Then in your code: 76 77 use Text::Aspell; 78 my $speller = Text::Aspell->new; 79 die unless $speller; 80 $speller->set_option('master','./dictionary.local'); 81 # check a word 82 print $speller->check( $word ) 83 ? "$word found\n" 84 : "$word not found!\n"; 85 86 87 88=head1 DESCRIPTION 89 90This module provides a Perl interface to the GNU Aspell library. This module 91is to meet the need of looking up many words, one at a time, in a single 92session, such as spell-checking a document in memory. 93 94 95The GNU C interface is described at: 96 97 http://aspell.net/man-html/Through-the-C-API.html#Through-the-C-API 98 99It's worth looking over the way config and speller (manager) objects are 100created when using the Aspell C API as some of that is hidden in the 101Text::Aspell module. 102 103For example, with Text::Aspell you do not have to explicitly create a speller 104object. The speller (manager) object is created automatically the first time 105you call suggest() or check(). 106 107Note also that once the speller object is created some (all?) config options 108cannot be changed. For example, setting configuration options such as "lang" 109are what determine what dictionary Aspell will use. Once the speller object is 110created that dictionary will be used. I.e. setting "lang" after the speller 111object is created will have no effect. 112 113 114=head1 DEPENDENCIES 115 116You MUST have installed GNU Aspell library version 0.50.1 or higher on your 117system before installing this Text::Aspell Perl module. If installing Aspell 118using your operating system's package management system, you may need to 119install the Aspell development package (for example, on Debian libaspell-dev). 120 121Aspell can source can be downloaded from: 122 123 http://aspell.net 124 125 126There have been a number of bug reports because people failed to install aspell 127before installing this module. This is an interface to the aspell library 128installed on your system, not a replacement for aspell. 129 130You must also have the English dictionary installed when running the module's 131test suite. 132 133Also, please see the README and Changes files. README may have specific 134information about your platform. 135 136 137 138=head1 METHODS 139 140The following methods are available: 141 142=over 4 143 144=item $speller = Text::Aspell->new; 145 146Creates a new speller object. New does not take any parameters (future version 147may allow options set by passing in a hash reference of options and value pairs). 148Returns C<undef> if the object could not be created, which is unlikely. 149 150Internally, new() creates an object to store Aspell structures (AspellConfig, 151AspellSpeller, and a space for an error string and then calls new_aspell_config(); 152 153=item $speller->set_option($option_name, $value); 154 155Sets the configuration option C<$option_name> to the value of C<$value>. 156Returns C<undef> on error, and the error message can be printed with $speller->errstr. 157 158You should set configuration options before calling the $speller->create_speller 159method. See the GNU Aspell documentation for the available configuration settings 160and how (and when) they may be used. 161 162=item $speller->remove_option($option_name); 163 164Removes (sets to the default value) the configuration option specified by C<$option_name>. 165Returns C<undef> on error, and the error message can be printed with $speller->errstr. 166You may only set configuration options before calling the $speller->create_speller 167method. 168 169=item $string = $speller->get_option($option_name); 170 171Returns the current setting for the given configuration option. The values are strings. 172For configuration options that are lists used the C<get_option_as_list()> method. 173 174Returns C<undef> on error, and the error message can be printed with $speller->errstr. 175 176Note that this may return different results depending on if it's called before or after 177$speller->create_speller is called. 178 179=item @list = $speller->get_option_as_list($option_name); 180 181Returns an array of list items for the given option. Use this method to fetch configuration 182values that are of type I<list>. 183 184Returns C<undef> on error, and the error message can be printed with $speller->errstr. 185 186Note that this may return different results depending on if it's called before or after 187$speller->create_speller is called. 188 189=item $options = $speller->fetch_option_keys; 190 191Returns a hash of hashes. The keys are the possible configuration options 192and the values is a hash with keys of: 193 194 desc : A short description of the option 195 default : The default value for this option 196 type : The data type of option (see aspell.h) 197 198 199=item $speller->print_config; 200 201Prints the current configuration to STDOUT. Useful for debugging. 202Note that this will return different results depending on if it's called before or after 203$speller->create_speller is called. 204 205=item $speller->errstr; 206 207Returns the error string from the last error. Check the previous call for an C<undef> return 208value before calling this method 209 210=item $errnum = $speller->errnum; 211 212Returns the error number from the last error. Some errors may only set the 213error string ($speller->errstr) on errors, so it's best to check use the errstr method 214over this method. 215 216This method is deprecated. 217 218 219=item $found = $speller->check($word); 220 221Checks if a word is found in the dictionary. Returns true if the word is found 222in the dictionary, false but defined if the word is not in the dictionary. 223Returns C<undef> on error, and the error message can be printed with $speller->errstr. 224 225This calls $speller->create_speller if the speller has not been created by an 226explicit call to $speller->create_speller. 227 228=item @suggestions = $speller->suggest($word) 229 230Returns an array of word suggestions for the specified word. The words are returned 231with the best guesses at the start of the list. 232 233 234=item $speller->create_speller; 235 236This method is normally not called by your program. 237It is called automatically the first time $speller->check() or 238$speller->suggest() is called to create a spelling "speller". 239 240You might want to call this when your program first starts up to make the first 241access a bit faster, or if you need to read back configuration settings before 242looking up words. 243 244The creation of the speller builds a configuration 245profile in the speller structure. Results from calling print_config() and get_option() will 246change after calling create_speller(). In general, it's best to read config settings back 247after calling create_speller() or after calling spell() or suggest(). 248Returns C<undef> on error, and the error message can be printed with $speller->errstr. 249 250=item $speller->add_to_session($word) 251 252=item $speller->add_to_personal($word) 253 254Adds a word to the session or personal word lists. 255Words added will be offered as suggestions. 256 257=item $speller->store_replacement($word, $replacement); 258 259This method can be used to instruct the speller which word you used as a replacement 260for a misspelled word. This allows the speller to offer up the replacement next time 261the word is misspelled. See section 6.3 of the GNU Aspell documentation for a better description. 262 263(July 2005 note: best to ignore any return value for now) 264 265=item $speller->save_all_word_lists; 266 267Writes any pending word lists to disk. 268 269=item $speller->clear_session; 270 271Clears the current session word list. 272 273=item @dicts = $speller->list_dictionaries; 274 275This returns an array of installed dictionary files. Each is a single string 276formatted as: 277 278 [name]:[code]:[jargon]:[size]:[module] 279 280Name and code will often be the same, but 281name is the complete name of the dictionary which can be used to directly 282select a dictionary, and code is the language/region code only. 283 284=item $array_ref = $speller->$speller->dictionary_info; 285 286Like the C<list_dictionaries()> method, this method returns an array of 287hash references. For example, an entry for a dictionary might have the 288following hash reference: 289 290 { 291 'module' => 'default', 292 'code' => 'en_US', 293 'size' => 60, 294 'jargon' => 'w-accents', 295 'name' => 'en_US-w-accents' 296 }, 297 298Not all hash keys will be available for every dictionary 299(e.g. the dictionary may not have a "jargon" key). 300 301 302=back 303 304=head1 Upgrading from Text::Pspell 305 306Text::Aspell works with GNU Aspell and is a replacement for the 307module Text::Pspell. Text::Pspell is no longer supported. 308 309Upgrading should be a simple process. Only one method name has changed: 310C<create_manager> is now called C<create_speller>. 311Code designed to use the old Text::Pspell module may not even call the 312C<create_manager> method so this may not be an issue. 313 314The C<language_tag> configuration setting is now called C<lang>. 315 316Diffs for code that uses Text::Pspell might look like: 317 318 - use Text::Pspell; 319 + use Text::Aspell; 320 321 - $speller = Text::Pspell->new; 322 + $speller = Text::Aspell->new; 323 324 - $speller->create_manager || die "Failed to create speller: " . $speller->errstr; 325 + $speller->create_speller || die "Failed to create speller: " . $speller->errstr; 326 327If you used a custom dictionary installed in non-standard location and indexed the dictionary with 328Aspell/Pspell .pwli files you will need to change how you access your dictionary (e.g. 329by setting the "master" configuration setting with the path to the dictionary). 330See the GNU Aspell documentation for details. 331 332 333=head1 BUGS 334 335Probably. 336 337 338=head1 COPYRIGHT 339 340This library is free software; you can redistribute it and/or modify it under 341the same terms as Perl itself. 342 343 344=head1 AUTHOR 345 346Bill Moseley moseley@hank.org. 347 348This module is based on a perl module written by Doru Theodor Petrescu <pdoru@kappa.ro>. 349 350Aspell is written and maintained by Kevin Atkinson. 351 352Please see: 353 354 http://aspell.net 355 356=cut 357