RPA Toolkit
documentation changes.
authorMartin Stoilov <martin@rpasearch.com>
Wed, 6 Jul 2011 04:40:06 +0000 (21:40 -0700)
committerMartin Stoilov <martin@rpasearch.com>
Wed, 6 Jul 2011 04:40:06 +0000 (21:40 -0700)
13 files changed:
build/linux/build.mk
doc/doxygen/rpa.cfg
rgrep/rpagrep.c
rpa/doc/main.txt
rpa/doc/rpa_dbex.txt
rpa/doc/rpa_error.txt [new file with mode: 0644]
rpa/doc/rpa_stat.txt
rpa/rpadbex.c
rpa/rpadbex.h
rpa/rpaerror.h
rpa/rparecord.h
rpa/rpastat.h
rpa/rpastatpriv.h

index ca15251..15bb983 100644 (file)
@@ -28,11 +28,19 @@ clean:
        +make -C $(SRCDIR)/tests/testrjs/build/$(OS)/$(ARCHDIR) clean
        +make -C $(SRCDIR)/rgrep/build/$(OS)/$(ARCHDIR) clean
 
-install:
+$(RPATK_INC_INSTALL) :
        mkdir $(RPATK_INC_INSTALL)
+
+$(RPATK_INC_INSTALL)/rlib :
        mkdir $(RPATK_INC_INSTALL)/rlib
+
+$(RPATK_INC_INSTALL)/rvm :
        mkdir $(RPATK_INC_INSTALL)/rvm
+
+$(RPATK_INC_INSTALL)/rpa :
        mkdir $(RPATK_INC_INSTALL)/rpa
+
+install: $(RPATK_INC_INSTALL) $(RPATK_INC_INSTALL)/rlib $(RPATK_INC_INSTALL)/rvm $(RPATK_INC_INSTALL)/rpa
        cp $(SRCDIR)/arch/$(OS)/$(ARCHDIR)/rtypes.h $(RPATK_INC_INSTALL)
        +make -C $(SRCDIR)/rlib/build/$(OS)/$(ARCHDIR) install
        +make -C $(SRCDIR)/rpa/build/$(OS)/$(ARCHDIR) install
index 8ff7650..99e3963 100644 (file)
@@ -103,6 +103,7 @@ INPUT                  = ../../rpa/rpadbex.h \
                          ../../rpa/doc/rpa_dbex.txt \
                          ../../rpa/doc/rpa_stat.txt \
                          ../../rpa/doc/rpa_record.txt \
+                         ../../rpa/doc/rpa_error.txt \
                          ../../rpa/doc/introduction.txt 
 
 INPUT_ENCODING         = UTF-8
index 8f66c75..1b7e504 100644 (file)
@@ -248,8 +248,8 @@ int rpa_grep_parse(rpa_grep_t *pGrep, const char* buffer, unsigned long size)
                        r_snprintf(location, sizeof(location), "Parse Error: Code: %ld", err.code);
                        rpa_grep_output_utf8_string(pGrep, location);
                }
-               if (err.ruleid) {
-                       r_snprintf(location, sizeof(location), ", Rule UID: %ld", err.ruleid);
+               if (err.ruleuid) {
+                       r_snprintf(location, sizeof(location), ", Rule UID: %ld", err.ruleuid);
                        rpa_grep_output_utf8_string(pGrep, location);
                }
                if (*err.name) {
index cdd396f..77dffef 100644 (file)
@@ -8,5 +8,6 @@
        - @subpage rpa_dbex
        - @subpage rpa_stat
        - @subpage rpa_record
+       - @subpage rpa_error    
 */
 
index 14c03f5..819615e 100644 (file)
@@ -4,7 +4,7 @@ compile the BNF schema using the @ref rpadbex_t API.
 
 - 1. Create an BNF expression database (rpadbex_t object), using @ref rpa_dbex_create.
 - 2. Open the expression database, using @ref rpa_dbex_open.
-- 3. Load the BNF productions into the databse, using @ref rpa_dbex_load or @ref rpa_dbex_load_s.
+- 3. Load the BNF productions into the database, using @ref rpa_dbex_load or @ref rpa_dbex_load_s.
 - 4. Close the database, using @ref rpa_dbex_close.
 - 5. Compile the BNF productions in the database to byte code, using @ref rpa_dbex_compile.
 
diff --git a/rpa/doc/rpa_error.txt b/rpa/doc/rpa_error.txt
new file mode 100644 (file)
index 0000000..2bb1ffa
--- /dev/null
@@ -0,0 +1,5 @@
+/** \page rpa_error rpa_error_t - Check the error in case of error.
+
+Use @ref rpa_dbex_lasterrorinfo or @ref rpa_dbex_lasterror to check the error if an error occurs.
+
+*/
index 576ae77..e3c5c2c 100644 (file)
@@ -1,6 +1,6 @@
 /** \page rpa_stat rpastat_t - Parsing, searching or matching.
 To parse, search or match you must use @ref rpastat_t API.
-- 1. Create @ref rpastat_t object with @rpa_stat_create.
+- 1. Create @ref rpastat_t object with @ref rpa_stat_create.
 - 2. To parse, search or match use:
        - @ref rpa_stat_parse
        - @ref rpa_stat_scan
index c9a7cc5..01199dd 100644 (file)
@@ -19,7 +19,7 @@
  */
 
 /**
- *\file rpadbex.c
+ *@file rpadbex.c
  */
 
 #include "rpa/rpacompiler.h"
index 5a02c91..5d52bed 100644 (file)
  */
 
 /**
- * \file rpa/rpadbex.h
- * \brief The public interface to BNF productions database API
+ * @file rpa/rpadbex.h
+ * @brief The public interface to BNF productions database API
  *
  * <h2>Synopsis</h2>
  * The following APIs are used to Create, Compile, Enumerate, etc. BNF productions.
  *
- * \example personname.c
+ * @example personname.c
  * This is an example how to use rpadbex_t APIs
 
  */
@@ -50,19 +50,19 @@ extern "C" {
 
 
 /**
- * \typedef rpadbex_t
- * \brief Database of BNF productions (The BNF schema)
+ * @typedef rpadbex_t
+ * @brief Database of BNF productions (The BNF schema)
  */
 typedef struct rpadbex_s rpadbex_t;
 /**
- * \example personname.c
+ * @example personname.c
  * This is an example how to use rpadbex_t
  */
 
 
 /**
- * \typedef rparule_t
- * \brief Unique BNF rule identifier.
+ * @typedef rparule_t
+ * @brief Unique BNF rule identifier.
  */
 typedef rlong rparule_t;
 
@@ -70,172 +70,172 @@ typedef rlong rparule_t;
 #define RPA_DBEXCFG_DEBUG 2
 
 /**
- * \brief Return the version string of the RPA library.
+ * @brief Return the version string of the RPA library.
  *
- * \return NULL terminated version string.
+ * @return NULL terminated version string.
  */
 const rchar *rpa_dbex_version();
 
 
 /**
- * \brief Create an object of type \ref 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 productions database object.
+ * @return pointer to newly create BNF productions database object.
  */
 rpadbex_t *rpa_dbex_create(void);
 
 
 /**
- * \brief Destoies an object of type rpadbex_t, created by \ref rpa_dbex_create.
+ * @brief Destoies an object of type rpadbex_t, created by @ref rpa_dbex_create.
  *
  * Use this function to destroy the object. After this call the pointer to dbex should never be used again.
  *
- * \param dbex pointer to an object of type \ref rpadbex_t
+ * @param dbex pointer to an object of type @ref rpadbex_t
  */
 void rpa_dbex_destroy(rpadbex_t *dbex);
 
 
 /**
- * \brief Return the error code of the last occurred error.
+ * @brief Return the error code of the last occurred error.
  *
- * \param dbex Pointer to \ref rpadbex_t object.
- * \return The error code of the last occurred error. If this function fails the
+ * @param dbex Pointer to @ref rpadbex_t object.
+ * @return The error code of the last occurred error. If this function fails the
  * return value is negative.
  */
 rlong rpa_dbex_lasterror(rpadbex_t *dbex);
 
 /**
- * \brief Get error information for the last occurred error.
+ * @brief Get error information for the last occurred error.
  *
- * \param dbex Pointer to \ref rpadbex_t object.
- * \param errinfo Pointer to \ref rpa_errinfo_t buffer that will be
+ * @param dbex Pointer to @ref rpadbex_t object.
+ * @param errinfo Pointer to @ref rpa_errinfo_t buffer that will be
  * filled with the error information. This parameter cannot be NULL.
- * \return Return 0 if the function is successful or negative otherwise. If this function fails the
+ * @return Return 0 if the function is successful or negative otherwise. If this function fails the
  * return value is negative.
  */
 rlong rpa_dbex_lasterrorinfo(rpadbex_t *dbex, rpa_errinfo_t *errinfo);
 
 
 /**
- * \brief Open the BNF productions database.
+ * @brief Open the BNF productions database.
  *
  * 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.
+ * @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.
  *
- * \param dbex Pointer to \ref rpadbex_t object.
- * \return If successful return 0, otherwise return negative.
- *         Use \ref rpa_dbex_lasterror or \ref rpa_dbex_lasterrorinfo to retrieve the error
+ * @param dbex Pointer to @ref rpadbex_t object.
+ * @return If successful return 0, otherwise return negative.
+ *         Use @ref rpa_dbex_lasterror or @ref rpa_dbex_lasterrorinfo to retrieve the error
  *         information.
  */
 rinteger rpa_dbex_open(rpadbex_t *dbex);
 
 
 /**
- * \brief Close the BNF productions database.
+ * @brief Close the BNF productions database.
  *
  * This function must be called when the BNF schema is complete and ready
  * to be compiled.
  *
- * \param dbex Pointer to \ref rpadbex_t object.
+ * @param dbex Pointer to @ref rpadbex_t object.
  */
 void rpa_dbex_close(rpadbex_t *dbex);
 
 
 /**
- * \brief Compile the BNF productions database to byte code.
+ * @brief Compile the BNF productions database to byte code.
  *
  * 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.
+ * Parsing, Matching, Searching (Running the code) is controlled by @ref rpastat_t.
  *
- * \param dbex Pointer to \ref rpadbex_t object.
- * \return If successful return 0, otherwise return negative.
- *         Use \ref rpa_dbex_lasterror or \ref rpa_dbex_lasterrorinfo to retrieve the error
+ * @param dbex Pointer to @ref rpadbex_t object.
+ * @return If successful return 0, otherwise return negative.
+ *         Use @ref rpa_dbex_lasterror or @ref rpa_dbex_lasterrorinfo to retrieve the error
  *         information.
  */
 rinteger rpa_dbex_compile(rpadbex_t *dbex);
 
 
 /**
- * \brief Load BNF production(s) into the database.
+ * @brief Load BNF production(s) into the 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 production(s).
- * \param size Buffer size.
- * \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
+ * @param dbex Pointer to @ref rpadbex_t object.
+ * @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 production(s), otherwise returns negative.
+ *         Use @ref rpa_dbex_lasterror or @ref rpa_dbex_lasterrorinfo to retrieve the error
  *         information.
  */
 rlong rpa_dbex_load(rpadbex_t *dbex, const rchar *buffer, rsize_t size);
 
 
 /**
- * \brief Load BNF production(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 production(s).
- * \return Upon successful completion, the function returns the size of the copied productions,
+ * @param dbex Pointer to @ref rpadbex_t object.
+ * @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
+ *         Use @ref rpa_dbex_lasterror or @ref rpa_dbex_lasterrorinfo to retrieve the error
  *         information.
  */
 rlong rpa_dbex_load_s(rpadbex_t *dbex, const rchar *buffer);
 
 
 /**
- * \brief Return a pointer to the executable code segment.
+ * @brief Return a pointer to the executable code segment.
  *
- * 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.
- * \return Pointer to the beginning of executable byte code. In case of an error it returns NULL.
- *         Use \ref rpa_dbex_lasterror or \ref rpa_dbex_lasterrorinfo to retrieve the error
+ * 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.
+ * @return Pointer to the beginning of executable byte code. In case of an error it returns NULL.
+ *         Use @ref rpa_dbex_lasterror or @ref rpa_dbex_lasterrorinfo to retrieve the error
  *         information.
  */
 rvm_asmins_t *rpa_dbex_executable(rpadbex_t *dbex);
 
 
 /**
- * \brief Return the offset of the executable byte code for the specified rule.
+ * @brief Return the offset of the executable byte code for the specified rule.
  *
- * 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
+ * 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 ID.
- * This function will succeed only if it is called after a call to \ref rpa_dbex_compile.
+ * 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 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
+ * @param dbex Pointer to @ref rpadbex_t object.
+ * @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.
  */
 rlong rpa_dbex_executableoffset(rpadbex_t *dbex, rparule_t rid);
 
 
 /**
- * \brief Lookup BNF production ID in the database.
+ * @brief Lookup BNF production ID in the database.
  *
  * 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
+ * @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 production name (the identifier located before the operator '::= ')
- * \param namesize The size of the buffer to be used.
- * \return Unique ID for the specified production name.
+ * @param dbex Pointer to @ref rpadbex_t object.
+ * @param name The production name (the identifier located before the operator '::= ')
+ * @param namesize The size of the buffer to be used.
+ * @return Unique ID for the specified production name.
  */
 rparule_t rpa_dbex_lookup(rpadbex_t *dbex, const rchar *name, rsize_t namesize);
 
 
 /**
- * \brief Lookup BNF production ID in the database.
+ * @brief Lookup BNF production ID in the database.
  *
- * Same as \ref rpa_dbex_lookup, but the name parameter is NULL terminated string.
+ * Same as @ref rpa_dbex_lookup, but the name parameter is NULL terminated string.
  */
 rparule_t rpa_dbex_lookup_s(rpadbex_t *dbex, const rchar *name);
 
@@ -247,7 +247,7 @@ rparule_t rpa_dbex_lookup_s(rpadbex_t *dbex, const rchar *name);
  * The returned points directly in the database structures, if you need
  * to preserved name, you will have to make a copy.
  *
- * @param dbex Pointer to \ref rpadbex_t object.
+ * @param dbex Pointer to @ref rpadbex_t object.
  * @param rid Rule id
  * @return Returns the name of the specified ID or NULL in case of error.
  */
@@ -255,77 +255,77 @@ const rchar *rpa_dbex_name(rpadbex_t *dbex, rparule_t rid);
 
 
 /**
- * \brief Return the first production ID in the database.
+ * @brief Return the first production ID in the database.
  *
  * 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 production.
+ * @param dbex Pointer to @ref rpadbex_t object.
+ * @return Returns the ID of the first production.
  */
 rparule_t rpa_dbex_first(rpadbex_t *dbex);
 
 
 /**
- * \brief Return the last production ID
+ * @brief Return the last production 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 production.
+ * @param dbex Pointer to @ref rpadbex_t object.
+ * @return Returns the ID of the last production.
  */
 rparule_t rpa_dbex_last(rpadbex_t *dbex);
 
 
 /**
- * \brief Return the next production ID
+ * @brief Return the next production ID
  *
- * \param dbex Pointer to \ref rpadbex_t object.
- * \param rid current production ID.
- * \return Returns the ID of the next production.
+ * @param dbex Pointer to @ref rpadbex_t object.
+ * @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 production ID
+ * @brief Return the previous production ID
  *
- * \param dbex Pointer to \ref rpadbex_t object.
- * \param rid current production ID.
- * \return Returns the ID of the previous production.
+ * @param dbex Pointer to @ref rpadbex_t object.
+ * @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 production
+ * @brief Returns the string length of the specified BNF production
  *
- * \param dbex Pointer to \ref rpadbex_t object.
- * \param rid production ID.
- * \return the string length of the specified production
+ * @param dbex Pointer to @ref rpadbex_t object.
+ * @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 production 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 production ID.
- * \param dest destination buffer
- * \param size to be copied
- * \return Return the number of bytes written in the buffer.
+ * @param dbex Pointer to @ref rpadbex_t object.
+ * @param rid production ID.
+ * @param dest destination buffer
+ * @param size to be copied
+ * @return Return the number of bytes written in the buffer.
  */
 rsize_t rpa_dbex_strncpy(rpadbex_t *dbex, rchar *dest, rparule_t rid, rsize_t size);
 
 
 /**
- * \brief Set a configuration value for the dbex object.
+ * @brief Set a configuration value for the dbex object.
  *
- * \param dbex Pointer to \ref rpadbex_t object.
- * \param cfg Configuration ID
- * \param val Configuration value
+ * @param dbex Pointer to @ref rpadbex_t object.
+ * @param cfg Configuration ID
+ * @param val Configuration value
  *
  * Supported configuration IDs / Values:
  * - RPA_DBEXCFG_OPTIMIZATIONS
@@ -339,11 +339,11 @@ rlong rpa_dbex_cfgset(rpadbex_t *dbex, rulong cfg, rulong val);
 
 
 /**
- * \brief Get a configuration value for the dbex object.
+ * @brief Get a configuration value for the dbex object.
  *
- * \param dbex Pointer to \ref rpadbex_t object.
- * \param cfg Configuration ID.
- * \return Return the value of the specified configuration ID. If an error occurs the return negative.
+ * @param dbex Pointer to @ref rpadbex_t object.
+ * @param cfg Configuration ID.
+ * @return Return the value of the specified configuration ID. If an error occurs the return negative.
  *
  * Supported configuration IDs
  * - RPA_DBEXCFG_OPTIMIZATIONS
@@ -353,57 +353,57 @@ rlong rpa_dbex_cfgget(rpadbex_t *dbex, rulong cfg);
 
 
 /**
- * \brief Printeger a BNF production in a tree format
+ * @brief Printeger 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.
+ * 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.
  */
 rinteger rpa_dbex_dumptree(rpadbex_t *dbex, rparule_t rid);
 
 /**
- * \brief Dump the compiled byte code for the specified production ID
+ * @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.
+ * @param dbex Pointer to @ref rpadbex_t object.
+ * @param rid production ID.
+ * @return Return 0 on success or negative if error occurred.
  */
 rinteger rpa_dbex_dumpcode(rpadbex_t* dbex, rparule_t rid);
 
 
 /**
- * \brief Printeger the AST of the parsed BNF productions.
+ * @brief Printeger the AST of the parsed BNF productions.
  *
  * 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.
+ * @param dbex Pointer to @ref rpadbex_t object.
+ * @return Return 0 on success or negative if error occurred.
  */
 rinteger rpa_dbex_dumprecords(rpadbex_t *dbex);
 
 /**
- * \brief Printeger the content of BNF productions database.
+ * @brief Printeger the content of BNF productions database.
  *
  * Enumerate all BNF productions and printeger them in a text format.
- * \param dbex Pointer to \ref rpadbex_t object.
- * \return Return 0 on success or negative if error occurred.
+ * @param dbex Pointer to @ref rpadbex_t object.
+ * @return Return 0 on success or negative if error occurred.
  */
 rinteger rpa_dbex_dumpproductions(rpadbex_t *dbex);
 
 /**
- * \brief Printeger debug information about the state of the BNF productions database.
+ * @brief Printeger 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.
+ * @param dbex Pointer to @ref rpadbex_t object.
+ * @return Return 0 on success or negative if error occurred.
  */
 rinteger rpa_dbex_dumpinfo(rpadbex_t *dbex);
 
 /**
- * \brief Printeger the production user IDs in a format suitable to be
+ * @brief Printeger 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
@@ -412,7 +412,7 @@ rinteger rpa_dbex_dumpinfo(rpadbex_t *dbex);
 rinteger rpa_dbex_dumpuids(rpadbex_t *dbex);
 
 /**
- * \example personname.c
+ * @example personname.c
  */
 
 /**
index a81cd75..b1bd917 100644 (file)
@@ -19,8 +19,8 @@
  */
 
 /**
- * \file rpa/rpaerror.h
- * \brief The public interface for examining errors.
+ * @file rpa/rpaerror.h
+ * @brief The public interface for examining errors.
  *
  *
  * <h2>Synopsis</h2>
 
 #include "rtypes.h"
 
-#define RPA_ERRINFO_NONE 0
-#define RPA_ERRINFO_CODE (1<<0)
-#define RPA_ERRINFO_OFFSET (1<<1)
-#define RPA_ERRINFO_LINE (1<<2)
-#define RPA_ERRINFO_RULEID (1<<3)
-#define RPA_ERRINFO_NAME (1<<4)
-
-
-#define RPA_E_NONE 0
-#define RPA_E_OUTOFMEM 1001
-#define RPA_E_NOTCOMPILED 1002
-#define RPA_E_NOTOPEN 1003
-#define RPA_E_NOTCLOSED 1004
-#define RPA_E_NOTFOUND 1005
-#define RPA_E_SYNTAXERROR 1006
-#define RPA_E_UNRESOLVEDSYMBOL 1007
-#define RPA_E_PARAM 1008
-#define RPA_E_COMPILE 1009
-
-#define RPA_E_EXECUTION 2001
-#define RPA_E_USERABORT 2002
-#define RPA_E_RULEABORT 2003
-#define RPA_E_INVALIDINPUT 2004
+#define RPA_ERRINFO_NONE 0                             /**< No error fields are set */
+#define RPA_ERRINFO_CODE (1<<0)                        /**< The code field is set */
+#define RPA_ERRINFO_OFFSET (1<<1)              /**< The offset field is set */
+#define RPA_ERRINFO_LINE (1<<2)                        /**< The line field is set */
+#define RPA_ERRINFO_RULEID (1<<3)              /**< The ruleid is set */
+#define RPA_ERRINFO_NAME (1<<4)                        /**< The name field is set */
+
+
+#define RPA_E_NONE 0                                   /**< No error */
+#define RPA_E_OUTOFMEM 1001                            /**< Not enough memory */
+#define RPA_E_NOTCOMPILED 1002                 /**< The database is not yet compiled to byte code. Some of the operations are not possible until the call to @ref rpa_dbex_compile is made. */
+#define RPA_E_NOTOPEN 1003                             /**< The database is not open. Use @ref rpa_dbex_open to open it. */
+#define RPA_E_NOTCLOSED 1004                   /**< The database is not closed. Use @ref rpa_dbex_close to close it. */
+#define RPA_E_NOTFOUND 1005                            /**< The specified rule cannot be found */
+#define RPA_E_SYNTAXERROR 1006                 /**< Syntax Error. Check the BNF syntax. */
+#define RPA_E_UNRESOLVEDSYMBOL 1007            /**< A rule name is used in the BNF specification, but it is not defined */
+#define RPA_E_PARAM 1008                               /**< Invalid parameter */
+#define RPA_E_COMPILE 1009                             /**< Compile error */
+
+#define RPA_E_EXECUTION 2001                   /**< Execution error */
+#define RPA_E_USERABORT 2002                   /**< Operation is interrupted by user */
+#define RPA_E_RULEABORT 2003                   /**< If a rule is set to abort with the directive #!abort, if it cannot be matched the engine will generate this error */
+#define RPA_E_INVALIDINPUT 2004                        /**< Invalid input was specified */
 
 /**
- * \typedef rpaerror_t
- * \brief RPA error description.
+ * @brief RPA error description.
  */
 typedef struct rpa_errinfo_s rpa_errinfo_t;
+
+/**
+ * \struct rpa_errinfo_s <rpa/rpaerror.h> <rpa/rpaerror.h>
+ * @brief Error description.
+ */
 struct rpa_errinfo_s {
+       /**
+        * Mask of valid fields
+        * - @ref RPA_ERRINFO_CODE
+        * - @ref RPA_ERRINFO_OFFSET
+        * - @ref RPA_ERRINFO_LINE
+        * - @ref RPA_ERRINFO_RULEID
+        * - @ref RPA_ERRINFO_NAME
+        */
        rulong mask;
+
+       /**
+        * Error code:
+        * - @ref RPA_E_NONE
+        * - @ref RPA_E_OUTOFMEM
+        * - ...
+        */
        rlong code;
+
+       /**
+        * Error offset in the BNF schema
+        */
        rlong offset;
+
+       /**
+        * Error line in the BNF schema
+        */
        rlong line;
-       rlong ruleid;
+
+       /**
+        * Error rule user ID. If the engine can determine the ruleuid of the rule generating the error,
+        * this field will be set accordingly
+        */
+       rlong ruleuid;
+
+       /**
+        * Error rule name
+        */
        rchar name[128];
 };
 
index 89f9b8f..4b94300 100644 (file)
  */
 
 /**
- * \file rpa/rparecord.h
- * \brief The public interface for working with Abstract Syntax Tree (AST), produced by @ref rpa_stat_parse.
+ * @file rpa/rparecord.h
+ * @brief The public interface for working with Abstract Syntax Tree (AST), produced by @ref rpa_stat_parse.
  *
  *
  * <h2>Synopsis</h2>
- * Upon a successful call to \ref rpa_stat_parse, the parser produces a stack of \ref rparecord_t records.
- * There are two kinds of records: \ref RPA_RECORD_START and \ref RPA_RECORD_END. \ref RPA_RECORD_START marks
- * the beginning of a branch and \ref RPA_RECORD_END marks the end of that branch. Empty branches are specified by
- * a record \ref RPA_RECORD_START followed immediately by \ref RPA_RECORD_END (no child records in between).
+ * Upon a successful call to @ref rpa_stat_parse, the parser produces a stack of @ref rparecord_t records.
+ * There are two kinds of records: @ref RPA_RECORD_START and @ref RPA_RECORD_END. @ref RPA_RECORD_START marks
+ * the beginning of a branch and @ref RPA_RECORD_END marks the end of that branch. Empty branches are specified by
+ * a record @ref RPA_RECORD_START followed immediately by @ref RPA_RECORD_END (no child records in between).
  * Empty branches are considered leaves.
  *
  * Example:
@@ -77,19 +77,19 @@ extern "C" {
 #define RPA_RECORD_END (1 << 1)                                        /**< End record - the parser generates this record after evaluating the rule and the rule matched some input. */
 
 /**
- * typedef rparecord_t
+ * Abstract Syntax Tree (AST) construction element
  */
 typedef struct rparecord_s rparecord_t;
 
 /**
- * typedef rpa_recordtree_callback
+ * Tree walk callback
  */
 typedef rlong (*rpa_recordtree_callback)(rarray_t *records, rlong rec, rpointer userdata);
 
 
 /**
  * \struct rparecord_s <rpa/rparecord.h> <rpa/rparecord.h>
- * \brief Abstract Syntax Tree (AST) construction element.
+ * Abstract Syntax Tree (AST) construction element.
  */
 struct rparecord_s {
        ruint32 top;                    /**< This is a private member, used by the engine and is not significant to the user */
index 64ccda8..4c0b565 100644 (file)
@@ -41,65 +41,65 @@ extern "C" {
 #endif
 
 /**
- * \file rpa/rpastat.h
- * \brief The public interface to the execution context.
+ * @file rpa/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
+ * BNF productions database @ref rpadbex_t
  */
 
 
 /**
- * \typedef rpastat_t
- * \brief Execution context. If you need mutli-threading, multiple objects of this
+ * @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.
+ * 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;
 
 /**
- * \brief Create an object of type \ref rpastat_t.
+ * @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
+ * 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
+ * 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.
+ * 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.
+ * @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
+ * @brief Destroy an object of type @ref rpastat_t
  *
- * Destroy the object created with \ref rpa_stat_create. After calling this function
+ * 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 of type \ref rpastat_t.
+ * @param stat Pointer to object of type @ref rpastat_t.
  */
 void rpa_stat_destroy(rpastat_t *stat);
 
 
 /**
- * \brief Scan an input stream
+ * @brief Scan an input stream
  *
  * Scan the stream using the specified rule id.
- * \param stat Pointer to object of type \ref rpastat_t
- * \param rid Rule ID of the BNF root.
- * \param encoding Input stream encoding. This parameter specifies how to interpret the data in the input stream. If you want the parser to
+ * @param stat Pointer to object of type @ref rpastat_t
+ * @param rid Rule ID of the BNF root.
+ * @param encoding Input stream encoding. This parameter specifies how to interpret the data in the input stream. If you want the parser to
  * ignore the case of the parsed data use encodings with _ICASE_. Supported encodings are:
  *             - RPA_ENCODING_UTF8
  *             - RPA_ENCODING_UTF16LE
@@ -107,23 +107,23 @@ void rpa_stat_destroy(rpastat_t *stat);
  *             - RPA_ENCODING_ICASE_UTF8
  *             - RPA_ENCODING_ICASE_UTF16LE
  *             - RPA_ENCODING_ICASE_BYTE
- * \param input The starting point of the operation. The input pointer must be: input >= start and input < end
- * \param start The start of the buffer.
- * \param end The end of the buffer, it should be: end = start + buffersize.
- * \param where If this function returns a number greater than 0 (a match was found) this parameter will be
+ * @param input The starting point of the operation. The input pointer must be: input >= start and input < end
+ * @param start The start of the buffer.
+ * @param end The end of the buffer, it should be: end = start + buffersize.
+ * @param where If this function returns a number greater than 0 (a match was found) this parameter will be
  *                             initialized with a pointer the place in the buffer where the match was found.
- * \return If successful return the size of the matched string in bytes, if no match was found
+ * @return If successful return the size of the matched string in bytes, if no match was found
  *                     return 0, return negative in case of error.
  */
 rlong rpa_stat_scan(rpastat_t *stat, rparule_t rid, ruinteger encoding, const rchar *input, const rchar *start, const rchar *end, const rchar **where);
 
 /**
- * \brief Parse an input stream
+ * @brief Parse an input stream
  *
  * Parse the stream using the specified rule id.
- * \param stat Pointer to object of type \ref rpastat_t
- * \param rid Rule ID of the BNF root.
- * \param encoding Input stream encoding. This parameter specifies how to interpret the data in the input stream. If you want the parser to
+ * @param stat Pointer to object of type @ref rpastat_t
+ * @param rid Rule ID of the BNF root.
+ * @param encoding Input stream encoding. This parameter specifies how to interpret the data in the input stream. If you want the parser to
  * ignore the case of the parsed data use encodings with _ICASE_. Supported encodings are:
  *             - RPA_ENCODING_UTF8
  *             - RPA_ENCODING_UTF16LE
@@ -131,25 +131,25 @@ rlong rpa_stat_scan(rpastat_t *stat, rparule_t rid, ruinteger encoding, const rc
  *             - RPA_ENCODING_ICASE_UTF8
  *             - RPA_ENCODING_ICASE_UTF16LE
  *             - RPA_ENCODING_ICASE_BYTE
- * \param input The starting point of the operation. The input pointer must be: input >= start and input < end
- * \param start The start of the buffer.
- * \param end The end of the buffer, it should be: end = start + buffersize.
- * \param records If the function is successful this parameter will be used to
+ * @param input The starting point of the operation. The input pointer must be: input >= start and input < end
+ * @param start The start of the buffer.
+ * @param end The end of the buffer, it should be: end = start + buffersize.
+ * @param records If the function is successful this parameter will be used to
  *                     store the AST records the parser generates. The records stored in the array
- *                     are of type \ref rparecord_t
- * \return If successful return the size of the matched string in bytes, if the input stream cannot be matched against the BNF
+ *                     are of type @ref rparecord_t
+ * @return If successful return the size of the matched string in bytes, if the input stream cannot be matched against the BNF
  *                     return 0, return negative in case of error.
  */
 rlong rpa_stat_parse(rpastat_t *stat, rparule_t rid, ruinteger encoding, const rchar *input, const rchar *start, const rchar *end, rarray_t *records);
 
 /**
- * \brief Match an input stream
+ * @brief Match an input stream
  *
  * Match the stream using the specified rule id. This function is similar to /ref rpa_stat_parse, but it
  * doesn't generate parsing records. It just returs the size of the matched input stream.
- * \param stat Pointer to object of type \ref rpastat_t
- * \param rid Rule ID of the BNF root.
- * \param encoding Input stream encoding. This parameter specifies how to interpret the data in the input stream. If you want the parser to
+ * @param stat Pointer to object of type @ref rpastat_t
+ * @param rid Rule ID of the BNF root.
+ * @param encoding Input stream encoding. This parameter specifies how to interpret the data in the input stream. If you want the parser to
  * ignore the case of the parsed data use encodings with _ICASE_. Supported encodings are:
  *             - RPA_ENCODING_UTF8
  *             - RPA_ENCODING_UTF16LE
@@ -157,24 +157,24 @@ rlong rpa_stat_parse(rpastat_t *stat, rparule_t rid, ruinteger encoding, const r
  *             - RPA_ENCODING_ICASE_UTF8
  *             - RPA_ENCODING_ICASE_UTF16LE
  *             - RPA_ENCODING_ICASE_BYTE
- * \param input The starting point of the operation. The input pointer must be: input >= start and input < end
- * \param start The start of the buffer.
- * \param end The end of the buffer, it should be: end = start + buffersize.
- * \return If successful return the size of the matched string in bytes, if the input stream cannot be matched against the BNF
+ * @param input The starting point of the operation. The input pointer must be: input >= start and input < end
+ * @param start The start of the buffer.
+ * @param end The end of the buffer, it should be: end = start + buffersize.
+ * @return If successful return the size of the matched string in bytes, if the input stream cannot be matched against the BNF
  *                     return 0, return negative in case of error.
  */
 rlong rpa_stat_match(rpastat_t *stat, rparule_t rid, ruinteger encoding, const rchar *input, const rchar *start, const rchar *end);
 
 
 /**
- * \brief Execute the parser byte code to parse/match an input stream.
+ * @brief Execute the parser byte code to parse/match an input stream.
  *
- * This is a low level function used by \ref rpa_stat_parse \ref rpa_stat_match and \ref rpa_stat_scan. You shouldn't
+ * This is a low level function used by @ref rpa_stat_parse @ref rpa_stat_match and @ref rpa_stat_scan. You shouldn't
  * need to use it directly.
- * \param stat Pointer to object of type \ref rpastat_t
- * \param prog Byte code
- * \param off Execution start point
- * \param encoding Input stream encoding. This parameter specifies how to interpret the data in the input stream. If you want the parser to
+ * @param stat Pointer to object of type @ref rpastat_t
+ * @param prog Byte code
+ * @param off Execution start point
+ * @param encoding Input stream encoding. This parameter specifies how to interpret the data in the input stream. If you want the parser to
  * ignore the case of the parsed data use encodings with _ICASE_. Supported encodings are:
  *             - RPA_ENCODING_UTF8
  *             - RPA_ENCODING_UTF16LE
@@ -182,51 +182,51 @@ rlong rpa_stat_match(rpastat_t *stat, rparule_t rid, ruinteger encoding, const r
  *             - RPA_ENCODING_ICASE_UTF8
  *             - RPA_ENCODING_ICASE_UTF16LE
  *             - RPA_ENCODING_ICASE_BYTE
- * \param input The starting point of the operation. The input pointer must be: input >= start and input < end
- * \param start The start of the buffer.
- * \param end The end of the buffer, it should be: end = start + buffersize.
- * \param records If the function is successful this parameter will be used to
+ * @param input The starting point of the operation. The input pointer must be: input >= start and input < end
+ * @param start The start of the buffer.
+ * @param end The end of the buffer, it should be: end = start + buffersize.
+ * @param records If the function is successful this parameter will be used to
  *                     store the AST records the parser generates. The records stored in the array
- *                     are of type \ref rparecord_t
- * \return If successful return the size of the matched string in bytes, if the input stream cannot be matched against the BNF
+ *                     are of type @ref rparecord_t
+ * @return If successful return the size of the matched string in bytes, if the input stream cannot be matched against the BNF
  *                     return 0, return negative in case of error.
  */
 rlong rpa_stat_exec(rpastat_t *stat, rvm_asmins_t *prog, rword off, ruinteger encoding, const rchar *input, const rchar *start, const rchar *end, rarray_t *records);
 
 
 /**
- * \brief Abort the current operation.
+ * @brief Abort the current operation.
  *
- * Use this function to abort \ref rpa_stat_parse \ref rpa_stat_match and \ref rpa_stat_scan or \ref rpa_stat_exec
- * \param stat Pointer to object of type \ref rpastat_t
- * \return If sucessful return 0, otherwise return negative.
+ * Use this function to abort @ref rpa_stat_parse @ref rpa_stat_match and @ref rpa_stat_scan or @ref rpa_stat_exec
+ * @param stat Pointer to object of type @ref rpastat_t
+ * @return If sucessful return 0, otherwise return negative.
  */
 rinteger rpa_stat_abort(rpastat_t *stat);
 
 
 /**
- * \brief Return the error code of the last occurred error.
+ * @brief Return the error code of the last occurred error.
  *
- * \param stat Pointer to \ref rpastat_t object.
- * \return The error code of the last occurred error. If this function fails the
+ * @param stat Pointer to @ref rpastat_t object.
+ * @return The error code of the last occurred error. If this function fails the
  * return value is negative.
  */
 rlong rpa_stat_lasterror(rpastat_t *stat);
 
 /**
- * \brief Get error information for the last occurred error.
+ * @brief Get error information for the last occurred error.
  *
- * \param stat Pointer to \ref rpastat_t object.
- * \param errinfo Pointer to \ref rpa_errinfo_t buffer that will be
+ * @param stat Pointer to @ref rpastat_t object.
+ * @param errinfo Pointer to @ref rpa_errinfo_t buffer that will be
  * filled with the error information. This parameter cannot be NULL.
- * \return Return 0 if the function is successful or negative otherwise. If this function fails the
+ * @return Return 0 if the function is successful or negative otherwise. If this function fails the
  * return value is negative.
  */
 rlong rpa_stat_lasterrorinfo(rpastat_t *stat, rpa_errinfo_t *errinfo);
 
 
 /**
- * \example personname.c
+ * @example personname.c
  */
 
 
index e9d0959..ceb9103 100644 (file)
@@ -36,7 +36,7 @@ extern "C" {
 
 #define RPA_STAT_SETERROR_CODE(__d__, __e__) do { (__d__)->err.code = __e__; (__d__)->err.mask |= RPA_ERRINFO_CODE;} while (0)
 #define RPA_STAT_SETERRINFO_OFFSET(__d__, __o__) do { (__d__)->err.offset = __o__; (__d__)->err.mask |= RPA_ERRINFO_OFFSET; } while (0)
-#define RPA_STAT_SETERRINFO_RULEUID(__d__, __r__) do { (__d__)->err.ruleid = __r__; (__d__)->err.mask |= RPA_ERRINFO_RULEID; } while (0)
+#define RPA_STAT_SETERRINFO_RULEUID(__d__, __r__) do { (__d__)->err.ruleuid = __r__; (__d__)->err.mask |= RPA_ERRINFO_RULEID; } while (0)
 #define RPA_STAT_SETERRINFO_NAME(__d__, __n__, __s__) do { \
        (__d__)->err.mask |= RPA_ERRINFO_NAME; \
        r_memset((__d__)->err.name, 0, sizeof((__d__)->err.name)); \