XmlSlurper (groovy 2.4.10 API)
Date: 2017-03-14

Package: groovy.util

## [Java] Class XmlSlurper

- groovy.util.XmlSlurper

- Parse XML into a document tree that may be traversed similar to XPath expressions. For example:

       def rootNode = new XmlSlurper().parseText(
          '<root><one a1="uno!"/><two>Some text!</two></root>' )

       assert rootNode.name() == 'root'
       assert rootNode.one[0].@a1 == 'uno!'
       assert rootNode.two.text() == 'Some text!'
       rootNode.children().each { assert it.name() in ['one','two'] }

  Note that in some cases, a 'selector' expression may not resolve to a single node. For example:

       def rootNode = new XmlSlurper().parseText(
          '''<root>
               <a>one!</a>
               <a>two!</a>
             </root>''' )

       assert rootNode.a.size() == 2
       rootNode.a.each { assert it.text() in ['one!','two!'] }

  See Also:
    GPathResult
  Authors:
    John Wilson

- - ### Constructor Summary

    Constructors
    Constructor and description
    `XmlSlurper ()` Creates a non-validating and namespace-aware `XmlSlurper` which does not allow DOCTYPE declarations in documents.
    `XmlSlurper (boolean validating, boolean namespaceAware)` Creates a `XmlSlurper` which does not allow DOCTYPE declarations in documents.
    `XmlSlurper (boolean validating, boolean namespaceAware, boolean allowDocTypeDeclaration)` Creates a `XmlSlurper`.
    `XmlSlurper (XMLReader reader)`
    `XmlSlurper (SAXParser parser)`

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `void` | `characters(char[] ch, int start, int length)`
    `` | `void` | `endDocument()`
    `` | `void` | `endElement(String namespaceURI, String localName, String qName)`
    `` | `DTDHandler` | `getDTDHandler()`
    `` | `GPathResult` | `getDocument()` @return The GPathResult instance created by consuming a stream of SAX events Note if one of the parse methods has been called then this returns null Note if this is called more than once all calls after the first will return null
    `` | `EntityResolver` | `getEntityResolver()`
    `` | `ErrorHandler` | `getErrorHandler()`
    `` | `boolean` | `getFeature(String uri)`
    `` | `Object` | `getProperty(String uri)`
    `` | `void` | `ignorableWhitespace(char[] buffer, int start, int len)`
    `` | `boolean` | `isKeepIgnorableWhitespace()` @return true if ignorable whitespace is kept
    `` | `GPathResult` | `parse(InputSource input)` Parse the content of the specified input source into a GPathResult object
    `` | `GPathResult` | `parse(File file)` Parses the content of the given file as XML turning it into a GPathResult object
    `` | `GPathResult` | `parse(InputStream input)` Parse the content of the specified input stream into an GPathResult Object.
    `` | `GPathResult` | `parse(Reader in)` Parse the content of the specified reader into a GPathResult Object.
    `` | `GPathResult` | `parse(String uri)` Parse the content of the specified URI into a GPathResult Object
    `` | `GPathResult` | `parseText(String text)` A helper method to parse the given text as XML
    `` | `void` | `setDTDHandler(DTDHandler dtdHandler)`
    `` | `void` | `setEntityBaseUrl(URL base)` Resolves entities against using the supplied URL as the base for relative URLs
    `` | `void` | `setEntityResolver(EntityResolver entityResolver)`
    `` | `void` | `setErrorHandler(ErrorHandler errorHandler)`
    `` | `void` | `setFeature(String uri, boolean value)`
    `` | `void` | `setKeepIgnorableWhitespace(boolean keepIgnorableWhitespace)` Parameters: `keepIgnorableWhitespace` - If true then ignorable whitespace (i.e. whitespace before elements) is kept.
    `` | `void` | `setKeepWhitespace(boolean keepWhitespace)` @deprecated use setKeepIgnorableWhitespace
    `` | `void` | `setProperty(String uri, Object value)`
    `` | `void` | `startDocument()`
    `` | `void` | `startElement(String namespaceURI, String localName, String qName, Attributes atts)`
    `` | `void` | `startPrefixMapping(String tag, String uri)`

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class DefaultHandler` | `error, warning, characters, startElement, endElement, endDocument, startDocument, processingInstruction, ignorableWhitespace, endPrefixMapping, fatalError, notationDecl, resolveEntity, setDocumentLocator, skippedEntity, startPrefixMapping, unparsedEntityDecl, wait, wait, wait, equals, toString, hashCode, getClass, notify, notifyAll`
    `class Object` | `wait, wait, wait, equals, toString, hashCode, getClass, notify, notifyAll`

- - ### Constructor Detail

    - #### public XmlSlurper()

      Creates a non-validating and namespace-aware `XmlSlurper` which does not allow DOCTYPE declarations in documents.

      throws:
        ParserConfigurationException if no parser which satisfies the requested configuration can be created.
      throws:
        SAXException for SAX errors.

    - #### public XmlSlurper(boolean validating, boolean namespaceAware)

      Creates a `XmlSlurper` which does not allow DOCTYPE declarations in documents.

      throws:
        ParserConfigurationException if no parser which satisfies the requested configuration can be created.
      throws:
        SAXException for SAX errors.
      Parameters:
        `validating` - `true` if the parser should validate documents as they are parsed; false otherwise.
        `namespaceAware` - `true` if the parser should provide support for XML namespaces; `false` otherwise.

    - #### public XmlSlurper(boolean validating, boolean namespaceAware, boolean allowDocTypeDeclaration)

      Creates a `XmlSlurper`.

      throws:
        ParserConfigurationException if no parser which satisfies the requested configuration can be created.
      throws:
        SAXException for SAX errors.
      Parameters:
        `validating` - `true` if the parser should validate documents as they are parsed; false otherwise.
        `namespaceAware` - `true` if the parser should provide support for XML namespaces; `false` otherwise.
        `allowDocTypeDeclaration` - `true` if the parser should provide support for DOCTYPE declarations; `false` otherwise.

    - #### public XmlSlurper(XMLReader reader)

    - #### public XmlSlurper(SAXParser parser)

  - ### Method Detail

    - #### public void characters(char[] ch, int start, int length)

    - #### public void endDocument()

    - #### public void endElement(String namespaceURI, String localName, String qName)

    - #### public DTDHandler getDTDHandler()

    - #### public GPathResult getDocument()

      Returns:
        The GPathResult instance created by consuming a stream of SAX events Note if one of the parse methods has been called then this returns null Note if this is called more than once all calls after the first will return null

    - #### public EntityResolver getEntityResolver()

    - #### public ErrorHandler getErrorHandler()

    - #### public boolean getFeature(String uri)

    - #### public Object getProperty(String uri)

    - #### public void ignorableWhitespace(char[] buffer, int start, int len)

    - #### public boolean isKeepIgnorableWhitespace()

      Returns:
        true if ignorable whitespace is kept

    - #### public GPathResult parse(InputSource input)

      Parse the content of the specified input source into a GPathResult object

      throws:
        SAXException Any SAX exception, possibly wrapping another exception.
      throws:
        IOException An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
      Returns:
        An object which supports GPath expressions
      Parameters:
        `input` - the InputSource to parse

    - #### public GPathResult parse(File file)

      Parses the content of the given file as XML turning it into a GPathResult object

      throws:
        SAXException Any SAX exception, possibly wrapping another exception.
      throws:
        IOException An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
      Returns:
        An object which supports GPath expressions
      Parameters:
        `file` - the File to parse

    - #### public GPathResult parse(InputStream input)

      Parse the content of the specified input stream into an GPathResult Object. Note that using this method will not provide the parser with any URI for which to find DTDs etc. It is up to you to close the InputStream after parsing is complete (if required).

      throws:
        SAXException Any SAX exception, possibly wrapping another exception.
      throws:
        IOException An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
      Returns:
        An object which supports GPath expressions
      Parameters:
        `input` - the InputStream to parse

    - #### public GPathResult parse(Reader in)

      Parse the content of the specified reader into a GPathResult Object. Note that using this method will not provide the parser with any URI for which to find DTDs etc. It is up to you to close the Reader after parsing is complete (if required).

      throws:
        SAXException Any SAX exception, possibly wrapping another exception.
      throws:
        IOException An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
      Returns:
        An object which supports GPath expressions
      Parameters:
        `in` - the Reader to parse

    - #### public GPathResult parse(String uri)

      Parse the content of the specified URI into a GPathResult Object

      throws:
        SAXException Any SAX exception, possibly wrapping another exception.
      throws:
        IOException An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
      Returns:
        An object which supports GPath expressions
      Parameters:
        `uri` - a String containing the URI to parse

    - #### public GPathResult parseText(String text)

      A helper method to parse the given text as XML

      throws:
        SAXException Any SAX exception, possibly wrapping another exception.
      throws:
        IOException An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
      Returns:
        An object which supports GPath expressions
      Parameters:
        `text` - a String containing XML to parse

    - #### public void setDTDHandler(DTDHandler dtdHandler)

    - #### public void setEntityBaseUrl(URL base)

      Resolves entities against using the supplied URL as the base for relative URLs

      Parameters:
        `base` - The URL used to resolve relative URLs

    - #### public void setEntityResolver(EntityResolver entityResolver)

    - #### public void setErrorHandler(ErrorHandler errorHandler)

    - #### public void setFeature(String uri, boolean value)

    - #### public void setKeepIgnorableWhitespace(boolean keepIgnorableWhitespace)

      Parameters:
        `keepIgnorableWhitespace` - If true then ignorable whitespace (i.e. whitespace before elements) is kept. The default is to discard the whitespace.

    - #### @Deprecated public void setKeepWhitespace(boolean keepWhitespace)

      deprecated:
        use setKeepIgnorableWhitespace
      Parameters:
        `keepWhitespace` - If true then whitespace before elements is kept. The default is to discard the whitespace.

    - #### public void setProperty(String uri, Object value)

    - #### public void startDocument()

    - #### public void startElement(String namespaceURI, String localName, String qName, Attributes atts)

    - #### public void startPrefixMapping(String tag, String uri)