xmlconf: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		Unit XMLConf provides the TXMLConfig component. It uses a TXMLDocument object to do the work of reading and writing the XMLfile, but descends directly from TComponent.
2	2
3	3		##### Disclaimer
4	4
5	5		This documentation is not authoritative, it is based on the usual process of (1) examining the source code (2) experimentation (3) pondering "I wonder if that is what the author had in mind ?"
6	6
7	7		## Configuration
8	8
9	9		##### property Filename: String (published)
10	10
11	11		The file name of the xml file. Setting the filename to a different name:
12	12
13	13		- Flushes the current xml file.
14	14		- Frees the xmldocument object
15	15		- If Filename exists and StartEmpty is false:
16	16		- A new xmldocument is created by reading the file, which must have the same root element as RootName otherwise an exception is raised.
17	17		- Otherwise, a new xmldocument object is created with root element RootName
18	18
19	19		I have not checked this by experiment, but it appears that an empty xmldocument is created (in memory) when the component is created, and this can be modified. However, it cannot be saved until it has a file name - there is no default file name - hence all modifications will inevitably be lost when the file name is set.
20	20
21	21		##### property StartEmpty: Boolean (published)
22	22
23	23		Controls whether an existing xmlfile is read from Filename.
24	24
25	25		- Default is false - an existing file is read.
26	26
27	27		##### property RootName: DOMString (published)
28	28
29	29		The name of the root element in the file. Must match the value in the file when an existing file is read.
30	30
31	31		- Default is 'CONFIG'. It is simplest to leave this alone unless you have a good reason to change it.
32	32
33	33		##### procedure Flush (public)
34	34
35	35		Writes the xml file - as long as there is a file name set.
36	36
37	37		##### procedure Clear (public)
38	38
39	39		Recreates the xmldocument as an empty document.
40	40
41	41		##### constructor Create(AOwner: TComponent) (public)
42	42
43	43		##### destructor Destroy (public)
44	44
45	45		## Working with keys and paths
46	46
47	47		XMLConfig maintains a "stack" of paths (as an array of widestrings). The overall path to an element might be
48	48
49		-	~~` <rootName>/key1/key2/key3/key4/value="some_value". `~~
	49	+	```text
	50	+	<rootName>/key1/key2/key3/key4/value="some_value".
	51	+	```
50	52
51	53		This would appear in the file
52	54
53		-	~~` <CONFIG><key1><key2><key3><key4 value="some_value"/></key3></key2></key1></CONFIG`~~
	55	+	```text
	56	+	<CONFIG><key1><key2><key3><key4 value="some_value"/></key3></key2></key1></CONFIG
	57	+	```
54	58
55	59		(neglecting any other elements). However, the path stack can contain paths, not just nodes, so it could be four elements deep as key1;key2; key3;key4, but just as well only two elements as key1/key2;key3/key4, or three elements as key1;key2/key3;key4.
56	60
57	61		Further, when reading or setting a value, a complete path can then be specified, so the path "stack" can be completely ignored and the full path (past RootName) specified for each value. Each value has an effective path, and the path stack is just a convenient way of getting to a specific effective path.
58	62
59	63		##### procedure OpenKey(const aPath: WideString) (public)
60	64
61	65		"Pushes" aPath onto the stack. If the effective path was \<RootName\>/key1, and aPath = key2/key3, after the call to OpenKey, the effective path is \<RootName\>/key1/key2/key3.
62	66
63	67		##### procedure CloseKey (public)
64	68
65	69		"Pops" the top path off the stack. Note that this is the last entered path, NOT the top element. Thus after the OpenKey example above followed by a CloseKey call, the stack reverts to \<RootName\>/key1, not \<RootName\>/key1/key2
66	70
67	71		##### procedure ResetKey (public)
68	72
69	73		Completely clears the stack. The effetive path reverts to \<RootName\>
70	74
71	75		## Setting, Getting and Deleting Values
72	76
73	77		All values are actually read and written as strings, with other overloaded types providing defined 'AsString' translations.
74	78
75	79		##### function GetValue(const APath: WideString; const ADefault: WideString): WideString (public)\
76	80		procedure SetValue(const APath: WideString; const AValue: WideString) (public)
77	81
78	82		Sets or Gets a string value from RootName/Effective_path_from_stack/APath. The path is created if it does not exist on Setting, and ADefault is returned if the path does not exist on Getting.
79	83
80	84		##### function GetValue(const APath: WideString; ADefault: Integer): Integer; (public)\
81	85		procedure SetValue(const APath: WideString; AValue: Integer); (public)
82	86
83	87		The integer values are converted to/from strings using IntToStr and strToIntDef
84	88
85	89		##### function GetValue(const APath: WideString; ADefault: Boolean): Boolean; (public)\
86	90		procedure SetValue(const APath: WideString; AValue: Boolean); (public)
87	91
88	92		The boolean values are stored as "True" or "False".
89	93
90	94		Warning - some other FCL/LCL XML components (eg those descended from TCustomPropertyStorage, such as TXMLPropStorage) store booleans using integer values, despite using XMLConifg as the storage component. This is, of course, only a problem if you use the same files from both components, or switch from one to the other during development, as I did.
91	95
92	96		##### procedure SetDeleteValue(const APath: WideString; const AValue, DefValue: WideString); (public)\
93	97		procedure SetDeleteValue(const APath: WideString; AValue, DefValue: Integer); (public)\
94	98		procedure SetDeleteValue(const APath: WideString; AValue, DefValue: Boolean); (public)
95	99
96	100		If AValue = DefValue, the element is deleted. Otherwise, it is set to AValue.
97	101
98	102		I have not used this, but presumably could be used to store eg values of properties with well defined defaults only when they were different from the defaults.
99	103
100	104		##### procedure DeletePath(const APath: WideString); (public)
101	105
102	106		Deletes everything beyond path APath
103	107
104	108		##### procedure DeleteValue(const APath: WideString); (public)
105	109
106	110		Deletes a value specified by APath. If APath does not specify a value , it does nothing
107	111
108	112		##### property Modified: Boolean read FModified; (public)
109	113
110	114		Allows you to see if the xmldocument has been modified, and hence, needs to be flushed. However, flush does nothing if the document is not modified, so it is easier just to call flush anyway.
111	115
112	116		## Example
113	117
114	118		The following sequence of instructions:
115	119
116		-	~~` XmlConfig1.Filename := FILE_NAME ; // reads the file if it already exists, but...`\~~
117		-	~~` XmlConfig1.Clear ; // if the file already exists, clear the data, we want to start from scratch`\~~
118		-	~~` XmlConfig1.SetValue ('L1/L2/L3', '333') ; // add a few data`\~~
119		-	~~` XmlConfig1.SetValue ('L1/L2/L4', '44') ;`\~~
120		-	~~` XmlConfig1.SetValue ('L1/L2/L3', '33') ; // this will overwrite the previous value`\~~
121		-	~~` XmlConfig1.OpenKey ('L1/L2') ; // from now on, all keys will be relative to L1/L2`\~~
122		-	~~` XmlConfig1.SetValue ('Lm', 'mm') ; // these will be added in L1/L2`\~~
123		-	~~` XmlConfig1.SetValue ('Lm/Ln', 'nn') ;`\~~
124		-	~~` XmlConfig1.SetValue ('/Lx/Ly', 'yy') ; // but because of the initial "/", this will be added to the root`\~~
125		-	~~` XmlConfig1.CloseKey ;`\~~
126		-	~~` XmlConfig1.SetValue ('L6/L7', '77') ; // L6 will be deleted`\~~
127		-	~~` XmlConfig1.SetValue ('L9', '99') ;`\~~
128		-	~~` XmlConfig1.SetValue ('L9/L99', '9999') ; // the previous L9 was an attibute, this one will be a node`\~~
129		-	~~` XmlConfig1.DeletePath ('L6') ;`\~~
130		-	~~` XmlConfig1.Flush ;`~~
	120	+	``` pascal
	121	+	XmlConfig1.Filename := FILE_NAME ; // reads the file if it already exists, but...
	122	+	XmlConfig1.Clear ; // if the file already exists, clear the data, we want to start from scratch
	123	+	XmlConfig1.SetValue ('L1/L2/L3', '333') ; // add a few data
	124	+	XmlConfig1.SetValue ('L1/L2/L4', '44') ;
	125	+	XmlConfig1.SetValue ('L1/L2/L3', '33') ; // this will overwrite the previous value
	126	+	XmlConfig1.OpenKey ('L1/L2') ; // from now on, all keys will be relative to L1/L2
	127	+	XmlConfig1.SetValue ('Lm', 'mm') ; // these will be added in L1/L2
	128	+	XmlConfig1.SetValue ('Lm/Ln', 'nn') ;
	129	+	XmlConfig1.SetValue ('/Lx/Ly', 'yy') ; // but because of the initial "/", this will be added to the root
	130	+	XmlConfig1.CloseKey ;
	131	+	XmlConfig1.SetValue ('L6/L7', '77') ; // L6 will be deleted
	132	+	XmlConfig1.SetValue ('L9', '99') ;
	133	+	XmlConfig1.SetValue ('L9/L99', '9999') ; // the previous L9 was an attibute, this one will be a node
	134	+	XmlConfig1.DeletePath ('L6') ;
	135	+	XmlConfig1.Flush ;
	136	+	```
131	137
132	138		will give this XML:
133	139
134		-	~~` <?xml version="1.0" encoding="utf-8"?>`\~~
135		-	~~` <CONFIG L9="99">`\~~
136		-	~~` <L1>`\~~
137		-	~~` <L2 L3="33" L4="44" Lm="mm">`\~~
138		-	~~` <Lm Ln="nn"/>`\~~
139		-	~~` </L2>`\~~
140		-	~~` </L1>`\~~
141		-	~~` <Lx Ly="yy"/>`\~~
142		-	~~` <L9 L99="9999"/>`\~~
143		-	~~` </CONFIG>`~~
	140	+	```text
	141	+	<?xml version="1.0" encoding="utf-8"?>
	142	+	<CONFIG L9="99">
	143	+	<L1>
	144	+	<L2 L3="33" L4="44" Lm="mm">
	145	+	<Lm Ln="nn"/>
	146	+	</L2>
	147	+	</L1>
	148	+	<Lx Ly="yy"/>
	149	+	<L9 L99="9999"/>
	150	+	</CONFIG>
	151	+	```
144	152
145	153		Note that the last item in the aPath parameter for SetValue is actually an attribute: XmlConfig1.SetValue ('L1/L2/L3', '333') actually sets attribute L3 for element L1/L2.
146	154
147	155		------------------------------------------------------------------------
148	156
149	157		## See also
150	158
151	159		- XMLConf/TXMLConf is provided by the [[fcl-xml]] package.
152	160
153	161		---
154	162		From the Free Pascal wiki, page "xmlconf", as it stood on 2022-01-02 after a change by FTurtle, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history