Package apg

Class Trace

  • public class Trace
extends java.lang.Object
    The Trace class will display the exact path followed by the parser on its journey through the syntax tree. It will generate a detailed information record for every operator node the Parser visits (hits). Separate records are generated for the pre-branch node hit (just prior to visiting the branch below) and the post-branch node hit (just after visiting the branch below.)

    Methods are available for controlling which nodes to create records for and for displaying the records after the parse has completed. The enabling/disabling of operator nodes is incremental. A few examples will illustrate.

    Suppose you wanted to display all operator nodes except the UDT operator nodes. This could be accomplished with
    enableAllNodes(true);
    enableAllUdtNodes(false;)

    Or suppose you wanted to display only the operator nodes for rules named "alpha", with grammar id=3, and "beta", with grammar id=5
    enableAllNodes(false);
    enableRule(3, true);
    enableRule(5, true);

    Or suppose you wanted to display all operator nodes except for rules named "alpha", with grammar, id=3 and "beta", with grammar id=5
    enableAllNodes(true);
    enableRule(3, false);
    enableRule(5, false);

    Optionally, the trace records may be generated as an XML file. The user can then use his/her favorite XML parser to peruse the trace.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void enableAllNodes​(boolean enable)
      Enables or disables all operator nodes.
      void enableAllNonTerminals​(boolean enable)
      Enables or disables the tracing of all non-terminal operators.
      void enableAllRules​(boolean enable)
      Enables or disables the tracing of all rule name operators.
      void enableAllTerminals​(boolean enable)
      Enables or disables the tracing of all terminal operators.
      void enableAllUdts​(boolean enable)
      Enables or disables the tracing of all UDT operator nodes.
      void enableDefaultNodes()
      Resets the set of operator nodes to trace to the default set.
      void enableNode​(boolean enable, java.lang.String name)
      Enables or disables the tracing of the named nodes.
      void enableRule​(boolean enable, int id)
      Enables or disables the tracing of individual rule name operators.
      void enableUdt​(boolean enable, int id)
      Enables or disables the tracing of individual UDT operators.
      void enableXml​(boolean enabled)
      Enable or disable XML as the trace record format.
      void setOut​(java.io.PrintStream out)
      Sets the output device to record the trace records on.

      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • enableDefaultNodes

        public void enableDefaultNodes()
        Resets the set of operator nodes to trace to the default set. The default set is to trace all rule name and all UDT operator nodes only. All other operators are not trace.

      • enableAllNodes

        public void enableAllNodes​(boolean enable)
        Enables or disables all operator nodes.
        Parameters:
        enable - if true all operator nodes will be traced, if false none will be trace.

      • enableAllRules

        public void enableAllRules​(boolean enable)
        Enables or disables the tracing of all rule name operators.
        Parameters:
        enable - if true all rule name operators will be traced, if false no rule name operators will be trace.

      • enableAllUdts

        public void enableAllUdts​(boolean enable)
        Enables or disables the tracing of all UDT operator nodes.
        Parameters:
        enable - if true all UDT operator nodes will be traced, if false no UDT operators will be trace.

      • enableAllTerminals

        public void enableAllTerminals​(boolean enable)
        Enables or disables the tracing of all terminal operators. Terminal nodes are literal string operators (TLS), binary string operators (TBS) and character range operators (TRG)
        Parameters:
        enable - if true all terminal operators will be traced, if false no terminal operators will be trace.

      • enableAllNonTerminals

        public void enableAllNonTerminals​(boolean enable)
        Enables or disables the tracing of all non-terminal operators. Non-terminal operators are alternation operators (ALT), concatenation operators (CAT), repetition operators (REP), "and" syntactic predicate operators (AND) and "not" syntactic predicate operators (NOT)
        Parameters:
        enable - if true all non-terminal operators will be traced, if false no non-terminal operators will be traced.

      • enableNode

        public void enableNode​(boolean enable,
                       java.lang.String name)
                throws java.lang.Exception
        Enables or disables the tracing of the named nodes.
        Parameters:
        enable - if true the named operator nodes will be traced, if false the named operators will not be traced.
        name - name of the operator type to enable or disable
        "alt" enable/disable alternation (ALT) operators
        "cat" enable/disable concatenation (CAT) operators
        "rep" enable/disable repetition (REP) operators
        "and" enable/disable "and" syntactic predicate (AND) operators
        "not" enable/disable "not" syntactic predicate (NOT) operators
        Throws:
        java.lang.Exception - thrown if operator type name is unrecognized (none of the above)

      • enableRule

        public void enableRule​(boolean enable,
                       int id)
                throws java.lang.Exception
        Enables or disables the tracing of individual rule name operators.
        Parameters:
        enable - if true the named rule name operators will be traced, if false the named rule name operators will not be traced.
        id - the grammar id of the rule to enable/disable
        Throws:
        java.lang.Exception - thrown if the rule id is out of range

      • enableUdt

        public void enableUdt​(boolean enable,
                      int id)
               throws java.lang.Exception
        Enables or disables the tracing of individual UDT operators.
        Parameters:
        enable - if true the named UDT operators will be traced, if false the named UDT operators will not be traced.
        id - the grammar id of the UDT to enable/disable
        Throws:
        java.lang.Exception - thrown if the UDT id is out of range

      • enableXml

        public void enableXml​(boolean enabled)
        Enable or disable XML as the trace record format.
        Parameters:
        enabled - if true, XML format will be enabled, if false the native APG format will be used.

      • setOut

        public void setOut​(java.io.PrintStream out)
        Sets the output device to record the trace records on. They are not recorded in internal RAM memory.

        An example of the XML records is given here: 

         <?xml version="1.0" encoding="UTF-8"?>
 <TRACE_ROOT tag="0">
 <opcode tag="152" type="CAT" children="3">
 <input length="5">(a+b)</input>
 [child nodes]
 <state opcodeTag="152" match="true">MATCH</state>
 <phrase length="5">(a+b)</phrase>
 </opcode>
 </TRACE_ROOT>

 NOTES:
 1.0 Encoding is always UTF-8.
 2.0 A special root node "TRACE_ROOT" is always added to ensure a root node that
 is the parent of all other nodes.
 3.0 The pre-branch visit to the node displays two records:
 1) The <opcode> record, tag is the record number and type is the node type.
 2) The <input> record has the text of the remaining string to be parsed.
 4.0 The post-branch visit to the node displays two or three records:
 1) The <state> record, opcodeTag is the tag of the pre-branch <opcode>
 and match = true/false is the parser state.
 2) The <phrase> record gives the matched phrase, if match is true.
 3) The end tag </opcode>
        Parameters:
        out - the output device. The default device is System.out.