Typedefs | Functions
rpastat.h File Reference

The public interface to the execution context. More...

Go to the source code of this file.

Typedefs

typedef struct rpastat_s rpastat_t
 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: rpa_stat_parse, rpa_stat_match and rpa_stat_scan have to be called from separate threads.

Functions

rpastat_trpa_stat_create (rpadbex_t *dbex, unsigned long stacksize)
 Create an object of type rpastat_t.
void rpa_stat_destroy (rpastat_t *stat)
 Destroy an object of type rpastat_t.
long rpa_stat_scan (rpastat_t *stat, rparule_t rid, unsigned int encoding, const char *input, const char *start, const char *end, const char **where)
 Scan an input stream.
long rpa_stat_parse (rpastat_t *stat, rparule_t rid, unsigned int encoding, const char *input, const char *start, const char *end, rarray_t *records)
 Parse an input stream.
long rpa_stat_match (rpastat_t *stat, rparule_t rid, unsigned int encoding, const char *input, const char *start, const char *end)
 Match an input stream.
long rpa_stat_exec (rpastat_t *stat, rvm_asmins_t *prog, ruword off, unsigned int encoding, const char *input, const char *start, const char *end, rarray_t *records)
 Execute the parser byte code to parse/match an input stream.
int rpa_stat_abort (rpastat_t *stat)
 Abort the current operation.
long rpa_stat_lasterror (rpastat_t *stat)
 Return the error code of the last occurred error.
long rpa_stat_lasterrorinfo (rpastat_t *stat, rpa_errinfo_t *errinfo)
 Get error information for the last occurred error.

Detailed Description

The public interface to the execution context.

Synopsis

The following APIs are used to parse, match, scan an input stream, using an existing BNF productions database rpadbex_t


Function Documentation

int rpa_stat_abort ( rpastat_t stat)

Abort the current operation.

Use this function to abort rpa_stat_parse rpa_stat_match and rpa_stat_scan or rpa_stat_exec

Parameters:
statPointer to object of type rpastat_t
Returns:
If sucessful return 0, otherwise return negative.
rpastat_t* rpa_stat_create ( rpadbex_t dbex,
unsigned long  stacksize 
)

Create an object of type rpastat_t.

Multi-threading is supported by creating multiple rpastat_t objects, referencing the same rpadbex_t BNF productions database. Every thread must have its own 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 rpa_stat_parse, rpa_stat_match and rpa_stat_scan from the main thread.

The allocated rpastat_t object must be destroyed with rpa_stat_destroy.

Parameters:
dbexBNF productions database created with rpa_dbex_create.
stacksizeExecution stack size. The size is specified in byts.
Returns:
Returns a pointer to newly created rpastat_t object or NULL if error occurred.
Examples:
personname.c.
void rpa_stat_destroy ( rpastat_t stat)

Destroy an object of type rpastat_t.

Destroy the object created with rpa_stat_create. After calling this function the pointer is invalid and must never be used again.

Parameters:
statPointer to object of type rpastat_t.
Examples:
personname.c.
long rpa_stat_exec ( rpastat_t stat,
rvm_asmins_t *  prog,
ruword  off,
unsigned int  encoding,
const char *  input,
const char *  start,
const char *  end,
rarray_t *  records 
)

Execute the parser byte code to parse/match an input stream.

This is a low level function used by rpa_stat_parse rpa_stat_match and rpa_stat_scan. You shouldn't need to use it directly.

Parameters:
statPointer to object of type rpastat_t
progByte code
offExecution start point
encodingInput 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
  • RPA_ENCODING_BYTE
  • RPA_ENCODING_ICASE_UTF8
  • RPA_ENCODING_ICASE_UTF16LE
  • RPA_ENCODING_ICASE_BYTE
inputThe starting point of the operation. The input pointer must be: input >= start and input < end
startThe start of the buffer.
endThe end of the buffer, it should be: end = start + buffersize.
recordsIf 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 rparecord_t
Returns:
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.
long rpa_stat_lasterror ( rpastat_t stat)

Return the error code of the last occurred error.

Parameters:
statPointer to rpastat_t object.
Returns:
The error code of the last occurred error. If this function fails the return value is negative.
long rpa_stat_lasterrorinfo ( rpastat_t stat,
rpa_errinfo_t errinfo 
)

Get error information for the last occurred error.

Parameters:
statPointer to rpastat_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_stat_match ( rpastat_t stat,
rparule_t  rid,
unsigned int  encoding,
const char *  input,
const char *  start,
const char *  end 
)

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.

Parameters:
statPointer to object of type rpastat_t
ridRule ID of the BNF root.
encodingInput 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
  • RPA_ENCODING_BYTE
  • RPA_ENCODING_ICASE_UTF8
  • RPA_ENCODING_ICASE_UTF16LE
  • RPA_ENCODING_ICASE_BYTE
inputThe starting point of the operation. The input pointer must be: input >= start and input < end
startThe start of the buffer.
endThe end of the buffer, it should be: end = start + buffersize.
Returns:
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.
long rpa_stat_parse ( rpastat_t stat,
rparule_t  rid,
unsigned int  encoding,
const char *  input,
const char *  start,
const char *  end,
rarray_t *  records 
)

Parse an input stream.

Parse the stream using the specified rule id.

Parameters:
statPointer to object of type rpastat_t
ridRule ID of the BNF root.
encodingInput 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
  • RPA_ENCODING_BYTE
  • RPA_ENCODING_ICASE_UTF8
  • RPA_ENCODING_ICASE_UTF16LE
  • RPA_ENCODING_ICASE_BYTE
inputThe starting point of the operation. The input pointer must be: input >= start and input < end
startThe start of the buffer.
endThe end of the buffer, it should be: end = start + buffersize.
recordsIf 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 rparecord_t
Returns:
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.
Examples:
personname.c.
long rpa_stat_scan ( rpastat_t stat,
rparule_t  rid,
unsigned int  encoding,
const char *  input,
const char *  start,
const char *  end,
const char **  where 
)

Scan an input stream.

Scan the stream using the specified rule id.

Parameters:
statPointer to object of type rpastat_t
ridRule ID of the BNF root.
encodingInput 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
  • RPA_ENCODING_BYTE
  • RPA_ENCODING_ICASE_UTF8
  • RPA_ENCODING_ICASE_UTF16LE
  • RPA_ENCODING_ICASE_BYTE
inputThe starting point of the operation. The input pointer must be: input >= start and input < end
startThe start of the buffer.
endThe end of the buffer, it should be: end = start + buffersize.
whereIf 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.
Returns:
If successful return the size of the matched string in bytes, if no match was found return 0, return negative in case of error.