Public header file for the APG API suite of functions. More...

#include <limits.h>
#include "../utilities/utilities.h"

Include dependency graph for api.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	api_attr
	The recursive attributes of a single SABNF grammra rule. More...

struct	pppt_size
	Size information for the Partially-Predictive Parsing Tables (PPPT) data. More...

Functions
Construction/Destruction
void *	vpApiCtor (exception *spEx)
	Construct an API component context (object). More...

void	vApiDtor (void *vpCtx)
	The API component destructor. More...

abool	bApiValidate (void *vpCtx)
	Validates an API context pointer. More...

void *	vpApiGetErrorLog (void *vpCtx)
	Get the internal message log. More...

Input - Getting the Grammar Source
This suite of functions is concerned with the input SABNF grammar file. Facilities are available for files, strings, clearing for a new grammar and display of the input grammar.
void	vApiInClear (void *vpCtx)
	Clears the input and related memory. More...

const char *	cpApiInFile (void vpCtx, const char cpFileName)
	Reads an SABNF grammar byte stream from a file. More...

const char *	cpApiInString (void vpCtx, const char cpString)
	Reads an SABNF grammar byte stream from a string. More...

void	vApiInValidate (void *vpCtx, abool bStrict)
	Scans the input SABNF grammar for invalid characters and line ends. More...

void	vApiInToAscii (void vpCtx, const char cpFileName)
	Display the input lines with line numbers and character offsets. More...

void	vApiInToHtml (void vpCtx, const char cpFileName, const char *cpTitle)
	Display the input lines with line numbers and character offsets. More...

Syntax Analysis of the Grammar
The syntax is validated and if valid an Abstract Syntax Tree (AST)is generated.
void	vApiSyntax (void *vpCtx, abool bStrict)
	Parse the SABNF grammar to validate that the grammar structure is valid. More...

Semantic Analysis of the Grammar
The AST from the syntax phase is translated into specific opcode. That is, for each node in the syntax tree, the grammar-specific information necessary to execute the node operations are generated.
void	vApiOpcodes (void *vpCtx)
	Parse the SABNF grammar and translate its AST into opcodes for all the rules. More...

void	vApiOpcodesToAscii (void vpCtx, const char cpFileName)
	Display all opcodes in human-readable format. More...

void	vApiRulesToAscii (void vpCtx, const char cpMode, const char *cpFileName)
	Display rules and UDTs in human-readable format in ASCII format. More...

void	vApiRulesToHtml (void vpCtx, const char cpFileName)
	Display the grammar rules in human-readable, HTML format. More...

The Rule Attributes
Evaluate the rule attributes (e.g. left recursive, cyclic) to identify any fatal aspects or attributes of the grammar.
abool	bApiAttrs (void *vpCtx)
	Computes the grammar's attributes. More...

void	vApiAttrsToAscii (void vpCtx, const char cpMode, const char *cpFileName)
	Display all rule attributes. More...

void	vApiAttrsErrorsToAscii (void vpCtx, const char cpMode, const char *cpFileName)
	Display all rule attributes with errors. More...

Evaluate the Partially-Predictive Parsing Tables (PPPT)
PPPT maps can significantly reduce the number of node visits necessary for a traversal of the parse tree. The PPPT maps are generated here.
void	vApiPppt (void vpCtx, char *cppProtectedRules, aint uiProtectedRules)
	Compute the Partially-Predictive Parsing Tables. More...

void	vApiPpptSize (void vpCtx, pppt_size spSize)
	Compute the size of the PPPT maps and the number of bytes for the entire table. More...

One-Step Generation
Composite functions which will perform all steps of generation with a single function call. grammar input & character validation syntax validation semantic validation and opcode generation attribute validation PPPT map generation
void	vApiFile (void vpCtx, const char cpFileName, abool bStrict, abool bPppt)
	Quicky way to generate a parser from a grammar file. More...

void	vApiString (void vpCtx, const char cpString, abool bStrict, abool bPppt)
	Quicky way to generate a parser from a grammar string. More...

Parser Generation
Generator output can be in two forms. A pair of grammar files can be generated from which a parser can be constructed. Or a parser object, completely independent of the API, can be generated.
void	vApiOutput (void vpCtx, const char cpOutput)
	Generate a source and header file that can be used to construct a parser for the specified SABNF grammar. More...

void *	vpApiOutputParser (void *vpCtx)
	Generate a parser object directly from the specified SABNF grammar. More...

Detailed Description

Public header file for the APG API suite of functions.

The command line parser generator, apg, is built from an Application Programming Interface (API) object. This object is available for custom applications to use as well. It's primary documentation is here and in api.c but it has a lot of code which is spread over a number of files in the api directory. Refer to them here:

Definition in file api.h.

Function Documentation

◆ bApiAttrs()

abool bApiAttrs ( void * vpCtx )

Computes the grammar's attributes.

For each rule in the SABNF grammar the rule attributes are:

left - if true, rule is left recursive (fatal)
nested - if true, rule is nested recursive (is not a regular expression)
right - if true, rule is right recursive
cyclic - if true, at least one branch has no terminal nodes (fatal)
empty - if true, the rule matches the empty string
finite - if false, the rule only matches infinite strings (fatal)

Parameters

vpCtx	- Pointer to an API context previously returned from vpApiCtor().
uipCount	- Pointer to an integer. Set to the number (count) of attributes. This will always be the number of rules in the grammar. May be NULL if no count is wanted.

Returns: Returns a pointer to an array of api_attr structures, one for each rule in the grammar. Throws exception on fatal error.

Definition at line 79 of file attributes.c.

◆ bApiValidate()

abool bApiValidate ( void * vpCtx )

Validates an API context pointer.

Parameters

vpCtx - Pointer to an API context previously returned from vpApiCtor().

Returns: True is the context pointer is valid, false otherwise.

Definition at line 104 of file api.c.

◆ cpApiInFile()

const char* cpApiInFile	(	void *	vpCtx,
		const char *	cpFileName
	)

Reads an SABNF grammar byte stream from a file.

May be called multiple times. Successive calls will append data to the previous grammar result. May be mixed with calls to cpApiInString().

Parameters

[in]	vpCtx	- Pointer to an API context previously returned from vpApiCtor().
[in]	cpFileName	- Name of the file to read.

Returns: Pointer to the cumulative, null-terminated SABNF grammar string.

Definition at line 117 of file input.c.

◆ cpApiInString()

const char* cpApiInString	(	void *	vpCtx,
		const char *	cpString
	)

Reads an SABNF grammar byte stream from a string.

May be called multiple times. Successive calls will append data to the previous SABNF grammar result. May be mixed with calls to cpApiInFile().

Parameters

[in]	vpCtx	- Pointer to an API context previously returned from vpApiCtor().
[in]	cpString	- Pointer to the string to read.

Returns: Pointer to the cumulative, null-terminated SABNF grammar string.

Definition at line 165 of file input.c.

◆ vApiAttrsErrorsToAscii()

void vApiAttrsErrorsToAscii	(	void *	vpCtx,
		const char *	cpMode,
		const char *	cpFileName
	)

Display all rule attributes with errors.

Parameters

vpCtx	- Pointer to an API context previously returned from vpApiCtor().
cpMode	(note: the first character (case-insensitive) of the following options is all that is needed) "index" sort attributes by rule name index (the order they appear in the grammar syntax) "alpha" sort attributes by rule name alphabetically "type" sort attributes by type (non-recursive, recursive, etc.). Rules are alphabetical within each type. NULL, empty string or any string not beginning with "a" or "t" defaults to "index"
cpFileName	- Name of the file to display on. Any directories in the path name must exist. If NULL, stdout is used.

Definition at line 268 of file attributes.c.

◆ vApiAttrsToAscii()

void vApiAttrsToAscii	(	void *	vpCtx,
		const char *	cpMode,
		const char *	cpFileName
	)

Display all rule attributes.

Parameters

vpCtx	- Pointer to an API context previously returned from vpApiCtor().
cpMode	(note: the first character (case-insensitive) of the following options is all that is needed) "index" sort attributes by rule name index (the order they appear in the grammar syntax) "alpha" sort attributes by rule name alphabetically "type" sort attributes by type (non-recursive, recursive, etc.). Rules are alphabetical within each type. NULL, empty string or any string not beginning with "a" or "t" defaults to "index"
cpFileName	- Name of the file to display on. Any directories in the path name must exist. If NULL, stdout is used.

Definition at line 220 of file attributes.c.

◆ vApiDtor()

void vApiDtor ( void * vpCtx )

The API component destructor.

Parameters

vpCtx - Pointer to an API context previously returned from vpApiCtor().

Returns: Silently ignores NULL context pointer. However, if non-NULL the API context pointer must be valid.

Definition at line 84 of file api.c.

◆ vApiFile()

void vApiFile	(	void *	vpCtx,
		const char *	cpFileName,
		abool	bStrict,
		abool	bPppt
	)

Quicky way to generate a parser from a grammar file.

Calls all of the intermediate steps in one function. Input is limited to a single file.

Parameters

vpCtx	- Pointer to an API context previously returned from vpApiCtor().
cpFileName	- Name of the grammar file.
bStrict	If true, only strictly ABNF (RFC 5234 & RFC7405) grammars allowed.
bPppt	If true, Partially-Predictive Parsing Tables (PPPTs) are generated. Note that in this single, collective call to generate a parser there is no opportunity to protect any rules from PPPT replacement. If any rules need protecting it will be necessary to do the full sequence of API calls.

Definition at line 517 of file api.c.

◆ vApiInClear()

void vApiInClear ( void * vpCtx )

Clears the input and related memory.

The user must call this to clear any previous input grammar before reusing the API object for another job.

Parameters

[in] vpCtx - Pointer to an API context previously returned from vpApiCtor().

Definition at line 61 of file input.c.

◆ vApiInToAscii()

void vApiInToAscii	(	void *	vpCtx,
		const char *	cpFileName
	)

Display the input lines with line numbers and character offsets.

Writes the input grammar in ASCII format to a file.

Valid control characters are single quoted, e.g. '\t', '\n', '\r'
Invalid characters are double quoted hex, e.g. '\xHH'
Invalid last line with no line ending is indicated as "EOF"
Parameters

[in] vpCtx - pointer to an API context previously returned from vpApiCtor().

[in] cpFileName - Name of the file to write the result to. If NULL, stdout is used.

Definition at line 261 of file input.c.

◆ vApiInToHtml()

void vApiInToHtml	(	void *	vpCtx,
		const char *	cpFileName,
		const char *	cpTitle
	)

Display the input lines with line numbers and character offsets.

Writes the input grammar as an HTML page to a file.

Valid control characters are stylized as TAB, LF and CR
Invalid characters are error stylized in hex, e.g. \xHH

Invalid last line with no line ending is error stylized as EOF

Parameters

[in]	vpCtx	- pointer to an API context previously returned from vpApiCtor().
[in]	cpFileName	- name of the file to write the result to.
[in]	cpTitle	- HTML title. If NULL, a default page title is used.

Definition at line 319 of file input.c.

◆ vApiInValidate()

void vApiInValidate	(	void *	vpCtx,
		abool	bStrict
	)

Scans the input SABNF grammar for invalid characters and line ends.

Constructs a lines object for dealing with finding and handling lines.

Parameters

[in]	vpCtx	- Pointer to an API context previously returned from vpApiCtor().
[in]	bStrict	- If true, validate as strict ABNF. If APG_TRUE, validate as strict ABNF (RFC5234 & RFC7405). Otherwise, validate as SABNF.

Returns: Throws exception on error.

Definition at line 204 of file input.c.

◆ vApiOpcodes()

void vApiOpcodes ( void * vpCtx )

Parse the SABNF grammar and translate its AST into opcodes for all the rules.

Parameters

vpCtx - Pointer to an API context previously returned from vpApiCtor().

Definition at line 64 of file semantics.c.

◆ vApiOpcodesToAscii()

void vApiOpcodesToAscii	(	void *	vpCtx,
		const char *	cpFileName
	)

Display all opcodes in human-readable format.

Parameters

vpCtx	- Pointer to an API context previously returned from vpApiCtor().
cpFileName	- Name of the file to display on. Any directories in the path name must exist. If NULL, stdout is used.

Definition at line 328 of file api.c.

◆ vApiOutput()

void vApiOutput	(	void *	vpCtx,
		const char *	cpOutput
	)

Generate a source and header file that can be used to construct a parser for the specified SABNF grammar.

Parameters

vpCtx	- Pointer to an API context previously returned from vpApiCtor().
cpOutput	The root of the file name to use for the generated source and header files. Any extension will be stripped and replaces with .h for the header file and .c for the source file. The name may be relative or absolute. Any directories in the pathname must exist.

Returns: Throws exceptions on errors.

Definition at line 152 of file output.c.

◆ vApiPppt()

void vApiPppt	(	void *	vpCtx,
		char **	cppProtectedRules,
		aint	uiProtectedRules
	)

Compute the Partially-Predictive Parsing Tables.

Parameters

vpCtx	Context pointer previously returned from vpApiCtor().
cppProtectedRules	An array of string pointers pointing to the rule names to protect. Protection means that the rule is generated, even if the PPPT would have been deterministic prior to calling the rule. May be NULL, in which case no rules are protected.
uiProtectedRules	The number of protected rules. May be 0, in which case no rules are protected.

Definition at line 101 of file pppt.c.

◆ vApiPpptSize()

void vApiPpptSize	(	void *	vpCtx,
		pppt_size *	spSize
	)

Compute the size of the PPPT maps and the number of bytes for the entire table.

This function may be called after vApiOpcodes() and before vApiPppt() to determine if the application has sufficient memory to handle the PPPTs. vApiOpcodes() is where the PPPT sizes are computed. The tables are not allocated until vApiPppt().

Parameters

vpCtx	Context pointer previously returned from vpApiCtor().
spSize	Pointer to a pppt_size structure to receive the size information.

Definition at line 246 of file pppt.c.

◆ vApiRulesToAscii()

void vApiRulesToAscii	(	void *	vpCtx,
		const char *	cpMode,
		const char *	cpFileName
	)

Display rules and UDTs in human-readable format in ASCII format.

Parameters

vpCtx	- Pointer to an API context previously returned from vpApiCtor().
cpMode	(note: the first character (case-insensitive) of the following options is all that is needed) "index" sort rule names index (the order they appear in the grammar syntax) "alpha" sort rule names alphabetically NULL, empty string or any string not beginning with "i" or "a", defaults to "index"
cpFileName	- Name of the file to display on. Any directories in the path name must exist. If NULL, stdout is used.

Definition at line 257 of file api.c.

◆ vApiRulesToHtml()

void vApiRulesToHtml	(	void *	vpCtx,
		const char *	cpFileName
	)

Display the grammar rules in human-readable, HTML format.

Parameters

vpCtx	- Pointer to an API context previously returned from vpApiCtor().
cpFileName	- Name of the file to display on. Any directories in the path name must exist. If NULL, stdout is used.

Definition at line 132 of file api.c.

◆ vApiString()

void vApiString	(	void *	vpCtx,
		const char *	cpString,
		abool	bStrict,
		abool	bPppt
	)

Quicky way to generate a parser from a grammar string.

Calls all of the intermediate steps in one function. Input is limited to a single file.

Parameters

vpCtx	- Pointer to an API context previously returned from vpApiCtor().
cpString	- Pointer to a string which contains the entire grammar.
bStrict	If true, only strictly ABNF (RFC 5234 & RFC7405) grammars allowed.
bPppt	If true, Partially-Predictive Parsing Tables (PPPTs) are generated. Note that in this single, collective call to generate a parser there is no opportunity to protect any rules from PPPT replacement. If any rules need protecting it will be necessary to do the full sequence of API calls.

Definition at line 544 of file api.c.

◆ vApiSyntax()

void vApiSyntax	(	void *	vpCtx,
		abool	bStrict
	)

Parse the SABNF grammar to validate that the grammar structure is valid.

Parameters

vpCtx	- Pointer to an API context previously returned from vpApiCtor().
bStrict	If true, only strict RFC 5234 syntax is allowed. If false, full SABNF syntax is allowed.

Definition at line 51 of file syntax.c.

◆ vpApiCtor()

void* vpApiCtor ( exception * spEx )

Construct an API component context (object).

Parameters

spEx	Pointer to a valid exception object. See XCTOR(). If invalid, the application will silently exit with a BAD_CONTEXT exit code.

Returns: Pointer to an API context. Exception thrown on memory allocation error.

Definition at line 55 of file api.c.

◆ vpApiGetErrorLog()

void* vpApiGetErrorLog ( void * vpCtx )

Get the internal message log.

User may want to display or otherwise use the list of messages.

Parameters

vpCtx - Pointer to an API context previously returned from vpApiCtor().

Returns: Pointer to a message log context.

Definition at line 117 of file api.c.

◆ vpApiOutputParser()

void* vpApiOutputParser ( void * vpCtx )

Generate a parser object directly from the specified SABNF grammar.

The generated parser has its own memory object and is independent of the parent API object other than sharing the same exception object. That is, throw exceptions will land in the API catch block. But the API and the generated parser must each call their respective destructors to prevent memory leaks.

Parameters

vpCtx - Pointer to an API context previously returned from vpApiCtor().

Returns: Throws exceptions on errors.

Definition at line 217 of file output.c.

Data Structures

Functions

Detailed Description

Function Documentation

◆ bApiAttrs()

◆ bApiValidate()

◆ cpApiInFile()

◆ cpApiInString()

◆ vApiAttrsErrorsToAscii()

◆ vApiAttrsToAscii()

◆ vApiDtor()

◆ vApiFile()

◆ vApiInClear()

◆ vApiInToAscii()

◆ vApiInToHtml()

◆ vApiInValidate()

◆ vApiOpcodes()

◆ vApiOpcodesToAscii()

◆ vApiOutput()

◆ vApiPppt()

◆ vApiPpptSize()

◆ vApiRulesToAscii()

◆ vApiRulesToHtml()

◆ vApiString()

◆ vApiSyntax()

◆ vpApiCtor()

◆ vpApiGetErrorLog()

◆ vpApiOutputParser()