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

table-centered_columns_3_and_4

| Name | Type | Read-Only | Shared | |--------------------------------------------------------------|------------------------------------|-----------|--------| | `Base` | `String` | | | | `CurrentByteCount` | `Integer` | ✓ | | | `CurrentByteIndex` | `Integer` | ✓ | | | `CurrentColumnNumber` | `Integer` | ✓ | | | `CurrentLineNumber` | `Integer` | ✓ | | | `ErrorCode` | `Integer` | ✓ | | | `SetDefaultHandler` | `Boolean` | | | | `SetDefaultHandlerExpand` | `Boolean` | | | ## Methods

table-centered_column_4

| Name | Parameters | Returns | Shared | |--------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|------------------------------------|--------| | `Constructor` | | | | | `Constructor` | XMLEncoding As `String`, namespaceSeparator As `String` | | | | `CreateExternalEntityReader` | XMLEncoding As `String` | | | | `DefaultCurrent` | | | | | `FreeExternalEntityReader` | | | | | `Parse` | file As `FolderItem` | | | | | file As `FolderItem`, isFinal As `Boolean` | | | | | s As `String` | | | | | s As `String`, isFinal As `Boolean` | | | | `Reset` | | `Boolean` | | | | xmlEncoding As `String` | `Boolean` | | ## Events

table-centered_column_4

| 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

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

forsearch

XMLReader.Base **Base** As `String` > Sets the base to be used for resolving relative URIs in system identifiers in declarations.

forsearch

XMLReader.CurrentByteCount **CurrentByteCount** As `Integer` > The number of bytes in the current event. > > This property is read-only.

forsearch

XMLReader.CurrentByteIndex **CurrentByteIndex** As `Integer` > The byte position where the error occurred. > > This property is read-only.

forsearch

XMLReader.CurrentColumnNumber **CurrentColumnNumber** As `Integer` > The column number the parser is currently on. > > This property is read-only.

forsearch

XMLReader.CurrentLineNumber **CurrentLineNumber** As `Integer` > The line number the parser is currently on. > > This property is read-only.

forsearch

XMLReader.ErrorCode **ErrorCode** As `Integer` > The last error code. > > This property is read-only.

forsearch

XMLReader.SetDefaultHandler **SetDefaultHandler** As `Boolean` > Sets Expat to send unknown data to the default event. Entities are not parsed.

forsearch

XMLReader.SetDefaultHandlerExpand **SetDefaultHandlerExpand** As `Boolean` > Sets Expat to send unknown data to the Default event and expands entities. ## Method descriptions

forsearch

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.

forsearch

XMLReader.Constructor **Constructor**(XMLEncoding as `String`, namespaceSeparator as `String`) > 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.

forsearch

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.

forsearch

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

forsearch

XMLReader.FreeExternalEntityReader **FreeExternalEntityReader** > Removes from memory the child parser created by the `CreateExternalEntityReader` method.

forsearch

XMLReader.Parse **Parse**(file As `FolderItem`) > Parses the data in the passed document, *file*. **Parse**(file As `FolderItem`, isFinal As `Boolean`) > Parses the data in the passed document, *file*. > > The 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. **Parse**(s As `String`) > Parses the data in the passed string, *s*. **Parse**(s As `String`, isFinal As `Boolean`) > Parses the data in the passed string, *s*. > > The 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.

forsearch

XMLReader.Reset **Reset** As `Boolean` > Resets the parser. **Reset**(xmlEncoding As `String`) As `Boolean` > Resets the parser. > > The parameter *xmlEncoding* specifies the Encoding of the data to be parsed. Returns a `Boolean`. ## Event descriptions

forsearch

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.

forsearch

XMLReader.Characters **Characters**(s As `String`) > Called at character data, *s*.

forsearch

XMLReader.Comment **Comment**(data As `String`) > Called at the XML comment, *data*.

forsearch

XMLReader.Default **Default**(s As `String`) > Called for any characters in the XML document for which there is no applicable handler.

forsearch

XMLReader.ElementDecl **ElementDecl**(name As `String`, content As `XMLContentModel`) > Called at a DTD element declaration.

forsearch

XMLReader.EndCDATA **EndCDATA** > Called at the end of CDATA.

forsearch

XMLReader.EndDoctypeDecl **EndDoctypeDecl** > Called at the end of a DocType declaration.

forsearch

XMLReader.EndDocument **EndDocument** > Called at the end of the document.

forsearch

XMLReader.EndElement **EndElement**(name As `String`) > Called at the end of the element, *Name*.

forsearch

XMLReader.EndPrefixMapping **EndPrefixMapping**(prefix As `String`) > Called at the end of a namespace declaration.

forsearch

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(\), 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.

forsearch

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.

forsearch

XMLReader.NotationDecl **NotationDecl**(notationName As `String`, base As `String`, systemID As `String`, publicID As `String`) > Called at a notation.

forsearch

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.

forsearch

XMLReader.ProcessingInstruction **ProcessingInstruction**(target As `String`, data As `String`) > Called at the processing instruction, *Target* and *Data*.

forsearch

XMLReader.SkippedEntity **SkippedEntity**(entityName As `String`, is_Parameter_Entity As `Boolean`) > Called when an entity is reached, but entities are not currently being expanded.

forsearch

XMLReader.StartCDATA **StartCDATA** > Called at the start of CDATA.

forsearch

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.

forsearch

XMLReader.StartDocument **StartDocument** > Called at the start of a document.

forsearch

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 > > > > > > > > > > > > > > > > ``` > > This code in the StarElement event handler will display the XML as it is processed: > > ``` xojo > 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 > ```

forsearch

XMLReader.StartPrefixMapping **StartPrefixMapping**(prefix As `String`, URI As `String`) > Called at the beginning of the namespace declaration, *Prefix* and *URI*.

forsearch

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 | | | |-----------------------|-----| | **Project Types** | All | | **Operating Systems** | All |

`Object` parent class; `XMLReaderException` class.