ecpg: clean up documentation of parse.pl, and add more input checking.
authorTom Lane <[email protected]>
Mon, 14 Oct 2024 17:29:36 +0000 (13:29 -0400)
committerTom Lane <[email protected]>
Mon, 14 Oct 2024 17:29:36 +0000 (13:29 -0400)
commit00b0e7204d530d878b188254b62008651030921a
tree377a49a32deabeeabbec9aa9899dc21d69135670
parent7be4ba4a9d560bc6dfb19749ad58cfc1a04d3a7c
ecpg: clean up documentation of parse.pl, and add more input checking.

README.parser is the user's manual, such as it is, for parse.pl.
It's rather poorly written if you ask me; so try to improve it.
(More could be written here, but this at least covers the same
info in a more organized fashion.)

Also, the single solitary line of usage info in parse.pl itself
was a lie.  Replace.

Add some error checks that the ecpg.addons entries meet the syntax
rules set forth in README.parser.  One of them didn't, but
accidentally worked anyway because the logic in include_addon is
such that 'block' is the default behavior.

Also add a cross-check that each ecpg.addons entry is matched exactly
once in the backend grammar.  This exposed that there are two dead
entries there --- they are dead because the %replace_types table in
parse.pl causes their nonterminals to be ignored altogether.
Removing them doesn't change the generated preproc.y file.

(This implies that check_rules.pl is completely worthless and should
be nuked: it adds build cycles and maintenance effort while failing
to reliably accomplish its one job of detecting dead rules.  I'll
do that separately.)

Discussion: https://postgr.es/m/2011420.1713493114@sss.pgh.pa.us
src/interfaces/ecpg/preproc/README.parser
src/interfaces/ecpg/preproc/ecpg.addons
src/interfaces/ecpg/preproc/parse.pl