The SABNF parser's public header file. More...

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

Data Structures
struct	callback_data
	The data struct passed to each callback function. More...

struct	parser_state
	The parser's final state. More...

struct	parser_config
	Defines the input string and other configuration parameters for the parser,. More...

Macros
ABNF Opcode Identifiers
These are the unique identifiers of the original 7 ABNF opcodes.
#define	ID_ALT 1
	alternation More...

#define	ID_CAT 2
	concatenation More...

#define	ID_REP 3
	repetition More...

#define	ID_RNM 4
	rule name More...

#define	ID_TRG 5
	terminal range More...

#define	ID_TBS 6
	terminal binary string More...

#define	ID_TLS 7
	terminal literal string More...

SABNF Superset Opcode Identifiers
These are the unique identifiers of the additional opcodes of the superset SABNF.
#define	ID_UDT 8
	user-defined terminal More...

#define	ID_AND 9
	positive look ahead More...

#define	ID_NOT 10
	negative look ahead More...

#define	ID_BKR 11
	back reference to a previously matched rule or UDT name More...

#define	ID_BKA 12
	positive look behind More...

#define	ID_BKN 13
	negative look behind More...

#define	ID_ABG 14
	anchor - beginning of string More...

#define	ID_AEN 15
	anchor - end of string More...

#define	ID_GEN 19
	general opcode (not SABNF). Serves to locate the ID in any opcode structure and must be larger than all other opcode IDs. One or more arrays may be created of size ID_GEN and data for all other opcodes must fit in the array. More...

Parser State Indentifiers
These four identifiers are used to indicate the parser state for any node operation in the parse tree.
#define	ID_ACTIVE 20
	indicates active parser state, parser has just entered the node and is moving down the parse tree More...

#define	ID_MATCH 21
	indicates a matched phrase parser state on return from parse tree below this node More...

#define	ID_NOMATCH 22
	indicates that no phrase was matched on return from parse tree below this node More...

#define	ID_EMPTY 23
	indicates a matched empty phrase parser state on return from parse tree below this node More...

PPPT Map Values
These are the four possible values for a single character in a Partially-Predictive Parsing Table map.
#define	ID_PPPT_NOMATCH 0
	deterministic NOMATCH – there is no chance of a phrase match with this leading character More...

#define	ID_PPPT_MATCH 1
	deterministic MATCH – this character constitutes a single character phrase match of length 1 More...

#define	ID_PPPT_EMPTY 2
	deterministic EMTPY – this is an empty string match, the parse succeeds but the phrase length is 0 More...

#define	ID_PPPT_ACTIVE 3
	non-deterministic – it is not possible to determine a match or not based on this character – the parser will have to do a full, normal parse to find out More...

Asymetric Syntax Tree (AST) States and Return Codes
These identifiers are used for the traversal direction and return codes in AST call back functions.
#define	ID_AST_PRE 30
	indicates pre-node-traversal AST callback state (down the tree) More...

#define	ID_AST_POST 31
	indicates post-node-traversal AST callback state (up the tree) More...

#define	ID_AST_OK 32
	normal AST callback function return More...

#define	ID_AST_SKIP 33
	on return from AST callback, skip all nodes below (ignored on return from ID_AST_POST state) More...

Attribute Rule Types
These identifiers indicate the attribute classifications of the grammar's rules.
#define	ID_ATTR_N 40
	rule is non-recursive - never refers to itself More...

#define	ID_ATTR_R 41
	rule is recursive - refers to itself, directly or indirectly, one or more times More...

#define	ID_ATTR_MR 42
	rule is one of a mutually-recursive group (each rule in the group refers to itself and all others) More...

Look Ahead and Look Behind (Look Around) Indicators
The parser behaves somewhat differently when in a look around state. That is, whether or not there is a look around opcode (AND(&), NOT(!), BKA(&&) or BKN(!!)) in the branch of the parse tree,
#define	ID_LOOKAROUND_NONE 50
	the parser presently is not in look around mode More...

#define	ID_LOOKAROUND_AHEAD 51
	the parser presently is in look ahead mode More...

#define	ID_LOOKAROUND_BEHIND 52
	the parser presently is in look behind mode More...

Back Reference Mode and Case Indicators
Identifies the case sensitivity and back reference mode of the back reference operator. Back referencing can be either case-sensitive or insensitive and can be either universal- or parent-mode.
#define	ID_BKR_MODE_U 60
	the back reference is universal mode More...

#define	ID_BKR_MODE_P 61
	the back reference is parent mode More...

#define	ID_BKR_CASE_S 62
	the back reference is case sensitive More...

#define	ID_BKR_CASE_I 63
	the back reference is case insensitive More...

Typedefs
typedef void(*	parser_callback) (callback_data *spData)
	User-written callback function prototype. More...

Functions
void *	vpParserCtor (exception spException, void vpParserInit)
	The parser's constructor for file initialization data. More...

void	vParserDtor (void *vpCtx)
	Clears the parser component's context and frees all heap memory associated with this parser. More...

abool	bParserValidate (void *vpCtx)
	Validate the context pointer of a parser. More...

void	vParserParse (void vpCtx, parser_config spConfig, parser_state *spState)
	Parse an input string of alphabet characters. More...

aint	uiParserRuleLookup (void vpCtx, const char cpRuleName)
	Find the rule index corresponding to a rule name. More...

aint	uiParserUdtLookup (void vpCtx, const char cpUdtName)

const char *	cpParserRuleName (void *vpCtx, aint uiRuleIndex)
	Find the rule name from the corresponding index. More...

const char *	cpParserUdtName (void *vpCtx, aint uiUdtIndex)
	Find the UDT name corresponding to a UDT index. More...

void	vParserSetRuleCallback (void *vpCtx, aint uiRuleId, parser_callback pfnCallback)
	Set a call back function for a specific rule. More...

void	vParserSetUdtCallback (void *vpCtx, aint uiUdtId, parser_callback pfnCallback)
	Set a call back function for a specific UDT. More...

Detailed Description

The SABNF parser's public header file.

Defines only the macros, structures, typedefs, and function prototypes needed by the user of the parser.

Definition in file parser.h.

Macro Definition Documentation

◆ ID_ABG

#define ID_ABG 14

anchor - beginning of string

Definition at line 61 of file parser.h.

◆ ID_ACTIVE

#define ID_ACTIVE 20

indicates active parser state, parser has just entered the node and is moving down the parse tree

Definition at line 72 of file parser.h.

◆ ID_AEN

#define ID_AEN 15

anchor - end of string

Definition at line 62 of file parser.h.

◆ ID_ALT

#define ID_ALT 1

alternation

Definition at line 43 of file parser.h.

◆ ID_AND

#define ID_AND 9

positive look ahead

Definition at line 56 of file parser.h.

◆ ID_AST_OK

#define ID_AST_OK 32

normal AST callback function return

Definition at line 93 of file parser.h.

◆ ID_AST_POST

#define ID_AST_POST 31

indicates post-node-traversal AST callback state (up the tree)

Definition at line 92 of file parser.h.

◆ ID_AST_PRE

#define ID_AST_PRE 30

indicates pre-node-traversal AST callback state (down the tree)

Definition at line 91 of file parser.h.

◆ ID_AST_SKIP

#define ID_AST_SKIP 33

on return from AST callback, skip all nodes below (ignored on return from ID_AST_POST state)

Definition at line 94 of file parser.h.

◆ ID_ATTR_MR

#define ID_ATTR_MR 42

rule is one of a mutually-recursive group (each rule in the group refers to itself and all others)

Definition at line 102 of file parser.h.

◆ ID_ATTR_N

#define ID_ATTR_N 40

rule is non-recursive - never refers to itself

Definition at line 100 of file parser.h.

◆ ID_ATTR_R

#define ID_ATTR_R 41

rule is recursive - refers to itself, directly or indirectly, one or more times

Definition at line 101 of file parser.h.

◆ ID_BKA

#define ID_BKA 12

positive look behind

Definition at line 59 of file parser.h.

◆ ID_BKN

#define ID_BKN 13

negative look behind

Definition at line 60 of file parser.h.

◆ ID_BKR

#define ID_BKR 11

back reference to a previously matched rule or UDT name

Definition at line 58 of file parser.h.

◆ ID_BKR_CASE_I

#define ID_BKR_CASE_I 63

the back reference is case insensitive

Definition at line 121 of file parser.h.

◆ ID_BKR_CASE_S

#define ID_BKR_CASE_S 62

the back reference is case sensitive

Definition at line 120 of file parser.h.

◆ ID_BKR_MODE_P

#define ID_BKR_MODE_P 61

the back reference is parent mode

Definition at line 119 of file parser.h.

◆ ID_BKR_MODE_U

#define ID_BKR_MODE_U 60

the back reference is universal mode

Definition at line 118 of file parser.h.

◆ ID_CAT

#define ID_CAT 2

concatenation

Definition at line 44 of file parser.h.

◆ ID_EMPTY

#define ID_EMPTY 23

indicates a matched empty phrase parser state on return from parse tree below this node

Definition at line 75 of file parser.h.

◆ ID_GEN

#define ID_GEN 19

general opcode (not SABNF). Serves to locate the ID in any opcode structure and must be larger than all other opcode IDs. One or more arrays may be created of size ID_GEN and data for all other opcodes must fit in the array.

Definition at line 63 of file parser.h.

◆ ID_LOOKAROUND_AHEAD

#define ID_LOOKAROUND_AHEAD 51

the parser presently is in look ahead mode

Definition at line 110 of file parser.h.

◆ ID_LOOKAROUND_BEHIND

#define ID_LOOKAROUND_BEHIND 52

the parser presently is in look behind mode

Definition at line 111 of file parser.h.

◆ ID_LOOKAROUND_NONE

#define ID_LOOKAROUND_NONE 50

the parser presently is not in look around mode

Definition at line 109 of file parser.h.

◆ ID_MATCH

#define ID_MATCH 21

indicates a matched phrase parser state on return from parse tree below this node

Definition at line 73 of file parser.h.

◆ ID_NOMATCH

#define ID_NOMATCH 22

indicates that no phrase was matched on return from parse tree below this node

Definition at line 74 of file parser.h.

◆ ID_NOT

#define ID_NOT 10

negative look ahead

Definition at line 57 of file parser.h.

◆ ID_PPPT_ACTIVE

#define ID_PPPT_ACTIVE 3

non-deterministic – it is not possible to determine a match or not based on this character – the parser will have to do a full, normal parse to find out

Definition at line 84 of file parser.h.

◆ ID_PPPT_EMPTY

#define ID_PPPT_EMPTY 2

deterministic EMTPY – this is an empty string match, the parse succeeds but the phrase length is 0

Definition at line 83 of file parser.h.

◆ ID_PPPT_MATCH

#define ID_PPPT_MATCH 1

deterministic MATCH – this character constitutes a single character phrase match of length 1

Definition at line 82 of file parser.h.

◆ ID_PPPT_NOMATCH

#define ID_PPPT_NOMATCH 0

deterministic NOMATCH – there is no chance of a phrase match with this leading character

Definition at line 81 of file parser.h.

◆ ID_REP

#define ID_REP 3

repetition

Definition at line 45 of file parser.h.

◆ ID_RNM

#define ID_RNM 4

rule name

Definition at line 46 of file parser.h.

◆ ID_TBS

#define ID_TBS 6

terminal binary string

Definition at line 48 of file parser.h.

◆ ID_TLS

#define ID_TLS 7

terminal literal string

Definition at line 49 of file parser.h.

◆ ID_TRG

#define ID_TRG 5

terminal range

Definition at line 47 of file parser.h.

◆ ID_UDT

#define ID_UDT 8

user-defined terminal

Definition at line 55 of file parser.h.

Typedef Documentation

◆ parser_callback

parser_callback

User-written callback function prototype.

Parameters

spData Callback data supplied by the parser. See callback_data for restrictions.

Returns: APG_SUCCESS on success, APG_FAILURE if any type of error occurs

Definition at line 178 of file parser.h.

Function Documentation

◆ bParserValidate()

abool bParserValidate ( void * vpCtx )

Validate the context pointer of a parser.

Parameters

vpCtx Pointer to a supposedly valid parser context previously returned from vpParserCtor() or vpApiOutputParser().

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

Definition at line 422 of file parser.c.

◆ cpParserRuleName()

const char* cpParserRuleName	(	void *	vpCtx,
		aint	uiRuleIndex
	)

Find the rule name from the corresponding index.

A rule's index is the 0-based order in which it appears in the SABNF grammar. Used in many places instead of the name to identify a rule. The parser's start rule (parser_config) would be a prime example.

Parameters

vpCtx	Pointer to a valid parser context previously returned from vpParserCtor() or vpApiOutputParser(). If not valid, the application will silently exit with a BAD_CONTEXT exit code.
uiRuleIndx	Index (order of appearance in the SABNF grammar) of the rule name to look up

Returns: Pointer to the rule name if successful. NULL if the index is out of range.

Definition at line 469 of file parser.c.

◆ cpParserUdtName()

const char* cpParserUdtName	(	void *	vpCtx,
		aint	uiUdtIndex
	)

Find the UDT name corresponding to a UDT index.

A UDT's index is the 0-based order in which it appears in the SABNF grammar. Used in some places instead of the name to identify a UDT. vParserSetUdtCallback() would be an example.

Parameters

vpCtx	Pointer to a valid parser context previously returned from vpParserCtor() or vpApiOutputParser(). If not valid, the application will silently exit with a BAD_CONTEXT exit code.
uiUdtIndex	Index of the UDT to look up.

Returns: Pointer to the UDT name if successful. NULL if the index is out of range.

Definition at line 491 of file parser.c.

◆ uiParserRuleLookup()

aint uiParserRuleLookup	(	void *	vpCtx,
		const char *	cpRuleName
	)

Find the rule index corresponding to a rule name.

A rule's index is the 0-based order in which it appears in the SABNF grammar. Used in many places instead of the name to identify a rule. The parser's start rule (parser_config) would be a prime example.

Parameters

vpCtx	Pointer to a valid parser context previously returned from vpParserCtor() or vpApiOutputParser(). If not valid, the application will silently exit with a BAD_CONTEXT exit code.
cpRuleName	Name of the rule to look up. Case insensitive.

Returns: The rule index if successful. APG_UNDEFINED if the name does not appear in the SABNF grammar.

Definition at line 440 of file parser.c.

◆ uiParserUdtLookup()

aint uiParserUdtLookup	(	void *	vpCtx,
		const char *	cpUdtName
	)

◆ vParserDtor()

void vParserDtor ( void * vpCtx )

Clears the parser component's context and frees all heap memory associated with this parser.

Parameters

vpCtx a parser context pointer previously returned from vpParserCtor() or vpApiOutputParser(). NULL is silently ignored. However, non-NULL values must be valid parser context pointers.

Definition at line 245 of file parser.c.

◆ vParserParse()

void vParserParse	(	void *	vpCtx,
		parser_config *	spConfig,
		parser_state *	spState
	)

Parse an input string of alphabet characters.

Parameters

vpCtx	Pointer to a valid parser context previously returned from vpParserCtor() or vpApiOutputParser(). If not valid, the application will silently exit with a BAD_CONTEXT exit code.
spConfig	Pointer to the configuration defining the input string and other parsing parameters. See parser_config.
spState	Pointer to a parser state structure. See parser_state.

Returns: The parser state is returned in the caller's state structure, spState.

Definition at line 268 of file parser.c.

◆ vParserSetRuleCallback()

void vParserSetRuleCallback	(	void *	vpCtx,
		aint	uiRuleId,
		parser_callback	pfnCallback
	)

Set a call back function for a specific rule.

Parameters

vpCtx	Pointer to a valid parser context previously returned from vpParserCtor() or vpApiOutputParser(). If not valid, the application will silently exit with a BAD_CONTEXT exit code.
uiRuleId	The index of the rule to set the call back function for.
pfnCallback	Pointer to the call back function.

Definition at line 386 of file parser.c.

◆ vParserSetUdtCallback()

void vParserSetUdtCallback	(	void *	vpCtx,
		aint	uiUdtId,
		parser_callback	pfnCallback
	)

Set a call back function for a specific UDT.

Note that the parser, vParserParse(), checks on initialization that all UDTs in the SABNF grammar have call back functions set.

Parameters

vpCtx	Pointer to a valid parser context previously returned from vpParserCtor() or vpApiOutputParser(). If not valid, the application will silently exit with a BAD_CONTEXT exit code.
uiUdtId	The index of the UDT to set the call back function for.
pfnCallback	Pointer to the call back function.

Definition at line 407 of file parser.c.

◆ vpParserCtor()

void* vpParserCtor	(	exception *	spException,
		void *	vpParserInit
	)

The parser's constructor for file initialization data.

This function is used to construct a parser from grammar file, "namespace.c", generated by vApiOutput().

Parameters

spException	Pointer to a valid exception structure initialized with vExCtor() or XCTOR(). If not valid, the application will silently exit with a BAD_CONTEXT exit code.
vpParserInit	- Pointer to the initialization data in the generated "namespace.c" file.

Returns: Pointer to a parser context. Exceptions thrown on errors.

Definition at line 67 of file parser.c.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ ID_ABG

◆ ID_ACTIVE

◆ ID_AEN

◆ ID_ALT

◆ ID_AND

◆ ID_AST_OK

◆ ID_AST_POST

◆ ID_AST_PRE

◆ ID_AST_SKIP

◆ ID_ATTR_MR

◆ ID_ATTR_N

◆ ID_ATTR_R

◆ ID_BKA

◆ ID_BKN

◆ ID_BKR

◆ ID_BKR_CASE_I

◆ ID_BKR_CASE_S

◆ ID_BKR_MODE_P

◆ ID_BKR_MODE_U

◆ ID_CAT

◆ ID_EMPTY

◆ ID_GEN

◆ ID_LOOKAROUND_AHEAD

◆ ID_LOOKAROUND_BEHIND

◆ ID_LOOKAROUND_NONE

◆ ID_MATCH

◆ ID_NOMATCH

◆ ID_NOT

◆ ID_PPPT_ACTIVE

◆ ID_PPPT_EMPTY

◆ ID_PPPT_MATCH

◆ ID_PPPT_NOMATCH

◆ ID_REP

◆ ID_RNM

◆ ID_TBS

◆ ID_TLS

◆ ID_TRG

◆ ID_UDT

Typedef Documentation

◆ parser_callback

Function Documentation

◆ bParserValidate()

◆ cpParserRuleName()

◆ cpParserUdtName()

◆ uiParserRuleLookup()

◆ uiParserUdtLookup()

◆ vParserDtor()

◆ vParserParse()

◆ vParserSetRuleCallback()

◆ vParserSetUdtCallback()

◆ vpParserCtor()