Parasol Framework Manual

Provides an interface for the management of structured data.

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 2.0 queries, content manipulation and document validation.

The class has been designed in such a way as to accommodate other structured data formats such as JSON and YAML. In this way, the class not only provides XML support but also serves as Parasol's general-purpose structured data handler. It also makes it trivial to convert between different structured data formats, and benefit from the cross-application use of features, such as applying XPath 2.0 queries on data originating from YAML.

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 changed post-initialisation, causing the XML object to clear old data and parse the new. 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. Altering tag attributes is permitted and methods to do so are provided in the C++ header for objXML and XMLTag, with additional functions in the xml namespace. Check the header for details.

Fluid developers need to be aware that reading the Tags field generates a copy of the entire tag structure - it should therefore be read only as needed and cached until the XML object is modified.

Not Supported

DTD processing and validation is intentionally not supported. While the class can parse DOCTYPE declarations, it does not load or validate against external DTDs as this is now a legacy technology. Use XML Schema (XSD) for validation instead.

Structure

The XML class consists of the following fields:

Access

Name

Type

Comment

DocType STRING Root element name from DOCTYPE declaration

ErrorMsg STRING A textual description of the last parse error.

This field may provide a textual description of the last parse error that occurred, in conjunction with the most recently received error code. Issues parsing malformed XPath expressions may also be reported here.

Flags XMF Controls XML parsing behaviour and processing options.

Name	Description
XMF::HAS_SCHEMA	Automatically defined when a schema has been loaded into the XML object.
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 skip content between tags when they contain pure whitespace. Setting this flag will retain all whitespace.
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::NAMESPACE_AWARE	Enable namespace processing during parsing.
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	Enables parsing of DOCTYPE entities.
XMF::PARSE_HTML	Automatically parse HTML escape codes.
XMF::READABLE	Indent the output of serialised XML to improve readability.
XMF::STANDALONE	Automatically defined when the XML declaration specifies standalone="yes".
XMF::STRIP_CDATA	Do not serialise `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.

PublicID STRING Public identifier for external DTD

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.

SystemID STRING System identifier for external DTD

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.

NOTE: Fluid will copy this field on read, caching the value is therefore recommended.

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.

Example:


local xml = obj.new('xml')
local err = xml.acDataFeed(nil, DATA_XML, 'First element')

GetKey Retrieves data using XPath 2.0 queries.

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 2.0 queries. Documentation of the XPath standard is out of the scope for this document, however the following examples illustrate common 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.
/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.
/menu/window/@title	Return the value of the title attribute from the window tag.
exists(/menu/@title)	Return `1` if a menu with a title attribute can be matched, otherwise `0`.
exists(/menu/text())	Return `1` if menu contains content.
//window	Return content of the first window discovered at any branch of the XML tree (double-slash enables flat scanning of the XML tree).

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 2.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 2.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 2.0 compatible expressions. The method supports both single-result queries and comprehensive tree traversal with callback-based processing for complex operations.

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

GetEntity Retrieves the value of a parsed entity declaration.

ERR xml::GetEntity(OBJECTPTR Object, CSTRING Name, CSTRING * Value)

Parameter	Description
Name	The name of the entity to retrieve. This must correspond to a parsed entity declaration.
Value	Receives the resolved entity value on success. The returned pointer remains valid while the XML object exists.

This method returns the expanded value associated with a general entity parsed from the document's DOCTYPE declaration. Entity names are case-sensitive and must match exactly as declared.

Error Codes

Okay	The entity was found and its value returned.
Search	No matching entity could be found for the specified name.
NullArgs	Either the Name or Value parameter was NULL.

GetNamespaceURI Retrieve the namespace URI for a given namespace UID.

ERR xml::GetNamespaceURI(OBJECTPTR Object, UINT NamespaceID, CSTRING * Result)

Parameter	Description
NamespaceID	The UID of the namespace.
Result	Pointer to a string pointer that will receive the namespace URI.

This method retrieves the original namespace URI string for a given namespace UID.

Error Codes

Okay	The namespace URI was successfully retrieved.
Search	No namespace found for the specified UID.
NullArgs	Required arguments were not specified correctly.

GetNotation Retrieves information about a parsed notation declaration.

ERR xml::GetNotation(OBJECTPTR Object, CSTRING Name, CSTRING * Value)

Parameter	Description
Name	The notation name to look up.
Value	Receives the notation descriptor on success.

Returns the system or public identifier captured for a notation declaration inside the document type definition. If both public and system identifiers were provided they are returned as a single string separated by a single space.

Error Codes

Okay	The notation was found and its descriptor returned.
Search	No matching notation could be found for the specified name.
NullArgs	Either the Name or Value parameter was NULL.

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.
Args	The Where parameter specifies an invalid insertion position.
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.
NotFound	The target Index does not correspond to a valid XML element.
Args	The Where parameter specifies an invalid insertion position.
NoData	The provided XML statement parsed to an empty result.
ReadOnly	Changes to the XML data are not permitted.
NullArgs	Required parameters were NULL or not properly specified.

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	The XML statement was successfully inserted at the specified XPath location.
Search	The XPath could not be resolved to a valid location.
ReadOnly	The XML object is in read-only mode and cannot be modified.
NullArgs	Required parameters were NULL or not properly specified.

LoadSchema Load an XML Schema definition to enable schema-aware validation.

ERR xml::LoadSchema(OBJECTPTR Object, CSTRING Path)

Parameter	Description
Path	File system path to the XML Schema (XSD) document.

This method parses an XML Schema document and attaches its schema context to the current XML object. Once loaded, schema metadata is available for validation and XPath evaluation routines that utilise schema-aware behaviour.

Error Codes

Okay	Schema was successfully loaded and parsed.
NoData	The schema document did not contain any parsable definitions.
CreateObject	The file in Path could not be processed as XML content.
NullArgs	The Path argument was not provided.

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 (including the targeted tag) 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	Either the source or destination tag index does not exist.
Args	Invalid parameter values were provided.
ReadOnly	The XML object is in read-only mode and cannot be modified.
NullArgs	Required parameters were NULL or not properly specified.
SanityCheckFailed	An internal consistency check failed during the move operation.

RegisterNamespace Register a namespace URI and return its UID.

ERR xml::RegisterNamespace(OBJECTPTR Object, CSTRING URI, UINT * Result)

Parameter	Description
URI	The namespace URI to register. Must not be NULL or empty.
Result	Pointer to an integer that will receive the UID for the namespace URI.

This method registers a namespace URI and returns a UID that can be used to identify the namespace efficiently throughout the XML document.

Error Codes

Okay	The namespace was successfully registered.
Failed	The URI was empty or invalid.
NullArgs	Required arguments were not specified correctly.

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	The tag(s) were successfully removed.
NotFound	The specified tag Index does not exist in the XML structure.
ReadOnly	The XML object is in read-only mode and cannot be modified.
NullArgs	Required parameters were NULL or not properly specified.

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 to delete. A value of one or zero will remove only the indicated tag and its children. A value of -1 removes all matching tags.

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	The matching tag(s) or attribute(s) were successfully removed.
NoData	The XML document contains no data to process.
ReadOnly	The XML object is in read-only mode and cannot be modified.
NullArgs	Required parameters were NULL or not properly specified.

ResolvePrefix Resolve a namespace prefix to the UID of its namespace URI within a tag's scope.

ERR xml::ResolvePrefix(OBJECTPTR Object, CSTRING Prefix, INT TagID, UINT * Result)

Parameter	Description
Prefix	The namespace prefix to resolve. Use empty string for default namespace.
TagID	The tag ID defining the starting scope for namespace resolution.
Result	Pointer to an integer that will receive the resolved namespace hash.

This method resolves a namespace prefix to its corresponding URI by examining namespace declarations within the specified tag's hierarchical scope. The resolution process:

Walks up the tag hierarchy from the specified tag to the root.
Examines xmlns:prefix and xmlns attributes in each tag to find the declaration.
Returns the UID of the first matching namespace URI found.

This approach correctly handles nested namespace scopes and prefix redefinitions.

Error Codes

Okay	The prefix was successfully resolved.
NotFound	The specified tag was not found.
Search	The prefix could not be resolved in any accessible scope.
NullArgs	Required arguments were not specified correctly.

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 successfully serialised.
NotFound	The specified tag Index does not exist in the XML structure.
NoData	No information has been loaded into the XML object.
AllocMemory	Failed to allocate memory for the XML string result.
NullArgs	Required parameters were NULL or not properly specified.

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)

SetTagNamespace Set the namespace for a specific XML tag.

ERR xml::SetTagNamespace(OBJECTPTR Object, INT TagID, INT NamespaceID)

Parameter	Description
TagID	The unique identifier of the XML tag.
NamespaceID	The UID of the namespace to assign.

This method assigns a namespace to an XML tag using the namespace's UID.

Error Codes

Okay	The namespace was successfully assigned to the tag.
NotFound	The specified tag was not found.
NullArgs	Required arguments were not specified correctly.

SetVariable Stores a variable that can be referenced in XPath expressions.

ERR xml::SetVariable(OBJECTPTR Object, CSTRING Key, CSTRING Value)

Parameter	Description
Key	The name of the variable (case sensitive).
Value	The string value to store.

This method allows you to store key-value pairs that can be referenced in XPath expressions using the variable syntax $variableName. Variables are stored as strings and are made available during XPath evaluation.

Error Codes

Okay	Operation successful.
ReadOnly	The XML object is read-only.
NullArgs	The `Key` parameter was not specified.

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.
ReadOnly	The XML object is in read-only mode and cannot be modified.
NullArgs	Required parameters were NULL or not properly specified.

ValidateDocument Validate the XML document against the currently loaded schema.

ERR xml::ValidateDocument(OBJECTPTR Object)

This method performs structural and simple type validation of the document using the loaded XML Schema. The Result parameter returns 1 when the document conforms to the schema, otherwise 0.

Error Codes

Okay	Validation completed successfully.
Search	The schema does not define the root element present in the document.
NoData	The XML document does not contain any parsed tags.
NoSupport	No schema has been loaded for this XML object.
NullArgs	The Result parameter was not supplied.

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
XPVT::Boolean
XPVT::Date
XPVT::DateTime
XPVT::NodeSet
XPVT::Number
XPVT::String
XPVT::Time

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

Field	Type	Description
type	XPVT	Identifies the type of value stored
number_value	DOUBLE
string_value	std::string

XML Class

Data Loading and Parsing

Document Structure and Access

Not Supported

Structure

Actions

Methods

Performance Considerations

Data Integrity

Comparison with Deep Extraction

XMF Type

XMI Type

XMS Type

XPVT Type

XSF Type

XMLAttrib Structure

XMLTag Structure

XPathValue 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
NamespaceID	UINT	Hash of namespace URI or 0 for no namespace
Attribs	pf::vector<XMLAttrib>	Array of attributes for this tag
Children	pf::vector<XMLTag>	Array of child tags