groovy.util

## Class XmlSlurper

- java.lang.Object
- - org.xml.sax.helpers.DefaultHandler
  - - groovy.util.XmlSlurper

- All Implemented Interfaces:
    org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler

      public class XmlSlurper
      extends org.xml.sax.helpers.DefaultHandler

  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`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `XmlSlurper()` Uses the defaults of not validating and namespace aware.
    `XmlSlurper(boolean validating, boolean namespaceAware)`
    `XmlSlurper(javax.xml.parsers.SAXParser parser)`
    `XmlSlurper(org.xml.sax.XMLReader reader)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `characters(char[] ch, int start, int length)`
    `void` | `endDocument()`
    `void` | `endElement(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName)`
    `GPathResult` | `getDocument()`
    `org.xml.sax.DTDHandler` | `getDTDHandler()`
    `org.xml.sax.EntityResolver` | `getEntityResolver()`
    `org.xml.sax.ErrorHandler` | `getErrorHandler()`
    `boolean` | `getFeature(java.lang.String uri)`
    `java.lang.Object` | `getProperty(java.lang.String uri)`
    `GPathResult` | `parse(java.io.File file)` Parses the content of the given file as XML turning it into a GPathResult object
    `GPathResult` | `parse(org.xml.sax.InputSource input)` Parse the content of the specified input source into a GPathResult object
    `GPathResult` | `parse(java.io.InputStream input)` Parse the content of the specified input stream into an GPathResult Object.
    `GPathResult` | `parse(java.io.Reader in)` Parse the content of the specified reader into a GPathResult Object.
    `GPathResult` | `parse(java.lang.String uri)` Parse the content of the specified URI into a GPathResult Object
    `GPathResult` | `parseText(java.lang.String text)` A helper method to parse the given text as XML
    `void` | `setDTDHandler(org.xml.sax.DTDHandler dtdHandler)`
    `void` | `setEntityBaseUrl(java.net.URL base)` Resolves entities against using the supplied URL as the base for relative URLs
    `void` | `setEntityResolver(org.xml.sax.EntityResolver entityResolver)`
    `void` | `setErrorHandler(org.xml.sax.ErrorHandler errorHandler)`
    `void` | `setFeature(java.lang.String uri, boolean value)`
    `void` | `setKeepWhitespace(boolean keepWhitespace)`
    `void` | `setProperty(java.lang.String uri, java.lang.Object value)`
    `void` | `startDocument()`
    `void` | `startElement(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes atts)`
    `void` | `startPrefixMapping(java.lang.String tag, java.lang.String uri)`

    - ### Methods inherited from class org.xml.sax.helpers.DefaultHandler

      `endPrefixMapping, error, fatalError, ignorableWhitespace, notationDecl, processingInstruction, resolveEntity, setDocumentLocator, skippedEntity, unparsedEntityDecl, warning`

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

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

- - ### Constructor Detail

    - #### XmlSlurper

          public XmlSlurper()
                     throws javax.xml.parsers.ParserConfigurationException,
                            org.xml.sax.SAXException

      Uses the defaults of not validating and namespace aware.
      Throws:
        `javax.xml.parsers.ParserConfigurationException` - if a parser cannot be created which satisfies the requested configuration.
        `org.xml.sax.SAXException` - for SAX errors.

    - #### XmlSlurper

          public XmlSlurper(boolean validating,
                    boolean namespaceAware)
                     throws javax.xml.parsers.ParserConfigurationException,
                            org.xml.sax.SAXException

      Throws:
        `javax.xml.parsers.ParserConfigurationException`
        `org.xml.sax.SAXException`

    - #### XmlSlurper

          public XmlSlurper(org.xml.sax.XMLReader reader)

    - #### XmlSlurper

          public XmlSlurper(javax.xml.parsers.SAXParser parser)
                     throws org.xml.sax.SAXException

      Throws:
        `org.xml.sax.SAXException`

  - ### Method Detail

    - #### setKeepWhitespace

          public void setKeepWhitespace(boolean keepWhitespace)

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

    - #### getDocument

          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

    - #### parse

          public GPathResult parse(org.xml.sax.InputSource input)
                            throws java.io.IOException,
                                   org.xml.sax.SAXException

      Parse the content of the specified input source into a GPathResult object
      Parameters:
        `input` - the InputSource to parse
      Returns:
        An object which supports GPath expressions
      Throws:
        `org.xml.sax.SAXException` - Any SAX exception, possibly wrapping another exception.
        `java.io.IOException` - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.

    - #### parse

          public GPathResult parse(java.io.File file)
                            throws java.io.IOException,
                                   org.xml.sax.SAXException

      Parses the content of the given file as XML turning it into a GPathResult object
      Parameters:
        `file` - the File to parse
      Returns:
        An object which supports GPath expressions
      Throws:
        `org.xml.sax.SAXException` - Any SAX exception, possibly wrapping another exception.
        `java.io.IOException` - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.

    - #### parse

          public GPathResult parse(java.io.InputStream input)
                            throws java.io.IOException,
                                   org.xml.sax.SAXException

      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).
      Parameters:
        `input` - the InputStream to parse
      Returns:
        An object which supports GPath expressions
      Throws:
        `org.xml.sax.SAXException` - Any SAX exception, possibly wrapping another exception.
        `java.io.IOException` - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.

    - #### parse

          public GPathResult parse(java.io.Reader in)
                            throws java.io.IOException,
                                   org.xml.sax.SAXException

      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).
      Parameters:
        `in` - the Reader to parse
      Returns:
        An object which supports GPath expressions
      Throws:
        `org.xml.sax.SAXException` - Any SAX exception, possibly wrapping another exception.
        `java.io.IOException` - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.

    - #### parse

          public GPathResult parse(java.lang.String uri)
                            throws java.io.IOException,
                                   org.xml.sax.SAXException

      Parse the content of the specified URI into a GPathResult Object
      Parameters:
        `uri` - a String containing the URI to parse
      Returns:
        An object which supports GPath expressions
      Throws:
        `org.xml.sax.SAXException` - Any SAX exception, possibly wrapping another exception.
        `java.io.IOException` - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.

    - #### parseText

          public GPathResult parseText(java.lang.String text)
                                throws java.io.IOException,
                                       org.xml.sax.SAXException

      A helper method to parse the given text as XML
      Parameters:
        `text` - a String containing XML to parse
      Returns:
        An object which supports GPath expressions
      Throws:
        `org.xml.sax.SAXException` - Any SAX exception, possibly wrapping another exception.
        `java.io.IOException` - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.

    - #### getDTDHandler

          public org.xml.sax.DTDHandler getDTDHandler()

    - #### getEntityResolver

          public org.xml.sax.EntityResolver getEntityResolver()

    - #### getErrorHandler

          public org.xml.sax.ErrorHandler getErrorHandler()

    - #### getFeature

          public boolean getFeature(java.lang.String uri)
                             throws org.xml.sax.SAXNotRecognizedException,
                                    org.xml.sax.SAXNotSupportedException

      Throws:
        `org.xml.sax.SAXNotRecognizedException`
        `org.xml.sax.SAXNotSupportedException`

    - #### getProperty

          public java.lang.Object getProperty(java.lang.String uri)
                                       throws org.xml.sax.SAXNotRecognizedException,
                                              org.xml.sax.SAXNotSupportedException

      Throws:
        `org.xml.sax.SAXNotRecognizedException`
        `org.xml.sax.SAXNotSupportedException`

    - #### setDTDHandler

          public void setDTDHandler(org.xml.sax.DTDHandler dtdHandler)

    - #### setEntityResolver

          public void setEntityResolver(org.xml.sax.EntityResolver entityResolver)

    - #### setEntityBaseUrl

          public void setEntityBaseUrl(java.net.URL base)

      Resolves entities against using the supplied URL as the base for relative URLs
      Parameters:
        `base` - The URL used to resolve relative URLs

    - #### setErrorHandler

          public void setErrorHandler(org.xml.sax.ErrorHandler errorHandler)

    - #### setFeature

          public void setFeature(java.lang.String uri,
                        boolean value)
                          throws org.xml.sax.SAXNotRecognizedException,
                                 org.xml.sax.SAXNotSupportedException

      Throws:
        `org.xml.sax.SAXNotRecognizedException`
        `org.xml.sax.SAXNotSupportedException`

    - #### setProperty

          public void setProperty(java.lang.String uri,
                         java.lang.Object value)
                           throws org.xml.sax.SAXNotRecognizedException,
                                  org.xml.sax.SAXNotSupportedException

      Throws:
        `org.xml.sax.SAXNotRecognizedException`
        `org.xml.sax.SAXNotSupportedException`

    - #### startDocument

          public void startDocument()
                             throws org.xml.sax.SAXException

      Specified by:
        `startDocument` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `startDocument` in class `org.xml.sax.helpers.DefaultHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### startPrefixMapping

          public void startPrefixMapping(java.lang.String tag,
                                java.lang.String uri)
                                  throws org.xml.sax.SAXException

      Specified by:
        `startPrefixMapping` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `startPrefixMapping` in class `org.xml.sax.helpers.DefaultHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### startElement

          public void startElement(java.lang.String namespaceURI,
                          java.lang.String localName,
                          java.lang.String qName,
                          org.xml.sax.Attributes atts)
                            throws org.xml.sax.SAXException

      Specified by:
        `startElement` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `startElement` in class `org.xml.sax.helpers.DefaultHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### characters

          public void characters(char[] ch,
                        int start,
                        int length)
                          throws org.xml.sax.SAXException

      Specified by:
        `characters` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `characters` in class `org.xml.sax.helpers.DefaultHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### endElement

          public void endElement(java.lang.String namespaceURI,
                        java.lang.String localName,
                        java.lang.String qName)
                          throws org.xml.sax.SAXException

      Specified by:
        `endElement` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `endElement` in class `org.xml.sax.helpers.DefaultHandler`
      Throws:
        `org.xml.sax.SAXException`

    - #### endDocument

          public void endDocument()
                           throws org.xml.sax.SAXException

      Specified by:
        `endDocument` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `endDocument` in class `org.xml.sax.helpers.DefaultHandler`
      Throws:
        `org.xml.sax.SAXException`