page_util_peg(n)					      Parser generator tools						  page_util_peg(n)

__________________________________________________________________________________________________________________________________________________

NAME

       page_util_peg - page PEG transformation utilities

SYNOPSIS

       package require page::util::peg	?0.1?

       package require snit

       ::page::util::peg::symbolNodeOf tree node

       ::page::util::peg::symbolOf tree node

       ::page::util::peg::updateUndefinedDueRemoval tree

       ::page::util::peg::flatten treequery tree

       ::page::util::peg::getWarnings tree

       ::page::util::peg::printWarnings msg

       ::page::util::peg::peOf tree eroot

       ::page::util::peg::printTclExpr pe

_________________________________________________________________

DESCRIPTION

       This  package  provides a few common operations to PEG transformations.	They assume a Normalized PE Grammar Tree as input, see the package
       page::util::norm::peg, possibly augmented with attributes coming from transformations not in conflict with the base definition.

API

       ::page::util::peg::symbolNodeOf tree node
	      Given an arbitrary expression node in the AST tree it determines the node (itself or an ancestor) containing the name of the nonter-
	      minal  symbol  the  node	belongs to, and returns its id. The result is either the root of the tree (for the start expression), or a
	      definition node.

       ::page::util::peg::symbolOf tree node
	      As ::page::util::peg::symbolNodeOf, but returns the symbol name instead of the node.

       ::page::util::peg::updateUndefinedDueRemoval tree
	      The removal of nodes in the AST tree can cause symbols to lose one or more users.

		   A used by B and C,
		   B is reachable,
		   C is not,

		   so A now loses the node in the expression for C calling it,
		   or rather, not calling it anymore.

	      This command updates the cross-references and which nonterminals are now undefined.

       ::page::util::peg::flatten treequery tree
	      This commands flattens nested sequence and choice operators in the AST tree, re-using the treeql object treequery to run	the  query
	      determining which nodes to cut.

       ::page::util::peg::getWarnings tree
	      This  command looks at the attributes of the AST tree for problems with the grammar and issues warnings. They do not prevent us from
	      writing the grammar, but still represent problems with it the user should be made aware of.

	      The result of the command is a dictionary mapping nonterminal names to their associated warnings.

       ::page::util::peg::printWarnings msg
	      The argument of the command is a dictionary mapping nonterminal names to their associated warnings, as generated	by,  for  example,
	      the command ::page::util::peg::getWarnings.

	      The  warnings  contained	therein  are formatted and then printed via the log command page_info. This means that this command can be
	      used only from within a plugin managed by the package page::pluginmgr.

       ::page::util::peg::peOf tree eroot
	      This command converts the parsing expression starting at the node eroot in the AST tree into a nested list. The exact syntax of this
	      list specified by the package grammar::peg.

       ::page::util::peg::printTclExpr pe
	      This  command  converts  the  parsing  expression  contained  in the nested list pe into a Tcl string which can be placed into a Tcl
	      script.  See the package grammar::peg for the exact syntax of pe.

BUGS, IDEAS, FEEDBACK
       This document, will undoubtedly contain bugs and other problems.  Please report such in	the  category  page  of  the  Tcllib  SF  Trackers
       [http://sourceforge.net/tracker/?group_id=12883].  Please also report any ideas for enhancements you may have.

KEYWORDS

       PEG, page, parser generator, parsing expression grammar, text processing, transformation

CATEGORY

       Page Parser Generator

COPYRIGHT

       Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>

page									1.0							  page_util_peg(n)