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

hlt.language.syntax

## Class GenericParser

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

- Direct Known Subclasses:
    DynamicParser, StaticParser

      public abstract class GenericParser
      extends java.lang.Object

  This is the generic parser that is inherited by all parser classes generated by `ParserGenerator`. It is further subclassed by two other abstract classes: `StaticParser` and `DynamicParser`.
  Version:
    Last modified on Fri Nov 02 18:07:18 2012 by hak
  Author:
    Hassan Aït-Kaci
  See Also:
    `ParserGenerator`, `StaticParser`, `DynamicParser`
  Copyright:
    © by the author

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `COMPACT_TREE` A value indicating that a compact parse tree must be built.
    `static ParseNode` | `E_O_I` Canonical token denoting the end of input.
    `static ParserTerminal` | `ERROR_SYMBOL` Canonical terminal to identify error tokens.
    `static int` | `FULL_TREE` A value indicating that the full (concrete) parse tree must be built.
    `static int` | `NO_TREE` A value indicating that no parse tree must be built.
    `int` | `parseTreeType` The value used by the parser to build, or not, a parse tree.
    `static int` | `XML_TREE` A value indicating that an XML serialization tree must be built.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `GenericParser()` The members of this class are divided into a static group and non-static group.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `abort()` Aborts the parsing upon an unrecoverable error and throws an exception signaling so.
    `ParseNode` | `currentNode()` Returns the current node; i.e., the result returned by the most recent semantic action.
    `static ParseNode` | `eoi()` Returns the end of input token with the current location.
    `ParseNode` | `error()` Returns an error token.
    `static ParseNode` | `error(ParseNode node)` Returns an error token whose `svalue` is set to the supplied ParseNode's printed value, and whose span is set to that of the supplied node.
    `static ParseNode` | `error(java.lang.String errval)` Returns an error token whose `svalue` is set to the supplied string.
    `ErrorManager` | `errorManager()`
    `Error` | `fatalError(java.lang.String msg)`
    `Error` | `fatalError(java.lang.String msg, Locatable extent)`
    `java.lang.String` | `fileName()` The following is for showing items - for debugging purposes...
    `Tokenizer` | `getTokenizer()`
    `void` | `initialize()` One may override this method to execute whatever initializations one wishes.
    `static ParseNode` | `literalToken(java.lang.String symbol)`
    `ParseNode` | `locate(ParseNode node)`
    `org.jdom.Document` | `makeXmlDocument(ParseNode node)` Returns the XML document rooted in the specified node.
    `static ParseNode` | `numberToken(java.lang.String symbol, double num)`
    `static ParseNode` | `numberToken(java.lang.String symbol, int num)`
    `void` | `parse()` This is the method to invoke for parsing a token stream using the `Tokenizer` instance specified as input.
    `void` | `parse(boolean fullTree)` This is the same as `parse()`, but specifies building the parse tree: `true` is equivalent to `FULL_TREE`, and `false` is equivalent to `COMPACT_TREE`.
    `void` | `parse(int treeType)` This is the same as `parse()`, but specifies what type of parse tree to build.
    `void` | `parse(java.io.Reader reader)` Same as `parse()` but sets the tokenizer's reader to the specified one before doing the parse.
    `void` | `parse(java.lang.String file)` Same as `parse()` but sets the tokenizer's reader to one reading from the file having the specified name before doing the parse.
    `void` | `parse(Tokenizer input)` Same as `parse()` but sets the tokenizer to the specified one before doing the parse.
    `void` | `resetParser()`
    `void` | `setErrorManager(ErrorManager errorManager)`
    `void` | `setSwitchToken(ParseNode token)`
    `void` | `setTokenizer(Tokenizer input)`
    `void` | `setTrace(boolean flag)`
    `void` | `setTreeType(int type)` Sets the parse tree type to the specified value (one of `NO_TREE`, `COMPACT_TREE`, `FULL_TREE`, or `XML_TREE`).
    `void` | `setTreeType(java.lang.String type)` Sets the parse tree type according to the specified string (one of `"NONE"`, `"COMPACT"`, `"FULL"`, or `"XML"`).
    `static ParseNode` | `symbolToken(java.lang.String symbol, java.lang.String token)` The following methods are public conveniences that may be used by the class implementing the tokenizer interface.
    `Error` | `syntaxError(java.lang.String msg)`
    `Error` | `syntaxError(java.lang.String msg, Locatable extent)`
    `void` | `toggleTrace()`
    `void` | `trace()`
    `void` | `traceAction(ParserAction a)`
    `boolean` | `tracingIsOn()`
    `void` | `writeXml(ParseNode node, java.io.PrintStream out)` Serializes the XML tree rooted in this node on the specified output stream.
    `static java.lang.String` | `xmlForm(org.jdom.Document document)` Serializes the XML tree rooted in this node on the specified output stream.
    `static org.jdom.output.XMLOutputter` | `xmlWriter()`

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

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

- - ### Field Detail

    - #### NO_TREE

          public static final int NO_TREE

      A value indicating that no parse tree must be built.
      See Also:
        Constant Field Values

    - #### COMPACT_TREE

          public static final int COMPACT_TREE

      A value indicating that a compact parse tree must be built.
      See Also:
        Constant Field Values

    - #### FULL_TREE

          public static final int FULL_TREE

      A value indicating that the full (concrete) parse tree must be built.
      See Also:
        Constant Field Values

    - #### XML_TREE

          public static final int XML_TREE

      A value indicating that an XML serialization tree must be built.
      See Also:
        Constant Field Values

    - #### E_O_I

          public static ParseNode E_O_I

      Canonical token denoting the end of input. It gets initialized by the method `newTerminal`.

    - #### ERROR_SYMBOL

          public static ParserTerminal ERROR_SYMBOL

      Canonical terminal to identify error tokens. It gets initialized by the method `newTerminal`.

    - #### parseTreeType

          public int parseTreeType

      The value used by the parser to build, or not, a parse tree. It defaults to `NO_TREE`.

  - ### Constructor Detail

    - #### GenericParser

          public GenericParser()

      The members of this class are divided into a static group and non-static group. The latter is the information proper of each individual instance. The former is all the (read-only) information that is intrinsic to the parser's class and shared by all parser instances. It comprises all the tables defining the grammar symbols and rules, and the parsing automaton as well as all such read-only shareable ressources. These are initialized in static blocks by the generated parser's class, and are therefore defined at most once per application upon loading the parser's class. By constrast, the members that are proper to an individual parser's instance are created when the parser's constructor is called. Thus, a single application may create, and run concurrently, several parsers that are instances of the same class without interference, while still avoiding the substantial waste of having redundant tables.

  - ### Method Detail

    - #### initialize

          public void initialize()

      One may override this method to execute whatever initializations one wishes. The default method is empty.

    - #### eoi

          public static final ParseNode eoi()

      Returns the end of input token with the current location.

    - #### error

          public static final ParseNode error(java.lang.String errval)

      Returns an error token whose `svalue` is set to the supplied string.

    - #### error

          public static final ParseNode error(ParseNode node)

      Returns an error token whose `svalue` is set to the supplied ParseNode's printed value, and whose span is set to that of the supplied node.

    - #### symbolToken

          public static final ParseNode symbolToken(java.lang.String symbol,
                              java.lang.String token)

      The following methods are public conveniences that may be used by the class implementing the tokenizer interface.

    - #### numberToken

          public static final ParseNode numberToken(java.lang.String symbol,
                              double num)

    - #### numberToken

          public static final ParseNode numberToken(java.lang.String symbol,
                              int num)

    - #### literalToken

          public static ParseNode literalToken(java.lang.String symbol)

    - #### xmlWriter

          public static final org.jdom.output.XMLOutputter xmlWriter()

    - #### xmlForm

          public static java.lang.String xmlForm(org.jdom.Document document)

      Serializes the XML tree rooted in this node on the specified output stream.

    - #### writeXml

          public void writeXml(ParseNode node,
                      java.io.PrintStream out)
                        throws java.lang.Exception

      Serializes the XML tree rooted in this node on the specified output stream.
      Throws:
        `java.lang.Exception`

    - #### makeXmlDocument

          public org.jdom.Document makeXmlDocument(ParseNode node)
                                            throws java.lang.Exception

      Returns the XML document rooted in the specified node.
      Throws:
        `java.lang.Exception`

    - #### error

          public ParseNode error()

      Returns an error token.

    - #### currentNode

          public ParseNode currentNode()

      Returns the current node; i.e., the result returned by the most recent semantic action.

    - #### setSwitchToken

          public final void setSwitchToken(ParseNode token)

    - #### setTokenizer

          public final void setTokenizer(Tokenizer input)

    - #### getTokenizer

          public final Tokenizer getTokenizer()

    - #### resetParser

          public void resetParser()

    - #### setTreeType

          public final void setTreeType(int type)

      Sets the parse tree type to the specified value (one of `NO_TREE`, `COMPACT_TREE`, `FULL_TREE`, or `XML_TREE`). Values outside this sets are ignored.

    - #### setTreeType

          public final void setTreeType(java.lang.String type)

      Sets the parse tree type according to the specified string (one of `"NONE"`, `"COMPACT"`, `"FULL"`, or `"XML"`). Values outside this sets are ignored.

    - #### parse

          public final void parse()
                           throws java.io.IOException

      This is the method to invoke for parsing a token stream using the `Tokenizer` instance specified as input.
      Throws:
        `java.io.IOException`

    - #### parse

          public final void parse(java.io.Reader reader)
                           throws java.io.IOException

      Same as `parse()` but sets the tokenizer's reader to the specified one before doing the parse.
      Throws:
        `java.io.IOException`

    - #### parse

          public final void parse(java.lang.String file)
                           throws java.io.IOException

      Same as `parse()` but sets the tokenizer's reader to one reading from the file having the specified name before doing the parse.
      Throws:
        `java.io.IOException`

    - #### parse

          public final void parse(Tokenizer input)
                           throws java.io.IOException

      Same as `parse()` but sets the tokenizer to the specified one before doing the parse.
      Throws:
        `java.io.IOException`

    - #### parse

          public final void parse(int treeType)
                           throws java.io.IOException

      This is the same as `parse()`, but specifies what type of parse tree to build. The value must be one of `NO_TREE`, `COMPACT_TREE`, `FULL_TREE`, or `XML_TREE`. Otherwise, it is ignored.
      Throws:
        `java.io.IOException`

    - #### parse

          public final void parse(boolean fullTree)
                           throws java.io.IOException

      This is the same as `parse()`, but specifies building the parse tree: `true` is equivalent to `FULL_TREE`, and `false` is equivalent to `COMPACT_TREE`.
      Throws:
        `java.io.IOException`

    - #### errorManager

          public final ErrorManager errorManager()

    - #### setErrorManager

          public final void setErrorManager(ErrorManager errorManager)

    - #### syntaxError

          public final Error syntaxError(java.lang.String msg)

    - #### syntaxError

          public final Error syntaxError(java.lang.String msg,
                          Locatable extent)

    - #### fatalError

          public final Error fatalError(java.lang.String msg)

    - #### fatalError

          public final Error fatalError(java.lang.String msg,
                         Locatable extent)

    - #### fileName

          public java.lang.String fileName()

      The following is for showing items - for debugging purposes...

    - #### locate

          public final ParseNode locate(ParseNode node)

    - #### abort

          public final void abort()

      Aborts the parsing upon an unrecoverable error and throws an exception signaling so.

    - #### tracingIsOn

          public final boolean tracingIsOn()

    - #### setTrace

          public final void setTrace(boolean flag)

    - #### toggleTrace

          public final void toggleTrace()

    - #### trace

          public final void trace()
                           throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### traceAction

          public final void traceAction(ParserAction a)
                                 throws java.io.IOException

      Throws:
        `java.io.IOException`