Files | Typedefs | Functions
Regular Pattern Analyser (RPA)

Files

file  rpadbex.h
 

The public interface to BNF productions database API.


Typedefs

typedef struct rpadbex_s rpadbex_t
 Database of BNF productions (The BNF schema)
typedef long rparule_t
 Unique BNF rule identifier.

Functions

const char * rpa_dbex_version ()
 Return the version string of the RPA library.
rpadbex_trpa_dbex_create (void)
 Create an object of type rpadbex_t.
void rpa_dbex_destroy (rpadbex_t *dbex)
 Destroy an object of type rpadbex_t, created by rpa_dbex_create.
long rpa_dbex_lasterror (rpadbex_t *dbex)
 Return the error code of the last occurred error.
long rpa_dbex_lasterrorinfo (rpadbex_t *dbex, rpa_errinfo_t *errinfo)
 Get error information for the last occurred error.
int rpa_dbex_open (rpadbex_t *dbex)
 Open the BNF productions database.
void rpa_dbex_close (rpadbex_t *dbex)
 Close the BNF productions database.
int rpa_dbex_compile (rpadbex_t *dbex)
 Compile the BNF productions database to byte code.
long rpa_dbex_load (rpadbex_t *dbex, const char *buffer, unsigned long size)
 Load BNF production(s) into the database.
long rpa_dbex_load_s (rpadbex_t *dbex, const char *buffer)
 Load BNF production(s) into the database. Same as rpa_dbex_load, but the buffer is NULL terminated string.
rvm_asmins_t * rpa_dbex_executable (rpadbex_t *dbex)
 Return a pointer to the executable code segment.
long rpa_dbex_executableoffset (rpadbex_t *dbex, rparule_t rid)
 Return the offset of the executable byte code for the specified rule.
rparule_t rpa_dbex_lookup (rpadbex_t *dbex, const char *name, unsigned int namesize)
 Lookup BNF production ID in the database.
rparule_t rpa_dbex_lookup_s (rpadbex_t *dbex, const char *name)
 Lookup BNF production ID in the database.
const char * rpa_dbex_name (rpadbex_t *dbex, rparule_t rid)
 Return the name of the specified rule ID.
rparule_t rpa_dbex_first (rpadbex_t *dbex)
 Return the first production ID in the database.
rparule_t rpa_dbex_last (rpadbex_t *dbex)
 Return the last production ID.
rparule_t rpa_dbex_next (rpadbex_t *dbex, rparule_t rid)
 Return the next production ID.
rparule_t rpa_dbex_prev (rpadbex_t *dbex, rparule_t rid)
 Return the previous production ID.
long rpa_dbex_strlen (rpadbex_t *dbex, rparule_t rid)
 Returns the string length of the specified BNF production.
long rpa_dbex_strncpy (rpadbex_t *dbex, char *dest, rparule_t rid, unsigned long size)
 Copy the string of the specified BNF production to the destination buffer.
long rpa_dbex_cfgset (rpadbex_t *dbex, unsigned long cfg, unsigned long val)
 Set a configuration value for the dbex object.
long rpa_dbex_cfgget (rpadbex_t *dbex, unsigned long cfg)
 Get a configuration value for the dbex object.
int rpa_dbex_dumptree (rpadbex_t *dbex, rparule_t rid)
 Print a BNF production in a tree format.
int rpa_dbex_dumpcode (rpadbex_t *dbex, rparule_t rid)
 Dump the compiled byte code for the specified production ID.
int rpa_dbex_dumprecords (rpadbex_t *dbex)
 Print the AST of the parsed BNF productions.
int rpa_dbex_dumpproductions (rpadbex_t *dbex)
 Print the content of BNF productions database.
int rpa_dbex_dumpinfo (rpadbex_t *dbex)
 Print debug information about the state of the BNF productions database.
int rpa_dbex_dumpuids (rpadbex_t *dbex)
 Print the production user IDs in a format suitable to be included in source code.

Function Documentation

long rpa_dbex_cfgget ( rpadbex_t dbex,
unsigned long  cfg 
)

Get a configuration value for the dbex object.

Parameters:
dbexPointer to rpadbex_t object.
cfgConfiguration ID.
Returns:
Return the value of the specified configuration ID. If an error occurs the return negative.

Supported configuration IDs

  • RPA_DBEXCFG_OPTIMIZATIONS
  • RPA_DBEXCFG_DEBUG
  • RPA_DBEXCFG_BITMAP
long rpa_dbex_cfgset ( rpadbex_t dbex,
unsigned long  cfg,
unsigned long  val 
)

Set a configuration value for the dbex object.

Parameters:
dbexPointer to rpadbex_t object.
cfgConfiguration ID
valConfiguration value

Supported configuration IDs / Values:

  • RPA_DBEXCFG_OPTIMIZATIONS
    • 0 Disable optimizations
    • 1 Enable optimizations
  • RPA_DBEXCFG_DEBUG
    • 0 Disable debugging
    • 1 Enable debugging
  • RPA_DBEXCFG_BITMAP
    • 0 Disable bitmap
    • 1 Enable bitmap
void rpa_dbex_close ( rpadbex_t dbex)

Close the BNF productions database.

This function must be called when the BNF schema is complete and ready to be compiled.

Parameters:
dbexPointer to rpadbex_t object.
Examples:
personname.c.
int rpa_dbex_compile ( rpadbex_t dbex)

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 rpastat_t.

Parameters:
dbexPointer to rpadbex_t object.
Returns:
If successful return 0, otherwise return negative. Use rpa_dbex_lasterror or rpa_dbex_lasterrorinfo to retrieve the error information.
Examples:
personname.c.
rpadbex_t* rpa_dbex_create ( void  )

Create an object of type rpadbex_t.

The created object must be destroyed with rpa_dbex_destroy.

Returns:
pointer to newly create BNF productions database object.
Examples:
personname.c.
void rpa_dbex_destroy ( rpadbex_t dbex)

Destroy an object of type rpadbex_t, created by rpa_dbex_create.

Use this function to destroy the object. After this call the pointer to dbex should never be used again.

Parameters:
dbexpointer to an object of type rpadbex_t
Examples:
personname.c.
int rpa_dbex_dumpcode ( rpadbex_t dbex,
rparule_t  rid 
)

Dump the compiled byte code for the specified production ID.

This function is a debug helper, you shouldn't need it.

Parameters:
dbexPointer to rpadbex_t object.
ridproduction ID.
Returns:
Return 0 on success or negative if error occurred.
int rpa_dbex_dumpinfo ( rpadbex_t dbex)

Print debug information about the state of the BNF productions database.

This is a debug helper, you shouldn't need it.

Parameters:
dbexPointer to rpadbex_t object.
Returns:
Return 0 on success or negative if error occurred.
int rpa_dbex_dumpproductions ( rpadbex_t dbex)

Print the content of BNF productions database.

Enumerate all BNF productions and print them in a text format.

Parameters:
dbexPointer to rpadbex_t object.
Returns:
Return 0 on success or negative if error occurred.
int rpa_dbex_dumprecords ( rpadbex_t dbex)

Print the AST of the parsed BNF productions.

This function is a debug helper, you shouldn't need it. unless you are debugging this library.

Parameters:
dbexPointer to rpadbex_t object.
Returns:
Return 0 on success or negative if error occurred.
int rpa_dbex_dumptree ( rpadbex_t dbex,
rparule_t  rid 
)

Print a BNF production in a tree format.

Use rpa_dbex_lookup to find the ID of a BNF production

Parameters:
dbexPointer to rpadbex_t object.
ridproduction ID.
Returns:
Return 0 on success or negative if error occurred.
int rpa_dbex_dumpuids ( rpadbex_t dbex)

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.

rvm_asmins_t* rpa_dbex_executable ( rpadbex_t dbex)

Return a pointer to the executable code segment.

This function will succeed only if it is called after a call to rpa_dbex_compile.

Parameters:
dbexPointer to rpadbex_t object.
Returns:
Pointer to the beginning of executable byte code. In case of an error it returns NULL. Use rpa_dbex_lasterror or rpa_dbex_lasterrorinfo to retrieve the error information.
long rpa_dbex_executableoffset ( rpadbex_t dbex,
rparule_t  rid 
)

Return the offset of the executable byte code for the specified rule.

Return the offset of the executable byte code segment returned by rpa_dbex_executable for the specified rule. The two functions rpa_dbex_executable and 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 rpa_dbex_compile.

Parameters:
dbexPointer to rpadbex_t object.
ridUnique ID of the requested BNF production.
Returns:
Pointer the offset of the executable byte code. In case of an error it returns negative. Use rpa_dbex_lasterror or rpa_dbex_lasterrorinfo to retrieve the error information.
rparule_t rpa_dbex_first ( rpadbex_t dbex)

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.

Parameters:
dbexPointer to rpadbex_t object.
Returns:
Returns the ID of the first production.
rparule_t rpa_dbex_last ( rpadbex_t dbex)

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.

Parameters:
dbexPointer to rpadbex_t object.
Returns:
Returns the ID of the last production.
Examples:
personname.c.
long rpa_dbex_lasterror ( rpadbex_t dbex)

Return the error code of the last occurred error.

Parameters:
dbexPointer to rpadbex_t object.
Returns:
The error code of the last occurred error. If this function fails the return value is negative.
long rpa_dbex_lasterrorinfo ( rpadbex_t dbex,
rpa_errinfo_t errinfo 
)

Get error information for the last occurred error.

Parameters:
dbexPointer to rpadbex_t object.
errinfoPointer to rpa_errinfo_t buffer that will be filled with the error information. This parameter cannot be NULL.
Returns:
Return 0 if the function is successful or negative otherwise. If this function fails the return value is negative.
long rpa_dbex_load ( rpadbex_t dbex,
const char *  buffer,
unsigned long  size 
)

Load BNF production(s) into the database.

Loads the BNF production(s) from the buffer into the dbex database.

Parameters:
dbexPointer to rpadbex_t object.
bufferUTF8 string containing BNF production(s).
sizeBuffer size.
Returns:
Upon successful completion, the function returns the size of the loaded BNF production(s), otherwise returns negative. Use rpa_dbex_lasterror or rpa_dbex_lasterrorinfo to retrieve the error information.
Examples:
personname.c.
long rpa_dbex_load_s ( rpadbex_t dbex,
const char *  buffer 
)

Load BNF production(s) into the database. Same as rpa_dbex_load, but the buffer is NULL terminated string.

Parameters:
dbexPointer to rpadbex_t object.
bufferUTF8 string containing BNF production(s).
Returns:
Upon successful completion, the function returns the size of the copied productions, otherwise returns negative. Use rpa_dbex_lasterror or rpa_dbex_lasterrorinfo to retrieve the error information.
rparule_t rpa_dbex_lookup ( rpadbex_t dbex,
const char *  name,
unsigned int  namesize 
)

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 rpa_dbex_load. You can lookup the unique ID for this production by using this function.

Parameters:
dbexPointer to rpadbex_t object.
nameThe production name (the identifier located before the operator '::= ')
namesizeThe size of the buffer to be used.
Returns:
Unique ID for the specified production name.
rparule_t rpa_dbex_lookup_s ( rpadbex_t dbex,
const char *  name 
)

Lookup BNF production ID in the database.

Same as rpa_dbex_lookup, but the name parameter is NULL terminated string.

const char* rpa_dbex_name ( rpadbex_t dbex,
rparule_t  rid 
)

Return the name of the specified rule ID.

If rid is a valid rule, this function will return a pointer to the rule name. The returned points directly in the database structures, if you need to preserved name, you will have to make a copy.

Parameters:
dbexPointer to rpadbex_t object.
ridRule id
Returns:
Returns the name of the specified ID or NULL in case of error.
rparule_t rpa_dbex_next ( rpadbex_t dbex,
rparule_t  rid 
)

Return the next production ID.

Parameters:
dbexPointer to rpadbex_t object.
ridcurrent production ID.
Returns:
Returns the ID of the next production.
int rpa_dbex_open ( rpadbex_t dbex)

Open the BNF productions database.

This function must be called before inserting any BNF production with rpa_dbex_load or rpa_dbex_load_s. To close the database you must use rpa_dbex_close. The database can opened and closed multiple times as long it is not destroyed with rpa_dbex_destroy.

Parameters:
dbexPointer to rpadbex_t object.
Returns:
If successful return 0, otherwise return negative. Use rpa_dbex_lasterror or rpa_dbex_lasterrorinfo to retrieve the error information.
Examples:
personname.c.
rparule_t rpa_dbex_prev ( rpadbex_t dbex,
rparule_t  rid 
)

Return the previous production ID.

Parameters:
dbexPointer to rpadbex_t object.
ridcurrent production ID.
Returns:
Returns the ID of the previous production.
long rpa_dbex_strlen ( rpadbex_t dbex,
rparule_t  rid 
)

Returns the string length of the specified BNF production.

Parameters:
dbexPointer to rpadbex_t object.
ridproduction ID.
Returns:
the string length of the specified production
long rpa_dbex_strncpy ( rpadbex_t dbex,
char *  dest,
rparule_t  rid,
unsigned long  size 
)

Copy the string of the specified BNF production to the destination buffer.

Parameters:
dbexPointer to rpadbex_t object.
ridproduction ID.
destdestination buffer
sizeto be copied
Returns:
Return the number of bytes written in the buffer.
const char* rpa_dbex_version ( )

Return the version string of the RPA library.

Returns:
NULL terminated version string.