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

hlt.language.syntax

## Class XmlInfo

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

-     public class XmlInfo
      extends java.lang.Object

  This is the class of information concerning XML annotation.
  Version:
    Last modified on Wed Nov 07 04:06:57 2012 by hak
  Author:
    Hassan Aït-Kaci
  Copyright:
    © by the author

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `XmlInfo(java.lang.String localName)`
    `XmlInfo(java.lang.String localName, java.lang.String nsPrefix)`
    `XmlInfo(java.lang.String localName, java.lang.String nsPrefix, XmlAttributeInfo[] attributes, int[] children, int[][] xmlPaths, XmlWrapper[][] wrapperPaths, java.lang.String[] attributeRefs, boolean terminalValueFlag, XmlTextInfo[][] textInfos)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String[]` | `attributeRefs()`
    `java.lang.String` | `attributeRefs(int i)`
    `XmlAttributeInfo[]` | `attributes()`
    `void` | `checkConsistency(Rule r)` Throws a `BadXmlAnnotationException` if and only if this `XmlInfo` is inconsistent with the specified rule.
    `void` | `checkConsistency(Terminal t)` Throws a `BadXmlAnnotationException` if and only if this `XmlInfo` is inconsistent with the specified terminal.
    `int[]` | `children()`
    `org.jdom.Element` | `createXmlForm(ParseNode node, org.jdom.Element root)` This method synthesizes and returns a JDOM `Element` computed using the information in this `XmlInfo` in the context of the specified XML document root `root`.
    `void` | `generateAttributeInitializers(ParserGenerator g, int index, XmlAttributeInfo a)` Uses the specified `ParserGenerator` to generate the parser's Java code recording the specified `XmlAttributeInfo` where appropriate.
    `void` | `generateRuleXmlInfo(ParserGenerator g, int index)` Uses the specified `ParserGenerator` to generate the parser's Java code recording this rule's `XmlInfo` where appropriate.
    `void` | `generateTerminalXmlInfo(ParserGenerator g, int index)` Uses the specified `ParserGenerator` to generate the parser's Java code recording this `XmlInfo` when it is that of a `Terminal`.
    `boolean` | `hasAttributeRefs()` `hasAttributeRefs()` returns `true` iff the array of strings `_attributeRefs` is non null and contains at least one non-null string.
    `boolean` | `hasAttributes()`
    `boolean` | `hasChildren()`
    `boolean` | `hasNsPrefix()`
    `boolean` | `hasTerminalValue()`
    `boolean` | `hasTextInfos()` `hasTextInfos()` returns `true` iff the array of string arrays `_textInfos` is non null and contains at least one non-null array.
    `boolean` | `hasWrapperPaths()`
    `boolean` | `hasXmlPaths()`
    `boolean` | `isTerminal()`
    `java.lang.String` | `localName()`
    `java.lang.String` | `nsPrefix()`
    `XmlInfo` | `setAttributeRefs(java.lang.String[] refs)`
    `XmlInfo` | `setAttributes(XmlAttributeInfo[] attributes)`
    `XmlInfo` | `setChildren(int[] children)`
    `XmlInfo` | `setIsTerminal()`
    `XmlInfo` | `setIsTerminal(boolean flag)`
    `XmlInfo` | `setLocalName(java.lang.String localName)`
    `XmlInfo` | `setNsPrefix(java.lang.String nsPrefix)`
    `XmlInfo` | `setTerminalValueFlag()`
    `XmlInfo` | `setTerminalValueFlag(boolean flag)`
    `XmlInfo` | `setTextInfos(XmlTextInfo[][] infos)`
    `XmlInfo` | `setWrapperPaths(XmlWrapper[][] paths)`
    `XmlInfo` | `setXmlPaths(int[][] paths)`
    `boolean` | `terminalValueFlag()`
    `java.lang.String` | `toHtmlString(int offset, java.lang.String sep)`
    `java.lang.String` | `toPrettyHtmlString(int offset)`
    `java.lang.String` | `toString()`
    `java.lang.String` | `toString(int offset, java.lang.String sep, boolean html)` `toString(int offset, String sep, boolean htmlPrefix, aboolean htmlName, boolean htmlAttribute)` returns a formatted string for this `XmlInfo`.
    `XmlWrapper[][]` | `wrapperPaths()`
    `int[][]` | `xmlPaths()`

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

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

- - ### Constructor Detail

    - #### XmlInfo

          public XmlInfo(java.lang.String localName)

    - #### XmlInfo

          public XmlInfo(java.lang.String localName,
                 java.lang.String nsPrefix)

    - #### XmlInfo

          public XmlInfo(java.lang.String localName,
                 java.lang.String nsPrefix,
                 XmlAttributeInfo[] attributes,
                 int[] children,
                 int[][] xmlPaths,
                 XmlWrapper[][] wrapperPaths,
                 java.lang.String[] attributeRefs,
                 boolean terminalValueFlag,
                 XmlTextInfo[][] textInfos)

  - ### Method Detail

    - #### terminalValueFlag

          public final boolean terminalValueFlag()

    - #### setTerminalValueFlag

          public XmlInfo setTerminalValueFlag(boolean flag)

    - #### setTerminalValueFlag

          public XmlInfo setTerminalValueFlag()

    - #### hasTerminalValue

          public final boolean hasTerminalValue()

    - #### isTerminal

          public final boolean isTerminal()

    - #### setIsTerminal

          public XmlInfo setIsTerminal(boolean flag)

    - #### setIsTerminal

          public XmlInfo setIsTerminal()

    - #### nsPrefix

          public final java.lang.String nsPrefix()

    - #### hasNsPrefix

          public final boolean hasNsPrefix()

    - #### setNsPrefix

          public XmlInfo setNsPrefix(java.lang.String nsPrefix)

    - #### localName

          public final java.lang.String localName()

    - #### setLocalName

          public XmlInfo setLocalName(java.lang.String localName)

    - #### attributes

          public final XmlAttributeInfo[] attributes()

    - #### setAttributes

          public XmlInfo setAttributes(XmlAttributeInfo[] attributes)

    - #### hasAttributes

          public final boolean hasAttributes()

    - #### children

          public final int[] children()

    - #### setChildren

          public XmlInfo setChildren(int[] children)

    - #### hasChildren

          public final boolean hasChildren()

    - #### xmlPaths

          public final int[][] xmlPaths()

    - #### setXmlPaths

          public XmlInfo setXmlPaths(int[][] paths)

    - #### hasXmlPaths

          public final boolean hasXmlPaths()

    - #### wrapperPaths

          public final XmlWrapper[][] wrapperPaths()

    - #### setWrapperPaths

          public XmlInfo setWrapperPaths(XmlWrapper[][] paths)

    - #### hasWrapperPaths

          public final boolean hasWrapperPaths()

    - #### attributeRefs

          public final java.lang.String[] attributeRefs()

    - #### setAttributeRefs

          public XmlInfo setAttributeRefs(java.lang.String[] refs)

    - #### attributeRefs

          public java.lang.String attributeRefs(int i)

    - #### hasAttributeRefs

          public final boolean hasAttributeRefs()

      `hasAttributeRefs()` returns `true` iff the array of strings `_attributeRefs` is non null and contains at least one non-null string.

    - #### setTextInfos

          public XmlInfo setTextInfos(XmlTextInfo[][] infos)

    - #### hasTextInfos

          public final boolean hasTextInfos()

      `hasTextInfos()` returns `true` iff the array of string arrays `_textInfos` is non null and contains at least one non-null array.

    - #### checkConsistency

          public void checkConsistency(Rule r)
                                throws BadXmlAnnotationException

      Throws a `BadXmlAnnotationException` if and only if this `XmlInfo` is inconsistent with the specified rule.

      `[See what consistent annotation means for a rule.]`

      Throws:
        `BadXmlAnnotationException`

    - #### checkConsistency

          public void checkConsistency(Terminal t)
                                throws BadXmlAnnotationException

      Throws a `BadXmlAnnotationException` if and only if this `XmlInfo` is inconsistent with the specified terminal.

      `[See what consistent annotation means for a terminal.]`

      Throws:
        `BadXmlAnnotationException`

    - #### generateTerminalXmlInfo

          public void generateTerminalXmlInfo(ParserGenerator g,
                                     int index)
                                       throws java.io.IOException

      Uses the specified `ParserGenerator` to generate the parser's Java code recording this `XmlInfo` when it is that of a `Terminal`. Namely, it generates the code that will initialize `temrinals[index].xmlInfo()`. The set up is that of classical instruction generation writing out packaged instructions that will do the actual work at parse time for each annotated terminal from the information present in that terminal being recognized. Hence, `ParserTerminal` has methods defined to set `XmlInfo` contents - typically called `setXmlInfo(...)` with arguments of appropriate types of XML info components. That information is then used at parse time by the methods `processTerminal`, that takes the context of a `ParseNode` to generate the actual JDOM constructs corresponding to the annotation that speciified this terminal's `XmlInfo`.
      Throws:
        `java.io.IOException`

    - #### generateRuleXmlInfo

          public void generateRuleXmlInfo(ParserGenerator g,
                                 int index)
                                   throws java.io.IOException

      Uses the specified `ParserGenerator` to generate the parser's Java code recording this rule's `XmlInfo` where appropriate. Namely, at index `index` in the array `rules`. The set up is that of classical instruction generation writing out packaged instructions that will do the actual work at parse time for each annotated terminal and rule from the information present in that rule being reduced. Hence, a `ParserRule` has methods defined to attach `XmlInfo` contents to a rule - typically called `setXmlInfo(...)`, with arguments of appropriate types of XML info components. That information is then used at parse time by the methods `processAttributes` and `processChildren` that both take the context of a `ParseNode` to generate the actual JDOM constructs corresponding to the annotation that yielded this rule's `XmlInfo`.
      Throws:
        `java.io.IOException`

    - #### generateAttributeInitializers

          public void generateAttributeInitializers(ParserGenerator g,
                                           int index,
                                           XmlAttributeInfo a)
                                             throws java.io.IOException

      Uses the specified `ParserGenerator` to generate the parser's Java code recording the specified `XmlAttributeInfo` where appropriate. Namely, at index `index` in the array `XmlAttributes`.
      Throws:
        `java.io.IOException`

    - #### createXmlForm

          public final org.jdom.Element createXmlForm(ParseNode node,
                                       org.jdom.Element root)

      This method synthesizes and returns a JDOM `Element` computed using the information in this `XmlInfo` in the context of the specified XML document root `root`.

      In the simpler case (i.e., that of a homomorphic tree transduction), this builds the XML element tree inductively from leaves to root with mutually recursive calls to `xmlify (Element root)`.

      In the more complex case (i.e., that of a heteromorphic tree transduction), this also builds the XML element tree inductively from leaves to root; but now, the attribute values and XML components of the element being constructed may be those of already constructed elements beneath this one. In that case, the "lower" element must first be detached from its parent element. This is because the XML DOM tree model does not support sharing; i.e., an element may not belong to more than one container - in other words, this is indeed a tree rather than a DAG (directed acyclic graph). Of course, this will modify the parent of the referenced element, but this is fine because that container is now harmlessless useless anyway (since it will now never be attached to any element or document higher up).

      However, we can't just carelessly slice up the referenced element's container by removing the referenced element from its parent's children's list. Indeed, since other references to other children of this container may yet take place, it is important to keep the number and order of all the elements' components consistent. To achieve this, we simply substitute a dummy element in the place previously occupied by the element being detached (and returned to be re-attached where appropriate).

      `[See also the method `xmlify(Element container)` in the class `ParseNode`.]`

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

    - #### toString

          public final java.lang.String toString(int offset,
                                  java.lang.String sep,
                                  boolean html)

      `toString(int offset, String sep, boolean htmlPrefix, aboolean htmlName, boolean htmlAttribute)` returns a formatted string for this `XmlInfo`. It is a generic method that can be adapted depending on its arguments as a string with plain contents, or with HTML code, or pretty-printed. The arguments are:

      - `int offset`: a margin offset for pretty-printing;

      - `String sep`: a string separating documentation items (i.e., white space, or newline, etc.);

      - `boolean htmlPrefix`: when `true`, the namespace prefix is HTML-ified;

      - `boolean htmlName`: when `true`, the local name is HTML-ified;

      - `boolean htmlAttribute`: when `true`, the attributes are HTML-ified.

    - #### toHtmlString

          public final java.lang.String toHtmlString(int offset,
                                      java.lang.String sep)

    - #### toPrettyHtmlString

          public final java.lang.String toPrettyHtmlString(int offset)

    - #### toString

          public final java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`