com.coasttocoastresearch.apg
Class Trace

java.lang.Object
  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.