<html lang="en">
<head>
<title>Through the C API - GNU Aspell 0.60.6.1</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="description" content="Aspell 0.60.6.1 spell checker user's manual.">
<meta name="generator" content="makeinfo 4.8">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Writing-programs-to-use-Aspell.html#Writing-programs-to-use-Aspell" title="Writing programs to use Aspell">
<link rel="next" href="Through-A-Pipe.html#Through-A-Pipe" title="Through A Pipe">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
This is the user's manual for Aspell
GNU Aspell is a spell checker designed to eventually replace Ispell.
It can either be used as a library or as an independent spell checker.
Copyright (C) 2000--2011 Kevin Atkinson.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.1 or any later version published by the Free Software
Foundation; with no Invariant Sections, no Front-Cover Texts and
no Back-Cover Texts. A copy of the license is included in the
section entitled "GNU Free Documentation License".
-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
--></style>
</head>
<body>
<div class="node">
<p>
<a name="Through-the-C-API"></a>
Next: <a rel="next" accesskey="n" href="Through-A-Pipe.html#Through-A-Pipe">Through A Pipe</a>,
Up: <a rel="up" accesskey="u" href="Writing-programs-to-use-Aspell.html#Writing-programs-to-use-Aspell">Writing programs to use Aspell</a>
<hr>
</div>
<h3 class="section">6.1 Through the C API</h3>
<p>The Aspell library contains two main classes and several helper
classes. The two main classes are <code>AspellConfig</code> and
<code>AspellSpeller</code>. The <code>AspellConfig</code> class is used to set
initial defaults and to change spell checker specific options. The
<code>AspellSpeller</code> class does most of the real work. The
<code>C API</code> 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
<code>AspellWordList</code>, <code>AspellMutableWordList</code>,
<code>Aspell*Enumeration</code>. The <code>AspellWordList</code> classes is used
for accessing the suggestion list, as well as the personal and
suggestion word list currently in use. The
<code>AspellMutableWordList</code> is used to manage the personal, and
perhaps other, word lists. The <code>Aspell*Enumeration</code> classes are
used for iterating through a list.
<h4 class="subsection">6.1.1 Usage</h4>
<p>To use Aspell your application should include <samp><span class="file">aspell.h</span></samp>. 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 <code>-laspell</code> should be all that is necessary. When
using shared libraries you might be able to simply link
<code>-laspell</code>, but this is not recommended. This version of Aspell
uses the CVS version of libtool however released versions of libtool
should also work.
<p>When your application first starts you should get a new configuration
class with the command:
<pre class="smallexample"> AspellConfig * spell_config = new_aspell_config();
</pre>
<p class="noindent">which will create a new <code>AspellConfig</code> class. It is allocated
with <samp><span class="command">new</span></samp> and it is your responsibility to delete it with
<code>delete_aspell_config</code>. 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:
<pre class="smallexample"> aspell_config_replace(spell_config, "lang", "en_US");
</pre>
<p class="noindent">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 <samp><span class="option">size</span></samp>
option, any extra info via the <samp><span class="option">variety</span></samp> option, and the
encoding via the <samp><span class="option">encoding</span></samp> option. Other things you might
want to set is the preferred spell checker to use, the search path for
dictionaries, and the like — see <a href="The-Options.html#The-Options">The Options</a>, for a list of
all available options.
<p>Whenever a new document is created a new <code>AspellSpeller</code> class
should also be created. There should be one speller class per
document. To create a new speller class use the
<code>new_aspell_speller</code> and then cast it up using
<code>to_aspell_speller</code> like so:
<pre class="smallexample"> 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);
</pre>
<p class="noindent">which will create a new <code>AspellSpeller</code> class using the defaults
found in <code>spell_config</code>. To find out which dictionary is
selected the <samp><span class="option">lang</span></samp>, <samp><span class="option">size</span></samp>, and <samp><span class="option">variety</span></samp> options
may be examined. To find out the exact name of the dictionary the
<samp><span class="option">master</span></samp> option may be examined as well as the
<samp><span class="option">master-flags</span></samp> options to see if there were any special flags
that were passed on to the module. The <samp><span class="option">module</span></samp> 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.
<p>If for some reason you want to use different defaults simply clone
<code>spell_config</code> and change the setting like so:
<pre class="smallexample"> 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);
</pre>
<p>Once the speller class is created you can use the <code>check</code> method
to see if a word in the document is correct like so:
<pre class="smallexample"> int correct = aspell_speller_check(spell_checker, <var>word</var>, <var>size</var>);
</pre>
<p class="noindent"><var>word</var> is expected to be a <code>const char *</code> character
string. If the encoding is set to be <code>ucs-2</code> or
<code>ucs-4</code> <var>word</var> is expected to be a cast
from either <code>const u16int *</code> or <code>const u32int *</code>
respectively. <code>u16int</code> and <code>u32int</code> are generally
<code>unsigned short</code> and <code>unsigned int</code> respectively.
<var>size</var> is the length of the string or <code>-1</code> if the string
is null terminated. If the string is a cast from <code>const u16int
*</code> or <code>const u32int *</code> then <i>size</i> is the amount of
space in bytes the string takes up after being cast to <code>const
char *</code> and not the true size of the string. <code>sspell_speller_check</code>
will return <code>0</code> if it is not found and non-zero otherwise.
<p>If the word is not correct, then the <code>suggest</code> method can be used
to come up with likely replacements.
<pre class="smallexample"> AspellWordList * suggestions = aspell_speller_suggest(spell_checker,
<var>word</var>, <var>size</var>);
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);
</pre>
<p>Notice how <code>elements</code> is deleted but <code>suggestions</code> is not.
The value returned by <code>suggestions</code> is only valid to the next
call to <code>suggest</code>. Once a replacement is made the
<code>store_repl</code> method should be used to communicate the replacement
pair back to the spell checker (for the reason, see <a href="Notes-on-Storing-Replacement-Pairs.html#Notes-on-Storing-Replacement-Pairs">Notes on Storing Replacement Pairs</a>). Its usage is as follows:
<pre class="smallexample"> aspell_speller_store_repl(spell_checker, <var>misspelled_word</var>, <var>size</var>,
<var>correctly_spelled_word</var>, <var>size</var>);
</pre>
<p>If the user decided to add the word to the session or personal
dictionary the the word can be be added using the
<code>add_to_session</code> or <code>add_to_personal</code> methods respectively
like so:
<pre class="smallexample"> aspell_speller_add_to_session|personal(spell_checker, <i>word</i>, <i>size</i>);
</pre>
<p>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.
<p>Finally, when the document is closed the <code>AspellSpeller</code> class
should be deleted like so:
<pre class="smallexample"> delete_aspell_speller(spell_checker);
</pre>
<h4 class="subsection">6.1.2 API Reference</h4>
<p>Methods that return a boolean result generally return <code>false</code> on
error and <code>true</code> otherwise. To find out what went wrong use the
<code>error_number</code> and <code>error_message</code> methods. Unless
otherwise stated methods that return a <code>const char *</code> will return
<code>NULL</code> on error. In general, the character string returned is
only valid until the next method which returns a <code>const char *</code>
is called.
<p>For the details of the various classes please see the header files.
In the future I will generate class references using some automated
tool.
<h4 class="subsection">6.1.3 Examples</h4>
<p>Two simple examples are included in the examples directory. The
<code>example-c</code> program demonstrates most of the Aspell library
functionality and the <code>list-dicts</code> lists the available
dictionaries.
<h4 class="subsection">6.1.4 Notes About Thread Safety</h4>
<p>Aspell should be thread safe, when used properly, as long as the
underlying compiler, C and C++ library is thread safe. Aspell
objects, including the AspellSpeller class, should not be used by
multiple threads unless they are protected by locks or it is only
accessed by read-only methods. A method is read-only only if a
<code>const</code> object is passed in. Many methods that seam to be
read-only are not because they may store state information in the
object.
</body></html>
