|
APG
… ABNF Parser Generator
|
Required header file for all APG-generated parsers. Contains important configuration macros and declarations of the API functions for the entire library. More...
#include <stdlib.h>#include <string.h>Go to the source code of this file.
Data Structures | |
| struct | APG_MEM_STATS |
| generated by the Memory component, available to the user for display of memory statistics More... | |
| struct | APG_CBDATA |
| The data structure passed to all syntax and AST callback functions, both rule and UDT. More... | |
| struct | APG_PARSER_STATE |
| the state of the parser after parsing an input string. More... | |
| struct | APG_STAT |
| the parsers total node hit statistics More... | |
| struct | APG_NAME_STAT |
| named rule or UDT node statistics More... | |
| struct | APG_PARSER_STATS |
| full set of statistics gathered during parsing, uiParserSyntaxAnalysis() More... | |
Macros | |
| #define | APG_TRUE 1 |
| #define | APG_FALSE 0 |
| #define | APG_UNDEFINED -1 |
| #define | APG_INFINITE -1 |
| #define | APG_VEC_ELEMENT ((apg_uint)1) |
| #define | APG_VEC_ALLOC ((apg_uint)100) |
| #define | APG_DISPLAY_MAX_LINE 128 |
| #define | min(a, b) (((a) < (b)) ? (a) : (b)) |
| #define | max(a, b) (((a) > (b)) ? (a) : (b)) |
| #define | PRE_PARSE ((apg_uint)0) |
| #define | NOMATCH ((apg_uint)1) |
| #define | EMPTY ((apg_uint)2) |
| #define | MATCH ((apg_uint)3) |
| #define | PRE_AST ((apg_uint)4) |
| #define | POST_AST ((apg_uint)5) |
Typedefs | |
| typedef unsigned int | apg_uint |
| typedef unsigned char | apg_achar |
| typedef void(* | PFN_ALERT) (unsigned int uiLine, const char *cpFile) |
| typedef void(* | PFN_ALERT_MSG) (unsigned int uiLine, const char *cpFile, const char *cpMsg) |
| typedef void *(* | PFN_ALLOCATOR) (size_t) |
| typedef void(* | PFN_DEALLOCATOR) (void *) |
| typedef apg_uint(* | APG_CALLBACK) (APG_CBDATA *spData) |
Functions | |
| void | vDefaultAlertHandler (unsigned int uiLine, const char *cpFile) |
| int | apg_stricmp (const char *cpLhs, const char *cpRhs) |
| void | vCharToAChar (apg_achar *acpAChars, const char *cpChars, apg_uint uiLen) |
| apg_uint | uiACharToStringSize (const apg_achar *acpAChars, apg_uint uiALen) |
| apg_uint | uiACharToString (char *cpChars, apg_uint uiCLen, const apg_achar *acpAChars, apg_uint uiALen) |
| void * | vpMemCtorA (PFN_ALLOCATOR pfnAllocator, PFN_DEALLOCATOR pfnDeAllocator) |
| void * | vpMemCtor () |
| void | vMemDtor (void *vpCtx) |
| apg_uint | uiMemValidate (void *vpCtx) |
| void * | vpMemAlloc (void *vpCtx, apg_uint uiBytes) |
| void * | vpMemRealloc (void *vpCtx, void *vpData, apg_uint uiBytes) |
| void | vMemFree (void *vpCtx, void *vpData) |
| apg_uint | uiMemCheckPoint (void *vpCtx) |
| void | vMemFreeToCheckPoint (void *vpCtx, apg_uint uiChk) |
| void | vMemClear (void *vpCtx) |
| void * | vpVecCtor (void *vpMemCtx, apg_uint uiElementSize, apg_uint uiInitialAlloc) |
| void | vVecDtor (void *vpCtx) |
| void * | vpVecPush (void *vpVec, void *vpElement) |
| void * | vpVecPushn (void *vpCtx, void *vpElement, apg_uint uiCount) |
| void * | vpVecPop (void *vpCtx) |
| void * | vpVecPopn (void *vpCtx, apg_uint uiCount) |
| void * | vpVecPopTo (void *vpCtx, apg_uint uiIndex) |
| void * | vpVecFront (void *vpCtx) |
| void * | vpVecBack (void *vpCtx) |
| void * | vpVecAt (void *vpCtx, apg_uint uiIndex) |
| apg_uint | uiVecBytes (void *vpCtx) |
| apg_uint | uiVecSize (void *vpCtx) |
| apg_uint | uiVecElementSize (void *vpCtx) |
| apg_uint | uiVecReallocations (void *vpCtx) |
| apg_uint | uiVecValidate (void *vpCtx) |
| void | vVecClear (void *vpCtx) |
| void | vExecuteRule (APG_CBDATA *spData, apg_uint uiId, apg_uint uiOffset) |
| void | vExecuteUdt (APG_CBDATA *spData, apg_uint uiId, apg_uint uiOffset) |
| void * | vpParserCtor (void *vpParserInit, PFN_ALERT pfnAlertHandler) |
| void | vParserDtor (void *vpCtx) |
| apg_uint | uiParserSyntaxInitCallbacks (void *vpCtx, APG_CALLBACK *spRuleCallbacks, APG_CALLBACK *spUdtCallbacks) |
| apg_uint | uiParserSyntaxAnalysis (void *vpCtx, apg_uint uiStartRule, const apg_achar *acpSrc, apg_uint uiSrcLen, void *vpData) |
| apg_uint | uiParserState (void *vpCtx, APG_PARSER_STATE *spState) |
| void | vParserAstInitNodes (void *vpCtx, apg_uint *uipRules, apg_uint *uipUdts) |
| void | vParserAstInitCallbacks (void *vpCtx, APG_CALLBACK *spRuleCallbacks, APG_CALLBACK *spUdtCallbacks) |
| apg_uint | uiParserAstTranslate (void *vpCtx, APG_CALLBACK *pfnRuleCallbacks, APG_CALLBACK *pfnUdtCallbacks, void *vpData) |
| apg_uint | uiParserStatsEnable (void *vpCtx, apg_uint uiEnable) |
| apg_uint | uiParserStatsGet (void *vpCtx, APG_PARSER_STATS *spStats, apg_uint *uipBufferSize) |
| apg_uint | uiParserTraceEnable (void *vpCtx, apg_uint uiEnable) |
| void | vParserTraceOp (void *vpCtx, apg_uint uiOpId, apg_uint uiEnable) |
| void | vParserTraceRule (void *vpCtx, apg_uint uiIndex, apg_uint uiEnable) |
| void | vParserTraceUdt (void *vpCtx, apg_uint uiIndex, apg_uint uiEnable) |
| void | vParserTraceRange (void *vpCtx, apg_uint uiBegin, apg_uint uiCount) |
| apg_uint | uiUdtLib_e_owsp (APG_CBDATA *spData) |
| apg_uint | uiUdtLib_u_wsp (APG_CBDATA *spData) |
| apg_uint | uiUdtLib_u_lineend (APG_CBDATA *spData) |
| apg_uint | uiUdtLib_e_any (APG_CBDATA *spData) |
| apg_uint | uiUdtLib_u_semi_comment (APG_CBDATA *spData) |
| apg_uint | uiUdtLib_u_cpp_comment (APG_CBDATA *spData) |
| apg_uint | uiUdtLib_u_c_comment (APG_CBDATA *spData) |
| apg_uint | uiUdtLib_u_alphanum (APG_CBDATA *spData) |
| apg_uint | uiUdtLib_u_alphanum_hyphen (APG_CBDATA *spData) |
| apg_uint | uiUdtLib_u_alphanum_under (APG_CBDATA *spData) |
| apg_uint | uiUdtLib_u_decnum (APG_CBDATA *spData) |
| apg_uint | uiUdtLib_u_hexnum (APG_CBDATA *spData) |
| apg_uint | uiUdtLib_u_quotedstring (APG_CBDATA *spData) |
| apg_uint | uiUdtLib_u_singlequotedstring (APG_CBDATA *spData) |
| apg_uint | uiUdtLib_u_doublequotedstring (APG_CBDATA *spData) |
Required header file for all APG-generated parsers. Contains important configuration macros and declarations of the API functions for the entire library.
APG Version 6.3 is the first version to allow for alphabet character codes larger than 8 bits wide. While variable, it is a "compile-time" variable and how it is controlled is dicussed here.
Alphabet character codes have the typedef apg_achar (the prefix apg_ or APG_ is often used here as a namespace.) Its definition is controlled with the #define macro _APG_CFG_ACHAR. The corresponding values of _APG_CFG_ACHAR and apg_achar are given here:
typedef unsigned char apg_achar; // _APG_CFG_ACHAR = 1 typedef unsigned short int apg_achar; // _APG_CFG_ACHAR = 2 typedef unsigned int apg_achar; // _APG_CFG_ACHAR = 4 typedef unsigned long int apg_achar; // _APG_CFG_ACHAR = 8 typedef unsigned char apg_achar; // (default) _APG_CFG_ACHAR undefined or defined as some value other than 1, 2, 4 or 8.
Similarly, the size of the unsigned integer, apg_uint, ubiquitously used by APG, can be controlled here as well. (Sizes less than 4 are risky and should be avoided. The full range is given here for completness.)
typedef unsigned char apg_uint; // _APG_CFG_UINT = 1 typedef unsigned short int apg_uint; // _APG_CFG_UINT = 2 typedef unsigned int apg_uint; // _APG_CFG_UINT = 4 typedef unsigned long int apg_uint; // _APG_CFG_UINT = 8 typedef unsigned int apg_uint; // (default) _APG_CFG_UINT undefined or defined as some value other than 1, 2, 4 or 8.
In this regard, also note that APG code rather fastidiously adheres to use of the following Hungarian notation for variable and function names:
prefix - type c - char cp - char* ac - apg_achar acp - apg_achar* ui - apg_uint uip - apg_uint* v - void vp - void* s - struct/union sp - pointer to struct/union
A second important set of configuration #define macros are _APG_CFG_DEBUG, _APG_CFG_TRACE and _APG_CFG_STATS.
_APG_CFG_DEBUG is really a legacy macro whose usefullness is minor. In Version 6.3 it serves only as a shorthand way to simultaneously define the other two, _APG_CFG_TRACE and _APG_CFG_STATS. (In previous versions it also defined a debug assertion macro. This has been removed because of some complications it caused in multi-threaded applications.)
_APG_CFG_TRACE must be defined in order to enable tracing. The reason for doing it this way is because tracing seriously impacts the parser's performance and forces the inclusion of the IO library functions into the libary. When this macro is not defined, the tracing code is not compiled or included in the library, resulting in not only better preformance but a significanly smaller footprint.
For simialar reasons, _APG_CFG_STATS must be defined to enable the collection of parsing statistics. Statistics collection can be vitally important when optimizing a parser, especially through the use of UDTs, but usually serves no purpose in a release or production version.
Definition in file Apg.h.
| #define APG_DISPLAY_MAX_LINE 128 |
| #define APG_INFINITE -1 |
| #define APG_UNDEFINED -1 |
| #define APG_VEC_ALLOC ((apg_uint)100) |
The default initial number of vector elements allocated.
| #define APG_VEC_ELEMENT ((apg_uint)1) |
| #define EMPTY ((apg_uint)2) |
The uiState value passed to callback functions by uiParserSyntaxAnalysis() to indicate the post-parse or upward traversal of a syntax tree node when an empty phrase has been matched.
| #define MATCH ((apg_uint)3) |
The uiState value passed to callback functions by uiParserSyntaxAnalysis() to indicate the post-parse or upward traversal of a syntax tree node when a non-empty phrase has been matched.
| #define max | ( | a, | |
| b | |||
| ) | (((a) > (b)) ? (a) : (b)) |
| #define min | ( | a, | |
| b | |||
| ) | (((a) < (b)) ? (a) : (b)) |
| #define NOMATCH ((apg_uint)1) |
The uiState value passed to callback functions by uiParserSyntaxAnalysis() to indicate the post-parse or upward traversal of a syntax tree node when no phrase has been matched.
| #define POST_AST ((apg_uint)5) |
The uiState value passed to callback functions by uiParserAstTranslate() to indicate the upward traversal of an AST node.
| #define PRE_AST ((apg_uint)4) |
The uiState value passed to callback functions by uiParserAstTranslate() to indicate the downward traversal of an AST node.
| #define PRE_PARSE ((apg_uint)0) |
The uiState value passed to callback functions by uiParserSyntaxAnalysis() to indicate the pre-parse or downward traversal of a syntax tree node.
| typedef unsigned char apg_achar |
| typedef apg_uint(* APG_CALLBACK) (APG_CBDATA *spData) |
Prototype of all user-written callback functions. It is the same for rule and UDT callback functions and for syntax and semantic analysis.
The interpretation of some data structure variables are somewhat different in each of the different cases. While this has been done for program development convenience, it can be confusing to the user in practice. Therefore, each of the four cases is descibed separately. Also, see Callbacks.c in the Demo example for explict examples how to write the callback functions in each case and initialize the Parser so that it will call them.
Only the uiState, uiPhraseLength and return values differ. For all other data variables refer to APG_CBDATA.
| uiState | one of PRE_PARSE, EMPTY, MATCH, NOMATCH indicating the parser state prior to phrase matching or the state following phrase matching |
| uiPhraseLength | input: (from Parser) the length of the matched phrase, if any output: (if overriding the Parser, ie. returning true) >= 0 for matched phrase, APG_UNDEFINED for no matched phrase |
| uiState | one of PRE_AST, POST_AST indicating before the AST node traversal (downward direction node visit) or after AST node traversal (upward directionnode visit). |
| uiPhraseLength | the length of the matched phrase. Note that a phrase has always been matched for this node or it wouldn't be in the AST. |
| uiState | PRE_PARSE only. UDTs are terminals and are only traversed once from the downward direction. |
| uiPhraseLength | user must set this to 0 if an empty phrase is matched, > 0 if a non-empty phrase is matched or APG_UNDEFINED if no phrase is matched. Note that only UDTs whose names begin with "e_" may return 0. If a "u-" named UDT returns 0 the Parser will fail. |
| uiState | one of PRE_AST or POST_AST indicating a pre-branch (downward direction) traversal or a post-branch (upward direction) traversal of the node. |
| uiPhraseLength | the length of the matched phrase. Note that a phrase has always been matched for this node or it wouldn't be in the AST. |
| typedef unsigned int apg_uint |
| typedef void(* PFN_ALERT) (unsigned int uiLine, const char *cpFile) |
Defines the function type for handling alerts with line number and file name.
| uiLine | the line number where the alert was generated. |
| cpFile | name of the file where the alert was generated. |
| typedef void(* PFN_ALERT_MSG) (unsigned int uiLine, const char *cpFile, const char *cpMsg) |
Defines the function type for handling alerts with line number, file name and a dexcriptive message.
| uiLine | the line number where the alert was generated. |
| cpFile | name of the file where the alert was generated. |
| cpMsg | a descriptive message for the alert that was generated. |
| typedef void*(* PFN_ALLOCATOR) (size_t) |
| typedef void(* PFN_DEALLOCATOR) (void *) |
| int apg_stricmp | ( | const char * | cpLhs, |
| const char * | cpRhs | ||
| ) |
Case-insensitive: compares two strings. The two strings are compared, character for character. NOTE: stricmp() is non-ANSI and therefore, not used
| cpLhs | pointer to the left of the two strings to compare |
| cpRhs | pointer to the right of the two strings to compare |
| apg_uint uiACharToString | ( | char * | cpChars, |
| apg_uint | uiCLen, | ||
| const apg_achar * | acpAChars, | ||
| apg_uint | uiALen | ||
| ) |
Converts a string of apg_achar characters to a null-terminated printable ASCII string. Non-printing characters are of the form: <xFF>. Brackets are used to distinguish the hex format from adjacent printing characters of "x" and "F", for example. The worst case scenario is that all translated characters will be of the form <xFF>, where sizeof(apg_achar) is 1 for example. To be safe, the cpChars buffer size, uiCLen, should be at least: uiALen * ((sizeof(apg_achar) * 2) + 3) plus 1 for terminating null. To get the exact size in advance, see uiACharToStringSize().
| cpChars | pointer to the buffer to receive the printable, 8-bit character string |
| uiCLen | length of the cpChars buffer |
| acpAChars | pointer the apg_achar character string |
| uiALen | the number of apg_achar characters |
Converts a string of alphabet characters to a null-terminated printable ASCII string. Non-printing characters are of the form: <xFF>. Brackets are used to distinguish the hex format from adjacent printing characters of "x" and "F", for example. The worst case scenario is that all translated characters will be of the form <xFF>, where sizeof(apg_achar) is 1 for example. To be safe, the cpChars buffer size, uiCLen, should be at least: uiALen * ((sizeof(apg_achar) * 2) + 3) plus 1 for terminating null. To get the exact size in advance, see uiACharToStringSize().
| cpChars | pointer to the buffer to receive the printable, 8-bit character string |
| uiCLen | length of the cpChars buffer |
| acpAChars | pointer the apg_achar character string |
| uiALen | the number of apg_achar characters |
Calculate the size of the string translated by uiACharToString()
| acpAChars | pointer the apg_achar character string |
| uiALen | the number of apg_achar characters |
| apg_uint uiMemCheckPoint | ( | void * | vpCtx | ) |
Returns a check point to the current state of the memory component. Can be used later to restore the current state.
| vpCtx | a Memory context handle previously returned from vpMemCtor(), or vpMemCtorA(). |
| apg_uint uiMemValidate | ( | void * | vpCtx | ) |
Validates a Memory context handle.
| vpCtx | a Memory context handle previously returned from vpMemCtor(), or vpMemCtorA(). |
| apg_uint uiParserAstTranslate | ( | void * | vpCtx, |
| APG_CALLBACK * | pfnRuleCallbacks, | ||
| APG_CALLBACK * | pfnUdtCallbacks, | ||
| void * | vpData | ||
| ) |
Translates an AST.
Translation is done via user-written callback functions assigned to the AST nodes. The callback functions may be defined with a previous call to vParserAstInitCallbacks() or may be assigned/overridden here. A "depth first" traversal of the AST is done. The callback function defined for each node is called twice. Once on the downward traversal (PRE_AST) of the node and again later on the upward traversal (POST_AST) of the node.
| vpCtx | pointer to a parser context, returned by vpParserCtor(). |
| pfnRuleCallbacks | pointer to an array of rule name callback function pointers. May be NULL. Will override any functions previously assigned in a call to vParserAstInitCallbacks(). |
| pfnUdtCallbacks | pointer to an array of UDT callback function pointers. May be NULL. Will override any functions previously assigned in a call to vParserAstInitCallbacks(). |
| vpData | user-defined data to be passed to the callback functions. May be NULL. Ignored by Parser. |
| apg_uint uiParserState | ( | void * | vpCtx, |
| APG_PARSER_STATE * | spState | ||
| ) |
Returns the parser state. Only meaningful after a call to uiParserSyntaxAnalysis().
| vpCtx | pointer to a parser context, returned by vpParserCtor(). |
| spState | pointer to a user-supplied APG_PARSER_STATE struct. |
Enables/disables collection of parser statistics.
Statistics gathering will negatively affect the parser's performance. Therefore, statistics gathering is disabled by default.
Note: a call to this function will have no affect unless _APG_CFG_STATS is defined.
| vpCtx | pointer to a parser context, returned by vpParserCtor(). |
| uiEnable | true if statistics gathering is to be enabled, false to disable (default.) |
| apg_uint uiParserStatsGet | ( | void * | vpCtx, |
| APG_PARSER_STATS * | spStats, | ||
| apg_uint * | uipBufferSize | ||
| ) |
Retrieve the statistics collected by uiParserSyntaxAnalysis().
| vpCtx | pointer to a parser context, returned by vpParserCtor(). |
| spStats | pointer to a user-supplied statistics data buffer. If NULL, only the required buffer size is returned. |
| uipBufferSize | pointer to the variable to receive the required buffer size. |
| apg_uint uiParserSyntaxAnalysis | ( | void * | vpCtx, |
| apg_uint | uiStartRule, | ||
| const apg_achar * | acpSrc, | ||
| apg_uint | uiSrcLen, | ||
| void * | vpData | ||
| ) |
Parses an input string of alphabet characters.
| vpCtx | pointer to a parser context, returned by vpParserCtor(). |
| uiStartRule | index of the grammar rule to be used as the start rule. 0 will always be the index of the first rule defined by the grammar. Good usage practice is to always use an index defined in the ProjectName.h header file generated by apg, the parser generator. This will be a #define of the form "RULE_PROJECTNAME_RULENAME". |
| acpSrc | pointer to the array of alphabet character codes defining the string to be parsed. |
| uiSrcLen | the number of alphabet characters in the input string. |
| vpData | optional pointer to user-defined data. This pointer, which may be NULL, will be passed on to the user-defined callback functions. It will be the vpUserData member of the APG_CBDATA structs passed to the callback functions. It is otherwise ignored by the parser. |
| apg_uint uiParserSyntaxInitCallbacks | ( | void * | vpCtx, |
| APG_CALLBACK * | spRuleCallbacks, | ||
| APG_CALLBACK * | spUdtCallbacks | ||
| ) |
Defined the syntax callback functions to the parser.
| vpCtx | pointer to a parser context, returned by vpParserCtor(). |
| spRuleCallbacks | an array of pointers to the rule callback functions. May be NULL. |
| spUdtCallbacks | an array of pointers to the UDT callback functions, if any. May be NULL if the grammar defines no UDTs. Each UDT defined in the grammar must have a callback function defined here. Otherwise, this function will return false and the parser syntax analysis will fail. |
Enables/disables tracing.
Tracing will negatively affect the parser's performance. Therefore, tracing is disabled by default.
If tracing is enabled, trace records will be printed to the standard output as the parser traverses the syntax tree. By default, records are printed only for rule and UDT nodes (RNM and UDT.) However, prior to parsing, tracing can be configured to trace or not trace any type of node. For tracing other than the default nodes:
Note: a call to this function will have no affect unless _APG_CFG_TRACE is defined.
| vpCtx | pointer to a parser context, returned by vpParserCtor(). |
| uiEnable | if true, enables tracing, if false, disables tracing |
| apg_uint uiUdtLib_e_any | ( | APG_CBDATA * | spData | ) |
| apg_uint uiUdtLib_e_owsp | ( | APG_CBDATA * | spData | ) |
Phrase recognizer for optional white space
Equivalent SABNF syntax:
WSP = *(TAB / SPACE) TAB = %d9 SPACE = %d32
NOTE: see UdtLib.c for the static function uiWsp() for more options. Line continuations and various types of comments may also be easily included as white space.
| spData | data struct passed to this function by the Parser |
| apg_uint uiUdtLib_u_alphanum | ( | APG_CBDATA * | spData | ) |
| apg_uint uiUdtLib_u_alphanum_hyphen | ( | APG_CBDATA * | spData | ) |
Phrase recognizer for an alphanumeric string, including hyphen.
Equivalent SABNF syntax:
ALPHANUM = ALPHA *(ALPHA / DIGIT / HYPHEN) ALPHA = %d65-90 / %d97-122 DIGIT = %d48-57 HYPHEN = %d45
| spData | data struct passed to this function by the Parser |
| apg_uint uiUdtLib_u_alphanum_under | ( | APG_CBDATA * | spData | ) |
Phrase recognizer for an alphanumeric string, including underscore.
Equivalent SABNF syntax:
ALPHANUM = ALPHA *(ALPHA / DIGIT / UNDER) ALPHA = %d65-90 / %d97-122 DIGIT = %d48-57 UNDER = %d95
| spData | data struct passed to this function by the Parser |
| apg_uint uiUdtLib_u_c_comment | ( | APG_CBDATA * | spData | ) |
Phrase recognizer for a C-style comment. Comment runs from "/ *" to "* /".
Equivalent SABNF syntax:
CCOMMENT = BEGIN *(!END ANY) END BEGIN = %d47.42 END = %d42.47 ANY = TAB / CR / LF / %d32-127 TAB = %d9 LF = %d10 CF = %d13
| spData | data struct passed to this function by the Parser |
| apg_uint uiUdtLib_u_cpp_comment | ( | APG_CBDATA * | spData | ) |
| apg_uint uiUdtLib_u_decnum | ( | APG_CBDATA * | spData | ) |
| apg_uint uiUdtLib_u_doublequotedstring | ( | APG_CBDATA * | spData | ) |
Phrase recognizer for a double-quoted string, a string beginning and ending with a double quote (").
Equivalent SABNF syntax:
DOUBLEQUOTE = %d34 *(%d9 / %d32-33 / %d35-127) %d34
| spData | data struct passed to this function by the Parser |
| apg_uint uiUdtLib_u_hexnum | ( | APG_CBDATA * | spData | ) |
| apg_uint uiUdtLib_u_lineend | ( | APG_CBDATA * | spData | ) |
Phrase recognizer for line ending. This is a "forgiving" line end allowing for the most commonly used values.
Equivalent SABNF syntax:
LINEEND = CR LF / CR / LF CR = %d13 LF = %d10
| spData | data struct passed to this function by the Parser |
| apg_uint uiUdtLib_u_quotedstring | ( | APG_CBDATA * | spData | ) |
Phrase recognizer for a quoted string, a string beginning and ending with a single (') or double (") quote.
Equivalent SABNF syntax:
QUOTEDSTRING = SINGLEQUOTE / DOUBLEQUOTE SINGLEQUOTE = %d39 *(%d9 / %d32-38 / %d40-127) %d39 DOUBLEQUOTE = %d34 *(%d9 / %d32-33 / %d35-127) %d34
| spData | data struct passed to this function by the Parser |
| apg_uint uiUdtLib_u_semi_comment | ( | APG_CBDATA * | spData | ) |
Phrase recognizer for a semicolon initialized comment. Comment runs from semicolon to end of line.
Equivalent SABNF syntax:
SEMICOMMENT = ";" ANY ANY = *(%d9 / %d32-127)
| spData | data struct passed to this function by the Parser |
| apg_uint uiUdtLib_u_singlequotedstring | ( | APG_CBDATA * | spData | ) |
Phrase recognizer for a single-quoted string, a string beginning and ending with a single quote (').
Equivalent SABNF syntax:
SINGLEQUOTE = %d39 *(%d9 / %d32-38 / %d40-127) %d39
| spData | data struct passed to this function by the Parser |
| apg_uint uiUdtLib_u_wsp | ( | APG_CBDATA * | spData | ) |
Phrase recognizer for required white space
Equivalent SABNF syntax:
WSP = 1*(TAB / SPACE) TAB = %d9 SPACE = %d32
NOTE: see UdtLib.c for the static function uiWsp() for more options. Line continuations and various types of comments may also be easily included as white space.
| spData | data struct passed to this function by the Parser |
| apg_uint uiVecBytes | ( | void * | vpCtx | ) |
Gets the number of bytes of data in use.
| vpCtx | a Vector component handle previously returned from vpVecCtor(). NULL or invalid handles are silently ignored. |
| apg_uint uiVecElementSize | ( | void * | vpCtx | ) |
Gets the size of a single element.
Note that:
uiVecBytes() = uiVecElementSize() * uiVecSize().
| vpCtx | a Vector component handle previously returned from vpVecCtor(). NULL or invalid handles are silently ignored. |
| apg_uint uiVecReallocations | ( | void * | vpCtx | ) |
Gets the number times the array memory has been reallocated.
| vpCtx | a Vector component handle previously returned from vpVecCtor(). |
| apg_uint uiVecSize | ( | void * | vpCtx | ) |
Gets the number of array elements in use.
| vpCtx | a Vector component handle previously returned from vpVecCtor(). NULL or invalid handles are silently ignored. |
| apg_uint uiVecValidate | ( | void * | vpCtx | ) |
Validates a Vector component handle.
| vpCtx | a Vector component handle previously returned from vpVecCtor(). NULL or invalid handles are silently ignored. |
Convert an ASCII, 8-bit character string to an apg_achar character string.
| acpAChars | pointer the destination or apg_achar character string |
| cpChars | pointer to the 8-bit character string to convert |
| uiLen | the number of characters to convert |
Convert an ASCII, 8-bit character string to an apg_achar character string.
| acpAChars | pointer to the apg_achar character string |
| cpChars | pointer to the 8-bit character string to convert |
| uiLen | the number of characters to convert |
| void vDefaultAlertHandler | ( | unsigned int | uiLine, |
| const char * | cpFile | ||
| ) |
| void vExecuteRule | ( | APG_CBDATA * | spData, |
| apg_uint | uiId, | ||
| apg_uint | uiOffset | ||
| ) |
To be called only from callback functions. Executes the specified rule as if it were the following node in the syntax tree.
| spData | the data supplied to the callback function by the parser |
| uiId | index of the rule to execute |
| uiOffset | offset into the input string of the first character of the phrase to match |
| void vExecuteUdt | ( | APG_CBDATA * | spData, |
| apg_uint | uiId, | ||
| apg_uint | uiOffset | ||
| ) |
To be called only from callback functions. Executes the specified UDT as if it were the following node in the syntax tree.
| spData | the data supplied to the callback function by the parser |
| uiId | index of the UDT to execute |
| uiOffset | offset into the input string of the first character of the phrase to match |
| void vMemClear | ( | void * | vpCtx | ) |
Frees all memory allocations from this Memory component.
| vpCtx | a Memory context handle previously returned from vpMemCtor(), or vpMemCtorA(). NULL pointers are silently ignored. |
| void vMemDtor | ( | void * | vpCtx | ) |
Destroys a Memory component.
| vpCtx | a Memory context handle previously returned from vpMemCtor(), or vpMemCtorA(). NULL pointers are silently ignored. |
| void vMemFree | ( | void * | vpCtx, |
| void * | vpData | ||
| ) |
De-allocates memory previously allocated with vpMemAlloc().
| vpCtx | a Memory context handle previously returned from vpMemCtor(), or vpMemCtorA(). NULL pointers are silently ignored. |
| vpData | pointer to the memory allocation to free. If NULL, silently ignored. |
| void vMemFreeToCheckPoint | ( | void * | vpCtx, |
| apg_uint | uiChk | ||
| ) |
Restores a previous state of the Memory component.
| vpCtx | a Memory context handle previously returned from vpMemCtor(), or vpMemCtorA(). NULL pointers are silently ignored. |
| uiChk | the previous state to restore. Must be from a previous call to uiMemCheckPoint(). |
| void vParserAstInitCallbacks | ( | void * | vpCtx, |
| APG_CALLBACK * | pfnRuleCallbacks, | ||
| APG_CALLBACK * | pfnUdtCallbacks | ||
| ) |
Defines which rule/UDT nodes are to be assigned callback functions in the AST.
These functions need only be assigned if translation with the function uiParserAstTranslate() is to be used.
| vpCtx | pointer to a parser context, returned by vpParserCtor(). |
| pfnRuleCallbacks | pointer to an array of rule name callback function pointers. May be NULL. |
| pfnUdtCallbacks | pointer to an array of UDT callback function pointers. May be NULL. |
Defines which rule/UDT names are to be kept as nodes in the Abstract Syntax Tree (AST).
Note that defining the nodes to be kept is a separate issue from defining which nodes have callback functions. The AST nodes may or may not be used for translation.
| vpCtx | pointer to a parser context, returned by vpParserCtor(). |
| uipRules | pointer to an array of integers defining the rule indexes of the rule name nodes to be kept in the AST. May be NULL. |
| uipUdts | pointer to an array of integers defining the UDT indexes of the UDT nodes to be kept in the AST. May be NULL. |
| void vParserDtor | ( | void * | vpCtx | ) |
Parser component destructor
| vpCtx | pointer to parser component context (returned from vpParserCtor()) |
Configures the types of operator nodes to trace.
| vpCtx | pointer to a parser context, returned by vpParserCtor(). |
| uiOpId | should be one of the following: APG_TRACE_ALL - trace all operator nodes APG_TRACE_TRG - trace the TRG nodes APG_TRACE_TBS - trace the TBS nodes APG_TRACE_TLS - trace the TLS nodes APG_TRACE_AND - trace the AND nodes APG_TRACE_NOT - trace the NOT nodes APG_TRACE_ALT - trace the ALT nodes APG_TRACE_CAT - trace the CAT nodes APG_TRACE_REP - trace the REP nodes APG_TRACE_RNM - trace the RNM nodes APG_TRACE_UDT - trace the UDT nodes APG_TRACE_COUNT - count the trace records only, none are printed |
| uiEnable | if true, the specified operators are printed, if false, not |
Configures the trace record range to print.
Trace records can be voluminous. This configuration can reduce the number printed to a managable set. In this context, it may be useful to first trace the parse with APG_TRACE_COUNT configured in vParserTraceOp().
| vpCtx | pointer to a parser context, returned by vpParserCtor(). |
| uiBegin | the record number of the first trace record to print |
| uiCount | the number of trace records to print |
Configures which rule names to trace. By default all rule names are traced.
| vpCtx | pointer to a parser context, returned by vpParserCtor(). |
| uiIndex | rule index of the rule name to trace |
| uiEnable | if true, the specified rule name records are printed, if false, not |
Configures which UDT names to trace. By default all UDT names are traced.
| vpCtx | pointer to a parser context, returned by vpParserCtor(). |
| uiIndex | UDT index of the UDT name to trace |
| uiEnable | if true, the specified UDT name records are printed, if false, not |
| void* vpMemAlloc | ( | void * | vpCtx, |
| apg_uint | uiBytes | ||
| ) |
Allocates memory.
| vpCtx | a Memory context handle previously returned from vpMemCtor(), or vpMemCtorA(). |
| uiBytes | the number of bytes of memory to allocate |
| void* vpMemCtor | ( | ) |
| void* vpMemCtorA | ( | PFN_ALLOCATOR | pfnAllocator, |
| PFN_DEALLOCATOR | pfnDeAllocator | ||
| ) |
Constructs a Memory component using a user-defined memory allocator and de-allocator.
| pfnAllocator | pointer to a user-defined memory allocator |
| pfnDeAllocator | pointer to a user-defined memory de-allocator |
| void* vpMemRealloc | ( | void * | vpCtx, |
| void * | vpData, | ||
| apg_uint | uiBytes | ||
| ) |
Re-allocates memory previously allocated with vpMemAlloc(). Can be used to up-size or down-size a memory allocation. Any previous data in the memory allocation is copied to the re-allocation.
| vpCtx | a Memory context handle previously returned from vpMemCtor(), or vpMemCtorA(). |
| vpData | pointer to the memory to be re-allocated. |
| uiBytes | number of re-allocated bytes of memory. |
| void* vpParserCtor | ( | void * | vpParserInit, |
| PFN_ALERT | pfnAlertHandler | ||
| ) |
Construct a new APG parser component.
| vpParserInit | the initialization data from APG |
| pfnAlertHandler | the alert handler, called on terminal errors. NULL for default alert handler. |
| void* vpVecAt | ( | void * | vpCtx, |
| apg_uint | uiIndex | ||
| ) |
Get a the indexed element in the array. The array is not altered.
| vpCtx | a Vector component handle previously returned from vpVecCtor(). |
| uiIndex | the index of the element to get (0-based) |
| void* vpVecBack | ( | void * | vpCtx | ) |
Get a the last element in the array. The array is not altered.
| vpCtx | a Vector component handle previously returned from vpVecCtor(). |
The Vector comonent constructor.
| vpMemCtx | a Memory component context handle, previously returned from vpMemCtor(). |
| uiElementSize | size, in bytes, of each array element. If 0, uses the default element size APG_VEC_ELEMENT. |
| uiInitialAlloc | number of elements to initially allocate. If 0, uses the default APG_VEC_ALLOC. |
| void* vpVecFront | ( | void * | vpCtx | ) |
Get a the first element in the array. The array is not altered.
| vpCtx | a Vector component handle previously returned from vpVecCtor(). |
| void* vpVecPop | ( | void * | vpCtx | ) |
Pops one element from the end of the array.
| vpCtx | a Vector component handle previously returned from vpVecCtor(). |
| void* vpVecPopn | ( | void * | vpCtx, |
| apg_uint | uiCount | ||
| ) |
Pops one or more elements from the end of the array.
| vpCtx | a Vector component handle previously returned from vpVecCtor(). |
| uiCount | the number of elements to pop. |
| void* vpVecPopTo | ( | void * | vpCtx, |
| apg_uint | uiIndex | ||
| ) |
Pops one or more elements from the end of the array.
| vpCtx | a Vector component handle previously returned from vpVecCtor(). |
| uiIndex | index of the first element to pop. Elements uiIndex and all higher indexed elements are popped. |
| void* vpVecPush | ( | void * | vpCtx, |
| void * | vpElement | ||
| ) |
Adds one element to the end of the array.
| vpCtx | a Vector component handle previously returned from vpVecCtor(). |
| vpElement | pointer to the element to add. If NULL, space for a new element is added but no data is copied to it. |
| void* vpVecPushn | ( | void * | vpCtx, |
| void * | vpElement, | ||
| apg_uint | uiCount | ||
| ) |
Adds one or more elements to the end of the array.
| vpCtx | a Vector component handle previously returned from vpVecCtor(). |
| vpElement | pointer to the first element to add. If NULL, space for the new elements is added but no data is copied to it. |
| uiCount | the number of elements to add. |
| void vVecClear | ( | void * | vpCtx | ) |
Clears all used elements in a Vector component.
This simply resents the current element pointer to zero. No data is actually deleted. No memory is released or re-allocated.
| vpCtx | a Vector component handle previously returned from vpVecCtor(). NULL or invalid handles are silently ignored. |
| void vVecDtor | ( | void * | vpCtx | ) |
The Vector component destructor. Frees all resouces allocated to this component.
| vpCtx | a Vector component handle previously returned from vpVecCtor(). NULL or invalid handles are silently ignored. |
1.8.17