Parasol Framework Manual

Provides XML data management services.

The XML class provides functionality to create and maintain XML data files. It is capable of parsing and validating XML files with or without correct structure, and can perform optional parsing behaviours such as stripping comments during processing.

Data can be loaded into an XML object either by specifying a file Path or by giving it an XML Statement. If multiple XML statements need to be processed then reset the Path or Statement field after initialisation and the XML object will rebuild itself. This saves on allocating multiple XML objects for batch processing.

Successfully processed data can be read back by scanning the array referenced in the Tags field. The array contains an XMLTag structure for each tag parsed from the original XML statement. For more information on how to scan this information, refer to the Tags field. C++ developers are recommended to interact with Tags directly, which is represented as pf::vector<XMLTag>. Note that adding new Tags is a volatile action that can destabilise the object (taking a complete copy of the tags may be warranted instead).

Structure

The XML class consists of the following fields:

Access

Name

Type

Comment

Flags XMF Optional flags.

Name	Description
XMF::INCLUDE_COMMENTS	By default, comments are stripped when parsing XML input unless this flag is specified.
XMF::INCLUDE_SIBLINGS	Include siblings when building an XML string (GetXMLString() only)
XMF::INCLUDE_WHITESPACE	By default the XML parser will trim whitespace (such as return codes, spaces and tabs) found in the XML content between tags. Setting this flag turns off this feature, allowing all whitespace to be included.
XMF::INDENT	Indent the output of serialised XML to improve readability.
XMF::LOCK_REMOVE	Prevents removal of tags from the XML tree. This specifically affects the RemoveTag and RemoveXPath methods.
XMF::LOG_ALL	Print extra log messages.
XMF::NEW	Creates an empty XML object on initialisation - if the Path field has been set, the source file will not be loaded.
XMF::NO_ESCAPE	Turns off escape code conversion.
XMF::OMIT_TAGS	Prevents tags from being output when the XML is serialised (output content only).
XMF::PARSE_ENTITY	Entity references in the DTD will be parsed automatically.
XMF::PARSE_HTML	Automatically parse HTML escape codes.
XMF::READABLE	Indent the output of serialised XML to improve readability.
XMF::STRIP_CDATA	Do not echo `CDATA` sections. Note that this option is used as a parameter, not an object flag.
XMF::STRIP_CONTENT	Strip all content from incoming XML data.
XMF::STRIP_HEADERS	XML headers found in the source data will not be included in the parsed results.
XMF::WELL_FORMED	By default, the XML class will accept badly structured XML data. This flag requires that XML statements must be well-formed (tags must balance) or an `ERR::BadData` error will be returned during processing.

Modified INT A timestamp of when the XML data was last modified.

The Modified field provides an artificial timestamp value of when the XML data was last modified (e.g. by a tag insert or update). Storing the current Modified value and making comparisons later makes it easy to determine that a change has been made. A rough idea of the total number of change requests can also be calculated by subtracting out the difference.

Path STRING Set this field if the XML document originates from a file source.

XML documents can be loaded from the file system by specifying a file path in this field. If set post-initialisation, all currently loaded data will be cleared and the file will be parsed automatically.

The XML class supports LoadFile(), so an XML file can be pre-cached by the program if it is frequently used during a program's life cycle.

ReadOnly INT Prevents modifications and enables caching for a loaded XML data source.

This field can be set to true prior to initialisation of an XML object that will use an existing data source. It prevents modifications to the XML object. If the data originates from a file path, the data may be cached to optimise parsing where the same data is used across multiple XML objects.

Source OBJECTPTR Set this field if the XML data is to be sourced from another object.

An XML document can be loaded from another object by referencing it here, on the condition that the object's class supports the Read action.

If set post-initialisation, all currently loaded data will be cleared and the source object will be parsed automatically.

Start INT Set a starting cursor to affect the starting point for some XML operations.

When using any XML function that creates an XML string (e.g. SaveToObject), the XML object will include the entire XML tree by default. Defining the Start value will restrict processing to a specific tag and its children.

The Start field currently affects the SaveToObject() action and the Statement field.

Statement STRING XML data is processed through this field.

Set the Statement field to parse an XML formatted data string through the object. If this field is set after initialisation then the XML object will clear any existing data first.

Be aware that setting this field with an invalid statement will result in an empty XML object.

Reading the Statement field will return a serialised string of XML data. By default all tags will be included in the statement unless a predefined starting position is set by the Start field. The string result is an allocation that must be freed.

Tags STRUCT [] Points to an array of tags loaded into an XML object.

The successful parsing of XML data will make the information available via the Tags array. The array is presented as a series of XMLTag structures.

Each XMLTag will also have at least one attribute set in the Attribs array. The first attribute will either reflect the tag name or a content string if the Name is undefined. The Children array provides access to all child elements.

Developers may treat the entire tag hierarchy as readable, but writes should be accomplished with the available XML methods.

Actions

The following actions are currently supported:

Clear Clears all of the data held in an XML object.

GetKey Retrieves data from an xml object.

ERR acGetKey(*Object, CSTRING Key, STRING Value, INT Size)

Parameter	Description
Key	The name of a key value.
Value	Pointer to a buffer space large enough to hold the retrieved value.
Size	Indicates the byte size of the Buffer.

The XML class uses key-values for the execution of XPath queries. Documentation of the XPath standard is out of the scope for this document, however the following examples illustrate the majority of uses for this query language and a number of special instructions that we support:

Name	Description
/menu/submenu	Return the content of the submenu tag whose parent is the first menu.
xpath:/menu[2]/submenu	Return the content of the submenu tag whose parent is the third menu.
count:/menu	Return a count of all menu tags at the root level.
xml:/menu/window/@title	Return the value of the title attribute from the window tag.
content:/menu/window(@title='foo')	Return the content of the window tag which has title `foo`.
extract:/menu/window(@title='bar')	Extract all XML from the window tag which has title `bar`.
extract:/menu//window(=apple)	Extract all XML from the first window tag found anywhere inside `<menu>` that contains content `apple`.
exists:/menu/@title	Return `1` if a menu with a title attribute can be matched, otherwise `0`.
contentexists:/menu	Return `1` if if the immediate child tags of the XPath contain text (white space is ignored).
//window	Return content of the first window discovered at any branch of the XML tree (double-slash enables flat scanning of the XML tree).

The xpath, xml and / prefixes are all identical in identifying the start of an xpath. The content prefix is used to specifically extract the content of the tag that matches the xpath. Square brackets and round brackets may be used interchangeably for lookups and filtering clauses.

Reset Clears the information held in an XML object.

SaveToObject Saves XML data to a storage object (e.g. File).

ERR acSaveToObject(*Object, OBJECTID Dest, CLASSID ClassID)

Parameter	Description
Dest	Refers to an object that will receive the encoded data.
ClassID	Can refer to a sub-class that should be used when encoding the data.

SetKey Sets attributes and content in the XML tree using XPaths.

ERR acSetKey(*Object, CSTRING Key, CSTRING Value)

Parameter	Description
Key	The name of the target key.
Value	The string value to associate with Key.

Use SetKey to add tag attributes and content using XPaths. The XPath is specified in the Key parameter and the data is specified in the Value parameter. Setting the Value to NULL will remove the attribute or existing content, while an empty string will keep an attribute but eliminate any associated data.

It is not possible to add new tags using this action - it is only possible to update existing tags.

Please note that making changes to the XML tree will render all previously obtained tag pointers and indexes invalid.

Error Codes

Okay	Operation successful.
Search	Failed to find the tag referenced by the XPath.
ReadOnly	Changes to the XML structure are not permitted.

Methods

The following methods are currently supported:

Count Count all tags that match a given XPath.

ERR xml::Count(OBJECTPTR Object, CSTRING XPath, INT * Result)

Parameter	Description
XPath	The XPath on which to perform the count.
Result	The total number of matching tags is returned here.

This method will count all tags that match a given XPath and return the value in the Result parameter.

Error Codes

Okay	Operation successful.
NullArgs	Function call missing argument value(s)

Filter Filters the XML data down to a single tag and its children.

ERR xml::Filter(OBJECTPTR Object, CSTRING XPath)

Parameter	Description
XPath	Refers to a valid XPath string.

The Filter() method is used to reduce the amount of data in an XML tree, filtering out all data exclusive to the targeted tag and its children. This is useful for speeding up XPath queries where interest is limited to only one area of the XML tree, or for reducing the memory footprint of large trees.

Data that has been filtered out by this method is permanently removed.

Error Codes

Okay	Operation successful.
Search	A matching tag could not be found.
NullArgs	Function call missing argument value(s)

FindTag Searches for a tag via XPath.

ERR xml::FindTag(OBJECTPTR Object, CSTRING XPath, FUNCTION * Callback, INT * Result)

Parameter	Description
XPath	An XPath string.
Callback	Optional reference to a function that should be called for each matching tag.
Result	The index of the first matching tag is returned in this parameter (not valid if a `Callback` is defined).

This method will return the first tag that matches the search string specified in XPath. Optionally, if the XPath uses wildcards or would match multiple tags, a Callback function may be passed that will be called for each matching tag that is discovered. The prototype for the callback function is ERR Function(*XML, XMLTag &Tag, CSTRING Attrib).

The Callback routine can terminate the search early by returning ERR::Terminate. All other error codes are ignored.

Error Codes

Okay	A matching tag was found.
Search	A matching tag could not be found.
NoData	No data is available for use.
NullArgs	Function call missing argument value(s)

GetAttrib Retrieves the value of an XML attribute.

ERR xml::GetAttrib(OBJECTPTR Object, INT Index, CSTRING Attrib, CSTRING * Value)

Parameter	Description
Index	The index of the XML tag to search.
Attrib	The name of the attribute to search for (case insensitive). If `NULL` or an empty string, the tag name is returned as the result.
Value	The value of the attribute is returned here, or `NULL` if the named `Attrib` does not exist.

The GetAttrib method scans a tag for a specific attribute and returns it. A tag Index and name of the required Attrib must be specified. If found, the attribute value is returned in the Value parameter.

It is recommended that C/C++ programs bypass this method and access the XMLAttrib structure directly.

Error Codes

Okay	The attribute was found.
NotFound	The `Attrib` name was not found.
Args	The required arguments were not specified.

GetContent Extracts the content of an XML tag.

ERR xml::GetContent(OBJECTPTR Object, INT Index, STRING Buffer, INT Length)

Parameter	Description
Index	Index of a tag that contains content.
Buffer	Pointer to a buffer that will receive the string data.
Length	The length of the `Buffer` in bytes.

The GetContent method is used to extract the string content from an XML tag. It will extract content that is immediately embedded within the XML tag and will not perform deep analysis of the tag structure (refer to Serialise() for deep extraction). Consider the following structure:

<body>
  Hello
  <bold>my</bold>
  friend!
</body>

This will produce the result Hello friend! and omit everything encapsulated within the bold tag.

Error Codes

Okay	The content string was successfully extracted.
NotFound	The tag identified by `Index` was not found.
Args	Invalid arguments passed to function.
BufferOverflow	The `Buffer` was not large enough to hold the content (the resulting string will be valid but truncated).

GetTag Returns a pointer to the XMLTag structure for a given tag index.

ERR xml::GetTag(OBJECTPTR Object, INT Index, struct XMLTag ** Result)

Parameter	Description
Index	The index of the tag that is being retrieved.
Result	The XMLTag is returned in this parameter.

This method will return the XMLTag structure for a given tag Index. The Index is checked to ensure it is valid prior to retrieval, and an ERR::OutOfRange error will be returned if it is invalid.

Error Codes

Okay	Operation successful.
NotFound	The Index is not recognised.
NullArgs	Function call missing argument value(s)

InsertContent Inserts XML content into the XML tree.

ERR xml::InsertContent(OBJECTPTR Object, INT Index, XMI Where, CSTRING Content, INT * Result)

Parameter	Description
Index	Identifies the target XML tag.
Where	Use `PREV` or `NEXT` to insert behind or ahead of the target tag. Use `CHILD` for a child insert.
Content	The content to insert.
Result	The index of the new tag is returned here.

The InsertContent method will insert content strings into any position within the XML tree. A content string must be provided in the Content parameter and the target insertion point is specified in the Index parameter. An insertion point relative to the target index must be specified in the Where parameter. The new tags can be inserted as a child of the target by using a Where value of XMI::CHILD. To insert behind or after the target, use XMI::PREV or XMI::NEXT.

To modify existing content, call SetAttrib() instead.

Error Codes

Okay	Operation successful.
ReadOnly	A delete or write operation failed due to read-only status.
NullArgs	Function call missing argument value(s)

InsertXML Parse an XML string and insert it in the XML tree.

ERR xml::InsertXML(OBJECTPTR Object, INT Index, XMI Where, CSTRING XML, INT * Result)

Parameter	Description
Index	The new data will target the tag specified here.
Where	Use `PREV` or `NEXT` to insert behind or ahead of the target tag. Use `CHILD` or `CHILD_END` for a child insert.
XML	An XML statement to parse.
Result	The resulting tag index.

The InsertXML() method is used to translate and insert a new set of XML tags into any position within the XML tree. A standard XML statement must be provided in the XML parameter and the target insertion point is specified in the Index parameter. An insertion point relative to the target index must be specified in the Where parameter. The new tags can be inserted as a child of the target by using a Where value of XMI::CHILD. Use XMI::CHILD_END to insert at the end of the child list. To insert behind or after the target, use XMI::PREV or XMI::NEXT.

Error Codes

Okay	The statement was added successfully.
Args	Invalid arguments passed to function.
OutOfRange	A specified number is outside of the valid range.
ReadOnly	Changes to the XML data are not permitted.
NullArgs	Function call missing argument value(s)

InsertXPath Inserts an XML statement in an XML tree.

ERR xml::InsertXPath(OBJECTPTR Object, CSTRING XPath, XMI Where, CSTRING XML, INT * Result)

Parameter	Description
XPath	An XPath string that refers to the target insertion point.
Where	Use `PREV` or `NEXT` to insert behind or ahead of the target tag. Use `CHILD` for a child insert.
XML	The statement to process.
Result	The index of the new tag is returned here.

The InsertXPath method is used to translate and insert a new set of XML tags into any position within the XML tree. A standard XML statement must be provided in the XML parameter and the target insertion point is referenced as a valid XPath location string. An insertion point relative to the XPath target must be specified in the Where parameter. The new tags can be inserted as a child of the target by using an Insert value of XMI::CHILD or XMI::CHILD_END. To insert behind or after the target, use XMI::PREV or XMI::NEXT.

Error Codes

Okay	Operation successful.
Search	The `XPath` could not be resolved.
NullArgs	Function call missing argument value(s)

MoveTags Move an XML tag group to a new position in the XML tree.

ERR xml::MoveTags(OBJECTPTR Object, INT Index, INT Total, INT DestIndex, XMI Where)

Parameter	Description
Index	Index of the source tag to be moved.
Total	The total number of sibling tags to be moved from the source index. Minimum value of 1.
DestIndex	The destination tag index. If the index exceeds the total number of tags, the value will be automatically limited to the last tag index.
Where	Use `PREV` or `NEXT` to insert behind or ahead of the target tag. Use `CHILD` for a child insert.

This method is used to move XML tags within the XML tree structure. It supports the movement of single and groups of tags from one index to another. The client must supply the index of the tag that will be moved and the index of the target tag. All child tags of the source will be included in the move.

An insertion point relative to the target index must be specified in the Where parameter. The source tag can be inserted as a child of the destination by using a Where of XMI::CHILD. To insert behind or after the target, use XMI::PREV or XMI::NEXT.

Error Codes

Okay	Tags were moved successfully.
NotFound	A search routine in this function failed.
ReadOnly	A delete or write operation failed due to read-only status.
NullArgs	Function call missing argument value(s)

RemoveTag Removes tag(s) from the XML structure.

ERR xml::RemoveTag(OBJECTPTR Object, INT Index, INT Total)

Parameter	Description
Index	Reference to the tag that will be removed.
Total	The total number of sibling (neighbouring) tags that should also be deleted. A value of one or less will remove only the indicated tag and its children. The total may exceed the number of tags actually available, in which case all tags up to the end of the branch will be affected.

The RemoveTag method is used to remove one or more tags from an XML structure. Child tags will automatically be discarded as a consequence of using this method, in order to maintain a valid XML structure.

This method is capable of deleting multiple tags if the Total parameter is set to a value greater than 1. Each consecutive tag and its children following the targeted tag will be removed from the XML structure until the count is exhausted. This is useful for mass delete operations.

This method is volatile and will destabilise any cached address pointers that have been acquired from the XML object.

Error Codes

Okay	Operation successful.
OutOfRange	A specified number is outside of the valid range.
ReadOnly	A delete or write operation failed due to read-only status.
NullArgs	Function call missing argument value(s)

RemoveXPath Removes tag(s) from the XML structure, using an xpath lookup.

ERR xml::RemoveXPath(OBJECTPTR Object, CSTRING XPath, INT Limit)

Parameter	Description
XPath	An XML path string.
Limit	The maximum number of matching tags that should be deleted. A value of one or less will remove only the indicated tag and its children. The total may exceed the number of tags actually available, in which case all matching tags up to the end of the tree will be affected.

The RemoveXPath method is used to remove one or more tags from an XML structure. Child tags will automatically be discarded as a consequence of using this method, in order to maintain a valid XML structure.

Individual tag attributes can also be removed if an attribute is referenced at the end of the XPath.

The removal routine will be repeated so that each tag that matches the XPath will be deleted, or the Limit is reached.

This method is volatile and will destabilise any cached address pointers that have been acquired from the XML object.

Error Codes

Okay	Operation successful.
ReadOnly	A delete or write operation failed due to read-only status.
NullArgs	Function call missing argument value(s)

Serialise Serialise part of the XML tree to an XML string.

ERR xml::Serialise(OBJECTPTR Object, INT Index, XMF Flags, STRING * Result)

Parameter	Description
Index	Index to a source tag for which serialisation will start. Set to zero to serialise the entire tree.
Flags	Use `INCLUDE_SIBLINGS` to include siblings of the tag found at Index.
Result	The resulting string is returned in this parameter.

The Serialise() method will serialise all or part of the XML data tree to a string.

The string will be allocated as a memory block and stored in the Result parameter. It must be freed once the data is no longer required.

Error Codes

Okay	The XML string was retrieved.
Args	Invalid arguments passed to function.
NoData	No information has been loaded into the XML object.
AllocMemory	Failed to allocate an XML string for the result.

SetAttrib Adds, updates and removes XML attributes.

ERR xml::SetAttrib(OBJECTPTR Object, INT Index, XMS Attrib, CSTRING Name, CSTRING Value)

Parameter	Description
Index	Identifies the tag that is to be updated.
Attrib	Either the index number of the attribute that is to be updated, or set to `NEW`, `UPDATE` or `UPDATE_ONLY`.
Name	String containing the new name for the attribute. If `NULL`, the name will not be changed. If Attrib is `UPDATE` or `UPDATE_ONLY`, the `Name` is used to find the attribute.
Value	String containing the new value for the attribute. If `NULL`, the attribute is removed.

This method is used to update and add attributes to existing XML tags, as well as adding or modifying content.

The data for the attribute is defined in the Name and Value parameters. Use an empty string if no data is to be associated with the attribute. Set the Value pointer to NULL to remove the attribute. If both Name and Value are NULL, an error will be returned.

NOTE: The attribute at position 0 declares the name of the tag and should not normally be accompanied with a value declaration. However, if the tag represents content within its parent, then the Name must be set to NULL and the Value string will determine the content.

Error Codes

Okay	Operation successful.
Search	The attribute, identified by `Name`, could not be found.
Args	Invalid arguments passed to function.
OutOfRange	The `Index` or `Attrib` value is out of range.
ReadOnly	The XML object is read-only.
NullArgs	Function call missing argument value(s)

Sort Sorts XML tags to your specifications.

ERR xml::Sort(OBJECTPTR Object, CSTRING XPath, CSTRING Sort, XSF Flags)

Parameter	Description
XPath	Sort everything under the specified tag, or `NULL` to sort the entire top level.
Sort	Pointer to a sorting instruction string.
Flags	Optional flags.

The Sort method is used to sort a single branch of XML tags in ascending or descending order. An XPath is required that refers to the tag containing each item that will be sorted. To sort the root level, use an XPath of NULL.

The Sort parameter is used to specify a list of sorting instructions. The format for the Sort string is Tag:Attrib,Tag:Attrib,.... The Tag indicates the tag name that should be identified for sorting each node, and child tags are supported for this purpose. Wildcard filtering is allowed and a Tag value of * will match every tag at the requested XPath level. The optional Attrib value names the attribute containing the sort string. To sort on content, do not define an Attrib value (use the format Tag,Tag,...).

Error Codes

Okay	The XML object was successfully sorted.
Search	The provided `XPath` failed to locate a tag.
AllocMemory	A call to AllocMemory() failed to create a new memory block.
ReadOnly	A delete or write operation failed due to read-only status.
NullArgs	Function call missing argument value(s)

Name	Description
XMS::NEW	Adds a new attribute. Note that if the attribute already exists, this will result in at least two attributes of the same name in the tag.
XMS::UPDATE	As for `UPDATE_ONLY`, but if the attribute does not exist, it will be created.
XMS::UPDATE_ONLY	SetAttrib will find the target attribute and update it. It is not possible to rename the attribute when using this technique. `ERR::Search` is returned if the attribute cannot be found.

Name	Description
XSF::CHECK_SORT	Tells the algorithm to check for a 'sort' attribute in each analysed tag and if found, the algorithm will use that as the sort value instead of that indicated in the `Attrib` field.
XSF::DESC	Sort in descending order.

Field	Type	Description
Name	std::string	Name of the attribute
Value	std::string	Value of the attribute

XML Class

Structure

Actions

Methods

XMF Type

XMI Type

XMS Type

XSF Type

XMLAttrib Structure

XMLTag Structure

Name	Description
XMI::CHILD	Insert as the first child of the target.
XMI::CHILD_END	Insert as the last child of the target.
XMI::NEXT	Insert as the next tag of the target.
XMI::PREV	Insert as the previous tag of the target.

Field	Type	Description
ID	INT	Unique ID assigned to the tag on creation
ParentID	INT	Unique ID of the parent tag
LineNo	INT	Line number on which this tag was encountered
Flags	XTF	Optional flags
Attribs	pf::vector<XMLAttrib>	Array of attributes for this tag
Children	pf::vector<XMLTag>	Array of child tags