Provided by: libtext-aspell-perl_0.09-3build4_amd64 bug

NAME

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

SYNOPSIS

           use Text::Aspell;
           my $speller = Text::Aspell->new;

           die unless $speller;

           # Set some options
           $speller->set_option('lang','en_US');
           $speller->set_option('sug-mode','fast');

           # check a word
           print $speller->check( $word )
                 ? "$word found\n"
                 : "$word not found!\n";

           # lookup up words
           my @suggestions = $speller->suggest( $misspelled );

           # lookup config options
           my $language = $speller->get_option('lang');
           print $speller->errstr unless defined $language;

           # fetch a config item that is a list
           my @sgml_extensions = $speller->get_option_as_list('sgml-extension');

           # 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( \@dicts );

       Here's an example how to create and use your own word list

       Create a dictionary:

           $ aspell --lang=en create master ./dictionary.local < space_separated_word_list

       Then in your code:

           use Text::Aspell;
           my $speller = Text::Aspell->new;
           die unless $speller;
           $speller->set_option('master','./dictionary.local');
           # check a word
           print $speller->check( $word )
                 ? "$word found\n"
                 : "$word not found!\n";

DESCRIPTION

       This module provides a Perl interface to the GNU 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.

       The GNU C interface is described at:

           http://aspell.net/man-html/Through-the-C-API.html#Through-the-C-API

       It's worth looking over the way config and speller (manager) objects are created when using the Aspell C
       API as some of that is hidden in the Text::Aspell module.

       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 suggest() or check().

       Note also that once the speller object is created some (all?) config options cannot be changed.  For
       example, setting configuration options such as "lang" are what determine what dictionary Aspell will use.
       Once the speller object is created that dictionary will be used.  I.e. setting "lang" after the speller
       object is created will have no effect.

DEPENDENCIES

       You MUST have installed GNU 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).

       Aspell can source can be downloaded from:

           http://aspell.net

       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.

       You must also have the English dictionary installed when running the module's test suite.

       Also, please see the README and Changes files.  README may have specific information about your platform.

METHODS

       The following methods are available:

       $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 "undef" if the object could not
           be created, which is unlikely.

           Internally, new() creates an object to store Aspell structures (AspellConfig,  AspellSpeller,  and  a
           space for an error string and then calls new_aspell_config();

       $speller->set_option($option_name, $value);
           Sets the configuration option $option_name to the value of $value.  Returns "undef" on error, and the
           error message can be printed with $speller->errstr.

           You should set configuration options before calling the $speller->create_speller method.  See the GNU
           Aspell documentation for the available configuration settings and how (and when) they may be used.

       $speller->remove_option($option_name);
           Removes  (sets  to  the  default  value) the configuration option specified by $option_name.  Returns
           "undef" on error, and the error message can be printed  with  $speller->errstr.   You  may  only  set
           configuration options before calling the $speller->create_speller method.

       $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 get_option_as_list() method.

           Returns "undef" on error, and the error message can be printed with $speller->errstr.

           Note  that  this  may  return  different  results  depending  on  if  it's  called  before  or  after
           $speller->create_speller is called.

       @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 list.

           Returns "undef" on error, and the error message can be printed with $speller->errstr.

           Note  that  this  may  return  different  results  depending  on  if  it's  called  before  or  after
           $speller->create_speller is called.

       $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:

               desc    : A short description of the option
               default : The default value for this option
               type    : The data type of option (see aspell.h)

       $speller->print_config;
           Prints the current configuration to STDOUT.  Useful  for  debugging.   Note  that  this  will  return
           different results depending on if it's called before or after $speller->create_speller is called.

       $speller->errstr;
           Returns  the  error  string from the last error.  Check the previous call for an "undef" return value
           before calling this method

       $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.

           This method is deprecated.

       $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 "undef"  on  error,  and  the  error
           message can be printed with $speller->errstr.

           This  calls  $speller->create_speller  if  the  speller  has  not been created by an explicit call to
           $speller->create_speller.

       @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.

       $speller->create_speller;
           This  method  is  normally  not  called  by  your program.  It is called automatically the first time
           $speller->check() or $speller->suggest() is called to create a spelling "speller".

           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.

           The  creation  of  the  speller builds a configuration profile in the speller structure. Results from
           calling print_config() and get_option() will change after calling create_speller().  In general, it's
           best to read config settings  back  after  calling  create_speller()  or  after  calling  spell()  or
           suggest().  Returns "undef" on error, and the error message can be printed with $speller->errstr.

       $speller->add_to_session($word)
       $speller->add_to_personal($word)
           Adds a word to the session or personal word lists.  Words added will be offered as suggestions.

       $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 GNU Aspell documentation for a better description.

           (July 2005 note: best to ignore any return value for now)

       $speller->save_all_word_lists;
           Writes any pending word lists to disk.

       $speller->clear_session;
           Clears the current session word list.

       @dicts = $speller->list_dictionaries;
           This returns an array of installed dictionary files.  Each is a single string formatted as:

               [name]:[code]:[jargon]:[size]:[module]

           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.

       $array_ref = $speller->$speller->dictionary_info;
           Like  the  list_dictionaries() method, this method returns an array of hash references.  For example,
           an entry for a dictionary might have the following hash reference:

               {
                   'module' => 'default',
                   'code' => 'en_US',
                   'size' => 60,
                   'jargon' => 'w-accents',
                   'name' => 'en_US-w-accents'
               },

           Not all hash keys will be available for every dictionary (e.g. the dictionary may not have a "jargon"
           key).

Upgrading from Text::Pspell

       Text::Aspell works with GNU Aspell and is a replacement for the module Text::Pspell.  Text::Pspell is  no
       longer supported.

       Upgrading  should  be a simple process.  Only one method name has changed: "create_manager" is now called
       "create_speller".   Code  designed  to  use  the  old  Text::Pspell  module  may  not   even   call   the
       "create_manager" method so this may not be an issue.

       The "language_tag" configuration setting is now called "lang".

       Diffs for code that uses Text::Pspell might look like:

           -    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;

       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
       "master"  configuration  setting  with the path to the dictionary).  See the GNU Aspell documentation for
       details.

BUGS

       Probably.

COPYRIGHT

       This library is free software; you can redistribute it and/or modify it under  the  same  terms  as  Perl
       itself.

AUTHOR

       Bill Moseley moseley@hank.org.

       This module is based on a perl module written by Doru Theodor Petrescu <pdoru@kappa.ro>.

       Aspell is written and maintained by Kevin Atkinson.

       Please see:

           http://aspell.net

perl v5.38.2                                       2024-03-31                                        Aspell(3pm)