Version 7.0
Copyright © 2021 Lowell D. Thomas
APG
… an ABNF Parser Generator
api.h
Go to the documentation of this file.
1 /* *************************************************************************************
2  Copyright (c) 2021, Lowell D. Thomas
3  All rights reserved.
4 
5  This file is part of APG Version 7.0.
6  APG Version 7.0 may be used under the terms of the BSD 2-Clause License.
7 
8  Redistribution and use in source and binary forms, with or without
9  modification, are permitted provided that the following conditions are met:
10 
11  1. Redistributions of source code must retain the above copyright notice, this
12  list of conditions and the following disclaimer.
13 
14  2. Redistributions in binary form must reproduce the above copyright notice,
15  this list of conditions and the following disclaimer in the documentation
16  and/or other materials provided with the distribution.
17 
18  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
19  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
21  DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
22  FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23  DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
24  SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
25  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
26  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
27  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28 
29 * *************************************************************************************/
57 #ifndef API_H_
58 #define API_H_
59 
60 #include <limits.h>
61 
62 #include "../utilities/utilities.h"
63 
67 typedef struct {
74  const char *cpRuleName;
78 } api_attr;
79 
83 typedef struct{
89 } pppt_size;
90 
91 // the API constructor and destructor
93 void* vpApiCtor(exception* spEx);
95 void vApiDtor(void *vpCtx);
96 abool bApiValidate(void *vpCtx);
97 void* vpApiGetErrorLog(void *vpCtx);
99 
100 // the input API - get, validate and manipulate the SABNF grammar characters
106 void vApiInClear(void *vpCtx);
108 const char* cpApiInFile(void *vpCtx, const char *cpFileName);
109 const char* cpApiInString(void *vpCtx, const char *cpString);
110 void vApiInValidate(void *vpCtx, abool bStrict);
111 void vApiInToAscii(void *vpCtx, const char *cpFileName);
112 void vApiInToHtml(void *vpCtx, const char *cpFileName, const char *cpTitle);
114 
115 // the syntax API - parsing the SABNF grammar
119 void vApiSyntax(void *vpCtx, abool bStrict);
122 
123 // the semantics API - translating the SABNF grammar AST to APG opcodes
129 void vApiOpcodes(void *vpCtx);
131 void vApiOpcodesToAscii(void *vpCtx, const char *cpFileName);
132 void vApiRulesToAscii(void *vpCtx, const char *cpMode, const char *cpFileName);
133 void vApiRulesToHtml(void *vpCtx, const char *cpFileName);
135 
136 // the attributes API - analyzing the SABNF grammar's opcodes
141 abool bApiAttrs(void *vpCtx);
143 //const api_attr* spApiAttrsErrors(void *vpCtx, aint* uipCount);
144 void vApiAttrsToAscii(void *vpCtx, const char *cpMode, const char *cpFileName);
145 void vApiAttrsErrorsToAscii(void *vpCtx, const char *cpMode, const char *cpFileName);
147 
148 // the Partially-Predictive Parsing Tables (PPPT)
153 void vApiPppt(void *vpCtx, char **cppProtectedRules, aint uiProtectedRules);
155 void vApiPpptSize(void *vpCtx, pppt_size* spSize);
157 
158 // full parser generation tools
167 void vApiFile(void *vpCtx, const char *cpFileName, abool bStrict, abool bPppt);
169 void vApiString(void *vpCtx, const char *cpString, abool bStrict, abool bPppt);
171 
172 // the generator API - generate a parser from the SABNF grammar
178 void vApiOutput(void *vpCtx, const char *cpOutput);
180 void* vpApiOutputParser(void* vpCtx);
182 
343 #endif /* API_H_ */
vApiOpcodesToAscii
void vApiOpcodesToAscii(void *vpCtx, const char *cpFileName)
Display all opcodes in human-readable format.
Definition: api.c:328
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 gram...
Definition: output.c:152
api_attr::bFinite
abool bFinite
APG_TRUE if the rule is finite.
Definition: api.h:72
vApiAttrsToAscii
void vApiAttrsToAscii(void *vpCtx, const char *cpMode, const char *cpFileName)
Display all rule attributes.
Definition: attributes.c:220
vApiPpptSize
void vApiPpptSize(void *vpCtx, pppt_size *spSize)
Compute the size of the PPPT maps and the number of bytes for the entire table.
Definition: pppt.c:246
vApiInClear
void vApiInClear(void *vpCtx)
Clears the input and related memory.
Definition: input.c:61
api_attr::bEmpty
abool bEmpty
APG_TRUE if the rule can be empty.
Definition: api.h:73
vApiInValidate
void vApiInValidate(void *vpCtx, abool bStrict)
Scans the input SABNF grammar for invalid characters and line ends.
Definition: input.c:204
vApiString
void vApiString(void *vpCtx, const char *cpString, abool bStrict, abool bPppt)
Quicky way to generate a parser from a grammar string.
Definition: api.c:544
pppt_size::luiMapSize
luint luiMapSize
The size, in bytes, of a single PPPT table entry (map).
Definition: api.h:86
vApiOpcodes
void vApiOpcodes(void *vpCtx)
Parse the SABNF grammar and translate its AST into opcodes for all the rules.
Definition: semantics.c:64
api_attr::uiMRGroup
aint uiMRGroup
the group number, if this is a member of a mutually-recursive group (there may be multiple groups)
Definition: api.h:77
vApiFile
void vApiFile(void *vpCtx, const char *cpFileName, abool bStrict, abool bPppt)
Quicky way to generate a parser from a grammar file.
Definition: api.c:517
api_attr::bNested
abool bNested
APG_TRUE if the rule is nested recursive.
Definition: api.h:69
api_attr
The recursive attributes of a single SABNF grammra rule.
Definition: api.h:67
pppt_size::luiAcharMax
luint luiAcharMax
The maximum character size in the grammar alphabet.
Definition: api.h:85
api_attr::cpRuleName
const char * cpRuleName
the rule name for these attributes
Definition: api.h:74
vApiRulesToHtml
void vApiRulesToHtml(void *vpCtx, const char *cpFileName)
Display the grammar rules in human-readable, HTML format.
Definition: api.c:132
aint
uint_fast32_t aint
The APG parser's unsigned integer type.
Definition: apg.h:79
vApiRulesToAscii
void vApiRulesToAscii(void *vpCtx, const char *cpMode, const char *cpFileName)
Display rules and UDTs in human-readable format in ASCII format.
Definition: api.c:257
pppt_size::luiMaps
luint luiMaps
The number of maps needed.
Definition: api.h:87
vApiSyntax
void vApiSyntax(void *vpCtx, abool bStrict)
Parse the SABNF grammar to validate that the grammar structure is valid.
Definition: syntax.c:51
vpApiCtor
void * vpApiCtor(exception *spEx)
Construct an API component context (object).
Definition: api.c:55
exception
A structure to describe the type and location of a caught exception.
Definition: exception.h:47
pppt_size::luiTableSize
luint luiTableSize
The memory requirement, in bytes, of the full table.
Definition: api.h:88
luint
uintmax_t luint
luint is used to cast integers suitable for the %"PRIuMAX" printf format.
Definition: apg.h:133
vpApiOutputParser
void * vpApiOutputParser(void *vpCtx)
Generate a parser object directly from the specified SABNF grammar.
Definition: output.c:217
api_attr::uiRecursiveType
aint uiRecursiveType
ID_ATTR_N, ID_ATTR_R, ID_ATTR_MR, ID_ATTR_NMR, or ID_ATTR_RMR.
Definition: api.h:76
bApiAttrs
abool bApiAttrs(void *vpCtx)
Computes the grammar's attributes.
Definition: attributes.c:79
pppt_size
Size information for the **P**artially-**P**redictive **P**arsing **T**ables (PPPT) data.
Definition: api.h:83
api_attr::bLeft
abool bLeft
APG_TRUE if the rule is left recursive.
Definition: api.h:68
api_attr::bRight
abool bRight
APG_TRUE if the rule is right recursive.
Definition: api.h:70
cpApiInFile
const char * cpApiInFile(void *vpCtx, const char *cpFileName)
Reads an SABNF grammar byte stream from a file.
Definition: input.c:117
api_attr::bCyclic
abool bCyclic
APG_TRUE if the rule is cyclic.
Definition: api.h:71
vApiDtor
void vApiDtor(void *vpCtx)
The API component destructor.
Definition: api.c:84
pppt_size::luiAcharMin
luint luiAcharMin
The minimum character size in the grammar alphabet.
Definition: api.h:84
vApiAttrsErrorsToAscii
void vApiAttrsErrorsToAscii(void *vpCtx, const char *cpMode, const char *cpFileName)
Display all rule attributes with errors.
Definition: attributes.c:268
vApiInToAscii
void vApiInToAscii(void *vpCtx, const char *cpFileName)
Display the input lines with line numbers and character offsets.
Definition: input.c:261
cpApiInString
const char * cpApiInString(void *vpCtx, const char *cpString)
Reads an SABNF grammar byte stream from a string.
Definition: input.c:165
abool
uint8_t abool
abool is the APG bool type.
Definition: apg.h:140
vApiInToHtml
void vApiInToHtml(void *vpCtx, const char *cpFileName, const char *cpTitle)
Display the input lines with line numbers and character offsets.
Definition: input.c:319
bApiValidate
abool bApiValidate(void *vpCtx)
Validates an API context pointer.
Definition: api.c:104
vpApiGetErrorLog
void * vpApiGetErrorLog(void *vpCtx)
Get the internal message log.
Definition: api.c:117
api_attr::uiRuleIndex
aint uiRuleIndex
the index of the rule for these attributes
Definition: api.h:75
vApiPppt
void vApiPppt(void *vpCtx, char **cppProtectedRules, aint uiProtectedRules)
Compute the Partially-Predictive Parsing Tables.
Definition: pppt.c:101
APG Version 7.0 is licensed under the 2-Clause BSD License,
an Open Source Initiative Approved License.