Version 7.0
Copyright © 2021 Lowell D. Thomas
APG
… an ABNF Parser Generator
apgex.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 * *************************************************************************************/
37 #ifndef APGEX_H_
38 #define APGEX_H_
39 
40 #include "../api/api.h"
41 
45 typedef struct{
48 } apgex_phrase;
49 
58 typedef struct{
59  const char* cpRuleName;
63 } apgex_rule;
64 
72 typedef struct{
85 } apgex_result;
86 
94 typedef struct{
95  void* vpParser;
96  void* vpAst;
97  void* vpTrace;
98  const char* cpFlags;
99  const char* cpPattern;
103  apgex_phrase sLastMatch;
117 
125 typedef apg_phrase (*pfn_replace)(apgex_result* spResult, apgex_properties* spProperties, void* vpUser);
126 
128 void* vpApgexCtor(exception* spEx);
130 void vApgexDtor(void* vpCtx);
132 
134 void vApgexPattern(void* vpCtx, const char* cpPattern, const char* cpFlags);
136 void vApgexPatternFile(void* vpCtx, const char* cpFileName, const char* cpFlags);
137 void vApgexPatternParser(void* vpCtx, void* vpParser, const char* cpFlags);
139 
141 void vApgexEnableRules(void* vpCtx, const char* cpNames, abool bEnable);
143 void vApgexDefineUDT(void* vpCtx, const char* cpName, parser_callback pfnUdt);
144 void vApgexSetLastIndex(void* vpCtx, aint uiLastIndex);
146 
148 apgex_result sApgexExec(void* vpCtx, apg_phrase* spSource);
150 apg_phrase sApgexReplace(void* vpCtx, apg_phrase* spSource, apg_phrase* spReplacement);
151 apg_phrase sApgexReplaceFunc(void* vpCtx, apg_phrase* spSource, pfn_replace pfnFunc, void* vpUser);
152 apg_phrase* spApgexSplit(void* vpCtx, apg_phrase* spSource, aint uiLimit, aint* uipCount);
153 abool bApgexTest(void* vpCtx, apg_phrase* spSource);
155 void* vpApgexGetAst(void* vpCtx);
156 void* vpApgexGetTrace(void* vpCtx);
157 void* vpApgexGetParser(void* vpCtx);
159 
161 void vApgexDisplayResult(void* vpCtx, apgex_result* spResult, const char* cpFileName);
163 void vApgexDisplayPhrase(void* vpCtx, apgex_phrase* spPhrase, const char* cpFileName);
164 void vApgexDisplayProperties(void* vpCtx, apgex_properties* spProperties, const char* cpFileName);
165 void vApgexDisplayPatternErrors(void* vpCtx, const char* cpFileName);
167 
168 void vApgexBkrCheck(exception* spEx);
342 #endif /* APGEX_H_ */
apgex_result::uiNodeHits
aint uiNodeHits
The number of parser node hits.
Definition: apgex.h:83
vApgexDisplayResult
void vApgexDisplayResult(void *vpCtx, apgex_result *spResult, const char *cpFileName)
Display the complete results from a pattern match.
Definition: apgex.c:1129
apgex_rule::spPhrases
apgex_phrase * spPhrases
The list of matched phrases. Any given rule or UDT may have multiple matched sub-phrases.
Definition: apgex.h:60
spApgexSplit
apg_phrase * spApgexSplit(void *vpCtx, apg_phrase *spSource, aint uiLimit, aint *uipCount)
Split a phrase into an array of sub-phrases.
Definition: apgex.c:648
vApgexPatternParser
void vApgexPatternParser(void *vpCtx, void *vpParser, const char *cpFlags)
Define the SABNF pattern with a user-created parser.
Definition: apgex.c:444
apgex_rule::uiPhraseCount
aint uiPhraseCount
The number of matched sub-phrases for this rule/UDT.
Definition: apgex.h:61
vpApgexCtor
void * vpApgexCtor(exception *spEx)
The phrase-matching engine object constructor.
Definition: apgex.c:239
apgex_properties::bTraceMode
abool bTraceMode
True if the t flag is set in the cpFlags string.
Definition: apgex.h:114
apgex_properties
Detailed information about the apgex object after vApgexPattern() has been called.
Definition: apgex.h:94
apgex_properties::sRightContext
apgex_phrase sRightContext
The right context of the last match - that is the phrase suffix to the matched phrase.
Definition: apgex.h:107
apgex_properties::bStickyMode
abool bStickyMode
True if the y flag is set prior to any occurrence of g in the cpFlags string.
Definition: apgex.h:113
vApgexDisplayProperties
void vApgexDisplayProperties(void *vpCtx, apgex_properties *spProperties, const char *cpFileName)
Display the object's properties.
Definition: apgex.c:1028
apgex_result::uiTreeDepth
aint uiTreeDepth
The maximum parsing tree depth.
Definition: apgex.h:84
apgex_result
The phrase matching results.
Definition: apgex.h:72
apgex_properties::vpParser
void * vpParser
Pointer to the parser object context.
Definition: apgex.h:95
apgex_rule::uiIndex
aint uiIndex
The rule or UDT grammar index.
Definition: apgex.h:62
apgex_properties::bDefaultMode
abool bDefaultMode
True if the cpFlags parameter in vApgexPattern() is NULL or empty.
Definition: apgex.h:110
bApgexTest
abool bApgexTest(void *vpCtx, apg_phrase *spSource)
Report only success or failure on a pattern match.
Definition: apgex.c:752
apgex_properties::cpFlags
const char * cpFlags
The original string of flags from vApgexPattern().
Definition: apgex.h:98
vApgexSetLastIndex
void vApgexSetLastIndex(void *vpCtx, aint uiLastIndex)
Sets the index of the character in the source where the pattern-match search is to begin.
Definition: apgex.c:874
parser_callback
void(* parser_callback)(callback_data *spData)
User-written callback function prototype.
Definition: parser.h:178
apgex_result::spLeftContext
apgex_phrase * spLeftContext
The phrase prefix.
Definition: apgex.h:74
vApgexDtor
void vApgexDtor(void *vpCtx)
The phrase-matching engine object destructor.
Definition: apgex.c:295
sApgexExec
apgex_result sApgexExec(void *vpCtx, apg_phrase *spSource)
Attempt a pattern match on the source array of APG alphabet characters.
Definition: apgex.c:479
apgex_result::uiRuleCount
aint uiRuleCount
The number of combined rules and UDTs in the pattern.
Definition: apgex.h:82
aint
uint_fast32_t aint
The APG parser's unsigned integer type.
Definition: apg.h:79
vApgexBkrCheck
void vApgexBkrCheck(exception *spEx)
Back referencing check.
Definition: apgex.c:279
sApgexProperties
apgex_properties sApgexProperties(void *vpCtx)
Get a copy of the object's properties.
Definition: apgex.c:888
apgex_result::spResult
apgex_phrase * spResult
The matched phrase. NULL if no match.
Definition: apgex.h:73
apgex_properties::uiLastIndex
aint uiLastIndex
The index of the character in the input string where the attempted pattern match begins....
Definition: apgex.h:108
sApgexReplaceFunc
apg_phrase sApgexReplaceFunc(void *vpCtx, apg_phrase *spSource, pfn_replace pfnFunc, void *vpUser)
Replace the matched phrase with a user-generated phrase.
Definition: apgex.c:581
pfn_replace
apg_phrase(* pfn_replace)(apgex_result *spResult, apgex_properties *spProperties, void *vpUser)
Prototype for the replacement function used by sApgexReplaceFunc().
Definition: apgex.h:125
vpApgexGetAst
void * vpApgexGetAst(void *vpCtx)
Get a pointer to the AST object's context.
Definition: apgex.c:957
exception
A structure to describe the type and location of a caught exception.
Definition: exception.h:47
apgex_result::uiLastIndex
aint uiLastIndex
The last index following the last pattern match attempt.
Definition: apgex.h:81
apg_phrase
Defines a pointer to an achar array plus its length. That is, a phrase as is often used by APG.
Definition: lib.h:60
apgex_rule::cpRuleName
const char * cpRuleName
The rule or UDT name.
Definition: apgex.h:59
apgex_properties::bTraceHtmlMode
abool bTraceHtmlMode
True if the th flags ar set for HTML trace output in the cpFlags string.
Definition: apgex.h:115
vApgexDisplayPatternErrors
void vApgexDisplayPatternErrors(void *vpCtx, const char *cpFileName)
Definition: apgex.c:1180
apgex_properties::sLastSource
apg_phrase sLastSource
The last source or input string as a phrase - may be different from original if sApgexReplace() or sA...
Definition: apgex.h:102
vApgexEnableRules
void vApgexEnableRules(void *vpCtx, const char *cpNames, abool bEnable)
Enable or disable specified rule and/or UDT names for phrase capture.
Definition: apgex.c:786
apgex_properties::cpPattern
const char * cpPattern
Internally preserve copy of the SABNF grammar defining the string to match. NULL if the pattern is de...
Definition: apgex.h:99
vApgexDefineUDT
void vApgexDefineUDT(void *vpCtx, const char *cpName, parser_callback pfnUdt)
Define the callback function for a User-Defined Terminal (UDT).
Definition: apgex.c:1222
apgex_properties::sOriginalSource
apg_phrase sOriginalSource
The original source or input string as a phrase.
Definition: apgex.h:101
apgex_properties::bGlobalMode
abool bGlobalMode
True if the g flag is set prior to any occurrence of y in the cpFlags string.
Definition: apgex.h:111
apgex_result::spRightContext
apgex_phrase * spRightContext
The phrase suffix.
Definition: apgex.h:77
vpApgexGetParser
void * vpApgexGetParser(void *vpCtx)
Get a pointer to the parser object's context.
Definition: apgex.c:1009
apgex_properties::vpTrace
void * vpTrace
Pointer to the trace object context. NULL unless the t flag is used.
Definition: apgex.h:97
abool
uint8_t abool
abool is the APG bool type.
Definition: apg.h:140
vpApgexGetTrace
void * vpApgexGetTrace(void *vpCtx)
Get a pointer to the trace object's context.
Definition: apgex.c:984
apgex_rule
Information about each rule or UDT in the SABNF pattern.
Definition: apgex.h:58
vApgexDisplayPhrase
void vApgexDisplayPhrase(void *vpCtx, apgex_phrase *spPhrase, const char *cpFileName)
Display the object's properties.
Definition: apgex.c:1098
sApgexReplace
apg_phrase sApgexReplace(void *vpCtx, apg_phrase *spSource, apg_phrase *spReplacement)
Replace the matched phrase with a specified phrase.
Definition: apgex.c:528
vApgexPattern
void vApgexPattern(void *vpCtx, const char *cpPattern, const char *cpFlags)
Prepare a phrase-matching parser for the given pattern.
Definition: apgex.c:378
apgex_properties::sLeftContext
apgex_phrase sLeftContext
The left context of the last match - that is the phrase prefix to the matched phrase.
Definition: apgex.h:106
apgex_phrase::sPhrase
apg_phrase sPhrase
The matched phrase.
Definition: apgex.h:46
vApgexPatternFile
void vApgexPatternFile(void *vpCtx, const char *cpFileName, const char *cpFlags)
Reads the SABNF grammar defining the pattern from a file.
Definition: apgex.c:404
apgex_properties::vpAst
void * vpAst
Pointer to the AST object context. NULL unless the a flag is used.
Definition: apgex.h:96
apgex_properties::bPpptMode
abool bPpptMode
True if the p flag is set. The parser will use Partially-Predictive Parsing Tables.
Definition: apgex.h:112
apgex_phrase
The representation of a matched phrase.
Definition: apgex.h:45
apgex_result::spRules
apgex_rule * spRules
The phrases matched by all enabled rules and/or UDTs. NULL if no match.
Definition: apgex.h:80
apgex_phrase::uiPhraseOffset
aint uiPhraseOffset
Offset into the source string where the matched phrase begins.
Definition: apgex.h:47
APG Version 7.0 is licensed under the 2-Clause BSD License,
an Open Source Initiative Approved License.