git.maemo.org Git - mverbiste/blob - verbiste/c-api.h

   1 /*  $Id: c-api.h,v 1.13 2011/01/25 03:16:39 sarrazip Exp $
   2     FrenchVerbDictionary.h - Dictionary of verbs and conjugation templates
   3
   4     verbiste - French conjugation system
   5     Copyright (C) 2003-2010 Pierre Sarrazin <http://sarrazip.com/>
   6
   7     This program is free software; you can redistribute it and/or
   8     modify it under the terms of the GNU General Public License
   9     as published by the Free Software Foundation; either version 2
  10     of the License, or (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., 59 Temple Place - Suite 330, Boston, MA
  20     02111-1307, USA.
  21 */
  22
  23 #ifndef _H_c_api
  24 #define _H_c_api
  25
  26 #include <stddef.h>
  27
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33
  34 typedef enum
  35 {
  36     VERBISTE_INVALID_MODE,
  37     VERBISTE_INFINITIVE_MODE,
  38     VERBISTE_INDICATIVE_MODE,
  39     VERBISTE_CONDITIONAL_MODE,
  40     VERBISTE_SUBJUNCTIVE_MODE,
  41     VERBISTE_IMPERATIVE_MODE,
  42     VERBISTE_PARTICIPLE_MODE,
  43     VERBISTE_GERUND_MODE,
  44
  45     // Greek modes:
  46     VERBISTE_PRESENT_INDICATIVE,
  47     VERBISTE_PRESENT_SUBJUNCTIVE,
  48     VERBISTE_PRESENT_IMPERATIVE,
  49     VERBISTE_PRESENT_GERUND,
  50     VERBISTE_PAST_IMPERFECT_INDICATIVE,
  51     VERBISTE_PAST_PERFECT_INDICATIVE,
  52     VERBISTE_PAST_PERFECT_SUBJUNCTIVE,
  53     VERBISTE_PAST_PERFECT_IMPERATIVE,
  54     VERBISTE_PAST_PERFECT_INFINITIVE
  55
  56 /** Valid conjugation modes. */
  57 } Verbiste_Mode;
  58
  59 typedef enum
  60 {
  61     VERBISTE_INVALID_TENSE,
  62     VERBISTE_PRESENT_TENSE,
  63     VERBISTE_PAST_TENSE,
  64     VERBISTE_IMPERFECT_TENSE,
  65     VERBISTE_FUTURE_TENSE,
  66     VERBISTE_ACTIVE_TENSE,
  67     VERBISTE_PASSIVE_TENSE,
  68     VERBISTE_IMPERATIVE_ACTIVE_TENSE,
  69     VERBISTE_IMPERATIVE_PASSIVE_TENSE,
  70     VERBISTE_PAST_PERFECT
  71
  72 /** Valid conjugation tenses. */
  73 } Verbiste_Tense;
  74
  75 /** List of conjugation template names (e.g., "aim:er").
  76     The last character pointer in an array of this type is NULL.
  77 */
  78 typedef char **Verbiste_TemplateArray;
  79
  80
  81 typedef struct
  82 {
  83   char *infinitive_verb;
  84   Verbiste_Mode   mode;
  85   Verbiste_Tense  tense;
  86   int person;  /* 1, 2, 3, or 0 for infinitive and participle modes */
  87   int plural;  /* boolean indicating plural number instead of singular */
  88   int correct;  /* boolean indicating if termination is correct or an error */
  89
  90 /** Mode descriptor. */
  91 } Verbiste_ModeTensePersonNumber;
  92
  93
  94 /** List of strings, each string being an inflection (e.g., "assis").
  95     The last character pointer in an array of this type is NULL.
  96 */
  97 typedef char **Verbiste_InflectionArray;
  98
  99 /** List of list of strings, each sublist being an inflection array.
 100     The last Verbiste_InflectionArray pointer in an array of this type is NULL.
 101 */
 102 typedef Verbiste_InflectionArray *Verbiste_PersonArray;
 103
 104
 105 typedef struct
 106 {
 107   Verbiste_Mode mode;
 108   Verbiste_Tense tense;
 109 } Verbiste_ModeTense;
 110
 111
 112 extern const Verbiste_ModeTense verbiste_valid_modes_and_tenses[];
 113
 114
 115 /** Initializes the French verb dictionary object.
 116     This function must be called before any other function of this library.
 117     If the construction of the object fails (i.e., -2 is returned),
 118     call verbist_get_init_error() to obtain a text description of the failure.
 119     @param  conjugation_filename        filename of the XML document that
 120                                         defines all the conjugation templates
 121     @param  verbs_filename              filename of the XML document that
 122                                         defines all the known verbs and their
 123                                         corresponding template
 124     @param  lang_code                   "fr" for French, "it" for Italian
 125     @returns                            0 on success,
 126                                         -1 if the object has already been
 127                                         initialized, or
 128                                         -2 if the construction of the
 129                                         object fails.
 130 */
 131 int verbiste_init(const char *conjugation_filename,
 132                   const char *verbs_filename,
 133                   const char *lang_code);
 134
 135
 136 /** Gets a text description of the failure that occurred in verbiste_init().
 137     This function must only be called if verbiste_init() has returned -2.
 138     @returns                        the what() value of the logic_error expression
 139                                 thrown by the FrenchVerbDictionary constructor.
 140 */
 141 const char *verbiste_get_init_error();
 142
 143
 144 /** Frees the resources associated with the French verb dictionary object.
 145     This function should be called when this library's functionalities
 146     are not needed anymore.
 147     After this function has been called successfully, verbiste_init()
 148     can be called again to reinitialize the dictionary object.
 149     It must not be called if verbiste_init() failed.
 150     @returns                        0 on success, or -1 if the object had not
 151                                 been initialized (or had already been destroyed)
 152 */
 153 int verbiste_close(void);
 154
 155
 156 /** Frees the memory associated with the given string.
 157     The string to deallocate must have been received from a function
 158     of this API that specifically requires the deallocation to be
 159     done with verbiste_free_string().
 160     @param        str           string to deallocate
 161 */
 162 void verbiste_free_string(char *str);
 163
 164
 165 /** Returns the ASCII English name of the given mode.
 166     @param        mode          mode whose name is requested
 167     @returns                    pointer to an internal string that gives the
 168                                 requested name
 169 */
 170 const char *verbiste_get_mode_name(Verbiste_Mode mode);
 171
 172
 173 /** Returns the ASCII English name of the given tense.
 174     @param        tense         tense whose name is requested
 175     @returns                    pointer to an internal string that gives the
 176                                 requested name
 177 */
 178 const char *verbiste_get_tense_name(Verbiste_Tense tense);
 179
 180
 181 /** Analyses a conjugated verb and describes how it is conjugated.
 182     @param        verb          Latin-1 string containing the verb
 183                                 to deconjugate
 184     @returns                    a dynamically allocated array
 185                                 which must be freed by a call to
 186                                 verbiste_free_mtpn_array();
 187                                 the strings in this array are in Latin-1
 188 */
 189 Verbiste_ModeTensePersonNumber *verbiste_deconjugate(const char *verb);
 190
 191
 192 /** Frees the memory associated by the given array.
 193     @param        array         array to be freed;
 194                                 must have been allocated by a function such as
 195                                 verbiste_deconjugate();
 196                                 nothing is done if 'array' is null
 197 */
 198 void verbiste_free_mtpn_array(Verbiste_ModeTensePersonNumber *array);
 199
 200
 201 /** Returns the list of conjugation templates that apply to the given infinitive.
 202     @param  infinitive_verb     Latin-1 string containing the infinitive
 203     @returns                    an array of strings, the last element begin
 204                                 a null pointer; a NULL pointer is returned if
 205                                 the infinitive is unknown; this array must be
 206                                 passed to verbiste_free_verb_template_array()
 207                                 to free the memory
 208 */
 209 Verbiste_TemplateArray verbiste_get_verb_template_array(const char *infinitive_verb);
 210
 211
 212 /** Frees the memory allocated by verbiste_get_verb_template_array().
 213     @param  array               an array returned by verbiste_get_verb_template_array();
 214                                 can be NULL: this function does nothing in such a case
 215 */
 216 void verbiste_free_verb_template_array(Verbiste_TemplateArray array);
 217
 218
 219 /** Conjugates a verb in a certain mode and tense.
 220     @param  infinitiveVerb      Latin-1 infinitive form of the verb
 221                                 to be conjugated
 222     @param  template_name       name of the conjugation template to use
 223                                 (e.g., "aim:er")
 224     @param  mode                selected mode
 225     @param  tense               selected tense
 226     @param  include_pronouns    if non-zero, put pronouns before
 227                                 conjugated verbs in the modes where
 228                                 pronouns are used
 229     @returns                    a dynamically allocated array
 230                                 which must be freed by a call to
 231                                 verbiste_free_person_array();
 232                                 the strings in this array
 233                                 are in Latin-1;
 234                                 returns NULL if an error occurs
 235 */
 236 Verbiste_PersonArray verbiste_conjugate(const char *infinitive_verb,
 237                                         const char *template_name,
 238                                         const Verbiste_Mode mode,
 239                                         const Verbiste_Tense tense,
 240                                         int include_pronouns);
 241
 242
 243 /** Frees the memory associated by the given person array.
 244     @param        array         array to be freed;
 245                                 must have been allocated by a function such as
 246                                 verbiste_conjugate();
 247                                 nothing is done if 'array' is null
 248 */
 249 void verbiste_free_person_array(Verbiste_PersonArray array);
 250
 251
 252 #ifdef __cplusplus
 253 }
 254 #endif
 255
 256 #endif  /* _H_c_api */