1[comment {-*- tcl -*- doctools manpage}]
2[manpage_begin page_util_peg n 1.0]
3[copyright {2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>}]
4[moddesc   {Parser generator tools}]
5[titledesc {page PEG transformation utilities}]
6[category  {Page Parser Generator}]
7[require page::util::peg [opt 0.1]]
8[require snit]
9[keywords page {parsing expression grammar} {parser generator} {text processing}]
10[keywords PEG transformation]
11[description]
12[para]
13
14This package provides a few common operations to PEG transformations.
15They assume a [term {Normalized PE Grammar Tree}] as input, see the
16package [package page::util::norm::peg], possibly augmented with
17attributes coming from transformations not in conflict with the base
18definition.
19
20[para]
21
22[section API]
23
24[list_begin definitions]
25[call [cmd ::page::util::peg::symbolNodeOf] [arg tree] [arg node]]
26
27Given an arbitrary expression [arg node] in the AST [arg tree] it
28determines the node (itself or an ancestor) containing the name of the
29nonterminal symbol the node belongs to, and returns its id. The result
30is either the root of the tree (for the start expression), or a
31definition node.
32
33[call [cmd ::page::util::peg::symbolOf] [arg tree] [arg node]]
34
35As [cmd ::page::util::peg::symbolNodeOf], but returns the symbol name
36instead of the node.
37
38[call [cmd ::page::util::peg::updateUndefinedDueRemoval] [arg tree]]
39
40The removal of nodes in the AST [arg tree] can cause symbols to lose
41one or more users.
42
43[example {
44	A used by B and C,
45	B is reachable,
46	C is not,
47
48	so A now loses the node in the expression for C calling it,
49	or rather, not calling it anymore.
50}]
51
52This command updates the cross-references and which nonterminals are
53now undefined.
54
55[call [cmd ::page::util::peg::flatten] [arg treequery] [arg tree]]
56
57This commands flattens nested sequence and choice operators in the AST
58[arg tree], re-using the [package treeql] object [arg treequery] to
59run the query determining which nodes to cut.
60
61[call [cmd ::page::util::peg::getWarnings] [arg tree]]
62
63This command looks at the attributes of the AST [arg tree] for
64problems with the grammar and issues warnings. They do not prevent us
65from writing the grammar, but still represent problems with it the
66user should be made aware of.
67
68[para]
69
70The result of the command is a dictionary mapping nonterminal names to
71their associated warnings.
72
73[call [cmd ::page::util::peg::printWarnings] [arg msg]]
74
75The argument of the command is a dictionary mapping nonterminal names
76to their associated warnings, as generated by, for example, the
77command [cmd ::page::util::peg::getWarnings].
78
79[para]
80
81The warnings contained therein are formatted and then printed via the
82log command [cmd page_info]. This means that this command can be used
83only from within a plugin managed by the package
84[package page::pluginmgr].
85
86[call [cmd ::page::util::peg::peOf] [arg tree] [arg eroot]]
87
88This command converts the parsing expression starting at the node
89[arg eroot] in the AST [arg tree] into a nested list. The exact syntax
90of this list specified by the package [package grammar::peg].
91
92[call [cmd ::page::util::peg::printTclExpr] [arg pe]]
93
94This command converts the parsing expression contained in the nested
95list [arg pe] into a Tcl string which can be placed into a Tcl script.
96
97See the package [package grammar::peg] for the exact syntax of
98[arg pe].
99
100[list_end]
101
102[section {BUGS, IDEAS, FEEDBACK}]
103
104This document, will undoubtedly contain bugs and other problems.
105
106Please report such in the category [emph page] of the
107[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}].
108
109Please also report any ideas for enhancements you may have.
110
111[manpage_end]
112