RPA Toolkit
324b6e12ae7b3f062c7e0e92909852cca1648e1f
[rpatk.git] / rpa / rpadbex.h
1 /*
2  *  Regular Pattern Analyzer (RPA)
3  *  Copyright (c) 2009-2010 Martin Stoilov
4  *
5  *  This program is free software: you can redistribute it and/or modify
6  *  it under the terms of the GNU General Public License as published by
7  *  the Free Software Foundation, either version 3 of the License, or
8  *  (at your option) any later version.
9  *
10  *  This program is distributed in the hope that it will be useful,
11  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
12  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  *  GNU General Public License for more details.
14  *
15  *  You should have received a copy of the GNU General Public License
16  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
17  *
18  *  Martin Stoilov <martin@rpasearch.com>
19  */
20
21 /**
22  * \file rpa/rpadbex.h
23  * \brief The public interface to BNF productions database API
24  *
25  *
26  * <h2>Synopsis</h2>
27  * The following APIs are used to Create, Compile, Enumerate, etc. BNF productions.
28  *
29  * \example personname.c
30  * This is an example how to use rpadbex_t APIs
31
32  */
33
34 #ifndef _RPADBEX_H_
35 #define _RPADBEX_H_
36
37
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41
42 #include "rtypes.h"
43 #include "rvm/rvmcpu.h"
44 #include "rpa/rpaerror.h"
45
46
47 /**
48  * \typedef rpadbex_t
49  * \brief Database of BNF productions (The BNF schema)
50  */
51 typedef struct rpadbex_s rpadbex_t;
52 /**
53  * \example personname.c
54  * This is an example how to use rpadbex_t
55  */
56
57
58 /**
59  * \typedef rparule_t
60  * \brief Unique BNF rule identifier.
61  */
62 typedef rlong rparule_t;
63
64 #define RPA_DBEXCFG_OPTIMIZATIONS 1
65 #define RPA_DBEXCFG_DEBUG 2
66
67 /**
68  * \brief Return the version string of the RPA library.
69  *
70  * \return NULL terminated version string.
71  */
72 const rchar *rpa_dbex_version();
73
74
75 /**
76  * \brief Create an object of type \ref rpadbex_t.
77  *
78  * The created object must be destroyed with rpa_dbex_destroy.
79  * \return pointer to newly create BNF productions database object.
80  */
81 rpadbex_t *rpa_dbex_create(void);
82
83
84 /**
85  * \brief Destoies an object of type rpadbex_t, created by \ref rpa_dbex_create.
86  *
87  * Use this function to destroy the object. After this call the pointer to dbex should never be used again.
88  *
89  * \param dbex pointer to an object of type \ref rpadbex_t
90  */
91 void rpa_dbex_destroy(rpadbex_t *dbex);
92
93
94 /**
95  * \brief Return the error code of the last occurred error.
96  *
97  * \param dbex Pointer to \ref rpadbex_t object.
98  * \return The error code of the last occurred error. If this function fails the
99  * return value is negative.
100  */
101 rlong rpa_dbex_lasterror(rpadbex_t *dbex);
102
103 /**
104  * \brief Get error information for the last occurred error.
105  *
106  * \param dbex Pointer to \ref rpadbex_t object.
107  * \param errinfo Pointer to \ref rpa_errinfo_t buffer that will be
108  * filled with the error information. This parameter cannot be NULL.
109  * \return Return 0 if the function is successful or negative otherwise. If this function fails the
110  * return value is negative.
111  */
112 rlong rpa_dbex_lasterrorinfo(rpadbex_t *dbex, rpa_errinfo_t *errinfo);
113
114
115 /**
116  * \brief Open the BNF productions database.
117  *
118  * This function must be called before inserting any BNF production with
119  * \ref  rpa_dbex_load or \ref rpa_dbex_load_s. To close the database you
120  * must use \ref rpa_dbex_close. The database can opened and closed multiple
121  * times as long it is not destroyed with \ref rpa_dbex_destroy.
122  *
123  * \param dbex Pointer to \ref rpadbex_t object.
124  * \return If successful return 0, otherwise return negative.
125  *         Use \ref rpa_dbex_lasterror or \ref rpa_dbex_lasterrorinfo to retrieve the error
126  *         information.
127  */
128 rinteger rpa_dbex_open(rpadbex_t *dbex);
129
130
131 /**
132  * \brief Close the BNF productions database.
133  *
134  * This function must be called when the BNF schema is complete and ready
135  * to be compiled.
136  *
137  * \param dbex Pointer to \ref rpadbex_t object.
138  */
139 void rpa_dbex_close(rpadbex_t *dbex);
140
141
142 /**
143  * \brief Compile the BNF productions database to byte code.
144  *
145  * Compile the BNF productions database to byte code. This function generates
146  * the byte code (executable code) used to parse or search input stream.
147  * Parsing, Matching, Searching (Running the code) is controlled by \ref rpastat_t.
148  *
149  * \param dbex Pointer to \ref rpadbex_t object.
150  * \return If successful return 0, otherwise return negative.
151  *         Use \ref rpa_dbex_lasterror or \ref rpa_dbex_lasterrorinfo to retrieve the error
152  *         information.
153  */
154 rinteger rpa_dbex_compile(rpadbex_t *dbex);
155
156
157 /**
158  * \brief Load BNF production(s) into the database.
159  *
160  * Loads the BNF production(s) from the buffer into the dbex database.
161  * \param dbex Pointer to \ref rpadbex_t object.
162  * \param buffer UTF8 string containing BNF production(s).
163  * \param size Buffer size.
164  * \return Upon successful completion, the function returns the size of the loaded BNF production(s), otherwise returns negative.
165  *         Use \ref rpa_dbex_lasterror or \ref rpa_dbex_lasterrorinfo to retrieve the error
166  *         information.
167  */
168 rlong rpa_dbex_load(rpadbex_t *dbex, const rchar *buffer, rsize_t size);
169
170
171 /**
172  * \brief Load BNF production(s) into the database. Same as \ref rpa_dbex_load,
173  *                      but the buffer is NULL terminated string.
174  *
175  * \param dbex Pointer to \ref rpadbex_t object.
176  * \param buffer UTF8 string containing BNF production(s).
177  * \return Upon successful completion, the function returns the size of the copied productions,
178  *         otherwise returns negative.
179  *         Use \ref rpa_dbex_lasterror or \ref rpa_dbex_lasterrorinfo to retrieve the error
180  *         information.
181  */
182 rlong rpa_dbex_load_s(rpadbex_t *dbex, const rchar *buffer);
183
184
185 /**
186  * \brief Return a pointer to the executable code segment.
187  *
188  * This function will succeed only if it is called after a call to \ref rpa_dbex_compile.
189  * \param dbex Pointer to \ref rpadbex_t object.
190  * \return Pointer to the beginning of executable byte code. In case of an error it returns NULL.
191  *         Use \ref rpa_dbex_lasterror or \ref rpa_dbex_lasterrorinfo to retrieve the error
192  *         information.
193  */
194 rvm_asmins_t *rpa_dbex_executable(rpadbex_t *dbex);
195
196
197 /**
198  * \brief Return the offset of the executable byte code for the specified rule.
199  *
200  * Return the offset of the executable byte code segment returned by \ref rpa_dbex_executable for the specified rule.
201  * The two functions \ref rpa_dbex_executable and \ref rpa_dbex_executableoffset work together to locate the
202  * beginning of the executable byte code for the specified ID.
203  * This function will succeed only if it is called after a call to \ref rpa_dbex_compile.
204  *
205  * \param dbex Pointer to \ref rpadbex_t object.
206  * \param rid Unique ID of the requested BNF production.
207  * \return Pointer the offset of the executable byte code. In case of an error it returns negative.
208  *         Use \ref rpa_dbex_lasterror or \ref rpa_dbex_lasterrorinfo to retrieve the error
209  *         information.
210  */
211 rlong rpa_dbex_executableoffset(rpadbex_t *dbex, rparule_t rid);
212
213
214 /**
215  * \brief Lookup BNF production ID in the database.
216  *
217  * Lookup the unique ID for BNF production in the dbex database. For example if you
218  * have loaded and compiled a BNF production like: "alpha ::= [a-zA-Z]" with a previous call to
219  * \ref rpa_dbex_load. You can lookup the unique ID for this production by using this
220  * function.
221  *
222  * \param dbex Pointer to \ref rpadbex_t object.
223  * \param name The production name (the identifier located before the operator '::= ')
224  * \param namesize The size of the buffer to be used.
225  * \return Unique ID for the specified production name.
226  */
227 rparule_t rpa_dbex_lookup(rpadbex_t *dbex, const rchar *name, rsize_t namesize);
228
229
230 /**
231  * \brief Lookup BNF production ID in the database.
232  *
233  * Same as \ref rpa_dbex_lookup, but the name parameter is NULL terminated string.
234  */
235 rparule_t rpa_dbex_lookup_s(rpadbex_t *dbex, const rchar *name);
236
237
238 /**
239  * @brief Return the name of the specified rule ID.
240  *
241  * If rid is a valid rule, this function will return a pointer to the rule name.
242  * The returned points directly in the database structures, if you need
243  * to preserved name, you will have to make a copy.
244  *
245  * @param dbex Pointer to \ref rpadbex_t object.
246  * @param rid Rule id
247  * @return Returns the name of the specified ID or NULL in case of error.
248  */
249 const rchar *rpa_dbex_name(rpadbex_t *dbex, rparule_t rid);
250
251
252 /**
253  * \brief Return the first production ID in the database.
254  *
255  * Depending on how the BNF schema is structured, if the first production is also the
256  * root production you should use this function to get the root ID.
257  *
258  * \param dbex Pointer to \ref rpadbex_t object.
259  * \return Returns the ID of the first production.
260  */
261 rparule_t rpa_dbex_first(rpadbex_t *dbex);
262
263
264 /**
265  * \brief Return the last production ID
266  *
267  * Depending on how the BNF schema is structured, if the last production is also the
268  * root production you should use this function to get the root ID.
269  *
270  * \param dbex Pointer to \ref rpadbex_t object.
271  * \return Returns the ID of the last production.
272  */
273 rparule_t rpa_dbex_last(rpadbex_t *dbex);
274
275
276 /**
277  * \brief Return the next production ID
278  *
279  * \param dbex Pointer to \ref rpadbex_t object.
280  * \param rid current production ID.
281  * \return Returns the ID of the next production.
282  */
283 rparule_t rpa_dbex_next(rpadbex_t *dbex, rparule_t rid);
284
285
286 /**
287  * \brief Return the previous production ID
288  *
289  * \param dbex Pointer to \ref rpadbex_t object.
290  * \param rid current production ID.
291  * \return Returns the ID of the previous production.
292  */
293 rparule_t rpa_dbex_prev(rpadbex_t *dbex, rparule_t rid);
294
295
296 /**
297  * \brief Returns the string length of the specified BNF production
298  *
299  * \param dbex Pointer to \ref rpadbex_t object.
300  * \param rid production ID.
301  * \return the string length of the specified production
302  */
303 rsize_t rpa_dbex_strlen(rpadbex_t *dbex, rparule_t rid);
304
305
306 /**
307  * \brief Copy the string of the specified BNF production to the destination buffer
308  *
309  * \param dbex Pointer to \ref rpadbex_t object.
310  * \param rid production ID.
311  * \param dest destination buffer
312  * \param size to be copied
313  * \return Return the number of bytes written in the buffer.
314  */
315 rsize_t rpa_dbex_strncpy(rpadbex_t *dbex, rchar *dest, rparule_t rid, rsize_t size);
316
317
318 /**
319  * \brief Set a configuration value for the dbex object.
320  *
321  * \param dbex Pointer to \ref rpadbex_t object.
322  * \param cfg Configuration ID
323  * \param val Configuration value
324  *
325  * Supported configuration IDs / Values:
326  * - RPA_DBEXCFG_OPTIMIZATIONS
327  *   - 0 Dissable optimizations
328  *   - 1 Enable optimizations
329  * - RPA_DBEXCFG_DEBUG
330  *   - 0 Dissable debugging
331  *   - 1 Enable debugging
332  */
333 rlong rpa_dbex_cfgset(rpadbex_t *dbex, rulong cfg, rulong val);
334
335
336 /**
337  * \brief Get a configuration value for the dbex object.
338  *
339  * \param dbex Pointer to \ref rpadbex_t object.
340  * \param cfg Configuration ID.
341  * \return Return the value of the specified configuration ID. If an error occurs the return negative.
342  *
343  * Supported configuration IDs
344  * - RPA_DBEXCFG_OPTIMIZATIONS
345  * - RPA_DBEXCFG_DEBUG
346  */
347 rlong rpa_dbex_cfgget(rpadbex_t *dbex, rulong cfg);
348
349
350 /**
351  * \brief Printeger a BNF production in a tree format
352  *
353  * Use \ref rpa_dbex_lookup to find the ID of a BNF production
354  * \param dbex Pointer to \ref rpadbex_t object.
355  * \param rid production ID.
356  * \return Return 0 on success or negative if error occurred.
357  */
358 rinteger rpa_dbex_dumptree(rpadbex_t *dbex, rparule_t rid);
359
360 /**
361  * \brief Dump the compiled byte code for the specified production ID
362  *
363  * This function is a debug helper, you shouldn't need it.
364  * \param dbex Pointer to \ref rpadbex_t object.
365  * \param rid production ID.
366  * \return Return 0 on success or negative if error occurred.
367  */
368 rinteger rpa_dbex_dumpcode(rpadbex_t* dbex, rparule_t rid);
369
370
371 /**
372  * \brief Printeger the AST of the parsed BNF productions.
373  *
374  * This function is a debug helper, you shouldn't need it.
375  * unless you are debugging this library.
376  *
377  * \param dbex Pointer to \ref rpadbex_t object.
378  * \return Return 0 on success or negative if error occurred.
379  */
380 rinteger rpa_dbex_dumprecords(rpadbex_t *dbex);
381
382 /**
383  * \brief Printeger the content of BNF productions database.
384  *
385  * Enumerate all BNF productions and printeger them in a text format.
386  * \param dbex Pointer to \ref rpadbex_t object.
387  * \return Return 0 on success or negative if error occurred.
388  */
389 rinteger rpa_dbex_dumpproductions(rpadbex_t *dbex);
390
391 /**
392  * \brief Printeger debug information about the state of the BNF productions database.
393  *
394  * This is a debug helper, you shouldn't need it.
395  * \param dbex Pointer to \ref rpadbex_t object.
396  * \return Return 0 on success or negative if error occurred.
397  */
398 rinteger rpa_dbex_dumpinfo(rpadbex_t *dbex);
399
400 /**
401  * \brief Printeger the production user IDs in a format suitable to be
402  * included in source code.
403  *
404  * If you define user IDs for your productions you can dump all user IDs
405  * in a format suitable to be included in a C/C++ source code.
406  */
407 rinteger rpa_dbex_dumpuids(rpadbex_t *dbex);
408
409 /**
410  * \example personname.c
411  */
412
413
414 #ifdef __cplusplus
415 }
416 #endif
417
418 #endif