| 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). |