Package groovy.xml

# Class XmlSlurper

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

All Implemented Interfaces:
  `ContentHandler`, `DTDHandler`, `EntityResolver`, `ErrorHandler`

public class XmlSlurper extends DefaultHandler
Parse XML into a document tree that may be traversed similar to XPath expressions. For example:

     import groovy.xml.XmlSlurper
     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:

     import groovy.xml.XmlSlurper
     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
  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(SAXParser parser)`
  `XmlSlurper(XMLReader reader)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `characters(char[] ch, int start, int length)`
  `void`
  `endDocument()`
  `void`
  `endElement(String namespaceURI, String localName, String qName)`
  `GPathResult`
  `getDocument()`
  `DTDHandler`
  `getDTDHandler()`
  `EntityResolver`
  `getEntityResolver()`
  `ErrorHandler`
  `getErrorHandler()`
  `boolean`
  `getFeature(String uri)`
  `Object`
  `getProperty(String uri)`
  `void`
  `ignorableWhitespace(char[] buffer, int start, int len)`
  `boolean`
  `isKeepIgnorableWhitespace()`
  `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`
  `parse(Path path)`
  Parses the content of the file at the given path as XML turning it into a GPathResult object
  `GPathResult`
  `parse(InputSource input)`
  Parse the content of the specified input source 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)`
  `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)`

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

  `endPrefixMapping, error, fatalError, 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`

  ### Methods inherited from interface org.xml.sax.ContentHandler

  `declaration`

- ## Constructor Details

  - ### XmlSlurper

    public XmlSlurper() throws ParserConfigurationException, SAXException
    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.
      `SAXException` - for SAX errors.

  - ### XmlSlurper

    public XmlSlurper(boolean validating, boolean namespaceAware) throws ParserConfigurationException, SAXException
    Creates a `XmlSlurper` which does not allow DOCTYPE declarations in documents.
    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.
    Throws:
      `ParserConfigurationException` - if no parser which satisfies the requested configuration can be created.
      `SAXException` - for SAX errors.

  - ### XmlSlurper

    public XmlSlurper(boolean validating, boolean namespaceAware, boolean allowDocTypeDeclaration) throws ParserConfigurationException, SAXException
    Creates a `XmlSlurper`.
    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.
    Throws:
      `ParserConfigurationException` - if no parser which satisfies the requested configuration can be created.
      `SAXException` - for SAX errors.

  - ### XmlSlurper

    public XmlSlurper(XMLReader reader)

  - ### XmlSlurper

    public XmlSlurper(SAXParser parser) throws SAXException
    Throws:
      `SAXException`

- ## Method Details

  - ### setKeepWhitespace

    @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.

  - ### setKeepIgnorableWhitespace

    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.

  - ### isKeepIgnorableWhitespace

    public boolean isKeepIgnorableWhitespace()
    Returns:
      true if ignorable whitespace is kept

  - ### 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(InputSource input) throws IOException, 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:
      `SAXException` - Any SAX exception, possibly wrapping another exception.
      `IOException` - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.

  - ### parse

    public GPathResult parse(File file) throws IOException, 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:
      `SAXException` - Any SAX exception, possibly wrapping another exception.
      `IOException` - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.

  - ### parse

    public GPathResult parse(InputStream input) throws IOException, 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:
      `SAXException` - Any SAX exception, possibly wrapping another exception.
      `IOException` - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.

  - ### parse

    public GPathResult parse(Reader in) throws IOException, 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:
      `SAXException` - Any SAX exception, possibly wrapping another exception.
      `IOException` - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.

  - ### parse

    public GPathResult parse(String uri) throws IOException, 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:
      `SAXException` - Any SAX exception, possibly wrapping another exception.
      `IOException` - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.

  - ### parse

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

  - ### parseText

    public GPathResult parseText(String text) throws IOException, 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:
      `SAXException` - Any SAX exception, possibly wrapping another exception.
      `IOException` - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.

  - ### getDTDHandler

    public DTDHandler getDTDHandler()

  - ### getEntityResolver

    public EntityResolver getEntityResolver()

  - ### getErrorHandler

    public ErrorHandler getErrorHandler()

  - ### getFeature

    public boolean getFeature(String uri) throws SAXNotRecognizedException, SAXNotSupportedException
    Throws:
      `SAXNotRecognizedException`
      `SAXNotSupportedException`

  - ### getProperty

    public Object getProperty(String uri) throws SAXNotRecognizedException, SAXNotSupportedException
    Throws:
      `SAXNotRecognizedException`
      `SAXNotSupportedException`

  - ### setDTDHandler

    public void setDTDHandler(DTDHandler dtdHandler)

  - ### setEntityResolver

    public void setEntityResolver(EntityResolver entityResolver)

  - ### setEntityBaseUrl

    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

  - ### setErrorHandler

    public void setErrorHandler(ErrorHandler errorHandler)

  - ### setFeature

    public void setFeature(String uri, boolean value) throws SAXNotRecognizedException, SAXNotSupportedException
    Throws:
      `SAXNotRecognizedException`
      `SAXNotSupportedException`

  - ### setProperty

    public void setProperty(String uri, Object value) throws SAXNotRecognizedException, SAXNotSupportedException
    Throws:
      `SAXNotRecognizedException`
      `SAXNotSupportedException`

  - ### startDocument

    public void startDocument() throws SAXException
    Specified by:
      `startDocument` in interface `ContentHandler`
    Overrides:
      `startDocument` in class `DefaultHandler`
    Throws:
      `SAXException`

  - ### startPrefixMapping

    public void startPrefixMapping(String tag, String uri) throws SAXException
    Specified by:
      `startPrefixMapping` in interface `ContentHandler`
    Overrides:
      `startPrefixMapping` in class `DefaultHandler`
    Throws:
      `SAXException`

  - ### startElement

    public void startElement(String namespaceURI, String localName, String qName, Attributes atts) throws SAXException
    Specified by:
      `startElement` in interface `ContentHandler`
    Overrides:
      `startElement` in class `DefaultHandler`
    Throws:
      `SAXException`

  - ### ignorableWhitespace

    public void ignorableWhitespace(char[] buffer, int start, int len) throws SAXException
    Specified by:
      `ignorableWhitespace` in interface `ContentHandler`
    Overrides:
      `ignorableWhitespace` in class `DefaultHandler`
    Throws:
      `SAXException`

  - ### characters

    public void characters(char[] ch, int start, int length) throws SAXException
    Specified by:
      `characters` in interface `ContentHandler`
    Overrides:
      `characters` in class `DefaultHandler`
    Throws:
      `SAXException`

  - ### endElement

    public void endElement(String namespaceURI, String localName, String qName) throws SAXException
    Specified by:
      `endElement` in interface `ContentHandler`
    Overrides:
      `endElement` in class `DefaultHandler`
    Throws:
      `SAXException`

  - ### endDocument

    public void endDocument() throws SAXException
    Specified by:
      `endDocument` in interface `ContentHandler`
    Overrides:
      `endDocument` in class `DefaultHandler`
    Throws:
      `SAXException`