<?xml version="1.0" encoding="UTF-8"?>
<fpdoc-descriptions>
<package name="lazutils">
<!--
====================================================================
LazConfigStorage
====================================================================
-->
<module name="LazConfigStorage">
<short>
Defines various base classes for loading and saving configuration files.
</short>
<descr>
<p>
<file>lazconfigstorage.pas</file> is part of the <file>LazUtils</file> package.
</p>
<p>
Author: Mattias Gaertner
</p>
</descr>

<!-- unresolved external references -->
<element name="Classes"/>
<element name="SysUtils"/>
<element name="typinfo"/>
<element name="Laz_AVL_Tree"/>
<element name="LazLoggerBase"/>
<element name="AvgLvlTree"/>
<element name="LazStringUtils"/>

<element name="TConfigStorage">
<short>
Defines the base class for a configuration storage mechanism.
</short>
<descr>
<p>
<var>TConfigStorage</var> is a class used to create and maintain 
configuration information using an XML-based storage format. TConfigStorage 
is a base class; it contains abstract virtual methods which must be 
implemented in descendent class to provide memory- or file-based storage for 
its values.
</p>
<p>
TConfigStorage and descendent classes have a base path where its data is 
stored, and sub-paths and values for the data items in the storage. Path 
information uses an XPath-like notation which indicates where a given value 
is stored, and the name associated with the stored value.
</p>
<p>
For example:
</p>
<code>
'path/to/loginform'
'path/to/loginform/top'
'path/to/loginform/left'
'path/to/loginform/width'
'path/to/loginform/height'
</code>
<p>
Values can be specified using one of the native Pascal data types supported 
in the class, like:
</p>
<ul>
<li>String</li>
<li>Integer</li>
<li>Boolean</li>
<li>TStrings</li>
<li>TRect</li>
<li>TPoint</li>
<li>TPersistent</li>
</ul>
<p>
Methods are provided to get, set, or delete stored items using their path 
notation. Methods are also provided to read or write published property values to or from persistent objects using RTTI.
</p>
<p>
Do not create instances of TConfigStorage. Use of the descendent classes like 
TConfigMemStorage or TXMLConfigStorage.
</p>
</descr>
<seealso>
<link id="TConfigMemStorage"/>
<link id="#lcl.xmlpropstorage.TXMLConfigStorage">TXMLConfigStorage</link>
</seealso>
</element>

<element name="TConfigStorage.FPathStack">
<short>Contains a path history built using AppendBasePath.</short>
</element>

<element name="TConfigStorage.FCurrentBasePath">
<short>Member used to store the value in CurrentBasePath.</short>
</element>

<element name="TConfigStorage.GetFullPathValue">
<short>
Specifies a method used to get a value or its default from the specified fully-qualified path.
</short>
<descr>
<p>
Returns the value stored using the path and name in the APath argument. The 
value in ADefault is returned if APath is not found in the configuration 
storage. The overloaded variants allow the return and default values to be 
specified using String, Integer, or Boolean types.
</p>
<p>
GetFullPathValue is an abstract virtual method in TConfigStorage. It is 
implemented in a descendent class to use the storage mechanism for the class 
instance.
</p>
</descr>
<seealso/>
</element>
<element name="TConfigStorage.GetFullPathValue.Result">
<short>
Value in the configuration storage for the specified value type.
</short>
</element>
<element name="TConfigStorage.GetFullPathValue.APath">
<short>
Fully-qualified path to the value. Includes both the base path and the name for the item.
</short>
</element>
<element name="TConfigStorage.GetFullPathValue.ADefault">
<short>
Default value returned when APath is not found in the configuration storage.
</short>
</element>

<element name="TConfigStorage.SetFullPathValue">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.SetFullPathValue.APath">
<short/>
</element>
<element name="TConfigStorage.SetFullPathValue.AValue">
<short/>
</element>

<element name="TConfigStorage.SetDeleteFullPathValue">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.SetDeleteFullPathValue.APath">
<short/>
</element>
<element name="TConfigStorage.SetDeleteFullPathValue.AValue">
<short/>
</element>
<element name="TConfigStorage.SetDeleteFullPathValue.DefValue">
<short/>
</element>

<element name="TConfigStorage.DeleteFullPath">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.DeleteFullPath.APath">
<short/>
</element>

<element name="TConfigStorage.DeleteFullPathValue">
<short/>
<descr/>
<seealso/>
</element>

<element name="TConfigStorage.DeleteFullPathValue.APath">
<short/>
</element>

<element name="TConfigStorage.WriteProperty">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.WriteProperty.Path">
<short/>
</element>
<element name="TConfigStorage.WriteProperty.Instance">
<short/>
</element>
<element name="TConfigStorage.WriteProperty.PropInfo">
<short/>
</element>
<element name="TConfigStorage.WriteProperty.DefInstance">
<short/>
</element>
<element name="TConfigStorage.WriteProperty.OnlyProperty">
<short/>
</element>

<element name="TConfigStorage.ReadProperty">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.ReadProperty.Path">
<short/>
</element>
<element name="TConfigStorage.ReadProperty.Instance">
<short/>
</element>
<element name="TConfigStorage.ReadProperty.PropInfo">
<short/>
</element>
<element name="TConfigStorage.ReadProperty.DefInstance">
<short/>
</element>
<element name="TConfigStorage.ReadProperty.OnlyProperty">
<short/>
</element>

<element name="TConfigStorage.Create">
<short>
Constructor for the class instance.
</short>
<descr>
<remark>
Create has an empty implementation in TConfigStorage. Use one of the 
descendent classes which re-implements the constructor as needed for its 
storage mechanism.
</remark>
</descr>
<seealso/>
</element>
<element name="TConfigStorage.Create.Filename">
<short>File name where configuration data is stored.</short>
</element>
<element name="TConfigStorage.Create.LoadFromDisk">
<short>
<b>True</b> to load values from the specified file if it exists. <b>False</b> 
to create a new, empty storage.
</short>
</element>

<element name="TConfigStorage.Destroy">
<short>Destructor for the class instance.</short>
<descr>
<p>
<var>Destroy</var> is the overridden destructor for the class instance. It 
frees resources allocated for members in the class instance, and calls the 
inherited destructor.
</p>
</descr>
<seealso>
<link id="#rtl.system.TObject.Destroy">TObject.Destroy</link>
</seealso>
</element>

<element name="TConfigStorage.Clear">
<short>
Clears the content in the configuration storage.
</short>
<descr>
<p>
<var>Clear</var> is an abstract virtual method in TConfigStorage. It is 
implemented in descendent classes to provide a file- or memory-based 
storage mechanism.
</p>
</descr>
<seealso/>
</element>

<element name="TConfigStorage.GetValue">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.GetValue.Result">
<short/>
</element>
<element name="TConfigStorage.GetValue.APath">
<short/>
</element>
<element name="TConfigStorage.GetValue.ADefault">
<short/>
</element>
<element name="TConfigStorage.GetValue.ARect">
<short/>
</element>
<element name="TConfigStorage.GetValue.APoint">
<short/>
</element>
<element name="TConfigStorage.GetValue.List">
<short/>
</element>

<element name="TConfigStorage.SetValue">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.SetValue.APath">
<short/>
</element>
<element name="TConfigStorage.SetValue.AValue">
<short/>
</element>

<element name="TConfigStorage.SetDeleteValue">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.SetDeleteValue.APath">
<short/>
</element>
<element name="TConfigStorage.SetDeleteValue.AValue">
<short/>
</element>
<element name="TConfigStorage.SetDeleteValue.DefValue">
<short/>
</element>

<element name="TConfigStorage.DeletePath">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.DeletePath.APath">
<short/>
</element>

<element name="TConfigStorage.DeleteValue">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.DeleteValue.APath">
<short/>
</element>

<element name="TConfigStorage.CurrentBasePath">
<short/>
<descr/>
<seealso/>
</element>

<element name="TConfigStorage.ExtendPath">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.ExtendPath.Result">
<short/>
</element>
<element name="TConfigStorage.ExtendPath.APath">
<short/>
</element>

<element name="TConfigStorage.AppendBasePath">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.AppendBasePath.Path">
<short/>
</element>

<element name="TConfigStorage.UndoAppendBasePath">
<short/>
<descr/>
<seealso/>
</element>

<element name="TConfigStorage.WriteToDisk">
<short/>
<descr/>
<seealso/>
</element>

<element name="TConfigStorage.GetFilename">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.GetFilename.Result">
<short/>
</element>

<element name="TConfigStorage.WriteObject">
<short>
Stores property names and values in the specified object to the configuration 
storage.
</short>
<descr>
<p>
<var>WriteObject</var> is a method used to store names and values from the 
properties in the specified persistent object into the configuration storage.
</p>
<p>
<var>Path</var> contains the location in configuration storage where the 
property values are stored. It provides a unique location for the values 
stored in the method.
</p>
<p>
<var>Obj</var> is the <var>TPersistent</var> instance with the property 
values stored in the method.
</p>
<p>
WriteObject calls <var>WriteProperty</var> for each of the properties 
returned from the RTL <var>GetPropList</var> routine. Sub-paths representing 
each of the published properties in the object are created by calling the 
WriteProperty method.
</p>
<p>
WriteObject (and WriteProperty) rely on RTTI types and routines to get the 
values from the persistent object. As such, only published properties can be 
serialized; the FPC RTL does not provide RTTI type information for other 
protected or public visibility at this time. The properties must have getter and setter routines (read and write specifiers); otherwise, they are omitted from the serialized values.
</p>
<p>
Use the <var>OnlyProperty</var> argument to specify the name for a single 
property in Obj that should be written in the method. Otherwise, all 
properties are stored.
</p>
<p>
Use <var>ReadObject</var> to read values from a given path into a persistent 
object instance.
</p>
</descr>
<seealso>
<link id="TConfigStorage.WriteProperty"/>
<link id="TConfigStorage.ReadObject"/>
<link id="#rtl.classes.TPersistent">TPersistent</link>
<link id="#rtl.typinfo.GetPropList">GetPropList</link>
<link id="#rtl.typinfo.GetPropInfo">GetPropInfo</link>
<link id="#rtl.typinfo.TTypeData">TTypeData</link>
</seealso>
</element>
<element name="TConfigStorage.WriteObject.Path">
<short>
Path where property names and values from Obj are stored.
</short>
</element>
<element name="TConfigStorage.WriteObject.Obj">
<short>
Persistent object with properties stored in the method.
</short>
</element>
<element name="TConfigStorage.WriteObject.DefObject">
<short>
Persistent object with default values for the properties in Obj.
</short>
</element>
<element name="TConfigStorage.WriteObject.OnlyProperty">
<short>
Name for a single property that should be written in the method, instead of all properties.
</short>
</element>

<element name="TConfigStorage.ReadObject">
<short>
Reads names and values from the configuration storage into properties for the 
specified object instance.
</short>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.ReadObject.Path">
<short>
Path where the property names and values read in the method are stored.
</short>
</element>
<element name="TConfigStorage.ReadObject.Obj">
<short>
Persistent object where the values read in the method are stored.
</short>
</element>
<element name="TConfigStorage.ReadObject.DefObject">
<short>
Persistent object with the default values for properties updated in the 
method.
</short>
</element>
<element name="TConfigStorage.ReadObject.OnlyProperty">
<short>
Name for a single property value read and stored in Obj.
</short>
</element>

<element name="TConfigStorageClass">
<short/>
<descr/>
<seealso/>
</element>

<element name="TConfigMemStorageNode">
<short>
Implements a storage node used in a memory-based configuration storage.
</short>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorageNode.Name">
<short>
Name for the node.
</short>
</element>
<element name="TConfigMemStorageNode.Value">
<short>
Value for the node.
</short>
</element>

<element name="TConfigMemStorageNode.Parent">
<short>
Parent node in the tree structure where the current node is stored.
</short>
<descr/>
<seealso/>
</element>

<element name="TConfigMemStorageNode.Children">
<short>
Child nodes with names and values stored as sub-paths of the current node.
</short>
<descr/>
<seealso/>
</element>

<element name="TConfigMemStorageNode.ClearChilds">
<short>
Frees storage nodes allocated in Children.
</short>
<descr/>
<seealso/>
</element>

<element name="TConfigMemStorageNode.Create">
<short>
Constructor for the class instance.
</short>
<descr>
<p>
<var>Create</var> is the constructor for the class instance. It initializes values in the Parent and Name properties to the arguments passed to the constructor.
</p>
</descr>
<seealso/>
</element>
<element name="TConfigMemStorageNode.Create.AParent">
<short>
Node where the current node is stored as a child node.
</short>
</element>
<element name="TConfigMemStorageNode.Create.AName">
<short>
Name for the new storage node.
</short>
</element>

<element name="TConfigMemStorageNode.Destroy">
<short>
Destructor for the class instance.
</short>
<descr>
<p>
<var>Destroy</var> is the overridden destructor for the class instance. It 
calls <var>ClearChilds</var> to remove all storage nodes allocated in 
<var>Children</var>. It ensures the current class instance is removed from 
the <var>Parent</var> node (when assigned).
</p>
<p>
Destroy calls the inherited destructor prior to exiting from the method.
</p>
</descr>
<seealso/>
</element>

<element name="TConfigMemStorageModification">
<short>
Represents modification operations for configuration storage nodes.
</short>
<descr>
<p>
<var>TConfigMemStorageModification</var> is an enumerated type with values 
that represent modification operations performed for nodes in a memory-based 
configuration storage.
</p>
</descr>
<seealso/>
</element>
<element name="TConfigMemStorageModification.cmsmSet">
<short>
Represents a set or write operation.
</short>
</element>
<element name="TConfigMemStorageModification.cmsmGet">
<short>
Represents a get or read operation.
</short>
</element>
<element name="TConfigMemStorageModification.cmsmDelete">
<short>
Represents a delete operation for a storage node.
</short>
</element>
<element name="TConfigMemStorageModification.cmsmDeleteValue">
<short>
Represents a delete operation for the value in a storage node.
</short>
</element>

<element name="ConfigMemStorageFormatVersion">
<short>
Current version for the storage format used in configuration storage classes.
</short>
<descr/>
<seealso/>
</element>

<element name="TConfigMemStorage">
<short>
Implement a configuration storage class using in-memory storage for values in 
the class instance.
</short>
<descr/>
<seealso/>
</element>

<element name="TConfigMemStorage.CreateRoot">
<short>
Creates the root node used to store the values for the memory-based 
configuration storage.
</short>
<descr/>
<seealso/>
</element>

<element name="TConfigMemStorage.CreateChilds">
<short>
Creates the tree structure used to store child nodes in the configuration 
storage.
</short>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorage.CreateChilds.Node">
<short>
Memory-based storage node where the child nodes are stored.
</short>
</element>

<element name="TConfigMemStorage.Modify">
<short>
Stores a modified value to the specified path in the configuration storage.
</short>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorage.Modify.APath">
<short>
Path in the storage where the modified value is stored.
</short>
</element>
<element name="TConfigMemStorage.Modify.Mode">
<short>
Action performed in the modification.
</short>
</element>
<element name="TConfigMemStorage.Modify.AValue">
<short>
New value stored at the specified path in the storage.
</short>
</element>

<element name="TConfigMemStorage.DeleteFullPath">
<short/>
<descr/>
<seealso/>
</element>

<element name="TConfigMemStorage.DeleteFullPath.APath">
<short/>
</element>

<element name="TConfigMemStorage.DeleteFullPathValue">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorage.DeleteFullPathValue.APath">
<short/>
</element>

<element name="TConfigMemStorage.GetFullPathValue">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorage.GetFullPathValue.Result">
<short/>
</element>
<element name="TConfigMemStorage.GetFullPathValue.APath">
<short/>
</element>
<element name="TConfigMemStorage.GetFullPathValue.ADefault">
<short/>
</element>

<element name="TConfigMemStorage.SetDeleteFullPathValue">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorage.SetDeleteFullPathValue.APath">
<short/>
</element>
<element name="TConfigMemStorage.SetDeleteFullPathValue.AValue">
<short/>
</element>
<element name="TConfigMemStorage.SetDeleteFullPathValue.DefValue">
<short/>
</element>

<element name="TConfigMemStorage.SetFullPathValue">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorage.SetFullPathValue.APath">
<short/>
</element>
<element name="TConfigMemStorage.SetFullPathValue.AValue">
<short/>
</element>

<element name="TConfigMemStorage.Root">
<short>
TConfigMemStorageNode instance with the storage nodes are the configuration 
storage.
</short>
<descr/>
<seealso/>
</element>

<element name="TConfigMemStorage.GetFilename">
<short>
Re-implements the method used to get the file name where the configuration 
items are stored. Not used in TConfigMemStorage.
</short>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorage.GetFilename.Result">
<short>
Always returns an empty string ('') in TConfigMemStorage.
</short>
</element>

<element name="TConfigMemStorage.WriteToDisk">
<short>
Re-implements the method used to store the configuration items to disk.
</short>
<descr>
<p>
WriteToDisk raises an Exception with the message:
</p>
<code>
'TConfigMemStorage.WriteToDisk invalid operation'
</code>
</descr>
<seealso/>
</element>

<element name="TConfigMemStorage.Destroy">
<short>
Destructor for the class instance.
</short>
<descr>
<p>
Frees resources allocate to the Root storage node in the class instance. 
Calls the inherited destructor prior to exit.
</p>
</descr>
<seealso/>
</element>

<element name="TConfigMemStorage.Clear">
<short>
Clears the storage nodes in the memory-based configuration storage.
</short>
<descr>
<p>
Free resources allocated to the Root storage node in the class instance.
</p>
</descr>
<seealso/>
</element>

<element name="TConfigMemStorage.SaveToConfig">
<short>
Save the storage nodes to the specified path in another configuration 
storage class instance.
</short>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorage.SaveToConfig.Config">
<short/>
</element>
<element name="TConfigMemStorage.SaveToConfig.APath">
<short/>
</element>

<element name="TConfigMemStorage.LoadFromConfig">
<short>
Loads storage nodes from the specified path in another configuration storage 
class instance.
</short>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorage.LoadFromConfig.Config">
<short/>
</element>
<element name="TConfigMemStorage.LoadFromConfig.APath">
<short/>
</element>

<element name="TConfigMemStorage.WriteDebugReport">
<short>
Generates the content in the Root node in a format suitable for debugger 
output.
</short>
<descr/>
<seealso/>
</element>

<element name="LoadStringToStringTree">
<short>
Loads names and values in the specified path from a configuration storage 
instance to the specified Tree.
</short>
<descr/>
<seealso/>
</element>
<element name="LoadStringToStringTree.Config">
<short>
Configuration storage instance with the names and values loaded into the tree.
</short>
</element>
<element name="LoadStringToStringTree.Path">
<short>
Path with the item names and values loaded from Config.
</short>
</element>
<element name="LoadStringToStringTree.Tree">
<short>
String map where the names and values for configuration items stored in the routine.
</short>
</element>

<element name="SaveStringToStringTree">
<short/>
<descr/>
<seealso/>
</element>
<element name="SaveStringToStringTree.Config">
<short/>
</element>
<element name="SaveStringToStringTree.Path">
<short/>
</element>
<element name="SaveStringToStringTree.Tree">
<short/>
</element>

<element name="DateAsCfgStrFormat">
<short>
Default locale-independent format used for date values in DateToCfgStr.
</short>
<descr/>
<version>
Added in LazUtils version 3.0.
</version>
<seealso/>
</element>

<element name="DateTimeAsCfgStrFormat">
<short>
Default locale-independent format used for date/time values.
</short>
<descr/>
<version>
Added in LazUtils version 3.0.
</version>
<seealso/>
</element>

<element name="DateToCfgStr">
<short>
Returns a string representation for TDateTime value using the specified format.
</short>
<descr/>
<version>
Added in LazUtils version 3.0.
</version>
<seealso/>
</element>
<element name="DateToCfgStr.Result">
<short>
String with the date and/or time represented using the specified format.
</short>
</element>
<element name="DateToCfgStr.Date">
<short>
TDateTime value converted in the routine.
</short>
</element>
<element name="DateToCfgStr.AFormat">
<short>
Format for the date/time value. Default value is defined in the 
DateAsCfgStrFormat constant and represents the date part of the specified 
value.
</short>
</element>

<element name="CfgStrToDate">
<short>
Converts a string with a date/time value using the specified format to the 
TDateTime output value.
</short>
<descr/>
<version>
Added in LazUtils version 3.0.
</version>
<seealso/>
</element>
<element name="CfgStrToDate.Result">
<short>
<b>True</b> if the string was successfully converted to a TDateTIme value in 
the routine.
</short>
</element>
<element name="CfgStrToDate.s">
<short>
String with the date and/or time value converted in the routine.
</short>
</element>
<element name="CfgStrToDate.Date">
<short>
Returns the TDateTime value for the specified string, or an empty TDateTime 
value (0.0) when the routine returns <b>False</b>.
</short>
</element>
<element name="CfgStrToDate.AFormat">
<short>
Format used for the date/time value passed in the s argument.
</short>
</element>

<element name="CompareConfigMemStorageNames">
<short/>
<descr/>
<seealso/>
</element>
<element name="CompareConfigMemStorageNames.Result">
<short/>
</element>
<element name="CompareConfigMemStorageNames.p1">
<short/>
</element>
<element name="CompareConfigMemStorageNames.p2">
<short/>
</element>

<element name="CompareConfigMemStorageNodes">
<short/>
<descr/>
<seealso/>
</element>
<element name="CompareConfigMemStorageNodes.Result">
<short/>
</element>
<element name="CompareConfigMemStorageNodes.Node1">
<short/>
</element>
<element name="CompareConfigMemStorageNodes.Node2">
<short/>
</element>

<element name="ComparePCharWithConfigMemStorageNode">
<short/>
<descr/>
<seealso/>
</element>
<element name="ComparePCharWithConfigMemStorageNode.Result">
<short/>
</element>
<element name="ComparePCharWithConfigMemStorageNode.aPChar">
<short/>
</element>
<element name="ComparePCharWithConfigMemStorageNode.ANode">
<short/>
</element>

</module>
<!-- LazConfigStorage -->

</package>
</fpdoc-descriptions>
