Implements classes used to read and write configuration data files in XML format.

laz2_xmlcfg.pas contains classes, type and routines used to read and write configuration data files in XML format.

It is copied from the FreePascal Free Component Library (FCL) and adapted to use UTF-8 strings instead of WideStrings.

laz2_xmlcfg.pas is part of the LazUtils package.

Implements a class used to access and maintain an XML configuration data file.

TXMLConfig is a TComponent descendant used to store configuration data using XML format. TXMLConfig is a simpler mechanism for accessing the content in an XML document. It uses path specifiers to describe the hierarchy of elements and attribute values, instead of focusing on DOM nodes. See the TXMLConfig Path Syntax topic for more information about path specifiers in TXMLConfig.

TXMLConfig provides method used to get or set the value for a path specifier in the XML document. Overloaded methods are includes to handle values using String, Integer, Extended, TRect, or Boolean data types. See the Using TXMLConfig topic for more information about using TXMLConfig.

Creates a DOM element representing the root node in Document.

CreateConfigNode is a procedure used to create a DOM element for the root node (or document element) in the XML Document. CreateConfigNode ensures that Document is a valid TXMLDocument instance; it is created when not already assigned (contains Nil). A TDomElement is created (if needed) with the element name CONFIG; it is stored as the document element (root node) in Document.

CreateConfigNode is used in the implementation of various methods, and is called when Document has not been assigned.

Sets the default format settings used in the class instance.

InitFormatSettings is a procedure which sets the default format settings used in the class instance. InitFormatSettings updates an internal TFormatSettings member to the values returned by DefaultFormatSettings. It also specifies that the decimal separator is '.' (Period), and the thousands separator is ',' (Comma).

While this may not agree with format settings for some locales, it is the format expected in the XML data files for the class instance.

InitFormatSettings is called from the Create constructor.

Sets the value for the Filename property. New value for the property. Internal member with the TXMLDocument for the class instance.

Doc is a TXMLDocument member with the document instance used to store the XML content for the configuration file. The value in Doc is assigned in the Clear, SetFilename, or CreateConfigNode methods. It is checked in other methods to ensure that a valid XML document exists prior to performing Input/Output operations.

Use the FreeDoc method to free the XML document for the class instance.

The visibility for the Doc member is protected. Member used to indicate the configuration file has been modified. Member used to indicate that the data was created manually, and not loaded from a file or stream. Member used to store String content loaded into the configuration file. Not used/updated in the current implementation. Not used/updated in the current implementation. Member used to cache DOM nodes accessed using paths in the class instance. Signals that LCL component streaming has been completed.

Loaded is an overridden method in TXMLConfig used to perform actions needed when the component has finished loading during LCL component streaming. Loaded calls the inherited method. It calls SetFilename to load the XML configuration file data when the Filename property is assigned in the component.

Converts an extended value to its representation as a String. String representation for the Extended value. Extended value converted in the method. Converts the specified String value to an Extended data type.

StrToExtended converts the specified String value to its representation as an Extended data type.

ADefault contains the default value used in the method when the string is empty or contains an invalid representation for an Extended data type. StrToExtended calls the StrToFloatDef routine to convert the string value using the format settings for the class.

StrToExtended is used in the implementation of the GetExtendedValue method.

Extended value converted in the method. String converted to an Extended value. Default value used when no value can be derived from the string. Gets the number of bytes needed to store a value using the specified RTTI type. Number of bytes needed for a value of the specified type. Pointer to the RTTI type information for a given value. Gets the string representation for the specified value as the specified type. String with the value for the specified type. Untyped parameter with the value converted to a string in the method. Pointer to the RTTI type for the specified value. Converts the specified string value to a value using the specified type. The return value is overloaded in StringToValueWithTypeInfo. Returns True if the value is successfully converted to the type in APTypeInfo. Returns a string with the converted value in an overloaded variant. String with the value converted to the specified type in the method. Pointer to the RTTI type information for the converted value. Untyped output parameter with the value converted to the specified type. Reads the XML content from the specified file into a TXMLDocument instance.

ReadXMLFile is a procedure used to read the XML content in AFilename into the TXMLDocument instance returned in ADoc. ReadXMLFile calls InvalidatePathCache to remove cached DOM nodes in the class instance. ReadXMLFile calls the ReadXMLFile method in the Laz2_XMLRead unit to load the file content into the XML document instance.

Use ReadFromStream to load the XML content in the class from a TStream instance.

Use WriteXMLFile or WriteToStream to store the XML content for the class instance.

ReadXMLFile . XML document with the content loaded in the method. File name containing the XML content for the configuration file. Writes XML configuration data in Document to the specified file name.

WriteXMLFile is a procedure used to write the XML content in the Document property to the file specified in AFilename. WriteXMLFile calls the WriteXMLFile routine in LazUtils to write the XML content using the WriteFlags defined in the class instance. The InvalidateFileStateCache routine is called to invalidate a file cache entry for the specified file name.

Use WriteToSteam to store the XML content in Document to a TStream instance.

Document with the XML content written in the method. File name where the XML content is stored. Frees the TXMLDocument instance for the XML configuration file.

FreeDoc is a procedure used to free the TXMLDocument instance used in the Document property. FreeDoc calls InvalidatePathCache to remove all cached DOM nodes from the Document. FreeAndNil is used to free the object instance and to set the value for the member to Nil.

FreeDoc is used in the implementation of various methods like Destroy, Clear, ReadFromStream, and SetFilename.

Ensures a DOM node is present in the internal cache for the class instance.

SetPathNodeCache is a procedure used to ensure that the DOM node with the specified position and name is present in the node cache for the class instance. SetPathNodeCache adjusts the length of the internal node cache when needed to accommodate a new DOM node. InvalidateCacheTilEnd is called to refresh the cache when the Node is not found starting at the specified position.

SetPathNodeCache is used in the implementation of the InternalFindNode method.

Position in the cache to start looking for the specified DOM node. DOM node to locate in the internal cache. DOM node name to locate in the cache. Gets a cached DOM node starting at the specified position in the cache.

GetCachedPathNode is an overloaded TDomNode function used to get the document element at the specified position in the cached DOM nodes for the Document. GetCachedPathNode is used in the implementation of the InternalFindNode method.

DOM node with the specified name, or Nil when the cache is invalid. Position in the cache for the initial DOM node in the search. Node name located in the cache. Removes DOM nodes from the internal cache starting at the specified ordinal position.

InvalidateCacheTilEnd iterates over the TNodeCache items in PathNodeCache stating at the position in StartIndex, and sets the node references to Nil to invalidate the DOM node in the cache.

InvalidateCacheTilEnd is used in the implementation of the InvalidatePathCache, SetPathNodeCache, and FindChildNode methods.

Initial position in the cache affected in the method. Searches for the DOM node with the specified path, and updates the node cache.

InternalFindNode is a TDOMNode function used to locate the node stored at the path specified in Document. InternalFindNode ensures that the node cache for the class is updated to include the TDOMNode at APath when it is accessed in the method. It also ensures that all element nodes for the specifier in APath are included in the cache as well. The FindChildNode method is used to locate TDOMNodes in the hierarchy. When CreateNodes is True, any missing DOM nodes in the hierarchy are created.

InternalFindNode is used in the implementation of the GetValue, SetValue, GetListItemCount, DeletePath, and FindNode methods.

DOM node located for the specified path. Path specifier for the DOM node. Length of the path specifier. Indicates if missing DOM nodes in Document are created. Removes the specified node and all of its children from the Document.

InternalCleanNode ensures that the specified DOM node is removed from the Document, both as a parent or child node in the element tree. InternalCleanNode calls InvalidatePathCache to reflect the change in the Document, and sets the value in Modified to True.

No actions are performed in the method when Node is unassigned (contains Nil).

InternalCleanNode is used in the implementation of the DeletePath and DeleteValue methods.

DOM Node to remove from the Document. Finds (and optionally caches) a child node starting at the specified index position using the specified XPath node name and position.

FindChildNode is a TDOMNode function used to retrieve (and optionally cache) a DOM node which matches the XPATH expression in AName.

PathIndex contains the ordinal position for the first child node examined in the list of child nodes. It is a 0-based value.

AName can contain the name for a child and and a predicate with the index position in the list of nodes. For example: 'NodeName[4]'. Please note that positions in XPATH start at 1 instead of 0 as used in Pascal.

Child DOM node which matches the expression and position indicated in the function arguments. Position for the first child node in the list of nodes examined in the method. XPATH expression which indicates the node name and the predicate which indicates the position for the selected child node. True if cache entries are created for the node(s) which match the arguments to the function. Constructor for the class instance.

Create is the overloaded, overridden constructor for the class instance.

Calling Create with the AFilename argument causes the XML content in the specified Filename to be loaded into the class instance. The variant that specifies an owner simply sets the default values in ReadFlags, WriteFlags, and its internal format settings.

Alternate constructors, like CreateClean and CreateWithSource, are provided to create an empty XML configuration file or to load its content from a String variable.

Owner of the class instance. File with the XML content loaded in the class instance. Alternate constructor used to create the class without reading existing XML content in the specified file.

CreateClean is an alternate constructor for the class instance. CreateClean sets an internal flag to indicate that the XML content in AFilename is not automatically loaded when the value in the Filename property is assigned. This ensures that the class instance is "clean" (has no XML content).

CreateClean calls an overloaded variant of Create using AFilename as an argument. The value in Modified is set to True if the specified file exists in the cache for the local file system.

File name where XML content will be stored. Alternate constructor used to create the class using the XML content specified in Source.

CreateWithSource is an alternate constructor used to create the class instance and load the XML content specified in the Source argument. CreateWithSource sets an internal member used for the XML content in Source. CreateWithSource calls the CreateClean method to initialize the class instance.

File name where XML configuration data will be stored. String with the XML content loaded in the class instance. Destructor for the class instance.

Destroy is the overridden destructor for the class instance. Destroy ensures that a TXMLDocument instance in the Document property is written to disk and freed before the object instance is destroyed. Destroy calls the inherited destructor.

Removes existing XML content in the Document property.

Clear is a procedure used to remove existing XML content in the Document property. Clear calls FreeDoc to free the Document instance, and re-creates the member along with its CONFIG document element.

Clear is used in the implementation of the ReadFromStream method.

Forces the XML content for the configuration file to be written to Filename.

Flush is a procedure which forces the XML content in Document to be written to the file specified in Filename. Flush uses the value in the Modified property to determine if the content in Document has been altered.

Flush calls the WriteXMLFile method to store Document to the required Filename. The value in Modified is set to False when the Document has been written to the local file system.

No actions are performed in the method when Modified is False, or when Filename contains an empty string ('').

Flush is used in the implementation of methods like Destroy and SetFilename.

Reads the XML content in Document from the specified stream instance.

ReadFromStream is a procedure used to read the XML content for the Document from the TStream instance in S. ReadFromStream calls FreeDoc to ensure that any existing XML content in the configuration file is discarded prior to loading values from the stream.

ReadFromStream calls the ReadXMLFile routine in the Laz2_XMLRead unit to load the XML content. If Document was not assigned in ReadXMLFile, the Clear method is called to create a Document with the correct default values.

Use ReadXMLFile to read XML content from a file on the local file system.

Use WriteToStream or WriteXMLFile to store XML content in the Document property to a stream or file.

ReadXMLFile TStream instance with the XML content read in the method. Writes the XML content for the configuration file to the specified stream instance.

WriteToStream is a procedure used to write the XML content for the configuration file to the TStream instance specified in S. WriteToStream checks the Document property to ensure that a valid TXMLDocument instance has been assigned to the member. When Document is unassigned (contains Nil), the CreateConfigNode method is called to allocate a document instance with the required CONFIG document element.

The WriteXMLFile routine in the Laz2_XMLWrite unit is called to store the XML document to the TStream specified in S using the WriteFlags for the class instance.

WriteXMLFile TStream instance where the XML content in Document is stored in the method. Gets the value from the DOM node at the specified path in the XML configuration file.

GetValue is an overloaded function used to get the value stored in a DOM node at the path specified in APath. Overloaded variants are provided to return String, Integer, Int64, Boolean, and TRect data types. Other variants allow the arguments to be represented as various data types including untyped constants.

APath contain the path specifier that represents the hierarchy of elements and attributes in Document where the value is stored. See TXMLConfig Path Syntax for details about path specifiers.

ADefault contains the default value returned when the DOM node does not have any content representing a value.

ARect is the TRect output parameter used to return the value in the overloaded method.

Use GetExtendedValue to get the value for a DOM node as an Extended (or Float) data type.

Value for the Node at the specified path. Path to locate in the Document. Default value used when the DOM node has no content. TRect with the value for the DOM node. Returns the value for a set or enumeration element as the type specified in APTypeInfo. Pointer to the RTTI type information for the value. Gets the value for a DOM node at the specified path as an extended data type.

GetExtendedValue is an Extended function used to get the value for a DOM node at the specified path as an Extended data type. GetExtendedValue is similar to the method; in fact it calls GetValue to retrieve the value for the DOM node in APath. It calls StrToExtended to convert the node value to the Extended data type used as the return value.

Use ADefault to specify the default value used in the method when the DOM node does not contain any content (or value).

Extended value for the specified DOM node. Path to the DOM node examined in the method. Default value used when the DOM node has no content. Sets the value in a DOM node at the specified path.

SetValue is an overloaded procedure used to set the value in the DOM node located at the path specified in APath. AValue contains the content stored in the specified DOM node. Overloaded variants of the method are provided where AValue is either a String, Int64, or Boolean data type. The String variant of the method is called to store the various value types in a DOM node.

Use SetExtendedValue to store an Extended data type in a specified DOM node.

Path to the DOM node updated in the method. Value to store in the specified DOM node. Pointer to the RTTI type information for the value. Updates or removes the value at the specified path

SetDeleteValue is an overloaded method used to update or remove the node at the path specified in APath. The AValue and DefValue arguments determine whether the node is updated, or removed by calling DeletePath. When AValue and DefValue are equal, this indicates the node value is the default or unassigned value for the node and DeletePath is called to remove the node at APath. Otherwise, SetValue is called to store AValue to the node path.

The overloaded variants allow the AValue and DefValue arguments to contain various data types including String, Int64, Boolean, TRect, or untyped constants.

Path specifier for the value affected in the method. Value to store at the specified path. Value which indicates the path should be removed instead of updated. Pointer to the RTTI type information for the value / default value. Sets the value in the DOM node at the specified path using an extended data type.

SetExtendedValue is a procedure used to set the value in the DOM node at the specified path to the value in the Extended data type.

APath contains the path specifier which describes the hierarchy of elements and attributes to the value. See TXMLConfig Path Syntax for details about path specifiers. AValue contains the Extended data type stored at the specified path.

SetExtendedValue is similar to the method; in fact, it calls SetValue to store the string representation of AValue prepared using ExtendedToStr.

Path to the DOM node updated in the method. Value stored in the specified DOM node. Updates or removes the Extended value at the specified path. Path specifier to the node affected in the method. Value stored at the specified path. Value which indicates the node should be removed instead of updated. Deletes the DOM node at the specified path in the Document.

DeletePath is a procedure used to delete the DOM node at the specified path in the Document. APath contains the path specifier that describes the hierarchy of elements and attributes needed to access the DOM node. See TXMLConfig Path Syntax for details about path specifiers.

DeletePath calls InternalFindNode to get the node removed in the method. The node is removed from its parent DOM node, and the value in Modified is set to True. The InvalidatePathCache method is called to reflect the change in the Document. InternalCleanNode is called to ensure that the node is removed from the parent DOM node in Document.

No actions are performed in the method when a node for the specified path cannot be located, or the node does not have a parent node (it is the root node in the Document). Path specifier for the DOM node to locate in the Document. Deletes the value stored in the DOM node at the specified path.

DeleteValue is a procedure used to remove the value for a DOM node stored at the path specified in APath. APath contains the path specifier which describes the hierarchy of elements and attributes needed to access the DOM node. See TXMLConfig Path Syntax for details about path specifiers.

DeleteValue calls the FindNode method to get the DOM node updated in the method.

No actions are performed in the method when a node cannot be found with the specified path. Path to the DOM node affected in the method. Retrieves the DOM node with the specified path.

FindNode is a TDOMNode function used to retrieve the DOM node stored at the path specified in APath in the Document instance. FindNode calls InternalFindNode to locate the DOM node used as the return value for the method.

APath contains the path specifier used to locate the DOM node. It contains the hierarchy of elements and attributes needed to access the DOM node, as described in TXMLConfig Path Syntax.

PathHasValue indicates if APath includes a specifier for the attribute where the value is stored. When PathHasValue is True, the trailing path identifier (for the attribute name) is removed from APath. Otherwise, the value in APath is used in its unmodified state.

FindNode is used in the implementation of the DeleteValue, GetChildCount, HasPath, and HasChildPaths methods.

DOM node stored at the specified path. Path to the DOM node retrieve in the method. Indicates if the path is checked for a value. Indicates if a DOM node exists for the specified path. True when a DOM node exists with the specified path. Path examined in the method. Indicates if the DOM node has content representing the value. Indicates if the DOM node at the specified path has child nodes. TDOMNode.HasChildNodes True when the specified path has child nodes in the Document. Path to the DOM node examined in the method. Gets the number of child nodes used in the DOM node at the specified path. GetChildCount Number of child nodes in the specified DOM node. Path to the DOM node examined in the method. Indicates if the specified list was written using the format from a previous LazUtils version.

In a previous LazUtils version, a Count value was written to indicate the number of items in the list. The return value is True if an entry named "Count" is found in APath with a value other than -1.

True when the path includes a Count value. Path the values examined in the method. Gets the number of values with the specified name found in the given path.

GetListItemCount is an Integer function used to get the number of values with the name in AItemName found on the path in APath.

ALegacyList indicates whether the list includes a "Count" value from a previous LazUtils version. When ALegacyList is True, the "Count" value is used (or 0 as the default). When set to False, a list of XML nodes is retrieved from APath with the name in AItemName. The length of the resulting list node list is used as the return value, or 0 when no XML nodes are found with the specified name.

Number of items in the list identified by APath. Path the XML nodes for the list. Name for the list items in APath. True when the Count value from an older LazUtils version is used. Gets the path specifier used to access a list item at the specified position.

GetListItemXPath is a String class function used to get the path specifier used to access a list item at the specified position in the Document. The return value contains the path specifier constructed for the list item. For example:


'item0'
'item1'
'item[0]'

Path specifier for the list item at the specified position. Name for the list item. Position for the list item. Indicates that array-style notation (with square brackets) is not used when True. Indicates if positions in the list start at 1 instead of 0. Sets the value for the Count element in a legacy version of the class.

SetListItemCount is a method used to store a Count element with the number of list items in APath. No actions are performed in the method when ALegacyList is set to False; the Count tag is not written or maintained in newer versions of the class.

SetListItemCount adds or updates the Count element to use the value in ACount. SetListItemCount deletes the Count element if its value is 0 (zero).

Path to the XML node where the list is stored. Value for the Count element written in the method. True the Count element from an older LazUtils version is used. Indicates if the XML content in the class has been modified.

Modified is a Boolean property used to indicate if the XML content in Document has been altered since it was loaded or created. The value in Modified is updated in methods like CreateClean, Flush, SetValue, DeletePath, DeleteValue, and InternalCleanNode.

Removes cached DOM nodes for paths in the XML configuration file.

InvalidatePathCache is a procedure used to invalidate all of the cached references to DOM nodes used in the class instance. InvalidatePathCache calls the InvalidateCacheTilEnd method starting at position 0 in the internal array of DOM nodes used for the cache.

InvalidatePathCache is used in the implementation of methods like: DeletePath, ReadXMLFile, FreeDoc, InternalCleanNode, and SetFilename.

File name used to read or write the XML content in the class instance.

Filename is a String property which specifies the file name on the local file system where the content for the XML configuration file is stored. Changing the value in Filename causes the DOM node cache to be cleared by calling the InvalidatePathCache method.

If Document contains a valid TXMLDocument instance, the Flush method is called to write any pending changes to disk. The FreeDoc method is called to re-initialize the Document instance. The XML content in Document is then reloaded using the file or string content as required.

No actions are performed in the method when the value in Filename is assigned as the component is loaded using the LCL streaming mechanism. XML document used for the class instance.

Document is a read-only TXMLDocument property which contains the XML content in the configuration file. Document is a hierarchical sequence of DOM nodes which represent the paths and values for configuration data. DOM nodes are added and deleted in Document using a path specifier which represents the hierarchical structure for the XML content. See the TXMLConfig Path Syntax topic for more information about path specifiers in TXMLConfig.

The TXMLDocument instance in Document is created and freed in methods like Clear, FreeDoc, CreateConfigNode, and SetFilename.

TXMLReaderFlags for the XML configuration file.

ReadFlags is a TXMLReaderFlags property which represents the options enabled when reading the XML content for the configuration file. Values in ReadFlags are passed as an argument in ReadFromStream and ReadXMLFile to routines used to read the XML content.

The set in ReadFlags is initialized in the Create constructor to the following enumeration values:

xrfAllowLowerThanInAttributeValue
xrfAllowSpecialCharsInAttributeValue

See TXMLReaderFlags for a description of enumeration values and their meanings.

TXMLWriteFlags for the XML configuration file.

WriteFlags is a TXMLWriteFlags property which represents the options enabled when writing the XML content for the configuration file. Values in WriteFlags are passed as an argument in WriteToSteam and WriteXMLFile to routines used to write the XML content.

The set in WriteFlags is initialized in the Create constructor to the following enumeration values:

xwfSpecialCharsInAttributeValue

See TXMLWriterFlags for a description of enumeration values and their meanings.

Implements an XML configuration file with RTTI support.

TRttiXMLConfig is a TXMLConfig descendant which implements support for reading and writing objects and their property values using RTTI (Run-Time Type Information). TRttiXMLConfig extends the ancestor class to include methods used to read and write objects, or just specific properties, using path specifiers supported in the class. See the TXMLConfig Path Syntax topic for more information about path specifiers in TXMLConfig.

Type information provided by RTTI (Run-Time Type Information) is used to determine the value and formatting used for supported data types. Supported RTTI type kinds include:

tkChar
tkWChar
tkSString
tkLString
tkAString
tkInteger
tkFloat
tkEnumeration
tkSet
tkBool
tkClass

Properties must be implemented with both getter and setter procedures to be available for use in TRttiXMLConfig. Properties which do not use both types of procedure are ignored. Writes a property value from an object to the specified path in the XML Document. Path to the DOM node where property values are stored. Object instance with property value examined in the method. RTTI property information used to get the value written in the method. Object instance used to provide a default value for the property. List of property names included in the process; all properties are included when omitted. Stores the value for the specified path to a property in an object instance. Path where the value is stored in the Document. Object instance where the value is stored. RTTI property information for the update property. Object instance with the default value for the property. List of property names included in the process; all properties are included when omitted. Stores property values from an object to the specified path in the document. Path used as a container for property values from the object. Object instance with property values written in the method. Object instance with the default values for the properties. List of property names included in the process, or all properties when omitted. Stores property values from the specified path to an object instance. Path with the property values loaded into the object in the method. Object instance where property values are stored. Object instance with default values used for properties in the method. List of property names included in the process, or all properties when omitted. Compares the names for the specified DOM nodes.

CompareDomNodeNames is an Integer function used to compare the pointers to DOM nodes specified in DOMNode1 and DOMNode2. CompareDomNodeNames calls CompareStr to examine the names in the pointers. The return value contains the relative sort order for the node names as determined in the CompareStr routine.

CompareDomNodeNames is the routine passed as an argument to MergeSortLen in the TNodeCache.RefreshChildren method.

Relative sort order for the specified node pointers. Pointer to a DOM node examined in the routine. Pointer to a DOM node examined in the routine. Using TXMLConfig.

What is TXMLConfig

TXMLConfig provides a simple mechanism for storing and retrieving values in an XML file. It is intended for use with configuration setting and option values. It is also used as the ancestor for an RTTI-enabled version which store values for object properties using the facilities provided by Run-Time Type Information (RTTI).

Using TXMLConfig is easier than building DOM nodes, child nodes, and attribute values in a TXMLDocument instance. This ease of use is made possible by its use of path specifiers to describe the hierarchy of elements and attributes in the XML document. See TXMLConfig Path Syntax for a description of the path specifier syntax.

Path specifiers are passed as arguments to the GetValue and SetValue methods which read and write values in the XML document. The methods are overloaded to support the use of String, Integer, Boolean, and TRect data types in the value.

Creating Instances of TXMLConfig

Various constructors are available in the class to create TXMLConfig instances. Specifically, they are the Create, CreateClean, and CreateWithSource methods. CreateClean allows an empty XML document to be created that is ultimately stored in the specified file name. CreateWithSource creates an XML document with content specified in a String argument passed to the constructor.

Use the Filename property to change the file name on the local file system where the XML document is stored. Use the Modified property to determine if the XML content in the document has been altered since it was created or loaded.

Loading and Saving XML Content

If the XML document was created was a destination file name, it can be written to disk using the Flush method. TXMLConfig includes other methods that can be used to read or write the XML content in the document to/from a specific file name, or to a TStream instance. Used the ReadXMLFile and WriteXMLFile methods to read and write XML content to a file. Use ReadFromStream and WriteToSteam to read and write XML content using a TStream instance.


// load the content in an existing configuration file
ACfg := TXMLConfig.Create('/path/to/file.xml');


//create an empty XML configuration file
ACfg := TXMLConfig.CreateClean('/path/to/file.xml');


//create an XML configuration file with the specified content, same as CreateClean
ACfg := TXMLConfig.CreateWithSource('/path/to/file.xml', '<CONFIG></CONFIG>');


// stores changes to disk
ACfg.Flush;


// write XML content to a different file
ACfg.WriteXMLFile('/another/path/to/file.xml');


// write XML content to a stream
AStream := TStream.Create;
ACfg.WriteToSteam(AStream);


ACfg := TXMLConfig.CreateClean('myappconfig.xml');
ACfg.SetValue('settings/backup/path', './backup');
ACfg.SetValue('settings/backup/enabled', True);
ACfg.SetValue('settings/spellcheck/enabled', False);

if ACfg.Modified then ACfg.Flush;
ACfg.Free;

The myappconfig.xml file contains the following:


<?xml version="1.0" encoding="UTF-8"?>
<CONFIG>
  <settings>
    <backup path="./backup" enabled="True"/>
    <spellcheck enabled="False"/>
  </settings>
</CONFIG>

TXMLConfig Path Syntax.

Path specifiers in TXMLConfig are used to get or set a value in the XML configuration file. Its syntax describes the hierarchy of elements and attributes needed to access a value in the XML document. It consists of a relative path to a DOM node and an attribute name where the value is stored.

The path specifier should NOT include a root node (or document element name); that is assumed to be a DOM node with the name "CONFIG". Use of the root node in the specifier is invalid in TXMLConfig.

Element and attributes names in the hierarchy are separated by the '/' (Forward Slash) character. The final identifier in the path specifier is the attribute name where a value is stored in the XML document.

Lists or arrays of elements can be read /written using a path specifier that includes notation which indicates the ordinal position of the element. For example:


ACfg.SetValue('list/items/item[0]/name', 'itemA');
ACfg.SetValue('list/items/item[0]/value', 'valueA');
ACfg.SetValue('list/items/item[1]/name', 'itemB');
ACfg.SetValue('list/items/item[1]/value', 'valueB');
ACfg.SetValue('list/items/item[2]/name', 'itemC');
ACfg.SetValue('list/items/item[2]/value', 'valueC');

Results in the following XML content:


<list>
  <items>
    <item name="itemA" value="valueA"/>
    <item name="itemB" value="valueB"/>
    <item name="itemC" value="valueC"/>
  </items>
</list>

There is no overloaded variant of the SetValue method which handles writing a TRect data type in the current implementation. You must write the Top, Left, Right, and Bottom coordinates as separate calls to SetValue using the desired path. Contrary to suggestions in source code comments, the syntax used for path specifiers in TXMLConfig is not fully XPath-compatible.