ParseNode (API documentation of hlt.language packages)
Date: 2013-01-30

hlt.language.syntax

## Class ParseNode

- java.lang.Object
- - hlt.language.syntax.ParseNode

- All Implemented Interfaces:
    Locatable
  Direct Known Subclasses:
    DynamicToken

      public class ParseNode
      extends java.lang.Object
      implements Locatable

  This class is the type of objects pushed on the semantic evaluation stack along with parser's states. It comes with two predefined attributes that may be used in a rule's semantic action: a numeric one (`nvalue`) of type `double`, and a symbolic one (`svalue`) of type `String`. If attributes of other types are needed, one may use the `%nodeclass` command for the appropriate symbol, which has for effect to make the type of the value it returns a subclass of this one containing the new fields.

  It is also the root of the parse tree which is built automatically when parsing is done with `GenericParser.parse(boolean)`.

  Version:
    Last modified on Sun Oct 21 01:57:23 2012 by hak
  Author:
    Hassan Aït-Kaci
  See Also:
    `GenericParser`
  Copyright:
    © by the author

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ParseNode()` Constructs an unititialized `ParseNode` object.
    `ParseNode(ParseNode node)` Constructs a `ParseNode` object that is a (shallow) copy of of the specified `ParseNode`.
    `ParseNode(ParserSymbol symbol)` Constructs a `ParseNode` object with its `symbol` field initialized to the specified parser symbol.
    `ParseNode(ParserSymbol symbol, double value)` Constructs a `ParseNode` object with its `symbol` field initialized to the specified parser symbol, and `nvalue` field initialized to the specified double value.
    `ParseNode(ParserSymbol symbol, int value)` Constructs a `ParseNode` object with its `symbol` field initialized to the specified parser symbol, and `nvalue` field initialized to the specified integer value.
    `ParseNode(ParserSymbol symbol, java.lang.String value)` Constructs a `ParseNode` object with its `symbol` field initialized to the specified parser symbol and `svalue` field initialized to the specified string.
    `ParseNode(java.lang.String value)` Constructs an anonymous `ParseNode` object (i.e., with a `null` symbol), and sets its `svalue` field to the specified string.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addAlternative(ParseNode alternative)` Add an alternative form for this ParseNode.
    `ArrayList` | `alternatives()` If non-null, this contains alternative forms of an ambiguous token.
    `int` | `associativity()` Returns the associativity value of this node.
    `ParseNode` | `child(int i)` If a parse tree has been built, this returns the `i`-th in the sequence of `ParseNode`s that are this node's constituents.
    `ArrayList` | `children()` When constructing the parse tree, this is the set of constituents.
    `ParseNode` | `copy()` Returns a new ParseNode that is a shallow copy of this ParseNode.
    `ParseNode` | `copy(ParseNode node)` Returns an almost complete copy of the specified node by copying the values of all its attributes except that of its `symbol`, `children`, and location `span`.
    `void` | `display()` Spawns a framed graphical display of the parse tree rooted in this node.
    `void` | `display(java.lang.String source)` Spawns a framed graphical display of the parse tree rooted in this node and corresponding to the specified source file.
    `boolean` | `equals(java.lang.Object other)` Two ParseNodes are considered equal iff they carry the same info.
    `ParseNode` | `firstChild()` If a parse tree has been built, this returns the first in the sequence of `ParseNode`s that are this node's constituents.
    `int` | `fixity()` Returns the fixity value of this node.
    `Location` | `getEnd()`
    `java.lang.String` | `getFile()` Returns the file name where this node's constituents start from if any; or `null`
    `int` | `getLineNumber()` Returns the line number in the input stream corresponding to the start location of this node's extent.
    `Span` | `getSpan()` Returns information to locate this node's extent in the input stream or `null`.
    `Location` | `getStart()`
    `boolean` | `hasAlternatives()` Returns `true` iff this ParseNode has one or more alternative forms.
    `boolean` | `hasChildren()` Returns `true` iff this node does not have any child.
    `boolean` | `hasValue()` Returns `true` iff this node carries a value (which is either in its `svalue` or `nvalue` field).
    `boolean` | `hasXmlForm()` Returns `true` iff `xmlForm()` is non-empty.
    `boolean` | `isEmptyNode()` Returns `true` iff this node is a null inner node (i.e., iff it corresponds to an empty derivation).
    `boolean` | `isEOI()`
    `boolean` | `isError()`
    `boolean` | `isInnerNode()` Returns `true` iff this node is an inner node in the parse tree (i.e., iff it corresponds to a nonterminal symbol).
    `boolean` | `isInteger()` Returns `true` iff this `ParseNode` is an integer number.
    `boolean` | `isLeafNode()` Returns `true` iff this node is a leaf in the parse tree (i.e., iff it corresponds to a terminal symbol or an anonymous symbol).
    `boolean` | `isLocated()`
    `boolean` | `isOperator()` Returns `true` iff this is a dynamic operator.
    `boolean` | `isTerminal()` Returns `true` iff this node corresponds to a terminal symbol.
    `boolean` | `isUnknown()`
    `ParseNode` | `lastChild()` If a parse tree has been built, this returns the last in the sequence of `ParseNode`s that are this node's constituents.
    `void` | `locate()` This method (by default empty) is invoked anytime this node's span is set.
    `java.lang.String` | `locationString()` Returns an explicit string for this node's location.
    `void` | `makeInteger(boolean isInteger)` Sets the integer flag to the given boolean argument (i.e., whenever this argument is `true`, this node's numerical value will be cast as an `int`).
    `java.lang.String` | `nodeInfo()` Returns a string representation of this node's information contents: its string form and its location if known.
    `int` | `numberOfChildren()` Returns the number of constituents of this node.
    `double` | `nvalue()` The number value of this node.
    `ParserOperator` | `operator()` If this is a dynamic operator, the actual specific operator.
    `int` | `precedence()` Returns the precedence value of this node.
    `void` | `setChildren(ArrayList children)`
    `Locatable` | `setEnd(Location location)`
    `ParseNode` | `setFile(java.lang.String file)` Sets the file name where this node's constituents are, and returns this parse node.
    `ParseNode` | `setLineNumber(int line)` Sets the line number in the input stream corresponding to this node's location extent start, and returns this parse node.
    `void` | `setNvalue(double nvalue)` Sets the number value of this node.
    `void` | `setOperator(ParserOperator operator)` Sets the operator.
    `Locatable` | `setSpan(ParseNode node)`
    `Locatable` | `setStart(Location location)`
    `void` | `setSvalue(java.lang.String svalue)` Sets the String value of this node.
    `void` | `setSymbol(ParserSymbol symbol)` Sets the grammar symbol this node stands for.
    `ParseNode` | `setXmlInfo(XmlInfo info)` Sets this parse node's XML info to the specified `info` and returns this node.
    `void` | `show()` Prints the parse tree rooted in this node on stdout.
    `void` | `show(int margin, java.io.PrintStream out)` Prints the parse tree rooted in this node on the specified output stream with the given initial margin.
    `void` | `show(java.io.PrintStream out)` Prints the parse tree rooted in this node on the specified output stream.
    `void` | `showXmlElement(org.jdom.Element element, java.io.PrintStream out)` Serializes the specified XML element on the specified output stream.
    `Span` | `span()` Returns information to locate this node's extent in the input stream.
    `java.lang.String` | `stringValue()` Returns the value carried by this node as a String.
    `java.lang.String` | `svalue()` The String value of this node.
    `ParserSymbol` | `symbol()` The grammar symbol this node stands for.
    `java.lang.String` | `toString()` Returns a string representation of this node, along, possibly, with all its alternatives if any.
    `org.jdom.Document` | `xmlDocument()` Returns the XML document associated with this parse node, if any, or `null` otherwise.
    `org.jdom.Document` | `xmlDocument(java.lang.String xmlroot, java.lang.String nsprefix, java.lang.String[] namespaces)` Returns the XML document associated with this parse node with a root element named as specified by `xmlroot` and `nsprefix` in the context of the namespaces declarations specified in `namespaces`.
    `ArrayList` | `xmlForm()` Returns the (possibly empty) list of XML elements associated with this parse node.
    `ArrayList` | `xmlify(org.jdom.Element root)` This method builds and returns the XML form of this parse node as a (possibly empty) `ArrayList`.

    - ### Methods inherited from class java.lang.Object

      `getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### ParseNode

          public ParseNode()

      Constructs an unititialized `ParseNode` object.

    - #### ParseNode

          public ParseNode(java.lang.String value)

      Constructs an anonymous `ParseNode` object (i.e., with a `null` symbol), and sets its `svalue` field to the specified string. This is used in `DynamicParser` when a symbol that has been read is not a known terminal symbol, but may be a potential dynamic operator.

    - #### ParseNode

          public ParseNode(ParserSymbol symbol)

      Constructs a `ParseNode` object with its `symbol` field initialized to the specified parser symbol. This is used by a `DynamicParser` reading a new token and wrapping it into a `DynamicToken` where it can be restored in its original for upon backtracking.
      See Also:
        `DynamicParser`, `DynamicToken`

    - #### ParseNode

          public ParseNode(ParserSymbol symbol,
                   double value)

      Constructs a `ParseNode` object with its `symbol` field initialized to the specified parser symbol, and `nvalue` field initialized to the specified double value.

    - #### ParseNode

          public ParseNode(ParserSymbol symbol,
                   int value)

      Constructs a `ParseNode` object with its `symbol` field initialized to the specified parser symbol, and `nvalue` field initialized to the specified integer value.

    - #### ParseNode

          public ParseNode(ParserSymbol symbol,
                   java.lang.String value)

      Constructs a `ParseNode` object with its `symbol` field initialized to the specified parser symbol and `svalue` field initialized to the specified string.

    - #### ParseNode

          public ParseNode(ParseNode node)

      Constructs a `ParseNode` object that is a (shallow) copy of of the specified `ParseNode`.

  - ### Method Detail

    - #### symbol

          public ParserSymbol symbol()

      The grammar symbol this node stands for.

    - #### setSymbol

          public void setSymbol(ParserSymbol symbol)

      Sets the grammar symbol this node stands for.

    - #### nvalue

          public double nvalue()

      The number value of this node.

    - #### setNvalue

          public void setNvalue(double nvalue)

      Sets the number value of this node.

    - #### isInteger

          public boolean isInteger()

      Returns `true` iff this `ParseNode` is an integer number.

    - #### makeInteger

          public void makeInteger(boolean isInteger)

      Sets the integer flag to the given boolean argument (i.e., whenever this argument is `true`, this node's numerical value will be cast as an `int`).

    - #### svalue

          public java.lang.String svalue()

      The String value of this node.

    - #### setSvalue

          public void setSvalue(java.lang.String svalue)

      Sets the String value of this node.

    - #### alternatives

          public ArrayList alternatives()

      If non-null, this contains alternative forms of an ambiguous token.

    - #### addAlternative

          public void addAlternative(ParseNode alternative)

      Add an alternative form for this ParseNode.

    - #### hasAlternatives

          public boolean hasAlternatives()

      Returns `true` iff this ParseNode has one or more alternative forms.

    - #### isUnknown

          public boolean isUnknown()

    - #### isError

          public boolean isError()

    - #### isEOI

          public boolean isEOI()

    - #### span

          public final Span span()

      Returns information to locate this node's extent in the input stream.

    - #### getSpan

          public final Span getSpan()

      Returns information to locate this node's extent in the input stream or `null`.

    - #### locate

          public void locate()

      This method (by default empty) is invoked anytime this node's span is set. It is meant to be overridden for locating specific `Locatable` members using the span of this parsenode as the extent (either implicitly using the `locates` option of a `%nodeclass` declaration, or explicitly in the body of such a declaration).

    - #### setSpan

          public final Locatable setSpan(ParseNode node)

    - #### isLocated

          public final boolean isLocated()

    - #### getStart

          public final Location getStart()

      Specified by:
        `getStart` in interface `Locatable`

    - #### setStart

          public final Locatable setStart(Location location)

      Specified by:
        `setStart` in interface `Locatable`

    - #### getEnd

          public final Location getEnd()

      Specified by:
        `getEnd` in interface `Locatable`

    - #### setEnd

          public final Locatable setEnd(Location location)

      Specified by:
        `setEnd` in interface `Locatable`

    - #### getFile

          public final java.lang.String getFile()

      Returns the file name where this node's constituents start from if any; or `null`

    - #### getLineNumber

          public final int getLineNumber()

      Returns the line number in the input stream corresponding to the start location of this node's extent.

    - #### setFile

          public final ParseNode setFile(java.lang.String file)

      Sets the file name where this node's constituents are, and returns this parse node.

    - #### setLineNumber

          public final ParseNode setLineNumber(int line)

      Sets the line number in the input stream corresponding to this node's location extent start, and returns this parse node. This is a dangerous method to use as it can set the start line number to a value inconsistent with its end's. Therefore, a warning is issued.

    - #### locationString

          public final java.lang.String locationString()

      Returns an explicit string for this node's location.
      Specified by:
        `locationString` in interface `Locatable`

    - #### children

          public final ArrayList children()

      When constructing the parse tree, this is the set of constituents. If a parse tree has been built (by `GenericParser.parse(boolean)`), this returns the sequence of `ParseNode`s that are this node's constituents. Otherwise, returns `null`.

    - #### setChildren

          public void setChildren(ArrayList children)

    - #### numberOfChildren

          public final int numberOfChildren()

      Returns the number of constituents of this node.

    - #### isTerminal

          public final boolean isTerminal()

      Returns `true` iff this node corresponds to a terminal symbol.

    - #### hasChildren

          public final boolean hasChildren()

      Returns `true` iff this node does not have any child.

    - #### isLeafNode

          public final boolean isLeafNode()

      Returns `true` iff this node is a leaf in the parse tree (i.e., iff it corresponds to a terminal symbol or an anonymous symbol).

    - #### isInnerNode

          public final boolean isInnerNode()

      Returns `true` iff this node is an inner node in the parse tree (i.e., iff it corresponds to a nonterminal symbol).

    - #### isEmptyNode

          public final boolean isEmptyNode()

      Returns `true` iff this node is a null inner node (i.e., iff it corresponds to an empty derivation). These nodes have no children.

    - #### hasValue

          public final boolean hasValue()

      Returns `true` iff this node carries a value (which is either in its `svalue` or `nvalue` field).

    - #### stringValue

          public final java.lang.String stringValue()

      Returns the value carried by this node as a String.

    - #### nodeInfo

          public final java.lang.String nodeInfo()

      Returns a string representation of this node's information contents: its string form and its location if known.

    - #### child

          public final ParseNode child(int i)

      If a parse tree has been built, this returns the `i`-th in the sequence of `ParseNode`s that are this node's constituents. Otherwise, returns `null`. NB: the argument `i` ranges from `1` to `numberOfChildren`.

    - #### firstChild

          public final ParseNode firstChild()

      If a parse tree has been built, this returns the first in the sequence of `ParseNode`s that are this node's constituents. Otherwise, returns `null`.

    - #### lastChild

          public final ParseNode lastChild()

      If a parse tree has been built, this returns the last in the sequence of `ParseNode`s that are this node's constituents. Otherwise, returns `null`.

    - #### operator

          public ParserOperator operator()

      If this is a dynamic operator, the actual specific operator.

    - #### setOperator

          public void setOperator(ParserOperator operator)

      Sets the operator.

    - #### isOperator

          public final boolean isOperator()

      Returns `true` iff this is a dynamic operator.

    - #### precedence

          public final int precedence()

      Returns the precedence value of this node. This assumes that this is a token node.

    - #### associativity

          public final int associativity()

      Returns the associativity value of this node. This assumes that this is a token node.

    - #### fixity

          public final int fixity()

      Returns the fixity value of this node. This assumes that this is a token node. If this is not an operator, returns -1.

    - #### copy

          public final ParseNode copy(ParseNode node)

      Returns an almost complete copy of the specified node by copying the values of all its attributes except that of its `symbol`, `children`, and location `span`. The symbol of the copy is set to that of this (not the specified) node, and the children and span are set to `null`.

    - #### copy

          public ParseNode copy()

      Returns a new ParseNode that is a shallow copy of this ParseNode.

    - #### display

          public final void display()

      Spawns a framed graphical display of the parse tree rooted in this node.

    - #### display

          public final void display(java.lang.String source)

      Spawns a framed graphical display of the parse tree rooted in this node and corresponding to the specified source file.

    - #### show

          public final void show()

      Prints the parse tree rooted in this node on stdout.

    - #### show

          public final void show(java.io.PrintStream out)

      Prints the parse tree rooted in this node on the specified output stream.

    - #### show

          public final void show(int margin,
                  java.io.PrintStream out)

      Prints the parse tree rooted in this node on the specified output stream with the given initial margin.

    - #### xmlForm

          public final ArrayList xmlForm()

      Returns the (possibly empty) list of XML elements associated with this parse node. This XML form is synthesized from the concrete parse tree (CST) made of `ParseNode`'s rooted at this node, using the XML annotation specified for the rules and terminals (if any) and the default "xmlification". Note that in the total absence of any rule or terminal annotation, the XML form will simply amount to the sequence of XML elements corresponding to the value-carrying (i.e., non-punctuation) terminals at the leaves of the CST.

      [N.B.: This list is "populated" by calling `xmlify(Element root)`.]

    - #### hasXmlForm

          public final boolean hasXmlForm()

      Returns `true` iff `xmlForm()` is non-empty.

    - #### showXmlElement

          public final void showXmlElement(org.jdom.Element element,
                            java.io.PrintStream out)
                                    throws java.io.IOException

      Serializes the specified XML element on the specified output stream.
      Throws:
        `java.io.IOException`

    - #### xmlDocument

          public final org.jdom.Document xmlDocument()

      Returns the XML document associated with this parse node, if any, or `null` otherwise.

      [N.B.: This will return `null` as long as `xmlDocument(xmlroot,nsprefix,namespaces)` has not been invoked.]

    - #### xmlDocument

          public org.jdom.Document xmlDocument(java.lang.String xmlroot,
                                      java.lang.String nsprefix,
                                      java.lang.String[] namespaces)

      Returns the XML document associated with this parse node with a root element named as specified by `xmlroot` and `nsprefix` in the context of the namespaces declarations specified in `namespaces`. The first time this is called, this will trigger computation of the XML form of this node (and inductively of that of this node's descendants below it in the CST) as a (possibly empty) list of JDOM XML `Element`'s for the CST rooted in this `ParseNode`. This XML form is then recorded as this node's `_xmlForm`. Finally, all the elements in this form are attached in the order they come as contents to the root of a JDOM XML `Document`, which is then saved as this node's `_xmlDocument`. Further calls will simply return the saved `_xmlDocument`.

    - #### setXmlInfo

          public ParseNode setXmlInfo(XmlInfo info)

      Sets this parse node's XML info to the specified `info` and returns this node.

    - #### xmlify

          public final ArrayList xmlify(org.jdom.Element root)

      This method builds and returns the XML form of this parse node as a (possibly empty) `ArrayList`. The argument is the uppermost XML `Element` that is the root of the containing XML document. It is passed down to provide the context for retrieving global document information needed in the construction such as namespace prefix definitions, etc., ... It generates the creation of a list of zero, one, or more JDOM `Element` objects corresponding to the form of this node's XML serialization. This list is then recorded as this parse node's `_xmlForm`. This method uses the information stored in this node (which is a full CST) together with the (possibly `null`) XML info stored in its private field `_xmlInfo`. When non-`null`, this `_xmlInfo` specifies a guiding pattern according to which this node's XML form is generated as a singleton `ArrayList` `Element`.

      #### Specification

      The process of building the XML tree from the concrete syntax tree is one of tree transduction. The source is the full concrete parse tree (i.e., the one rooted in this `ParseNode`); and the target is the (possibly empty) `ArrayList` of JDOM XML trees (each of of type `Element`), which is then recorded as the `_xmlForm` field of this `ParseNode`. Thus, a parse node may be transduced into either (1) nothing, or (2) an `Element`, or (3) a sequence thereof. This transduction is performed inductively (i.e., from the leaves to the root) using the transduction information specified as this node's `XmlInfo` attribute `_xmlInfo` (which may be possibly `null`).

      The XML info is of type `XmlInfo` and consists of:

      - `_xmlInfo.localName()`: an XML element's name (a `String`);

      - `_xmlInfo.nsPrefix()`: an XML namespace's prefix (a `String`);

      - `_xmlInfo.attributes()`: an array of `XmlAttributeInfo`'s. Each `XmlAttributeInfo` specifies an attribute key/value pair of this node's XML form.

      - `_xmlInfo.children()`: an `int[]` containing indices in this `ParseNode`'s `children()`. If `_xmlInfo.children()[i]=j`, this means that the XML form of the `j`th child CST constitutes the `i`th (possibly empty) subsequence of this node's XML form.

      - `_xmlInfo.xmlPaths()`: an `int[][]` containing paths of XML subtree indices such that, if `_xmlInfo.xmlPaths()[i]` is non `null` and equal to some `int[] pathi`, then `pathi` denotes the XML tree address consisting of a sequence of indices of XML subcomponents, starting at an element in the XML form of this node's child `ParseNode` at index `children()[i]`, and navigating down the XML tree therefrom.

      - `_xmlInfo.wrapperPaths()`: a `String[][]` containing sequences of XML tags such that, if `_xmlInfo.wrapperPaths()[i]` is non `null` and equal to some `String[] pathi`, then `pathi` denotes the wrapping XML elements in which to nest the XML tree constructed from this node's descendants.
      This information comes from explicit annotations of the grammar's rules or terminals. When it is absent (i.e., `_xmlInfo` is `null`), a (sensible) default behavior for building the XML tree is carried out (see Case II below).

      Thus, we need to specify how to transduce this node into an `ArrayList` following the following steps:

      1. Create a new `ArrayList` called `xmlForm`;

      2. If there is no explicit annotation (i.e., if `_xmlInfo` is `null`), the default behavior is as follows:
         1. If this is a leaf node (i.e., if this has no children):
            1. If this node's symbol is a non-terminal with no children:
               - ignore it.
            2. If this node's symbol is a terminal:
               1. If it is punctuation (i.e., a literal terminal, not carrying any value but itself):
                  - ignore it;
               2. Else (it has a value):
                  - create a new XML `Element` using the name of the terminal symbol as this element's local name;
                  - add to it only one `Text` component containing the value of the node as contents;
                  - add this new element to `xmlForm`.
         2. Else (i.e., this is an interior node):
            - for each of this node's children, append the list returned by calling `xmlify(root)` to `xmlForm`;

      3. Else, there is an explicit annotation (i.e., `_xmlInfo` is not `null`):
         1. If this is a leaf node (i.e., it has no children):
            1. If this node's symbol is a non-terminal with no children:
               [N.B., `_xmlInfo.children()` is then null or empty since there may be no reference to children in an empty derivation's annotation - here's why]
               - create a new XML `Element` using `_xmlInfo`;
               - add this element to `xmlForm`;
            2. If this node's symbol is a terminal:
               1. If it is punctuation (i.e., a literal terminal, not carrying any value but itself):
                  [N.B: this should not happen and be flagged as an annotation error at grammar-processing time since punctuation terminals may not be annotated; only rules and value-carrying tokens may be annotated in the grammar. Thus, punctuation terminals are systematically ignored.]
               2. Else (it has a value):
                  [N.B.: `_xmlInfo.children()` is then null or empty since there may be no reference to children in a terminal's annotation - here's why]
                  - create a new XML `Element` using `_xmlInfo`;
                  - add to it only one `Text` component containing the value of the node as contents;
                  - add this new element to `xmlForm`;
         2. Else (i.e., this is an interior node):
            - create a new XML `Element` using `_xmlInfo`;
            - add it to `xmlForm`;

      4. Return `xmlForm`.

      `[See also the method `createXmlForm(ParseNode node, Element root)` in the class `XmlInfo`.]`

      `N.B.: The code below is guaranteed to work safely only if the annotation is strictly consistent.`

    - #### equals

          public final boolean equals(java.lang.Object other)

      Two ParseNodes are considered equal iff they carry the same info.
      Overrides:
        `equals` in class `java.lang.Object`

    - #### toString

          public java.lang.String toString()

      Returns a string representation of this node, along, possibly, with all its alternatives if any.
      Overrides:
        `toString` in class `java.lang.Object`