Class

XMLReader

Description

This is a wrapper class for the latest version of Expat (XML Parser Toolkit). Expat is a library for parsing XML documents.

Methods

Name

Parameters

Returns

Shared

Constructor

Constructor

XMLEncoding As String, namespaceSeparator As String

CreateExternalEntityReader

XMLEncoding As String

DefaultCurrent

FreeExternalEntityReader

Parse

file As FolderItem, [isFinal As Boolean]

s As String, [isFinal As Boolean]

Reset

[XMLEncoding As String]

Boolean

Events

Name

Parameters

Returns

AttListDecl

elName As String, attName As String, att_Type As String, dflt As String, isRequired As Boolean

Characters

s As String

Comment

data As String

Default

s As String

ElementDecl

name As String, content As XMLContentModel

EndCDATA

EndDoctypeDecl

EndDocument

EndElement

name As String

EndPrefixMapping

prefix As String

EntityDecl

entityName As String, is_parameter_entity As Boolean, value As String, base As String, systemID As String, publicID As String, notationName As String

ExternalEntityRef

context As String, base As String, systemID As String, publicID As String

NotationDecl

notationName As String, base As String, systemID As String, publicID As String

NotStandalone

ProcessingInstruction

target As String, data As String

SkippedEntity

entityName As String, is_parameter_entity As Boolean

StartCDATA

StartDoctypeDecl

doctypeName As String, systemID As String, publicID As String, has_Internal_Subset As Boolean

StartDocument

StartElement

name As String, attributeList As XMLAttributeList

StartPrefixMapping

prefix As String, URI As String

XMLDecl

version As String, XMLEncoding As String, standalone As Boolean

Constants

The following class constants can be used to test the value in ErrorCode.

Value

Constant

0

XML_ERROR_NONE

1

XML_ERROR_NO_MEMORY

2

XML_ERROR_SYNTAX

3

XML_ERROR_NO_ELEMENTS

4

XML_ERROR_INVALID_TOKEN

5

XML_ERROR_UNCLOSED_TOKEN

6

XML_ERROR_PARTIAL_CHAR

7

XML_ERROR_TAG_MISMATCH

8

XML_ERROR_DUPLICATE_ATTRIBUTE

9

XML_ERROR_JUNK_AFTER_DOC_ELEMENT

10

XML_ERROR_PARAM_ENTITY_REF

11

XML_ERROR_UNDEFINED_ENTITY

12

XML_ERROR_RECURSIVE_ENTITY_REF

13

XML_ERROR_ASYNC_ENTITY

14

XML_ERROR_BAD_CHAR_REF

15

XML_ERROR_BINARY_ENTITY_REF

16

XML_ERROR_ATTRIBUTE_EXTERNAL_ENTITY_REF

17

XML_ERROR_MISPLACED_XML_PI

18

XML_ERROR_UNKNOWN_ENCODING

19

XML_ERROR_INCORRECT_ENCODING

20

XML_ERROR_UNCLOSED_CDATA_SECTION

21

XML_ERROR_EXTERNAL_ENTITY_HANDLING

22

XML_ERROR_NOT_STANDALONE

23

XML_ERROR_UNEXPECTED_STATE

24

XML_ERROR_ENTITY_DECLARED_IN_PE

25

XML_ERROR_FEATURE_REQUIRES_XML_DTD

26

XML_ERROR_CANT_CHANGE_FEATURE_ONCE_PARSING

Property descriptions

XMLReader.Base

Base As String

Sets the base to be used for resolving relative URIs in system identifiers in declarations.

XMLReader.CurrentByteCount

CurrentByteCount As Integer

The number of bytes in the current event.

This property is read-only.

XMLReader.CurrentByteIndex

CurrentByteIndex As Integer

The byte position where the error occurred.

This property is read-only.

XMLReader.CurrentColumnNumber

CurrentColumnNumber As Integer

The column number the parser is currently on.

This property is read-only.

XMLReader.CurrentLineNumber

CurrentLineNumber As Integer

The line number the parser is currently on.

This property is read-only.

XMLReader.ErrorCode

ErrorCode As Integer

The last error code.

This property is read-only.

XMLReader.SetDefaultHandler

SetDefaultHandler As Boolean

Sets Expat to send unknown data to the default event. Entities are not parsed.

This property is read-only.

XMLReader.SetDefaultHandlerExpand

SetDefaultHandlerExpand As Boolean

Sets Expat to send unknown data to the Default event and expands entities.

This property is read-only.

Method descriptions

XMLReader.Constructor

Constructor

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Creates an empty XMLReader instance.

XMLReader.Constructor

Constructor(XMLEncoding as String, namespaceSeparator as String)

Note

Constructors are special methods called when you create an object with the New keyword and pass in the parameters above.

Creates an XMLReader object.

The XMLEncoding parameter sets the encoding for the parser. The default encoding is UTF-8. The namespaceSeparator parameter forces Expat to expand namespace definitions.

XMLReader.CreateExternalEntityReader

CreateExternalEntityReader(XMLEncoding As String)

Create a child parser which can be used to parse an external parsed entity referred to by content parsed by the parent parser.

XMLReader.DefaultCurrent

DefaultCurrent

If this is called from within an event, it will force the current data to route to the Default event.

XMLReader.FreeExternalEntityReader

FreeExternalEntityReader

Removes from memory the child parser created by the CreateExternalEntityReader method.

XMLReader.Parse

Parse(file As FolderItem, [isFinal As Boolean])

Parses the data in the passed document, file.

Parse(s As String, [isFinal As Boolean])

Parses the data in the passed string, s.

The optional parameter isFinal tells Expat what to do if the end of the data is reached and the XML is not well-formed, for example, if it stops in the middle of an element. Setting isFinal to False will tell Expat not to throw an error because more data will be coming in another call.

XMLReader.Reset

Reset([XMLEncoding As String]) As Boolean

Resets the parser.

The optional parameter XMLEncoding specifies the Encoding of the data to be parsed. Returns a Boolean.

Event descriptions

XMLReader.AttListDecl

AttListDecl(elName As String, attName As String, att_Type As String, dflt As String, isRequired As Boolean)

Called at a DTD attlist declaration.

XMLReader.Characters

Characters(s As String)

Called at character data, s.

XMLReader.Comment

Comment(data As String)

Called at the XML comment, data.

XMLReader.Default

Default(s As String)

Called for any characters in the XML document for which there is no applicable handler.

XMLReader.ElementDecl

ElementDecl(name As String, content As XMLContentModel)

Called at a DTD element declaration.

XMLReader.EndCDATA

EndCDATA

Called at the end of CDATA.

XMLReader.EndDoctypeDecl

EndDoctypeDecl

Called at the end of a DocType declaration.

XMLReader.EndDocument

EndDocument

Called at the end of the document.

XMLReader.EndElement

EndElement(name As String)

Called at the end of the element, Name.

XMLReader.EndPrefixMapping

EndPrefixMapping(prefix As String)

Called at the end of a namespace declaration.

XMLReader.EntityDecl

EntityDecl(entityName As String, is_Parameter_Entity As Boolean, value As String, base As String, systemID As String, publicID As String, notationName As String)

Called at an entity declaration.

The is_parameter_entity will be True if the entity is a parameter entity. For internal entities(<!ENTITY foo "bar">), value will be populated and SystemID, PublicID, and NotationName will be empty strings. For external entities, Value will be an empty string and SystemID will be populated. The PublicID argument will be empty unless a public identifier was provided. The NotationName argument will have a populated value only for unparsed entity declarations.

XMLReader.ExternalEntityRef

ExternalEntityRef(context As String, base As String, systemID As String, publicID As String)

Called at an external entity reference. Return False to stop parsing and return True to report that handling of the external entity succeeded.

XMLReader.NotationDecl

NotationDecl(notationName As String, base As String, systemID As String, publicID As String)

Called at a notation.

XMLReader.NotStandalone

NotStandalone

This is called if the document is not standalone, that is, it has an external subset or a reference to a parameter entity, but does not have Standalone=Yes. Return False to cause parsing to stop.

XMLReader.ProcessingInstruction

ProcessingInstruction(target As String, data As String)

Called at the processing instruction, Target and Data.

XMLReader.SkippedEntity

SkippedEntity(entityName As String, is_Parameter_Entity As Boolean)

Called when an entity is reached, but entities are not currently being expanded.

XMLReader.StartCDATA

StartCDATA

Called at the start of CDATA.

XMLReader.StartDoctypeDecl

StartDoctypeDecl(doctypeName As String, systemID As String, publicID As String, has_Internal_Subset As Boolean)

Called at the start of a DocType declaration.

XMLReader.StartDocument

StartDocument

Called at the start of a document.

XMLReader.StartElement

StartElement(name As String, attributeList As XMLAttributeList)

Called at the start of the XML element, Name and AttributeList.

This event handler is called as each XML node is processed. You can then check the name to determine how you want to proceed.

The following XML is contained in a constant called kTestXml:

<?xml version="1.0" encoding="UTF-8"?> <League>

<Team name="Seagulls">

<Player name="Bob" position="1B" /> <Player name="Tom" position="2B" />

</Team> <Team name="Pigeons">

<Player name="Bill" position="1B" /> <Player name="Tim" position="2B" />

</Team> <Team name="Crows">

<Player name="Ben" position="1B" /> <Player name="Ty" position="2B" />

</Team>

</League>

This code in the StarElement event handler will display the XML as it is processed:

Select Case name
Case "Team"
  ' On the Team node, get the name attribute and
  ' display it
  ' OutPut is a ListBox
  Output.AddRow(attributeList.Value("name"))

Case "Player"
  ' Get each player node and display the player name
  ' and position
  ' Output is a ListBox
  Output.AddRow("", attributeList.Value("name"), attributeList.Value("position"))

End Select

XMLReader.StartPrefixMapping

StartPrefixMapping(prefix As String, URI As String)

Called at the beginning of the namespace declaration, Prefix and URI.

XMLReader.XMLDecl

XMLDecl(version As String, XMLEncoding As String, standalone As Boolean)

Called on an XML declaration node.

Notes

You will likely use the StartElement event handler to do most of your processing.

XMLReader can be used to parse an XML document instead of using the XMLDocument class. In most cases you will want to use XMLDocument as it is simpler, but XMLReader can be useful for more advanced situations:

  • Large XML documents that would take too much memory to load with XMLDocument

  • Where you only need to parse out a subset of the XML and do not need to load the entire document

  • Situations where you want to convert the XML to another format on the fly

To use XMLReader, create a subclass and implement the event handlers.

Compatibility

Desktop, console, web and iOS project types on all supported operating systems.

See also

Object parent class; XMLReaderException class.