This section is a reference guide to the standards for creating and using Document Event Handlers with the xml compiler function. Document Event Handlers allow the user to avoid creating a document tree model in memory; but instead, to have the compiler pass each parse event to a document event handler Lambda. This allows complete user tailoring of the XML compilation process. All of the basic methods required of document event handlers are contained in this section.
This is the main interface that most SAX applications implement: if the application needs to be informed of basic parsing events, it implements this interface and passes an instance to the xml. The xml compiler uses the instance to report basic document-related events like the start and end of elements and character data.
The order of events in this interface is very important, and mirrors the order of information in the document itself. For example, all of an element's content (character data, processing instructions, and/or subelements) will appear, in order, between the startElement event and the corresponding endElement event. For example the following XML input string:
<?xml version="1.0"?>
<poem>
<line>Roses are red,</line>
<line>Violets are blue.</line>
<line>Sugar is sweet,</line>
<line>and I love you.</line>
</poem>
Initiates the following XML document event chain:
(eventHandler.startDocument)
(eventHandler.startElement "xml" #{version: "1.0"})
(eventHandler.startElement "poem" #void)
(eventHandler.startElement "line" #void)
(eventHandler.characters "Roses are red,")
(eventHandler.endElement "line")
(eventHandler.startElement "line" #void)
(eventHandler.characters "Violets are blue.")
(eventHandler.endElement "line")
(eventHandler.startElement "line" #void)
(eventHandler.characters "Sugar is sweet,")
(eventHandler.endElement "line")
(eventHandler.startElement "line" #void)
(eventHandler.characters "and I love you.")
(eventHandler.endElement "line")
(eventHandler.endElement "poem")
(eventHandler.endElement "xml")
(eventHandler.endDocument)
The document event handler receives notification of a stream of content character data. This method is invoked whenever character data is encountered in an element content section.
Syntax: (eventHandler.characters aString)
| aString | A string containing the content character data. |
| Returns | True if there were no errors; otherwise, an error. |
XML Input: <Name>John</Name>
Event Chain:
(eventHandler.startElement "Name" #void)
(eventHandler.characters "John")
(eventHandler.endElement "Name")
Note: The character event notifies the document event handler some content character data has been encountered.
The document event handler receives notification of a stream of comment character data. This method is invoked whenever comment data is encountered in an element content section.
Syntax: (eventHandler.comments aString)
| aString | A string containing the comment character data. |
| Returns | True if there were no errors; otherwise, an error. |
XML Input: <Name><!--This is a comment-->John</Name>
Event Chain:
(eventHandler.startElement "Name" #void)
(eventHandler.characters "John")
(eventHandler.comments "This is a comment")
(eventHandler.endElement "Name")
Note:The character event notifies the document event handler some content character data has been encountered.
The document event handler receives notification of a stream of document type definition character data. This method is invoked whenever a document type definition is encountered.
Syntax: (eventHandler.doctypeDefinition name aString)
| name | The tag name of the document type definition: DOCTYPE, ELEMENT, ENTITY, ATTLIST, or NOTATION. |
| aString | A string containing the content character data of the document type definition. |
| Returns | True if there were no errors; otherwise, an error. |
XML Input: <!DOCTYPE MyDoc SYSTEM "MYDOC.DTD">
Event Chain:
(eventHandler.doctypeDefinition "DOCTYPE" { MyDoc SYSTEM "MYDOC.DTD"})
Note: The doctype definition event notifies the document event handler when a document type has been encountered.
XML Input:
<!DOCTYPE list [
<!ELEMENT list (item+)>
<!ELEMENT item (#PCDATA)>
<!ATTLIST item topic CDATA #IMPLIED>
] >
Event Chain:
(eventHandler.doctypeDefinition "DOCTYPE" "list")
(eventHandler.doctypeDefinition "ELEMENT" "list (item+)")
(eventHandler.doctypeDefinition "ELEMENT" "item (#PCDATA)")
(eventHandler.doctypeDefinition "ATTLIST" "item topic CDATA #IMPLIED")
Note: The doctype definition event notifies the document event handler when a document type has been encountered.
The document event handler receives notification of a parse error. This method is invoked whenever the xml compiler encounters a parse error.
Syntax: (eventHandler.errorMessage aString)
| aString | A string containing the error message. |
| Returns | True if there were no errors; otherwise, an error. |
XML Input:
<Name>John</Mike>
Event Chain:
(eventHandler.startElement "Name" #void)
(eventHandler.characters "John")
(eventHandler.errorMessage "Element end had tag of Mike, expected Name")
(eventHandler.endElement "Mike")
Note: The errorMessage event notifies the document event handler when a parse error has been encountered.
The document event handler receives notification of the end of a document. This method is invoked after all other method of the document event handler.
Syntax: (eventHandler.endDocument)
| Returns | True if there were no errors; otherwise, an error. |
XML Input: <?xml?>
Event Chain:
(eventHandler.startDocument)
...
(eventHandler.endDocument)
Note: The endDocument event notifies the document event handler that the current document parse is ending.
The document event handler receives notification of the end of an element. This method is invoked at the end of every element, even if the element is empty.
Syntax: (eventHandler.endElement name)
| name | The Tag name of the element. |
| Returns | True if there were no errors; otherwise, an error. |
XML Input: <Name/>
Event Chain:
(eventHandler.startElement "Name" #void)
...
(eventHandler.endElement "Name")
Note: The endElement event notifies the document event handler that the current element parse is ending.
The document event handler receives notification of a stream of content whitespace data. This method is invoked whenever whitespace data is encountered in an element content section.
Syntax: (eventHandler.ignoreableWhitespace aString)
| aString | A string containing the content whitespace data. |
| Returns | True if there were no errors; otherwise, an error. |
XML Input:
<Name><First>John</First>
<Last>Doe</Last></Name>
Event Chain:
(eventHandler.startElement "Name" #void)
(eventHandler.startElement "First" #void)
(eventHandler.characters "John")
(eventHandler.endElement "First")
(eventHandler.ignorableWhitespace " ")
(eventHandler.startElement "Last" #void)
(eventHandler.characters "Doe")
(eventHandler.endElement "Last")
(eventHandler.endElement "Name")
Note: The ignorable whitespace event notifies the document event handler that some content white space data has been encountered.
The document event handler receives notification of a stream of processing instruction character data. This method is invoked whenever a process instruction is encountered.
Syntax: (eventHandler.processingInstruction name aString)
| name | The target name of the processing instruction. |
| aString | A string containing the content character data for processing. |
| Returns | True if there were no errors; otherwise, an error. |
XML Input: <"javaScript writeln("Hello world");">
Event Chain:
(eventHandler.processingInstruction "javaScript"
"writeln(:"Hello world");")
Note: The processing instruction event notifies the document event handler when a processing instruction has been encountered.
The document event handler receives notification of the start of a document. This method is invoked before any other method of the document event handler.
Syntax: (eventHandler.startDocument)
| Returns | True if there were no errors; otherwise, an error. |
XML Input: <?xml?>
Event Chain:
(eventHandler.startDocument)
...
(eventHandler.endDocument)
Note: The startDocument event notifies the document event handler that a new document is being parsed.
The document event handler receives notification of the start of an element. This method is invoked at the start of every element, even if the element is empty.
Syntax: (eventHandler.startElement name attlist)
| name | The tag name of the element. |
| attlist | The attribute list Structure, or #void if there are no attributes. |
| Returns | True if there were no errors; otherwise, an error. |
XML Input:
<Name/>
Event Chain:
(eventHandler.startElement "Name" #void)
(eventHandler.endElement "Name")
Note: The endElement event notifies the document event handler that the current element parse is ending.
XML Input: <Name>John</Name>
Event Chain:
(eventHandler.startElement "Name" #void)
(eventHandler.characters "John")
(eventHandler.endElement "Name")
Note: The startElement event notifies the document event handler that a new element parse is starting.
XML Input: <Name firstonly="yes">John</Name>
Event Chain:
(eventHandler.startElement "Name" #{firstonly: "yes"})
(eventHandler.characters "John")
(eventHandler.endElement "Name")
Note: The startElement event notifies the document event handler that a new element parse is starting.