Declarations of all APG utility functions. More...

#include "Apg.h"
#include "Private.h"
#include "Grammar.h"
#include <stdio.h>
#include <time.h>

Typedefs
typedef unsigned long int	printf_uint

Functions
apg_uint	uiGetFileSize (const char *cpFileName)

apg_uint	uiGetFile (const char cpFileName, void vpBuffer)

apg_uint	uiWriteFile (const char cpFileName, void vpData, apg_uint uiDataLen)

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

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

void *	vpTimerCtor (void *vpMemCtx)

void	vTimerDtor (void *vpCtx)

apg_uint	uiTimerStart (void *vpCtx)

apg_uint	uiTimerStop (void *vpCtx)

double	dTimerStartTime (void *vpCtx, double dConversion)

double	dTimerStopTime (void *vpCtx, double dConversion)

double	dTimerDuration (void *vpCtx, double dConversion)

apg_uint	uiTimerRates (void vpCtx, double dpRates, apg_uint uiLen, double dConversion)

void	vDisplayMemStats (void *vpCtx)

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)

apg_uint	uiAstToXml (FILE spOut, void vpParserCtx)

void	vDisplayOpcodes (void *vpCtx)

void	vDisplayAstRecords (FILE spOut, void vpParserCtx)

void	vDisplayRules (void *vpParserCtx)

void	vDisplayUdts (void *vpParserCtx)

const char *	cpState2String (apg_uint uiState)

const char *	cpBoolean2String (apg_uint uiBool)

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

void	vLicenseNotice (FILE *spFile)

void	vDisplayTypeSizes (FILE *spOut)

void	vDisplayGrammarInfo (FILE spOut, void vpHdr)

Detailed Description

Declarations of all APG utility functions.

APG utilites are in three main categories. There are a few file helpers for commonly used file functions, a "timer component" used in the timing studies in the examples and display utilities for displaying the parsing results.

Definition in file ApgUtilities.h.

Typedef Documentation

◆ printf_uint

typedef unsigned long int printf_uint

printf_uint is used uniformly in all printf() statemenst to convert integer data to unsigned ints. This way the %lu format can be used regardless of the current size of apg_uint.

Definition at line 52 of file ApgUtilities.h.

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.

◆ dTimerDuration()

double dTimerDuration	(	void *	vpCtx,
		double	dConversion
	)

The timed duration in specified units.

Parameters

vpCtx	context handle previously returned from vpTimerCtor()
dConversion	a time units conversion factor. Use 1 for seconds, 1000 for milliseconds, etc.

The following #define macros are available:

APG_TIMER_SEC      - return value in seconds
APG_TIMER_MILLISEC - return value in milliseconds
APG_TIMER_MICROSEC - return value in microseconds

See also: vpTimerCtor(); uiTimerStart(); uiTimerStop()

Returns: the timed duration in units specified by the dConversion parameter

Definition at line 237 of file timer.c.

◆ dTimerStartTime()

double dTimerStartTime	(	void *	vpCtx,
		double	dConversion
	)

Get the start time in specified units.

Parameters

vpCtx	context handle previously returned from vpTimerCtor()
dConversion	a time units conversion factor. Use 1 for seconds, 1000 for milliseconds, etc.

The following #define macros are available:

APG_TIMER_SEC      - return value in seconds
APG_TIMER_MILLISEC - return value in milliseconds
APG_TIMER_MICROSEC - return value in microseconds

See also: vpTimerCtor(); uiTimerStart(); uiTimerStop()

Returns: the start time in units specified by the dConversion parameter

Definition at line 185 of file timer.c.

◆ dTimerStopTime()

double dTimerStopTime	(	void *	vpCtx,
		double	dConversion
	)

Get the stop time in specified units.

Parameters

vpCtx	context handle previously returned from vpTimerCtor()
dConversion	a time units conversion factor. Use 1 for seconds, 1000 for milliseconds, etc.

The following #define macros are available:

APG_TIMER_SEC      - return value in seconds
APG_TIMER_MILLISEC - return value in milliseconds
APG_TIMER_MICROSEC - return value in microseconds

See also: vpTimerCtor(); uiTimerStart(); uiTimerStop()

Returns: the stop time in units specified by the dConversion parameter

Definition at line 211 of file timer.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.

◆ uiGetFile()

apg_uint uiGetFile	(	const char *	cpFileName,
		void *	vpBuffer
	)

Read an entire file into memory.

Parameters

cpFileName	the name of the file to get
vpBuffer	pointer to the memory area to read the file into.

See also: uiGetFileSize()

Returns: the file size on success, 0 if the file does not exist

Definition at line 71 of file Files.c.

◆ uiGetFileSize()

apg_uint uiGetFileSize ( const char * cpFileName )

Get the size of a file in bytes.

Useful when dynamically allocating a buffer for reading the entire file.

Parameters

cpFileName the name of the file whose size to get

See also: uiGetFile()

Returns: the file size on success, 0 if the file does not exist

Definition at line 40 of file Files.c.

◆ uiTimerRates()

apg_uint uiTimerRates	(	void *	vpCtx,
		double *	dpRates,
		apg_uint	uiLen,
		double	dConversion
	)

Convert any value into a rate (value/duration).

eg. If the parser parsed uiCharacters characters between the start and stop times, uiTimerRates(vpCtx, &uiCharacters, 1, APG_TIMER_MILLISEC) would overrite uiCharacters with uiCharacters/duration in the specified units.

Parameters

vpCtx	context handle previously returned from vpTimerCtor()
dpRates	an array of values to convert to rates
uiLen	the number of values in the array.
dConversion	a time units conversion factor. Use 1 for seconds, 1000 for milliseconds, etc.

The following #define macros are available:

APG_TIMER_SEC      - return value in seconds
APG_TIMER_MILLISEC - return value in milliseconds
APG_TIMER_MICROSEC - return value in microseconds

See also: vpTimerCtor(); uiTimerStart(); uiTimerStop()

Returns: true on success, false if the context handle vpCtx is invalid or the duration of the timer is 0.0.
The rates overwrite the original values in the dpRates array.

Definition at line 151 of file timer.c.

◆ uiTimerStart()

apg_uint uiTimerStart ( void * vpCtx )

Start the timer.

Parameters

vpCtx context handle previously returned from vpTimerCtor()

See also: vpTimerCtor(); uiTimerStop()

Returns: the start time in internal clock units

Definition at line 96 of file timer.c.

◆ uiTimerStop()

apg_uint uiTimerStop ( void * vpCtx )

Stop the timer.

Parameters

vpCtx context handle previously returned from vpTimerCtor()

See also: vpTimerCtor(); uiTimerStart()

Returns: the stop time in internal clock units

Definition at line 117 of file timer.c.

◆ uiWriteFile()

apg_uint uiWriteFile	(	const char *	cpFileName,
		void *	vpData,
		apg_uint	uiDataLen
	)

Write data into a file. If the file already exists its data is overwritten.

Parameters

cpFileName	the name of the file to write
vpData	pointer to the memory area to write.
uiDataLen	the number of bytes of data to write

Returns: the number of bytes written. If not equal to uiDataLen an error occurred.

Definition at line 108 of file Files.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.

◆ vDisplayMemStats()

void vDisplayMemStats ( void * vpCtx )

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

◆ vDisplayRules()

void vDisplayRules ( void * vpParserCtx )

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

◆ vDisplayUdts()

void vDisplayUdts ( void * vpParserCtx )

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

◆ vpTimerCtor()

void* vpTimerCtor ( void * vpMemCtx )

Constructs a timer component.

Parameters

vpMemCtx pointer to a Memory component

See also: Memory.c; vpMemCtor()

Returns: a context handle

Definition at line 51 of file timer.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.

◆ vTimerDtor()

void vTimerDtor ( void * vpCtx )

Destroys a timer component.

Parameters

vpCtx context handle previously returned from vpTimerCtor()

See also: vpTimerCtor()

Definition at line 80 of file timer.c.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ printf_uint

Function Documentation

◆ cpBoolean2String()

◆ cpState2String()

◆ dTimerDuration()

◆ dTimerStartTime()

◆ dTimerStopTime()

◆ uiAstToXml()

◆ uiGetFile()

◆ uiGetFileSize()

◆ uiTimerRates()

◆ uiTimerStart()

◆ uiTimerStop()

◆ uiWriteFile()

◆ vDisplayAscii()

◆ vDisplayAstRecords()

◆ vDisplayGrammarInfo()

◆ vDisplayMemStats()

◆ vDisplayOpcodes()

◆ vDisplayOperatorStats()

◆ vDisplayParserState()

◆ vDisplayRules()

◆ vDisplayRuleStats()

◆ vDisplayState()

◆ vDisplayTypeSizes()

◆ vDisplayUdts()

◆ vLicenseNotice()

◆ vpTimerCtor()

◆ vTerminalAlert()

◆ vTerminalAlertMsg()

◆ vTimerDtor()