A number of useful display functions. More...

#include "ApgUtilities.h"

Functions
void	vDisplayAscii (FILE spOut, const char cpSrc, apg_uint uiSrcLen)

void	vDisplayOpcodes (void *vpCtx)

void	vDisplayAstRecords (FILE spOut, void vpParserCtx)

void	vDisplayTypeSizes (FILE *spOut)

void	vDisplayOperatorStats (FILE spOut, APG_PARSER_STATS spStats)

void	vDisplayRuleStats (FILE spOut, APG_PARSER_STATS spStats, const char *cpType)

void	vDisplayParserState (FILE spOut, void vpParserCtx)

void	vDisplayState (FILE spOut, APG_PARSER_STATE spState)

void	vDisplayGrammarInfo (FILE spOut, void vpHdr)

void	vLicenseNotice (FILE *spFile)

apg_uint	uiAstToXml (FILE spOut, void vpParserCtx)

void	vTerminalAlert (unsigned int uiLine, const char *cpFile)

void	vTerminalAlertMsg (unsigned int uiLine, const char cpFile, const char cpMsg)

const char *	cpState2String (apg_uint uiState)

const char *	cpBoolean2String (apg_uint uiBool)

Detailed Description

A number of useful display functions.

Definition in file Utilities.c.

Function Documentation

◆ cpBoolean2String()

const char* cpBoolean2String ( apg_uint uiBool )

Translate a true/false value into a readable ASCII string.

Parameters

uiBool the true/false value: 1 (eg. APG_TRUE) is interpreted as true, all other values as false.

Returns: pointer to the string "TRUE" for true, "FALSE" for false.

Definition at line 605 of file Utilities.c.

◆ cpState2String()

const char* cpState2String ( apg_uint uiState )

Translates the Parser state into a readable ASCII string.

Parameters

uiState the Parse state.

Returns

pointer to the string:

"PRE_PARSE"
"EMPTY"
"MATCH"
"NOMATCH"
"PRE_AST"
"POST_AST"
"UNKNOWN" - if uiState is not a valid state value.

Definition at line 590 of file Utilities.c.

◆ uiAstToXml()

apg_uint uiAstToXml	(	FILE *	spOut,
		void *	vpParserCtx
	)

Displays the Abstract Syntax Tree (AST) in XML format to the specified file.

The AST has one node for each rule/UDT name. For example the rule named "Hello" with grammar index "1" would have the structure:

<node name="Hello" id="1">
 <phrase offset="0" length="5">Hello</phrase>
</node><!-- name="Hello" id="1" -->

That is an open <node> tag, defining the AST node, a <phrase> tag defining the matched phrase and a close </node> tag. <node> tags will be nested for recursion.

The <phrase> tag has attributes "offset=" giving the offset into the input string to the first character of the phrase, "length=" giving the phrase length and the tag text is the matched phrase.

There will always be a <root> tag to act as the mandatory parent of all <node> tags. The <root> tag will have attributes "lines=", giving the total number of lines in the AST and "nodes=" giving the number of nodes in the AST.

Parameters

spOut	the FILE to write the display to. If NULL, uses stdout.
vpParserCtx	context handle of the Parser, previously returned from vpParserCtor().

See also: vpParserCtor()

Returns: true if successful, false otherwise

Definition at line 479 of file Utilities.c.

◆ vDisplayAscii()

void vDisplayAscii	(	FILE *	spOut,
		const char *	cpSrc,
		apg_uint	uiSrcLen
	)

Displays a grammar (or any ASCII file of lines) with line and character number information.

Displays the grammar with 1-based line numbers and 0-based character offsets and lengths. Non-ASCII characters are displayed in hex as \xFF, for example.

Parameters

spOut	the FILE to write the display to. If NULL, uses stdout.
cpSrc	pointer to the ASCII data to display
uiSrcLen	the number of bytes to display

Definition at line 62 of file Utilities.c.

◆ vDisplayAstRecords()

void vDisplayAstRecords	(	FILE *	spOut,
		void *	vpParserCtx
	)

Displays the Abstract Syntax Tree (AST) records.

There is one record for each rule/UDT node visit. That means two records for each node: one for the PRE_AST or downward direction visit and one for the POST_AST or upward direction visit.

Parameters

spOut	the FILE to write the display to. If NULL, uses stdout.
vpParserCtx	context handle of the Parser, previously returned from vpParserCtor().

See also: vpParserCtor()

Definition at line 183 of file Utilities.c.

◆ vDisplayGrammarInfo()

void vDisplayGrammarInfo	(	FILE *	spOut,
		void *	vpHdr
	)

Displays information about a grammar.

Parameters

spOut	the FILE to write the display to. If NULL, uses stdout.
vpHdr	pointer to the grammar-generated data.

For a C-language parser this will be vpParserInit_ProjectName
For a C++ parser this will be the class data member m_vpParserInit.

Definition at line 409 of file Utilities.c.

◆ vDisplayOpcodes()

void vDisplayOpcodes ( void * vpCtx )

Displays a Parser's opcodes in a human-readable format.

Parameters

vpCtx context handle of the Parser, previously returned from vpParserCtor().

See also: vpParserCtor()

Definition at line 153 of file Utilities.c.

◆ vDisplayOperatorStats()

void vDisplayOperatorStats	(	FILE *	spOut,
		APG_PARSER_STATS *	spStats
	)

Displays statistics for all node types.

Parameters

spOut	the FILE to write the display to. If NULL, uses stdout.
spStats	pointer to the statistics data return from uiParserStatsGet().

See also: uiParserStatsEnable(); uiParserStatsGet()

Definition at line 296 of file Utilities.c.

◆ vDisplayParserState()

void vDisplayParserState	(	FILE *	spOut,
		void *	vpParserCtx
	)

Displays the Parser's state directly from the Parser.

Parameters

spOut	the FILE to write the display to. If NULL, uses stdout.
vpParserCtx	context handle of the Parser, previously returned from vpParserCtor().

See also: vpParserCtor()

Definition at line 373 of file Utilities.c.

◆ vDisplayRuleStats()

void vDisplayRuleStats	(	FILE *	spOut,
		APG_PARSER_STATS *	spStats,
		const char *	cpType
	)

Displays statistics for the rule and UDT nodes.

Parameters

spOut	the FILE to write the display to. If NULL, uses stdout.
spStats	pointer to the statistics data return from uiParserStatsGet().
cpType	indicates the type of rule/UDT listing

cpType = "alpha" - list the rule/UDT nodes alphabetically (rule/UDT nodes with 0 hits are omitted)
cpType = "count" - list the rule/UDT nodes descending numerically on hit count (rule/UDT nodes with 0 hits are omitted)
cpType = NULL or other, list the rule/UDT nodes by grammar index
See also
uiParserStatsEnable()

uiParserStatsGet()

Definition at line 338 of file Utilities.c.

◆ vDisplayState()

void vDisplayState	(	FILE *	spOut,
		APG_PARSER_STATE *	spState
	)

Displays the Parser state.

Parameters

spOut	the FILE to write the display to. If NULL, uses stdout.
spState	state data, previously returned from uiParserState().

See also: uiParserState()

Definition at line 391 of file Utilities.c.

◆ vDisplayTypeSizes()

void vDisplayTypeSizes ( FILE * spOut )

Displays size, in bytes, for each of the four basic C unsigned types (char, short, int, long) as well as for apg_uint and apg_achar.

Useful to check the type sizes for a specific OS and to verify the APG type sizes for apg_uint and apg_achar.

Parameters

spOut the FILE to write the display to. If NULL, uses stdout.

Definition at line 279 of file Utilities.c.

◆ vLicenseNotice()

void vLicenseNotice ( FILE * spFile )

Displays the APG license notice.

Parameters

spFile the FILE to write the display to. If NULL, uses stdout.

Definition at line 442 of file Utilities.c.

◆ vTerminalAlert()

void vTerminalAlert	(	unsigned int	uiLine,
		const char *	cpFile
	)

An alert handler which prints the location where the alert was generated and exits the application.

Note: this is the normal way that APG reports terminal errors. It is assumed that the user is a sufficiently able programmer to look at the code location and see what the problem is.

Parameters

uiLine	the line number where the alert was generated
cpFile	the name of the file where the alert was generated.

Definition at line 557 of file Utilities.c.

◆ vTerminalAlertMsg()

void vTerminalAlertMsg	(	unsigned int	uiLine,
		const char *	cpFile,
		const char *	cpMsg
	)

An alert handler which prints the location where the alert was generated, a user-defined message and exits the application.

Parameters

uiLine	the line number where the alert was generated
cpFile	the name of the file where the alert was generated.
cpMsg	the message that was generated by the function that issued the alert, presumably giving some indication of what the problem was.

Definition at line 569 of file Utilities.c.

Functions

Detailed Description

Function Documentation

◆ cpBoolean2String()

◆ cpState2String()

◆ uiAstToXml()

◆ vDisplayAscii()

◆ vDisplayAstRecords()

◆ vDisplayGrammarInfo()

◆ vDisplayOpcodes()

◆ vDisplayOperatorStats()

◆ vDisplayParserState()

◆ vDisplayRuleStats()

◆ vDisplayState()

◆ vDisplayTypeSizes()

◆ vLicenseNotice()

◆ vTerminalAlert()

◆ vTerminalAlertMsg()