/**
* \file rpadbex.h
- * \brief The public interface to BNF expression database API
+ * \brief The public interface to BNF productions database API
*
*
* <h2>Synopsis</h2>
- * The following APIs are used to Create, Compile, Enumerate, etc. BNF expressions schema.
+ * The following APIs are used to Create, Compile, Enumerate, etc. BNF productions.
*/
#ifndef _RPADBEX_H_
/**
* \typedef rpadbex_t
- * \brief Database of BNF expressions (The BNF schema)
+ * \brief Database of BNF productions (The BNF schema)
*/
typedef struct rpadbex_s rpadbex_t;
/**
- * \brief Creates and returns a pointer to an object of type rpadbex_t.
+ * \brief Create an object of type \ref rpadbex_t.
*
* The created object must be destroyed with rpa_dbex_destroy.
- * \return pointer to newly create BNF expressions database object.
+ * \return pointer to newly create BNF productions database object.
*/
rpadbex_t *rpa_dbex_create(void);
/**
- * \brief Open the BNF expressions database.
+ * \brief Open the BNF productions database.
*
- * This function must be called before inserting any BNF expression with
+ * This function must be called before inserting any BNF production with
* \ref rpa_dbex_load or \ref rpa_dbex_load_s. To close the database you
* must use \ref rpa_dbex_close. The database can opened and closed multiple
* times as long it is not destroyed with \ref rpa_dbex_destroy.
/**
- * \brief Close the BNF expressions database.
+ * \brief Close the BNF productions database.
*
* This function must be called when the BNF schema is complete and ready
* to be compiled.
/**
- * \brief Compile the BNF expressions database to byte code.
+ * \brief Compile the BNF productions database to byte code.
*
- * Compile the BNF expressions database to byte code. This function generates
+ * Compile the BNF productions database to byte code. This function generates
* the byte code (executable code) used to parse or search input stream.
* Parsing, Matching, Searching (Running the code) is controlled by \ref rpastat_t.
*
/**
- * \brief Load BNF expression(s) into the database.
+ * \brief Load BNF production(s) into the database.
*
- * Loads the BNF expression(s) from the buffer into the dbex database.
+ * Loads the BNF production(s) from the buffer into the dbex database.
* \param dbex Pointer to \ref rpadbex_t object.
- * \param buffer UTF8 string containing BNF expression(s).
+ * \param buffer UTF8 string containing BNF production(s).
* \param size Buffer size.
- * \return Upon successful completion, the function returns the size of the loaded BNF expression(s), otherwise returns negative.
+ * \return Upon successful completion, the function returns the size of the loaded BNF production(s), otherwise returns negative.
* Use \ref rpa_dbex_lasterror or \ref rpa_dbex_lasterrorinfo to retrieve the error
* information.
*/
/**
- * \brief Load BNF expression(s) into the database. Same as \ref rpa_dbex_load,
+ * \brief Load BNF production(s) into the database. Same as \ref rpa_dbex_load,
* but the buffer is NULL terminated string.
*
* \param dbex Pointer to \ref rpadbex_t object.
- * \param buffer UTF8 string containing BNF expression(s).
- * \return Upon successful completion, the function returns the size of the loaded expressions,
+ * \param buffer UTF8 string containing BNF production(s).
+ * \return Upon successful completion, the function returns the size of the copied productions,
* otherwise returns negative.
* Use \ref rpa_dbex_lasterror or \ref rpa_dbex_lasterrorinfo to retrieve the error
* information.
*
* Return the offset of the executable byte code segment returned by \ref rpa_dbex_executable for the specified rule.
* The two functions \ref rpa_dbex_executable and \ref rpa_dbex_executableoffset work together to locate the
- * beginning of the executable byte code for the specified rule id.
+ * beginning of the executable byte code for the specified ID.
* This function will succeed only if it is called after a call to \ref rpa_dbex_compile.
*
* \param dbex Pointer to \ref rpadbex_t object.
- * \param rid Rule Id of the requested BNF rule(expression).
+ * \param rid Unique ID of the requested BNF production.
* \return Pointer the offset of the executable byte code. In case of an error it returns negative.
* Use \ref rpa_dbex_lasterror or \ref rpa_dbex_lasterrorinfo to retrieve the error
* information.
/**
- * \brief Lookup Rule ID in the expression database.
+ * \brief Lookup BNF production ID in the database.
*
- * Lookup the unique Rule ID for BNF expression in the dbex database. For example if you
- * have loaded and compiled a BNF expression like: "alpha ::= [a-zA-Z]" with a previous call to
- * \ref rpa_dbex_load. You can lookup the unique rule id for this expression by using this
+ * Lookup the unique ID for BNF production in the dbex database. For example if you
+ * have loaded and compiled a BNF production like: "alpha ::= [a-zA-Z]" with a previous call to
+ * \ref rpa_dbex_load. You can lookup the unique ID for this production by using this
* function.
*
* \param dbex Pointer to \ref rpadbex_t object.
- * \param name The rule name (the identifier located before the operator '::= ')
+ * \param name The production name (the identifier located before the operator '::= ')
* \param namesize The size of the buffer to be used.
- * \return Unique id of the specified rule(expression).
+ * \return Unique ID for the specified production name.
*/
rparule_t rpa_dbex_lookup(rpadbex_t *dbex, const rchar *name, rsize_t namesize);
/**
- * \brief Lookup Rule ID in the expression database.
+ * \brief Lookup BNF production ID in the database.
*
* Same as \ref rpa_dbex_lookup, but the name parameter is NULL terminated string.
*/
/**
- * \brief Return the first expression id in the database.
+ * \brief Return the first production ID in the database.
*
- * Depending on how the BNF schema is structured, if the first expression is also the
- * root expression you should use this function to get the root id.
+ * Depending on how the BNF schema is structured, if the first production is also the
+ * root production you should use this function to get the root ID.
*
* \param dbex Pointer to \ref rpadbex_t object.
- * \return Returns the id of the first expression.
+ * \return Returns the ID of the first production.
*/
rparule_t rpa_dbex_first(rpadbex_t *dbex);
/**
- * \brief Return the last expression id
+ * \brief Return the last production ID
*
- * Depending on how the BNF schema is structured, if the last expression is also the
- * root expression you should use this function to get the root id.
+ * Depending on how the BNF schema is structured, if the last production is also the
+ * root production you should use this function to get the root ID.
*
* \param dbex Pointer to \ref rpadbex_t object.
- * \return Returns the id of the last expression.
+ * \return Returns the ID of the last production.
*/
rparule_t rpa_dbex_last(rpadbex_t *dbex);
/**
- * \brief Return the next expression id
+ * \brief Return the next production ID
*
* \param dbex Pointer to \ref rpadbex_t object.
- * \param rid current expression id.
- * \return Returns the id of the next expression.
+ * \param rid current production ID.
+ * \return Returns the ID of the next production.
*/
rparule_t rpa_dbex_next(rpadbex_t *dbex, rparule_t rid);
/**
- * \brief Return the previous expression id
+ * \brief Return the previous production ID
*
* \param dbex Pointer to \ref rpadbex_t object.
- * \param rid current expression id.
- * \return Returns the id of the previous expression.
+ * \param rid current production ID.
+ * \return Returns the ID of the previous production.
*/
rparule_t rpa_dbex_prev(rpadbex_t *dbex, rparule_t rid);
/**
- * \brief Returns the string length of the specified BNF expression
+ * \brief Returns the string length of the specified BNF production
*
* \param dbex Pointer to \ref rpadbex_t object.
- * \param rid expression id.
- * \return the string length of the specified expression
+ * \param rid production ID.
+ * \return the string length of the specified production
*/
rsize_t rpa_dbex_strlen(rpadbex_t *dbex, rparule_t rid);
/**
- * \brief Copy the string of the specified BNF expression to the destination buffer
+ * \brief Copy the string of the specified BNF production to the destination buffer
*
* \param dbex Pointer to \ref rpadbex_t object.
- * \param rid expression id.
+ * \param rid production ID.
* \param dest destination buffer
* \param size to be copied
* \return Return the number of bytes written in the buffer.
* \brief Set a configuration value for the dbex object.
*
* \param dbex Pointer to \ref rpadbex_t object.
- * \param cfg Configuration id
+ * \param cfg Configuration ID
* \param val Configuration value
*
* Supported configuration IDs / Values:
/**
- * \brief Print a BFN expression in a tree format
- *
+ * \brief Print a BNF production in a tree format
*
+ * Use \ref rpa_dbex_lookup to find the ID of a BNF production
+ * \param dbex Pointer to \ref rpadbex_t object.
+ * \param rid production ID.
+ * \return Return 0 on success or negative if error occurred.
*/
-rint rpa_dbex_dumptree(rpadbex_t *dbex, const rchar *rulename, rsize_t namesize, rint level);
-
+rint rpa_dbex_dumptree(rpadbex_t *dbex, rparule_t rid);
/**
- * \brief Print a BNF expression in a tree format
- *
+ * \brief Dump the compiled byte code for the specified production ID
*
+ * This function is a debug helper, you shouldn't need it.
+ * \param dbex Pointer to \ref rpadbex_t object.
+ * \param rid production ID.
+ * \return Return 0 on success or negative if error occurred.
*/
-rint rpa_dbex_dumptree_s(rpadbex_t *dbex, const rchar *name, rint level);
+rint rpa_dbex_dumpcode(rpadbex_t* dbex, rparule_t rid);
/*
- * \brief Print the AST of the parsed BNF expressions.
+ * \brief Print the AST of the parsed BNF productions.
*
- * This function is a debugging helper, you shouldn't need it
+ * This function is a debug helper, you shouldn't need it.
* unless you are debugging this library.
+ *
+ * \param dbex Pointer to \ref rpadbex_t object.
+ * \return Return 0 on success or negative if error occurred.
*/
rint rpa_dbex_dumprecords(rpadbex_t *dbex);
-rint rpa_dbex_dumprules(rpadbex_t *dbex);
+
+/*
+ * \brief Print the content of BNF productions database.
+ *
+ * Enumerate all BNF productions and print them in a text format.
+ * \param dbex Pointer to \ref rpadbex_t object.
+ * \return Return 0 on success or negative if error occurred.
+ */
+rint rpa_dbex_dumpproductions(rpadbex_t *dbex);
+
+/*
+ * \brief Print debug information about the state of the BNF productions database.
+ *
+ * This is a debug helper, you shouldn't need it.
+ * \param dbex Pointer to \ref rpadbex_t object.
+ * \return Return 0 on success or negative if error occurred.
+ */
rint rpa_dbex_dumpinfo(rpadbex_t *dbex);
-rint rpa_dbex_dumpcode(rpadbex_t* dbex, const rchar *rule);
-rint rpa_dbex_dumpalias(rpadbex_t *dbex);
+
+/*
+ * \brief Print the production user IDs in a format suitable to be
+ * included in source code.
+ *
+ * If you define user IDs for your productions you can dump all user IDs
+ * in a format suitable to be included in a C/C++ source code.
+ */
+rint rpa_dbex_dumpuids(rpadbex_t *dbex);
#include "rtypes.h"
#include "rarray.h"
#include "rvmreg.h"
-#include "rpavm.h"
#include "rpadbex.h"
-#include "rpacache.h"
#define RPA_ENCODING_UTF8 0
#define RPA_ENCODING_BYTE 1
extern "C" {
#endif
+/**
+ * \file rpastat.h
+ * \brief The public interface to the execution context.
+ *
+ *
+ * <h2>Synopsis</h2>
+ * The following APIs are used to parse, match, scan an input stream, using an existing
+ * BNF productions database \ref rpadbex_t
+ */
+/**
+ * \typedef rpastat_t
+ * \brief Execution context. If you need mutli-threading, multiple objects of this
+ * type must be created for every concurrent thread. All objects can be created/destroyed from the
+ * main thread. Only the execution functions: \ref rpa_stat_parse, \ref rpa_stat_match and
+ * \ref rpa_stat_scan have to be called from separate threads.
+ */
typedef struct rpastat_s rpastat_t;
-struct rpastat_s {
- rpadbex_t *dbex;
- const rchar *input;
- const rchar *start;
- const rchar *end;
- ruint error;
- ruint encoding;
- ruint debug;
- rarray_t *records;
- rarray_t *emitstack;
- rarray_t *orphans;
- rpainput_t *instackbuffer;
- rpainput_t *instack; /* instack = &instackbuffer[1]; This allows R_TOP = -1, without any additional checks */
- rulong instacksize;
- rpacache_t *cache;
- rpainmap_t ip;
- rvmcpu_t *cpu;
-};
-
+/**
+ * \brief Create an object of type \ref rpastat_t.
+ *
+ * Multi-threading is supported by creating multiple \ref rpastat_t objects,
+ * referencing the same \ref rpadbex_t BNF productions database. Every thread
+ * must have its own \ref rpastat_t object, created with this function. This
+ * function can be called from the main thread multiple times to allocate the objects and
+ * then the returned pointer(s) passed to the child threads.
+ *
+ * If you don't need multi-threading, call this function and any one of the execution
+ * functions \ref rpa_stat_parse, \ref rpa_stat_match and \ref rpa_stat_scan from the
+ * main thread.
+ *
+ * The allocated \ref rpastat_t object must be destroyed with \ref rpa_stat_destroy.
+ *
+ * \param dbex BNF productions database created with \ref rpa_dbex_create.
+ * \param stacksize Execution stack size. The size is specified in byts.
+ * \return Returns a pointer to newly created \ref rpastat_t object or NULL if error occured.
+ */
rpastat_t *rpa_stat_create(rpadbex_t *dbex, rulong stacksize);
+
+
+/**
+ * \brief Destroy an object of type \ref rpastat_t
+ *
+ * Destroy the object created with \ref rpa_stat_create. After calling this function
+ * the pointer is invalid and must never be used again.
+ *
+ * \param stat Pointer to object.
+ */
void rpa_stat_destroy(rpastat_t *stat);
-rint rpa_stat_init(rpastat_t *stat, const rchar *input, const rchar *start, const rchar *end);
-void rpa_stat_cachedisable(rpastat_t *stat, ruint disable);
-void rpa_stat_cacheinvalidate(rpastat_t *stat);
-rint rpa_stat_encodingset(rpastat_t *stat, ruint encoding);
-rlong rpa_stat_exec(rpastat_t *stat, rvm_asmins_t *prog, rword off);
+
+rint rpa_stat_encodingset(rpastat_t *stat, ruint encoding);
rlong rpa_stat_scan(rpastat_t *stat, rparule_t rid, const rchar *input, const rchar *start, const rchar *end, const rchar **where);
rlong rpa_stat_match(rpastat_t *stat, rparule_t rid, const rchar *input, const rchar *start, const rchar *end);
rlong rpa_stat_parse(rpastat_t *stat, rparule_t rid, const rchar *input, const rchar *start, const rchar *end, rarray_t **records);
rint rpa_stat_abort(rpastat_t *stat);
-
-rint rpa_stat_matchchr(rpastat_t *stat, rssize_t top, rulong wc);
-rint rpa_stat_matchspchr(rpastat_t *stat, rssize_t top, rulong wc);
-rint rpa_stat_matchrng(rpastat_t *stat, rssize_t top, rulong wc1, rulong wc2);
-rlong rpa_stat_shift(rpastat_t *stat, rssize_t top);
+rlong rpa_stat_exec(rpastat_t *stat, rvm_asmins_t *prog, rword off);
#ifdef __cplusplus
