Package ghidra.xml

Interface XmlPullParser

  • All Known Implementing Classes:
    AbstractXmlPullParser, NonThreadedXmlPullParserImpl
    public interface XmlPullParser
    An interface describing the API for the XML pull parsing system. This is similar to XmlParser, except that it has slightly different methods and IS case sensitive, conforming to the XML spec.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      int discardSubTree()
      Discards the current subtree.
      int discardSubTree​(XmlElement element)
      Discards a subtree.
      int discardSubTree​(java.lang.String name)
      Discards the current subtree.
      void dispose()
      Disposes all resources of the parser.
      XmlElement end()
      Returns the next element, which must be an end element.
      XmlElement end​(XmlElement element)
      Returns the next element, which must be an end element, and must match the supplied XmlElement's name (presumably the start element of the subtree).
      int getColumnNumber()
      Returns the current column number where the parser is (note that this may actually be ahead of where you think it is because of look-ahead and caching).
      int getCurrentLevel()
      The current element level, as if the XML document was a tree.
      int getLineNumber()
      Returns the current line number where the parser is (note that this may actually be ahead of where you think it is because of look-ahead and caching).
      java.lang.String getName()
      Returns the name of this parser.
      java.lang.String getProcessingInstruction​(java.lang.String name, java.lang.String attribute)
      Returns the value of the attribute of the processing instruction.
      boolean hasNext()
      Returns whether there is a next element.
      boolean isPullingContent()
      Returns whether the parser will return content elements as well as start and end elements (they're always accumulated and provided in the appropriate end element).
      XmlElement next()
      Returns the next element, removing it from the queue (assuming there is such a next element).
      XmlElement peek()
      Returns the next element, without removing it from the queue (assuming there is such a next element).
      void setPullingContent​(boolean pullingContent)
      Set whether the parser will return content elements.
      XmlElement softStart​(java.lang.String... names)
      Returns the next element, which must be a start element, and must be one of the supplied names (if provided).
      XmlElement start​(java.lang.String... names)
      Returns the next element, which must be a start element, and must be one of the supplied names (if provided).

    • Method Detail

      • getName

        java.lang.String getName()
        Returns the name of this parser.
        Returns:
        the name of this parser

      • getProcessingInstruction

        java.lang.String getProcessingInstruction​(java.lang.String name,
                                          java.lang.String attribute)
        Returns the value of the attribute of the processing instruction. For example, <?program_dtd version="1"?>
        Parameters:
        name - the name of the processing instruction
        attribute - the name of the attribute
        Returns:
        the value of the attribute of the processing instruction

      • getLineNumber

        int getLineNumber()
        Returns the current line number where the parser is (note that this may actually be ahead of where you think it is because of look-ahead and caching).
        Returns:
        the current line number

      • getColumnNumber

        int getColumnNumber()
        Returns the current column number where the parser is (note that this may actually be ahead of where you think it is because of look-ahead and caching).
        Returns:
        the current column number

      • isPullingContent

        boolean isPullingContent()
        Returns whether the parser will return content elements as well as start and end elements (they're always accumulated and provided in the appropriate end element).
        Returns:
        whether the parser will return content elements

      • setPullingContent

        void setPullingContent​(boolean pullingContent)
        Set whether the parser will return content elements. Note that this method may throw an exception if the parser cannot comply with the setting (usually when setting to true).
        Parameters:
        pullingContent - whether the parser will return content elements

      • getCurrentLevel

        int getCurrentLevel()
        The current element level, as if the XML document was a tree. The root element is at level 0. Each child is at a level one higher than its parent. Note that this is the same as peek().getLevel().
        Returns:
        the current element level

      • hasNext

        boolean hasNext()
        Returns whether there is a next element.
        Returns:
        whether there is a next element

      • peek

        XmlElement peek()
        Returns the next element, without removing it from the queue (assuming there is such a next element). This is very useful for examining the next item to decide who should handle the subtree, and then delegating to a subordinate with the parser state intact.
        Returns:
        the next element, without removing it

      • next

        XmlElement next()
        Returns the next element, removing it from the queue (assuming there is such a next element). This method should be used RARELY. Typically, when you're reading XML, you almost always at least know that you're either starting or ending a subtree, so start() or end() should be used instead. The only time you really might need to use this is if you don't really know where you are and you need to pop elements off until you synchronize back into a sane state.
        Returns:
        the next element, removing it

      • start

        XmlElement start​(java.lang.String... names)
        Returns the next element, which must be a start element, and must be one of the supplied names (if provided). This method is very useful for starting a subtree, and throws an XmlException if the next element does not conform to your specification.
        Parameters:
        names - optional vararg Strings which start element name must be one of
        Returns:
        the next element (which is a start element)

      • end

        XmlElement end()
        Returns the next element, which must be an end element. The name doesn't matter. This method throws an XmlException if the next element is not an end element. Use this method when you really know you're matching the right end and want to avoid extra constraint checks.
        Returns:
        the next element (which is an end element)

      • end

        XmlElement end​(XmlElement element)
        Returns the next element, which must be an end element, and must match the supplied XmlElement's name (presumably the start element of the subtree). This method throws an XmlException if the next element is not an end element, or if the name doesn't match.
        Parameters:
        element - the presumed start element to match names
        Returns:
        the next element (which is an end element)

      • softStart

        XmlElement softStart​(java.lang.String... names)
        Returns the next element, which must be a start element, and must be one of the supplied names (if provided). This method is very useful for starting a subtree, but differs from start(...) in that failures are soft. This means that if the next element isn't a start element, or doesn't match one of the optional provided names, null is returned (instead of raising an XmlException).
        Parameters:
        names - optional vararg Strings which start element name must be one of
        Returns:
        the next element (which is a start element) or null

      • discardSubTree

        int discardSubTree()
        Discards the current subtree. If the current element (peek()) is a content or end element, then just that element is discarded. If it's a start element, then the entire subtree starting with the start element is discarded (i.e. next() is called until the current element is now the element after the subtree's end element).
        Returns:
        the number of elements discarded

      • discardSubTree

        int discardSubTree​(java.lang.String name)
        Discards the current subtree. The current element must be a start element, and must be named name, otherwise an XmlException is thrown.
        Parameters:
        name - what the current start element must be named
        Returns:
        the number of elements discarded

      • discardSubTree

        int discardSubTree​(XmlElement element)
        Discards a subtree. The element provided is used as the "start" of the subtree (although it doesn't actually have to be a start element; only its name and level are used). The queue of elements is discarded such that the last element discarded is an end element, has the same name as the provided element, and is the same level as the provided element. If the provided element's level is higher than the current level, then nothing is discarded.
        Parameters:
        element - the element provided as the "start" element
        Returns:
        the number of elements discarded

      • dispose

        void dispose()
        Disposes all resources of the parser. It's important that this is called when a client is finished with the parser, because this allows files to be closed, threads to be stopped, etc.