next up previous contents
Next: 7. Adding Support For Up: Aspell .33.7.1 alpha A Previous: 5.
Customizing Aspell   Contents

Subsections

  * 6.1 Though the Pspell API
      + 6.1.1 Notes About Thread Safety
  * 6.2 Through A Pipe
      + 6.2.1 Format of the Data Stream
  * 6.3 Notes of Storing Replacement Pairs

--------------------------------------------------------------------------

6. Writing programs to use Aspell

There are two main ways to use aspell from within your application.
Through the Pspell API or though a pipe. The Aspell API can be used
directly but that is not recommended as the actual Aspell API is
constantly changing.

6.1 Though the Pspell API

To use Aspell through the Pspell API please see the Pspell manual.

6.1.1 Notes About Thread Safety

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.


6.2 Through A Pipe

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.


6.2.1 Format of the Data Stream

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:

OK:
    *
Suggestions:
    & original count offset: miss, miss, ...
None:
    # original offset

When in the -a mode, Aspell will also accept lines of single words
prefixed with any of '*', '&', '@', '+', '-', '~', '#', '!', '%', or '^'.
A line starting with '*' tells ispell to insert the word into the user's
dictionary. A line starting with '&' tells ispell to insert an
all-lowercase version of the word into the user's dictionary. A line
starting with '@' causes ispell to accept this word in the future. A line
starting with '+', followed immediately by a valid mode will cause aspell
to parse future input according the syntax of that formatter. A line
consisting solely of a '+' will place ispell in TEX/LATEX mode (similar to
the -t option) and '-' returns aspell to its default mode (but these
commands are obsolete). A line '~', is ignored for ispell compatibility. A
line prefixed with '#' will cause the personal dictionaries to be saved. A
line prefixed with '!' will turn on terse mode (see below), and a line
prefixed with '%' will return ispell to normal (non-terse) mode. Any input
following the prefix characters '+', '-', '#', '!', '~', or '%' is
ignored, as is any input following. To allow spell-checking of lines
beginning with these characters, a line starting with '^' has that
character removed before it is passed to the spell-checking code. It is
recommended that programmatic interfaces prefix every data line with an
uparrow to protect themselves against future changes in Aspell.

To summarize these:

*word
    Add a word to the personal dictionary
&word
    Insert the all-lowercase version of the word in the personal
    dictionary
@word
    Accept the word, but leave it out of the dictionary
#
    Save the current personal dictionary
~
    Ignored for ispell compatibility.
+
    Enter TEX mode.
+mode
    Enter the mode specified by mode.
-
    Enter the default mode.
!
    Enter terse mode
%
    Exit terse mode
^
    Spell-check the rest of the line

In terse mode, Aspell will not print lines beginning with '*', which
indicate correct words. This significantly improves running speed when the
driving program is going to ignore correct words anyway.

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.

cs option,value
    Change a configuration option.
cr option
    Prints the value of a configuration option.
s word1,word2
    Returns the score of the two words based roughly on how aspell would
    score them.
Sw word
    Returns the soundlike equivalent of the word.
Sl word
    Returns a list of words that have the same soundlike equivalent.
Pw word
    Returns the phoneme equivalent of the word.
pp
    Returns a list of all words in the current personal wordlist.
ps
    Returns a list of all words in the current session dictionary.
l
    Returns the current language name.
ra mis,cor
    Add the word pair to the replacement dictionary for latter use.
    Returns nothing.

Anything returned is returned on its own line line. All lists returned
have the following format

    num of items: item1, item2, etc

(Part of the preceding section was directly copied out of the Ispell
manual)


6.3 Notes of Storing Replacement Pairs

As of version .27 of Aspell storing replacements pairs has a memory. Which
means if you first store the replacement pair:

    sicolagest -> psycolagest

then store the replacement pair

    psycolagest -> psychologist

The replacement pair

    sicolagest -> psychologist

will also get stored so that you don't have to worry about it.

--------------------------------------------------------------------------
next up previous contents
Next: 7. Adding Support For Up: Aspell .33.7.1 alpha A Previous: 5.
Customizing Aspell   Contents
Kevin Atkinson 2001-08-19
