src/pinyin.h

   1 /*
   2  *  libpinyin
   3  *  Library to deal with pinyin.
   4  *
   5  *  Copyright (C) 2011 Peng Wu <alexepico@gmail.com>
   6  *
   7  *  This program is free software; you can redistribute it and/or modify
   8  *  it under the terms of the GNU General Public License as published by
   9  *  the Free Software Foundation; either version 2 of the License, or
  10  *  (at your option) any later version.
  11  *
  12  *  This program is distributed in the hope that it will be useful,
  13  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  15  *  GNU General Public License for more details.
  16  *
  17  *  You should have received a copy of the GNU General Public License
  18  *  along with this program; if not, write to the Free Software
  19  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  20  */
  21
  22
  23 #ifndef PINYIN_H
  24 #define PINYIN_H
  25
  26 #include <stdio.h>
  27 #include "novel_types.h"
  28 #include "pinyin_custom2.h"
  29 #include "chewing_key.h"
  30 #include "pinyin_parser2.h"
  31
  32 using namespace pinyin;
  33
  34 extern "C" {
  35
  36 typedef struct _pinyin_context_t pinyin_context_t;
  37 typedef struct _pinyin_instance_t pinyin_instance_t;
  38 typedef struct _lookup_candidate_t lookup_candidate_t;
  39
  40 typedef struct _import_iterator_t import_iterator_t;
  41
  42 typedef GArray * CandidateVector; /* GArray of lookup_candidate_t */
  43
  44 enum lookup_candidate_type_t{
  45     NORMAL_CANDIDATE = 1,
  46     DIVIDED_CANDIDATE,
  47     RESPLIT_CANDIDATE
  48 };
  49
  50 struct _lookup_candidate_t{
  51     enum lookup_candidate_type_t m_candidate_type;
  52     phrase_token_t m_token;
  53     ChewingKeyRest m_orig_rest;
  54     gchar * m_new_pinyins;
  55     guint32 m_freq; /* the amplifed gfloat numerical value. */
  56 public:
  57     _lookup_candidate_t() {
  58         m_candidate_type = NORMAL_CANDIDATE;
  59         m_token = null_token;
  60         m_new_pinyins = NULL;
  61         m_freq = 0;
  62     }
  63 };
  64
  65 struct _pinyin_instance_t{
  66     pinyin_context_t * m_context;
  67     gchar * m_raw_full_pinyin;
  68     TokenVector m_prefixes;
  69     ChewingKeyVector m_pinyin_keys;
  70     ChewingKeyRestVector m_pinyin_key_rests;
  71     CandidateConstraints m_constraints;
  72     MatchResults m_match_results;
  73 };
  74
  75 /**
  76  * pinyin_init:
  77  * @systemdir: the system wide language model data directory.
  78  * @userdir: the user's language model data directory.
  79  * @returns: the newly created pinyin context, NULL if failed.
  80  *
  81  * Create a new pinyin context.
  82  *
  83  */
  84 pinyin_context_t * pinyin_init(const char * systemdir, const char * userdir);
  85
  86 /**
  87  * pinyin_load_phrase_library:
  88  * @context: the pinyin context.
  89  * @index: the phrase index to be loaded.
  90  * @returns: whether the load succeeded.
  91  *
  92  * Load the sub phrase library of the index.
  93  *
  94  */
  95 bool pinyin_load_phrase_library(pinyin_context_t * context,
  96                                 guint8 index);
  97
  98 /**
  99  * pinyin_unload_phrase_library:
 100  * @context: the pinyin context.
 101  * @index: the phrase index to be unloaded.
 102  * @returns: whether the unload succeeded.
 103  *
 104  * Unload the sub phrase library of the index.
 105  *
 106  */
 107 bool pinyin_unload_phrase_library(pinyin_context_t * context,
 108                                   guint8 index);
 109
 110 import_iterator_t * pinyin_begin_add_phrases(pinyin_context_t * context,
 111                                              guint8 index);
 112
 113 bool pinyin_add_phrase(import_iterator_t * iterator,
 114                        const char * phrase,
 115                        const char * pinyin);
 116
 117 void pinyin_end_add_phrases(import_iterator_t * iterator);
 118
 119 /**
 120  * pinyin_save:
 121  * @context: the pinyin context to be saved into user directory.
 122  * @returns: whether the save succeeded.
 123  *
 124  * Save the user's self-learning information of the pinyin context.
 125  *
 126  */
 127 bool pinyin_save(pinyin_context_t * context);
 128
 129 /**
 130  * pinyin_set_double_pinyin_scheme:
 131  * @context: the pinyin context.
 132  * @scheme: the double pinyin scheme.
 133  * @returns: whether the set double pinyin scheme succeeded.
 134  *
 135  * Change the double pinyin scheme of the pinyin context.
 136  *
 137  */
 138 bool pinyin_set_double_pinyin_scheme(pinyin_context_t * context,
 139                                      DoublePinyinScheme scheme);
 140
 141 /**
 142  * pinyin_set_chewing_scheme:
 143  * @context: the pinyin context.
 144  * @scheme: the chewing scheme.
 145  * @returns: whether the set chewing scheme succeeded.
 146  *
 147  * Change the chewing scheme of the pinyin context.
 148  *
 149  */
 150 bool pinyin_set_chewing_scheme(pinyin_context_t * context,
 151                                ChewingScheme scheme);
 152
 153 /**
 154  * pinyin_fini:
 155  * @context: the pinyin context.
 156  *
 157  * Finalize the pinyin context.
 158  *
 159  */
 160 void pinyin_fini(pinyin_context_t * context);
 161
 162
 163 /**
 164  * pinyin_set_options:
 165  * @context: the pinyin context.
 166  * @options: the pinyin options of the pinyin context.
 167  * @returns: whether the set options scheme succeeded.
 168  *
 169  * Set the options of the pinyin context.
 170  *
 171  */
 172 bool pinyin_set_options(pinyin_context_t * context,
 173                         pinyin_option_t options);
 174
 175 /**
 176  * pinyin_alloc_instance:
 177  * @context: the pinyin context.
 178  * @returns: the newly allocated pinyin instance, NULL if failed.
 179  *
 180  * Allocate a new pinyin instance from the context.
 181  *
 182  */
 183 pinyin_instance_t * pinyin_alloc_instance(pinyin_context_t * context);
 184
 185 /**
 186  * pinyin_free_instance:
 187  * @instance: the pinyin instance.
 188  *
 189  * Free the pinyin instance.
 190  *
 191  */
 192 void pinyin_free_instance(pinyin_instance_t * instance);
 193
 194
 195 /**
 196  * pinyin_guess_sentence:
 197  * @instance: the pinyin instance.
 198  * @returns: whether the sentence are guessed successfully.
 199  *
 200  * Guess a sentence from the saved pinyin keys in the instance.
 201  *
 202  */
 203 bool pinyin_guess_sentence(pinyin_instance_t * instance);
 204
 205 /**
 206  * pinyin_guess_sentence_with_prefix:
 207  * @instance: the pinyin instance.
 208  * @prefix: the prefix before the sentence.
 209  * @returns: whether the sentence are guessed successfully.
 210  *
 211  * Guess a sentence from the saved pinyin keys with a prefix.
 212  *
 213  */
 214 bool pinyin_guess_sentence_with_prefix(pinyin_instance_t * instance,
 215                                        const char * prefix);
 216
 217 /**
 218  * pinyin_phrase_segment:
 219  * @instance: the pinyin instance.
 220  * @sentence: the utf-8 sentence to be segmented.
 221  * @returns: whether the sentence are segmented successfully.
 222  *
 223  * Segment a sentence and saved the result in the instance.
 224  *
 225  */
 226 bool pinyin_phrase_segment(pinyin_instance_t * instance,
 227                            const char * sentence);
 228
 229 /**
 230  * pinyin_get_sentence:
 231  * @instance: the pinyin instance.
 232  * @sentence: the saved sentence in the instance.
 233  * @returns: whether the sentence is already saved in the instance.
 234  *
 235  * Get the sentence from the instance.
 236  *
 237  * Note: the returned sentence should be freed by g_free().
 238  *
 239  */
 240 bool pinyin_get_sentence(pinyin_instance_t * instance,
 241                          char ** sentence);
 242
 243 /**
 244  * pinyin_parse_full_pinyin:
 245  * @instance: the pinyin instance.
 246  * @onepinyin: a single full pinyin to be parsed.
 247  * @onekey: the parsed key.
 248  * @returns: whether the parse is successfully.
 249  *
 250  * Parse a single full pinyin.
 251  *
 252  */
 253 bool pinyin_parse_full_pinyin(pinyin_instance_t * instance,
 254                               const char * onepinyin,
 255                               ChewingKey * onekey);
 256
 257 /**
 258  * pinyin_parse_more_full_pinyins:
 259  * @instance: the pinyin instance.
 260  * @pinyins: the full pinyins to be parsed.
 261  * @returns: the parsed length of the full pinyins.
 262  *
 263  * Parse multiple full pinyins and save it in the instance.
 264  *
 265  */
 266 size_t pinyin_parse_more_full_pinyins(pinyin_instance_t * instance,
 267                                       const char * pinyins);
 268
 269 /**
 270  * pinyin_parse_double_pinyin:
 271  * @instance: the pinyin instance.
 272  * @onepinyin: the single double pinyin to be parsed.
 273  * @onekey: the parsed key.
 274  * @returns: whether the parse is successfully.
 275  *
 276  * Parse a single double pinyin.
 277  *
 278  */
 279 bool pinyin_parse_double_pinyin(pinyin_instance_t * instance,
 280                                 const char * onepinyin,
 281                                 ChewingKey * onekey);
 282
 283 /**
 284  * pinyin_parse_more_double_pinyins:
 285  * @instance: the pinyin instance.
 286  * @pinyins: the double pinyins to be parsed.
 287  * @returns: the parsed length of the double pinyins.
 288  *
 289  * Parse multiple double pinyins and save it in the instance.
 290  *
 291  */
 292 size_t pinyin_parse_more_double_pinyins(pinyin_instance_t * instance,
 293                                         const char * pinyins);
 294
 295 /**
 296  * pinyin_parse_chewing:
 297  * @instance: the pinyin instance.
 298  * @onechewing: the single chewing to be parsed.
 299  * @onekey: the parsed key.
 300  * @returns: whether the parse is successfully.
 301  *
 302  * Parse a single chewing.
 303  *
 304  */
 305 bool pinyin_parse_chewing(pinyin_instance_t * instance,
 306                           const char * onechewing,
 307                           ChewingKey * onekey);
 308
 309 /**
 310  * pinyin_parse_more_chewings:
 311  * @instance: the pinyin instance.
 312  * @chewings: the chewings to be parsed.
 313  * @returns: the parsed length of the chewings.
 314  *
 315  * Parse multiple chewings and save it in the instance.
 316  *
 317  */
 318 size_t pinyin_parse_more_chewings(pinyin_instance_t * instance,
 319                                   const char * chewings);
 320
 321 /**
 322  * pinyin_in_chewing_keyboard:
 323  * @instance: the pinyin instance.
 324  * @key: the input key.
 325  * @symbol: the chewing symbol.
 326  * @returns: whether the key is in current chewing scheme.
 327  *
 328  * Check whether the input key is in current chewing scheme.
 329  *
 330  */
 331 bool pinyin_in_chewing_keyboard(pinyin_instance_t * instance,
 332                                 const char key, const char ** symbol);
 333 /**
 334  * pinyin_get_candidates:
 335  * @instance: the pinyin instance.
 336  * @offset: the offset in the pinyin keys.
 337  * @candidates: The GArray of token candidates.
 338  * @returns: whether a list of tokens are gotten.
 339  *
 340  * Get the candidates at the offset.
 341  *
 342  */
 343 bool pinyin_get_candidates(pinyin_instance_t * instance,
 344                            size_t offset,
 345                            TokenVector candidates);
 346
 347 /**
 348  * pinyin_get_full_pinyin_candidates:
 349  * @instance: the pinyin instance.
 350  * @offset: the offset in the pinyin keys.
 351  * @candidates: the GArray of lookup_candidate_t candidates.
 352  * @returns: whether a list of lookup_candidate_t candidates are gotten.
 353  *
 354  * Get the full pinyin candidates at the offset.
 355  *
 356  */
 357 bool pinyin_get_full_pinyin_candidates(pinyin_instance_t * instance,
 358                                        size_t offset,
 359                                        CandidateVector candidates);
 360
 361 /**
 362  * pinyin_choose_candidate:
 363  * @instance: the pinyin instance.
 364  * @offset: the offset in the pinyin keys.
 365  * @token: the selected candidate.
 366  * @returns: the cursor after the chosen candidate.
 367  *
 368  * Choose an candidate at the offset.
 369  *
 370  */
 371 int pinyin_choose_candidate(pinyin_instance_t * instance,
 372                             size_t offset,
 373                             phrase_token_t token);
 374
 375 /**
 376  * pinyin_choose_full_pinyin_candidate:
 377  * @instance: the pinyin instance.
 378  * @offset: the offset in the pinyin keys.
 379  * @candidate: the selected lookup_candidate_t candidate.
 380  * @returns: the cursor after the chosen candidate.
 381  *
 382  * Choose a full pinyin candidate at the offset.
 383  *
 384  */
 385 int pinyin_choose_full_pinyin_candidate(pinyin_instance_t * instance,
 386                                         size_t offset,
 387                                         lookup_candidate_t * candidate);
 388
 389 /**
 390  * pinyin_clear_constraint:
 391  * @instance: the pinyin instance.
 392  * @offset: the offset in the pinyin keys.
 393  * @returns: whether the constraint is cleared.
 394  *
 395  * Clear the previous chosen candidate.
 396  *
 397  */
 398 bool pinyin_clear_constraint(pinyin_instance_t * instance,
 399                              size_t offset);
 400
 401 /**
 402  * pinyin_clear_constraints:
 403  * @instance: the pinyin instance.
 404  * @returns: whether the constraints are cleared.
 405  *
 406  * Clear all constraints.
 407  *
 408  */
 409 bool pinyin_clear_constraints(pinyin_instance_t * instance);
 410
 411 /**
 412  * pinyin_translate_token:
 413  * @instance: the pinyin instance.
 414  * @token: the phrase token.
 415  * @word: the phrase in utf-8.
 416  * @returns: whether the token is valid.
 417  *
 418  * Translate the token to utf-8 phrase.
 419  *
 420  * Note: the returned word should be freed by g_free().
 421  *
 422  */
 423 bool pinyin_translate_token(pinyin_instance_t * instance,
 424                             phrase_token_t token, char ** word);
 425
 426 /**
 427  * pinyin_train:
 428  * @instance: the pinyin instance.
 429  * @returns: whether the sentence is trained.
 430  *
 431  * Train the current user input sentence.
 432  *
 433  */
 434 bool pinyin_train(pinyin_instance_t * instance);
 435
 436 /**
 437  * pinyin_reset:
 438  * @instance: the pinyin instance.
 439  * @returns: whether the pinyin instance is resetted.
 440  *
 441  * Reset the pinyin instance.
 442  *
 443  */
 444 bool pinyin_reset(pinyin_instance_t * instance);
 445
 446
 447 /* hack here. */
 448 typedef ChewingKey PinyinKey;
 449 typedef ChewingKeyRest PinyinKeyPos;
 450 typedef ChewingKeyVector PinyinKeyVector;
 451 typedef ChewingKeyRestVector PinyinKeyPosVector;
 452
 453
 454 #define LIBPINYIN_FORMAT_VERSION  "0.6.91"
 455
 456 };
 457
 458 #endif