Java APG, Version 1.0
Author Lowell D. Thomas
Copyright © Coast to Coast Research, Inc. 2011

com.coasttocoastresearch.apg
Class Trace

java.lang.Object
  extended by com.coasttocoastresearch.apg.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
 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

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.

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.

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.

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.

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.

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.


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.

Java APG, Version 1.0
Author Lowell D. Thomas
Copyright © Coast to Coast Research, Inc. 2011

Licence Notification

All the software in this distribution is free software:
you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program in the COPYING file. If not, see GPL, Version 2
or GPL, Version 3 or write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.