Class Element

java.lang.Object
eu.maveniverse.domtrip.Node
eu.maveniverse.domtrip.ContainerNode
eu.maveniverse.domtrip.Element
public class Element extends ContainerNode
Represents an XML element with attributes and children, preserving original formatting including attribute spacing, quote styles, and element structure.

The Element class is the core building block for XML documents, representing XML elements with their attributes, child nodes, and namespace information. It maintains lossless formatting preservation during round-trip parsing and serialization operations.

Capabilities:

  • Attribute Management - Preserves attribute order, quote styles, and whitespace
  • Namespace Support - XML namespace handling with prefix resolution
  • Child Navigation - Methods for finding and manipulating child elements
  • Self-Closing Support - Handles self-closing tags
  • Formatting Preservation - Maintains original tag formatting and whitespace

Usage Examples:

// Create elements using factory methods
Element root = Element.of("root").attribute("id", "main");
Element textElement = Element.text("child", "Hello World");
Element selfClosing = Element.selfClosing("br");

// Add child elements
root.addNode(textElement);
root.addNode(Element.text("version", "1.0.0"));

// Navigate children
Optional<Element> found = root.child("child");
Stream<Element> children = root.children("item");

// Namespace handling
QName soapEnvelope = QName.of("http://schemas.xmlsoap.org/soap/envelope/", "Envelope", "soap");
Element nsElement = Element.of(soapEnvelope);

// Complex elements with fluent API
Element dependency = Element.of("dependency")
    .attribute("scope", "test");
dependency.addNode(Element.text("groupId", "junit"));
dependency.addNode(Element.text("artifactId", "junit"));

Attribute Handling:

Elements maintain attributes using Attribute objects that preserve the original quote style, whitespace, and raw values. The setAttribute methods automatically preserve existing formatting when updating attributes:

// Setting new attributes uses default formatting
element.setAttribute("class", "important");           // Uses default double quotes
element.setAttribute("style", "color: red", '\'');    // Uses single quotes

// Updating existing attributes preserves original formatting
element.setAttribute("class", "updated");             // Preserves original quotes/whitespace
String value = element.attribute("class");         // Returns "updated"

// For advanced formatting control, use attribute objects directly
element.attributeObject("class").value("manual");
See Also:

  • Constructor Details

    • Element

      public Element(String name) throws DomTripException
      Create a new Element with the given tag name.

      The element is initialized with an empty, order-preserving attribute map, default (empty) whitespace/formatting fields, and is not self-closing.

      Parameters:
      name - the element's tag name; leading/trailing whitespace is trimmed
      Throws:
      DomTripException - if name is null or blank

  • Method Details

    • type

      public Node.NodeType type()
      Returns the node type for this element.
      Specified by:
      type in class Node
      Returns:
      Node.NodeType.ELEMENT

    • name

      public String name()
      Gets the name (tag name) of this element.

      For namespaced elements, this returns the full qualified name including the prefix (e.g., "soap:Envelope"). Use localName() to get just the local part.

      Returns:
      the element name
      See Also:

    • name

      public Element name(String name)
      Sets the element name.
      Parameters:
      name - the new element name
      Returns:
      this element for method chaining

    • attribute

      public String attribute(String name)
      Gets the value of the specified attribute.
      Parameters:
      name - the attribute name
      Returns:
      the attribute value, or null if the attribute doesn't exist

    • attribute

      public Element attribute(String name, String value)
      Sets an attribute value, preserving existing formatting when the attribute already exists.

      When setting an attribute that already exists, this method preserves the original quote style, whitespace, and other formatting properties. For new attributes, it uses default formatting (double quotes, single space preceding whitespace).

      Examples:

      // Original: <element attr1='existing' />
element.attribute("attr1", "updated");
// Result:   <element attr1='updated' />  (preserves single quotes)

element.attribute("attr2", "new");
// Result:   <element attr1='updated' attr2="new" />  (uses default double quotes)
      Parameters:
      name - the attribute name
      value - the attribute value
      Returns:
      this element for method chaining
      See Also:

    • attribute

      public Element attribute(String name, String value, QuoteStyle quoteStyle)
      Sets an attribute value with a specific quote style.

      When setting an attribute that already exists, this method preserves the original preceding whitespace but uses the specified quote style. For new attributes, it uses the specified quote style with default whitespace (single space).

      Parameters:
      name - the attribute name
      value - the attribute value
      quoteStyle - the quote style to use (SINGLE or DOUBLE)
      Returns:
      this element for method chaining
      See Also:

    • removeAttribute

      public void removeAttribute(String name)
      Removes the specified attribute from this element.
      Parameters:
      name - the name of the attribute to remove

    • attributes

      public Map<String,String> attributes()
      Gets all attributes as a map of names to values.
      Returns:
      a map containing all attribute names and their values

    • attributeObjects

      public Map<String, Attribute> attributeObjects()
      Gets all attribute objects with their formatting information.
      Returns:
      a map of attribute names to Attribute objects

    • hasAttribute

      public boolean hasAttribute(String name)
      Checks if this element has the specified attribute.
      Parameters:
      name - the attribute name to check
      Returns:
      true if the attribute exists, false otherwise

    • attributeObject

      public Attribute attributeObject(String name)
      Gets the Attribute object for the specified attribute name.
      Parameters:
      name - the attribute name
      Returns:
      the Attribute object, or null if the attribute doesn't exist

    • attributeObject

      public Element attributeObject(String name, Attribute attribute)
      Sets an attribute using an Attribute object.
      Parameters:
      name - the attribute name
      attribute - the Attribute object to set
      Returns:
      this element for method chaining

    • attributeWhitespace

      public Element attributeWhitespace(String attributeName, String whitespace)
      Sets the preceding whitespace for the specified attribute.
      Parameters:
      attributeName - the name of the attribute
      whitespace - the whitespace to set before the attribute
      Returns:
      this element for method chaining

    • attributeWhitespace

      public String attributeWhitespace(String attributeName)
      Gets the preceding whitespace for the specified attribute.
      Parameters:
      attributeName - the name of the attribute
      Returns:
      the preceding whitespace, or a single space if not set

    • attributeQuote

      public Element attributeQuote(String attributeName, QuoteStyle quoteStyle)
      Sets the quote character for the specified attribute.
      Parameters:
      attributeName - the name of the attribute
      quoteStyle - the quote style to use (SINGLE or DOUBLE)
      Returns:
      this element for method chaining

    • attributeQuote

      public QuoteStyle attributeQuote(String attributeName)
      Gets the quote style for the specified attribute.
      Parameters:
      attributeName - the name of the attribute
      Returns:
      the quote style, or DOUBLE if not set

    • parent

      public Element parent(ContainerNode parent)
      Sets the parent container node of this node.

      This method is typically called automatically when adding nodes to containers. Manual use should be done carefully to maintain tree consistency.

      Overrides:
      parent in class Node
      Parameters:
      parent - the parent container node to set, or null to clear the parent
      Returns:
      this element for method chaining
      See Also:

    • precedingWhitespace

      public Element precedingWhitespace(String whitespace)
      Sets the whitespace that precedes this node.

      This method allows control over the whitespace formatting before this node when serializing to XML.

      Overrides:
      precedingWhitespace in class Node
      Parameters:
      whitespace - the whitespace string to set, null is treated as empty string
      Returns:
      this element for method chaining
      See Also:

    • openTagWhitespace

      public String openTagWhitespace()
      Gets the whitespace within the opening tag (before the closing >).
      Returns:
      the whitespace within the opening tag

    • openTagWhitespace

      public Element openTagWhitespace(String whitespace)
      Sets the whitespace within the opening tag (before the closing >).
      Parameters:
      whitespace - the whitespace to set
      Returns:
      this element for method chaining

    • closeTagWhitespace

      public String closeTagWhitespace()
      Gets the whitespace within the closing tag (before the element name).
      Returns:
      the whitespace within the closing tag

    • closeTagWhitespace

      public Element closeTagWhitespace(String whitespace)
      Sets the whitespace within the closing tag (before the element name).
      Parameters:
      whitespace - the whitespace to set
      Returns:
      this element for method chaining

    • innerPrecedingWhitespace

      public String innerPrecedingWhitespace()
      Gets the whitespace immediately before the closing tag.

      This field is used for elements that contain only whitespace content (no child elements). It represents the whitespace that appears just before the closing tag, typically used for proper indentation.

      Example:

      // XML: <parent>\n    \n</parent>
String whitespace = element.innerPrecedingWhitespace(); // "\n"
      Returns:
      the inner preceding whitespace, or empty string if none
      See Also:

    • innerPrecedingWhitespace

      public Element innerPrecedingWhitespace(String whitespace)
      Sets the whitespace immediately before the closing tag.

      Use this method to control the whitespace that appears immediately before the closing tag in elements that contain only whitespace content. This is typically used for proper indentation of the closing tag.

      Example:

      element.innerPrecedingWhitespace("\n");
// Results in: <element>content\n</element> (whitespace before closing tag)
      Parameters:
      whitespace - the whitespace to set (null is treated as empty string)
      Returns:
      this element for method chaining
      See Also:

    • selfClosing

      public boolean selfClosing()
      Checks if this element is self-closing.
      Returns:
      true if the element is self-closing, false otherwise

    • selfClosing

      public Element selfClosing(boolean selfClosing)
      Sets whether this element should be self-closing.
      Parameters:
      selfClosing - true to make the element self-closing, false otherwise
      Returns:
      this element for method chaining

    • originalOpenTag

      public String originalOpenTag()
      Provide the original open tag exactly as it appeared in the source, or an empty string if none is available. If the element was parsed from a source buffer and the original open-tag slice is available, the tag is materialized from that source on first access.
      Returns:
      the original opening tag string, or empty string if not available

    • originalOpenTag

      public Element originalOpenTag(String originalOpenTag)
      Set the materialized original open tag and disable source-backed tag slicing.
      Parameters:
      originalOpenTag - the original opening tag; null is treated as an empty string
      Returns:
      this element for method chaining

    • originalCloseTag

      public String originalCloseTag()
      Gets the original closing tag as it appeared in the source XML.
      Returns:
      the original closing tag string, or empty string if not available

    • originalCloseTag

      public Element originalCloseTag(String originalCloseTag)
      Set the materialized original closing tag and disable source-backed close-tag slicing. If `originalCloseTag` is null, an empty string is stored. Calling this method clears any source-backed close-tag indices so future preserved serialization will use the provided string.
      Parameters:
      originalCloseTag - the original closing tag string (null is stored as an empty string)
      Returns:
      this element for method chaining

    • toXml

      public void toXml(StringBuilder sb)
      Serialize this element into XML and append the result to the supplied StringBuilder. If the element has not been modified and an original open tag is available, the original tag formatting is preserved; otherwise the element is serialized from scratch using the element's current state.
      Specified by:
      toXml in class Node
      Parameters:
      sb - the StringBuilder to append the XML representation to
      See Also:

    • textContent

      public String textContent()
      Gets the text content of this element (concatenates all text children)
      Overrides:
      textContent in class ContainerNode
      Returns:
      the text content of this node (concatenates all text children).

    • textContentOr

      public String textContentOr(String defaultValue)
      Gets the text content of this element, returning a default value if the text content is null or empty.

      This is a convenience method for getting text content with a fallback value.

      Example:

      Element scope = dependency.child("scope").orElse(null);
String scopeValue = scope != null ? scope.textContentOr("compile") : "compile";
// Or more simply:
String scopeValue = dependency.child("scope")
    .map(e -> e.textContentOr("compile"))
    .orElse("compile");
      Parameters:
      defaultValue - the default value to return if text content is null or empty
      Returns:
      the text content or default value
      Since:
      0.3.0

    • textContent

      public Element textContent(String content)
      Sets the text content, replacing all existing text children.

      Note: This method replaces all text children and does not preserve existing whitespace patterns. For whitespace-preserving updates, use textPreservingWhitespace(String) instead.

      Parameters:
      content - the new text content
      Returns:
      this element for method chaining
      See Also:

    • textPreservingWhitespace

      public Element textPreservingWhitespace(String content)
      Sets the text content while preserving existing whitespace patterns.

      This method attempts to preserve the whitespace structure of the existing text content when updating to new content. If the element has existing text with leading/trailing whitespace, the same pattern will be applied to the new content.

      Examples:

      // Original: <item>   old value   </item>
element.textPreservingWhitespace("new value");
// Result:   <item>   new value   </item>

// Original: <item>old value</item>
element.textPreservingWhitespace("new value");
// Result:   <item>new value</item>
      Parameters:
      content - the new text content
      Returns:
      this element for method chaining
      See Also:

    • textContentTrimmed

      public String textContentTrimmed()
      Gets the text content with leading and trailing whitespace removed.

      This is a convenience method that returns the trimmed text content without modifying the original content. Useful for getting clean content for processing while preserving the original formatting.

      Returns:
      the text content with leading and trailing whitespace removed
      See Also:

    • textContentTrimmedOr

      public String textContentTrimmedOr(String defaultValue)
      Gets the text content with leading and trailing whitespace removed if non-empty and non-null, otherwise returns the default value.

      This is a convenience method that returns the trimmed text content without modifying the original content. Useful for getting clean content for processing while preserving the original formatting.

      Returns:
      the text content with leading and trailing whitespace removed or default value
      Since:
      0.3.1
      See Also:

    • localName

      public String localName()
      Gets the local name part of this element (without namespace prefix).

    • prefix

      public String prefix()
      Gets the namespace prefix of this element. Returns null if the element has no prefix.

    • qualifiedName

      public String qualifiedName()
      Gets the qualified name of this element (prefix:localName or just localName).

    • namespaceURI

      public String namespaceURI()
      Gets the namespace URI of this element. Returns null if the element is not in any namespace.

    • inNamespace

      public boolean inNamespace(String namespaceURI)
      Checks if this element is in the specified namespace.

    • namespaceContext

      public NamespaceContext namespaceContext()
      Gets the namespace context for this element. Includes all namespace declarations from this element and its ancestors.

    • namespaceDeclaration

      public Element namespaceDeclaration(String prefix, String namespaceURI)
      Sets a namespace declaration attribute (xmlns or xmlns:prefix).
      Parameters:
      prefix - the namespace prefix, or null/empty for default namespace
      namespaceURI - the namespace URI
      Returns:
      this element for method chaining

    • namespaceDeclaration

      public String namespaceDeclaration(String prefix)
      Gets a namespace declaration for the given prefix. Returns null if no declaration is found on this element.

    • removeNamespaceDeclaration

      public void removeNamespaceDeclaration(String prefix)
      Removes a namespace declaration.

    • descendants

      public Stream<Element> descendants()
      Returns a stream of all descendant elements (depth-first traversal).

    • childElement

      public Optional<Element> childElement(QName qname)
      Finds the first child element with the given QName.
      Parameters:
      qname - the QName to match
      Returns:
      an Optional containing the first matching child element, or empty if none found

    • childElement

      public Optional<Element> childElement(String name)
      Finds the first child element with the given name.
      Parameters:
      name - the element name to match
      Returns:
      an Optional containing the first matching child element, or empty if none found

    • childTextOr

      public String childTextOr(String childName, String defaultValue)
      Gets the text content of an optional child element with the given name.

      This is a convenience method that combines child element lookup and text content extraction with a default value, making it useful for reading optional configuration values. If the child element exists but has no text content (empty element), the default value is returned.

      Example:

      Element dependency = ...;
// Get scope with default value "compile"
String scope = dependency.childTextOr("scope", "compile");

// Get optional classifier (returns null if not present)
String classifier = dependency.childTextOr("classifier", null);
      Parameters:
      childName - the name of the child element
      defaultValue - the default value to return if child is not found or has no text content
      Returns:
      the text content of the child or default value
      Since:
      0.3.0

    • childText

      public String childText(String childName)
      Gets the text content of a child element, or returns null if not found.

      This is a convenience method that provides a simple way to get child element text content with null fallback instead of handling Optional.

      Parameters:
      childName - the child element name
      Returns:
      the text content of the child element, or null if not found
      See Also:

    • childTextTrimmed

      public String childTextTrimmed(String childName)
      Gets the trimmed text content of a child element, or returns null if not found.

      This is a convenience method that provides a simple way to get trimmed child element text content with null fallback instead of handling Optional.

      Parameters:
      childName - the child element name
      Returns:
      the trimmed text content of the child element, or null if not found
      See Also:

    • childTextRequired

      public String childTextRequired(String childName)
      Gets the text content of a required child element with the given name.

      This method is useful when a child element is mandatory and you want to fail fast with a clear error message if it's missing.

      Example:

      Element dependency = ...;
// Get required groupId (throws if missing)
String groupId = dependency.childTextRequired("groupId");
      Parameters:
      childName - the name of the child element
      Returns:
      the text content of the child
      Throws:
      DomTripException - if the child element is not found
      Since:
      0.3.0

    • childElements

      public Stream<Element> childElements(QName qname)
      Finds all child elements with the given QName.
      Parameters:
      qname - the QName to match
      Returns:
      a Stream of matching child elements

    • childElements

      public Stream<Element> childElements(String name)
      Finds all child elements with the given name.
      Parameters:
      name - the element name to match
      Returns:
      a Stream of matching child elements

    • childElements

      public Stream<Element> childElements()
      Finds all child elements.
      Returns:
      a Stream of all child elements

    • descendant

      public Optional<Element> descendant(QName qname)
      Finds the first descendant element with the given QName.
      Parameters:
      qname - the QName to match
      Returns:
      an Optional containing the first matching descendant element, or empty if none found

    • descendant

      public Optional<Element> descendant(String name)
      Finds the first descendant element with the given name.
      Parameters:
      name - the element name to match
      Returns:
      an Optional containing the first matching descendant element, or empty if none found

    • descendants

      public Stream<Element> descendants(QName qname)
      Finds all descendant elements with the given QName.
      Parameters:
      qname - the QName to match
      Returns:
      a Stream of matching descendant elements

    • descendants

      public Stream<Element> descendants(String name)
      Finds all descendant elements with the given name (convenience method).
      Parameters:
      name - the element name to match
      Returns:
      a Stream of matching descendant elements

    • textChild

      public Optional<Text> textChild()
      Finds the first text child node.
      Returns:
      an Optional containing the first text child, or empty if none found

    • query

      public ElementQuery query()
      Creates a fluent query builder for finding elements.
      Returns:
      a new ElementQuery for fluent element searching

    • select

      public List<Element> select(String expression)
      Evaluates a mini-XPath expression against this element and returns all matching elements.

      This is a convenience method that compiles and evaluates the expression in one step. For repeated evaluation of the same expression, use XPathExpression.compile(String) to compile once and reuse.

      Examples:

      List<Element> deps = root.select("dependencies/dependency");
List<Element> allDeps = root.select("//dependency");
List<Element> testDeps = root.select("//dependency[@scope='test']");
      Parameters:
      expression - the mini-XPath expression
      Returns:
      a list of matching elements, never null
      Throws:
      DomTripException - if the expression is invalid
      Since:
      1.3.0
      See Also:

    • selectFirst

      public Optional<Element> selectFirst(String expression)
      Evaluates a mini-XPath expression against this element and returns the first match.

      This is a convenience method that compiles and evaluates the expression in one step. For repeated evaluation of the same expression, use XPathExpression.compile(String) to compile once and reuse.

      Examples:

      Optional<Element> dep = root.selectFirst("//dependency[groupId='junit']");
Optional<Element> ver = root.selectFirst("project/version");
      Parameters:
      expression - the mini-XPath expression
      Returns:
      an Optional containing the first matching element, or empty if none found
      Throws:
      DomTripException - if the expression is invalid
      Since:
      1.3.0
      See Also:

    • accept

      public DomTripVisitor.Action accept(DomTripVisitor visitor)
      Accepts a visitor for depth-first tree traversal.

      Calls DomTripVisitor.enterElement(Element) before visiting children and DomTripVisitor.exitElement(Element) after. If enterElement returns DomTripVisitor.Action.SKIP, children are not visited but exitElement is still called. If any visit method returns DomTripVisitor.Action.STOP, traversal aborts immediately.

      Specified by:
      accept in class Node
      Parameters:
      visitor - the visitor to accept
      Returns:
      the action indicating how traversal should proceed
      Throws:
      IllegalArgumentException - if visitor is null
      Since:
      1.3.0
      See Also:

    • walk

      public TreeWalker walk()
      Creates a lambda-friendly tree walker starting from this element.

      This provides a fluent API alternative to implementing DomTripVisitor directly:

      element.walk()
    .onEnter(e -> {
        if ("secret".equals(e.localName())) {
            e.textContent("***");
            return Action.SKIP;
        }
        return Action.CONTINUE;
    })
    .onExit(e -> { /* cleanup *&#47; })
    .onText(t -> { /* process text *&#47; })
    .execute();
      Returns:
      a new TreeWalker for fluent traversal configuration
      Since:
      1.3.0
      See Also:

    • path

      public Optional<Element> path(String... path)
      Finds an element by following a path of element names from this element.

      Example: element.path("dependencies", "dependency") will find the first dependency element under this element's dependencies child.

      Parameters:
      path - the path of element names to follow
      Returns:
      an Optional containing the element at the end of the path, or empty if not found

    • path

      public Optional<Element> path(QName... path)
      Finds an element by following a path of QNames from this element.
      Parameters:
      path - the path of QNames to follow
      Returns:
      an Optional containing the element at the end of the path, or empty if not found

    • copy

      public Element copy()
      Creates a deep copy of this node.

      The copied node will have:

      • All properties copied from the original
      • All child nodes recursively copied (for container nodes)
      • Whitespace and formatting properties preserved
      • No parent (parent is set to null)

      The copied node and its descendants will have their parent-child relationships properly established within the copied subtree.

      Specified by:
      copy in class Node
      Returns:
      a new node that is a deep copy of this node
      Since:
      1.1.0

    • clone

      @Deprecated public Element clone()
      Deprecated.
      Use copy() instead.
      Creates a deep copy of this element.
      Overrides:
      clone in class Node
      Returns:
      a new element that is a copy of this element

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • of

      public static Element of(String name) throws DomTripException
      Creates a simple element.
      Parameters:
      name - the element name
      Returns:
      a new Element
      Throws:
      DomTripException

    • of

      public static Element of(QName qname) throws DomTripException
      Creates an element from a QName.
      Parameters:
      qname - the QName for the element
      Returns:
      a new Element with namespace configuration
      Throws:
      DomTripException - if qname is null

    • text

      public static Element text(String name, String content) throws DomTripException
      Creates a simple text element.

      Creates an element with the specified name and text content. This is a convenience method for creating elements that contain only text.

      Parameters:
      name - the element name
      content - the text content to add
      Returns:
      a new Element with text content
      Throws:
      DomTripException

    • selfClosing

      public static Element selfClosing(String name) throws DomTripException
      Creates a self-closing element.

      Creates an element that will be serialized as a self-closing tag (e.g., <br/> instead of <br></br>).

      Parameters:
      name - the element name
      Returns:
      a new self-closing Element
      Throws:
      DomTripException

    • withAttributes

      public static Element withAttributes(String name, Map<String,String> attributes) throws DomTripException
      Creates an element with attributes.

      Creates an element with the specified name and adds all the provided attributes.

      Parameters:
      name - the element name
      attributes - a map of attribute names to values
      Returns:
      a new Element with attributes
      Throws:
      DomTripException

    • withTextAndAttributes

      public static Element withTextAndAttributes(String name, String content, Map<String,String> attributes) throws DomTripException
      Creates an element with text content and attributes.

      Creates an element with the specified name, adds all the provided attributes, and includes the specified text content.

      Parameters:
      name - the element name
      content - the text content to add
      attributes - a map of attribute names to values
      Returns:
      a new Element with text content and attributes
      Throws:
      DomTripException

    • cdata

      public static Element cdata(String name, String content) throws DomTripException
      Creates a CDATA element.

      Creates an element with the specified name and adds a CDATA section containing the provided content. CDATA sections preserve content exactly without XML entity escaping.

      Parameters:
      name - the element name
      content - the CDATA content to add
      Returns:
      a new Element with CDATA content
      Throws:
      DomTripException

    • text

      public static Element text(QName qname, String content) throws DomTripException
      Creates an element from a QName with text content.
      Parameters:
      qname - the QName for the element
      content - the text content to add
      Returns:
      a new Element with namespace configuration and text content
      Throws:
      DomTripException - if qname is null

    • comment

      public static Comment comment(String content)
      Creates a comment node.

      Creates a Comment node with the specified content. This is a convenience method equivalent to Comment.of(String).

      Parameters:
      content - the comment content
      Returns:
      a new Comment node
      See Also:

    • processingInstruction

      public static ProcessingInstruction processingInstruction(String target, String data)
      Creates a processing instruction.

      Creates a ProcessingInstruction node with the specified target and data. This is a convenience method equivalent to ProcessingInstruction.of(String, String).

      Parameters:
      target - the processing instruction target
      data - the processing instruction data
      Returns:
      a new ProcessingInstruction node
      See Also: