manual/aspell.html/Through-the-C-API.html

   1 <html lang="en">
   2 <head>
   3 <title>Through the C API - GNU Aspell 0.60.6.1</title>
   4 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   5 <meta name="description" content="Aspell 0.60.6.1 spell checker user's manual.">
   6 <meta name="generator" content="makeinfo 4.8">
   7 <link title="Top" rel="start" href="index.html#Top">
   8 <link rel="up" href="Writing-programs-to-use-Aspell.html#Writing-programs-to-use-Aspell" title="Writing programs to use Aspell">
   9 <link rel="next" href="Through-A-Pipe.html#Through-A-Pipe" title="Through A Pipe">
  10 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
  11 <!--
  12 This is the user's manual for Aspell
  13
  14 GNU Aspell is a spell checker designed to eventually replace Ispell.
  15 It can either be used as a library or as an independent spell checker.
  16
  17 Copyright (C) 2000--2011 Kevin Atkinson.
  18
  19      Permission is granted to copy, distribute and/or modify this
  20      document under the terms of the GNU Free Documentation License,
  21      Version 1.1 or any later version published by the Free Software
  22      Foundation; with no Invariant Sections, no Front-Cover Texts and
  23      no Back-Cover Texts.  A copy of the license is included in the
  24      section entitled "GNU Free Documentation License".
  25    -->
  26 <meta http-equiv="Content-Style-Type" content="text/css">
  27 <style type="text/css"><!--
  28   pre.display { font-family:inherit }
  29   pre.format  { font-family:inherit }
  30   pre.smalldisplay { font-family:inherit; font-size:smaller }
  31   pre.smallformat  { font-family:inherit; font-size:smaller }
  32   pre.smallexample { font-size:smaller }
  33   pre.smalllisp    { font-size:smaller }
  34   span.sc    { font-variant:small-caps }
  35   span.roman { font-family:serif; font-weight:normal; }
  36   span.sansserif { font-family:sans-serif; font-weight:normal; }
  37 --></style>
  38 </head>
  39 <body>
  40 <div class="node">
  41 <p>
  42 <a name="Through-the-C-API"></a>
  43 Next:&nbsp;<a rel="next" accesskey="n" href="Through-A-Pipe.html#Through-A-Pipe">Through A Pipe</a>,
  44 Up:&nbsp;<a rel="up" accesskey="u" href="Writing-programs-to-use-Aspell.html#Writing-programs-to-use-Aspell">Writing programs to use Aspell</a>
  45 <hr>
  46 </div>
  47
  48 <h3 class="section">6.1 Through the C API</h3>
  49
  50 <p>The Aspell library contains two main classes and several helper
  51 classes.  The two main classes are <code>AspellConfig</code> and
  52 <code>AspellSpeller</code>. The <code>AspellConfig</code> class is used to set
  53 initial defaults and to change spell checker specific options.  The
  54 <code>AspellSpeller</code> class does most of the real work.  The
  55 <code>C API</code> is responsible for managing the dictionaries, checking
  56 if a word is in the dictionary, and coming up with suggestions among
  57 other things. There are many helper classes the important ones are
  58 <code>AspellWordList</code>, <code>AspellMutableWordList</code>,
  59 <code>Aspell*Enumeration</code>.  The <code>AspellWordList</code> classes is used
  60 for accessing the suggestion list, as well as the personal and
  61 suggestion word list currently in use.  The
  62 <code>AspellMutableWordList</code> is used to manage the personal, and
  63 perhaps other, word lists.  The <code>Aspell*Enumeration</code> classes are
  64 used for iterating through a list.
  65
  66 <h4 class="subsection">6.1.1 Usage</h4>
  67
  68 <p>To use Aspell your application should include <samp><span class="file">aspell.h</span></samp>.  In
  69 order to ensure that all the necessary libraries are linked in libtool
  70 should be used to perform the linking.  When using libtool simply
  71 linking with <code>-laspell</code> should be all that is necessary.  When
  72 using shared libraries you might be able to simply link
  73 <code>-laspell</code>, but this is not recommended.  This version of Aspell
  74 uses the CVS version of libtool however released versions of libtool
  75 should also work.
  76
  77    <p>When your application first starts you should get a new configuration
  78 class with the command:
  79
  80 <pre class="smallexample">     AspellConfig * spell_config = new_aspell_config();
  81 </pre>
  82    <p class="noindent">which will create a new <code>AspellConfig</code> class.  It is allocated
  83 with <samp><span class="command">new</span></samp> and it is your responsibility to delete it with
  84 <code>delete_aspell_config</code>.  Once you have the config class you
  85 should set some variables.  The most important one is the language
  86 variable.  To do so use the command:
  87
  88 <pre class="smallexample">     aspell_config_replace(spell_config, "lang", "en_US");
  89 </pre>
  90    <p class="noindent">which will set the default language to use to American English.  The
  91 language is expected to be the standard two letter ISO 639 language
  92 code, with an optional two letter ISO 3166 country code after an
  93 underscore.  You can set the preferred size via the <samp><span class="option">size</span></samp>
  94 option, any extra info via the <samp><span class="option">variety</span></samp> option, and the
  95 encoding via the <samp><span class="option">encoding</span></samp> option.  Other things you might
  96 want to set is the preferred spell checker to use, the search path for
  97 dictionaries, and the like &mdash; see <a href="The-Options.html#The-Options">The Options</a>, for a list of
  98 all available options.
  99
 100    <p>Whenever a new document is created a new <code>AspellSpeller</code> class
 101 should also be created.  There should be one speller class per
 102 document.  To create a new speller class use the
 103 <code>new_aspell_speller</code> and then cast it up using
 104 <code>to_aspell_speller</code> like so:
 105
 106 <pre class="smallexample">     AspellCanHaveError * possible_err = new_aspell_speller(spell_config);
 107      AspellSpeller * spell_checker = 0;
 108      if (aspell_error_number(possible_err) != 0)
 109        puts(aspell_error_message(possible_err));
 110      else
 111        spell_checker = to_aspell_speller(possible_err);
 112 </pre>
 113    <p class="noindent">which will create a new <code>AspellSpeller</code> class using the defaults
 114 found in <code>spell_config</code>.  To find out which dictionary is
 115 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
 116 may be examined.  To find out the exact name of the dictionary the
 117 <samp><span class="option">master</span></samp> option may be examined as well as the
 118 <samp><span class="option">master-flags</span></samp> options to see if there were any special flags
 119 that were passed on to the module.  The <samp><span class="option">module</span></samp> option way
 120 also be examined to figure out which speller module was selected, but
 121 since there is only one this option will always be the same.
 122
 123    <p>If for some reason you want to use different defaults simply clone
 124 <code>spell_config</code> and change the setting like so:
 125
 126 <pre class="smallexample">     AspellConfig * spell_config2 = aspell_config_clone(spell_config);
 127      aspell_config_replace(spell_config2, "lang","nl");
 128      possible_err = new_aspell_speller(spell_config2);
 129      delete_aspell_config(spell_config2);
 130 </pre>
 131    <p>Once the speller class is created you can use the <code>check</code> method
 132 to see if a word in the document is correct like so:
 133
 134 <pre class="smallexample">     int correct = aspell_speller_check(spell_checker, <var>word</var>, <var>size</var>);
 135 </pre>
 136    <p class="noindent"><var>word</var> is expected to be a <code>const char *</code> character
 137 string.  If the encoding is set to be <code>ucs-2</code> or
 138 <code>ucs-4</code> <var>word</var> is expected to be a cast
 139 from either <code>const u16int *</code> or <code>const u32int *</code>
 140 respectively.  <code>u16int</code> and <code>u32int</code> are generally
 141 <code>unsigned short</code> and <code>unsigned int</code> respectively.
 142 <var>size</var> is the length of the string or <code>-1</code> if the string
 143 is null terminated.  If the string is a cast from <code>const u16int
 144 *</code> or <code>const u32int *</code> then <i>size</i> is the amount of
 145 space in bytes the string takes up after being cast to <code>const
 146 char *</code> and not the true size of the string.  <code>sspell_speller_check</code>
 147 will return <code>0</code> if it is not found and non-zero otherwise.
 148
 149    <p>If the word is not correct, then the <code>suggest</code> method can be used
 150 to come up with likely replacements.
 151
 152 <pre class="smallexample">     AspellWordList * suggestions = aspell_speller_suggest(spell_checker,
 153                                                            <var>word</var>, <var>size</var>);
 154      AspellStringEnumeration * elements = aspell_word_list_elements(suggestions);
 155      const char * word;
 156      while ( (word = aspell_string_enumeration_next(aspell_elements)) != NULL )
 157      {
 158        // add to suggestion list
 159      }
 160      delete_aspell_string_enumeration(elements);
 161 </pre>
 162    <p>Notice how <code>elements</code> is deleted but <code>suggestions</code> is not.
 163 The value returned by <code>suggestions</code> is only valid to the next
 164 call to <code>suggest</code>.  Once a replacement is made the
 165 <code>store_repl</code> method should be used to communicate the replacement
 166 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:
 167
 168 <pre class="smallexample">     aspell_speller_store_repl(spell_checker, <var>misspelled_word</var>, <var>size</var>,
 169                                <var>correctly_spelled_word</var>, <var>size</var>);
 170 </pre>
 171    <p>If the user decided to add the word to the session or personal
 172 dictionary the the word can be be added using the
 173 <code>add_to_session</code> or <code>add_to_personal</code> methods respectively
 174 like so:
 175
 176 <pre class="smallexample">     aspell_speller_add_to_session|personal(spell_checker, <i>word</i>, <i>size</i>);
 177 </pre>
 178    <p>It is better to let the spell checker manage these words rather than
 179 doing it yourself so that the words have a chance of appearing in the
 180 suggestion list.
 181
 182    <p>Finally, when the document is closed the <code>AspellSpeller</code> class
 183 should be deleted like so:
 184
 185 <pre class="smallexample">     delete_aspell_speller(spell_checker);
 186 </pre>
 187    <h4 class="subsection">6.1.2 API Reference</h4>
 188
 189 <p>Methods that return a boolean result generally return <code>false</code> on
 190 error and <code>true</code> otherwise.  To find out what went wrong use the
 191 <code>error_number</code> and <code>error_message</code> methods.  Unless
 192 otherwise stated methods that return a <code>const char *</code> will return
 193 <code>NULL</code> on error.  In general, the character string returned is
 194 only valid until the next method which returns a <code>const char *</code>
 195 is called.
 196
 197    <p>For the details of the various classes please see the header files.
 198 In the future I will generate class references using some automated
 199 tool.
 200
 201 <h4 class="subsection">6.1.3 Examples</h4>
 202
 203 <p>Two simple examples are included in the examples directory.  The
 204 <code>example-c</code> program demonstrates most of the Aspell library
 205 functionality and the <code>list-dicts</code> lists the available
 206 dictionaries.
 207
 208 <h4 class="subsection">6.1.4 Notes About Thread Safety</h4>
 209
 210 <p>Aspell should be thread safe, when used properly, as long as the
 211 underlying compiler, C and C++ library is thread safe.  Aspell
 212 objects, including the AspellSpeller class, should not be used by
 213 multiple threads unless they are protected by locks or it is only
 214 accessed by read-only methods.  A method is read-only only if a
 215 <code>const</code> object is passed in.  Many methods that seam to be
 216 read-only are not because they may store state information in the
 217 object.
 218
 219    </body></html>
 220