libconfig.html

Revision 1304, 136.5 kB (checked in by ppalmers, 14 years ago)
more forgotten files

Line
1	<html lang="en">
2	<head>
3	<title>libconfig</title>
4	<meta http-equiv="Content-Type" content="text/html">
5	<meta name="description" content="libconfig">
6	<meta name="generator" content="makeinfo 4.8">
7	<link title="Top" rel="top" href="#Top">
8	<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
9	<meta http-equiv="Content-Style-Type" content="text/css">
10	<style type="text/css"><!--
11	pre.display { font-family:inherit }
12	pre.format { font-family:inherit }
13	pre.smalldisplay { font-family:inherit; font-size:smaller }
14	pre.smallformat { font-family:inherit; font-size:smaller }
15	pre.smallexample { font-size:smaller }
16	pre.smalllisp { font-size:smaller }
17	span.sc { font-variant:small-caps }
18	span.roman { font-family:serif; font-weight:normal; }
19	span.sansserif { font-family:sans-serif; font-weight:normal; }
20	--></style>
21	</head>
22	<body>
23	<h1 class="settitle">libconfig</h1>
24	<hr noshade size=6 color="black">
25	<div align=right>A Library For Processing Structured Configuration Files<br>
26	Version 1.3<br>
27	6 April 2008</div>
28	<br><br><br><br>
29	<font size=+1>Mark A. Lindner</font>
30	<hr size=3 noshade color="black">
31	<br><br>
32
33	<div class="contents">
34	<h2>Table of Contents</h2>
35	<ul>
36	<li><a name="toc_Top" href="#Top">libconfig</a>
37	<li><a name="toc_Introduction" href="#Introduction">1 Introduction</a>
38	<ul>
39	<li><a href="#Why-Another-Configuration-File-Library_003f">1.1 Why Another Configuration File Library?</a>
40	<li><a href="#Using-the-Library-from-a-C-Program">1.2 Using the Library from a C Program</a>
41	<li><a href="#Using-the-Library-from-a-C_002b_002b-Program">1.3 Using the Library from a C++ Program</a>
42	<li><a href="#Multithreading-Issues">1.4 Multithreading Issues</a>
43	<li><a href="#Compiling-Using-pkg_002dconfig">1.5 Compiling Using pkg-config</a>
44	</li></ul>
45	<li><a name="toc_Configuration-Files" href="#Configuration-Files">2 Configuration Files</a>
46	<ul>
47	<li><a href="#Settings">2.1 Settings</a>
48	<li><a href="#Groups">2.2 Groups</a>
49	<li><a href="#Arrays">2.3 Arrays</a>
50	<li><a href="#Lists">2.4 Lists</a>
51	<li><a href="#Integer-Values">2.5 Integer Values</a>
52	<li><a href="#64_002dbit-Integer-Values">2.6 64-bit Integer Values</a>
53	<li><a href="#Floating-Point-Values">2.7 Floating Point Values</a>
54	<li><a href="#Boolean-Values">2.8 Boolean Values</a>
55	<li><a href="#String-Values">2.9 String Values</a>
56	<li><a href="#Comments">2.10 Comments</a>
57	</li></ul>
58	<li><a name="toc_The-C-API" href="#The-C-API">3 The C API</a>
59	<li><a name="toc_The-C_002b_002b-API" href="#The-C_002b_002b-API">4 The C++ API</a>
60	<li><a name="toc_Configuration-File-Grammar" href="#Configuration-File-Grammar">5 Configuration File Grammar</a>
61	<li><a name="toc_License" href="#License">Appendix A License</a>
62	<li><a name="toc_Function-Index" href="#Function-Index">Function Index</a>
63	<li><a name="toc_Type-Index" href="#Type-Index">Type Index</a>
64	<li><a name="toc_Concept-Index" href="#Concept-Index">Concept Index</a>
65	</li></ul>
66	</div>
67
68	<div class="node">
69	<p><hr>
70	<a name="Top"></a>
71	Next: <a rel="next" accesskey="n" href="#Introduction">Introduction</a>,
72	Up: <a rel="up" accesskey="u" href="#dir">(dir)</a>
73
74	</div>
75
76	<!-- node-name, next, previous, up -->
77	<h2 class="unnumbered">libconfig</h2>
78
79	<ul class="menu">
80	<li><a accesskey="1" href="#Introduction">Introduction</a>
81	<li><a accesskey="2" href="#Configuration-Files">Configuration Files</a>
82	<li><a accesskey="3" href="#The-C-API">The C API</a>
83	<li><a accesskey="4" href="#The-C_002b_002b-API">The C++ API</a>
84	<li><a accesskey="5" href="#Configuration-File-Grammar">Configuration File Grammar</a>
85	<li><a accesskey="6" href="#License">License</a>
86	<li><a accesskey="7" href="#Function-Index">Function Index</a>
87	<li><a accesskey="8" href="#Type-Index">Type Index</a>
88	<li><a accesskey="9" href="#Concept-Index">Concept Index</a>
89	</ul>
90
91	<div class="node">
92	<p><hr>
93	<a name="Introduction"></a>
94	Next: <a rel="next" accesskey="n" href="#Configuration-Files">Configuration Files</a>,
95	Previous: <a rel="previous" accesskey="p" href="#Top">Top</a>,
96	Up: <a rel="up" accesskey="u" href="#Top">Top</a>
97
98	</div>
99
100	<!-- node-name, next, previous, up -->
101	<ul class="menu">
102	<li><a accesskey="1" href="#Why-Another-Configuration-File-Library_003f">Why Another Configuration File Library?</a>
103	<li><a accesskey="2" href="#Using-the-Library-from-a-C-Program">Using the Library from a C Program</a>
104	<li><a accesskey="3" href="#Using-the-Library-from-a-C_002b_002b-Program">Using the Library from a C++ Program</a>
105	<li><a accesskey="4" href="#Multithreading-Issues">Multithreading Issues</a>
106	<li><a accesskey="5" href="#Compiling-Using-pkg_002dconfig">Compiling Using pkg-config</a>
107	</ul>
108
109	<h2 class="chapter">1 Introduction</h2>
110
111	<p><i>Libconfig</i> is a library for reading, manipulating, and writing
112	structured configuration files. The library features a fully
113	reentrant parser and includes bindings for both the C and C++
114	programming languages.
115
116	<p>The library runs on modern POSIX-compilant systems, such as Linux,
117	Solaris, and Mac OS X (Darwin), as well as on Microsoft Windows
118	2000/XP and later (with either Microsoft Visual Studio 2005 or later,
119	or the GNU toolchain via the MinGW environment).
120
121	<div class="node">
122	<p><hr>
123	<a name="Why-Another-Configuration-File-Library%3f"></a>
124	<a name="Why-Another-Configuration-File-Library_003f"></a>
125	Next: <a rel="next" accesskey="n" href="#Using-the-Library-from-a-C-Program">Using the Library from a C Program</a>,
126	Up: <a rel="up" accesskey="u" href="#Introduction">Introduction</a>
127
128	</div>
129
130	<!-- node-name, next, previous, up -->
131	<h3 class="section">1.1 Why Another Configuration File Library?</h3>
132
133	<p>There are several open-source configuration file libraries available
134	as of this writing. This library was written because each of those
135	libraries falls short in one or more ways. The main features of
136	<i>libconfig</i> that set it apart from the other libraries are:
137
138	<ul>
139	<li>A fully reentrant parser. Independent configurations can be parsed in concurrent threads at the same time.
140
141	<li>Both C <i>and</i> C++ bindings, as well as hooks to allow for the creation of wrappers in other languages.
142
143	<li>A simple, structured configuration file format that is more
144	readable and compact than XML and more flexible than the obsolete but
145	prevalent Windows “INI” file format.
146
147	<li>A low-footprint implementation (just 38K for the C library and 66K for the C++ library) that is suitable for memory-constrained systems.
148
149	<li>Proper documentation.
150
151	</ul>
152
153	<div class="node">
154	<p><hr>
155	<a name="Using-the-Library-from-a-C-Program"></a>
156	Next: <a rel="next" accesskey="n" href="#Using-the-Library-from-a-C_002b_002b-Program">Using the Library from a C++ Program</a>,
157	Previous: <a rel="previous" accesskey="p" href="#Why-Another-Configuration-File-Library_003f">Why Another Configuration File Library?</a>,
158	Up: <a rel="up" accesskey="u" href="#Introduction">Introduction</a>
159
160	</div>
161
162	<!-- node-name, next, previous, up -->
163	<h3 class="section">1.2 Using the Library from a C Program</h3>
164
165	<p>To use the library from C code, include the following preprocessor
166	directive in your source files:
167
168	<pre class="sp">
169
170	</pre>
171	<pre class="example"> #include <libconfig.h>
172	</pre>
173	<pre class="sp">
174
175	</pre>
176
177	To link with the library, specify `<samp><span class="samp">-lconfig</span></samp>' as an argument to the
178	linker.
179
180	<div class="node">
181	<p><hr>
182	<a name="Using-the-Library-from-a-C++-Program"></a>
183	<a name="Using-the-Library-from-a-C_002b_002b-Program"></a>
184	Next: <a rel="next" accesskey="n" href="#Multithreading-Issues">Multithreading Issues</a>,
185	Previous: <a rel="previous" accesskey="p" href="#Using-the-Library-from-a-C-Program">Using the Library from a C Program</a>,
186	Up: <a rel="up" accesskey="u" href="#Introduction">Introduction</a>
187
188	</div>
189
190	<!-- node-name, next, previous, up -->
191	<h3 class="section">1.3 Using the Library from a C++ Program</h3>
192
193	<p>To use the library from C++, include the following preprocessor
194	directive in your source files:
195
196	<pre class="sp">
197
198	</pre>
199	<pre class="example"> #include <libconfig.h++>
200	</pre>
201	<pre class="sp">
202
203	</pre>
204
205	Or, alternatively:
206
207	<pre class="sp">
208
209	</pre>
210	<pre class="example"> #include <libconfig.hh>
211	</pre>
212	<pre class="sp">
213
214	</pre>
215
216	The C++ API classes are defined in the namespace `<samp><span class="samp">libconfig</span></samp>', hence the
217	following statement may optionally be used:
218
219	<pre class="sp">
220
221	</pre>
222	<pre class="example"> using namespace libconfig;
223	</pre>
224	<pre class="sp">
225
226	</pre>
227
228	To link with the library, specify `<samp><span class="samp">-lconfig++</span></samp>' as an argument to
229	the linker.
230
231	<div class="node">
232	<p><hr>
233	<a name="Multithreading-Issues"></a>
234	Next: <a rel="next" accesskey="n" href="#Compiling-Using-pkg_002dconfig">Compiling Using pkg-config</a>,
235	Previous: <a rel="previous" accesskey="p" href="#Using-the-Library-from-a-C_002b_002b-Program">Using the Library from a C++ Program</a>,
236	Up: <a rel="up" accesskey="u" href="#Introduction">Introduction</a>
237
238	</div>
239
240	<!-- node-name, next, previous, up -->
241	<h3 class="section">1.4 Multithreading Issues</h3>
242
243	<p><i>Libconfig</i> is fully <dfn>reentrant</dfn>; the functions in the library
244	do not make use of global variables and do not maintain state between
245	successive calls. Therefore two independent configurations may be safely
246	manipulated concurrently by two distinct threads.
247
248	<p><i>Libconfig</i> is not <dfn>thread-safe</dfn>. The library is not aware of
249	the presence of threads and knows nothing about the host system's
250	threading model. Therefore, if an instance of a configuration is to be
251	accessed from multiple threads, it must be suitably protected by
252	synchronization mechanisms like read-write locks or mutexes; the
253	standard rules for safe multithreaded access to shared data must be
254	observed.
255
256	<p><i>Libconfig</i> is not <dfn>async-safe</dfn>. Calls should not be made into
257	the library from signal handlers, because some of the C library
258	routines that it uses may not be async-safe.
259
260	<p><i>Libconfig</i> is not guaranteed to be <dfn>cancel-safe</dfn>. Since it is
261	not aware of the host system's threading model, the library does not
262	contain any thread cancellation points. In most cases this will not be
263	an issue for multithreaded programs. However, be aware that some of
264	the routines in the library (namely those that read/write
265	configurations from/to files or streams) perform I/O using C library
266	routines which may potentially block; whether these C library routines
267	are cancel-safe or not depends on the host system.
268
269	<div class="node">
270	<p><hr>
271	<a name="Compiling-Using-pkg-config"></a>
272	<a name="Compiling-Using-pkg_002dconfig"></a>
273	Previous: <a rel="previous" accesskey="p" href="#Multithreading-Issues">Multithreading Issues</a>,
274	Up: <a rel="up" accesskey="u" href="#Introduction">Introduction</a>
275
276	</div>
277
278	<!-- node-name, next, previous, up -->
279	<h3 class="section">1.5 Compiling Using pkg-config</h3>
280
281	<p>On UNIX systems you can use the <i>pkg-config</i> utility (version 0.20
282	or later) to automatically select the appropriate compiler and linker
283	switches for <i>libconfig</i>. Ensure that the environment variable
284	`<samp><span class="samp">PKG_CONFIG_PATH</span></samp>' contains the absolute path to the
285	<samp><span class="file">lib/pkgconfig</span></samp> subdirectory of the libconfig installation. Then,
286	you can link C programs with <i>libconfig</i> as follows:
287
288	<pre class="example"> gcc `pkg-config --cflags libconfig` myprogram.c -o myprogram \
289	`pkg-config --libs libconfig`
290	</pre>
291	<pre class="sp">
292
293	</pre>
294
295	And similarly, for C++ programs:
296
297	<pre class="example"> g++ `pkg-config --cflags libconfig++` myprogram.cpp -o myprogram \
298	`pkg-config --libs libconfig++`
299	</pre>
300	<pre class="sp">
301
302	</pre>
303	Note the backticks in the above examples.
304
305	<div class="node">
306	<p><hr>
307	<a name="Configuration-Files"></a>
308	Next: <a rel="next" accesskey="n" href="#The-C-API">The C API</a>,
309	Previous: <a rel="previous" accesskey="p" href="#Introduction">Introduction</a>,
310	Up: <a rel="up" accesskey="u" href="#Top">Top</a>
311
312	</div>
313
314	<!-- node-name, next, previous, up -->
315	<ul class="menu">
316	<li><a accesskey="1" href="#Settings">Settings</a>
317	<li><a accesskey="2" href="#Groups">Groups</a>
318	<li><a accesskey="3" href="#Arrays">Arrays</a>
319	<li><a accesskey="4" href="#Lists">Lists</a>
320	<li><a accesskey="5" href="#Integer-Values">Integer Values</a>
321	<li><a accesskey="6" href="#g_t64_002dbit-Integer-Values">64-bit Integer Values</a>
322	<li><a accesskey="7" href="#Floating-Point-Values">Floating Point Values</a>
323	<li><a accesskey="8" href="#Boolean-Values">Boolean Values</a>
324	<li><a accesskey="9" href="#String-Values">String Values</a>
325	<li><a href="#Comments">Comments</a>
326	</ul>
327
328	<h2 class="chapter">2 Configuration Files</h2>
329
330	<p><i>Libconfig</i> supports structured, hierarchical configurations. These
331	configurations can be read from and written to files and manipulated
332	in memory.
333
334	<p><a name="index-setting-1"></a><a name="index-value-2"></a><a name="index-scalar-value-3"></a><a name="index-array-4"></a><a name="index-group-5"></a><a name="index-list-6"></a><a name="index-configuration-7"></a>A <dfn>configuration</dfn> consists of a group of <dfn>settings</dfn>, which
335	associate names with values. A <dfn>value</dfn> can be one of the
336	following:
337
338	<ul>
339	<li>A <dfn>scalar value</dfn>: integer, 64-bit integer, floating-point number, boolean,
340	or string
341	<li>An <dfn>array</dfn>, which is a sequence of scalar values, all of which must have the same type
342	<li>A <dfn>group</dfn>, which is a collection of settings
343	<li>A <dfn>list</dfn>, which is a sequence of values of any type, including other lists
344	</ul>
345
346	<p>Consider the following configuration file for a hypothetical GUI
347	application, which illustrates all of the elements of the configuration
348	file grammar.
349
350	<pre class="sp">
351
352	</pre>
353	<p><table class="cartouche" summary="cartouche" border="1"><tr><td>
354	<pre class="smallexample"> # Example application configuration file
355
356	version = "1.0";
357
358	application:
359	{
360	window:
361	{
362	title = "My Application";
363	size = { w = 640; h = 480; };
364	pos = { x = 350; y = 250; };
365	};
366
367	list = ( ( "abc", 123, true ), 1.234, ( /* an empty list */) );
368
369	books = ( { title = "Treasure Island";
370	author = "Robert Louis Stevenson";
371	price = 29.95;
372	qty = 5; },
373	{ title = "Snow Crash";
374	author = "Neal Stephenson";
375	price = 9.99;
376	qty = 8; } );
377
378	misc:
379	{
380	pi = 3.141592654;
381	bigint = 9223372036854775807L;
382	columns = [ "Last Name", "First Name", "MI" ];
383	bitmask = 0x1FC3;
384	};
385	};
386	</pre>
387	</td></tr></table>
388
389	<pre class="sp">
390
391	</pre>
392
393	<a name="index-path-8"></a>Settings can be uniquely identified within the configuration by a
394	<dfn>path</dfn>. The path is a dot-separated sequence of names, beginning
395	at a top-level group and ending at the setting itself. Each name in
396	the path is either the name of a setting; if the setting has no name
397	because it is an element in a list or array, an integer index in
398	square brackets can be used as the name.
399
400	<p>For example, in our hypothetical configuration file, the path to the
401	<code>x</code> setting is <code>application.window.pos.x</code>; the path to the
402	<code>version</code> setting is simply <code>version</code>; and the path to the
403	<code>title</code> setting of the second book in the <code>books</code> list is
404	<code>application.books.[1].title</code>.
405
406	<p>The datatype of a value is determined from the format of the value
407	itself. If the value is enclosed in double quotes, it is treated as a
408	string. If it looks like an integer or floating point number, it is
409	treated as such. If it is one of the values <code>TRUE</code>, <code>true</code>,
410	<code>FALSE</code>, or <code>false</code> (or any other mixed-case version of
411	those tokens, e.g., <code>True</code> or <code>FaLsE</code>), it is treated as a
412	boolean. If it consists of a comma-separated list of values enclosed
413	in square brackets, it is treated as an array. And if it consists of a
414	comma-separated list of values enclosed in parentheses, it is treated
415	as a list. Any value which does not meet any of these conditions is
416	considered invalid and results in a parse error.
417
418	<p>All names are case-sensitive. They may consist only of alphanumeric
419	characters, dashes (`<samp><span class="samp">-</span></samp>'), underscores (`<samp><span class="samp">_</span></samp>'), and asterisks
420	(`<samp><span class="samp">*</span></samp>'), and must begin with a letter or asterisk. No other
421	characters are allowed.
422
423	<p>In C and C++, integer, 64-bit integer, floating point, and string
424	values are mapped to the types <code>long</code>, <code>long long</code>,
425	<code>double</code>, and <code>const char *</code>, respectively. The boolean type
426	is mapped to <code>int</code> in C and <code>bool</code> in C++.
427
428	<p>The following sections describe the elements of the configuration file
429	grammar in additional detail.
430
431	<div class="node">
432	<p><hr>
433	<a name="Settings"></a>
434	Next: <a rel="next" accesskey="n" href="#Groups">Groups</a>,
435	Up: <a rel="up" accesskey="u" href="#Configuration-Files">Configuration Files</a>
436
437	</div>
438
439	<!-- node-name, next, previous, up -->
440	<h3 class="section">2.1 Settings</h3>
441
442	<p>A setting has the form:
443
444	<p><i>name</i> <b>=</b> <i>value</i> <b>;</b>
445
446	<p>or:
447
448	<p><i>name</i> <b>:</b> <i>value</i> <b>;</b>
449
450	<p>The trailing semicolon is required. Whitespace is not significant.
451
452	<p>The value may be a scalar value, an array, a group, or a list.
453
454	<div class="node">
455	<p><hr>
456	<a name="Groups"></a>
457	Next: <a rel="next" accesskey="n" href="#Arrays">Arrays</a>,
458	Previous: <a rel="previous" accesskey="p" href="#Settings">Settings</a>,
459	Up: <a rel="up" accesskey="u" href="#Configuration-Files">Configuration Files</a>
460
461	</div>
462
463	<!-- node-name, next, previous, up -->
464	<h3 class="section">2.2 Groups</h3>
465
466	<p>A group has the form:
467
468	<p><b>{</b>
469	<i>settings ...</i>
470	<b>}</b>
471
472	<p>Groups can contain any number of settings, but each setting must have
473	a unique name within the group.
474
475	<div class="node">
476	<p><hr>
477	<a name="Arrays"></a>
478	Next: <a rel="next" accesskey="n" href="#Lists">Lists</a>,
479	Previous: <a rel="previous" accesskey="p" href="#Groups">Groups</a>,
480	Up: <a rel="up" accesskey="u" href="#Configuration-Files">Configuration Files</a>
481
482	</div>
483
484	<!-- node-name, next, previous, up -->
485	<h3 class="section">2.3 Arrays</h3>
486
487	<p>An array has the form:
488
489	<p><b>[</b> <i>value</i><b>,</b> <i>value ...</i> <b>]</b>
490
491	<p>An array may have zero or more elements, but the elements must all be
492	scalar values of the same type.
493
494	<div class="node">
495	<p><hr>
496	<a name="Lists"></a>
497	Next: <a rel="next" accesskey="n" href="#Integer-Values">Integer Values</a>,
498	Previous: <a rel="previous" accesskey="p" href="#Arrays">Arrays</a>,
499	Up: <a rel="up" accesskey="u" href="#Configuration-Files">Configuration Files</a>
500
501	</div>
502
503	<!-- node-name, next, previous, up -->
504	<h3 class="section">2.4 Lists</h3>
505
506	<p>A list has the form:
507
508	<p><b>(</b> <i>value</i><b>,</b> <i>value ...</i> <b>)</b>
509
510	<p>A list may have zero or more elements, each of which can be a scalar
511	value, an array, a group, or another list.
512
513	<div class="node">
514	<p><hr>
515	<a name="Integer-Values"></a>
516	Next: <a rel="next" accesskey="n" href="#g_t64_002dbit-Integer-Values">64-bit Integer Values</a>,
517	Previous: <a rel="previous" accesskey="p" href="#Lists">Lists</a>,
518	Up: <a rel="up" accesskey="u" href="#Configuration-Files">Configuration Files</a>
519
520	</div>
521
522	<!-- node-name, next, previous, up -->
523	<h3 class="section">2.5 Integer Values</h3>
524
525	<p>Integers can be represented in one of two ways: as a series of one or
526	more decimal digits (`<samp><span class="samp">0</span></samp>' - `<samp><span class="samp">9</span></samp>'), with an optional leading
527	sign character (`<samp><span class="samp">+</span></samp>' or `<samp><span class="samp">-</span></samp>'); or as a hexadecimal value
528	consisting of the characters `<samp><span class="samp">0x</span></samp>' followed by a series of one or
529	more hexadecimal digits (`<samp><span class="samp">0</span></samp>' - `<samp><span class="samp">9</span></samp>', `<samp><span class="samp">A</span></samp>' - `<samp><span class="samp">F</span></samp>',
530	`<samp><span class="samp">a</span></samp>' - `<samp><span class="samp">f</span></samp>').
531
532	<div class="node">
533	<p><hr>
534	<a name="64-bit-Integer-Values"></a>
535	<a name="g_t64_002dbit-Integer-Values"></a>
536	Next: <a rel="next" accesskey="n" href="#Floating-Point-Values">Floating Point Values</a>,
537	Previous: <a rel="previous" accesskey="p" href="#Integer-Values">Integer Values</a>,
538	Up: <a rel="up" accesskey="u" href="#Configuration-Files">Configuration Files</a>
539
540	</div>
541
542	<!-- node-name, next, previous, up -->
543	<h3 class="section">2.6 64-bit Integer Values</h3>
544
545	<p>Long long (64-bit) integers are represented identically to integers,
546	except that an 'L' character is appended to indicate a 64-bit
547	value. For example, `<samp><span class="samp">0L</span></samp>' indicates a 64-bit integer value 0.
548
549	<div class="node">
550	<p><hr>
551	<a name="Floating-Point-Values"></a>
552	Next: <a rel="next" accesskey="n" href="#Boolean-Values">Boolean Values</a>,
553	Previous: <a rel="previous" accesskey="p" href="#g_t64_002dbit-Integer-Values">64-bit Integer Values</a>,
554	Up: <a rel="up" accesskey="u" href="#Configuration-Files">Configuration Files</a>
555
556	</div>
557
558	<!-- node-name, next, previous, up -->
559	<h3 class="section">2.7 Floating Point Values</h3>
560
561	<p>Floating point values consist of a series of one or more digits, one
562	decimal point, an optional leading sign character (`<samp><span class="samp">+</span></samp>' or
563	`<samp><span class="samp">-</span></samp>'), and an optional exponent. An exponent consists of the
564	letter `<samp><span class="samp">E</span></samp>' or `<samp><span class="samp">e</span></samp>', an optional sign character, and a series
565	of one or more digits.
566
567	<div class="node">
568	<p><hr>
569	<a name="Boolean-Values"></a>
570	Next: <a rel="next" accesskey="n" href="#String-Values">String Values</a>,
571	Previous: <a rel="previous" accesskey="p" href="#Floating-Point-Values">Floating Point Values</a>,
572	Up: <a rel="up" accesskey="u" href="#Configuration-Files">Configuration Files</a>
573
574	</div>
575
576	<!-- node-name, next, previous, up -->
577	<h3 class="section">2.8 Boolean Values</h3>
578
579	<p>Boolean values may have one of the following values: `<samp><span class="samp">true</span></samp>',
580	`<samp><span class="samp">false</span></samp>', or any mixed-case variation thereof.
581
582	<div class="node">
583	<p><hr>
584	<a name="String-Values"></a>
585	Next: <a rel="next" accesskey="n" href="#Comments">Comments</a>,
586	Previous: <a rel="previous" accesskey="p" href="#Boolean-Values">Boolean Values</a>,
587	Up: <a rel="up" accesskey="u" href="#Configuration-Files">Configuration Files</a>
588
589	</div>
590
591	<!-- node-name, next, previous, up -->
592	<h3 class="section">2.9 String Values</h3>
593
594	<p>String values consist of arbitrary text delimited by double
595	quotes. Literal double quotes can be escaped by preceding them with a
596	backslash: `<samp><span class="samp">\"</span></samp>'. The escape sequences `<samp><span class="samp">\\</span></samp>', `<samp><span class="samp">\f</span></samp>',
597	`<samp><span class="samp">\n</span></samp>', `<samp><span class="samp">\r</span></samp>', and `<samp><span class="samp">\t</span></samp>' are also recognized, and have the
598	usual meaning. No other escape sequences are currently supported.
599
600	<p>Adjacent strings are automatically concatenated, as in C/C++ source
601	code. This is useful for formatting very long strings as sequences of
602	shorter strings. For example, the following constructs are equivalent:
603
604	<ul>
605	<li><code>"The quick brown fox jumped over the lazy dog."</code>
606
607	<li><code>"The quick brown fox"</code> <br>
608	<code>" jumped over the lazy dog."</code>
609
610	<li><code>"The quick" /* comment */ " brown fox " // another comment</code> <br>
611	<code>"jumped over the lazy dog."</code>
612
613	</ul>
614
615	<div class="node">
616	<p><hr>
617	<a name="Comments"></a>
618	Previous: <a rel="previous" accesskey="p" href="#String-Values">String Values</a>,
619	Up: <a rel="up" accesskey="u" href="#Configuration-Files">Configuration Files</a>
620
621	</div>
622
623	<!-- node-name, next, previous, up -->
624	<h3 class="section">2.10 Comments</h3>
625
626	<p>Three types of comments are allowed within a configuration:
627
628	<ul>
629	<li>Script-style comments. All text beginning with a `<samp><span class="samp">#</span></samp>' character
630	to the end of the line is ignored.
631
632	<li>C-style comments. All text, including line breaks, between a starting
633	`<samp><span class="samp">/</span></samp>' sequence and an ending `<samp><span class="samp">/</span></samp>' sequence is ignored.
634
635	<li>C++-style comments. All text beginning with a `<samp><span class="samp">//</span></samp>' sequence to the
636	end of the line is ignored.
637
638	</ul>
639
640	<p>As expected, comment delimiters appearing within quoted strings are
641	treated as literal text.
642
643	<p>Comments are ignored when the configuration is read in, so they are
644	not treated as part of the configuration. Therefore if the
645	configuration is written back out to a stream, any comments that were
646	present in the original configuration will be lost.
647
648	<div class="node">
649	<p><hr>
650	<a name="The-C-API"></a>
651	Next: <a rel="next" accesskey="n" href="#The-C_002b_002b-API">The C++ API</a>,
652	Previous: <a rel="previous" accesskey="p" href="#Configuration-Files">Configuration Files</a>,
653	Up: <a rel="up" accesskey="u" href="#Top">Top</a>
654
655	</div>
656
657	<!-- node-name, next, previous, up -->
658	<h2 class="chapter">3 The C API</h2>
659
660	<p><a name="index-config_005ft-9"></a><a name="index-config_005fsetting_005ft-10"></a>This chapter describes the C library API. The type <i>config_t</i>
661	represents a configuration, and the type <i>config_setting_t</i> represents
662	a configuration setting.
663
664	<p>The boolean values <code>CONFIG_TRUE</code> and <code>CONFIG_FALSE</code> are
665	macros defined as <code>(1)</code> and <code>(0)</code>, respectively.
666
667	<div class="defun">
668	— Function: void <b>config_init</b> (<var>config_t * config<!-- /@w --></var>)<var><a name="index-config_005finit-11"></a></var><br>
669	— Function: void <b>config_destroy</b> (<var>config_t * config<!-- /@w --></var>)<var><a name="index-config_005fdestroy-12"></a></var><br>
670	<blockquote>
671	<p>These functions initialize and destroy the configuration object <var>config</var>.
672
673	<p><code>config_init()</code> initializes <var>config</var> as a new, empty
674	configuration.
675
676	<p><code>config_destroy()</code> destroys the configuration <var>config</var>,
677	deallocating all memory associated with the configuration, but not
678	including the <i>config_t</i> structure itself.
679
680	</blockquote></div>
681
682	<div class="defun">
683	— Function: int <b>config_read</b> (<var>config_t * config<!-- /@w -->, FILE * stream<!-- /@w --></var>)<var><a name="index-config_005fread-13"></a></var><br>
684	<blockquote>
685	<p>This function reads and parses a configuration from the given
686	<var>stream</var> into the configuration object <var>config</var>. It returns
687	<code>CONFIG_TRUE</code> on success, or <code>CONFIG_FALSE</code> on failure; the
688	<code>config_error_text()</code> and <code>config_error_line()</code>
689	functions, described below, can be used to obtain information about the
690	error.
691
692	</blockquote></div>
693
694	<div class="defun">
695	— Function: int <b>config_read_file</b> (<var>config_t * config<!-- /@w -->, const char * filename<!-- /@w --></var>)<var><a name="index-config_005fread_005ffile-14"></a></var><br>
696	<blockquote>
697	<p>This function reads and parses a configuration from the file named
698	<var>filename</var> into the configuration object <var>config</var>. It returns
699	<code>CONFIG_TRUE</code> on success, or <code>CONFIG_FALSE</code> on failure; the
700	<code>config_error_text()</code> and <code>config_error_line()</code> functions,
701	described below, can be used to obtain information about the error.
702
703	</blockquote></div>
704
705	<div class="defun">
706	— Function: void <b>config_write</b> (<var>const config_t * config<!-- /@w -->, FILE * stream<!-- /@w --></var>)<var><a name="index-config_005fwrite-15"></a></var><br>
707	<blockquote>
708	<p>This function writes the configuration <var>config</var> to the given
709	<var>stream</var>.
710
711	</blockquote></div>
712
713	<div class="defun">
714	— Function: int <b>config_write_file</b> (<var>config_t * config<!-- /@w -->, const char * filename<!-- /@w --></var>)<var><a name="index-config_005fwrite_005ffile-16"></a></var><br>
715	<blockquote>
716	<p>This function writes the configuration <var>config</var> to the file named
717	<var>filename</var>. It returns <code>CONFIG_TRUE</code> on success, or
718	<code>CONFIG_FALSE</code> on failure.
719
720	</blockquote></div>
721
722	<div class="defun">
723	— Function: const char * <b>config_error_text</b> (<var>const config_t * config<!-- /@w --></var>)<var><a name="index-config_005ferror_005ftext-17"></a></var><br>
724	— Function: int <b>config_error_line</b> (<var>const config_t * config<!-- /@w --></var>)<var><a name="index-config_005ferror_005fline-18"></a></var><br>
725	<blockquote>
726	<p>These functions, which are implemented as macros, return the text and
727	line number of the parse error, if one occurred during a call to
728	<code>config_read()</code> or <code>config_read_file()</code>. Storage for the
729	string returned by <code>config_error_text()</code> is managed by the
730	library and released automatically when the configuration is
731	destroyed; the string must not be freed by the caller.
732
733	</blockquote></div>
734
735	<div class="defun">
736	— Function: void <b>config_set_auto_convert</b> (<var>config_t *config<!-- /@w -->, int flag<!-- /@w --></var>)<var><a name="index-config_005fset_005fauto_005fconvert-19"></a></var><br>
737	— Function: int <b>config_get_auto_convert</b> (<var>const config_t *config<!-- /@w --></var>)<var><a name="index-config_005fget_005fauto_005fconvert-20"></a></var><br>
738	<blockquote>
739	<p><code>config_set_auto_convert()</code> enables number auto-conversion for
740	the configuration <var>config</var> if <var>flag</var> is non-zero, and disables
741	it otherwise. When this feature is enabled, an attempt to retrieve a
742	floating point setting's value into an integer (or vice versa), or
743	store an integer to a floating point setting's value (or vice versa)
744	will cause the library to silently perform the necessary conversion
745	(possibly leading to loss of data), rather than reporting failure. By
746	default this feature is disabled.
747
748	<p><code>config_get_auto_convert()</code> returns <code>CONFIG_TRUE</code> if number
749	auto-conversion is currently enabled for <var>config</var>; otherwise it
750	returns <code>CONFIG_FALSE</code>.
751
752	</blockquote></div>
753
754	<div class="defun">
755	— Function: long <b>config_lookup_int</b> (<var>const config_t * config<!-- /@w -->, const char * path<!-- /@w --></var>)<var><a name="index-config_005flookup_005fint-21"></a></var><br>
756	— Function: long long <b>config_lookup_int64</b> (<var>const config_t * config<!-- /@w -->, const char * path<!-- /@w --></var>)<var><a name="index-config_005flookup_005fint64-22"></a></var><br>
757	— Function: double <b>config_lookup_float</b> (<var>const config_t * config<!-- /@w -->, const char * path<!-- /@w --></var>)<var><a name="index-config_005flookup_005ffloat-23"></a></var><br>
758	— Function: int <b>config_lookup_bool</b> (<var>const config_t * config<!-- /@w -->, const char * path<!-- /@w --></var>)<var><a name="index-config_005flookup_005fbool-24"></a></var><br>
759	— Function: const char * <b>config_lookup_string</b> (<var>const config_t * config<!-- /@w -->, const char * path<!-- /@w --></var>)<var><a name="index-config_005flookup_005fstring-25"></a></var><br>
760	<blockquote>
761	<p>These functions locate the setting in the configuration <var>config</var>
762	specified by the path <var>path</var>. They return the value of the setting
763	on success, or a 0 or <code>NULL</code> value if the setting was not found or
764	if the type of the value did not match the type requested.
765
766	<p>Storage for the string returned by <code>config_lookup_string()</code> is
767	managed by the library and released automatically when the setting is
768	destroyed or when the setting's value is changed; the string must not
769	be freed by the caller.
770
771	</blockquote></div>
772
773	<div class="defun">
774	— Function: config_setting_t * <b>config_lookup</b> (<var>const config_t * config<!-- /@w -->, const char * path<!-- /@w --></var>)<var><a name="index-config_005flookup-26"></a></var><br>
775	<blockquote>
776	<p>This function locates the setting in the configuration <var>config</var>
777	specified by the path <var>path</var>. It returns a pointer to the
778	<code>config_setting_t</code> structure on success, or <code>NULL</code> if the
779	setting was not found.
780
781	</blockquote></div>
782
783	<div class="defun">
784	— Function: long <b>config_setting_get_int</b> (<var>const config_setting_t * setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fget_005fint-27"></a></var><br>
785	— Function: long long <b>config_setting_get_int64</b> (<var>const config_setting_t * setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fget_005fint64-28"></a></var><br>
786	— Function: double <b>config_setting_get_float</b> (<var>const config_setting_t * setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fget_005ffloat-29"></a></var><br>
787	— Function: int <b>config_setting_get_bool</b> (<var>const config_setting_t * setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fget_005fbool-30"></a></var><br>
788	— Function: const char * <b>config_setting_get_string</b> (<var>const config_setting_t * setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fget_005fstring-31"></a></var><br>
789	<blockquote>
790	<p>These functions return the value of the given <var>setting</var>. If the
791	type of the setting does not match the type requested, a 0 or
792	<code>NULL</code> value is returned. Storage for the string returned by
793	<code>config_setting_get_string()</code> is managed by the library and
794	released automatically when the setting is destroyed or when the
795	setting's value is changed; the string must not be freed by the
796	caller.
797
798	</blockquote></div>
799
800	<div class="defun">
801	— Function: int <b>config_setting_set_int</b> (<var>config_setting_t * setting<!-- /@w -->, long value<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fset_005fint-32"></a></var><br>
802	— Function: int <b>config_setting_set_int64</b> (<var>config_setting_t * setting<!-- /@w -->, long long value<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fset_005fint64-33"></a></var><br>
803	— Function: int <b>config_setting_set_float</b> (<var>config_setting_t * setting<!-- /@w -->, double value<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fset_005ffloat-34"></a></var><br>
804	— Function: int <b>config_setting_set_bool</b> (<var>config_setting_t * setting<!-- /@w -->, int value<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fset_005fbool-35"></a></var><br>
805	— Function: int <b>config_setting_set_string</b> (<var>config_setting_t * setting<!-- /@w -->, const char * value<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fset_005fstring-36"></a></var><br>
806	<blockquote>
807	<p>These functions set the value of the given <var>setting</var> to
808	<var>value</var>. On success, they return <code>CONFIG_TRUE</code>. If
809	the setting does not match the type of the value, they return
810	<code>CONFIG_FALSE</code>. <code>config_setting_set_string()</code> makes a copy
811	of the passed string <var>value</var>, so it may be subsequently freed or
812	modified by the caller without affecting the value of the setting.
813
814	</blockquote></div>
815
816	<div class="defun">
817	— Function: short <b>config_setting_get_format</b> (<var>config_setting_t * setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fget_005fformat-37"></a></var><br>
818	— Function: int <b>config_setting_set_format</b> (<var>config_setting_t * setting<!-- /@w -->, short format<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fset_005fformat-38"></a></var><br>
819	<blockquote>
820	<p>These functions get and set the external format for the setting <var>setting</var>.
821
822	<p><a name="index-SettingFormat-39"></a>
823	The <var>format</var> must be one of the constants
824	<code>CONFIG_FORMAT_DEFAULT</code> or <code>CONFIG_FORMAT_HEX</code>. All settings
825	support the <code>CONFIG_FORMAT_DEFAULT</code> format. The
826	<code>CONFIG_FORMAT_HEX</code> format specifies hexadecimal formatting for
827	integer values, and hence only applies to settings of type
828	<code>CONFIG_TYPE_INT</code> and <code>CONFIG_TYPE_INT64</code>. If <var>format</var>
829	is invalid for the given setting, it is ignored.
830
831	<p><code>config_setting_set_format()</code> returns <code>CONFIG_TRUE</code> on
832	success and <code>CONFIG_FALSE</code> on failure.
833
834	</blockquote></div>
835
836	<div class="defun">
837	— Function: config_setting_t * <b>config_setting_get_member</b> (<var>config_setting_t * setting<!-- /@w -->, const char * name<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fget_005fmember-40"></a></var><br>
838	<blockquote>
839	<p>This function fetches the child setting named <var>name</var> from the group
840	<var>setting</var>. It returns the requested setting on success, or
841	<code>NULL</code> if the setting was not found or if <var>setting</var> is not a
842	group.
843
844	</blockquote></div>
845
846	<div class="defun">
847	— Function: config_setting_t * <b>config_setting_get_elem</b> (<var>const config_setting_t * setting<!-- /@w -->, unsigned int idx<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fget_005felem-41"></a></var><br>
848	<blockquote>
849	<p>This function fetches the element at the given index <var>idx</var> in the
850	setting <var>setting</var>, which must be an array, list, or group. It returns the
851	requested setting on success, or <code>NULL</code> if <var>idx</var> is out of
852	range or if <var>setting</var> is not an array, list, or group.
853
854	</blockquote></div>
855
856	<div class="defun">
857	— Function: long <b>config_setting_get_int_elem</b> (<var>const config_setting_t * setting<!-- /@w -->, int idx<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fget_005fint_005felem-42"></a></var><br>
858	— Function: long long <b>config_setting_get_int64_elem</b> (<var>const config_setting_t * setting<!-- /@w -->, int idx<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fget_005fint64_005felem-43"></a></var><br>
859	— Function: double <b>config_setting_get_float_elem</b> (<var>const config_setting_t * setting<!-- /@w -->, int idx<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fget_005ffloat_005felem-44"></a></var><br>
860	— Function: int <b>config_setting_get_bool_elem</b> (<var>const config_setting_t * setting<!-- /@w -->, int idx<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fget_005fbool_005felem-45"></a></var><br>
861	— Function: const char * <b>config_setting_get_string_elem</b> (<var>const config_setting_t * setting<!-- /@w -->, int idx<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fget_005fstring_005felem-46"></a></var><br>
862	<blockquote>
863	<p>These functions return the value at the specified index <var>idx</var> in the
864	setting <var>setting</var>. If the setting is not an array or list, or if
865	the type of the element does not match the type requested, or if
866	<var>idx</var> is out of range, they return 0 or <code>NULL</code>. Storage for
867	the string returned by <code>config_setting_get_string_elem()</code> is
868	managed by the library and released automatically when the setting is
869	destroyed or when its value is changed; the string must not be freed
870	by the caller.
871	</p></blockquote></div>
872
873	<div class="defun">
874	— Function: config_setting_t * <b>config_setting_set_int_elem</b> (<var>config_setting_t * setting<!-- /@w -->, int idx<!-- /@w -->, long value<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fset_005fint_005felem-47"></a></var><br>
875	— Function: config_setting_t * <b>config_setting_set_int64_elem</b> (<var>config_setting_t * setting<!-- /@w -->, int idx<!-- /@w -->, long long value<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fset_005fint64_005felem-48"></a></var><br>
876	— Function: config_setting_t * <b>config_setting_set_float_elem</b> (<var>config_setting_t * setting<!-- /@w -->, int idx<!-- /@w -->, double value<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fset_005ffloat_005felem-49"></a></var><br>
877	— Function: config_setting_t * <b>config_setting_set_bool_elem</b> (<var>config_setting_t * setting<!-- /@w -->, int idx<!-- /@w -->, int value<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fset_005fbool_005felem-50"></a></var><br>
878	— Function: config_setting_t * <b>config_setting_set_string_elem</b> (<var>config_setting_t * setting<!-- /@w -->, int idx<!-- /@w -->, const char * value<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fset_005fstring_005felem-51"></a></var><br>
879	<blockquote>
880	<p>These functions set the value at the specified index <var>idx</var> in the
881	setting <var>setting</var> to <var>value</var>. If <var>idx</var> is negative, a
882	new element is added to the end of the array or list. On success,
883	these functions return a pointer to the setting representing the
884	element. If the setting is not an array or list, or if the setting is
885	an array and the type of the array does not match the type of the
886	value, or if <var>idx</var> is out of range, they return
887	<code>NULL</code>. <code>config_setting_set_string_elem()</code> makes a copy of
888	the passed string <var>value</var>, so it may be subsequently freed or
889	modified by the caller without affecting the value of the setting.
890	</p></blockquote></div>
891
892	<div class="defun">
893	— Function: config_setting_t * <b>config_setting_add</b> (<var>config_setting_t * parent<!-- /@w -->, const char * name<!-- /@w -->, int type<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fadd-52"></a></var><br>
894	<blockquote>
895	<p>This function adds a new child setting or element to the setting
896	<var>parent</var>, which must be a group, array, or list. If <var>parent</var>
897	is an array or list, the <var>name</var> parameter is ignored and may be
898	<code>NULL</code>.
899
900	<p>The function returns the new setting on success, or <code>NULL</code> if
901	<var>parent</var> is not a group, array, or list; or if there is already a
902	child setting of <var>parent</var> named <var>name</var>; or if <var>type</var> is
903	invalid.
904	</p></blockquote></div>
905
906	<div class="defun">
907	— Function: int <b>config_setting_remove</b> (<var>config_setting_t * parent<!-- /@w -->, const char * name<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fremove-53"></a></var><br>
908	<blockquote>
909	<p>This function removes and destroys the setting named <var>name</var> from
910	the parent setting <var>parent</var>, which must be a group. Any child
911	settings of the setting are recursively destroyed as well.
912
913	<p>The function returns <code>CONFIG_TRUE</code> on success. If <var>parent</var> is
914	not a group, or if it has no setting with the given name, it returns
915	<code>CONFIG_FALSE</code>.
916
917	</blockquote></div>
918
919	<div class="defun">
920	— Function: int <b>config_setting_remove_elem</b> (<var>config_setting_t * parent<!-- /@w -->, unsigned int idx<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fremove_005felem-54"></a></var><br>
921	<blockquote>
922	<p>This function removes the child setting at the given index <var>idx</var> from
923	the setting <var>parent</var>, which must be a group, list, or array. Any
924	child settings of the removed setting are recursively destroyed as
925	well.
926
927	<p>The function returns <code>CONFIG_TRUE</code> on success. If <var>parent</var> is
928	not a group, list, or array, or if <var>idx</var> is out of range, it returns
929	<code>CONFIG_FALSE</code>.
930
931	</blockquote></div>
932
933	<div class="defun">
934	— Function: config_setting_t * <b>config_root_setting</b> (<var>const config_t * config<!-- /@w --></var>)<var><a name="index-config_005froot_005fsetting-55"></a></var><br>
935	<blockquote>
936	<p>This function returns the root setting for the configuration
937	<var>config</var>. The root setting is a group.
938
939	</blockquote></div>
940
941	<div class="defun">
942	— Function: const char * <b>config_setting_name</b> (<var>const config_setting_t * setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fname-56"></a></var><br>
943	<blockquote>
944	<p>This function returns the name of the given <var>setting</var>, or
945	<code>NULL</code> if the setting has no name. Storage for the returned
946	string is managed by the library and released automatically when the
947	setting is destroyed; the string must not be freed by the caller.
948
949	</blockquote></div>
950
951	<div class="defun">
952	— Function: config_setting_t * <b>config_setting_parent</b> (<var>const config_setting_t * setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fparent-57"></a></var><br>
953	<blockquote>
954	<p>This function returns the parent setting of the given <var>setting</var>,
955	or <code>NULL</code> if <var>setting</var> is the root setting.
956
957	</blockquote></div>
958
959	<div class="defun">
960	— Function: int <b>config_setting_is_root</b> (<var>const config_setting_t * setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fis_005froot-58"></a></var><br>
961	<blockquote>
962	<p>This function returns <code>CONFIG_TRUE</code> if the given <var>setting</var> is
963	the root setting, and <code>CONFIG_FALSE</code> otherwise.
964
965	</blockquote></div>
966
967	<div class="defun">
968	— Function: int <b>config_setting_index</b> (<var>const config_setting_t * setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005findex-59"></a></var><br>
969	<blockquote>
970	<p>This function returns the index of the given <var>setting</var> within its
971	parent setting. If <var>setting</var> is the root setting, this function
972	returns -1.
973
974	</blockquote></div>
975
976	<div class="defun">
977	— Function: int <b>config_setting_length</b> (<var>const config_setting_t * setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005flength-60"></a></var><br>
978	<blockquote>
979	<p>This function returns the number of settings in a group, or the number of
980	elements in a list or array. For other types of settings, it returns
981	0.
982
983	</blockquote></div>
984
985	<div class="defun">
986	— Function: int <b>config_setting_type</b> (<var>const config_setting_t * setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005ftype-61"></a></var><br>
987	<blockquote>
988	<p>This function returns the type of the given <var>setting</var>. The return
989	value is one of the constants
990	<code>CONFIG_TYPE_INT</code>, <code>CONFIG_TYPE_INT64</code>, <code>CONFIG_TYPE_FLOAT</code>,
991	<code>CONFIG_TYPE_STRING</code>, <code>CONFIG_TYPE_BOOL</code>,
992	<code>CONFIG_TYPE_ARRAY</code>, <code>CONFIG_TYPE_LIST</code>, or <code>CONFIG_TYPE_GROUP</code>.
993
994	</blockquote></div>
995
996	<div class="defun">
997	— Function: int <b>config_setting_is_group</b> (<var>const config_setting_t * setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fis_005fgroup-62"></a></var><br>
998	— Function: int <b>config_setting_is_array</b> (<var>const config_setting_t * setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fis_005farray-63"></a></var><br>
999	— Function: int <b>config_setting_is_list</b> (<var>const config_setting_t * setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fis_005flist-64"></a></var><br>
1000	<blockquote>
1001	<p>These convenience functions, which are implemented as macros, test if
1002	the setting <var>setting</var> is of a given type. They return
1003	<code>CONFIG_TRUE</code> or <code>CONFIG_FALSE</code>.
1004
1005	</blockquote></div>
1006
1007	<div class="defun">
1008	— Function: int <b>config_setting_is_aggregate</b> (<var>const config_setting_t * setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fis_005faggregate-65"></a></var><br>
1009	— Function: int <b>config_setting_is_scalar</b> (<var>const config_setting_t * setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fis_005fscalar-66"></a></var><br>
1010	— Function: int <b>config_setting_is_number</b> (<var>const config_setting_t * setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fis_005fnumber-67"></a></var><br>
1011	<blockquote>
1012	<p>These convenience functions, which are implemented as macros, test if
1013	the setting <var>setting</var> is of an aggregate type (a group, array, or
1014	list), of a scalar type (integer, 64-bit integer, floating point,
1015	boolean, or string), and of a number (integer, 64-bit integer, or
1016	floating point), respectively. They return <code>CONFIG_TRUE</code> or
1017	<code>CONFIG_FALSE</code>.
1018
1019	</blockquote></div>
1020
1021	<div class="defun">
1022	— Function: unsigned int <b>config_setting_source_line</b> (<var>const config_setting_t * setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fsource_005fline-68"></a></var><br>
1023	<blockquote>
1024	<p>This function returns the line number of the configuration file or
1025	stream at which the setting <var>setting</var> was parsed. This information
1026	is useful for reporting application-level errors. If the setting was
1027	not read from a file or stream, or if the line number is otherwise
1028	unavailable, the function returns 0.
1029
1030	</blockquote></div>
1031
1032	<div class="defun">
1033	— Function: void <b>config_setting_set_hook</b> (<var>config_setting_t * setting<!-- /@w -->, void * hook<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fset_005fhook-69"></a></var><br>
1034	— Function: void * <b>config_setting_get_hook</b> (<var>const config_setting_t * setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fget_005fhook-70"></a></var><br>
1035	<blockquote>
1036	<p>These functions make it possible to attach arbitrary data to each
1037	setting structure, for instance a “wrapper” or “peer” object written in
1038	another programming language. The destructor function, if one has been
1039	supplied via a call to <code>config_set_destructor()</code>, will be called
1040	by the library to dispose of this data when the setting itself is
1041	destroyed. There is no default destructor.
1042
1043	</blockquote></div>
1044
1045	<div class="defun">
1046	— Function: void <b>config_set_destructor</b> (<var>config_t * config<!-- /@w -->, void (* destructor)(void *)<!-- /@w --></var>)<var><a name="index-config_005fset_005fdestructor-71"></a></var><br>
1047	<blockquote>
1048	<p>This function assigns the destructor function <var>destructor</var> for the
1049	configuration <var>config</var>. This function accepts a single <code>void
1050	*</code> argument and has no return value. See
1051	<code>config_setting_set_hook()</code> above for more information.
1052
1053	</blockquote></div>
1054
1055	<div class="node">
1056	<p><hr>
1057	<a name="The-C++-API"></a>
1058	<a name="The-C_002b_002b-API"></a>
1059	Next: <a rel="next" accesskey="n" href="#Configuration-File-Grammar">Configuration File Grammar</a>,
1060	Previous: <a rel="previous" accesskey="p" href="#The-C-API">The C API</a>,
1061	Up: <a rel="up" accesskey="u" href="#Top">Top</a>
1062
1063	</div>
1064
1065	<!-- node-name, next, previous, up -->
1066	<h2 class="chapter">4 The C++ API</h2>
1067
1068	<p><a name="index-Config-72"></a><a name="index-Setting-73"></a>This chapter describes the C++ library API. The class <code>Config</code>
1069	represents a configuration, and the class <code>Setting</code> represents a
1070	configuration setting. Note that by design, neither of these classes
1071	provides a public copy constructor or assignment operator. Therefore,
1072	instances of these classes may only be passed between functions via
1073	references or pointers.
1074
1075	<p><a name="index-ConfigException-74"></a>The library defines a group of exceptions, all of which extend the
1076	common base exception <code>ConfigException</code>.
1077
1078	<p><a name="index-SettingTypeException-75"></a>A <code>SettingTypeException</code> is thrown when the type of a setting's
1079	value does not match the type requested.
1080
1081	<p><a name="index-SettingNotFoundException-76"></a>A <code>SettingNotFoundException</code> is thrown when a setting is not found.
1082
1083	<p><a name="index-SettingNameException-77"></a>A <code>SettingNameException</code> is thrown when an attempt is made to add
1084	a new setting with a non-unique or invalid name.
1085
1086	<p><a name="index-ParseException-78"></a>A <code>ParseException</code> is thrown when a parse error occurs while
1087	reading a configuration from a stream.
1088
1089	<p><a name="index-FileIOException-79"></a>A <code>FileIOException</code> is thrown when an I/O error occurs while
1090	reading/writing a configuration from/to a file.
1091
1092	<p>The remainder of this chapter describes the methods for manipulating
1093	configurations and configuration settings.
1094
1095	<div class="defun">
1096	— Method on Config: <b>Config</b> ()<var><a name="index-Config-on-Config-80"></a></var><br>
1097	— Method on Config: <b>~Config</b> ()<var><a name="index-g_t_007eConfig-on-Config-81"></a></var><br>
1098	<blockquote>
1099	<p>These methods create and destroy <code>Config</code> objects.
1100
1101	</blockquote></div>
1102
1103	<div class="defun">
1104	— Method on Config: void <b>read</b> (<var>FILE * stream<!-- /@w --></var>)<var><a name="index-read-on-Config-82"></a></var><br>
1105	— Method on Config: void <b>write</b> (<var>FILE * stream<!-- /@w --></var>)<var><a name="index-write-on-Config-83"></a></var><br>
1106	<blockquote>
1107	<p>The <code>read()</code> method reads and parses a configuration from the given
1108	<var>stream</var>. A <code>ParseException</code> is thrown if a parse error occurs.
1109
1110	<p>The <code>write()</code> method writes the configuration to the given <var>stream</var>.
1111
1112	</blockquote></div>
1113
1114	<div class="defun">
1115	— Method on Config: void <b>readFile</b> (<var>const char * filename<!-- /@w --></var>)<var><a name="index-readFile-on-Config-84"></a></var><br>
1116	— Method on Config: void <b>writeFile</b> (<var>const char * filename<!-- /@w --></var>)<var><a name="index-writeFile-on-Config-85"></a></var><br>
1117	<blockquote>
1118	<p>The <code>readFile()</code> method reads and parses a configuration from the file
1119	named <var>filename</var>. A <code>ParseException</code> is thrown if a parse error occurs. A
1120	<code>FileIOException</code> is thrown if the file cannot be read.
1121
1122	<p>The <code>writeFile()</code> method writes the configuration to the file
1123	named <var>filename</var>. A <code>FileIOException</code> is thrown if the file cannot
1124	be written.
1125
1126	</blockquote></div>
1127
1128	<div class="defun">
1129	— Method on ParseException: const char * <b>getError</b> ()<var><a name="index-getError-on-ParseException-86"></a></var><br>
1130	— Method on ParseException: int <b>getLine</b> ()<var><a name="index-getLine-on-ParseException-87"></a></var><br>
1131	<blockquote>
1132	<p>If a call to <code>readFile()</code> or <code>read()</code> resulted in a
1133	<code>ParseException</code>, these methods can be called on the exception
1134	object to obtain the text and line number of the parse error. Storage
1135	for the string returned by <code>getError()</code> is managed by the
1136	library; the string must not be freed by the caller.
1137
1138	</blockquote></div>
1139
1140	<div class="defun">
1141	— Method on Config: void <b>setAutoConvert</b> (<var>bool flag</var>)<var><a name="index-setAutoConvert-on-Config-88"></a></var><br>
1142	— Method on Config: bool <b>getAutoConvert</b> ()<var><a name="index-getAutoConvert-on-Config-89"></a></var><br>
1143	<blockquote>
1144	<p><code>setAutoConvert()</code> enables number auto-conversion for the
1145	configuration if <var>flag</var> is <code>true</code>, and disables it
1146	otherwise. When this feature is enabled, an attempt to assign a
1147	floating point setting to an integer (or vice versa), or
1148	assign an integer to a floating point setting (or vice versa) will
1149	cause the library to silently perform the necessary conversion
1150	(possibly leading to loss of data), rather than throwing a
1151	<code>SettingTypeException</code>. By default this feature is disabled.
1152
1153	<p><code>getAutoConvert()</code> returns <code>true</code> if number auto-conversion
1154	is currently enabled for the configuration; otherwise it returns
1155	<code>false</code>.
1156
1157	</blockquote></div>
1158
1159	<div class="defun">
1160	— Method on Config: Setting & <b>getRoot</b> ()<var><a name="index-getRoot-on-Config-90"></a></var><br>
1161	<blockquote>
1162	<p>This method returns the root setting for the configuration, which is a group.
1163
1164	</blockquote></div>
1165
1166	<div class="defun">
1167	— Method on Config: Setting & <b>lookup</b> (<var>const std::string &path<!-- /@w --></var>)<var><a name="index-lookup-on-Config-91"></a></var><br>
1168	— Method on Config: Setting & <b>lookup</b> (<var>const char * path<!-- /@w --></var>)<var><a name="index-lookup-on-Config-92"></a></var><br>
1169	<blockquote>
1170	<p>These methods locate the setting specified by the path <var>path</var>. If
1171	the requested setting is not found, a <code>SettingNotFoundException</code> is
1172	thrown.
1173
1174	</blockquote></div>
1175
1176	<div class="defun">
1177	— Method on Config: bool <b>exists</b> (<var>const std::string &path<!-- /@w --></var>)<var><a name="index-exists-on-Config-93"></a></var><br>
1178	— Method on Config: bool <b>exists</b> (<var>const char *path<!-- /@w --></var>)<var><a name="index-exists-on-Config-94"></a></var><br>
1179	<blockquote>
1180	<p>These methods test if a setting with the given <var>path</var> exists in
1181	the configuration. They return <code>true</code> if the setting exists, and
1182	<var>false</var> otherwise. These methods do not throw exceptions.
1183
1184	</blockquote></div>
1185
1186	<div class="defun">
1187	— Method on Config: bool <b>lookupValue</b> (<var>const char *path<!-- /@w -->, bool &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-95"></a></var><br>
1188	— Method on Config: bool <b>lookupValue</b> (<var>const std::string &path<!-- /@w -->, bool &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-96"></a></var><br>
1189
1190	— Method on Config: bool <b>lookupValue</b> (<var>const char *path<!-- /@w -->, int &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-97"></a></var><br>
1191	— Method on Config: bool <b>lookupValue</b> (<var>const std::string &path<!-- /@w -->, int &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-98"></a></var><br>
1192
1193	— Method on Config: bool <b>lookupValue</b> (<var>const char *path<!-- /@w -->, unsigned int &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-99"></a></var><br>
1194	— Method on Config: bool <b>lookupValue</b> (<var>const std::string &path<!-- /@w -->, unsigned int &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-100"></a></var><br>
1195
1196	— Method on Config: bool <b>lookupValue</b> (<var>const char *path<!-- /@w -->, long &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-101"></a></var><br>
1197	— Method on Config: bool <b>lookupValue</b> (<var>const std::string &path<!-- /@w -->, long &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-102"></a></var><br>
1198
1199	— Method on Config: bool <b>lookupValue</b> (<var>const char *path<!-- /@w -->, long long &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-103"></a></var><br>
1200	— Method on Config: bool <b>lookupValue</b> (<var>const std::string &path<!-- /@w -->, long long &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-104"></a></var><br>
1201
1202	— Method on Config: bool <b>lookupValue</b> (<var>const char *path<!-- /@w -->, unsigned long &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-105"></a></var><br>
1203	— Method on Config: bool <b>lookupValue</b> (<var>const std::string &path<!-- /@w -->, unsigned long &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-106"></a></var><br>
1204
1205	— Method on Config: bool <b>lookupValue</b> (<var>const char *path<!-- /@w -->, float &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-107"></a></var><br>
1206	— Method on Config: bool <b>lookupValue</b> (<var>const std::string &path<!-- /@w -->, float &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-108"></a></var><br>
1207
1208	— Method on Config: bool <b>lookupValue</b> (<var>const char *path<!-- /@w -->, double &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-109"></a></var><br>
1209	— Method on Config: bool <b>lookupValue</b> (<var>const std::string &path<!-- /@w -->, double &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-110"></a></var><br>
1210
1211	— Method on Config: bool <b>lookupValue</b> (<var>const char path<!-- /@w -->, const char &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-111"></a></var><br>
1212	— Method on Config: bool <b>lookupValue</b> (<var>const std::string &path<!-- /@w -->, const char *&value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-112"></a></var><br>
1213
1214	— Method on Config: bool <b>lookupValue</b> (<var>const char *path<!-- /@w -->, std::string &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-113"></a></var><br>
1215	— Method on Config: bool <b>lookupValue</b> (<var>const std::string &path<!-- /@w -->, std::string &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-114"></a></var><br>
1216	<blockquote>
1217	<p>These are convenience methods for looking up the value of a setting
1218	with the given <var>path</var>. If the setting is found and is of an
1219	appropriate type, the value is stored in <var>value</var> and the method
1220	returns <code>true</code>. Otherwise, <var>value</var> is left unmodified and the
1221	method returns <var>false</var>. These methods do not throw exceptions.
1222
1223	<p>Storage for <i>const char *</i><!-- /@w --> values is managed by the library and
1224	released automatically when the setting is destroyed or when its value
1225	is changed; the string must not be freed by the caller. For safety and
1226	convenience, always assigning string values to a <code>std::string</code> is
1227	suggested.
1228
1229	<p>Since these methods have boolean return values and do not throw
1230	exceptions, they can be used within boolean logic expressions. The following
1231	example presents a concise way to look up three values at once and
1232	perform error handling if any of them are not found or are of the
1233	wrong type:
1234
1235	<pre class="sp">
1236
1237	</pre>
1238	<p><table class="cartouche" summary="cartouche" border="1"><tr><td>
1239	<pre class="example"> int var1;
1240	double var2;
1241	const char *var3;
1242
1243	if(config.lookupValue("values.var1", var1)
1244	&& config.lookupValue("values.var2", var2)
1245	&& config.lookupValue("values.var3", var3))
1246	{
1247	// use var1, var2, var3
1248	}
1249	else
1250	{
1251	// error handling here
1252	}
1253	</pre>
1254	</td></tr></table>
1255
1256	<p>This approach also takes advantage of the short-circuit evaluation rules
1257	of C++, i.e., if the first lookup fails (returning <code>false</code>), the
1258	remaining lookups are skipped entirely.
1259
1260	</blockquote></div>
1261
1262	<div class="defun">
1263	— Method on Setting: <b>operator bool()</b><var><a name="index-operator-bool_0028_0029-on-Setting-115"></a></var><br>
1264	— Method on Setting: <b>operator int()</b><var><a name="index-operator-int_0028_0029-on-Setting-116"></a></var><br>
1265	— Method on Setting: <b>operator unsigned int()</b><var><a name="index-operator-unsigned-int_0028_0029-on-Setting-117"></a></var><br>
1266	— Method on Setting: <b>operator long()</b><var><a name="index-operator-long_0028_0029-on-Setting-118"></a></var><br>
1267	— Method on Setting: <b>operator unsigned long()</b><var><a name="index-operator-unsigned-long_0028_0029-on-Setting-119"></a></var><br>
1268	— Method on Setting: <b>operator long long()</b><var><a name="index-operator-long-long_0028_0029-on-Setting-120"></a></var><br>
1269	— Method on Setting: <b>operator unsigned long long()</b><var><a name="index-operator-unsigned-long-long_0028_0029-on-Setting-121"></a></var><br>
1270	— Method on Setting: <b>operator float()</b><var><a name="index-operator-float_0028_0029-on-Setting-122"></a></var><br>
1271	— Method on Setting: <b>operator double()</b><var><a name="index-operator-double_0028_0029-on-Setting-123"></a></var><br>
1272	— Method on Setting: <b>operator const char *()</b><var><a name="index-operator-const-char-_002a_0028_0029-on-Setting-124"></a></var><br>
1273	— Method on Setting: <b>operator std::string()</b><var><a name="index-operator-std_003a_003astring_0028_0029-on-Setting-125"></a></var><br>
1274	<blockquote>
1275	<p>These cast operators allow a <code>Setting</code> object to be assigned to a
1276	variable of type <i>bool</i> if it is of type <code>TypeBoolean</code>;
1277	<i>int</i>, <i>unsigned int</i>, <i>long</i>, or <i>unsigned long</i> if it is of
1278	type <code>TypeInt</code>; <code>long long</code> or <code>unsigned long long</code> if
1279	it is of type <code>TypeInt64</code>, <i>float</i> or <i>double</i> if it is of type
1280	<code>TypeFloat</code>; or <i>const char *</i><!-- /@w --> or <i>std::string</i> if it is
1281	of type <code>TypeString</code>.
1282
1283	<p>Storage for <i>const char *</i><!-- /@w --> return values is managed by the
1284	library and released automatically when the setting is destroyed or
1285	when its value is changed; the string must not be freed by the
1286	caller. For safety and convenience, always assigning string return
1287	values to a <code>std::string</code> is suggested.
1288
1289	<p>The following examples demonstrate this usage:
1290
1291	<p><table class="cartouche" summary="cartouche" border="1"><tr><td>
1292	<pre class="example"> long width = config.lookup("application.window.size.w");
1293
1294	bool splashScreen = config.lookup("application.splash_screen");
1295
1296	std::string title = config.lookup("application.window.title");
1297	</pre>
1298	</td></tr></table>
1299
1300	<p>Note that certain conversions can lead to loss of precision or
1301	clipping of values, e.g., assigning a negative value to an <i>unsigned
1302	int</i> (in which case the value will be treated as 0), or a
1303	double-precision value to a <i>float</i>. The library does not treat
1304	these lossy conversions as errors.
1305
1306	<p>Perhaps surprisingly, the following code in particular will cause a
1307	compiler error:
1308
1309	<p><table class="cartouche" summary="cartouche" border="1"><tr><td>
1310	<pre class="example"> std::string title;
1311	.
1312	.
1313	.
1314	title = config.lookup("application.window.title");
1315	</pre>
1316	</td></tr></table>
1317
1318	<p>This is because the assignment operator of <code>std::string</code> is being
1319	invoked with a <code>Setting &</code> as an argument. The compiler is unable
1320	to make an implicit conversion because both the <code>const char *</code>
1321	and the <code>std::string</code> cast operators of <code>Setting</code> are
1322	equally appropriate. This is not a bug in <i>libconfig</i>; providing
1323	only the <code>const char *</code> cast operator would resolve this
1324	particular ambiguity, but would cause assignments to
1325	<code>std::string</code> like the one in the previous example to produce a
1326	compiler error. (To understand why, see section 11.4.1 of <i>The C++
1327	Programming Language</i>.)
1328
1329	<p>The solution to this problem is to use an explicit conversion that
1330	avoids the construction of an intermediate <code>std::string</code> object,
1331	as follows:
1332
1333	<p><table class="cartouche" summary="cartouche" border="1"><tr><td>
1334	<pre class="example"> std::string title;
1335	.
1336	.
1337	.
1338	title = (const char *)config.lookup("application.window.title");
1339	</pre>
1340	</td></tr></table>
1341
1342	<p>If the assignment is invalid due to a type mismatch, a
1343	<code>SettingTypeException</code> is thrown.
1344
1345	</blockquote></div>
1346
1347	<div class="defun">
1348	— Method on Setting: Setting & <b>operator=</b> (<var>bool value<!-- /@w --></var>)<var><a name="index-operator_003d-on-Setting-126"></a></var><br>
1349	— Method on Setting: Setting & <b>operator=</b> (<var>int value<!-- /@w --></var>)<var><a name="index-operator_003d-on-Setting-127"></a></var><br>
1350	— Method on Setting: Setting & <b>operator=</b> (<var>long value<!-- /@w --></var>)<var><a name="index-operator_003d-on-Setting-128"></a></var><br>
1351	— Method on Setting: Setting & <b>operator=</b> (<var>const long long &value<!-- /@w --></var>)<var><a name="index-operator_003d-on-Setting-129"></a></var><br>
1352	— Method on Setting: Setting & <b>operator=</b> (<var>float value<!-- /@w --></var>)<var><a name="index-operator_003d-on-Setting-130"></a></var><br>
1353	— Method on Setting: Setting & <b>operator=</b> (<var>const double &value<!-- /@w --></var>)<var><a name="index-operator_003d-on-Setting-131"></a></var><br>
1354	— Method on Setting: Setting & <b>operator=</b> (<var>const char *value<!-- /@w --></var>)<var><a name="index-operator_003d-on-Setting-132"></a></var><br>
1355	— Method on Setting: Setting & <b>operator=</b> (<var>const std::string &value<!-- /@w --></var>)<var><a name="index-operator_003d-on-Setting-133"></a></var><br>
1356	<blockquote>
1357	<p>These assignment operators allow values of type <i>bool</i>, <i>int</i>,
1358	<i>long</i>, <i>long long</i>, <i>float</i>, <i>double</i>, <i>const char *</i>, and
1359	<i>std::string</i> to be assigned to a setting. In the case of strings,
1360	the library makes a copy of the passed string <var>value</var>, so it may
1361	be subsequently freed or modified by the caller without affecting the
1362	value of the setting.
1363
1364	<p>If the assignment is invalid due to a type mismatch, a
1365	<code>SettingTypeException</code> is thrown.
1366
1367	</blockquote></div>
1368
1369	<div class="defun">
1370	— Method on Setting: Setting & <b>operator[]</b> (<var>int idx<!-- /@w --></var>)<var><a name="index-operator_005b_005d-on-Setting-134"></a></var><br>
1371	— Method on Setting: Setting & <b>operator[]</b> (<var>const std::string &name<!-- /@w --></var>)<var><a name="index-operator_005b_005d-on-Setting-135"></a></var><br>
1372	— Method on Setting: Setting & <b>operator[]</b> (<var>const char *name<!-- /@w --></var>)<var><a name="index-operator_005b_005d-on-Setting-136"></a></var><br>
1373	<blockquote>
1374	<p>A <code>Setting</code> object may be subscripted with an integer index
1375	<var>idx</var> if it is an array or list, or with either a string
1376	<var>name</var> or an integer index <var>idx</var> if it is a group. For example,
1377	the following code would produce the string `<samp><span class="samp">Last Name</span></samp>' when
1378	applied to the example configuration in <a href="#Configuration-Files">Configuration Files</a>.
1379
1380	<p><table class="cartouche" summary="cartouche" border="1"><tr><td>
1381	<pre class="example"> Setting& setting = config.lookup("application.misc");
1382	const char *s = setting["columns"][0];
1383	</pre>
1384	</td></tr></table>
1385
1386	<p>If the setting is not an array, list, or group, a
1387	<code>SettingTypeException</code> is thrown. If the subscript (<var>idx</var>
1388	or <var>name</var>) does not refer to a valid element, a
1389	<code>SettingNotFoundException</code> is thrown.
1390
1391	<p>Iterating over a group's child settings with an integer index will
1392	return the settings in the same order that they appear in the
1393	configuration.
1394
1395	</blockquote></div>
1396
1397	<div class="defun">
1398	— Method on Setting: bool <b>lookupValue</b> (<var>const char *name<!-- /@w -->, bool &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-137"></a></var><br>
1399	— Method on Setting: bool <b>lookupValue</b> (<var>const std::string &name<!-- /@w -->, bool &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-138"></a></var><br>
1400
1401	— Method on Setting: bool <b>lookupValue</b> (<var>const char *name<!-- /@w -->, int &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-139"></a></var><br>
1402	— Method on Setting: bool <b>lookupValue</b> (<var>const std::string &name<!-- /@w -->, int &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-140"></a></var><br>
1403
1404	— Method on Setting: bool <b>lookupValue</b> (<var>const char *name<!-- /@w -->, unsigned int &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-141"></a></var><br>
1405	— Method on Setting: bool <b>lookupValue</b> (<var>const std::string &name<!-- /@w -->, unsigned int &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-142"></a></var><br>
1406
1407	— Method on Setting: bool <b>lookupValue</b> (<var>const char *name<!-- /@w -->, long long &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-143"></a></var><br>
1408	— Method on Setting: bool <b>lookupValue</b> (<var>const std::string &name<!-- /@w -->, long long &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-144"></a></var><br>
1409
1410	— Method on Setting: bool <b>lookupValue</b> (<var>const char *name<!-- /@w -->, unsigned long long &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-145"></a></var><br>
1411	— Method on Setting: bool <b>lookupValue</b> (<var>const std::string &name<!-- /@w -->, unsigned long long &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-146"></a></var><br>
1412
1413	— Method on Setting: bool <b>lookupValue</b> (<var>const char *name<!-- /@w -->, long &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-147"></a></var><br>
1414	— Method on Setting: bool <b>lookupValue</b> (<var>const std::string &name<!-- /@w -->, long &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-148"></a></var><br>
1415
1416	— Method on Setting: bool <b>lookupValue</b> (<var>const char *name<!-- /@w -->, unsigned long &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-149"></a></var><br>
1417	— Method on Setting: bool <b>lookupValue</b> (<var>const std::string &name<!-- /@w -->, unsigned long &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-150"></a></var><br>
1418
1419	— Method on Setting: bool <b>lookupValue</b> (<var>const char *name<!-- /@w -->, float &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-151"></a></var><br>
1420	— Method on Setting: bool <b>lookupValue</b> (<var>const std::string &name<!-- /@w -->, float &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-152"></a></var><br>
1421
1422	— Method on Setting: bool <b>lookupValue</b> (<var>const char *name<!-- /@w -->, double &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-153"></a></var><br>
1423	— Method on Setting: bool <b>lookupValue</b> (<var>const std::string &name<!-- /@w -->, double &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-154"></a></var><br>
1424
1425	— Method on Setting: bool <b>lookupValue</b> (<var>const char name<!-- /@w -->, const char &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-155"></a></var><br>
1426	— Method on Setting: bool <b>lookupValue</b> (<var>const std::string &name<!-- /@w -->, const char *&value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-156"></a></var><br>
1427
1428	— Method on Setting: bool <b>lookupValue</b> (<var>const char *name<!-- /@w -->, std::string &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-157"></a></var><br>
1429	— Method on Setting: bool <b>lookupValue</b> (<var>const std::string &name<!-- /@w -->, std::string &value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-158"></a></var><br>
1430	<blockquote>
1431	<p>These are convenience methods for looking up the value of a child setting
1432	with the given <var>name</var>. If the setting is found and is of an
1433	appropriate type, the value is stored in <var>value</var> and the method
1434	returns <code>true</code>. Otherwise, <var>value</var> is left unmodified and the
1435	method returns <var>false</var>. These methods do not throw exceptions.
1436
1437	<p>Storage for <i>const char *</i><!-- /@w --> values is managed by the library and
1438	released automatically when the setting is destroyed or when its value
1439	is changed; the string must not be freed by the caller. For safety and
1440	convenience, always assigning string values to a <code>std::string</code> is
1441	suggested.
1442
1443	<p>Since these methods have boolean return values and do not throw
1444	exceptions, they can be used within boolean logic expressions. The following
1445	example presents a concise way to look up three values at once and
1446	perform error handling if any of them are not found or are of the
1447	wrong type:
1448
1449	<pre class="sp">
1450
1451	</pre>
1452	<p><table class="cartouche" summary="cartouche" border="1"><tr><td>
1453	<pre class="example"> int var1;
1454	double var2;
1455	const char *var3;
1456
1457	if(setting.lookupValue("var1", var1)
1458	&& setting.lookupValue("var2", var2)
1459	&& setting.lookupValue("var3", var3))
1460	{
1461	// use var1, var2, var3
1462	}
1463	else
1464	{
1465	// error handling here
1466	}
1467	</pre>
1468	</td></tr></table>
1469
1470	<p>This approach also takes advantage of the short-circuit evaluation
1471	rules of C++, e.g., if the first lookup fails (returning <code>false</code>), the
1472	remaining lookups are skipped entirely.
1473
1474	</blockquote></div>
1475
1476	<div class="defun">
1477	— Method on Setting: Setting & <b>add</b> (<var>const std::string &name<!-- /@w -->, Setting::Type type<!-- /@w --></var>)<var><a name="index-add-on-Setting-159"></a></var><br>
1478	— Method on Setting: Setting & <b>add</b> (<var>const char *name<!-- /@w -->, Setting::Type type<!-- /@w --></var>)<var><a name="index-add-on-Setting-160"></a></var><br>
1479	<blockquote>
1480	<p>These methods add a new child setting with the given <var>name</var> and
1481	<var>type</var> to the setting, which must be a group. They return a
1482	reference to the new setting. If the setting already has a child
1483	setting with the given name, or if the name is invalid, a
1484	<code>SettingNameException</code> is thrown. If the setting is not a group,
1485	a <code>SettingTypeException</code> is thrown.
1486
1487	<p>Once a setting has been created, neither its name nor type can be
1488	changed.
1489
1490	</blockquote></div>
1491
1492	<div class="defun">
1493	— Method on Setting: Setting & <b>add</b> (<var>Setting::Type type<!-- /@w --></var>)<var><a name="index-add-on-Setting-161"></a></var><br>
1494	<blockquote>
1495	<p>This method adds a new element to the setting, which must be of type
1496	<code>TypeArray</code> or <code>TypeList</code>. If the setting is an array which
1497	currently has zero elements, the <var>type</var> parameter (which must be
1498	<code>TypeInt</code>, <code>TypeInt64</code>, <code>TypeFloat</code>, <code>TypeBool</code>,
1499	or <code>TypeString</code>) determines the type for the array; otherwise it
1500	must match the type of the existing elements in the array.
1501
1502	<p>The method returns the new setting on success. If <var>type</var> is a
1503	scalar type, the new setting will have a default value of 0, 0.0,
1504	<code>false</code>, or <code>NULL</code>, depending on the type.
1505
1506	<p>The method throws a <code>SettingTypeException</code> if the setting is not
1507	an array or list, or if <var>type</var> is invalid.
1508
1509	</blockquote></div>
1510
1511	<div class="defun">
1512	— Method on Setting: void <b>remove</b> (<var>const std::string &name<!-- /@w --></var>)<var><a name="index-remove-on-Setting-162"></a></var><br>
1513	— Method on Setting: void <b>remove</b> (<var>const char *name<!-- /@w --></var>)<var><a name="index-remove-on-Setting-163"></a></var><br>
1514	<blockquote>
1515	<p>These methods remove the child setting with the given <var>name</var> from
1516	the setting, which must be a group. Any child settings of the removed
1517	setting are recursively destroyed as well.
1518
1519	<p>If the setting is not a group, a <code>SettingTypeException</code> is
1520	thrown. If the setting does not have a child setting with the given
1521	name, a <code>SettingNotFoundException</code> is thrown.
1522
1523	</blockquote></div>
1524
1525	<div class="defun">
1526	— Method on Setting: void <b>remove</b> (<var>unsigned int idx<!-- /@w --></var>)<var><a name="index-remove-on-Setting-164"></a></var><br>
1527	<blockquote>
1528	<p>This method removes the child setting at the given index <var>idx</var> from
1529	the setting, which must be a group, list, or array. Any child settings
1530	of the removed setting are recursively destroyed as well.
1531
1532	<p>If the setting is not a group, list, or array, a
1533	<code>SettingTypeException</code> is thrown. If <var>idx</var> is out of range,
1534	a <code>SettingNotFoundException</code> is thrown.
1535
1536	</blockquote></div>
1537
1538	<div class="defun">
1539	— Method on Setting: const char * <b>getName</b> ()<var><a name="index-getName-on-Setting-165"></a></var><br>
1540	<blockquote>
1541	<p>This method returns the name of the setting, or <code>NULL</code> if the
1542	setting has no name. Storage for the returned string is managed by the
1543	library and released automatically when the setting is destroyed; the
1544	string must not be freed by the caller. For safety and convenience,
1545	consider assigning the return value to a <code>std::string</code>.
1546
1547	</blockquote></div>
1548
1549	<div class="defun">
1550	— Method on Setting: std::string <b>getPath</b> ()<var><a name="index-getPath-on-Setting-166"></a></var><br>
1551	<blockquote>
1552	<p>This method returns the complete dot-separated path to the
1553	setting. Settings which do not have a name (list and array elements)
1554	are represented by their index in square brackets.
1555
1556	</blockquote></div>
1557
1558	<div class="defun">
1559	— Method on Setting: Setting & <b>getParent</b> ()<var><a name="index-getParent-on-Setting-167"></a></var><br>
1560	<blockquote>
1561	<p>This method returns the parent setting of the setting. If the setting
1562	is the root setting, a <code>SettingNotFoundException</code> is thrown.
1563
1564	</blockquote></div>
1565
1566	<div class="defun">
1567	— Method on Setting: bool <b>isRoot</b> ()<var><a name="index-isRoot-on-Setting-168"></a></var><br>
1568	<blockquote>
1569	<p>This method returns <i>true</i> if the setting is the root setting, and
1570	<i>false</i> otherwise.
1571
1572	</blockquote></div>
1573
1574	<div class="defun">
1575	— Method on Setting: int <b>getIndex</b> ()<var><a name="index-getIndex-on-Setting-169"></a></var><br>
1576	<blockquote>
1577	<p>This method returns the index of the setting within its parent
1578	setting. When applied to the root setting, this method returns -1.
1579
1580	</blockquote></div>
1581
1582	<div class="defun">
1583	— Method on Setting: Setting::Type <b>getType</b> ()<var><a name="index-getType-on-Setting-170"></a></var><br>
1584	<blockquote>
1585	<p><a name="index-Setting_003a_003aType-171"></a>This method returns the type of the setting. The
1586	<code>Setting::Type</code> enumeration consists of the following constants:
1587	<code>TypeInt</code>, <code>TypeInt64</code>, <code>TypeFloat</code>, <code>TypeString</code>,
1588	<code>TypeBoolean</code>, <code>TypeArray</code>, <code>TypeList</code>, or
1589	<code>TypeGroup</code>.
1590
1591	</blockquote></div>
1592
1593	<div class="defun">
1594	— Method on Setting: Setting::Format <b>getFormat</b> ()<var><a name="index-getFormat-on-Setting-172"></a></var><br>
1595	— Method on Setting: void <b>setFormat</b> (<var>Setting::Format format<!-- /@w --></var>)<var><a name="index-setFormat-on-Setting-173"></a></var><br>
1596	<blockquote>
1597	<p>These methods get and set the external format for the setting.
1598
1599	<p><a name="index-Setting_003a_003aFormat-174"></a>The <var>Setting::Format</var> enumeration consists of the following
1600	constants: <code>FormatDefault</code>, <code>FormatHex</code>. All settings
1601	support the <code>FormatDefault</code> format. The <code>FormatHex</code> format
1602	specifies hexadecimal formatting for integer values, and hence only
1603	applies to settings of type <code>TypeInt</code> and <code>TypeInt64</code>. If
1604	<var>format</var> is invalid for the given setting, it is ignored.
1605
1606	</blockquote></div>
1607
1608	<div class="defun">
1609	— Method on Setting: bool <b>exists</b> (<var>const std::string &name<!-- /@w --></var>)<var><a name="index-exists-on-Setting-175"></a></var><br>
1610	— Method on Setting: bool <b>exists</b> (<var>const char *name<!-- /@w --></var>)<var><a name="index-exists-on-Setting-176"></a></var><br>
1611	<blockquote>
1612	<p>These methods test if the setting has a child setting with the given
1613	<var>name</var>. They return <code>true</code> if the setting exists, and
1614	<var>false</var> otherwise. These methods do not throw exceptions.
1615
1616	</blockquote></div>
1617
1618	<div class="defun">
1619	— Method on Setting: int <b>getLength</b> ()<var><a name="index-getLength-on-Setting-177"></a></var><br>
1620	<blockquote>
1621	<p>This method returns the number of settings in a group, or the number of
1622	elements in a list or array. For other types of settings, it returns
1623	0.
1624
1625	</blockquote></div>
1626
1627	<div class="defun">
1628	— Method on Setting: bool <b>isGroup</b> ()<var><a name="index-isGroup-on-Setting-178"></a></var><br>
1629	— Method on Setting: bool <b>isArray</b> ()<var><a name="index-isArray-on-Setting-179"></a></var><br>
1630	— Method on Setting: bool <b>isList</b> ()<var><a name="index-isList-on-Setting-180"></a></var><br>
1631	<blockquote>
1632	<p>These convenience methods test if a setting is of a given type.
1633
1634	</blockquote></div>
1635
1636	<div class="defun">
1637	— Method on Setting: bool <b>isAggregate</b> ()<var><a name="index-isAggregate-on-Setting-181"></a></var><br>
1638	— Method on Setting: bool <b>isScalar</b> ()<var><a name="index-isScalar-on-Setting-182"></a></var><br>
1639	— Method on Setting: bool <b>isNumber</b> ()<var><a name="index-isNumber-on-Setting-183"></a></var><br>
1640	<blockquote>
1641	<p>These convenience methods test if a setting is of an aggregate type (a
1642	group, array, or list), of a scalar type (integer, 64-bit integer,
1643	floating point, boolean, or string), and of a number (integer or
1644	floating point), respectively.
1645
1646	</blockquote></div>
1647
1648	<div class="defun">
1649	— Method on Setting: unsigned int <b>getSourceLine</b> ()<var><a name="index-getSourceLine-on-Setting-184"></a></var><br>
1650	<blockquote>
1651	<p>This method returns the line number of the configuration file or
1652	stream at which the setting was parsed. This information is useful for
1653	reporting application-level errors. If the setting was not read from a
1654	file or stream, or if the line number is otherwise unavailable, the
1655	method returns 0.
1656
1657	</blockquote></div>
1658
1659	<div class="node">
1660	<p><hr>
1661	<a name="Configuration-File-Grammar"></a>
1662	Next: <a rel="next" accesskey="n" href="#License">License</a>,
1663	Previous: <a rel="previous" accesskey="p" href="#The-C_002b_002b-API">The C++ API</a>,
1664	Up: <a rel="up" accesskey="u" href="#Top">Top</a>
1665
1666	</div>
1667
1668	<!-- node-name, next, previous, up -->
1669	<h2 class="chapter">5 Configuration File Grammar</h2>
1670
1671	<p>Below is the BNF grammar for configuration files. Comments are not part
1672	of the grammar, and hence are not included here.
1673
1674	<pre class="sp">
1675
1676	</pre>
1677	<pre class="example"> configuration = setting-list \| empty
1678
1679	empty =
1680
1681	setting-list = setting \| setting-list setting
1682
1683	setting = name (":" \| "=") value ";"
1684
1685	value = scalar-value \| array \| list \| group
1686
1687	value-list = value \| value-list "," value
1688
1689	scalar-value = boolean \| integer \| integer64 \| hex \| hex64 \| float
1690	\| string
1691
1692	scalar-value-list = scalar-value \| scalar-value-list "," scalar-value
1693
1694	array = "[" (scalar-value-list \| empty) "]"
1695
1696	list = "(" (value-list \| empty) ")"
1697
1698	group = "{" (setting-list \| empty) "}"
1699	</pre>
1700	<pre class="sp">
1701
1702
1703	</pre>
1704	Terminals are defined below as regular expressions:
1705	<pre class="sp">
1706
1707	</pre>
1708	<p><table summary=""><tr align="left"><td valign="top" width="20%"><code>boolean</code> </td><td valign="top" width="80%">
1709	<code>([Tt][Rr][Uu][Ee])\|([Ff][Aa][Ll][Ss][Ee])</code>
1710	<br></td></tr><tr align="left"><td valign="top" width="20%"><code>string</code> </td><td valign="top" width="80%">
1711	<code>\"([^\"\\]\|\\.)*\"</code>
1712	<br></td></tr><tr align="left"><td valign="top" width="20%"><code>name</code> </td><td valign="top" width="80%">
1713	<code>[A-Za-z\][-A-Za-z0-9_\]*</code>
1714	<br></td></tr><tr align="left"><td valign="top" width="20%"><code>integer</code> </td><td valign="top" width="80%">
1715	<code>[-+]?[0-9]+</code>
1716	<br></td></tr><tr align="left"><td valign="top" width="20%"><code>integer64</code> </td><td valign="top" width="80%">
1717	<code>[-+]?[0-9]+L(L)?</code>
1718	<br></td></tr><tr align="left"><td valign="top" width="20%"><code>hex</code> </td><td valign="top" width="80%">
1719	<code>0[Xx][0-9A-Fa-f]+</code>
1720	<br></td></tr><tr align="left"><td valign="top" width="20%"><code>hex64</code> </td><td valign="top" width="80%">
1721	<code>0[Xx][0-9A-Fa-f]+L(L)?</code>
1722	<br></td></tr><tr align="left"><td valign="top" width="20%"><code>float</code> </td><td valign="top" width="80%">
1723	<code>([-+]?([0-9])?\.[0-9]([eE][-+]?[0-9]+)?)\|([-+]([0-9]+)(\.[0-9]*)?[eE][-+]?[0-9]+)</code>
1724	<br></td></tr></table>
1725
1726	<div class="node">
1727	<p><hr>
1728	<a name="License"></a>
1729	Next: <a rel="next" accesskey="n" href="#Function-Index">Function Index</a>,
1730	Previous: <a rel="previous" accesskey="p" href="#Configuration-File-Grammar">Configuration File Grammar</a>,
1731	Up: <a rel="up" accesskey="u" href="#Top">Top</a>
1732
1733	</div>
1734
1735	<!-- node-name, next, previous, up -->
1736	<h2 class="appendix">Appendix A License</h2>
1737
1738	<!-- \input texinfo.tex @c --texinfo-- -->
1739	<!-- %**start of header -->
1740	<!-- All text is ignored before the setfilename. -->
1741	<div align="center">GNU LESSER GENERAL PUBLIC LICENSE</div>
1742	<div align="center">Version 2.1, February 1999</div>
1743
1744	<pre class="sp">
1745
1746	</pre>
1747
1748	Copyright © 1991, 1999 Free Software Foundation, Inc.,
1749	59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
1750
1751	<p>Everyone is permitted to copy and distribute verbatim copies of this
1752	license document, but changing it is not allowed.
1753
1754	<p>[This is the first released version of the Lesser GPL. It also counts
1755	as the successor of the GNU Library Public License, version 2, hence the
1756	version number 2.1.]
1757
1758	<pre class="sp">
1759
1760	</pre>
1761	<div align="center">Preamble</div>
1762	<pre class="sp">
1763
1764	</pre>
1765
1766	The licenses for most software are designed to take away your freedom to
1767	share and change it. By contrast, the GNU General Public Licenses are
1768	intended to guarantee your freedom to share and change free software–to
1769	make sure the software is free for all its users.
1770
1771	<p>This license, the Lesser General Public License, applies to some
1772	specially designated software packages–typically libraries–of the Free
1773	Software Foundation and other authors who decide to use it. You can use
1774	it too, but we suggest you first think carefully about whether this
1775	license or the ordinary General Public License is the better strategy to
1776	use in any particular case, based on the explanations below.
1777
1778	<p>When we speak of free software, we are referring to freedom of use, not
1779	price. Our General Public Licenses are designed to make sure that you
1780	have the freedom to distribute copies of free software (and charge for
1781	this service if you wish); that you receive source code or can get it if
1782	you want it; that you can change the software and use pieces of it in
1783	new free programs; and that you are informed that you can do these
1784	things.
1785
1786	<p>To protect your rights, we need to make restrictions that forbid
1787	distributors to deny you these rights or to ask you to surrender these
1788	rights. These restrictions translate to certain responsibilities for
1789	you if you distribute copies of the library or if you modify it.
1790
1791	<p>For example, if you distribute copies of the library, whether gratis or
1792	for a fee, you must give the recipients all the rights that we gave you.
1793	You must make sure that they, too, receive or can get the source code.
1794	If you link other code with the library, you must provide complete
1795	object files to the recipients, so that they can relink them with the
1796	library after making changes to the library and recompiling it. And you
1797	must show them these terms so they know their rights.
1798
1799	<p>We protect your rights with a two-step method: (1) we copyright the
1800	library, and (2) we offer you this license, which gives you legal
1801	permission to copy, distribute and/or modify the library.
1802
1803	<p>To protect each distributor, we want to make it very clear that there is
1804	no warranty for the free library. Also, if the library is modified by
1805	someone else and passed on, the recipients should know that what they
1806	have is not the original version, so that the original author's
1807	reputation will not be affected by problems that might be introduced by
1808	others.
1809
1810	<p>Finally, software patents pose a constant threat to the existence of any
1811	free program. We wish to make sure that a company cannot effectively
1812	restrict the users of a free program by obtaining a restrictive license
1813	from a patent holder. Therefore, we insist that any patent license
1814	obtained for a version of the library must be consistent with the full
1815	freedom of use specified in this license.
1816
1817	<p>Most GNU software, including some libraries, is covered by the ordinary
1818	GNU General Public License. This license, the GNU Lesser General Public
1819	License, applies to certain designated libraries, and is quite different
1820	from the ordinary General Public License. We use this license for
1821	certain libraries in order to permit linking those libraries into
1822	non-free programs.
1823
1824	<p>When a program is linked with a library, whether statically or using a
1825	shared library, the combination of the two is legally speaking a
1826	combined work, a derivative of the original library. The ordinary
1827	General Public License therefore permits such linking only if the entire
1828	combination fits its criteria of freedom. The Lesser General Public
1829	License permits more lax criteria for linking other code with the
1830	library.
1831
1832	<p>We call this license the “Lesser” General Public License because it does
1833	Less to protect the user's freedom than the ordinary General Public
1834	License. It also provides other free software developers Less of an
1835	advantage over competing non-free programs. These disadvantages are the
1836	reason we use the ordinary General Public License for many libraries.
1837	However, the Lesser license provides advantages in certain special
1838	circumstances.
1839
1840	<p>For example, on rare occasions, there may be a special need to encourage
1841	the widest possible use of a certain library, so that it becomes a
1842	de-facto standard. To achieve this, non-free programs must be allowed
1843	to use the library. A more frequent case is that a free library does
1844	the same job as widely used non-free libraries. In this case, there is
1845	little to gain by limiting the free library to free software only, so we
1846	use the Lesser General Public License.
1847
1848	<p>In other cases, permission to use a particular library in non-free
1849	programs enables a greater number of people to use a large body of free
1850	software. For example, permission to use the GNU C Library in non-free
1851	programs enables many more people to use the whole GNU operating system,
1852	as well as its variant, the GNU/Linux operating system.
1853
1854	<p>Although the Lesser General Public License is Less protective of the
1855	users' freedom, it does ensure that the user of a program that is linked
1856	with the Library has the freedom and the wherewithal to run that program
1857	using a modified version of the Library.
1858
1859	<p>The precise terms and conditions for copying, distribution and
1860	modification follow. Pay close attention to the difference between a
1861	“work based on the library” and a “work that uses the library”. The
1862	former contains code derived from the library, whereas the latter must
1863	be combined with the library in order to run.
1864
1865	<div align="center">GNU LESSER GENERAL PUBLIC LICENSE</div>
1866	<div align="center">TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION</div>
1867
1868	<ol type=1 start=0>
1869
1870	<pre class="sp">
1871
1872	</pre>
1873	<li>This License Agreement applies to any software library or other program
1874	which contains a notice placed by the copyright holder or other
1875	authorized party saying it may be distributed under the terms of this
1876	Lesser General Public License (also called “this License”). Each
1877	licensee is addressed as “you”.
1878
1879	<p>A “library” means a collection of software functions and/or data
1880	prepared so as to be conveniently linked with application programs
1881	(which use some of those functions and data) to form executables.
1882
1883	<p>The “Library”, below, refers to any such software library or work which
1884	has been distributed under these terms. A “work based on the Library”
1885	means either the Library or any derivative work under copyright law:
1886	that is to say, a work containing the Library or a portion of it, either
1887	verbatim or with modifications and/or translated straightforwardly into
1888	another language. (Hereinafter, translation is included without
1889	limitation in the term “modification”.)
1890
1891	<p>“Source code” for a work means the preferred form of the work for making
1892	modifications to it. For a library, complete source code means all the
1893	source code for all modules it contains, plus any associated interface
1894	definition files, plus the scripts used to control compilation and
1895	installation of the library.
1896
1897	<p>Activities other than copying, distribution and modification are not
1898	covered by this License; they are outside its scope. The act of running
1899	a program using the Library is not restricted, and output from such a
1900	program is covered only if its contents constitute a work based on the
1901	Library (independent of the use of the Library in a tool for writing
1902	it). Whether that is true depends on what the Library does and what the
1903	program that uses the Library does.
1904
1905	<pre class="sp">
1906
1907	</pre>
1908	<li>You may copy and distribute verbatim copies of the Library's complete
1909	source code as you receive it, in any medium, provided that you
1910	conspicuously and appropriately publish on each copy an appropriate
1911	copyright notice and disclaimer of warranty; keep intact all the notices
1912	that refer to this License and to the absence of any warranty; and
1913	distribute a copy of this License along with the Library.
1914
1915	<p>You may charge a fee for the physical act of transferring a copy, and
1916	you may at your option offer warranty protection in exchange for a fee.
1917
1918	<pre class="sp">
1919
1920	</pre>
1921	<li>You may modify your copy or copies of the Library or any portion of it,
1922	thus forming a work based on the Library, and copy and distribute such
1923	modifications or work under the terms of Section 1 above, provided that
1924	you also meet all of these conditions:
1925
1926	<ol type=a start=1>
1927
1928	<li>The modified work must itself be a software library.
1929
1930	<pre class="sp">
1931
1932	</pre>
1933	<li>You must cause the files modified to carry prominent notices stating
1934	that you changed the files and the date of any change.
1935
1936	<pre class="sp">
1937
1938	</pre>
1939	<li>You must cause the whole of the work to be licensed at no charge to all
1940	third parties under the terms of this License.
1941
1942	<pre class="sp">
1943
1944	</pre>
1945	<li>If a facility in the modified Library refers to a function or a table of
1946	data to be supplied by an application program that uses the facility,
1947	other than as an argument passed when the facility is invoked, then you
1948	must make a good faith effort to ensure that, in the event an
1949	application does not supply such function or table, the facility still
1950	operates, and performs whatever part of its purpose remains meaningful.
1951
1952	<p>(For example, a function in a library to compute square roots has a
1953	purpose that is entirely well-defined independent of the application.
1954	Therefore, Subsection 2d requires that any application-supplied function
1955	or table used by this function must be optional: if the application does
1956	not supply it, the square root function must still compute square
1957	roots.)
1958
1959	</ol>
1960
1961	<p>These requirements apply to the modified work as a whole. If
1962	identifiable sections of that work are not derived from the Library, and
1963	can be reasonably considered independent and separate works in
1964	themselves, then this License, and its terms, do not apply to those
1965	sections when you distribute them as separate works. But when you
1966	distribute the same sections as part of a whole which is a work based on
1967	the Library, the distribution of the whole must be on the terms of this
1968	License, whose permissions for other licensees extend to the entire
1969	whole, and thus to each and every part regardless of who wrote it.
1970
1971	<p>Thus, it is not the intent of this section to claim rights or contest
1972	your rights to work written entirely by you; rather, the intent is to
1973	exercise the right to control the distribution of derivative or
1974	collective works based on the Library.
1975
1976	<p>In addition, mere aggregation of another work not based on the Library
1977	with the Library (or with a work based on the Library) on a volume of a
1978	storage or distribution medium does not bring the other work under the
1979	scope of this License.
1980
1981	<pre class="sp">
1982
1983	</pre>
1984	<li>You may opt to apply the terms of the ordinary GNU General Public
1985	License instead of this License to a given copy of the Library. To do
1986	this, you must alter all the notices that refer to this License, so that
1987	they refer to the ordinary GNU General Public License, version 2,
1988	instead of to this License. (If a newer version than version 2 of the
1989	ordinary GNU General Public License has appeared, then you can specify
1990	that version instead if you wish.) Do not make any other change in
1991	these notices.
1992
1993	<p>Once this change is made in a given copy, it is irreversible for that
1994	copy, so the ordinary GNU General Public License applies to all
1995	subsequent copies and derivative works made from that copy.
1996
1997	<p>This option is useful when you wish to copy part of the code of the
1998	Library into a program that is not a library.
1999
2000	<pre class="sp">
2001
2002	</pre>
2003	<li>You may copy and distribute the Library (or a portion or derivative of
2004	it, under Section 2) in object code or executable form under the terms
2005	of Sections 1 and 2 above provided that you accompany it with the
2006	complete corresponding machine-readable source code, which must be
2007	distributed under the terms of Sections 1 and 2 above on a medium
2008	customarily used for software interchange.
2009
2010	<p>If distribution of object code is made by offering access to copy from a
2011	designated place, then offering equivalent access to copy the source
2012	code from the same place satisfies the requirement to distribute the
2013	source code, even though third parties are not compelled to copy the
2014	source along with the object code.
2015
2016	<pre class="sp">
2017
2018	</pre>
2019	<li>A program that contains no derivative of any portion of the Library, but
2020	is designed to work with the Library by being compiled or linked with
2021	it, is called a “work that uses the Library”. Such a work, in
2022	isolation, is not a derivative work of the Library, and therefore falls
2023	outside the scope of this License.
2024
2025	<p>However, linking a “work that uses the Library” with the Library creates
2026	an executable that is a derivative of the Library (because it contains
2027	portions of the Library), rather than a “work that uses the library”.
2028	The executable is therefore covered by this License. Section 6 states
2029	terms for distribution of such executables.
2030
2031	<p>When a “work that uses the Library” uses material from a header file
2032	that is part of the Library, the object code for the work may be a
2033	derivative work of the Library even though the source code is not.
2034	Whether this is true is especially significant if the work can be linked
2035	without the Library, or if the work is itself a library. The threshold
2036	for this to be true is not precisely defined by law.
2037
2038	<p>If such an object file uses only numerical parameters, data structure
2039	layouts and accessors, and small macros and small inline functions (ten
2040	lines or less in length), then the use of the object file is
2041	unrestricted, regardless of whether it is legally a derivative work.
2042	(Executables containing this object code plus portions of the Library
2043	will still fall under Section 6.)
2044
2045	<p>Otherwise, if the work is a derivative of the Library, you may
2046	distribute the object code for the work under the terms of Section 6.
2047	Any executables containing that work also fall under Section 6, whether
2048	or not they are linked directly with the Library itself.
2049
2050	<pre class="sp">
2051
2052	</pre>
2053	<li>As an exception to the Sections above, you may also combine or link a
2054	“work that uses the Library” with the Library to produce a work
2055	containing portions of the Library, and distribute that work under terms
2056	of your choice, provided that the terms permit modification of the work
2057	for the customer's own use and reverse engineering for debugging such
2058	modifications.
2059
2060	<p>You must give prominent notice with each copy of the work that the
2061	Library is used in it and that the Library and its use are covered by
2062	this License. You must supply a copy of this License. If the work
2063	during execution displays copyright notices, you must include the
2064	copyright notice for the Library among them, as well as a reference
2065	directing the user to the copy of this License. Also, you must do one
2066	of these things:
2067
2068	<ol type=a start=1>
2069
2070	<pre class="sp">
2071
2072	</pre>
2073	<li>Accompany the work with the complete corresponding machine-readable
2074	source code for the Library including whatever changes were used in the
2075	work (which must be distributed under Sections 1 and 2 above); and, if
2076	the work is an executable linked with the Library, with the complete
2077	machine-readable “work that uses the Library”, as object code and/or
2078	source code, so that the user can modify the Library and then relink to
2079	produce a modified executable containing the modified Library. (It is
2080	understood that the user who changes the contents of definitions files
2081	in the Library will not necessarily be able to recompile the application
2082	to use the modified definitions.)
2083
2084	<pre class="sp">
2085
2086	</pre>
2087	<li>Use a suitable shared library mechanism for linking with the Library. A
2088	suitable mechanism is one that (1) uses at run time a copy of the
2089	library already present on the user's computer system, rather than
2090	copying library functions into the executable, and (2) will operate
2091	properly with a modified version of the library, if the user installs
2092	one, as long as the modified version is interface-compatible with the
2093	version that the work was made with.
2094
2095	<pre class="sp">
2096
2097	</pre>
2098	<li>Accompany the work with a written offer, valid for at least three years,
2099	to give the same user the materials specified in Subsection 6a, above,
2100	for a charge no more than the cost of performing this distribution.
2101
2102	<pre class="sp">
2103
2104	</pre>
2105	<li>If distribution of the work is made by offering access to copy from a
2106	designated place, offer equivalent access to copy the above specified
2107	materials from the same place.
2108
2109	<pre class="sp">
2110
2111	</pre>
2112	<li>Verify that the user has already received a copy of these materials or
2113	that you have already sent this user a copy.
2114
2115	</ol>
2116
2117	<p>For an executable, the required form of the “work that uses the Library”
2118	must include any data and utility programs needed for reproducing the
2119	executable from it. However, as a special exception, the materials to
2120	be distributed need not include anything that is normally distributed
2121	(in either source or binary form) with the major components (compiler,
2122	kernel, and so on) of the operating system on which the executable runs,
2123	unless that component itself accompanies the executable.
2124
2125	<p>It may happen that this requirement contradicts the license restrictions
2126	of other proprietary libraries that do not normally accompany the
2127	operating system. Such a contradiction means you cannot use both them
2128	and the Library together in an executable that you distribute.
2129
2130	<pre class="sp">
2131
2132	</pre>
2133	<li>You may place library facilities that are a work based on the Library
2134	side-by-side in a single library together with other library facilities
2135	not covered by this License, and distribute such a combined library,
2136	provided that the separate distribution of the work based on the Library
2137	and of the other library facilities is otherwise permitted, and provided
2138	that you do these two things:
2139
2140	<ol type=a start=1>
2141
2142	<pre class="sp">
2143
2144	</pre>
2145	<li>Accompany the combined library with a copy of the same work based on the
2146	Library, uncombined with any other library facilities. This must be
2147	distributed under the terms of the Sections above.
2148
2149	<pre class="sp">
2150
2151	</pre>
2152	<li>Give prominent notice with the combined library of the fact that part of
2153	it is a work based on the Library, and explaining where to find the
2154	accompanying uncombined form of the same work.
2155
2156	</ol>
2157
2158	<pre class="sp">
2159
2160	</pre>
2161	<li>You may not copy, modify, sublicense, link with, or distribute the
2162	Library except as expressly provided under this License. Any attempt
2163	otherwise to copy, modify, sublicense, link with, or distribute the
2164	Library is void, and will automatically terminate your rights under this
2165	License. However, parties who have received copies, or rights, from you
2166	under this License will not have their licenses terminated so long as
2167	such parties remain in full compliance.
2168
2169	<pre class="sp">
2170
2171	</pre>
2172	<li>You are not required to accept this License, since you have not signed
2173	it. However, nothing else grants you permission to modify or distribute
2174	the Library or its derivative works. These actions are prohibited by
2175	law if you do not accept this License. Therefore, by modifying or
2176	distributing the Library (or any work based on the Library), you
2177	indicate your acceptance of this License to do so, and all its terms and
2178	conditions for copying, distributing or modifying the Library or works
2179	based on it.
2180
2181	<pre class="sp">
2182
2183	</pre>
2184	<li>Each time you redistribute the Library (or any work based on the
2185	Library), the recipient automatically receives a license from the
2186	original licensor to copy, distribute, link with or modify the Library
2187	subject to these terms and conditions. You may not impose any further
2188	restrictions on the recipients' exercise of the rights granted herein.
2189	You are not responsible for enforcing compliance by third parties with
2190	this License.
2191
2192	<pre class="sp">
2193
2194	</pre>
2195	<li>If, as a consequence of a court judgment or allegation of patent
2196	infringement or for any other reason (not limited to patent issues),
2197	conditions are imposed on you (whether by court order, agreement or
2198	otherwise) that contradict the conditions of this License, they do not
2199	excuse you from the conditions of this License. If you cannot
2200	distribute so as to satisfy simultaneously your obligations under this
2201	License and any other pertinent obligations, then as a consequence you
2202	may not distribute the Library at all. For example, if a patent license
2203	would not permit royalty-free redistribution of the Library by all those
2204	who receive copies directly or indirectly through you, then the only way
2205	you could satisfy both it and this License would be to refrain entirely
2206	from distribution of the Library.
2207
2208	<p>If any portion of this section is held invalid or unenforceable under
2209	any particular circumstance, the balance of the section is intended to
2210	apply, and the section as a whole is intended to apply in other
2211	circumstances.
2212
2213	<p>It is not the purpose of this section to induce you to infringe any
2214	patents or other property right claims or to contest validity of any
2215	such claims; this section has the sole purpose of protecting the
2216	integrity of the free software distribution system which is implemented
2217	by public license practices. Many people have made generous
2218	contributions to the wide range of software distributed through that
2219	system in reliance on consistent application of that system; it is up to
2220	the author/donor to decide if he or she is willing to distribute
2221	software through any other system and a licensee cannot impose that
2222	choice.
2223
2224	<p>This section is intended to make thoroughly clear what is believed to be
2225	a consequence of the rest of this License.
2226
2227	<pre class="sp">
2228
2229	</pre>
2230	<li>If the distribution and/or use of the Library is restricted in certain
2231	countries either by patents or by copyrighted interfaces, the original
2232	copyright holder who places the Library under this License may add an
2233	explicit geographical distribution limitation excluding those countries,
2234	so that distribution is permitted only in or among countries not thus
2235	excluded. In such case, this License incorporates the limitation as if
2236	written in the body of this License.
2237
2238	<pre class="sp">
2239
2240	</pre>
2241	<li>The Free Software Foundation may publish revised and/or new versions of
2242	the Lesser General Public License from time to time. Such new versions
2243	will be similar in spirit to the present version, but may differ in
2244	detail to address new problems or concerns.
2245
2246	<p>Each version is given a distinguishing version number. If the Library
2247	specifies a version number of this License which applies to it and “any
2248	later version”, you have the option of following the terms and
2249	conditions either of that version or of any later version published by
2250	the Free Software Foundation. If the Library does not specify a license
2251	version number, you may choose any version ever published by the Free
2252	Software Foundation.
2253
2254	<pre class="sp">
2255
2256	</pre>
2257	<li>If you wish to incorporate parts of the Library into other free programs
2258	whose distribution conditions are incompatible with these, write to the
2259	author to ask for permission. For software which is copyrighted by the
2260	Free Software Foundation, write to the Free Software Foundation; we
2261	sometimes make exceptions for this. Our decision will be guided by the
2262	two goals of preserving the free status of all derivatives of our free
2263	software and of promoting the sharing and reuse of software generally.
2264
2265	<pre class="sp">
2266
2267	</pre>
2268	<div align="center">NO WARRANTY</div>
2269	<pre class="sp">
2270
2271	</pre>
2272
2273	<li>BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
2274	THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
2275	OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
2276	PROVIDE THE LIBRARY “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER
2277	EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
2278	WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
2279	ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH
2280	YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
2281	NECESSARY SERVICING, REPAIR OR CORRECTION.
2282
2283	<pre class="sp">
2284
2285	</pre>
2286	<li>IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
2287	WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
2288	REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
2289	DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
2290	DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY
2291	(INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
2292	INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
2293	THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR
2294	OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
2295
2296	</ol>
2297
2298	<pre class="sp">
2299
2300	</pre>
2301	<div align="center">END OF TERMS AND CONDITIONS</div>
2302	<pre class="sp">
2303
2304	</pre>
2305
2306	<div align="center">How to Apply These Terms to Your New Libraries</div>
2307
2308	<p>If you develop a new library, and you want it to be of the greatest
2309	possible use to the public, we recommend making it free software that
2310	everyone can redistribute and change. You can do so by permitting
2311	redistribution under these terms (or, alternatively, under the terms of
2312	the ordinary General Public License).
2313
2314	<p>To apply these terms, attach the following notices to the library. It
2315	is safest to attach them to the start of each source file to most
2316	effectively convey the exclusion of warranty; and each file should have
2317	at least the “copyright” line and a pointer to where the full notice is
2318	found.
2319
2320	<pre class="format"><tt>
2321	<one line to give the library's name and a brief idea of what it does.>
2322	Copyright (C) <year> <name of author>
2323
2324	This library is free software; you can redistribute it and/or
2325	modify it under the terms of the GNU Lesser General Public
2326	License as published by the Free Software Foundation; either
2327	version 2 of the License, or (at your option) any later version.
2328
2329	This library is distributed in the hope that it will be useful,
2330	but WITHOUT ANY WARRANTY; without even the implied warranty of
2331	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
2332	Lesser General Public License for more details.
2333
2334	You should have received a copy of the GNU Lesser General Public
2335	License along with this library; if not, write to the Free Software
2336	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
2337	</tt>
2338	</pre>
2339	<p>Also add information on how to contact you by electronic and paper mail.
2340
2341	<p>You should also get your employer (if you work as a programmer) or your
2342	school, if any, to sign a “copyright disclaimer” for the library, if
2343	necessary. Here is a sample; alter the names:
2344
2345	<pre class="format"><tt>
2346	Yoyodyne, Inc., hereby disclaims all copyright interest in the
2347	library `Frob' (a library for tweaking knobs) written by James Random Hacker.
2348
2349	<signature of Ty Coon>, 1 April 1990
2350	Ty Coon, President of Vice
2351	</tt>
2352	</pre>
2353	<p>That's all there is to it!
2354
2355	<!-- @bye -->
2356	<div class="node">
2357	<p><hr>
2358	<a name="Function-Index"></a>
2359	Next: <a rel="next" accesskey="n" href="#Type-Index">Type Index</a>,
2360	Previous: <a rel="previous" accesskey="p" href="#License">License</a>,
2361	Up: <a rel="up" accesskey="u" href="#Top">Top</a>
2362
2363	</div>
2364
2365	<!-- node-name, next, previous, up -->
2366	<h2 class="unnumbered">Function Index</h2>
2367
2368	<ul class="index-fn" compact>
2369	<li><a href="#index-add-on-Setting-159"><code>add on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2370	<li><a href="#index-Config-on-Config-80"><code>Config on Config</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2371	<li><a href="#index-config_005fdestroy-12"><code>config_destroy</code></a>: <a href="#The-C-API">The C API</a></li>
2372	<li><a href="#index-config_005ferror_005fline-18"><code>config_error_line</code></a>: <a href="#The-C-API">The C API</a></li>
2373	<li><a href="#index-config_005ferror_005ftext-17"><code>config_error_text</code></a>: <a href="#The-C-API">The C API</a></li>
2374	<li><a href="#index-config_005fget_005fauto_005fconvert-20"><code>config_get_auto_convert</code></a>: <a href="#The-C-API">The C API</a></li>
2375	<li><a href="#index-config_005finit-11"><code>config_init</code></a>: <a href="#The-C-API">The C API</a></li>
2376	<li><a href="#index-config_005flookup-26"><code>config_lookup</code></a>: <a href="#The-C-API">The C API</a></li>
2377	<li><a href="#index-config_005flookup_005fbool-24"><code>config_lookup_bool</code></a>: <a href="#The-C-API">The C API</a></li>
2378	<li><a href="#index-config_005flookup_005ffloat-23"><code>config_lookup_float</code></a>: <a href="#The-C-API">The C API</a></li>
2379	<li><a href="#index-config_005flookup_005fint-21"><code>config_lookup_int</code></a>: <a href="#The-C-API">The C API</a></li>
2380	<li><a href="#index-config_005flookup_005fint64-22"><code>config_lookup_int64</code></a>: <a href="#The-C-API">The C API</a></li>
2381	<li><a href="#index-config_005flookup_005fstring-25"><code>config_lookup_string</code></a>: <a href="#The-C-API">The C API</a></li>
2382	<li><a href="#index-config_005fread-13"><code>config_read</code></a>: <a href="#The-C-API">The C API</a></li>
2383	<li><a href="#index-config_005fread_005ffile-14"><code>config_read_file</code></a>: <a href="#The-C-API">The C API</a></li>
2384	<li><a href="#index-config_005froot_005fsetting-55"><code>config_root_setting</code></a>: <a href="#The-C-API">The C API</a></li>
2385	<li><a href="#index-config_005fset_005fauto_005fconvert-19"><code>config_set_auto_convert</code></a>: <a href="#The-C-API">The C API</a></li>
2386	<li><a href="#index-config_005fset_005fdestructor-71"><code>config_set_destructor</code></a>: <a href="#The-C-API">The C API</a></li>
2387	<li><a href="#index-config_005fsetting_005fadd-52"><code>config_setting_add</code></a>: <a href="#The-C-API">The C API</a></li>
2388	<li><a href="#index-config_005fsetting_005fget_005fbool-30"><code>config_setting_get_bool</code></a>: <a href="#The-C-API">The C API</a></li>
2389	<li><a href="#index-config_005fsetting_005fget_005fbool_005felem-45"><code>config_setting_get_bool_elem</code></a>: <a href="#The-C-API">The C API</a></li>
2390	<li><a href="#index-config_005fsetting_005fget_005felem-41"><code>config_setting_get_elem</code></a>: <a href="#The-C-API">The C API</a></li>
2391	<li><a href="#index-config_005fsetting_005fget_005ffloat-29"><code>config_setting_get_float</code></a>: <a href="#The-C-API">The C API</a></li>
2392	<li><a href="#index-config_005fsetting_005fget_005ffloat_005felem-44"><code>config_setting_get_float_elem</code></a>: <a href="#The-C-API">The C API</a></li>
2393	<li><a href="#index-config_005fsetting_005fget_005fformat-37"><code>config_setting_get_format</code></a>: <a href="#The-C-API">The C API</a></li>
2394	<li><a href="#index-config_005fsetting_005fget_005fhook-70"><code>config_setting_get_hook</code></a>: <a href="#The-C-API">The C API</a></li>
2395	<li><a href="#index-config_005fsetting_005fget_005fint-27"><code>config_setting_get_int</code></a>: <a href="#The-C-API">The C API</a></li>
2396	<li><a href="#index-config_005fsetting_005fget_005fint64-28"><code>config_setting_get_int64</code></a>: <a href="#The-C-API">The C API</a></li>
2397	<li><a href="#index-config_005fsetting_005fget_005fint64_005felem-43"><code>config_setting_get_int64_elem</code></a>: <a href="#The-C-API">The C API</a></li>
2398	<li><a href="#index-config_005fsetting_005fget_005fint_005felem-42"><code>config_setting_get_int_elem</code></a>: <a href="#The-C-API">The C API</a></li>
2399	<li><a href="#index-config_005fsetting_005fget_005fmember-40"><code>config_setting_get_member</code></a>: <a href="#The-C-API">The C API</a></li>
2400	<li><a href="#index-config_005fsetting_005fget_005fstring-31"><code>config_setting_get_string</code></a>: <a href="#The-C-API">The C API</a></li>
2401	<li><a href="#index-config_005fsetting_005fget_005fstring_005felem-46"><code>config_setting_get_string_elem</code></a>: <a href="#The-C-API">The C API</a></li>
2402	<li><a href="#index-config_005fsetting_005findex-59"><code>config_setting_index</code></a>: <a href="#The-C-API">The C API</a></li>
2403	<li><a href="#index-config_005fsetting_005fis_005faggregate-65"><code>config_setting_is_aggregate</code></a>: <a href="#The-C-API">The C API</a></li>
2404	<li><a href="#index-config_005fsetting_005fis_005farray-63"><code>config_setting_is_array</code></a>: <a href="#The-C-API">The C API</a></li>
2405	<li><a href="#index-config_005fsetting_005fis_005fgroup-62"><code>config_setting_is_group</code></a>: <a href="#The-C-API">The C API</a></li>
2406	<li><a href="#index-config_005fsetting_005fis_005flist-64"><code>config_setting_is_list</code></a>: <a href="#The-C-API">The C API</a></li>
2407	<li><a href="#index-config_005fsetting_005fis_005fnumber-67"><code>config_setting_is_number</code></a>: <a href="#The-C-API">The C API</a></li>
2408	<li><a href="#index-config_005fsetting_005fis_005froot-58"><code>config_setting_is_root</code></a>: <a href="#The-C-API">The C API</a></li>
2409	<li><a href="#index-config_005fsetting_005fis_005fscalar-66"><code>config_setting_is_scalar</code></a>: <a href="#The-C-API">The C API</a></li>
2410	<li><a href="#index-config_005fsetting_005flength-60"><code>config_setting_length</code></a>: <a href="#The-C-API">The C API</a></li>
2411	<li><a href="#index-config_005fsetting_005fname-56"><code>config_setting_name</code></a>: <a href="#The-C-API">The C API</a></li>
2412	<li><a href="#index-config_005fsetting_005fparent-57"><code>config_setting_parent</code></a>: <a href="#The-C-API">The C API</a></li>
2413	<li><a href="#index-config_005fsetting_005fremove-53"><code>config_setting_remove</code></a>: <a href="#The-C-API">The C API</a></li>
2414	<li><a href="#index-config_005fsetting_005fremove_005felem-54"><code>config_setting_remove_elem</code></a>: <a href="#The-C-API">The C API</a></li>
2415	<li><a href="#index-config_005fsetting_005fset_005fbool-35"><code>config_setting_set_bool</code></a>: <a href="#The-C-API">The C API</a></li>
2416	<li><a href="#index-config_005fsetting_005fset_005fbool_005felem-50"><code>config_setting_set_bool_elem</code></a>: <a href="#The-C-API">The C API</a></li>
2417	<li><a href="#index-config_005fsetting_005fset_005ffloat-34"><code>config_setting_set_float</code></a>: <a href="#The-C-API">The C API</a></li>
2418	<li><a href="#index-config_005fsetting_005fset_005ffloat_005felem-49"><code>config_setting_set_float_elem</code></a>: <a href="#The-C-API">The C API</a></li>
2419	<li><a href="#index-config_005fsetting_005fset_005fformat-38"><code>config_setting_set_format</code></a>: <a href="#The-C-API">The C API</a></li>
2420	<li><a href="#index-config_005fsetting_005fset_005fhook-69"><code>config_setting_set_hook</code></a>: <a href="#The-C-API">The C API</a></li>
2421	<li><a href="#index-config_005fsetting_005fset_005fint-32"><code>config_setting_set_int</code></a>: <a href="#The-C-API">The C API</a></li>
2422	<li><a href="#index-config_005fsetting_005fset_005fint64-33"><code>config_setting_set_int64</code></a>: <a href="#The-C-API">The C API</a></li>
2423	<li><a href="#index-config_005fsetting_005fset_005fint64_005felem-48"><code>config_setting_set_int64_elem</code></a>: <a href="#The-C-API">The C API</a></li>
2424	<li><a href="#index-config_005fsetting_005fset_005fint_005felem-47"><code>config_setting_set_int_elem</code></a>: <a href="#The-C-API">The C API</a></li>
2425	<li><a href="#index-config_005fsetting_005fset_005fstring-36"><code>config_setting_set_string</code></a>: <a href="#The-C-API">The C API</a></li>
2426	<li><a href="#index-config_005fsetting_005fset_005fstring_005felem-51"><code>config_setting_set_string_elem</code></a>: <a href="#The-C-API">The C API</a></li>
2427	<li><a href="#index-config_005fsetting_005fsource_005fline-68"><code>config_setting_source_line</code></a>: <a href="#The-C-API">The C API</a></li>
2428	<li><a href="#index-config_005fsetting_005ftype-61"><code>config_setting_type</code></a>: <a href="#The-C-API">The C API</a></li>
2429	<li><a href="#index-config_005fwrite-15"><code>config_write</code></a>: <a href="#The-C-API">The C API</a></li>
2430	<li><a href="#index-config_005fwrite_005ffile-16"><code>config_write_file</code></a>: <a href="#The-C-API">The C API</a></li>
2431	<li><a href="#index-exists-on-Config-93"><code>exists on Config</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2432	<li><a href="#index-exists-on-Setting-175"><code>exists on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2433	<li><a href="#index-getAutoConvert-on-Config-89"><code>getAutoConvert on Config</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2434	<li><a href="#index-getError-on-ParseException-86"><code>getError on ParseException</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2435	<li><a href="#index-getFormat-on-Setting-172"><code>getFormat on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2436	<li><a href="#index-getIndex-on-Setting-169"><code>getIndex on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2437	<li><a href="#index-getLength-on-Setting-177"><code>getLength on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2438	<li><a href="#index-getLine-on-ParseException-87"><code>getLine on ParseException</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2439	<li><a href="#index-getName-on-Setting-165"><code>getName on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2440	<li><a href="#index-getParent-on-Setting-167"><code>getParent on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2441	<li><a href="#index-getPath-on-Setting-166"><code>getPath on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2442	<li><a href="#index-getRoot-on-Config-90"><code>getRoot on Config</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2443	<li><a href="#index-getSourceLine-on-Setting-184"><code>getSourceLine on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2444	<li><a href="#index-getType-on-Setting-170"><code>getType on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2445	<li><a href="#index-isAggregate-on-Setting-181"><code>isAggregate on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2446	<li><a href="#index-isArray-on-Setting-179"><code>isArray on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2447	<li><a href="#index-isGroup-on-Setting-178"><code>isGroup on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2448	<li><a href="#index-isList-on-Setting-180"><code>isList on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2449	<li><a href="#index-isNumber-on-Setting-183"><code>isNumber on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2450	<li><a href="#index-isRoot-on-Setting-168"><code>isRoot on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2451	<li><a href="#index-isScalar-on-Setting-182"><code>isScalar on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2452	<li><a href="#index-lookup-on-Config-91"><code>lookup on Config</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2453	<li><a href="#index-lookupValue-on-Config-95"><code>lookupValue on Config</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2454	<li><a href="#index-lookupValue-on-Setting-137"><code>lookupValue on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2455	<li><a href="#index-operator-bool_0028_0029-on-Setting-115"><code>operator bool() on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2456	<li><a href="#index-operator-const-char-_002a_0028_0029-on-Setting-124"><code>operator const char *() on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2457	<li><a href="#index-operator-double_0028_0029-on-Setting-123"><code>operator double() on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2458	<li><a href="#index-operator-float_0028_0029-on-Setting-122"><code>operator float() on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2459	<li><a href="#index-operator-int_0028_0029-on-Setting-116"><code>operator int() on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2460	<li><a href="#index-operator-long-long_0028_0029-on-Setting-120"><code>operator long long() on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2461	<li><a href="#index-operator-long_0028_0029-on-Setting-118"><code>operator long() on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2462	<li><a href="#index-operator-std_003a_003astring_0028_0029-on-Setting-125"><code>operator std::string() on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2463	<li><a href="#index-operator-unsigned-int_0028_0029-on-Setting-117"><code>operator unsigned int() on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2464	<li><a href="#index-operator-unsigned-long-long_0028_0029-on-Setting-121"><code>operator unsigned long long() on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2465	<li><a href="#index-operator-unsigned-long_0028_0029-on-Setting-119"><code>operator unsigned long() on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2466	<li><a href="#index-operator_003d-on-Setting-126"><code>operator= on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2467	<li><a href="#index-operator_005b_005d-on-Setting-134"><code>operator[] on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2468	<li><a href="#index-read-on-Config-82"><code>read on Config</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2469	<li><a href="#index-readFile-on-Config-84"><code>readFile on Config</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2470	<li><a href="#index-remove-on-Setting-162"><code>remove on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2471	<li><a href="#index-setAutoConvert-on-Config-88"><code>setAutoConvert on Config</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2472	<li><a href="#index-setFormat-on-Setting-173"><code>setFormat on Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2473	<li><a href="#index-write-on-Config-83"><code>write on Config</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2474	<li><a href="#index-writeFile-on-Config-85"><code>writeFile on Config</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2475	<li><a href="#index-g_t_007eConfig-on-Config-81"><code>~Config on Config</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2476	</ul><div class="node">
2477	<p><hr>
2478	<a name="Type-Index"></a>
2479	Next: <a rel="next" accesskey="n" href="#Concept-Index">Concept Index</a>,
2480	Previous: <a rel="previous" accesskey="p" href="#Function-Index">Function Index</a>,
2481	Up: <a rel="up" accesskey="u" href="#Top">Top</a>
2482
2483	</div>
2484
2485	<!-- node-name, next, previous, up -->
2486	<h2 class="unnumbered">Type Index</h2>
2487
2488
2489
2490	<ul class="index-tp" compact>
2491	<li><a href="#index-Config-72"><code>Config</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2492	<li><a href="#index-config_005fsetting_005ft-10"><code>config_setting_t</code></a>: <a href="#The-C-API">The C API</a></li>
2493	<li><a href="#index-config_005ft-9"><code>config_t</code></a>: <a href="#The-C-API">The C API</a></li>
2494	<li><a href="#index-ConfigException-74"><code>ConfigException</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2495	<li><a href="#index-FileIOException-79"><code>FileIOException</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2496	<li><a href="#index-ParseException-78"><code>ParseException</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2497	<li><a href="#index-Setting-73"><code>Setting</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2498	<li><a href="#index-Setting_003a_003aFormat-174"><code>Setting::Format</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2499	<li><a href="#index-Setting_003a_003aType-171"><code>Setting::Type</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2500	<li><a href="#index-SettingFormat-39"><code>SettingFormat</code></a>: <a href="#The-C-API">The C API</a></li>
2501	<li><a href="#index-SettingNameException-77"><code>SettingNameException</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2502	<li><a href="#index-SettingNotFoundException-76"><code>SettingNotFoundException</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2503	<li><a href="#index-SettingTypeException-75"><code>SettingTypeException</code></a>: <a href="#The-C_002b_002b-API">The C++ API</a></li>
2504	</ul><div class="node">
2505	<p><hr>
2506	<a name="Concept-Index"></a>
2507	Previous: <a rel="previous" accesskey="p" href="#Type-Index">Type Index</a>,
2508	Up: <a rel="up" accesskey="u" href="#Top">Top</a>
2509
2510	</div>
2511
2512	<!-- node-name, next, previous, up -->
2513	<h2 class="unnumbered">Concept Index</h2>
2514
2515
2516
2517	<ul class="index-cp" compact>
2518	<li><a href="#index-array-4">array</a>: <a href="#Configuration-Files">Configuration Files</a></li>
2519	<li><a href="#index-configuration-7">configuration</a>: <a href="#Configuration-Files">Configuration Files</a></li>
2520	<li><a href="#index-group-5">group</a>: <a href="#Configuration-Files">Configuration Files</a></li>
2521	<li><a href="#index-list-6">list</a>: <a href="#Configuration-Files">Configuration Files</a></li>
2522	<li><a href="#index-path-8">path</a>: <a href="#Configuration-Files">Configuration Files</a></li>
2523	<li><a href="#index-scalar-value-3">scalar value</a>: <a href="#Configuration-Files">Configuration Files</a></li>
2524	<li><a href="#index-setting-1">setting</a>: <a href="#Configuration-Files">Configuration Files</a></li>
2525	<li><a href="#index-value-2">value</a>: <a href="#Configuration-Files">Configuration Files</a></li>
2526	</ul></body></html>
2527

Note: See TracBrowser for help on using the browser.

root/branches/libffado-2.0/external/libconfig/libconfig.html

Download in other formats: