bionic (3) page_util_peg.3tcl.gz

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>