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
4 verbiste - French conjugation system
5 Copyright (C) 2003-2010 Pierre Sarrazin <http://sarrazip.com/>
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.
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.
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
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,
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
56 /** Valid conjugation modes. */
61 VERBISTE_INVALID_TENSE,
62 VERBISTE_PRESENT_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,
72 /** Valid conjugation tenses. */
75 /** List of conjugation template names (e.g., "aim:er").
76 The last character pointer in an array of this type is NULL.
78 typedef char **Verbiste_TemplateArray;
83 char *infinitive_verb;
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 */
90 /** Mode descriptor. */
91 } Verbiste_ModeTensePersonNumber;
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.
97 typedef char **Verbiste_InflectionArray;
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.
102 typedef Verbiste_InflectionArray *Verbiste_PersonArray;
108 Verbiste_Tense tense;
109 } Verbiste_ModeTense;
112 extern const Verbiste_ModeTense verbiste_valid_modes_and_tenses[];
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
128 -2 if the construction of the
131 int verbiste_init(const char *conjugation_filename,
132 const char *verbs_filename,
133 const char *lang_code);
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.
141 const char *verbiste_get_init_error();
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)
153 int verbiste_close(void);
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
162 void verbiste_free_string(char *str);
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
170 const char *verbiste_get_mode_name(Verbiste_Mode mode);
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
178 const char *verbiste_get_tense_name(Verbiste_Tense tense);
181 /** Analyses a conjugated verb and describes how it is conjugated.
182 @param verb Latin-1 string containing the verb
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
189 Verbiste_ModeTensePersonNumber *verbiste_deconjugate(const char *verb);
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
198 void verbiste_free_mtpn_array(Verbiste_ModeTensePersonNumber *array);
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()
209 Verbiste_TemplateArray verbiste_get_verb_template_array(const char *infinitive_verb);
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
216 void verbiste_free_verb_template_array(Verbiste_TemplateArray array);
219 /** Conjugates a verb in a certain mode and tense.
220 @param infinitiveVerb Latin-1 infinitive form of the verb
222 @param template_name name of the conjugation template to use
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
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
234 returns NULL if an error occurs
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);
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
249 void verbiste_free_person_array(Verbiste_PersonArray array);
256 #endif /* _H_c_api */