aspell: Through the C API
1
1 6.1 Through the C API
1 =====================
1
1 The Aspell library contains two main classes and several helper
1 classes. The two main classes are `AspellConfig' and `AspellSpeller'.
1 The `AspellConfig' class is used to set initial defaults and to change
1 spell checker specific options. The `AspellSpeller' class does most of
1 the real work. The `C API' is responsible for managing the
1 dictionaries, checking if a word is in the dictionary, and coming up
1 with suggestions among other things. There are many helper classes the
1 important ones are `AspellWordList', `AspellMutableWordList',
1 `Aspell*Enumeration'. The `AspellWordList' classes is used for
1 accessing the suggestion list, as well as the personal and suggestion
1 word list currently in use. The `AspellMutableWordList' is used to
1 manage the personal, and perhaps other, word lists. The
1 `Aspell*Enumeration' classes are used for iterating through a list.
1
1 6.1.1 Usage
1 -----------
1
1 To use Aspell your application should include `aspell.h'. In order to
1 ensure that all the necessary libraries are linked in libtool should be
1 used to perform the linking. When using libtool simply linking with
1 `-laspell' should be all that is necessary. When using shared
1 libraries you might be able to simply link `-laspell', but this is not
1 recommended. This version of Aspell uses the CVS version of libtool
1 however released versions of libtool should also work.
1
1 When your application first starts you should get a new configuration
1 class with the command:
1
1 AspellConfig * spell_config = new_aspell_config();
1
1 which will create a new `AspellConfig' class. It is allocated with
1 `new' and it is your responsibility to delete it with
1 `delete_aspell_config'. Once you have the config class you should set
1 some variables. The most important one is the language variable. To
1 do so use the command:
1
1 aspell_config_replace(spell_config, "lang", "en_US");
1
1 which will set the default language to use to American English. The
1 language is expected to be the standard two letter ISO 639 language
1 code, with an optional two letter ISO 3166 country code after an
1 underscore. You can set the preferred size via the `size' option, any
1 extra info via the `variety' option, and the encoding via the
1 `encoding' option. Other things you might want to set is the preferred
1 spell checker to use, the search path for dictionaries, and the like --
1 see ⇒The Options, for a list of all available options.
1
1 Whenever a new document is created a new `AspellSpeller' class
1 should also be created. There should be one speller class per
1 document. To create a new speller class use the `new_aspell_speller'
1 and then cast it up using `to_aspell_speller' like so:
1
1 AspellCanHaveError * possible_err = new_aspell_speller(spell_config);
1 AspellSpeller * spell_checker = 0;
1 if (aspell_error_number(possible_err) != 0)
1 puts(aspell_error_message(possible_err));
1 else
1 spell_checker = to_aspell_speller(possible_err);
1
1 which will create a new `AspellSpeller' class using the defaults found
1 in `spell_config'. To find out which dictionary is selected the
1 `lang', `size', and `variety' options may be examined. To find out the
1 exact name of the dictionary the `master' option may be examined as
1 well as the `master-flags' options to see if there were any special
1 flags that were passed on to the module. The `module' option way also
1 be examined to figure out which speller module was selected, but since
1 there is only one this option will always be the same.
1
1 If for some reason you want to use different defaults simply clone
1 `spell_config' and change the setting like so:
1
1 AspellConfig * spell_config2 = aspell_config_clone(spell_config);
1 aspell_config_replace(spell_config2, "lang","nl");
1 possible_err = new_aspell_speller(spell_config2);
1 delete_aspell_config(spell_config2);
1
1 Once the speller class is created you can use the `check' method to
1 see if a word in the document is correct like so:
1
1 int correct = aspell_speller_check(spell_checker, WORD, SIZE);
1
1 WORD is expected to be a `const char *' character string. If the
1 encoding is set to be `ucs-2' or `ucs-4' WORD is expected to be a cast
1 from either `const u16int *' or `const u32int *' respectively.
1 `u16int' and `u32int' are generally `unsigned short' and `unsigned int'
1 respectively. SIZE is the length of the string or `-1' if the string
1 is null terminated. If the string is a cast from `const u16int *' or
1 `const u32int *' then `size' is the amount of space in bytes the string
1 takes up after being cast to `const char *' and not the true size of
1 the string. `sspell_speller_check' will return `0' if it is not found
1 and non-zero otherwise.
1
1 If the word is not correct, then the `suggest' method can be used to
1 come up with likely replacements.
1
1 AspellWordList * suggestions = aspell_speller_suggest(spell_checker,
1 WORD, SIZE);
1 AspellStringEnumeration * elements = aspell_word_list_elements(suggestions);
1 const char * word;
1 while ( (word = aspell_string_enumeration_next(aspell_elements)) != NULL )
1 {
1 // add to suggestion list
1 }
1 delete_aspell_string_enumeration(elements);
1
1 Notice how `elements' is deleted but `suggestions' is not. The
1 value returned by `suggestions' is only valid to the next call to
1 `suggest'. Once a replacement is made the `store_repl' method should
1 be used to communicate the replacement pair back to the spell checker
1 (for the reason, ⇒Notes on Storing Replacement Pairs). Its
1 usage is as follows:
1
1 aspell_speller_store_repl(spell_checker, MISSPELLED_WORD, SIZE,
1 CORRECTLY_SPELLED_WORD, SIZE);
1
1 If the user decided to add the word to the session or personal
1 dictionary the the word can be be added using the `add_to_session' or
1 `add_to_personal' methods respectively like so:
1
1 aspell_speller_add_to_session|personal(spell_checker, word, size);
1
1 It is better to let the spell checker manage these words rather than
1 doing it yourself so that the words have a chance of appearing in the
1 suggestion list.
1
1 Finally, when the document is closed the `AspellSpeller' class
1 should be deleted like so:
1
1 delete_aspell_speller(spell_checker);
1
1 6.1.2 API Reference
1 -------------------
1
1 Methods that return a boolean result generally return `false' on error
1 and `true' otherwise. To find out what went wrong use the
1 `error_number' and `error_message' methods. Unless otherwise stated
1 methods that return a `const char *' will return `NULL' on error. In
1 general, the character string returned is only valid until the next
1 method which returns a `const char *' is called.
1
1 For the details of the various classes please see the header files.
1 In the future I will generate class references using some automated
1 tool.
1
1 6.1.3 Examples
1 --------------
1
1 Two simple examples are included in the examples directory. The
1 `example-c' program demonstrates most of the Aspell library
1 functionality and the `list-dicts' lists the available dictionaries.
1
1 6.1.4 Notes About Thread Safety
1 -------------------------------
1
1 Aspell should be thread safe, when used properly, as long as the
1 underlying compiler, C and C++ library is thread safe. Aspell objects,
1 including the AspellSpeller class, should not be used by multiple
1 threads unless they are protected by locks or it is only accessed by
1 read-only methods. A method is read-only only if a `const' object is
1 passed in. Many methods that seam to be read-only are not because they
1 may store state information in the object.
1