processing.data

## Class XML

- java.lang.Object
- - processing.data.XML

- All Implemented Interfaces:
    Serializable

      public class XML
      extends Object
      implements Serializable

  This is the base class used for the Processing XML library, representing a single node of an XML tree.
  See Also:
    `PApplet#createXML(String)`, `PApplet.loadXML(String)`, `PApplet.parseXML(String)`, `PApplet.saveXML(XML, String)`, Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `XML(File file)` Advanced users only; use loadXML() in PApplet.
    `XML(File file, String options)` Advanced users only; use loadXML() in PApplet.
    `XML(InputStream input)`
    `XML(InputStream input, String options)` Unlike the loadXML() method in PApplet, this version works with files that are not in UTF-8 format.
    `XML(Reader reader)` Advanced users only; use loadXML() in PApplet.
    `XML(Reader reader, String options)` Advanced users only; use loadXML() in PApplet.
    `XML(String name)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `XML` | `addChild(String tag)`
    `XML` | `addChild(XML child)`
    `String` | `format(int indent)` Format this XML data as a String.
    `int` | `getAttributeCount()` Returns the number of attributes.
    `XML` | `getChild(int index)` Quick accessor for an element at a particular index.
    `XML` | `getChild(String name)` Get a child by its name or path.
    `int` | `getChildCount()` Returns the number of children.
    `XML[]` | `getChildren()` Returns an array containing all the child elements.
    `XML[]` | `getChildren(String name)` Get any children that match this name or path.
    `String` | `getContent()` Return the #PCDATA content of the element.
    `String` | `getContent(String defaultValue)`
    `double` | `getDouble(String name)`
    `double` | `getDouble(String name, double defaultValue)` Returns the value of an attribute.
    `double` | `getDoubleContent()`
    `double` | `getDoubleContent(double defaultValue)`
    `float` | `getFloat(String name)` Returns the value of an attribute, or zero if not present.
    `float` | `getFloat(String name, float defaultValue)` Returns the value of an attribute.
    `float` | `getFloatContent()`
    `float` | `getFloatContent(float defaultValue)`
    `int` | `getInt(String name)`
    `int` | `getInt(String name, int defaultValue)` Returns the value of an attribute.
    `int` | `getIntContent()`
    `int` | `getIntContent(int defaultValue)`
    `String` | `getLocalName()` Returns the name of the element (without namespace prefix).
    `long` | `getLong(String name, long defaultValue)` Returns the value of an attribute.
    `long` | `getLongContent()`
    `long` | `getLongContent(long defaultValue)`
    `String` | `getName()` Returns the full name (i.e.
    `XML` | `getParent()` Returns the parent element.
    `String` | `getString(String name)`
    `String` | `getString(String name, String defaultValue)`
    `boolean` | `hasAttribute(String name)` Returns whether an attribute exists.
    `boolean` | `hasChildren()` Returns a boolean of whether or not there are children.
    `String[]` | `listAttributes()` Get a list of the names for all of the attributes for this node.
    `String[]` | `listChildren()` Put the names of all children into an array.
    `static XML` | `parse(String data)`
    `static XML` | `parse(String data, String options)`
    `void` | `removeChild(XML kid)`
    `boolean` | `save(File file, String options)`
    `void` | `setContent(String text)`
    `void` | `setDouble(String name, double value)`
    `void` | `setDoubleContent(double value)`
    `void` | `setFloat(String name, float value)`
    `void` | `setFloatContent(float value)`
    `void` | `setInt(String name, int value)`
    `void` | `setIntContent(int value)`
    `void` | `setLong(String name, long value)`
    `void` | `setLongContent(long value)`
    `void` | `setName(String newName)`
    `void` | `setString(String name, String value)`
    `String` | `toString()` Return the XML document formatted with two spaces for indents.
    `boolean` | `write(PrintWriter output)`

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

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

- - ### Constructor Detail

    - #### XML

          public XML(File file)
              throws IOException,
                     ParserConfigurationException,
                     SAXException

      Advanced users only; use loadXML() in PApplet. This is not a supported function and is subject to change. It is available simply for users that would like to handle the exceptions in a particular way.
      Throws:
        `IOException`
        `ParserConfigurationException`
        `SAXException`

    - #### XML

          public XML(File file,
             String options)
              throws IOException,
                     ParserConfigurationException,
                     SAXException

      Advanced users only; use loadXML() in PApplet.
      Throws:
        `IOException`
        `ParserConfigurationException`
        `SAXException`

    - #### XML

          public XML(InputStream input)
              throws IOException,
                     ParserConfigurationException,
                     SAXException

      Throws:
        `IOException`
        `ParserConfigurationException`
        `SAXException`

    - #### XML

          public XML(InputStream input,
             String options)
              throws IOException,
                     ParserConfigurationException,
                     SAXException

      Unlike the loadXML() method in PApplet, this version works with files that are not in UTF-8 format.
      Throws:
        `IOException`
        `ParserConfigurationException`
        `SAXException`

    - #### XML

          public XML(Reader reader)
              throws IOException,
                     ParserConfigurationException,
                     SAXException

      Advanced users only; use loadXML() in PApplet.
      Throws:
        `IOException`
        `ParserConfigurationException`
        `SAXException`

    - #### XML

          public XML(Reader reader,
             String options)
              throws IOException,
                     ParserConfigurationException,
                     SAXException

      Advanced users only; use loadXML() in PApplet. Added extra code to handle   (Unicode NLF), which is sometimes inserted by web browsers (Safari?) and not distinguishable from a "real" LF (or CRLF) in some text editors (i.e. TextEdit on OS X). Only doing this for XML (and not all Reader objects) because LFs are essential. https://github.com/processing/processing/issues/2100
      Throws:
        `IOException`
        `ParserConfigurationException`
        `SAXException`

    - #### XML

          public XML(String name)

      Parameters:
        `name` - creates a node with this name

  - ### Method Detail

    - #### parse

          public static XML parse(String data)
                           throws IOException,
                                  ParserConfigurationException,
                                  SAXException

      Parameters:
        `data` - the content to be parsed as XML
      Returns:
        an XML object, or null
      Throws:
        `SAXException`
        `ParserConfigurationException`
        `IOException`

    - #### parse

          public static XML parse(String data,
                  String options)
                           throws IOException,
                                  ParserConfigurationException,
                                  SAXException

      Throws:
        `IOException`
        `ParserConfigurationException`
        `SAXException`

    - #### save

          public boolean save(File file,
                     String options)

    - #### write

          public boolean write(PrintWriter output)

    - #### getParent

          public XML getParent()

      Returns the parent element. This method returns null for the root element.

    - #### getName

          public String getName()

      Returns the full name (i.e. the name including an eventual namespace prefix) of the element.
      Returns:
        the name, or null if the element only contains #PCDATA.

    - #### setName

          public void setName(String newName)

    - #### getLocalName

          public String getLocalName()

      Returns the name of the element (without namespace prefix). Internal function; not included in reference.

    - #### getChildCount

          public int getChildCount()

      Returns the number of children.
      Returns:
        the count.

    - #### hasChildren

          public boolean hasChildren()

      Returns a boolean of whether or not there are children.

    - #### listChildren

          public String[] listChildren()

      Put the names of all children into an array. Same as looping through each child and calling getName() on each XMLElement.

    - #### getChildren

          public XML[] getChildren()

      Returns an array containing all the child elements.

    - #### getChild

          public XML getChild(int index)

      Quick accessor for an element at a particular index.

    - #### getChild

          public XML getChild(String name)

      Get a child by its name or path.
      Parameters:
        `name` - element name or path/to/element
      Returns:
        the first matching element

    - #### getChildren

          public XML[] getChildren(String name)

      Get any children that match this name or path. Similar to getChild(), but will grab multiple matches rather than only the first.
      Parameters:
        `name` - element name or path/to/element
      Returns:
        array of child elements that match

    - #### addChild

          public XML addChild(String tag)

    - #### addChild

          public XML addChild(XML child)

    - #### removeChild

          public void removeChild(XML kid)

    - #### getAttributeCount

          public int getAttributeCount()

      Returns the number of attributes.

    - #### listAttributes

          public String[] listAttributes()

      Get a list of the names for all of the attributes for this node.

    - #### hasAttribute

          public boolean hasAttribute(String name)

      Returns whether an attribute exists.

    - #### getString

          public String getString(String name)

    - #### getString

          public String getString(String name,
                         String defaultValue)

    - #### setString

          public void setString(String name,
                       String value)

    - #### getInt

          public int getInt(String name)

    - #### setInt

          public void setInt(String name,
                    int value)

    - #### getInt

          public int getInt(String name,
                   int defaultValue)

      Returns the value of an attribute.
      Parameters:
        `name` - the non-null full name of the attribute
        `defaultValue` - the default value of the attribute
      Returns:
        the value, or defaultValue if the attribute does not exist

    - #### setLong

          public void setLong(String name,
                     long value)

    - #### getLong

          public long getLong(String name,
                     long defaultValue)

      Returns the value of an attribute.
      Parameters:
        `name` - the non-null full name of the attribute.
        `defaultValue` - the default value of the attribute.
      Returns:
        the value, or defaultValue if the attribute does not exist.

    - #### getFloat

          public float getFloat(String name)

      Returns the value of an attribute, or zero if not present.

    - #### getFloat

          public float getFloat(String name,
                       float defaultValue)

      Returns the value of an attribute.
      Parameters:
        `name` - the non-null full name of the attribute.
        `defaultValue` - the default value of the attribute.
      Returns:
        the value, or defaultValue if the attribute does not exist.

    - #### setFloat

          public void setFloat(String name,
                      float value)

    - #### getDouble

          public double getDouble(String name)

    - #### getDouble

          public double getDouble(String name,
                         double defaultValue)

      Returns the value of an attribute.
      Parameters:
        `name` - the non-null full name of the attribute
        `defaultValue` - the default value of the attribute
      Returns:
        the value, or defaultValue if the attribute does not exist

    - #### setDouble

          public void setDouble(String name,
                       double value)

    - #### getContent

          public String getContent()

      Return the #PCDATA content of the element. If the element has a combination of #PCDATA content and child elements, the #PCDATA sections can be retrieved as unnamed child objects. In this case, this method returns null.
      Returns:
        the content.
      See Also:
        `getIntContent()`, `getFloatContent()`

    - #### getContent

          public String getContent(String defaultValue)

    - #### getIntContent

          public int getIntContent()

      Returns:
        the content.
      See Also:
        `getContent()`, `getFloatContent()`

    - #### getIntContent

          public int getIntContent(int defaultValue)

      Parameters:
        `defaultValue` - the default value of the attribute

    - #### getFloatContent

          public float getFloatContent()

      Returns:
        the content.
      See Also:
        `getContent()`, `getIntContent()`

    - #### getFloatContent

          public float getFloatContent(float defaultValue)

      Parameters:
        `defaultValue` - the default value of the attribute

    - #### getLongContent

          public long getLongContent()

    - #### getLongContent

          public long getLongContent(long defaultValue)

    - #### getDoubleContent

          public double getDoubleContent()

    - #### getDoubleContent

          public double getDoubleContent(double defaultValue)

    - #### setContent

          public void setContent(String text)

    - #### setIntContent

          public void setIntContent(int value)

    - #### setFloatContent

          public void setFloatContent(float value)

    - #### setLongContent

          public void setLongContent(long value)

    - #### setDoubleContent

          public void setDoubleContent(double value)

    - #### format

          public String format(int indent)

      Format this XML data as a String.
      Parameters:
        `indent` - -1 for a single line (and no declaration), >= 0 for indents and newlines
      Returns:
        the content
      See Also:
        `toString()`

    - #### toString

          public String toString()

      Return the XML document formatted with two spaces for indents. Chosen to do this since it's the most common case (e.g. with println()). Same as format(2). Use the format() function for more options.
      Overrides:
        `toString` in class `Object`
      Returns:
        the content
      See Also:
        `format(int)`