root/branches/libffado-2.0/external/libconfig/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:&nbsp;<a rel="next" accesskey="n" href="#Introduction">Introduction</a>,
72 Up:&nbsp;<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:&nbsp;<a rel="next" accesskey="n" href="#Configuration-Files">Configuration Files</a>,
95 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Top">Top</a>,
96 Up:&nbsp;<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:&nbsp;<a rel="next" accesskey="n" href="#Using-the-Library-from-a-C-Program">Using the Library from a C Program</a>,
126 Up:&nbsp;<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 &ldquo;INI&rdquo; 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:&nbsp;<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:&nbsp;<a rel="previous" accesskey="p" href="#Why-Another-Configuration-File-Library_003f">Why Another Configuration File Library?</a>,
158 Up:&nbsp;<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 &lt;libconfig.h&gt;
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:&nbsp;<a rel="next" accesskey="n" href="#Multithreading-Issues">Multithreading Issues</a>,
185 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Using-the-Library-from-a-C-Program">Using the Library from a C Program</a>,
186 Up:&nbsp;<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 &lt;libconfig.h++&gt;
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 &lt;libconfig.hh&gt;
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:&nbsp;<a rel="next" accesskey="n" href="#Compiling-Using-pkg_002dconfig">Compiling Using pkg-config</a>,
235 Previous:&nbsp;<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:&nbsp;<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:&nbsp;<a rel="previous" accesskey="p" href="#Multithreading-Issues">Multithreading Issues</a>,
274 Up:&nbsp;<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:&nbsp;<a rel="next" accesskey="n" href="#The-C-API">The C API</a>,
309 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Introduction">Introduction</a>,
310 Up:&nbsp;<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:&nbsp;<a rel="next" accesskey="n" href="#Groups">Groups</a>,
435 Up:&nbsp;<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:&nbsp;<a rel="next" accesskey="n" href="#Arrays">Arrays</a>,
458 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Settings">Settings</a>,
459 Up:&nbsp;<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:&nbsp;<a rel="next" accesskey="n" href="#Lists">Lists</a>,
479 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Groups">Groups</a>,
480 Up:&nbsp;<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:&nbsp;<a rel="next" accesskey="n" href="#Integer-Values">Integer Values</a>,
498 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Arrays">Arrays</a>,
499 Up:&nbsp;<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:&nbsp;<a rel="next" accesskey="n" href="#g_t64_002dbit-Integer-Values">64-bit Integer Values</a>,
517 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Lists">Lists</a>,
518 Up:&nbsp;<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:&nbsp;<a rel="next" accesskey="n" href="#Floating-Point-Values">Floating Point Values</a>,
537 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Integer-Values">Integer Values</a>,
538 Up:&nbsp;<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:&nbsp;<a rel="next" accesskey="n" href="#Boolean-Values">Boolean Values</a>,
553 Previous:&nbsp;<a rel="previous" accesskey="p" href="#g_t64_002dbit-Integer-Values">64-bit Integer Values</a>,
554 Up:&nbsp;<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:&nbsp;<a rel="next" accesskey="n" href="#String-Values">String Values</a>,
571 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Floating-Point-Values">Floating Point Values</a>,
572 Up:&nbsp;<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:&nbsp;<a rel="next" accesskey="n" href="#Comments">Comments</a>,
586 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Boolean-Values">Boolean Values</a>,
587 Up:&nbsp;<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:&nbsp;<a rel="previous" accesskey="p" href="#String-Values">String Values</a>,
619 Up:&nbsp;<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:&nbsp;<a rel="next" accesskey="n" href="#The-C_002b_002b-API">The C++ API</a>,
652 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Configuration-Files">Configuration Files</a>,
653 Up:&nbsp;<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 &mdash; Function: void <b>config_init</b> (<var>config_t&nbsp;*&nbsp;config<!-- /@w --></var>)<var><a name="index-config_005finit-11"></a></var><br>
669 &mdash; Function: void <b>config_destroy</b> (<var>config_t&nbsp;*&nbsp;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 &mdash; Function: int <b>config_read</b> (<var>config_t&nbsp;*&nbsp;config<!-- /@w -->, FILE&nbsp;*&nbsp;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 &mdash; Function: int <b>config_read_file</b> (<var>config_t&nbsp;*&nbsp;config<!-- /@w -->, const&nbsp;char&nbsp;*&nbsp;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 &mdash; Function: void <b>config_write</b> (<var>const&nbsp;config_t&nbsp;*&nbsp;config<!-- /@w -->, FILE&nbsp;*&nbsp;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 &mdash; Function: int <b>config_write_file</b> (<var>config_t&nbsp;*&nbsp;config<!-- /@w -->, const&nbsp;char&nbsp;*&nbsp;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 &mdash; Function: const char * <b>config_error_text</b> (<var>const&nbsp;config_t&nbsp;*&nbsp;config<!-- /@w --></var>)<var><a name="index-config_005ferror_005ftext-17"></a></var><br>
724 &mdash; Function: int <b>config_error_line</b> (<var>const&nbsp;config_t&nbsp;*&nbsp;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 &mdash; Function: void <b>config_set_auto_convert</b> (<var>config_t&nbsp;*config<!-- /@w -->, int&nbsp;flag<!-- /@w --></var>)<var><a name="index-config_005fset_005fauto_005fconvert-19"></a></var><br>
737 &mdash; Function: int <b>config_get_auto_convert</b> (<var>const&nbsp;config_t&nbsp;*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 &mdash; Function: long <b>config_lookup_int</b> (<var>const&nbsp;config_t&nbsp;*&nbsp;config<!-- /@w -->, const&nbsp;char&nbsp;*&nbsp;path<!-- /@w --></var>)<var><a name="index-config_005flookup_005fint-21"></a></var><br>
756 &mdash; Function: long long <b>config_lookup_int64</b> (<var>const&nbsp;config_t&nbsp;*&nbsp;config<!-- /@w -->, const&nbsp;char&nbsp;*&nbsp;path<!-- /@w --></var>)<var><a name="index-config_005flookup_005fint64-22"></a></var><br>
757 &mdash; Function: double <b>config_lookup_float</b> (<var>const&nbsp;config_t&nbsp;*&nbsp;config<!-- /@w -->, const&nbsp;char&nbsp;*&nbsp;path<!-- /@w --></var>)<var><a name="index-config_005flookup_005ffloat-23"></a></var><br>
758 &mdash; Function: int <b>config_lookup_bool</b> (<var>const&nbsp;config_t&nbsp;*&nbsp;config<!-- /@w -->, const&nbsp;char&nbsp;*&nbsp;path<!-- /@w --></var>)<var><a name="index-config_005flookup_005fbool-24"></a></var><br>
759 &mdash; Function: const char * <b>config_lookup_string</b> (<var>const&nbsp;config_t&nbsp;*&nbsp;config<!-- /@w -->, const&nbsp;char&nbsp;*&nbsp;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 &mdash; Function: config_setting_t * <b>config_lookup</b> (<var>const&nbsp;config_t&nbsp;*&nbsp;config<!-- /@w -->, const&nbsp;char&nbsp;*&nbsp;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 &mdash; Function: long <b>config_setting_get_int</b> (<var>const&nbsp;config_setting_t&nbsp;*&nbsp;setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fget_005fint-27"></a></var><br>
785 &mdash; Function: long long <b>config_setting_get_int64</b> (<var>const&nbsp;config_setting_t&nbsp;*&nbsp;setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fget_005fint64-28"></a></var><br>
786 &mdash; Function: double <b>config_setting_get_float</b> (<var>const&nbsp;config_setting_t&nbsp;*&nbsp;setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fget_005ffloat-29"></a></var><br>
787 &mdash; Function: int <b>config_setting_get_bool</b> (<var>const&nbsp;config_setting_t&nbsp;*&nbsp;setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fget_005fbool-30"></a></var><br>
788 &mdash; Function: const char * <b>config_setting_get_string</b> (<var>const&nbsp;config_setting_t&nbsp;*&nbsp;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 &mdash; Function: int <b>config_setting_set_int</b> (<var>config_setting_t&nbsp;*&nbsp;setting<!-- /@w -->, long&nbsp;value<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fset_005fint-32"></a></var><br>
802 &mdash; Function: int <b>config_setting_set_int64</b> (<var>config_setting_t&nbsp;*&nbsp;setting<!-- /@w -->, long&nbsp;long&nbsp;value<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fset_005fint64-33"></a></var><br>
803 &mdash; Function: int <b>config_setting_set_float</b> (<var>config_setting_t&nbsp;*&nbsp;setting<!-- /@w -->, double&nbsp;value<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fset_005ffloat-34"></a></var><br>
804 &mdash; Function: int <b>config_setting_set_bool</b> (<var>config_setting_t&nbsp;*&nbsp;setting<!-- /@w -->, int&nbsp;value<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fset_005fbool-35"></a></var><br>
805 &mdash; Function: int <b>config_setting_set_string</b> (<var>config_setting_t&nbsp;*&nbsp;setting<!-- /@w -->, const&nbsp;char&nbsp;*&nbsp;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 &mdash; Function: short <b>config_setting_get_format</b> (<var>config_setting_t&nbsp;*&nbsp;setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fget_005fformat-37"></a></var><br>
818 &mdash; Function: int <b>config_setting_set_format</b> (<var>config_setting_t&nbsp;*&nbsp;setting<!-- /@w -->, short&nbsp;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 &mdash; Function: config_setting_t * <b>config_setting_get_member</b> (<var>config_setting_t&nbsp;*&nbsp;setting<!-- /@w -->, const&nbsp;char&nbsp;*&nbsp;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 &mdash; Function: config_setting_t * <b>config_setting_get_elem</b> (<var>const&nbsp;config_setting_t&nbsp;*&nbsp;setting<!-- /@w -->, unsigned&nbsp;int&nbsp;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 &mdash; Function: long <b>config_setting_get_int_elem</b> (<var>const&nbsp;config_setting_t&nbsp;*&nbsp;setting<!-- /@w -->, int&nbsp;idx<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fget_005fint_005felem-42"></a></var><br>
858 &mdash; Function: long long <b>config_setting_get_int64_elem</b> (<var>const&nbsp;config_setting_t&nbsp;*&nbsp;setting<!-- /@w -->, int&nbsp;idx<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fget_005fint64_005felem-43"></a></var><br>
859 &mdash; Function: double <b>config_setting_get_float_elem</b> (<var>const&nbsp;config_setting_t&nbsp;*&nbsp;setting<!-- /@w -->, int&nbsp;idx<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fget_005ffloat_005felem-44"></a></var><br>
860 &mdash; Function: int <b>config_setting_get_bool_elem</b> (<var>const&nbsp;config_setting_t&nbsp;*&nbsp;setting<!-- /@w -->, int&nbsp;idx<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fget_005fbool_005felem-45"></a></var><br>
861 &mdash; Function: const char * <b>config_setting_get_string_elem</b> (<var>const&nbsp;config_setting_t&nbsp;*&nbsp;setting<!-- /@w -->, int&nbsp;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 &mdash; Function: config_setting_t * <b>config_setting_set_int_elem</b> (<var>config_setting_t&nbsp;*&nbsp;setting<!-- /@w -->, int&nbsp;idx<!-- /@w -->, long&nbsp;value<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fset_005fint_005felem-47"></a></var><br>
875 &mdash; Function: config_setting_t * <b>config_setting_set_int64_elem</b> (<var>config_setting_t&nbsp;*&nbsp;setting<!-- /@w -->, int&nbsp;idx<!-- /@w -->, long&nbsp;long&nbsp;value<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fset_005fint64_005felem-48"></a></var><br>
876 &mdash; Function: config_setting_t * <b>config_setting_set_float_elem</b> (<var>config_setting_t&nbsp;*&nbsp;setting<!-- /@w -->, int&nbsp;idx<!-- /@w -->, double&nbsp;value<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fset_005ffloat_005felem-49"></a></var><br>
877 &mdash; Function: config_setting_t * <b>config_setting_set_bool_elem</b> (<var>config_setting_t&nbsp;*&nbsp;setting<!-- /@w -->, int&nbsp;idx<!-- /@w -->, int&nbsp;value<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fset_005fbool_005felem-50"></a></var><br>
878 &mdash; Function: config_setting_t * <b>config_setting_set_string_elem</b> (<var>config_setting_t&nbsp;*&nbsp;setting<!-- /@w -->, int&nbsp;idx<!-- /@w -->, const&nbsp;char&nbsp;*&nbsp;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 &mdash; Function: config_setting_t * <b>config_setting_add</b> (<var>config_setting_t&nbsp;*&nbsp;parent<!-- /@w -->, const&nbsp;char&nbsp;*&nbsp;name<!-- /@w -->, int&nbsp;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 &mdash; Function: int <b>config_setting_remove</b> (<var>config_setting_t&nbsp;*&nbsp;parent<!-- /@w -->, const&nbsp;char&nbsp;*&nbsp;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 &mdash; Function: int <b>config_setting_remove_elem</b> (<var>config_setting_t&nbsp;*&nbsp;parent<!-- /@w -->, unsigned&nbsp;int&nbsp;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 &mdash; Function: config_setting_t * <b>config_root_setting</b> (<var>const&nbsp;config_t&nbsp;*&nbsp;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 &mdash; Function: const char * <b>config_setting_name</b> (<var>const&nbsp;config_setting_t&nbsp;*&nbsp;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 &mdash; Function: config_setting_t * <b>config_setting_parent</b> (<var>const&nbsp;config_setting_t&nbsp;*&nbsp;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 &mdash; Function: int <b>config_setting_is_root</b> (<var>const&nbsp;config_setting_t&nbsp;*&nbsp;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 &mdash; Function: int <b>config_setting_index</b> (<var>const&nbsp;config_setting_t&nbsp;*&nbsp;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 &mdash; Function: int <b>config_setting_length</b> (<var>const&nbsp;config_setting_t&nbsp;*&nbsp;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 &mdash; Function: int <b>config_setting_type</b> (<var>const&nbsp;config_setting_t&nbsp;*&nbsp;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 &mdash; Function: int <b>config_setting_is_group</b> (<var>const&nbsp;config_setting_t&nbsp;*&nbsp;setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fis_005fgroup-62"></a></var><br>
998 &mdash; Function: int <b>config_setting_is_array</b> (<var>const&nbsp;config_setting_t&nbsp;*&nbsp;setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fis_005farray-63"></a></var><br>
999 &mdash; Function: int <b>config_setting_is_list</b> (<var>const&nbsp;config_setting_t&nbsp;*&nbsp;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 &mdash; Function: int <b>config_setting_is_aggregate</b> (<var>const&nbsp;config_setting_t&nbsp;*&nbsp;setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fis_005faggregate-65"></a></var><br>
1009 &mdash; Function: int <b>config_setting_is_scalar</b> (<var>const&nbsp;config_setting_t&nbsp;*&nbsp;setting<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fis_005fscalar-66"></a></var><br>
1010 &mdash; Function: int <b>config_setting_is_number</b> (<var>const&nbsp;config_setting_t&nbsp;*&nbsp;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 &mdash; Function: unsigned int <b>config_setting_source_line</b> (<var>const&nbsp;config_setting_t&nbsp;*&nbsp;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 &mdash; Function: void <b>config_setting_set_hook</b> (<var>config_setting_t&nbsp;*&nbsp;setting<!-- /@w -->, void&nbsp;*&nbsp;hook<!-- /@w --></var>)<var><a name="index-config_005fsetting_005fset_005fhook-69"></a></var><br>
1034 &mdash; Function: void * <b>config_setting_get_hook</b> (<var>const&nbsp;config_setting_t&nbsp;*&nbsp;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 &ldquo;wrapper&rdquo; or &ldquo;peer&rdquo; 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 &mdash; Function: void <b>config_set_destructor</b> (<var>config_t&nbsp;*&nbsp;config<!-- /@w -->, void&nbsp;(*&nbsp;destructor)(void&nbsp;*)<!-- /@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:&nbsp;<a rel="next" accesskey="n" href="#Configuration-File-Grammar">Configuration File Grammar</a>,
1060 Previous:&nbsp;<a rel="previous" accesskey="p" href="#The-C-API">The C API</a>,
1061 Up:&nbsp;<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 &mdash; Method on Config:  <b>Config</b> ()<var><a name="index-Config-on-Config-80"></a></var><br>
1097 &mdash; 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 &mdash; Method on Config: void <b>read</b> (<var>FILE&nbsp;*&nbsp;stream<!-- /@w --></var>)<var><a name="index-read-on-Config-82"></a></var><br>
1105 &mdash; Method on Config: void <b>write</b> (<var>FILE&nbsp;*&nbsp;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 &mdash; Method on Config: void <b>readFile</b> (<var>const&nbsp;char&nbsp;*&nbsp;filename<!-- /@w --></var>)<var><a name="index-readFile-on-Config-84"></a></var><br>
1116 &mdash; Method on Config: void <b>writeFile</b> (<var>const&nbsp;char&nbsp;*&nbsp;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 &mdash; Method on ParseException: const char * <b>getError</b> ()<var><a name="index-getError-on-ParseException-86"></a></var><br>
1130 &mdash; 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 &mdash; Method on Config: void <b>setAutoConvert</b> (<var>bool flag</var>)<var><a name="index-setAutoConvert-on-Config-88"></a></var><br>
1142 &mdash; 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 &mdash; Method on Config: Setting &amp; <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 &mdash; Method on Config: Setting &amp; <b>lookup</b> (<var>const&nbsp;std::string&nbsp;&amp;path<!-- /@w --></var>)<var><a name="index-lookup-on-Config-91"></a></var><br>
1168 &mdash; Method on Config: Setting &amp; <b>lookup</b> (<var>const&nbsp;char&nbsp;*&nbsp;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 &mdash; Method on Config: bool <b>exists</b> (<var>const&nbsp;std::string&nbsp;&amp;path<!-- /@w --></var>)<var><a name="index-exists-on-Config-93"></a></var><br>
1178 &mdash; Method on Config: bool <b>exists</b> (<var>const&nbsp;char&nbsp;*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 &mdash; Method on Config: bool <b>lookupValue</b> (<var>const&nbsp;char&nbsp;*path<!-- /@w -->, bool&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-95"></a></var><br>
1188 &mdash; Method on Config: bool <b>lookupValue</b> (<var>const&nbsp;std::string&nbsp;&amp;path<!-- /@w -->, bool&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-96"></a></var><br>
1189
1190 &mdash; Method on Config: bool <b>lookupValue</b> (<var>const&nbsp;char&nbsp;*path<!-- /@w -->, int&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-97"></a></var><br>
1191 &mdash; Method on Config: bool <b>lookupValue</b> (<var>const&nbsp;std::string&nbsp;&amp;path<!-- /@w -->, int&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-98"></a></var><br>
1192
1193 &mdash; Method on Config: bool <b>lookupValue</b> (<var>const&nbsp;char&nbsp;*path<!-- /@w -->, unsigned&nbsp;int&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-99"></a></var><br>
1194 &mdash; Method on Config: bool <b>lookupValue</b> (<var>const&nbsp;std::string&nbsp;&amp;path<!-- /@w -->, unsigned&nbsp;int&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-100"></a></var><br>
1195
1196 &mdash; Method on Config: bool <b>lookupValue</b> (<var>const&nbsp;char&nbsp;*path<!-- /@w -->, long&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-101"></a></var><br>
1197 &mdash; Method on Config: bool <b>lookupValue</b> (<var>const&nbsp;std::string&nbsp;&amp;path<!-- /@w -->, long&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-102"></a></var><br>
1198
1199 &mdash; Method on Config: bool <b>lookupValue</b> (<var>const&nbsp;char&nbsp;*path<!-- /@w -->, long&nbsp;long&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-103"></a></var><br>
1200 &mdash; Method on Config: bool <b>lookupValue</b> (<var>const&nbsp;std::string&nbsp;&amp;path<!-- /@w -->, long&nbsp;long&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-104"></a></var><br>
1201
1202 &mdash; Method on Config: bool <b>lookupValue</b> (<var>const&nbsp;char&nbsp;*path<!-- /@w -->, unsigned&nbsp;long&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-105"></a></var><br>
1203 &mdash; Method on Config: bool <b>lookupValue</b> (<var>const&nbsp;std::string&nbsp;&amp;path<!-- /@w -->, unsigned&nbsp;long&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-106"></a></var><br>
1204
1205 &mdash; Method on Config: bool <b>lookupValue</b> (<var>const&nbsp;char&nbsp;*path<!-- /@w -->, float&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-107"></a></var><br>
1206 &mdash; Method on Config: bool <b>lookupValue</b> (<var>const&nbsp;std::string&nbsp;&amp;path<!-- /@w -->, float&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-108"></a></var><br>
1207
1208 &mdash; Method on Config: bool <b>lookupValue</b> (<var>const&nbsp;char&nbsp;*path<!-- /@w -->, double&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-109"></a></var><br>
1209 &mdash; Method on Config: bool <b>lookupValue</b> (<var>const&nbsp;std::string&nbsp;&amp;path<!-- /@w -->, double&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-110"></a></var><br>
1210
1211 &mdash; Method on Config: bool <b>lookupValue</b> (<var>const&nbsp;char&nbsp;*path<!-- /@w -->, const&nbsp;char&nbsp;*&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-111"></a></var><br>
1212 &mdash; Method on Config: bool <b>lookupValue</b> (<var>const&nbsp;std::string&nbsp;&amp;path<!-- /@w -->, const&nbsp;char&nbsp;*&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-112"></a></var><br>
1213
1214 &mdash; Method on Config: bool <b>lookupValue</b> (<var>const&nbsp;char&nbsp;*path<!-- /@w -->, std::string&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Config-113"></a></var><br>
1215 &mdash; Method on Config: bool <b>lookupValue</b> (<var>const&nbsp;std::string&nbsp;&amp;path<!-- /@w -->, std::string&nbsp;&amp;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&nbsp;char&nbsp;*</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              &amp;&amp; config.lookupValue("values.var2", var2)
1245              &amp;&amp; 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 &mdash; Method on Setting:  <b>operator bool()</b><var><a name="index-operator-bool_0028_0029-on-Setting-115"></a></var><br>
1264 &mdash; Method on Setting:  <b>operator int()</b><var><a name="index-operator-int_0028_0029-on-Setting-116"></a></var><br>
1265 &mdash; Method on Setting:  <b>operator unsigned int()</b><var><a name="index-operator-unsigned-int_0028_0029-on-Setting-117"></a></var><br>
1266 &mdash; Method on Setting:  <b>operator long()</b><var><a name="index-operator-long_0028_0029-on-Setting-118"></a></var><br>
1267 &mdash; Method on Setting:  <b>operator unsigned long()</b><var><a name="index-operator-unsigned-long_0028_0029-on-Setting-119"></a></var><br>
1268 &mdash; Method on Setting:  <b>operator long long()</b><var><a name="index-operator-long-long_0028_0029-on-Setting-120"></a></var><br>
1269 &mdash; 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 &mdash; Method on Setting:  <b>operator float()</b><var><a name="index-operator-float_0028_0029-on-Setting-122"></a></var><br>
1271 &mdash; Method on Setting:  <b>operator double()</b><var><a name="index-operator-double_0028_0029-on-Setting-123"></a></var><br>
1272 &mdash; 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 &mdash; 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&nbsp;char&nbsp;*</i><!-- /@w --> or <i>std::string</i> if it is
1281 of type <code>TypeString</code>.
1282
1283         <p>Storage for <i>const&nbsp;char&nbsp;*</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 &amp;</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 &mdash; Method on Setting: Setting &amp; <b>operator=</b> (<var>bool&nbsp;value<!-- /@w --></var>)<var><a name="index-operator_003d-on-Setting-126"></a></var><br>
1349 &mdash; Method on Setting: Setting &amp; <b>operator=</b> (<var>int&nbsp;value<!-- /@w --></var>)<var><a name="index-operator_003d-on-Setting-127"></a></var><br>
1350 &mdash; Method on Setting: Setting &amp; <b>operator=</b> (<var>long&nbsp;value<!-- /@w --></var>)<var><a name="index-operator_003d-on-Setting-128"></a></var><br>
1351 &mdash; Method on Setting: Setting &amp; <b>operator=</b> (<var>const&nbsp;long&nbsp;long&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-operator_003d-on-Setting-129"></a></var><br>
1352 &mdash; Method on Setting: Setting &amp; <b>operator=</b> (<var>float&nbsp;value<!-- /@w --></var>)<var><a name="index-operator_003d-on-Setting-130"></a></var><br>
1353 &mdash; Method on Setting: Setting &amp; <b>operator=</b> (<var>const&nbsp;double&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-operator_003d-on-Setting-131"></a></var><br>
1354 &mdash; Method on Setting: Setting &amp; <b>operator=</b> (<var>const&nbsp;char&nbsp;*value<!-- /@w --></var>)<var><a name="index-operator_003d-on-Setting-132"></a></var><br>
1355 &mdash; Method on Setting: Setting &amp; <b>operator=</b> (<var>const&nbsp;std::string&nbsp;&amp;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 &mdash; Method on Setting: Setting &amp; <b>operator[]</b> (<var>int&nbsp;idx<!-- /@w --></var>)<var><a name="index-operator_005b_005d-on-Setting-134"></a></var><br>
1371 &mdash; Method on Setting: Setting &amp; <b>operator[]</b> (<var>const&nbsp;std::string&nbsp;&amp;name<!-- /@w --></var>)<var><a name="index-operator_005b_005d-on-Setting-135"></a></var><br>
1372 &mdash; Method on Setting: Setting &amp; <b>operator[]</b> (<var>const&nbsp;char&nbsp;*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&amp; 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 &mdash; Method on Setting: bool <b>lookupValue</b> (<var>const&nbsp;char&nbsp;*name<!-- /@w -->, bool&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-137"></a></var><br>
1399 &mdash; Method on Setting: bool <b>lookupValue</b> (<var>const&nbsp;std::string&nbsp;&amp;name<!-- /@w -->, bool&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-138"></a></var><br>
1400
1401 &mdash; Method on Setting: bool <b>lookupValue</b> (<var>const&nbsp;char&nbsp;*name<!-- /@w -->, int&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-139"></a></var><br>
1402 &mdash; Method on Setting: bool <b>lookupValue</b> (<var>const&nbsp;std::string&nbsp;&amp;name<!-- /@w -->, int&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-140"></a></var><br>
1403
1404 &mdash; Method on Setting: bool <b>lookupValue</b> (<var>const&nbsp;char&nbsp;*name<!-- /@w -->, unsigned&nbsp;int&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-141"></a></var><br>
1405 &mdash; Method on Setting: bool <b>lookupValue</b> (<var>const&nbsp;std::string&nbsp;&amp;name<!-- /@w -->, unsigned&nbsp;int&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-142"></a></var><br>
1406
1407 &mdash; Method on Setting: bool <b>lookupValue</b> (<var>const&nbsp;char&nbsp;*name<!-- /@w -->, long&nbsp;long&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-143"></a></var><br>
1408 &mdash; Method on Setting: bool <b>lookupValue</b> (<var>const&nbsp;std::string&nbsp;&amp;name<!-- /@w -->, long&nbsp;long&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-144"></a></var><br>
1409
1410 &mdash; Method on Setting: bool <b>lookupValue</b> (<var>const&nbsp;char&nbsp;*name<!-- /@w -->, unsigned&nbsp;long&nbsp;long&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-145"></a></var><br>
1411 &mdash; Method on Setting: bool <b>lookupValue</b> (<var>const&nbsp;std::string&nbsp;&amp;name<!-- /@w -->, unsigned&nbsp;long&nbsp;long&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-146"></a></var><br>
1412
1413 &mdash; Method on Setting: bool <b>lookupValue</b> (<var>const&nbsp;char&nbsp;*name<!-- /@w -->, long&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-147"></a></var><br>
1414 &mdash; Method on Setting: bool <b>lookupValue</b> (<var>const&nbsp;std::string&nbsp;&amp;name<!-- /@w -->, long&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-148"></a></var><br>
1415
1416 &mdash; Method on Setting: bool <b>lookupValue</b> (<var>const&nbsp;char&nbsp;*name<!-- /@w -->, unsigned&nbsp;long&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-149"></a></var><br>
1417 &mdash; Method on Setting: bool <b>lookupValue</b> (<var>const&nbsp;std::string&nbsp;&amp;name<!-- /@w -->, unsigned&nbsp;long&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-150"></a></var><br>
1418
1419 &mdash; Method on Setting: bool <b>lookupValue</b> (<var>const&nbsp;char&nbsp;*name<!-- /@w -->, float&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-151"></a></var><br>
1420 &mdash; Method on Setting: bool <b>lookupValue</b> (<var>const&nbsp;std::string&nbsp;&amp;name<!-- /@w -->, float&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-152"></a></var><br>
1421
1422 &mdash; Method on Setting: bool <b>lookupValue</b> (<var>const&nbsp;char&nbsp;*name<!-- /@w -->, double&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-153"></a></var><br>
1423 &mdash; Method on Setting: bool <b>lookupValue</b> (<var>const&nbsp;std::string&nbsp;&amp;name<!-- /@w -->, double&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-154"></a></var><br>
1424
1425 &mdash; Method on Setting: bool <b>lookupValue</b> (<var>const&nbsp;char&nbsp;*name<!-- /@w -->, const&nbsp;char&nbsp;*&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-155"></a></var><br>
1426 &mdash; Method on Setting: bool <b>lookupValue</b> (<var>const&nbsp;std::string&nbsp;&amp;name<!-- /@w -->, const&nbsp;char&nbsp;*&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-156"></a></var><br>
1427
1428 &mdash; Method on Setting: bool <b>lookupValue</b> (<var>const&nbsp;char&nbsp;*name<!-- /@w -->, std::string&nbsp;&amp;value<!-- /@w --></var>)<var><a name="index-lookupValue-on-Setting-157"></a></var><br>
1429 &mdash; Method on Setting: bool <b>lookupValue</b> (<var>const&nbsp;std::string&nbsp;&amp;name<!-- /@w -->, std::string&nbsp;&amp;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&nbsp;char&nbsp;*</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              &amp;&amp; setting.lookupValue("var2", var2)
1459              &amp;&amp; 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 &mdash; Method on Setting: Setting &amp; <b>add</b> (<var>const&nbsp;std::string&nbsp;&amp;name<!-- /@w -->, Setting::Type&nbsp;type<!-- /@w --></var>)<var><a name="index-add-on-Setting-159"></a></var><br>
1478 &mdash; Method on Setting: Setting &amp; <b>add</b> (<var>const&nbsp;char&nbsp;*name<!-- /@w -->, Setting::Type&nbsp;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 &mdash; Method on Setting: Setting &amp; <b>add</b> (<var>Setting::Type&nbsp;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 &mdash; Method on Setting: void <b>remove</b> (<var>const&nbsp;std::string&nbsp;&amp;name<!-- /@w --></var>)<var><a name="index-remove-on-Setting-162"></a></var><br>
1513 &mdash; Method on Setting: void <b>remove</b> (<var>const&nbsp;char&nbsp;*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 &mdash; Method on Setting: void <b>remove</b> (<var>unsigned&nbsp;int&nbsp;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 &mdash; 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 &mdash; 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 &mdash; Method on Setting: Setting &amp; <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 &mdash; 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 &mdash; 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 &mdash; 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 &mdash; Method on Setting: Setting::Format <b>getFormat</b> ()<var><a name="index-getFormat-on-Setting-172"></a></var><br>
1595 &mdash; Method on Setting: void <b>setFormat</b> (<var>Setting::Format&nbsp;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 &mdash; Method on Setting: bool <b>exists</b> (<var>const&nbsp;std::string&nbsp;&amp;name<!-- /@w --></var>)<var><a name="index-exists-on-Setting-175"></a></var><br>
1610 &mdash; Method on Setting: bool <b>exists</b> (<var>const&nbsp;char&nbsp;*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 &mdash; 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 &mdash; Method on Setting: bool <b>isGroup</b> ()<var><a name="index-isGroup-on-Setting-178"></a></var><br>
1629 &mdash; Method on Setting: bool <b>isArray</b> ()<var><a name="index-isArray-on-Setting-179"></a></var><br>
1630 &mdash; 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 &mdash; Method on Setting: bool <b>isAggregate</b> ()<var><a name="index-isAggregate-on-Setting-181"></a></var><br>
1638 &mdash; Method on Setting: bool <b>isScalar</b> ()<var><a name="index-isScalar-on-Setting-182"></a></var><br>
1639 &mdash; 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 &mdash; 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:&nbsp;<a rel="next" accesskey="n" href="#License">License</a>,
1663 Previous:&nbsp;<a rel="previous" accesskey="p" href="#The-C_002b_002b-API">The C++ API</a>,
1664 Up:&nbsp;<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:&nbsp;<a rel="next" accesskey="n" href="#Function-Index">Function Index</a>,
1730 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Configuration-File-Grammar">Configuration File Grammar</a>,
1731 Up:&nbsp;<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 &copy; 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&ndash;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&ndash;typically libraries&ndash;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 &ldquo;Lesser&rdquo; 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 &ldquo;work based on the library&rdquo; and a &ldquo;work that uses the library&rdquo;.  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 &ldquo;this License&rdquo;).  Each
1877 licensee is addressed as &ldquo;you&rdquo;.
1878
1879      <p>A &ldquo;library&rdquo; 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 &ldquo;Library&rdquo;, below, refers to any such software library or work which
1884 has been distributed under these terms.  A &ldquo;work based on the Library&rdquo;
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 &ldquo;modification&rdquo;.)
1890
1891      <p>&ldquo;Source code&rdquo; 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 &ldquo;work that uses the Library&rdquo;.  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 &ldquo;work that uses the Library&rdquo; 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 &ldquo;work that uses the library&rdquo;.
2028 The executable is therefore covered by this License.  Section 6 states
2029 terms for distribution of such executables.
2030
2031      <p>When a &ldquo;work that uses the Library&rdquo; 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 &ldquo;work that uses the Library&rdquo; 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 &ldquo;work that uses the Library&rdquo;, 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 &ldquo;work that uses the Library&rdquo;
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 &ldquo;any
2248 later version&rdquo;, 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 &ldquo;AS IS&rdquo; 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 &ldquo;copyright&rdquo; line and a pointer to where the full notice is
2318 found.
2319
2320 <pre class="format"><tt>
2321 &lt;one line to give the library's name and a brief idea of what it does.&gt;
2322 Copyright (C) &lt;year&gt;  &lt;name of author&gt;
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 &ldquo;copyright disclaimer&rdquo; 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 &lt;signature of Ty Coon&gt;, 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:&nbsp;<a rel="next" accesskey="n" href="#Type-Index">Type Index</a>,
2360 Previous:&nbsp;<a rel="previous" accesskey="p" href="#License">License</a>,
2361 Up:&nbsp;<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:&nbsp;<a rel="next" accesskey="n" href="#Concept-Index">Concept Index</a>,
2480 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Function-Index">Function Index</a>,
2481 Up:&nbsp;<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:&nbsp;<a rel="previous" accesskey="p" href="#Type-Index">Type Index</a>,
2508 Up:&nbsp;<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.