Parasol Framework Manual

Provides XML data management services for parsing, manipulation and serialisation.

The XML class is designed to provide robust functionality for creating, parsing and maintaining XML data structures. It supports both well-formed and loosely structured XML documents, offering flexible parsing behaviours to accommodate various XML formats. The class includes comprehensive support for XPath queries, content manipulation and document validation.

Data Loading and Parsing

XML documents can be loaded into an XML object through multiple mechanisms:

The Path field allows loading from file system sources, with automatic parsing upon initialisation. The class supports LoadFile() caching for frequently accessed files, improving performance for repeated operations.

The Statement field enables direct parsing of XML strings, supporting dynamic content processing and in-memory document construction.

The Source field provides object-based input, allowing XML data to be sourced from any object supporting the Read action.

For batch processing scenarios, the Path or Statement fields can be reset post-initialisation, causing the XML object to automatically rebuild itself. This approach optimises memory usage by reusing existing object instances rather than creating new ones.

Document Structure and Access

Successfully parsed XML data is accessible through the Tags field, which contains a hierarchical array of XMLTag structures. Each XMLTag represents a complete XML element including its attributes, content and child elements. The structure maintains the original document hierarchy, enabling both tree traversal and direct element access.

C++ developers benefit from direct access to the Tags field, represented as pf::vector<XMLTag>. This provides efficient iteration and element access with standard STL semantics. However, direct modification of the Tags array is discouraged as it can destabilise internal object state - developers should use the provided methods for safe manipulation.

Structure

The XML class consists of the following fields:

Access

Name

Type

Comment

Flags XMF Controls XML parsing behaviour and processing options.

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 [] Provides direct access to the XML document structure.

The Tags field exposes the complete XML document structure as a hierarchical array of XMLTag structures. This field becomes available after successful XML parsing and provides the primary interface for reading XML content programmatically.

Each XMLTag will 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.

Direct read access to the Tags hierarchy is safe and efficient for traversing the document structure. However, modifications should be performed using the XML object's methods (InsertXML(), SetAttrib(), RemoveTag(), etc.) to maintain internal consistency and trigger appropriate cache invalidation.

Actions

The following actions are currently supported:

Clear Completely clears all XML data and resets the object to its initial state.

ERR acClear(*Object)

The Clear action removes all parsed XML content from the object, including the complete tag hierarchy, cached data structures and internal state information. This action effectively returns the XML object to its freshly-initialised condition, ready to accept new XML data.

DataFeed Processes and integrates external XML data into the object's document structure.

ERR acDataFeed(*Object, OBJECTID Object, DATA Datatype, APTR Buffer, INT Size)

Parameter	Description
Object	Must refer to the unique ID of the object that you represent. If you do not represent an object, set this parameter to the current task ID.
Datatype	The type of data being sent.
Buffer	The data being sent to the target object.
Size	The size of the data in Buffer.

The DataFeed action provides a mechanism for supplying XML content to the object from external sources or streaming data. This action supports both complete document replacement and incremental content addition, depending on the current state of the XML object.

The action accepts data in XML or plain text format and automatically performs parsing and integration. When the object contains no existing content, the provided data becomes the complete document structure. If the object already contains parsed XML, the new data is parsed separately and appended to the existing tag hierarchy.

If the provided data contains malformed XML or cannot be parsed according to the current validation settings, the action will return appropriate error codes without modifying the existing document structure. This ensures that partial parsing failures do not corrupt previously loaded content.

Attempts to feed data into a read-only XML object will be rejected to maintain document integrity.

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 expression.

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

Parameter	Description
XPath	A valid XPath expression string defining the elements to count. The expression must conform to XPath 1.0 syntax with Parasol extensions.
Result	Pointer to an integer variable that will receive the total count of matching tags.

This method will count all tags that match a given XPath and return the value in the Result parameter. It is optimised for performance and does not modify the XML structure in any way. It is safe to call concurrently from multiple threads.

Error Codes

Okay	The count operation completed successfully.
NullArgs	Either the XPath parameter or Result parameter was NULL.

Filter Filters the XML data structure to retain only a specific tag and its descendants.

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

Parameter	Description
XPath	A valid XPath expression string that identifies the target tag to retain. The expression must resolve to exactly one element for successful filtering.

The Filter method provides a mechanism for reducing large XML documents to a specific subtree, permanently removing all content that exists outside the targeted element and its children. This operation is particularly valuable for performance optimisation when working with large documents where only a specific section is relevant.

The filtering process begins by locating the target element using the provided XPath expression. Once found, a new XML structure is created containing only the matched tag and its complete descendant hierarchy. All sibling tags, parent elements (excluding the direct lineage) and unrelated branches are permanently discarded.

Error Codes

Okay	The filtering operation completed successfully and the XML structure now contains only the specified subtree.
Search	No matching tag could be found for the specified XPath expression.
NullArgs	The XPath parameter was NULL or empty.

FindTag Searches for XML elements using XPath expressions with optional callback processing.

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

Parameter	Description
XPath	A valid XPath expression string conforming to XPath 1.0 syntax with Parasol extensions. Must not be NULL or empty.
Callback	Optional pointer to a callback function for processing multiple matches.
Result	Pointer to an integer that will receive the unique ID of the first matching tag. Only valid when no callback is provided.

The FindTag method provides the primary mechanism for locating XML elements within the document structure using XPath 1.0 compatible expressions. The method supports both single-result queries and comprehensive tree traversal with callback-based processing for complex operations.

The method supports comprehensive XPath syntax including absolute paths, attribute matching, content matching (a Parasol extension), wildcarding, deep scanning with double-slash notation, indexed access and complex expressions with multiple criteria.

When no callback function is provided, FindTag returns the first matching element and terminates the search immediately. This is optimal for simple queries where only the first occurrence is required.

When a callback function is specified, FindTag continues searching through the entire document structure, calling the provided function for each matching element. This enables comprehensive processing of all matching elements in a single traversal.

The C++ prototype for the callback function is ERR Function(*XML, XMLTag &Tag, CSTRING Attrib).

The callback should return ERR::Okay to continue processing, or ERR::Terminate to halt the search immediately. All other error codes are ignored to maintain search robustness.

Error Codes

Okay	A matching tag was found (or callback processing completed successfully).
Search	No matching tag could be found for the specified XPath expression.
NoData	The XML document contains no data to search.
NullArgs	The XPath parameter was NULL or the Result parameter was NULL when no callback was provided.

GetAttrib Retrieves the value of a specific XML attribute from a tagged element.

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

Parameter	Description
Index	The unique identifier of the XML tag to search. This must correspond to a valid tag ID as returned by methods such as FindTag().
Attrib	The name of the attribute to retrieve (case insensitive). If NULL or empty, the element's tag name is returned instead.
Value	Pointer to a string pointer that will receive the attribute value. Set to NULL if the specified attribute does not exist.

The GetAttrib method provides efficient access to individual attribute values within XML elements. Given a tag identifier and attribute name, the method performs a case-insensitive search through the element's attribute collection and returns the corresponding value.

When a specific attribute name is provided, the method searches through all attributes of the target tag. The search is case-insensitive to accommodate XML documents with varying capitalisation conventions.

When the attribute name is NULL or empty, the method returns the tag name itself, providing convenient access to element names without requiring separate API calls.

Performance Considerations

For applications requiring frequent attribute access or high-performance scenarios, C++ developers should consider direct access to the XMLAttrib structure array. This bypasses the method call overhead and provides immediate access to all attributes simultaneously.

The method performs a linear search through the attribute collection, so performance scales with the number of attributes per element. For elements with many attributes, caching frequently accessed values may improve performance.

Data Integrity

The returned string pointer references internal XML object memory and remains valid until the XML structure is modified. Callers should not attempt to modify or free the returned string. For persistent storage, the string content should be copied to application-managed memory.

Error Codes

Okay	The attribute was successfully found and its value returned.
NotFound	Either the specified tag Index does not exist, or the named attribute was not found within the tag.
NullArgs	Required arguments were not specified correctly.

GetContent Extracts the immediate text content of an XML element, excluding nested tags.

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

Parameter	Description
Index	The unique identifier of the XML element from which to extract content. This must correspond to a valid tag ID as returned by search methods.
Buffer	Pointer to a pre-allocated character buffer that will receive the extracted content string. Must not be NULL.
Length	The size of the provided buffer in bytes, including space for null termination. Must be at least 1.

The GetContent method provides efficient extraction of text content from XML elements using a shallow parsing approach. It retrieves only the immediate text content of the specified element, deliberately excluding any text contained within nested child elements. This behaviour is valuable for scenarios requiring precise content extraction without recursive tag processing.

Consider the following XML structure:

<body>
  Hello
  <bold>emphasis</bold>
  world!
</body>

The GetContent method would extract Hello world! and deliberately exclude emphasis since it is contained within the nested <bold> element.

Comparison with Deep Extraction

For scenarios requiring complete text extraction including all nested content, use the Serialise() method with appropriate flags to perform deep content analysis. The GetContent method is optimised for cases where nested tag content should be excluded from the result.

If the resulting content exceeds the buffer capacity, the result will be truncated but remain null-terminated.

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

Error Codes

Okay	The content string was successfully extracted and copied to the buffer.
NotFound	The tag identified by Index does not exist in the XML structure.
Args	The Length parameter was less than 1, indicating insufficient buffer space.
BufferOverflow	The buffer was not large enough to hold the complete content. The result is truncated but valid.
NullArgs	Either the Buffer parameter was NULL or other required arguments were missing.

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 text content into the XML document structure at specified positions.

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

Parameter	Description
Index	The unique identifier of the target XML element that will serve as the reference point for insertion.
Where	Specifies the insertion position relative to the target element. Use PREV or NEXT for sibling insertion, or CHILD for child content insertion.
Content	The text content to insert. Special XML characters will be automatically escaped to ensure document validity.
Result	Pointer to an integer that will receive the unique identifier of the newly created content node.

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	The content was successfully inserted and a new content node was created.
NotFound	The target Index does not correspond to a valid XML element.
ReadOnly	The XML object is in read-only mode and cannot be modified.
NullArgs	Required parameters were NULL or not properly specified.

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

Data Loading and Parsing

Document Structure and Access

Structure

Actions

Methods

Performance Considerations

Data Integrity

Comparison with Deep Extraction

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