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