Aspell(3pm)

📦
version 0.09 · 9 versions
, in ubuntu stonking

💖 Text::Aspell — Perl interface to the GNU Aspell library 💖

okay so hi bestie 🌸 welcome to Aspell(3pm), aka the user-contributed Perl doc for Text::Aspell. This is the little Perl bestie who lets you talk to the GNU Aspell library directly. Let's get into it 💅

✨ 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 is a Perl interface to the GNU Aspell library, no cap 🫶. The whole reason it exists? The vibe was: what if you needed to look up many words, one at a time, in a single session — like spell-checking a whole document that's just living in memory. That's the job. That's the assignment. ✨

The GNU C interface is described at:

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

Lowkey worth your time to peek at how config and speller (manager) objects get created in the Aspell C API, because some of that machinery is hidden inside the Text::Aspell module 🙈.

For example, with Text::Aspell you do not have to explicitly create a speller object. The speller (manager) object just… appears ✨ automatically the first time you call suggest() or check().

Also note: once that speller object exists, some (all?) config options cannot be changed. Like, setting configuration options such as "lang" is literally what determines which dictionary Aspell will use. Once the speller object is created, that dictionary is the one you're getting. I.e. setting "lang" after the speller object is created will have no effect. So set your stuff early, bestie 💀

🧚 DEPENDENCIES 🧚

You MUST have installed GNU Aspell library version 0.50.1 or higher on your system before installing this Text::Aspell Perl module. Periodt. 👑

If you're 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. Bestie. 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. Don't skip that step, it's giving "mysterious test failures" otherwise 🍓.

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 brand 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, like, 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, use the get_option_as_list() method instead. 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 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 ✨

Okay so listen bestie 💖 — Text::Aspell works with GNU Aspell and it's the glow-up replacement for the module Text::Pspell. And Text::Pspell? It's no longer supported. Gone. Retired. We don't talk about her anymore 🙈

The good news is the upgrade should be a simple process — like, actually simple, not "simple" in a README-that-lies way. Only one method name changed:

  • create_manager is now called create_speller

And here's the tea 🍓: code that was designed to use the old Text::Pspell module might not even call the create_manager method at all, so honestly this might not even be an issue for you. Vibe check passed.

Also, the language_tag configuration setting is now called lang. That's it. That's the whole rename arc.

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

One more thing, and this is the "read carefully" moment 🫶 — if you used a custom dictionary installed in a non-standard location and you indexed that 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). For all the deets on that, see the GNU Aspell documentation. Not me giving you homework, it's just how it is 😭

💀 BUGS 💀

Probably.

That's it. That's the whole section. Iconic honestly. Not a bug report, a ✨lifestyle✨.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Slay, open source queen 👑

👑 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

and that's the whole page bestie!! 💅 this was from perl v5.42.3, dated 2026-08-19, and yes it's the Aspell(3pm) manual page — go forth and spell check everything, no cap 🦋💜

📦 where this page comes from