1hspell(3) Ivrix hspell(3)
2
6 hspell - Hebrew spellchecker (C API)
7
9 #include <hspell.h>
10 int hspell_init(struct dict_radix **dictp, int flags);
12 void hspell_uninit(struct dict_radix *dictp);
14 int hspell_check_word(struct dict_radix *dict, const char *word, int
16 *preflen);
17 void hspell_trycorrect(struct dict_radix *dict, const char *word,
19 struct corlist *cl);
20 int corlist_init(struct corlist *cl);
22 int corlist_free(struct corlist *cl);
24 int corlist_n(struct corlist *cl);
26 char *corlist_str(struct corlist *cl, int i);
28 unsigned int hspell_is_canonic_gimatria(const char *word);
30 typedef int hspell_word_split_callback_func(const char *word, const
32 char *baseword, int preflen, int prefspec);
33 int hspell_enum_splits(struct dict_radix *dict, const char *word,
35 hspell_word_split_callback_func *enumf);
36 void hspell_set_dictionary_path(const char *path);
38 const char *hspell_get_dictionary_path(void);
40
42 This manual describes the C API of the Hspell Hebrew spellchecker.
43 Please refer to hspell(1) for a description of the Hspell project, its
44 spelling standard, and how it works.
45 The hspell_init() function must be called first to initialize the
47 Hspell library. It sets up some global structures (see CAVEATS section)
48 and then reads the necessary dictionary files (whose places are fixed
49 when the library is built). The 'dictp' parameter is a pointer to a
50 struct dict_radix* object, which is modified to point to a newly allo‐
51 cated dictionary. A typical hspell_init() call therefore looks like
52 struct dict_radix *dict;
54 hspell_init(&dict, flags);
55 Note that the (struct dict_radix*) type is an opaque pointer - the
57 library user has no access to the separate fields in this structure.
58 The 'flags' parameter can contain a bitwise or'ing of several flags
60 that modify Hspell's default behavior; Turning on HSPELL_OPT_HE_SHEELA
61 allows Hspell to recognize the interrogative He prefix (he ha-she'ela).
62 HSPELL_OPT_DEFAULT is a synonym for turning on no special flag, i.e.,
63 it evaluates to 0.
64 hspell_init() returns 0 on success, or negative numbers on errors. Cur‐
66 rently, the only error is -1, meaning the dictionary files could not be
67 read.
68 The hspell_uninit() function undoes the effects of hspell_init(), free‐
70 ing any memory that was allocated during initialization.
71 The hspell_check_word() function checks whether a certain word is a
73 correct Hebrew word (possibly with prefix particles attached in a syn‐
74 tacticly-correct manner). 1 is returned if the word is correct, or 0 if
75 it is incorrect.
76 The 'word' parameter should be a single Hebrew word, in the iso8859-8
78 encoding, possibly containing the ASCII quote or double-quote charac‐
79 ters (signifying the geresh and gershayim used in Hebrew for abbrevia‐
80 tions, acronyms, and a few foreign sounds). If the calling programs
81 works with other encodings, it must convert the word to iso8859-8
82 first. In particular cp1255 (the MS-Windows Hebrew encoding) extensions
83 to iso8859-8 like niqqud characters, geresh or gershayim, are currently
84 not recognized and must be removed from the word prior to calling
85 hspell_check_word().
86 Into the 'preflen' parameter, the function writes back the number of
88 characters it recognized as a prefix particle - the rest of the 'word'
89 is a stand-alone word. Because Hebrew words typically can be read in
90 several different ways, this feature (of getting just one prefix from
91 one possible reading) is usually not very useful, and it is likely to
92 be removed in a future version.
93 The hspell_enum_splits() function provides a way to get all possible
95 splitting of the given 'word' into an optional prefix particle and a
96 stand-alone word. For each possible (and legal, as some words cannot
97 accept certain prefixes) split, a user-defined callback function is
98 called. This callback function is given the whole word, the length of
99 the prefix, the stand-alone word, and a bitfield which describes what
100 types of words this prefix can get. Note that in some cases, a word
101 beginning with the letter waw gets this waw doubled before a prefix, so
102 sometimes strlen(word)!=strlen(baseword)+preflen.
103 The hspell_trycorrect() tries to find a list of possible corrections
105 for an incorrect word. Because in Hebrew the word density is high (a
106 random string of letters, especially if short, has a high probability
107 of being a correct word), this function attempts to try corrections
108 based on the assumption of a spelling error (replacement of letters
109 that sound alike, missing or spurious immot qri'a), not typo (slipped
110 finger on the keyboard, etc.) - see also CAVEATS.
111 hspell_trycorrect() returns the correction list into a structure of
113 type struct corlist. This structure must be first allocated with a
114 call to corlist_init() and subsequently freed with corlist_free(). The
115 corlist_n() macro returns the number of words held in an allocated
116 corlist, and corlist_str() returns the i'th word. Accordingly, here is
117 an example usage of hspell_trycorrect():
118 struct corlist cl;
120 printf ("Found misspelled word %s. Possible corrections:\n", w);
121 corlist_init (&cl);
122 hspell_trycorrect (dict, w, &cl);
123 for (i=0; i<corlist_n(&cl); i++) {
124 printf ("%s\n", corlist_str(&cl, i));
125 }
126 The hspell_is_canonic_gimatria() function checks whether the given word
128 is a canonic gimatria - i.e., the proper way to write in gimatria the
129 number it represents. The caller might want to accept canonic gimatria
130 as proper Hebrew words, even if hspell_check_word() previously reported
131 such word to be a non-existent word. hspell_is_canonic_gimatria()
132 returns the number represented as gimatria in 'word' if it is indeed
133 proper gimatria (in canonic form), or 0 otherwise.
134 hspell_init() normally reads the dictionary files from a path compiled
136 into the library. This makes sense when the library's code and the dic‐
137 tionaries are distributed together, but in some scenarios the library
138 user might want to use the Hspell dictionaries that are already present
139 on the system in an arbitrary path. The function hspell_set_dictio‐
140 nary_path() can be used to set this path, and should be used before
141 calling hspell_init(). The given path is that of the word list, and
142 other input files have that path with an appended prefix.
143 hspell_get_dictionary_path() can be used to find the current path. On
144 many installations, this defaults to
145 "/usr/local/share/hspell/hebrew.wgz".
146
149 On most systems, the Hspell library is compiled to use the Zlib library
150 for reading the compressed dictionaries. Therefore, a program linking
151 with the Hspell library must also be linked with the Zlib library (usu‐
152 ally, by adding "-lz" to the compilation line).
153 Programs that use autoconf to search for the Hspell library, should
155 remember to tell AC_CHECK_LIB to also link with the -lz library when
156 checking for -lhspell.
157
160 While the API described here has been stable for years, it may change
161 in the future. Users are encouraged to compare the values of the inte‐
162 ger macros HSPELL_VERSION_MAJOR and HSPELL_VERSION_MINOR to those
163 expected by the writer of the program. A third macro, HSPELL_VER‐
164 SION_EXTRA contains a string which can describe subrelease modifica‐
165 tions (e.g., beta versions).
166 The current Hspell C API is very low-level, in the sense that it leaves
168 the user to implement many features that some users take for granted
169 that a spell-checker should provide. For example it doesn't provide any
170 facilities for a user-defined personal dictionary. It also has separate
171 functions for checking valid Hebrew words and valid gimatria, and no
172 function to do both. It is assumed that the caller - a bigger spell-
173 checking library or word processor (for example), will already have
174 these facilities. If not, you may wish to look at the sources of
175 hspell(1) for an example implementation.
176 Currently there is no concept of separate Hspell "contexts" in an
178 application. Some of the context is now global for the entire applica‐
179 tion: currently, a single list of legal prefix-particles is kept, and
180 the dictionary read by hspell_init() is always read from the global
181 default place. This may be solved in a later version, e.g., by switch‐
182 ing to an API like:
183 context = hspell_new_context();
185 hspell_set_dictionary_path(context, "/some/path/hebrew.wgz");
186 hspell_init(context, flags);
187 ...
188 hspell_check_word(context, word, preflenp);
189 Note that despite the global context mentioned above, after initializa‐
191 tion all functions described here are thread-safe, because they only
192 read the dictionary data, not write to it.
193 hspell_trycorrect() is not as powerful as it could have been, with
195 typos or certain kinds of spelling mistakes not giving useful correc‐
196 tion suggestions. Along with more types of corrections, hspell_trycor‐
197 rect() needs a better way to order the likelihood of the corrections,
198 as an unordered list of 100 corrections would be just as useful (or
199 rather, useless) as none.
200 In some cases of errors during hspell_init(), warning messages are
202 printed to the standard errors. This is a bad thing for a library to
203 do.
204 There are too many CAVEATS in this manual.
206
209 The version of hspell described by this manual page is 1.4.
210
212 Copyright (C) 2000-2017, Nadav Har'El <nyh@math.technion.ac.il> and Dan
213 Kenigsberg <danken@cs.technion.ac.il>.
214 Hspell is free software, released under the GNU Affero General Public
216 License (AGPL) version 3. Note that not only the programs in the dis‐
217 tribution, but also the dictionary files and the generated word lists,
218 are licensed under the AGPL. There is no warranty of any kind.
219 See the LICENSE file for more information and the exact license terms.
221 The latest version of this software can be found in
223 http://hspell.ivrix.org.il/
224
226 hspell(1)
227Hspell 1.4 24 June 2017 hspell(3)