Introduction to Expat4D

XML (eXtensible Markup Language) is a data format for structured document interchange on the Web. It is a standard defined by The World Wide Web consortium (W3C). Information about XML and related technologies can be found at http://www.w3.org/XML/.

This 4D Plug-in implements support for James Clark's expat in 4D. This toolkit lets you parse, but not validate, XML documents, although you can build your own validating processor in 4D using Expat4D.

Expat is a stream-oriented parser. You register callback (or handler) functions with the parser and then start feeding it the document. As the parser recognizes parts of the document, it will call the appropriate handler for that part (if you've registered one.) The document is fed to the parser in pieces, so you can start parsing before you have all the document. This also allows you to parse really huge documents that won't fit into memory.

Expat has quite a few handlers and settings, but you only need to learn five functions in order to do 90% of what you'll want to do with it:

• xml_ParserCreate
  Create a new parser object.
   
• xml_SetElementHandler
  Set handlers for start and end tags.
   
• xml_SetCDATAHandler
  Set handler for text.
   
• xml_Parse
  Pass a buffer full of document to the parser.
   
• xml_ParserFree
  Frees the parser memory when you're done with it.
   

There is a great deal of documentation already available for Expat including an article on XML.COM. There is a detailed demonstration database which covers all of the handlers and configuration options and gives a few examples of XML parsers in use. The Command Reference contains fairly complete information on all of the commands in Expat4D and how to implement the handlers in your applications.

An Example

XML Element Structure Example

This first example displays puts the structure of the start elements into a text variable with indentation. We need two handler handler methods, one for the start tags and another for the end tags, plus the routine which runs the parser. These are "startTag", "endTag" and "parseDocument". You could run this routine from a form containing a text variable called "resultText" to see the result. A similar example is also in the demo database, but there's also the option to create a hierarchical list based on the elmeents in there too.

There are some sample XML files included with the demo database which you can use with this parser.

`Method: parseDocument (filePath) C_TEXT($1;$filePath) $filePath:=$1 C_BLOB($xmlBlob) DOCUMENT TO BLOB($filePath;$xmlBlob) C_LONGINT(xml_ParserDepth) C_TEXT(resultText) xml_ParserDepth:=0 resultText:="" C_LONGINT($parser) $parser:=xml_ParserCreate("") xml_SetElementHandler($parser;"handler_startElement";"handler_endElement") xml_SetCDATAHandler($parser;"handler_CDATA") C_LONGINT($errorCode) $errorCode:=xml_ParseBLOB($parser;$xmlBlob) If($error#0)   C_LONGINT($errorLine;$errorColumn;$errorByteIndex)   $errorLine:=xml_GetCurrentLineNumber($parser)   $errorColumn:=xml_GetCurrentColumnNumber($parser)   $errorByteIndex:=xml_GetCurrentByteIndex($parser)   resultText:=resultText+Char(13)   resultText:=resultText+"PARSER ERROR NO: "+String($error)+Char(13)   resultText:=resultText+"Line: "+String($errorLine)+Char(13)   resultText:=resultText+"Column: "+String($errorColumn)+Char(13)   resultText:=resultText+"ByteIndex: "+String($errorByteIndex)+Char(13) End if xml_ParserFree($parser)

	`Method: startTag (parser; elementName; numberOfAttributes) C_LONGINT($1;$parser) C_TEXT($2;$elementName) C_LONGINT($3;$numberOfAttributes) $parser:=$1 $elementName:=$2 $numberOfAttributes:=$3 C_LONGINT(xml_ParserDepth) C_TEXT(resultText) xml_ParserDepth:=xml_ParserDepth+1 resultText:=resultText+(" "*(xml_ParserDepth*4)) resultText:=resultText+$elementName resultText:=resultText+Char(13)

	`Method: handler_endElement (parser; elementName) C_LONGINT($1;$parser) C_TEXT($2;$elementName) $parser:=$1 $elementName:=$2 C_LONGINT(xml_ParserDepth) xml_ParserDepth:=xml_ParserDepth-1

The first method initiates the expat parser. The second two methods are the handler routines called by expat when start and end tags are found in the XML document. The following is a sample XML document which you can try with the parseDocument function.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<document>
	<person>
		<name>Mark Mitchenall</name>
		<email>mark@mitchenall.com</name>
	</peron>
</document>

After the parser has completed, resultText should contain the following text:

document
    person
        name
        email