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