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 nonterminal 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, and the package it describes,  will  undoubtedly  contain  bugs  and  other
       problems.    Please   report   such   in   the   category  page  of  the  Tcllib  Trackers
       [http://core.tcl.tk/tcllib/reportlist].  Please also report any ideas for enhancements you
       may have for either package and/or documentation.

       When proposing code changes, please provide unified diffs, i.e the output of diff -u.

       Note further that attachments are strongly preferred over inlined patches. Attachments can
       be made by going to the Edit form of the ticket immediately after its creation,  and  then
       using the left-most button in the secondary navigation bar.

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>