6.1.1 Usage

To use Aspell your application should include ‘aspell.h’. In order to ensure that all the necessary libraries are linked in libtool should be used to perform the linking. When using libtool simply linking with -laspell should be all that is necessary. When using shared libraries you might be able to simply link -laspell, but this is not recommended. This version of Aspell uses the CVS version of libtool however released versions of libtool should also work.

When your application first starts you should get a new configuration class with the command:

AspellConfig * spell_config = new_aspell_config();

which will create a new AspellConfig class. It is allocated with new and it is your responsibility to delete it with delete_aspell_config. Once you have the config class you should set some variables. The most important one is the language variable. To do so use the command:

aspell_config_replace(spell_config, "lang", "en_US");

which will set the default language to use to American English. The language is expected to be the standard two letter ISO 639 language code, with an optional two letter ISO 3166 country code after an underscore. You can set the preferred size via the ‘size’ option, any extra info via the ‘variety’ option, and the encoding via the ‘encoding’ option. Other things you might want to set is the preferred spell checker to use, the search path for dictionaries, and the like — see The Options, for a list of all available options.

Whenever a new document is created a new AspellSpeller class should also be created. There should be one speller class per document. To create a new speller class use the new_aspell_speller and then cast it up using to_aspell_speller like so:

AspellCanHaveError * possible_err = new_aspell_speller(spell_config);
AspellSpeller * spell_checker = 0;
if (aspell_error_number(possible_err) != 0)
  puts(aspell_error_message(possible_err));
else
  spell_checker = to_aspell_speller(possible_err);

which will create a new AspellSpeller class using the defaults found in spell_config. To find out which dictionary is selected the ‘lang’, ‘size’, and ‘variety’ options may be examined. To find out the exact name of the dictionary the ‘master’ option may be examined as well as the ‘master-flags’ options to see if there were any special flags that were passed on to the module. The ‘module’ option way also be examined to figure out which speller module was selected, but since there is only one this option will always be the same.

If for some reason you want to use different defaults simply clone spell_config and change the setting like so:

AspellConfig * spell_config2 = aspell_config_clone(spell_config);
aspell_config_replace(spell_config2, "lang","nl");
possible_err = new_aspell_speller(spell_config2);
delete_aspell_config(spell_config2);

Once the speller class is created you can use the check method to see if a word in the document is correct like so:

int correct = aspell_speller_check(spell_checker, word, size);

word is expected to be a const char * character string. If the encoding is set to be ucs-2 or ucs-4 word is expected to be a cast from either const u16int * or const u32int * respectively. u16int and u32int are generally unsigned short and unsigned int respectively. size is the length of the string or -1 if the string is null terminated. If the string is a cast from const u16int * or const u32int * then size is the amount of space in bytes the string takes up after being cast to const char * and not the true size of the string. sspell_speller_check will return 0 if it is not found and non-zero otherwise.

If the word is not correct, then the suggest method can be used to come up with likely replacements.

AspellWordList * suggestions = aspell_speller_suggest(spell_checker,
                                                      word, size);
AspellStringEnumeration * elements = aspell_word_list_elements(suggestions);
const char * word;
while ( (word = aspell_string_enumeration_next(aspell_elements)) != NULL )
{
  // add to suggestion list
}
delete_aspell_string_enumeration(elements);

Notice how elements is deleted but suggestions is not. The value returned by suggestions is only valid to the next call to suggest. Once a replacement is made the store_repl method should be used to communicate the replacement pair back to the spell checker (for the reason, see section Notes on Storing Replacement Pairs). Its usage is as follows:

aspell_speller_store_repl(spell_checker, misspelled_word, size,
                          correctly_spelled_word, size);

If the user decided to add the word to the session or personal dictionary the the word can be be added using the add_to_session or add_to_personal methods respectively like so:

aspell_speller_add_to_session|personal(spell_checker, word, size);

It is better to let the spell checker manage these words rather than doing it yourself so that the words have a chance of appearing in the suggestion list.

Finally, when the document is closed the AspellSpeller class should be deleted like so:

delete_aspell_speller(spell_checker);