There are two main ways to use aspell from within your application. Through the external C API or through a pipe. The internal Aspell API can be used directly but that is not recommended as the actual Aspell API is constantly changing.
The Aspell library contains two main classes and several helper classes. The two main classes are AspellConfig and AspellSpeller The AspellConfig class is used to set initial defaults and to change spell checker specific options. The AspellSpeller class does most of the real work. It is responsible for managing the dictionaries, checking if a word is in the dictionary, and coming up with suggestions among other things. There are many helper classes the important ones are AspellWordList, AspellMutableWordList, Aspell*Enumeration. The AspellWordList classes is used for accessing the suggestion list, as well as the personal and suggestion word list currently in use. The AspellMutableWordList is used to manage the personal, and perhaps other, word lists. The Aspell*Enumeration classes are used for iterating through a list.
To use Aspell your application should include ``aspell.h''. In order to insure 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.
When your application first starts you should get a new configuration class with the command:
When ever 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.
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);
If for some reason you want to use different defaults simply clone spell_config and change the setting like so:
aspell_config_replace(spell_config2, "lang","nl");
possible_err = new_aspell_speller(spell_config2);
delete_aspell_config(spell_config2);
If the word is not correct than the suggest method can be used to come up with likely replacements.
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_manag(elements);
<misspelled word>, <size>,
<correctly spelled word>, <size>);
Finally, when the document is closed the AspellSpeller class should be deleted like so.
Methods that return a boolean result generally return false on error and true other wise. To find out what went wrong use the error_number and error_message methods. Unless otherwise stated methods that return a ``const char *'' will return null on error. In general, the charter string returned is only valid until the next method which returns a ``const char *'' is called.
For the details of the various classes please see the header files. In the future I will generate class references using some automated tool.
Two simple examples are included in the examples directory. The ``example-c'' program demenstracts most of the Aspell library functionary and the ``list-dicts'' lists the available dictionaries.
Read-only Aspell methods and functions should be thread safe as long as exceptions, new, delete, delete[], and STL allocators are thread safe. To the best of my knowledge gcc and egcs meet these requirements. It is up to the programmer to make sure multiple threads do not do thing such as change the dictionaries and add or delete items from the personal or session dictionaries.
When given the pipe or -a command aspell goes into a pipe mode that is compatible with ``ispell -a''. Aspell also defines its own set of extensions to ispell pipe mode.
In this mode, Aspell prints a one-line version identification message, and then begins reading lines of input. For each input line, a single line is written to the standard output for each word checked for spelling on the line. If the word was found in the main dictionary, or your personal dictionary, then the line contains only a '*'.
If the word is not in the dictionary, but there are suggestions, then the line contains an '&', a space, the misspelled word, a space, the number of near misses, the number of characters between the beginning of the line and the beginning of the misspelled word, a colon, another space, and a list of the suggestions separated by commas and spaces.
Finally, if the word does not appear in the dictionary, and there are no suggestions, then the line contains a '#', a space, the misspelled word, a space, and the character offset from the beginning of the line. Each sentence of text input is terminated with an additional blank line, indicating that ispell has completed processing the input line.
These output lines can be summarized as follows:
To summarize these:
In addition to the above commands which are designed for Ispell compatibility Aspell also supports its own extension. All Aspell extensions follow the following format.
$$«command» [data]Where data may or may not be required depending on the particular command. Aspell currently supports the following command.
«num of items»: «item1», «item2», «etc»(Part of the preceding section was directly copied out of the Ispell manual)
The store_repl method and the $$ra should be used because Aspell is able to learn from users misspellings. For example on the first pass a user misspells beginning as beging so aspell suggests:
begging, begin, being, Beijing, bagging, ....However the user then tries "begning" and aspell suggests
beginning, beaning, begging, ...so the user selects beginning. However than, latter on in the document the user misspelles it as begng (NOT beging). Normally aspell will suggest.
began, begging, begin, begun, ....However becuase it knows the user mispelled beginning as beging it will instead suggest:
beginning, began, begging, begin, begun ...I myself often misspelled beginning (and still do) as something close to begging and two many times wind up writing sentences such as "begging with ....".
Please also note that replacements commands has a memory. Which means if you first store the replacement pair:
sicolagest -> psycolagestthen store the replacement pair
psycolagest -> psychologistThe replacement pair
sicolagest -> psychologistwill also get stored so that you don't have to worry about it.