Debian Codegraph @

src/interfaces/ecpg/preproc/README.parser

raw
1 ECPG's grammar (preproc.y) is built by parse.pl from the
2 backend's grammar (gram.y) plus various add-on rules.
3 Some notes:
4
5 1) Most input matching core grammar productions is simply converted
6 to strings and concatenated together to form the SQL string
7 passed to the server. This is handled mostly automatically,
8 as described below.
9 2) Some grammar rules need special actions that are added to or
10 completely override the default token-concatenation behavior.
11 This is controlled by ecpg.addons as explained below.
12 3) Additional grammar rules are needed for ECPG's own commands.
13 These are in ecpg.trailer, as is the "epilogue" part of preproc.y.
14 4) ecpg.header contains the "prologue" part of preproc.y, including
15 support functions, Bison options, etc.
16 5) Additional terminals added by ECPG must be defined in ecpg.tokens.
17 Additional nonterminals added by ECPG must be defined in ecpg.type,
18 but only if they have non-void result type, which most don't.
19
20 ecpg.header, ecpg.tokens, ecpg.type, and ecpg.trailer are just
21 copied verbatim into preproc.y at appropriate points.
22
23
24 In the pre-v18 implementation of ecpg, the strings constructed
25 by grammar rules were returned as the Bison result of each rule.
26 This led to a large number of effectively-identical rule actions,
27 which caused compilation-time problems with some versions of clang.
28 Now, rules that need to return a string are declared as having
29 void type (which in Bison means leaving out any %type declaration
30 for them). Instead, we abuse Bison's "location tracking" mechanism
31 to carry the string results, which allows a single YYLLOC_DEFAULT
32 call to handle the standard token-concatenation behavior for the
33 vast majority of the rules. Rules that don't need to do anything
34 else can omit a semantic action altogether. Rules that need to
35 construct an output string specially can do so, but they should
36 assign it to "@$" rather than the usual "$$"; also, to reference
37 the string value of the N'th input token, write "@N" not "$N".
38 (But rules that return something other than a simple string
39 continue to use the normal Bison notations.)
40
41
42 ecpg.addons contains entries that begin with a line like
43 ECPG: ruletype tokenlist
44 and typically have one or more following lines that are the code
45 for a grammar action. Any line not starting with "ECPG:" is taken
46 to be part of the code block for the preceding "ECPG:" line.
47
48 "tokenlist" identifies which gram.y production this entry affects.
49 It is simply a list of the target nonterminal and the input tokens
50 from the gram.y rule. For example, to modify the action for a
51 gram.y rule like this:
52 target: tokenA tokenB tokenC {...}
53 "tokenlist" would be "target tokenA tokenB tokenC". If we want to
54 modify a non-first alternative for a nonterminal, we still write the
55 nonterminal. For example, "tokenlist" should be "target tokenD tokenE"
56 to affect the second alternative in:
57 target: tokenA tokenB tokenC {...}
58 | tokenD tokenE {...}
59
60 "ruletype" is one of:
61
62 a) "block" - the automatic action that parse.pl would create is
63 completely overridden. Instead the entry's code block is emitted.
64 The code block must include the braces ({}) needed for a Bison action.
65
66 b) "addon" - the entry's code block is inserted into the generated
67 action, ahead of the automatic token-concatenation code.
68 In this case the code block need not contain braces, since
69 it will be inserted within braces.
70
71 c) "rule" - the automatic action is emitted, but then the entry's
72 code block is added verbatim afterwards. This typically is
73 used to add new alternatives to a nonterminal of the core grammar.
74 For example, given the entry:
75 ECPG: rule target tokenA tokenB tokenC
76 | tokenD tokenE { custom_action; }
77 what will be emitted is
78 target: tokenA tokenB tokenC { automatic_action; }
79 | tokenD tokenE { custom_action; }
80
81 Multiple "ECPG:" entries can share the same code block, if the
82 same action is needed for all. When an "ECPG:" line is immediately
83 followed by another one, it is not assigned an empty code block;
84 rather the next nonempty code block is assumed to apply to all
85 immediately preceding "ECPG:" entries.
86
87 In addition to the modifications specified by ecpg.addons,
88 parse.pl contains some tables that list backend grammar
89 productions to be ignored or modified.
90
91 Nonterminals that construct strings (as described above) should be
92 given void type, which is parse.pl's default assumption for
93 nonterminals found in gram.y. If the result should be of some other
94 type, make an entry in parse.pl's %replace_types table. %replace_types
95 can also be used to suppress output of a nonterminal's rules
96 altogether (in which case ecpg.trailer had better provide replacement
97 rules, since the nonterminal will still be referred to elsewhere).