Function Var2Xml() Foundation

Converts any value to an XML-encoded character string.

Syntax
Var2Xml( <xValue> ) --> cXmlString
Parameters
<xValue>
<xValue> is a value of any data type to be converted to an XML-encoded character string.
Return

The return value of Var2Xml() is a character string that contains the XML-encoded representation of the passed argument.

Description

The function Var2Xml() converts values of all data types to an XML-encoded character string, which includes both the data type and the value of the passed argument. The return value of Var2Xml() can be transformed back to the original value by passing it to the function Xml2Var().

This allows, for example, the exchange of data between different applications, specifically over Internet protocols, as well as storing data in a transparent, text-based, human-readable, and editable format.

Conversion of data types

Empty values are always represented by a single data type-specific XML element, in the format: <datatype/>, while not-empty values are first converted into their textual representation, and then enclosed in data type-specific XML start and end tags, to create an XML element in the format: <datatype>value</datatype>.

Converting data types
Data Type XML Representation (Example) Empty Value
Character (C) <character>Hello World</character> <character/>
Date (D) <date>20141213</date> <date/>
Logical (L) <logical>true</logical>
Numeric (N) <numeric>123.456</numeric>
Undefined (U) <undefined/>
Code Block (B) <codeblock>{|x| x + 1}</codeblock>
Array (A) <array>..elements..</array> *) <array/>
Object (O) <object classname="DataObject">..members..</object> *) <object classname="<ClassName>"/>
  1. See below for more detailed examples

Date values: Date values use DtoS() format (YYYYMMDD).

Character strings: Strings are XML-escaped. The following conversion table below shows which characters are XML-escaped and how they appear after conversion.

Character conversion table
Character ASCII value XML-encoded representation
TAB 9 Removed
LF 10 Removed
CR 13 Removed
SPACE 32 Leading spaces are removed
" 34 "
& 38 &
' 39 '
< 59 <
> 61 >
All others All others Unchanged

If a character string only contains white-space characters, it will be considered empty!

Code blocks: Code blocks shouldn't contain any STATIC or detached LOCAL variables, as any references to those variables are lost during the conversion.

Arrays: All array elements are listed as individual XML child elements, based on their data types and values, between the start and end tags of the array's XML element. Because child elements can represent any supported data type, they can themselves contain child elements, to describe multi-dimensional arrays or objects. For example, the array: {123.5, .t., "Test"} with three array elements would be represented by the following XML fragment:

<array> 
   <numeric>123.5</numeric> 
   <logical>true</logical> 
   <character>Test</character> 
</array> 

An array without elements is considered an empty value.

Objects: With regard to objects, the function Var2Xml() accepts only instances objects. When an object is converted to XML, the class name and the names of its exported instance variables are also encoded in the XML tags as XML Attributes. An object is represented by the XML start and end tags <object classname="<ClassName>"> and </object>. An object without any exported instance variables is considered an empty value.

All instance variables of an object are listed as individual XML child elements, based on their data types and values, between the start and end tags of the object's XML element. Each instance variable's start tag also contains a name attribute, which specifies the instance variable's name, such as: <array name="<iVarName>">. Because child elements can represent any supported data type, they can themselves contain child elements, to describe arrays or other objects. For example, an object of the class DataObject with a single instance variable named TextVar, which has a character string value of "Test", would be represented by the following XML fragment:

<object classname="DataObject"> 
   <character name="TextVar">Test</character> 
</object> 

Start tags of instance variables that represent objects will contain both attributes: <object classname="<ClassName>" name="<iVarName>">.

Examples
Convert values to XML-encoded strings

// The example shows how to convert values to XML format using Var2Xml(). 
// The XML-encoded representation of different value types are specified. 

PROCEDURE Main() 
   LOCAL oData     := DataObject():new() 

   oData:array     := {123, 'Text', Date()} 
   oData:codeblock := {|x| x + 1} 
   oData:character := "String with < & > ' " + Chr(34) 
   oData:date      := CtoD('01/23/2016') 
   oData:logical   := .t. 
   oData:number    := 123.456 
   oData:undefined := NIL 

   ? 'Var2Xml(oData)   : "' + Var2Xml(oData)    + '"' 
   WAIT 
RETURN 
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.