The APG header file. More...
#include <inttypes.h>
Go to the source code of this file.
Macros | |
Version Information | |
| #define | APG_VERSION "7.0" |
| #define | APG_COPYRIGHT "Copyright (c) 2021 Lowell D. Thomas, all rights reserved" |
| #define | APG_LICENSE "BSD 2-Clause" |
Trace Control. | |
The parser uses these macros to call the tracing functions. If APG_TRACE is defined, these are the functions that are called. If not defined, these macros are defined as empty, generating no code at all in the parser. This prevents the parser from having to do unnecessary testing when no tracing is requested. Additionally, all tracing code is excluded from the build. | |
| #define | TRACE_DOWN(x, o, f) if((x))vTraceDown((x), (o), (f)) |
| #define | TRACE_UP(x, o, s, f, p) if((x))vTraceUp((x), (o), (s), (f), (p)); |
| #define | TRACE_BEGIN(x) if((x))vTraceBegin((x)) |
| #define | TRACE_END(x) if((x))vTraceEnd((x)) |
| #define | TRACE_DTOR(x) if((x))vTraceDtor((x)) |
Parsing Statistics Control. | |
The parser uses these macros to call the statistics gathering functions. If APG_STATS is defined, these are the functions that are called. If not defined, these macros are defined as empty, generating no code at all in the parser. This prevents the parser from having to do unnecessary testing when no statistics are requested. Additionally, all statistics gathering code is excluded from the build. | |
| #define | STATS_HIT(x, o, s) if((x))vStatsHit((x), (o), (s)) |
Back Referencing Control. | |
The parser uses these macros to call the back referencing functions. If APG_BKR is defined, these are the functions that are called. If not defined, these macros are defined as empty, generating no code at all in the parser. This prevents the parser from having to do unnecessary testing when no statistics are requested. Additionally, all back referencing code is excluded from the build. Note that back referencing is compute intensive. It is used primarily in the phrase-matching application apgex.c. Unless strictly required for an application, this macro should not be defined. | |
| #define | BKR_APGEX_CHECK(e) |
| #define | BKRU_CTOR(x) vpBkruCtor((x)) |
| #define | BKRU_RULE_OPEN(x, i) if((x)) vBkruRuleOpen((x), (i)) |
| #define | BKRU_RULE_CLOSE(x, i, s, o, p) if((x)) vBkruRuleClose((x), (i), (s), (o), (p)) |
| #define | BKRU_UDT_CLOSE(x, i, s, o, p) if((x)) vBkruUdtClose((x), (i), (s), (o), (p)) |
| #define | BKRU_OP_OPEN(x) if((x)) vBkruOpOpen((x)) |
| #define | BKRU_OP_CLOSE(x, s) if((x)) vBkruOpClose((x), (s)) |
| #define | BKRP_CTOR(x) vpBkrpCtor((x)) |
| #define | BKRP_RULE_OPEN(x, i) if((x)) vBkrpRuleOpen((x), (i)) |
| #define | BKRP_RULE_CLOSE(x, i, s, o, p) if((x)) vBkrpRuleClose((x), (i), (s), (o), (p)) |
| #define | BKRP_UDT_CLOSE(x, i, s, o, p) if((x)) vBkrpUdtClose((x), (i), (s), (o), (p)) |
| #define | BKRP_OP_OPEN(x) if((x)) vBkrpOpOpen((x)) |
| #define | BKRP_OP_CLOSE(x, s) if((x)) vBkrpOpClose((x), (s)) |
Abstract Syntax Tree (AST) Control. | |
The parser uses these macros to call the generate the AST. If APG_AST is defined, these are the functions that are called. If not defined, these macros are defined as empty, generating no code at all in the parser. This prevents the parser from having to do unnecessary testing when no AST is requested. Additionally, all AST code is excluded from the build. | |
| #define | AST_CLEAR(v) if(v)vAstClear(v) |
| #define | AST_RULE_OPEN(x, l, i, o) if((x) && !(l)) vAstRuleOpen((x), (i), (o)) |
| #define | AST_RULE_CLOSE(x, l, i, s, o, p) if((x) && !(l)) vAstRuleClose((x), (i), (s), (o), (p)) |
| #define | AST_OP_OPEN(x, l) if((x)) if((x) && !(l)) vAstOpOpen((x)) |
| #define | AST_OP_CLOSE(x, l, s) if((x) && !(l)) vAstOpClose((x), (s)) |
Partially-Predictive Parsing Table (PPPT) Control. | |
The parser uses these macros to call the generate the PPPT. If APG_NO_PPPT is not defined, these are the functions that are called to evaluate the PPPT values. If not defined, these macros are defined as empty, generating no code at all in the parser. This prevents the parser from having to do unnecessary testing when no PPPT is requested. Additionally, if APG_NO_PPPT is defined the API will not generate any table data. | |
| #define | PPPT_OPEN(x, o, f) |
| #define | PPPT_CLOSE |
| #define | PPPT_DEFINED 0 |
True/False Values. | |
Provides a consistent definition of true and false throughout APG. | |
| #define | APG_TRUE 1 |
| #define | APG_FALSE 0 |
Success/Failure Values. | |
In many cases it is more intuitive for a function to return "success" or "failure" so that, for example, error checking can be done simply with if(!bApgFunc()){
//handle error
}
| |
| #define | APG_SUCCESS 1 |
| #define | APG_FAILURE 0 |
Undefined and Infinite Values. | |
It is sometimes the case of needing to have an undefined or infinite value. For finite, unsigned integers this is not possible. Therefore, the maximum unsigned integer value is used to indicate these. | |
| #define | APG_UNDEFINED ((aint)-1) |
| #define | APG_INFINITE ((aint)-1) |
Maximum Values. | |
| #define | APG_MAX_AINT ((aint)-2) |
| Since the maximum unsigned integer value is used to indicate Infinite and Undefined values, the maximum usable integer is one less. More... | |
| #define | APG_MAX_ACHAR ((achar)-1) |
Typedefs | |
| typedef uint_fast32_t | aint |
| The APG parser's unsigned integer type. More... | |
| typedef uint_fast8_t | achar |
| achar is the type for the parser's alphabet characters. More... | |
| typedef uintmax_t | luint |
| luint is used to cast integers suitable for the %"PRIuMAX" printf format. More... | |
| typedef uint8_t | abool |
| abool is the APG bool type. More... | |
Detailed Description
The APG header file.
APG has a large number of options. The alphabet character and the working integer sizes are configurable. Additionally, many facilities are optional and the code for them is excluded from the build when not used. Control of these features and options is done through the use of special macros defined here and with the compiler.
For many simple parsers the default values may be sufficient and no special compile-time interactions will be necessary. However, for full control of APG in an application some or all of these macros may need to be specifically defined.
This header (or lib.h) must be included first before all other APG and application-defined header files in all applications using a parser generated by APG. With the gcc compiler, for example, the controlling macros can be defined with the -D option. e.g.
gcc -DAPG_ACHAR=16 [other options] ../myfile.c
The controlling macros are:
- APG_ACHAR - specify the size of the alphabet character. See the typedef achar for a full explanation.
- APG_AINT - specify the size of the working APG unsigned integer. See the typedef aint for a full explanation.
- APG_TRACE - must be defined to use the tracing feature
- APG_STATS - must be defined to collect parsing statistics.
- APG_AST - must be defined to generate an Abstract Syntax Tree
- APG-BKR - must be defined if the grammar has any back referencing operators (i.e. \rulename)
- APG_NO_PPPT - if defined, no Partially-Predictive Parsing Tables are generated
- APG_STRICT_ABNF - if defined, the grammar must adhere strictly to the RFC5234 & RFC7405 standard
- APG_MEM_STATS - must be defined to generate memory object statistics
- APG_VEC_STATS - must be defined to generate vector object statistics.
Definition in file apg.h.
Macro Definition Documentation
◆ APG_COPYRIGHT
| #define APG_COPYRIGHT "Copyright (c) 2021 Lowell D. Thomas, all rights reserved" |
◆ APG_FAILURE
◆ APG_FALSE
◆ APG_INFINITE
◆ APG_LICENSE
◆ APG_MAX_ACHAR
◆ APG_MAX_AINT
| #define APG_MAX_AINT ((aint)-2) |
◆ APG_SUCCESS
◆ APG_TRUE
◆ APG_UNDEFINED
◆ APG_VERSION
◆ AST_CLEAR
◆ AST_OP_CLOSE
| #define AST_OP_CLOSE | ( | x, | |
| l, | |||
| s | |||
| ) | if((x) && !(l)) vAstOpClose((x), (s)) |
◆ AST_OP_OPEN
| #define AST_OP_OPEN | ( | x, | |
| l | |||
| ) | if((x)) if((x) && !(l)) vAstOpOpen((x)) |
◆ AST_RULE_CLOSE
| #define AST_RULE_CLOSE | ( | x, | |
| l, | |||
| i, | |||
| s, | |||
| o, | |||
| p | |||
| ) | if((x) && !(l)) vAstRuleClose((x), (i), (s), (o), (p)) |
◆ AST_RULE_OPEN
| #define AST_RULE_OPEN | ( | x, | |
| l, | |||
| i, | |||
| o | |||
| ) | if((x) && !(l)) vAstRuleOpen((x), (i), (o)) |
◆ BKR_APGEX_CHECK
◆ BKRP_CTOR
| #define BKRP_CTOR | ( | x | ) | vpBkrpCtor((x)) |
◆ BKRP_OP_CLOSE
| #define BKRP_OP_CLOSE | ( | x, | |
| s | |||
| ) | if((x)) vBkrpOpClose((x), (s)) |
◆ BKRP_OP_OPEN
| #define BKRP_OP_OPEN | ( | x | ) | if((x)) vBkrpOpOpen((x)) |
◆ BKRP_RULE_CLOSE
| #define BKRP_RULE_CLOSE | ( | x, | |
| i, | |||
| s, | |||
| o, | |||
| p | |||
| ) | if((x)) vBkrpRuleClose((x), (i), (s), (o), (p)) |
◆ BKRP_RULE_OPEN
| #define BKRP_RULE_OPEN | ( | x, | |
| i | |||
| ) | if((x)) vBkrpRuleOpen((x), (i)) |
◆ BKRP_UDT_CLOSE
| #define BKRP_UDT_CLOSE | ( | x, | |
| i, | |||
| s, | |||
| o, | |||
| p | |||
| ) | if((x)) vBkrpUdtClose((x), (i), (s), (o), (p)) |
◆ BKRU_CTOR
| #define BKRU_CTOR | ( | x | ) | vpBkruCtor((x)) |
◆ BKRU_OP_CLOSE
| #define BKRU_OP_CLOSE | ( | x, | |
| s | |||
| ) | if((x)) vBkruOpClose((x), (s)) |
◆ BKRU_OP_OPEN
| #define BKRU_OP_OPEN | ( | x | ) | if((x)) vBkruOpOpen((x)) |
◆ BKRU_RULE_CLOSE
| #define BKRU_RULE_CLOSE | ( | x, | |
| i, | |||
| s, | |||
| o, | |||
| p | |||
| ) | if((x)) vBkruRuleClose((x), (i), (s), (o), (p)) |
◆ BKRU_RULE_OPEN
| #define BKRU_RULE_OPEN | ( | x, | |
| i | |||
| ) | if((x)) vBkruRuleOpen((x), (i)) |
◆ BKRU_UDT_CLOSE
| #define BKRU_UDT_CLOSE | ( | x, | |
| i, | |||
| s, | |||
| o, | |||
| p | |||
| ) | if((x)) vBkruUdtClose((x), (i), (s), (o), (p)) |
◆ PPPT_CLOSE
◆ PPPT_DEFINED
◆ PPPT_OPEN
◆ STATS_HIT
◆ TRACE_BEGIN
| #define TRACE_BEGIN | ( | x | ) | if((x))vTraceBegin((x)) |
◆ TRACE_DOWN
| #define TRACE_DOWN | ( | x, | |
| o, | |||
| f | |||
| ) | if((x))vTraceDown((x), (o), (f)) |
◆ TRACE_DTOR
| #define TRACE_DTOR | ( | x | ) | if((x))vTraceDtor((x)) |
◆ TRACE_END
◆ TRACE_UP
| #define TRACE_UP | ( | x, | |
| o, | |||
| s, | |||
| f, | |||
| p | |||
| ) | if((x))vTraceUp((x), (o), (s), (f), (p)); |
Typedef Documentation
◆ abool
◆ achar
achar is the type for the parser's alphabet characters.
This is configurable with the APG_ACHAR macro. The default is uint_fast8_t. That is, the compiler's choice for the fastest way to handle unsigned 8-bit integers. However, this is configurable with the APG_ACHAR macro. For specific integer lengths define the APG_ACHAR macro.
- APG_ACHAR=8 for uint8_t, unsigned 8-bit integers
- APG_ACHAR=16 for uint16_t, unsigned 16-bit integers
- APG_ACHAR=32 for uint32_t, unsigned 32-bit integers
- APG_ACHAR=64 for uint64_t, unsigned 64-bit integers
For example, with the gcc compiler use the option -DAPG_ACHAR=16 for 16-bit unsigned integers. If APG_ACHAR is undefined or defined to something other than 8, 16. 32, or 64 the default is used.
◆ aint
The APG parser's unsigned integer type.
The default type is uint_fast32_t. That is, the compiler's choice for the fastest way to handle unsigned 32-bit integers. However, this is configurable with the APG_AINT macro. For specific integer lengths define the APG_AINT macro.
- APG_AINT=8 for uint8_t, unsigned 8-bit integers (not recommended)
- APG_AINT=16 for uint16_t, unsigned 16-bit integers
- APG_AINT=32 for uint32_t, unsigned 32-bit integers
- APG_AINT=64 for uint64_t, unsigned 64-bit integers
For example, with the gcc compiler use the option -DAPG_AINT=32 for 32-bit unsigned integers. If APG_AINT is undefined or defined to something other than 8, 16. 32, or 64 the default is used.
◆ luint
luint is used to cast integers suitable for the %"PRIuMAX" printf format.
Useful because the length of aint is compile-time dependent and the flag is not conveniently represtened by a variable. Avoids errors due to a printf("%u", uiSomeInt); when aint is not an uint32_t. Instead, use printf("%"PRIuMAX"", (luint)uiSomeInt);
