Parser.c File Reference

The Parser component API. This is the heart of an APG parser. More...

#include "Apg.h"
#include "Grammar.h"
#include "Private.h"

Go to the source code of this file.

Macros
#define	PASSERT(cond)   if(!(cond)){spCtx->pfnAlertHandler(__LINE__, __FILE__);}

Functions
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)
void	vParserAstInitNodes (void *vpCtx, apg_uint *uipRules, apg_uint *uipUdts)
void	vParserAstInitCallbacks (void *vpCtx, APG_CALLBACK *pfnRuleCallbacks, APG_CALLBACK *pfnUdtCallbacks)
apg_uint	uiParserAstTranslate (void *vpCtx, APG_CALLBACK *pfnRuleCallbacks, APG_CALLBACK *pfnUdtCallbacks, void *vpData)
apg_uint	uiParserState (void *vpCtx, APG_PARSER_STATE *spState)
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)
void	vExecuteRule (APG_CBDATA *spData, apg_uint uiId, apg_uint uiOffset)
void	vExecuteUdt (APG_CBDATA *spData, apg_uint uiId, apg_uint uiOffset)

Detailed Description

The Parser component API. This is the heart of an APG parser.

Definition in file Parser.c.

Macro Definition Documentation

PASSERT

#define PASSERT

(

cond

)

if(!(cond)){spCtx->pfnAlertHandler(__LINE__, __FILE__);}

Used exclusively for terminal error detection and handling.

It is highly recommended that the user write his own alert handler and install it at parser construction time. The default alert handler simply exits.

See also

vpParserCtor()

Definition at line 40 of file Parser.c.

Function Documentation

uiParserAstTranslate()

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.

Parameters

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.

See also

vpParserCtor()

vParserAstInitCallbacks()

PRE_AST

POST_AST

Returns

the number of callback functions defined for which no AST node records have been collected. If non-zero, this is a warning user may want to re-define some of the callback functions

Definition at line 361 of file Parser.c.

uiParserState()

apg_uint uiParserState	(	void *	vpCtx,
		APG_PARSER_STATE *	spState
	)

Returns the parser state. Only meaningful after a call to uiParserSyntaxAnalysis().

Parameters

vpCtx	pointer to a parser context, returned by vpParserCtor().
spState	pointer to a user-supplied APG_PARSER_STATE struct.

See also

vpParserCtor()

uiParserSyntaxAnalysis()

Returns

true if the parser state uiSuccess is true. false otherwise.

Definition at line 379 of file Parser.c.

uiParserStatsEnable()

apg_uint uiParserStatsEnable	(	void *	vpCtx,
		apg_uint	uiEnable
	)

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.

Parameters

vpCtx	pointer to a parser context, returned by vpParserCtor().
uiEnable	true if statistics gathering is to be enabled, false to disable (default.)

See also

vpParserCtor()

uiParserStatsGet()

_APG_CFG_STATS in the configuration of Apg.h.

Returns

true if _APG_CFG_STATS has been defined in Apg.h, false otherwise.

Definition at line 403 of file Parser.c.

uiParserStatsGet()

apg_uint uiParserStatsGet	(	void *	vpCtx,
		APG_PARSER_STATS *	spStats,
		apg_uint *	uipBufferSize
	)

Retrieve the statistics collected by uiParserSyntaxAnalysis().

Parameters

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.

See also

vpParserCtor()

uiParserStatsEnable()

vDisplayOperatorStats()

vDisplayRuleStats()

Returns

true if _APG_CFG_STATS has been defined in Apg.h, false otherwise.

Definition at line 422 of file Parser.c.

uiParserSyntaxAnalysis()

apg_uint uiParserSyntaxAnalysis	(	void *	vpCtx,
		apg_uint	uiStartRule,
		const apg_achar *	acpSrc,
		apg_uint	uiSrcLen,
		void *	vpData
	)

Parses an input string of alphabet characters.

Parameters

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.

See also

vpParserCtor()

uiParserState()

APG_CALLBACK

APG_CBDATA

Returns

true if the parser accepted all characters in the input string. false otherwise. It is the same as the uiSuccess variable in the APG_PARSER_STATE struct.

Definition at line 228 of file Parser.c.

uiParserSyntaxInitCallbacks()

apg_uint uiParserSyntaxInitCallbacks	(	void *	vpCtx,
		APG_CALLBACK *	spRuleCallbacks,
		APG_CALLBACK *	spUdtCallbacks
	)

Defined the syntax callback functions to the parser.

Parameters

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.

See also

vpParserCtor()

uiParserSyntaxAnalysis()

Returns

true if all UDTs defined in the grammar have a callback function defined here. false otherwise.

Definition at line 187 of file Parser.c.

uiParserTraceEnable()

apg_uint uiParserTraceEnable	(	void *	vpCtx,
		apg_uint	uiEnable
	)

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:

See also

vParserTraceOp()

vParserTraceRule()

vParserTraceUdt()

vParserTraceRange()

Note: a call to this function will have no affect unless _APG_CFG_TRACE is defined.

Parameters

vpCtx	pointer to a parser context, returned by vpParserCtor().
uiEnable	if true, enables tracing, if false, disables tracing

See also

vpParserCtor()

uiParserStatsEnable()

Returns

true if _APG_CFG_TRACE has been defined in Apg.h, false otherwise.

Definition at line 452 of file Parser.c.

vExecuteRule()

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.

Parameters

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

See also

APG_CALLBACK

Definition at line 537 of file Parser.c.

vExecuteUdt()

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.

Parameters

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

See also

APG_CALLBACK

Definition at line 559 of file Parser.c.

vParserAstInitCallbacks()

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.

Parameters

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.

See also

vpParserCtor()

uiParserAstTranslate()

Definition at line 316 of file Parser.c.

vParserAstInitNodes()

void vParserAstInitNodes	(	void *	vpCtx,
		apg_uint *	uipRules,
		apg_uint *	uipUdts
	)

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.

Parameters

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.

See also

vpParserCtor()

uiParserAstTranslate()

uiAstToXml()

Definition at line 283 of file Parser.c.

vParserDtor()

void vParserDtor

(

void *

vpCtx

)

Parser component destructor

Parameters

vpCtx

pointer to parser component context (returned from vpParserCtor())

See also

vpParserCtor()

Definition at line 168 of file Parser.c.

vParserTraceOp()

void vParserTraceOp	(	void *	vpCtx,
		apg_uint	uiOpId,
		apg_uint	uiEnable
	)

Configures the types of operator nodes to trace.

Parameters

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

See also

vpParserCtor()

uiParserTraceEnable()

Definition at line 482 of file Parser.c.

vParserTraceRange()

void vParserTraceRange	(	void *	vpCtx,
		apg_uint	uiBegin,
		apg_uint	uiCount
	)

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().

Parameters

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

See also

vpParserCtor()

uiParserTraceEnable()

Definition at line 524 of file Parser.c.

vParserTraceRule()

void vParserTraceRule	(	void *	vpCtx,
		apg_uint	uiIndex,
		apg_uint	uiEnable
	)

Configures which rule names to trace. By default all rule names are traced.

Parameters

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

See also

vpParserCtor()

uiParserTraceEnable()

Definition at line 495 of file Parser.c.

vParserTraceUdt()

void vParserTraceUdt	(	void *	vpCtx,
		apg_uint	uiIndex,
		apg_uint	uiEnable
	)

Configures which UDT names to trace. By default all UDT names are traced.

Parameters

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

See also

vpParserCtor()

uiParserTraceEnable()

Definition at line 508 of file Parser.c.

vpParserCtor()

void* vpParserCtor	(	void *	vpParserInit,
		PFN_ALERT	pfnAlertHandler
	)

Construct a new APG parser component.

Parameters

vpParserInit	the initialization data from APG
pfnAlertHandler	the alert handler, called on terminal errors. NULL for default alert handler.

See also

vParserDtor()

Returns

pointer to a parser component context.

Definition at line 58 of file Parser.c.