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