hamwalk

## Class HMLBuilder

- java.lang.Object
- - hamwalk.HMLBuilder

-     public class HMLBuilder
      extends java.lang.Object

  A `HMLBuilder` supports the construction of a DOM Document for a HML (HamNoSysML) element. It is primarily intended for use by an ANTLR-generated tree-walker that generates an HML element from the AST for a manual HNS string.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `HMLBuilder()` Constructs a new HML document builder.
    `HMLBuilder(javax.xml.parsers.DocumentBuilder bldr)` Constructs a new HML document builder using the given DOM document builder.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `appendChildList(org.w3c.dom.Element el, org.w3c.dom.Element[] chl)` Appends the given sequence of child elements to the children of the given element.
    `static void` | `checkedAppendChild(org.w3c.dom.Element el, org.w3c.dom.Element ch)` Appends the given child element to the children of the given element, unless the child is null, in which case the putative parent is unaltered.
    `static void` | `checkedAppendChildList(org.w3c.dom.Element el, org.w3c.dom.Element[] chl)` Appends the given sequence of child elements to the children of the given element, unless the sequence is null, in which case the putative parent is unaltered.
    `static void` | `checkedSetAttr(org.w3c.dom.Element el, java.lang.String aname, java.lang.String aval)` Attaches the attribute setting with the given name and value to the given element, unless the attribute value is `null`, in which case the element is not changed.
    `static void` | `checkedSetFlagAttr(org.w3c.dom.Element el, java.lang.String aname, boolean flagIsTrue)` For the given element and boolean attribute setting (name and value), attaches the attribute setting to the element if its value is true, but makes no change to the element if the attribute value is false.
    `static void` | `checkedStringSetFlagAttr(org.w3c.dom.Element el, java.lang.String aname, java.lang.String aval)` Similar to `checkedSetFlagAttr(org.w3c.dom.Element, java.lang.String, boolean)`, but with a boolean string input value, that is, if the given value string is non-null and equals `"true"`, then the given attribute of the given element is set to this value; otherwise the element is left unchanged.
    `org.w3c.dom.Element` | `elementFromList(java.util.ArrayList<org.w3c.dom.Element> al, java.lang.String etag)` If the given list has exactly one element, then returns that element (assumed to be of the given type); otherwise, creates and returns a new element of the given type with the given list of elements (in order) as its children.
    `org.w3c.dom.ls.LSSerializer` | `getLSSerializer()` Returns a DOM level 3 LS serializer for this builder's document.
    `void` | `insertNonManual(org.w3c.dom.Element signel, org.w3c.dom.Element nmel)` Inserts the given HML non-manual element in the given HML sign element as its first child, unless the former is `null`, in which case this method does nothing.
    `org.w3c.dom.Attr` | `newHMLAttr(java.lang.String aname)` Creates and returns a new DOM attribute of the given name.
    `org.w3c.dom.Comment` | `newHMLComment(java.lang.String data)` Creates and returns a new DOM comment with the given content.
    `org.w3c.dom.Element` | `newHMLElement(java.lang.String tag)` Creates and returns a new DOM element of the given type.
    `org.w3c.dom.Element` | `parseElement(java.lang.String eltext)` Returns a new DOM element structure for the given element text, unless the latter is the empty string, in which case this method returns `null`.
    `void` | `setDocRoot(org.w3c.dom.Element root)` Sets the given element as the document element for this builder's document.
    `org.w3c.dom.Element` | `stripParentIfNotNeeded(org.w3c.dom.Element el)` If the given element's first child has no attributes and has the same type as the given one, then returns this first child; otherwise returns the original element unchanged.
    `org.w3c.dom.Element` | `wrapIfNeeded(java.lang.String tag, org.w3c.dom.Element el)` If the given element is of the given type and has no attributes, then returns the element unaltered; otherwise returns a new element of the given type with the given element as its only child.
    `org.w3c.dom.Element` | `wrapPair(java.lang.String tag, org.w3c.dom.Element inner0, org.w3c.dom.Element inner1)` Creates and returns a new DOM element of the given type with the given pair of elements as its only children (in the given order).
    `org.w3c.dom.Element` | `wrapperEl(java.lang.String tag, org.w3c.dom.Element inner)` Creates and returns a new DOM element of the given type with the given element as its only child.

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

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

- - ### Constructor Detail

    - #### HMLBuilder

          public HMLBuilder()
                     throws java.io.IOException,
                            org.w3c.dom.DOMException,
                            javax.xml.parsers.ParserConfigurationException

      Constructs a new HML document builder.
      Throws:
        `java.io.IOException`
        `org.w3c.dom.DOMException`
        `javax.xml.parsers.ParserConfigurationException`

    - #### HMLBuilder

          public HMLBuilder(javax.xml.parsers.DocumentBuilder bldr)

      Constructs a new HML document builder using the given DOM document builder.

  - ### Method Detail

    - #### newHMLElement

          public org.w3c.dom.Element newHMLElement(java.lang.String tag)

      Creates and returns a new DOM element of the given type.

    - #### newHMLAttr

          public org.w3c.dom.Attr newHMLAttr(java.lang.String aname)

      Creates and returns a new DOM attribute of the given name.

    - #### newHMLComment

          public org.w3c.dom.Comment newHMLComment(java.lang.String data)

      Creates and returns a new DOM comment with the given content.

    - #### wrapperEl

          public org.w3c.dom.Element wrapperEl(java.lang.String tag,
                                               org.w3c.dom.Element inner)

      Creates and returns a new DOM element of the given type with the given element as its only child.

    - #### wrapPair

          public org.w3c.dom.Element wrapPair(java.lang.String tag,
                                              org.w3c.dom.Element inner0,
                                              org.w3c.dom.Element inner1)

      Creates and returns a new DOM element of the given type with the given pair of elements as its only children (in the given order).

    - #### wrapIfNeeded

          public org.w3c.dom.Element wrapIfNeeded(java.lang.String tag,
                                                  org.w3c.dom.Element el)

      If the given element is of the given type and has no attributes, then returns the element unaltered; otherwise returns a new element of the given type with the given element as its only child.

    - #### stripParentIfNotNeeded

          public org.w3c.dom.Element stripParentIfNotNeeded(org.w3c.dom.Element el)

      If the given element's first child has no attributes and has the same type as the given one, then returns this first child; otherwise returns the original element unchanged.

    - #### elementFromList

          public org.w3c.dom.Element elementFromList(java.util.ArrayList<org.w3c.dom.Element> al,
                                                     java.lang.String etag)

      If the given list has exactly one element, then returns that element (assumed to be of the given type); otherwise, creates and returns a new element of the given type with the given list of elements (in order) as its children.

    - #### insertNonManual

          public void insertNonManual(org.w3c.dom.Element signel,
                                      org.w3c.dom.Element nmel)

      Inserts the given HML non-manual element in the given HML sign element as its first child, unless the former is `null`, in which case this method does nothing.

    - #### setDocRoot

          public void setDocRoot(org.w3c.dom.Element root)

      Sets the given element as the document element for this builder's document.

    - #### parseElement

          public org.w3c.dom.Element parseElement(java.lang.String eltext)

      Returns a new DOM element structure for the given element text, unless the latter is the empty string, in which case this method returns `null`.

    - #### appendChildList

          public static void appendChildList(org.w3c.dom.Element el,
                                             org.w3c.dom.Element[] chl)

      Appends the given sequence of child elements to the children of the given element.

    - #### checkedAppendChildList

          public static void checkedAppendChildList(org.w3c.dom.Element el,
                                                    org.w3c.dom.Element[] chl)

      Appends the given sequence of child elements to the children of the given element, unless the sequence is null, in which case the putative parent is unaltered.

    - #### checkedAppendChild

          public static void checkedAppendChild(org.w3c.dom.Element el,
                                                org.w3c.dom.Element ch)

      Appends the given child element to the children of the given element, unless the child is null, in which case the putative parent is unaltered.

    - #### checkedSetAttr

          public static void checkedSetAttr(org.w3c.dom.Element el,
                                            java.lang.String aname,
                                            java.lang.String aval)

      Attaches the attribute setting with the given name and value to the given element, unless the attribute value is `null`, in which case the element is not changed.

    - #### checkedSetFlagAttr

          public static void checkedSetFlagAttr(org.w3c.dom.Element el,
                                                java.lang.String aname,
                                                boolean flagIsTrue)

      For the given element and boolean attribute setting (name and value), attaches the attribute setting to the element if its value is true, but makes no change to the element if the attribute value is false.

    - #### checkedStringSetFlagAttr

          public static void checkedStringSetFlagAttr(org.w3c.dom.Element el,
                                                      java.lang.String aname,
                                                      java.lang.String aval)

      Similar to `checkedSetFlagAttr(org.w3c.dom.Element, java.lang.String, boolean)`, but with a boolean string input value, that is, if the given value string is non-null and equals `"true"`, then the given attribute of the given element is set to this value; otherwise the element is left unchanged.

    - #### getLSSerializer

          public org.w3c.dom.ls.LSSerializer getLSSerializer()

      Returns a DOM level 3 LS serializer for this builder's document.