Functions and Directives

Function XmlSimpleParser() Foundation

The function XmlSimpleParser() parses an XML document or XML fragment.

Syntax
XmlSimpleParser( cXml [, coNode] ) -> oXmlNode
Parameters
<cXml>
The XML document or XML fragment to be processed.
<coNode>
The class object used as the factory for XML nodes. Defaults to class XmlNode.
Return

An instance of the XmlNode() or a derived class, which represents the document node of the XML document.

Description

The XmlSimpleParser() function provides a very simple and easy way for processing XML data using objects and their members. This way, the information in the XML document can be easily manipulated using methods and member variables, for example, for iterating over XML nodes or attributes.

Compared to a XML callback processor, using the XmlSimpleParser() is easier and requires fewer lines of code for accessing nodes or attributes. However, using a callback processer is more efficient if large amounts of data (> 1MB) need to be processed.

The following XML document is used as a reference in the paragraphs below. This XML document lists crew members of the Starship Enterprise using different XML notations. Captain James T. Kirk is expressed as child nodes, meaning each value of the first crew entity is written as a child node, while Chief Communications Officer Uhura is expressed using a mixture of attributes. Mr. Chekov is used as an example for node and attribute names containing punctuation marks and similar characters.

TEXT INTO cXml WRAP 
<?xml version="1.0" encoding="UTF-8"?> 
<list> 
  <crew> 
    <firstname>James</firstname> 
    <lastname>Kirk</lastname> 
    <rank>Captain</rank> 
  </crew> 

  <crew 
     firstname="Nyota" 
     lastname="Uhura" 
     rank="Chief Communications Officer" /> 

  <crew first-name="Pavel" last-name="Chekov"> 
     <ra.nk>Navigator</ra.nk> 
  </crew> 
 </list> 
ENDTEXT 

The simplicity of the XmlSimpleParser() becomes very clear in the code for retrieving the firstname of the first two crew members. Furthermore, we can see in the example that even so the two XML entities are different in the way their data is structured (node-based versus attribute-based), it makes no difference when accessing the data.

oXml := XmlSimpleParser( cXml ) 
? oXml:list:crew[1]:firstname // James 
? oXml:list:crew[2]:firstname // Nyota 

Since it is legal to use hyphens ("-"), punctuation marks (".") and other special characters in node names of an XML document, the data associated with the third crew member cannot be expressed via member variables. However, the XmlNode class provides methods for accessing the information. The method :getAttribute() can be used to access any attribute of a node object by name. The :getChild() method allows retrieving specific child nodes as shown below.

oXml := XmlSimpleParser( cXml ) 
? oXml:list:crew[3]:getAttribute("first-name")     // Pavel 
? oXml:list:crew[3]:getChild("ra.nk"):getContent() // Navigator 

The function raises a runtime error if the XML input data does not conform to the XML syntax. In this case, the oError:subSystem will be "XML" and the error description will include a detailed error description as well as the line number in the input data at which the error occured.

The XmlSimpleParser() supports only XML version 1.0 only.

Processing and manipulating a XML document

The following example demonstrates how values can be changed in an existing XML document. Also shown is how new nodes can be created, initialized with data and added to the XML document.

PROCEDURE Main 
  LOCAL cXml, oXml, oCrew 
  TEXT INTO cXml WRAP 
   <?xml version="1.0" encoding="UTF-8"?> 
   <list> 
     <crew> 
       <firstname>James</firstname> 
       <lastname>Kirk</lastname> 
       <rank>Captain</rank> 
     </crew> 

     <crew 
        firstname="Nyota" 
        lastname="Uhura" 
        rank="Chief Communications Officer" /> 

     <crew first-name="Pavel" last-name="Chekov"> 
        <ra.nk>Navigator</ra.nk> 
     </crew> 
    </list> 
  ENDTEXT 

  oXml := XmlSimpleParser( cXml ) 

  // Retrieve a certain child node and change its value 
  oXml:list:crew[1]:firstname := "James T." 

  // Create a new node from scratch, add attributes 
  // and child elements 
  oCrew := XmlNode():createElement("crew") 
  oCrew:addAttribute("firstname","Leonard") 
  oCrew:addAttribute("lastname","McCoy") 
  oCrew:addElement("rank","Chief Medical Officer") 

  // Insert the node into the document by 
  // adding it to the list of crew members 
  oXml:list:addChild( oCrew ) 
  ? oXml:toXml() 
  WAIT 
RETURN 

Result of XML document processing and manipulation

The following XML section shows the XML document after it was manipulated by the example above.

<?xml version="1.0" encoding="iso-8859-1" standalone="yes"?> 
<list> 
<crew> 
  <firstname>James T.</firstname> 
  <lastname>Kirk</lastname> 
  <rank>Captain</rank> 
</crew> 
<crew firstname="Nyota" lastname="Uhura" rank="Chief Communications Officer"/> 
<crew first-name="Pavel" last-name="Chekov"> 
  <ra.nk>Navigator</ra.nk> 
</crew> 
<crew firstname="Leonard" lastname="McCoy"> 
  <rank>Chief Medical Officer</rank> 
</crew> 
</list> 

Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.