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.
Properties
Name |
Type |
Read-Only |
Shared |
---|---|---|---|
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
|||
✓ |
Methods
Name |
Parameters |
Returns |
Shared |
---|---|---|---|
XMLEncoding As String |
|||
file As FolderItem, [isFinal As Boolean] |
|||
[XMLEncoding As String] |
Events
Name |
Parameters |
Returns |
---|---|---|
elName As String, attName As String, att_Type As String, dflt As String, isRequired As Boolean |
||
s As String |
||
data As String |
||
s As String |
||
name As String, content As XMLContentModel |
||
name As String |
||
prefix As String |
||
entityName As String, is_parameter_entity As Boolean, value As String, base As String, systemID As String, publicID As String, notationName As String |
||
context As String, base As String, systemID As String, publicID As String |
||
notationName As String, base As String, systemID As String, publicID As String |
||
doctypeName As String, systemID As String, publicID As String, has_Internal_Subset As Boolean |
||
name As String, attributeList As XMLAttributeList |
||
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 situtuations:
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
All project types on all supported operating systems.
See also
Object parent class; XMLReaderException class.