nfXml

**Provides two simple to use functions to parse/stringify XML **

Project Manager: Marco Plaza

Project includes:

• nfXmlRead.prg: standalone function, receives valid XML string or file name, returns VFP empty-based object.
• nfXmlCreate.prg: receives VFP object , returns XML string.

Basic Usage

oVfp = nfXMLRead(cXMLstring | fileName [, cArraysList, cXpath,@cObjectMap ])
    && creates a vfp object from xml.

cXml = nfXmlCreate( oVfp )
    && creates XML from a VFP empty-based object

cXpaths = nfxPaths( cXml )
    && Parse XML w/o schema and show all
    && object paths - please check notes
    && below for important notes about
    && arrays in XML.

IMPORTANT NOTES

oVfp = nfXMLRead( cXMLstring , cArraysList, @cXpath)

pass xml string, returns a vfp object. ( empty based, requires vfp9 )

ARRAYS ( cArraysList )

Unlike Json, XML does not identify object arrays on the XML document itself, it does it on the XML Schema.

To gain simplicity and ease of use, nfXmlRead uses no XML Schema.

nfXmlRead identifies arrays by counting the child nodes with identical names; so any node with more than one child node with identical name is identified as array, as no object can contain more than 2 properties with the same name.

If you're sure your XML contains no arrays and any contained array will have at least more than one member, you don't need to worry.

For any other situation, you can pass a comma separated list of all the xpaths that must be treated as arrays: a excel workbook contains the following arrays:

"/Workbook/Styles/Style[],/Workbook/Worksheet[]/Table/Row[]/Cell[]"

NAME PROPERTIES WITH SPECIAL CHARACTERS OR SPACES

XML allows node names with spaces and special characters; nfXml safely converts them to valid vfp property names by replacing them on the following way:

• ':' -> '_'
• '(' -> '_l_'
• ')' -> '_r_'
• '-' -> '_h_'
• '.' -> '_d_'

RESERVERD WORDS OR NON CHARACTER PROPERTY NAMES
will be prepended with '_' for example, you can't have an array called "row" since "row()" is a vfp function, then it gets renamed to _row also names starting with numbers and so on.

NODE ATTRIBUTES
node attributes are listed in a property called _attr_

NAMESPACES
Namespaces are prepended to node names, separated by "_" this way ss:Styles gets the vfp property name ss_styles;

object properties with "_" should be escaped with additional "_"

this way:

• oxml.customer_id gets serialized as: <customer:id>

• oxml.customer__id gets serialized as: <customer_id>

• oxml.customer___id gets serialized as: <customer_:id>

OPTIONAL PARAMETERS
xpathExp: you can pass any xPath Expression for nfXMLRead to return only the desired node without parsing the entire document; useful for big xml files.

ERROR MANAGEMENT
program will throw error if you supply invalid xml; manage accordingly.