java.lang.Object
- apg.Ast

public class Ast
extends java.lang.Object

A class representation of the parser-generated Abstract Syntax Tree (AST).

The functions in this class allow the user to define which nodes appear in the AST, traversal of the AST performing user-defined callback functions for translation of the parsed sentence, and output of the AST in native or XML format.

With the XML format the user is freed from the APG translation convention and may use the XML parser of his/her choice for translation. The XML generated is valid but has no Document Type Definition (DTD). The structure of an XML AST is:

 <?xml version="1.0" encoding="UTF-8"?>
 <AST_ROOT id="6" depth="0">
 <records thisRecord="0" oppositeRecord="105"/>
 <phrase length="22">the entire input string</phrase>
 <node-name id="4" depth="1">
 <records thisRecord="1" oppositeRecord="9"/>
 <phrase length="25">text of recognized phrase</phrase>
 [child nodes]
 <records thisRecord="9" oppositeRecord="1"/>
 </node-name>
 <records thisRecord="105" oppositeRecord="0"/>
 </AST_ROOT>

 open tag:
 node-name - the grammar rule or UDT name
 id        - the grammar identifier of the rule or UDT
 depth     - the AST tree depth of the node
 records: there are two AST records for each node, pre-branch and post-branch
 pre-branch record:
 thisRecord     - the record number of the pre-branch record
 oppositeRecord - the record number of the post-branch record
 phrase: content is the text of the phrase recognized by this node.
 length: the number of characters in the phrase
 post-branch record:
 thisRecord     - the record number of the post-branch record
 oppositeRecord - the record number of the pre-branch record
 close tag:

 Notes:
 1. Only UTF-8 encoding is used.
 2. The root node is always AST_ROOT. This is generated to satisfy the
 XML requirement of a root node that is the parent of all other nodes.
 If the start rule is not included in the AST, this requirement is
 not otherwise guaranteed. The underscore insures that the name
 will never conflict with any rule or UTD name.
 3. The "thisRecord/oppositeRecord" numbers are often useful for locating the opposite
 record, especially when there are a large number of child nodes between them.
 4. The phrase text is displayed in UTF-8 encoding. Only the ASCII characters
 newline (10) and printing characters (32-126) are used.
 XML character entity notation is used only for the pre-defined entity characters.
 The character reference notation, &#xhhhh;, is used for all
 non-newline control characters and all other non-printing characters.

Nested Class Summary

Nested Classes
Modifier and Type	Class	Description
`static class`	`Ast.AstCallback`	The base class for all AST callback functions.
`class`	`Ast.CallbackData`	The parser provisions each callback function with an instance of this class.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`void`	`display(java.io.PrintStream out)`	Display the AST in native APG format.
`void`	`display(java.io.PrintStream out, boolean xml)`	Display the AST in native APG format or XML format.
`void`	`enableRuleNode(int id, boolean enable)`
`void`	`enableUdtNode(int id, boolean enable)`
`void`	`setMyData(java.lang.Object data)`
`void`	`setRootCallback(Ast.AstCallback callback)`	Ast assigns a root node to each AST named AST_ROOT.
`void`	`setRuleCallback(int id, Ast.AstCallback callback)`	Used to set a callback function for the identified rule.
`void`	`setUdtCallback(int id, Ast.AstCallback callback)`	Used to set a callback function for the identified UDT.
`void`	`translateAst()`	Traverse the AST and call the user-defined callback functions at each node.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - setRootCallback
```
public void setRootCallback(Ast.AstCallback callback)
```
    Ast assigns a root node to each AST named AST_ROOT. The underscore insures that it will never conflict with an node name. The AST and its XML representation is always required to have a root node that is the last ancestor of every other node in the tree. Since the user may choose not to have the start rule in the AST, an assigned root node is necessary.
    With this function the user may assign a callback function for the root node.
    
    Parameters:
    
    callback - the callback function to attach to the root node.
  - setRuleCallback
```
public void setRuleCallback(int id,
                            Ast.AstCallback callback)
                     throws java.lang.Exception
```
    Used to set a callback function for the identified rule.
    
    Parameters:
    
    id - identifier of the rule to set the callback for. This is the id assigned to the rule in the generated Grammar class with the ruleID() function.
    
    callback - the user-defined callback function for this rule node. Must be an extension of the AstCallback class.
    
    Throws:
    
    java.lang.Exception - Exceptions are thrown if the id is out of range, 0-(ruleCount - 1) or id this rule node has not been set (@see enableRuleNode(int, boolean))
  - setUdtCallback
```
public void setUdtCallback(int id,
                           Ast.AstCallback callback)
                    throws java.lang.Exception
```
    Used to set a callback function for the identified UDT.
    
    Parameters:
    
    id - identifier of the rule to set the callback for. This is the id assigned to the rule in the generated Grammar class with the udtID() function.
    
    callback - the user-defined callback function for this rule node. Must be an extension of the AstCallback class.
    
    Throws:
    
    java.lang.Exception - Exceptions are thrown if the id is out of range, 0-(udtCount - 1) or id this UDT node has not been set (@see enableUdtNode(int, boolean))
  - enableRuleNode
```
public void enableRuleNode(int id,
                           boolean enable)
                    throws java.lang.Exception
```
    Parameters:
    
    id - identifier of the rule to be enabled in the AST.
    
    enable - if true, the rule node will be retained in the AST, if false, the rule node will never appear in the AST.
    
    Throws:
    
    java.lang.Exception - Exceptions are thrown if the id is out of range, 0-(ruleCount - 1)
  - enableUdtNode
```
public void enableUdtNode(int id,
                          boolean enable)
                   throws java.lang.Exception
```
    Parameters:
    
    id - identifier of the UDT to be enabled in the AST.
    
    enable - if true, the UDT node will be retained in the AST, if false, the UDT node will never appear in the AST.
    
    Throws:
    
    java.lang.Exception - Exceptions are thrown if the id is out of range, 0-(udtCount - 1)
  - setMyData
```
public void setMyData(java.lang.Object data)
```
    Parameters:
    
    data - any user-defined class object or null.
  - translateAst
```
public void translateAst()
```
    Traverse the AST and call the user-defined callback functions at each node. Nodes must have been identified with a call to enableRuleNode() or enableUdtNode(). Additionally, callback functions must have been set for the nodes with calls to setRuleCallback() or setUdtCallback();
    
    See Also:
    
    enableRuleNode(int, boolean), enableUdtNode(int, boolean), setRuleCallback(int, AstCallback), setUdtCallback(int, AstCallback)
  - display
```
public void display(java.io.PrintStream out)
```
    Display the AST in native APG format.
    
    Parameters:
    
    out - PrintStream to display the AST on.
  - display
```
public void display(java.io.PrintStream out,
                    boolean xml)
```
    Display the AST in native APG format or XML format.
    
    Parameters:
    
    out - PrintStream to display the AST on.
    
    xml - if true, format is XML, if false, format is native APG.

Class Ast

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

setRootCallback

setRuleCallback

setUdtCallback

enableRuleNode

enableUdtNode

setMyData

translateAst

display

display