1 /* enchant 2 * Copyright (C) 2003 Dom Lachowicz 3 * 4 * This library is free software; you can redistribute it and/or 5 * modify it under the terms of the GNU Lesser General Public 6 * License as published by the Free Software Foundation; either 7 * version 2.1 of the License, or (at your option) any later version. 8 * 9 * This library is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 * Lesser General Public License for more details. 13 * 14 * You should have received a copy of the GNU Lesser General Public 15 * License along with this library; if not, write to the 16 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 17 * Boston, MA 02110-1301, USA. 18 * 19 * In addition, as a special exception, Dom Lachowicz 20 * gives permission to link the code of this program with 21 * non-LGPL Spelling Provider libraries (eg: a MSFT Office 22 * spell checker backend) and distribute linked combinations including 23 * the two. You must obey the GNU Lesser General Public License in all 24 * respects for all of the code used other than said providers. If you modify 25 * this file, you may extend this exception to your version of the 26 * file, but you are not obligated to do so. If you do not wish to 27 * do so, delete this exception statement from your version. 28 */ 29 30 #ifndef ENCHANT_H 31 #define ENCHANT_H 32 33 #include <stdint.h> /* for uint32_t */ 34 #include <sys/types.h> /* for size_t, ssize_t */ 35 36 37 #ifdef __cplusplus 38 extern "C" { 39 #endif 40 41 typedef struct str_enchant_broker EnchantBroker; 42 typedef struct str_enchant_dict EnchantDict; 43 44 const char *enchant_get_version (void); 45 46 /** 47 * enchant_broker_init 48 * 49 * Returns: A new broker object capable of requesting 50 * dictionaries from providers. 51 */ 52 EnchantBroker *enchant_broker_init (void); 53 54 /** 55 * enchant_broker_free 56 * @broker: A non-null #EnchantBroker 57 * 58 * Destroys the broker object. Must only be called once per broker init 59 */ 60 void enchant_broker_free (EnchantBroker * broker); 61 62 /** 63 * enchant_broker_request_dict 64 * @broker: A non-null #EnchantBroker 65 * @tag: The non-null language tag you wish to request a dictionary for ("en_US", "de_DE", ...) 66 * 67 * Returns: An #EnchantDict, or %null if no suitable dictionary could be found. This dictionary is reference counted. 68 */ 69 EnchantDict *enchant_broker_request_dict (EnchantBroker * broker, const char *const tag); 70 71 /** 72 * enchant_broker_request_pwl_dict 73 * 74 * PWL is a personal wordlist file, 1 entry per line 75 * 76 * @pwl: A non-null pathname in the GLib file name encoding (UTF-8 on Windows) 77 * to the personal wordlist file 78 * 79 * Returns: An EnchantDict. This dictionary is reference counted. 80 */ 81 EnchantDict *enchant_broker_request_pwl_dict (EnchantBroker * broker, const char *const pwl); 82 83 /** 84 * enchant_broker_free_dict 85 * @broker: A non-null #EnchantBroker 86 * @dict: A non-null #EnchantDict 87 * 88 * Releases the dictionary when you are done using it. Must only be called once per dictionary request 89 */ 90 void enchant_broker_free_dict (EnchantBroker * broker, EnchantDict * dict); 91 92 /** 93 * enchant_broker_dict_exists 94 * @broker: A non-null #EnchantBroker 95 * @tag: The non-null language tag you wish to request a dictionary for ("en_US", "de_DE", ...) 96 * 97 * Return existance of the requested dictionary (1 == true, 0 == false) 98 */ 99 int enchant_broker_dict_exists (EnchantBroker * broker, const char * const tag); 100 101 /** 102 * enchant_broker_set_ordering 103 * @broker: A non-null #EnchantBroker 104 * @tag: A non-null language tag (en_US) 105 * @ordering: A non-null ordering (nuspell,aspell,hunspell,hspell) 106 * 107 * Declares a preference of dictionaries to use for the language 108 * described/referred to by @tag. The ordering is a comma delimited 109 * list of provider names. As a special exception, the "*" tag can 110 * be used as a language tag to declare a default ordering for any 111 * language that does not explictly declare an ordering. 112 */ 113 void enchant_broker_set_ordering (EnchantBroker * broker, 114 const char * const tag, 115 const char * const ordering); 116 /** 117 * enchant_broker_get_error 118 * @broker: A non-null broker 119 * 120 * Returns a const char string or NULL describing the last exception in UTF8 encoding. 121 * WARNING: error is transient and is likely cleared as soon as the 122 * next broker operation happens 123 */ 124 const char *enchant_broker_get_error (EnchantBroker * broker); 125 126 /** 127 * EnchantBrokerDescribeFn 128 * @provider_name: The provider's identifier, such as "hunspell" or "aspell", in UTF8 encoding 129 * @provider_desc: A description of the provider, such as "Aspell 0.53" in UTF8 encoding 130 * @provider_dll_file: The provider's DLL filename in Glib file encoding (UTF8 on Windows) 131 * @user_data: Supplied user data, or %null if you don't care 132 * 133 * Callback used to enumerate and describe Enchant's various providers 134 */ 135 typedef void (*EnchantBrokerDescribeFn) (const char * const provider_name, 136 const char * const provider_desc, 137 const char * const provider_dll_file, 138 void * user_data); 139 140 /** 141 * enchant_broker_describe 142 * @broker: A non-null #EnchantBroker 143 * @fn: A non-null #EnchantBrokerDescribeFn 144 * @user_data: Optional user-data 145 * 146 * Enumerates the Enchant providers and tells 147 * you some rudimentary information about them. 148 */ 149 void enchant_broker_describe (EnchantBroker * broker, 150 EnchantBrokerDescribeFn fn, 151 void * user_data); 152 153 /** 154 * enchant_dict_check 155 * @dict: A non-null #EnchantDict 156 * @word: The non-null word you wish to check, in UTF-8 encoding 157 * @len: The byte length of @word, or -1 for strlen (@word) 158 * 159 * Will return an "incorrect" value if any of those pre-conditions 160 * are not met. 161 * 162 * Returns: 0 if the word is correctly spelled, positive if not, negative if error 163 */ 164 int enchant_dict_check (EnchantDict * dict, const char *const word, ssize_t len); 165 166 /** 167 * enchant_dict_suggest 168 * @dict: A non-null #EnchantDict 169 * @word: The non-null word you wish to find suggestions for, in UTF-8 encoding 170 * @len: The byte length of @word, or -1 for strlen (@word) 171 * @out_n_suggs: The location to store the # of suggestions returned, or %null 172 * 173 * Will return an %null value if any of those pre-conditions 174 * are not met. 175 * 176 * Returns: A %null terminated list of UTF-8 encoded suggestions, or %null 177 */ 178 char **enchant_dict_suggest (EnchantDict * dict, const char *const word, 179 ssize_t len, size_t * out_n_suggs); 180 181 /** 182 * enchant_dict_add 183 * @dict: A non-null #EnchantDict 184 * @word: The non-null word you wish to add to your personal dictionary, in UTF-8 encoding 185 * @len: The byte length of @word, or -1 for strlen (@word) 186 * 187 * Remarks: if the word exists in the exclude dictionary, it will be removed from the 188 * exclude dictionary 189 */ 190 void enchant_dict_add (EnchantDict * dict, const char *const word, ssize_t len); 191 192 /** 193 * enchant_dict_add_to_session 194 * @dict: A non-null #EnchantDict 195 * @word: The non-null word you wish to add to this spell-checking session, in UTF-8 encoding 196 * @len: The byte length of @word, or -1 for strlen (@word) 197 * 198 */ 199 void enchant_dict_add_to_session (EnchantDict * dict, const char *const word, ssize_t len); 200 201 /** 202 * enchant_dict_remove 203 * @dict: A non-null #EnchantDict 204 * @word: The non-null word you wish to add to your exclude dictionary and 205 * remove from the personal dictionary, in UTF-8 encoding 206 * @len: The byte length of @word, or -1 for strlen (@word) 207 * 208 */ 209 void enchant_dict_remove (EnchantDict * dict, const char *const word, ssize_t len); 210 211 /** 212 * enchant_dict_remove_from_session 213 * @dict: A non-null #EnchantDict 214 * @word: The non-null word you wish to exclude from this spell-checking session, in UTF-8 encoding 215 * @len: The byte length of @word, or -1 for strlen (@word) 216 * 217 */ 218 void enchant_dict_remove_from_session (EnchantDict * dict, const char *const word, ssize_t len); 219 220 /** 221 * enchant_dict_is_added 222 * @dict: A non-null #EnchantDict 223 * @word: The word you wish to see if it has been added (to your session or dict) in UTF8 encoding 224 * @len: the byte length of @word, or -1 for strlen (@word) 225 */ 226 int enchant_dict_is_added (EnchantDict * dict, const char *const word, ssize_t len); 227 228 /** 229 * enchant_dict_is_removed 230 * @dict: A non-null #EnchantDict 231 * @word: The word you wish to see if it has been removed (from your session or dict) in UTF8 encoding 232 * @len: the byte length of @word, or -1 for strlen (@word) 233 */ 234 int enchant_dict_is_removed (EnchantDict * dict, const char *const word, ssize_t len); 235 236 /** 237 * enchant_dict_store_replacement 238 * @dict: A non-null #EnchantDict 239 * @mis: The non-null word you wish to add a correction for, in UTF-8 encoding 240 * @mis_len: The byte length of @mis, or -1 for strlen (@mis) 241 * @cor: The non-null correction word, in UTF-8 encoding 242 * @cor_len: The byte length of @cor, or -1 for strlen (@cor) 243 * 244 * Notes that you replaced @mis with @cor, so it's possibly more likely 245 * that future occurrences of @mis will be replaced with @cor. So it might 246 * bump @cor up in the suggestion list. 247 */ 248 void enchant_dict_store_replacement (EnchantDict * dict, 249 const char *const mis, ssize_t mis_len, 250 const char *const cor, ssize_t cor_len); 251 252 /** 253 * enchant_dict_free_string_list 254 * @dict: A non-null #EnchantDict 255 * @string_list: A non-null string list returned from enchant_dict_suggest 256 * 257 * Releases the string list 258 */ 259 void enchant_dict_free_string_list (EnchantDict * dict, char **string_list); 260 261 /** 262 * enchant_dict_get_error 263 * @dict: A non-null #EnchantDict 264 * 265 * Returns a const char string or NULL describing the last exception in UTF8 encoding. 266 * WARNING: error is transient. It will likely be cleared as soon as 267 * the next dictionary operation is called. 268 */ 269 const char *enchant_dict_get_error (EnchantDict * dict); 270 271 /** 272 * enchant_dict_get_extra_word_characters 273 * @dict: A non-null #EnchantDict 274 * 275 * Returns a const char UTF-8-encoded string containing the non-letter characters 276 * allowed in a word, e.g. "01234567890’-". If dash occurs, it will be last, so that 277 * the string can be appended to a character class used to match word characters. 278 * 279 * Words containing non-letters not in this string will automatically be rejected 280 * by Enchant. 281 * 282 * Note that for some back-ends the result may be a guess, in which case it 283 * may include characters not actually allowed in the given dictionary. 284 */ 285 const char *enchant_dict_get_extra_word_characters (EnchantDict * dict); 286 287 /** 288 * enchant_dict_is_word_character 289 * @dict: An #EnchantDict, or %null 290 * @uc: A unicode code-point 291 * @n: An integer: 0 if the character is at the start of a word, 1 if it is 292 * in the middle, or 2 if at the end. 293 * 294 * Returns a flag specifying whether the given character is valid at the 295 * given position. 296 * 297 * One way to match a complete word is to check that the first character matches 298 * with n == 0, then proceed matching characters with n == 1 until failure, then 299 * proceed backwards until a character matches with n == 2. 300 * 301 * Note that for some back-ends the result may be a guess, in which case it 302 * may allow characters not actually allowed in the given dictionary. 303 * 304 * If @dict is %null, a built-in implementation is used (FIXME: We should document 305 * behavior for this). If @n is not 0, 1 or 2, then a false flag is returned. 306 */ 307 int enchant_dict_is_word_character (EnchantDict * dict, uint32_t uc, size_t n); 308 309 /** 310 * EnchantDictDescribeFn 311 * @lang_tag: The dictionary's language tag (eg: en_US, de_AT, ...) 312 * @provider_name: The provider's name (eg: Aspell) in UTF8 encoding 313 * @provider_desc: The provider's description (eg: Aspell 0.50.3) in UTF8 encoding 314 * @provider_file: The DLL/SO where this dict's provider was loaded from in Glib file encoding (UTF8 on Windows) 315 * @user_data: Supplied user data, or %null if you don't care 316 * 317 * Callback used to describe an individual dictionary 318 */ 319 typedef void (*EnchantDictDescribeFn) (const char * const lang_tag, 320 const char * const provider_name, 321 const char * const provider_desc, 322 const char * const provider_file, 323 void * user_data); 324 325 /** 326 * enchant_dict_describe 327 * @broker: A non-null #EnchantDict 328 * @dict: A non-null #EnchantDictDescribeFn 329 * @user_data: Optional user-data 330 * 331 * Describes an individual dictionary 332 */ 333 void enchant_dict_describe (EnchantDict * dict, 334 EnchantDictDescribeFn fn, 335 void * user_data); 336 337 /** 338 * enchant_broker_list_dicts 339 * @broker: A non-null #EnchantBroker 340 * @fn: A non-null #EnchantDictDescribeFn 341 * @user_data: Optional user-data 342 * 343 * Enumerates the dictionaries available from 344 * all Enchant providers. 345 */ 346 void enchant_broker_list_dicts (EnchantBroker * broker, 347 EnchantDictDescribeFn fn, 348 void * user_data); 349 350 /** 351 * enchant_set_prefix_dir 352 * 353 * Set the prefix dir. This overrides any auto-detected value, 354 * and can also be used on systems or installations where 355 * auto-detection does not work. 356 * 357 */ 358 void enchant_set_prefix_dir(const char *); 359 360 #ifdef __cplusplus 361 } 362 #endif 363 364 #endif /* ENCHANT_H */ 365