KtXml/org.kobjects.ktxml.api/XmlPullParser

XmlPullParser

KtXmplParser is an interface that defines parsing functionality based on the XMLPULL V2 API, adapted to Kotlin.

There are two key methods: next and nextToken. While next() provides access to high level parsing events, nextToken() allows access to lower level tokens.

The current event state of the parser can be determined by reading the eventType property. Initially, the parser is in the START_DOCUMENT state.

The method next() advances the parser to the next event. The enum value returned from next() determines the current parser state and is identical to the value returned from following calls to eventType.

Th following event types are seen by next():

EventType.START_TAG: An XML start tag was read.
EventType.TEXT: Text content was read. The text content can be retrieved using the text property (when in validating mode, next will not report ignorable whitespaces, use nextToken instead).
EventType.END_TAG: An end tag was read.
EventType.END_DOCUMENT: No more events are available

Author

Stefan Haustein

Aleksander Slominski

Inheritors

MiniXmlPullParser

Properties

attributeCount

abstract val attributeCount: Int

The number of attributes of the current start tag, or -1 if the current event type is not START_TAG

columnNumber

abstract val columnNumber: Int

Returns the current column number, starting from 0. When the parser does not know the current column number or can not determine it, -1 is returned (e.g. for WBXML).

depth

abstract val depth: Int

Returns the current depth of the element. Outside the root element, the depth is 0. The depth is incremented by 1 when a start tag is reached. The depth is decremented AFTER the end tag event was observed.

eventType

abstract val eventType: EventType

Returns the type of the current event (START_TAG, END_TAG, TEXT, etc.)

isEmptyElementTag

abstract val isEmptyElementTag: Boolean

True if the current event is START_TAG and the tag is degenerated (e.g. ); false otherwise.

isWhitespace

abstract val isWhitespace: Boolean

Checks whether the current TEXT event contains only whitespace characters.

lastError

abstract val lastError: String

lineNumber

abstract val lineNumber: Int

Returns the current line number, starting from 1.

name

abstract val name: String

For START_TAG or END_TAG events, the (local) name of the current element is returned when namespaces are enabled. When namespace processing is disabled, the raw name is returned. For ENTITY_REF events, the entity name is returned. If the current event is not START_TAG, END_TAG, or ENTITY_REF, an empty string is returned.

namespace

abstract val namespace: String

Returns the namespace URI of the current element. The default namespace is represented as empty string. If namespaces are not enabled, an empty string ("") is always returned. The current event must be START_TAG or END_TAG; otherwise, an empty string is returned.

positionDescription

abstract val positionDescription: String

Returns a short text describing the current parser state, including the position, a description of the current event and the data source if known. This method is especially useful to provide meaningful error messages and for debugging purposes.

prefix

abstract val prefix: String

Returns the prefix of the current element.

text

abstract val text: String

Returns the text content of the current event as String.

Functions

getAttributeName

abstract fun getAttributeName(index: Int): String

Returns the local name of the specified attribute if namespaces are enabled or just attribute name if namespaces are disabled.

getAttributeNamespace

abstract fun getAttributeNamespace(index: Int): String?

Returns the namespace URI of the attribute with the given index (starts from 0).

getAttributePrefix

abstract fun getAttributePrefix(index: Int): String

Returns the prefix of the specified attribute.

getAttributeType

abstract fun getAttributeType(index: Int): String

Returns the type of the specified attribute.

getAttributeValue

abstract fun getAttributeValue(index: Int): String

Returns the given attributes value.

abstract fun getAttributeValue(namespace: String, name: String): String?

Returns the attributes value identified by namespace URI and namespace localName. If namespaces are disabled namespace must be null. If current event type is not START_TAG then IndexOutOfBoundsException will be thrown.

getNamespace

open fun getNamespace(prefix: String): String?

Returns the URI corresponding to the given prefix, depending on current state of the parser.

getNamespaceCount

abstract fun getNamespaceCount(depth: Int): Int

Returns the numbers of elements in the namespace stack for the give depth.

getNamespacePrefix

abstract fun getNamespacePrefix(pos: Int): String

Returns the namespace prefix for the given position in the namespace stack.

getNamespaceUri

abstract fun getNamespaceUri(pos: Int): String

Returns the namespace URI for the given position in the namespace stack.

isAttributeDefault

abstract fun isAttributeDefault(index: Int): Boolean

Returns if the specified attribute was not in input was declared in XML. If parser is non-validating it MUST always return false. This information is part of XML infoset:

abstract fun next(): EventType

Get next parsing event - element content wil be coalesced and only one TEXT event must be returned for whole element content (comments and processing instructions will be ignored and emtity references must be expanded or exception mus be thrown if entity reerence can not be exapnded). If element content is empty (content is "") then no TEXT event will be reported.

nextTag

open fun nextTag(): EventType

Call next() and return event if it is START_TAG or END_TAG otherwise throw an exception.

nextText

open fun nextText(): String

If current event is START_TAG then if next element is TEXT then element content is returned or if next event is END_TAG then empty string is returned, otherwise exception is thrown. After calling this function successfully parser will be positioned on END_TAG.

nextToken

abstract fun nextToken(): EventType

This method works similarly to next() but will expose additional event types (COMMENT, CDSECT, DOCDECL, ENTITY_REF, PROCESSING_INSTRUCTION, or IGNORABLE_WHITESPACE) if they are available in input.

require

open fun require(type: EventType?, namespace: String?, name: String?)

Test if the current event is of the given type and if the namespace and name do match.

skipSubTree

open fun skipSubTree()

Skip sub tree that is currently porser positioned on.