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