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