1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- Created by GNU Texinfo 6.1, http://www.gnu.org/software/texinfo/ --> 4<head> 5<title>libconfig</title> 6 7<meta name="description" content="libconfig"> 8<meta name="keywords" content="libconfig"> 9<meta name="resource-type" content="document"> 10<meta name="distribution" content="global"> 11<meta name="Generator" content="makeinfo"> 12<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 13<link href="#Top" rel="start" title="Top"> 14<link href="#Function-Index" rel="index" title="Function Index"> 15<link href="#SEC_Contents" rel="contents" title="Table of Contents"> 16<link href="dir.html#Top" rel="up" title="(dir)"> 17<style type="text/css"> 18<!-- 19a.summary-letter {text-decoration: none} 20blockquote.indentedblock {margin-right: 0em} 21blockquote.smallindentedblock {margin-right: 0em; font-size: smaller} 22blockquote.smallquotation {font-size: smaller} 23div.display {margin-left: 3.2em} 24div.example {margin-left: 3.2em} 25div.lisp {margin-left: 3.2em} 26div.smalldisplay {margin-left: 3.2em} 27div.smallexample {margin-left: 3.2em} 28div.smalllisp {margin-left: 3.2em} 29kbd {font-style: oblique} 30pre.display {font-family: inherit} 31pre.format {font-family: inherit} 32pre.menu-comment {font-family: serif} 33pre.menu-preformatted {font-family: serif} 34pre.smalldisplay {font-family: inherit; font-size: smaller} 35pre.smallexample {font-size: smaller} 36pre.smallformat {font-family: inherit; font-size: smaller} 37pre.smalllisp {font-size: smaller} 38span.nolinebreak {white-space: nowrap} 39span.roman {font-family: initial; font-weight: normal} 40span.sansserif {font-family: sans-serif; font-weight: normal} 41ul.no-bullet {list-style: none} 42--> 43</style> 44 45 46</head> 47 48<body lang="en"> 49<h1 class="settitle" align="center">libconfig</h1> 50 51 52 53 54 55 56 57 58 59<hr noshade size=6 color="black"> 60<div align=right>A Library For Processing Structured Configuration Files<br> 61Version 1.7.2<br> 625 Jan 2018</div> 63<br><br><br><br> 64<font size=+1>Mark A. Lindner</font> 65<hr size=3 noshade color="black"> 66<br><br> 67 68<a name="SEC_Contents"></a> 69<h2 class="contents-heading">Table of Contents</h2> 70 71<div class="contents"> 72 73<ul class="no-bullet"> 74 <li><a name="toc-Introduction-1" href="#Introduction">1 Introduction</a> 75 <ul class="no-bullet"> 76 <li><a name="toc-Why-Another-Configuration-File-Library_003f-1" href="#Why-Another-Configuration-File-Library_003f">1.1 Why Another Configuration File Library?</a></li> 77 <li><a name="toc-Using-the-Library-from-a-C-Program-1" href="#Using-the-Library-from-a-C-Program">1.2 Using the Library from a C Program</a></li> 78 <li><a name="toc-Using-the-Library-from-a-C_002b_002b-Program-1" href="#Using-the-Library-from-a-C_002b_002b-Program">1.3 Using the Library from a C++ Program</a></li> 79 <li><a name="toc-Multithreading-Issues-1" href="#Multithreading-Issues">1.4 Multithreading Issues</a></li> 80 <li><a name="toc-Internationalization-Issues-1" href="#Internationalization-Issues">1.5 Internationalization Issues</a></li> 81 <li><a name="toc-Compiling-Using-pkg_002dconfig-1" href="#Compiling-Using-pkg_002dconfig">1.6 Compiling Using pkg-config</a></li> 82 <li><a name="toc-Version-Test-Macros-1" href="#Version-Test-Macros">1.7 Version Test Macros</a></li> 83 </ul></li> 84 <li><a name="toc-Configuration-Files-1" href="#Configuration-Files">2 Configuration Files</a> 85 <ul class="no-bullet"> 86 <li><a name="toc-Settings-1" href="#Settings">2.1 Settings</a></li> 87 <li><a name="toc-Groups-1" href="#Groups">2.2 Groups</a></li> 88 <li><a name="toc-Arrays-1" href="#Arrays">2.3 Arrays</a></li> 89 <li><a name="toc-Lists-1" href="#Lists">2.4 Lists</a></li> 90 <li><a name="toc-Integer-Values-1" href="#Integer-Values">2.5 Integer Values</a></li> 91 <li><a name="toc-64_002dbit-Integer-Values-1" href="#g_t64_002dbit-Integer-Values">2.6 64-bit Integer Values</a></li> 92 <li><a name="toc-Floating-Point-Values-1" href="#Floating-Point-Values">2.7 Floating Point Values</a></li> 93 <li><a name="toc-Boolean-Values-1" href="#Boolean-Values">2.8 Boolean Values</a></li> 94 <li><a name="toc-String-Values-1" href="#String-Values">2.9 String Values</a></li> 95 <li><a name="toc-Comments-1" href="#Comments">2.10 Comments</a></li> 96 <li><a name="toc-Include-Directives-1" href="#Include-Directives">2.11 Include Directives</a></li> 97 </ul></li> 98 <li><a name="toc-The-C-API-1" href="#The-C-API">3 The C API</a></li> 99 <li><a name="toc-The-C_002b_002b-API-1" href="#The-C_002b_002b-API">4 The C++ API</a></li> 100 <li><a name="toc-Example-Programs-1" href="#Example-Programs">5 Example Programs</a></li> 101 <li><a name="toc-Other-Bindings-and-Implementations-1" href="#Other-Bindings-and-Implementations">6 Other Bindings and Implementations</a> 102 <ul class="no-bullet"> 103 <li><a name="toc-Bourne-Shell-1" href="#Bourne-Shell">6.1 Bourne Shell</a></li> 104 <li><a name="toc-D-1" href="#D">6.2 D</a></li> 105 <li><a name="toc-Haskell-1" href="#Haskell">6.3 Haskell</a></li> 106 <li><a name="toc-Java-1" href="#Java">6.4 Java</a></li> 107 <li><a name="toc-Lisp-1" href="#Lisp">6.5 Lisp</a></li> 108 <li><a name="toc-Perl-1" href="#Perl">6.6 Perl</a></li> 109 <li><a name="toc-Python-1" href="#Python">6.7 Python</a></li> 110 <li><a name="toc-Ruby-1" href="#Ruby">6.8 Ruby</a></li> 111 </ul></li> 112 <li><a name="toc-License-1" href="#License">Appendix A License</a></li> 113 <li><a name="toc-Configuration-File-Grammar-1" href="#Configuration-File-Grammar">Appendix B Configuration File Grammar</a></li> 114 <li><a name="toc-Function-Index-1" href="#Function-Index">Function Index</a></li> 115 <li><a name="toc-Type-Index-1" href="#Type-Index">Type Index</a></li> 116 <li><a name="toc-Concept-Index-1" href="#Concept-Index">Concept Index</a></li> 117</ul> 118</div> 119 120 121<a name="Top"></a> 122<div class="header"> 123<p> 124Next: <a href="#Introduction" accesskey="n" rel="next">Introduction</a>, Up: <a href="dir.html#Top" accesskey="u" rel="up">(dir)</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 125</div> 126<a name="libconfig"></a> 127<h1 class="top">libconfig</h1> 128 129<table class="menu" border="0" cellspacing="0"> 130<tr><td align="left" valign="top">• <a href="#Introduction" accesskey="1">Introduction</a>:</td><td> </td><td align="left" valign="top"> 131</td></tr> 132<tr><td align="left" valign="top">• <a href="#Configuration-Files" accesskey="2">Configuration Files</a>:</td><td> </td><td align="left" valign="top"> 133</td></tr> 134<tr><td align="left" valign="top">• <a href="#The-C-API" accesskey="3">The C API</a>:</td><td> </td><td align="left" valign="top"> 135</td></tr> 136<tr><td align="left" valign="top">• <a href="#The-C_002b_002b-API" accesskey="4">The C++ API</a>:</td><td> </td><td align="left" valign="top"> 137</td></tr> 138<tr><td align="left" valign="top">• <a href="#Example-Programs" accesskey="5">Example Programs</a>:</td><td> </td><td align="left" valign="top"> 139</td></tr> 140<tr><td align="left" valign="top">• <a href="#Other-Bindings-and-Implementations" accesskey="6">Other Bindings and Implementations</a>:</td><td> </td><td align="left" valign="top"> 141</td></tr> 142<tr><td align="left" valign="top">• <a href="#License" accesskey="7">License</a>:</td><td> </td><td align="left" valign="top"> 143</td></tr> 144<tr><td align="left" valign="top">• <a href="#Configuration-File-Grammar" accesskey="8">Configuration File Grammar</a>:</td><td> </td><td align="left" valign="top"> 145</td></tr> 146<tr><td align="left" valign="top">• <a href="#Function-Index" accesskey="9">Function Index</a>:</td><td> </td><td align="left" valign="top"> 147</td></tr> 148<tr><td align="left" valign="top">• <a href="#Type-Index">Type Index</a>:</td><td> </td><td align="left" valign="top"> 149</td></tr> 150<tr><td align="left" valign="top">• <a href="#Concept-Index">Concept Index</a>:</td><td> </td><td align="left" valign="top"> 151</td></tr> 152</table> 153 154<hr> 155<a name="Introduction"></a> 156<div class="header"> 157<p> 158Next: <a href="#Configuration-Files" accesskey="n" rel="next">Configuration Files</a>, Previous: <a href="#Top" accesskey="p" rel="prev">Top</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 159</div> 160<table class="menu" border="0" cellspacing="0"> 161<tr><td align="left" valign="top">• <a href="#Why-Another-Configuration-File-Library_003f" accesskey="1">Why Another Configuration File Library?</a>:</td><td> </td><td align="left" valign="top"> 162</td></tr> 163<tr><td align="left" valign="top">• <a href="#Using-the-Library-from-a-C-Program" accesskey="2">Using the Library from a C Program</a>:</td><td> </td><td align="left" valign="top"> 164</td></tr> 165<tr><td align="left" valign="top">• <a href="#Using-the-Library-from-a-C_002b_002b-Program" accesskey="3">Using the Library from a C++ Program</a>:</td><td> </td><td align="left" valign="top"> 166</td></tr> 167<tr><td align="left" valign="top">• <a href="#Multithreading-Issues" accesskey="4">Multithreading Issues</a>:</td><td> </td><td align="left" valign="top"> 168</td></tr> 169<tr><td align="left" valign="top">• <a href="#Internationalization-Issues" accesskey="5">Internationalization Issues</a>:</td><td> </td><td align="left" valign="top"> 170</td></tr> 171<tr><td align="left" valign="top">• <a href="#Compiling-Using-pkg_002dconfig" accesskey="6">Compiling Using pkg-config</a>:</td><td> </td><td align="left" valign="top"> 172</td></tr> 173<tr><td align="left" valign="top">• <a href="#Version-Test-Macros" accesskey="7">Version Test Macros</a>:</td><td> </td><td align="left" valign="top"> 174</td></tr> 175</table> 176<a name="Introduction-1"></a> 177<h2 class="chapter">1 Introduction</h2> 178 179<p><i>Libconfig</i> is a library for reading, manipulating, and writing 180structured configuration files. The library features a fully 181reentrant parser and includes bindings for both the C and C++ 182programming languages. 183</p> 184<p>The library runs on modern POSIX-compilant systems, such as Linux, 185Solaris, and Mac OS X (Darwin), as well as on Microsoft Windows 1862000/XP and later (with either Microsoft Visual Studio 2005 or later, 187or the GNU toolchain via the MinGW environment). 188</p> 189<hr> 190<a name="Why-Another-Configuration-File-Library_003f"></a> 191<div class="header"> 192<p> 193Next: <a href="#Using-the-Library-from-a-C-Program" accesskey="n" rel="next">Using the Library from a C Program</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 194</div> 195<a name="Why-Another-Configuration-File-Library_003f-1"></a> 196<h3 class="section">1.1 Why Another Configuration File Library?</h3> 197 198<p>There are several open-source configuration file libraries available 199as of this writing. This library was written because each of those 200libraries falls short in one or more ways. The main features of 201<i>libconfig</i> that set it apart from the other libraries are: 202</p> 203<ul> 204<li> A fully reentrant parser. Independent configurations can be parsed in concurrent threads at the same time. 205 206</li><li> Both C <i>and</i> C++ bindings, as well as hooks to allow for the creation of wrappers in other languages. 207 208</li><li> A simple, structured configuration file format that is more 209readable and compact than XML and more flexible than the obsolete but 210prevalent Windows “INI” file format. 211 212</li><li> A low-footprint implementation (just 37K for the C library and 76K for 213the C++ library) that is suitable for memory-constrained systems. 214 215</li><li> Proper documentation. 216 217</li></ul> 218 219<hr> 220<a name="Using-the-Library-from-a-C-Program"></a> 221<div class="header"> 222<p> 223Next: <a href="#Using-the-Library-from-a-C_002b_002b-Program" accesskey="n" rel="next">Using the Library from a C++ Program</a>, Previous: <a href="#Why-Another-Configuration-File-Library_003f" accesskey="p" rel="prev">Why Another Configuration File Library?</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 224</div> 225<a name="Using-the-Library-from-a-C-Program-1"></a> 226<h3 class="section">1.2 Using the Library from a C Program</h3> 227 228<p>To use the library from C code, include the following preprocessor 229directive in your source files: 230</p> 231<br> 232<div class="smallexample"> 233<pre class="smallexample">#include <libconfig.h> 234</pre></div> 235<br> 236 237<p>To link with the library, specify ‘<samp>-lconfig</samp>’ as an argument to the 238linker. 239</p> 240<hr> 241<a name="Using-the-Library-from-a-C_002b_002b-Program"></a> 242<div class="header"> 243<p> 244Next: <a href="#Multithreading-Issues" accesskey="n" rel="next">Multithreading Issues</a>, Previous: <a href="#Using-the-Library-from-a-C-Program" accesskey="p" rel="prev">Using the Library from a C Program</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 245</div> 246<a name="Using-the-Library-from-a-C_002b_002b-Program-1"></a> 247<h3 class="section">1.3 Using the Library from a C++ Program</h3> 248 249<p>To use the library from C++, include the following preprocessor 250directive in your source files: 251</p> 252<br> 253<div class="smallexample"> 254<pre class="smallexample">#include <libconfig.h++> 255</pre></div> 256<br> 257 258<p>Or, alternatively: 259</p> 260<br> 261<div class="smallexample"> 262<pre class="smallexample">#include <libconfig.hh> 263</pre></div> 264<br> 265<p>The C++ API classes are defined in the namespace ‘<samp>libconfig</samp>’, hence the 266following statement may optionally be used: 267</p> 268<br> 269<div class="smallexample"> 270<pre class="smallexample">using namespace libconfig; 271</pre></div> 272<br> 273 274<p>To link with the library, specify ‘<samp>-lconfig++</samp>’ as an argument to 275the linker. 276</p> 277<hr> 278<a name="Multithreading-Issues"></a> 279<div class="header"> 280<p> 281Next: <a href="#Internationalization-Issues" accesskey="n" rel="next">Internationalization Issues</a>, Previous: <a href="#Using-the-Library-from-a-C_002b_002b-Program" accesskey="p" rel="prev">Using the Library from a C++ Program</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 282</div> 283<a name="Multithreading-Issues-1"></a> 284<h3 class="section">1.4 Multithreading Issues</h3> 285 286<p><i>Libconfig</i> is fully <em>reentrant</em>; the functions in the library 287do not make use of global variables and do not maintain state between 288successive calls. Therefore two independent configurations may be safely 289manipulated concurrently by two distinct threads. 290</p> 291<p><i>Libconfig</i> is not <em>thread-safe</em>. The library is not aware of 292the presence of threads and knows nothing about the host system’s 293threading model. Therefore, if an instance of a configuration is to be 294accessed from multiple threads, it must be suitably protected by 295synchronization mechanisms like read-write locks or mutexes; the 296standard rules for safe multithreaded access to shared data must be 297observed. 298</p> 299<p><i>Libconfig</i> is not <em>async-safe</em>. Calls should not be made into 300the library from signal handlers, because some of the C library 301routines that it uses may not be async-safe. 302</p> 303<p><i>Libconfig</i> is not guaranteed to be <em>cancel-safe</em>. Since it is 304not aware of the host system’s threading model, the library does not 305contain any thread cancellation points. In most cases this will not be 306an issue for multithreaded programs. However, be aware that some of 307the routines in the library (namely those that read/write 308configurations from/to files or streams) perform I/O using C library 309routines which may potentially block; whether or not these C library 310routines are cancel-safe depends on the host system. 311</p> 312<hr> 313<a name="Internationalization-Issues"></a> 314<div class="header"> 315<p> 316Next: <a href="#Compiling-Using-pkg_002dconfig" accesskey="n" rel="next">Compiling Using pkg-config</a>, Previous: <a href="#Multithreading-Issues" accesskey="p" rel="prev">Multithreading Issues</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 317</div> 318<a name="Internationalization-Issues-1"></a> 319<h3 class="section">1.5 Internationalization Issues</h3> 320 321<a name="index-Unicode"></a> 322<a name="index-UTF_002d8"></a> 323<p><i>Libconfig</i> does not natively support Unicode configuration files, 324but string values may contain Unicode text encoded in UTF-8; such 325strings will be treated as ordinary 8-bit ASCII text by the 326library. It is the responsibility of the calling program to perform 327the necessary conversions to/from wide (<tt>wchar_t</tt>) strings using the 328wide string conversion functions such as <tt>mbsrtowcs()</tt> and 329<tt>wcsrtombs()</tt> or the <tt>iconv()</tt> function of the <i>libiconv</i> 330library. 331</p> 332<a name="index-locale"></a> 333<p>The textual representation of a floating point value varies by 334locale. However, the <i>libconfig</i> grammar specifies that 335floating point values are represented using a period (‘.’) as the 336radix symbol; this is consistent with the grammar of most programming 337languages. When a configuration is read in or written out, 338<i>libconfig</i> temporarily changes the <tt>LC_NUMERIC</tt> category of the 339locale of the calling thread to the “C” locale to ensure consistent 340handling of floating point values regardless of the locale(s) in use 341by the calling program. 342</p> 343<p>Note that the MinGW environment does not (as of this writing) provide 344functions for changing the locale of the calling thread. Therefore, 345when using <i>libconfig</i> in that environment, the calling program is 346responsible for changing the <tt>LC_NUMERIC</tt> category of the locale to 347the "C" locale before reading or writing a configuration. 348</p> 349<hr> 350<a name="Compiling-Using-pkg_002dconfig"></a> 351<div class="header"> 352<p> 353Next: <a href="#Version-Test-Macros" accesskey="n" rel="next">Version Test Macros</a>, Previous: <a href="#Internationalization-Issues" accesskey="p" rel="prev">Internationalization Issues</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 354</div> 355<a name="Compiling-Using-pkg_002dconfig-1"></a> 356<h3 class="section">1.6 Compiling Using pkg-config</h3> 357 358<a name="index-pkg_002dconfig"></a> 359<p>On UNIX systems you can use the <i>pkg-config</i> utility (version 0.20 360or later) to automatically select the appropriate compiler and linker 361switches for <i>libconfig</i>. Ensure that the environment variable 362<code>PKG_CONFIG_PATH</code> contains the absolute path to the 363<samp>lib/pkgconfig</samp> subdirectory of the <i>libconfig</i> installation. Then, 364you can compile and link C programs with <i>libconfig</i> as follows: 365</p> 366<div class="smallexample"> 367<pre class="smallexample">gcc `pkg-config --cflags libconfig` myprogram.c -o myprogram \ 368 `pkg-config --libs libconfig` 369</pre></div> 370<br> 371 372<p>And similarly, for C++ programs: 373</p> 374<div class="smallexample"> 375<pre class="smallexample">g++ `pkg-config --cflags libconfig++` myprogram.cpp -o myprogram \ 376 `pkg-config --libs libconfig++` 377</pre></div> 378 379<br> 380<p>Note the backticks in the above examples. 381</p> 382<p>When using <b>autoconf</b>, the <code>PKG_CHECK_MODULES</code> m4 macro may be used to check for the presence of a given version of <i>libconfig</i>, and set the appropriate Makefile variables automatically. For example: 383</p> 384<div class="smallexample"> 385<pre class="smallexample">PKG_CHECK_MODULES([LIBCONFIGXX], [libconfig++ >= 1.4],, 386 AC_MSG_ERROR([libconfig++ 1.4 or newer not found.]) 387) 388</pre></div> 389 390<p>In the above example, if <i>libconfig++</i> version 1.4 or newer is found, 391the Makefile variables <code>LIBCONFIGXX_LIBS</code> and <code>LIBCONFIGXX_CFLAGS</code> will be 392set to the appropriate compiler and linker flags for compiling with 393<i>libconfig</i>, and if it is not found, the configure script will abort 394with an error to that effect. 395</p> 396<hr> 397<a name="Version-Test-Macros"></a> 398<div class="header"> 399<p> 400Previous: <a href="#Compiling-Using-pkg_002dconfig" accesskey="p" rel="prev">Compiling Using pkg-config</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 401</div> 402<a name="Version-Test-Macros-1"></a> 403<h3 class="section">1.7 Version Test Macros</h3> 404 405<p>The <samp>libconfig.h</samp> header declares the following macros: 406</p> 407<dl> 408<dt><a name="index-LIBCONFIG_005fVER_005fMAJOR"></a>Macro: <strong>LIBCONFIG_VER_MAJOR</strong></dt> 409<dt><a name="index-LIBCONFIG_005fVER_005fMINOR"></a>Macro: <strong>LIBCONFIG_VER_MINOR</strong></dt> 410<dt><a name="index-LIBCONFIG_005fVER_005fREVISION"></a>Macro: <strong>LIBCONFIG_VER_REVISION</strong></dt> 411<dd> 412<p>These macros represent the major version, minor version, and revision 413of the <i>libconfig</i> library. For example, in <i>libconfig</i> 1.4 these 414are defined as ‘<samp>1</samp>’, ‘<samp>4</samp>’, and ‘<samp>0</samp>’, respectively. These 415macros can be used in preprocessor directives to determine which 416<i>libconfig</i> features and/or APIs are present. For example: 417</p> 418<div class="smallexample"> 419<pre class="smallexample">#if (((LIBCONFIG_VER_MAJOR == 1) && (LIBCONFIG_VER_MINOR >= 4)) \ 420 || (LIBCONFIG_VER_MAJOR > 1)) 421 /* use features present in libconfig 1.4 and later */ 422#endif 423</pre></div> 424 425<p>These macros were introduced in <i>libconfig</i> 1.4. 426</p> 427</dd></dl> 428 429<p>Similarly, the <samp>libconfig.h++</samp> header declares the following macros: 430</p> 431<dl> 432<dt><a name="index-LIBCONFIGXX_005fVER_005fMAJOR"></a>Macro: <strong>LIBCONFIGXX_VER_MAJOR</strong></dt> 433<dt><a name="index-LIBCONFIGXX_005fVER_005fMINOR"></a>Macro: <strong>LIBCONFIGXX_VER_MINOR</strong></dt> 434<dt><a name="index-LIBCONFIGXX_005fVER_005fREVISION"></a>Macro: <strong>LIBCONFIGXX_VER_REVISION</strong></dt> 435<dd> 436<p>These macros represent the major version, minor version, and revision 437of the <i>libconfig++</i> library. 438</p> 439</dd></dl> 440 441<hr> 442<a name="Configuration-Files"></a> 443<div class="header"> 444<p> 445Next: <a href="#The-C-API" accesskey="n" rel="next">The C API</a>, Previous: <a href="#Introduction" accesskey="p" rel="prev">Introduction</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 446</div> 447<table class="menu" border="0" cellspacing="0"> 448<tr><td align="left" valign="top">• <a href="#Settings" accesskey="1">Settings</a>:</td><td> </td><td align="left" valign="top"> 449</td></tr> 450<tr><td align="left" valign="top">• <a href="#Groups" accesskey="2">Groups</a>:</td><td> </td><td align="left" valign="top"> 451</td></tr> 452<tr><td align="left" valign="top">• <a href="#Arrays" accesskey="3">Arrays</a>:</td><td> </td><td align="left" valign="top"> 453</td></tr> 454<tr><td align="left" valign="top">• <a href="#Lists" accesskey="4">Lists</a>:</td><td> </td><td align="left" valign="top"> 455</td></tr> 456<tr><td align="left" valign="top">• <a href="#Integer-Values" accesskey="5">Integer Values</a>:</td><td> </td><td align="left" valign="top"> 457</td></tr> 458<tr><td align="left" valign="top">• <a href="#g_t64_002dbit-Integer-Values" accesskey="6">64-bit Integer Values</a>:</td><td> </td><td align="left" valign="top"> 459</td></tr> 460<tr><td align="left" valign="top">• <a href="#Floating-Point-Values" accesskey="7">Floating Point Values</a>:</td><td> </td><td align="left" valign="top"> 461</td></tr> 462<tr><td align="left" valign="top">• <a href="#Boolean-Values" accesskey="8">Boolean Values</a>:</td><td> </td><td align="left" valign="top"> 463</td></tr> 464<tr><td align="left" valign="top">• <a href="#String-Values" accesskey="9">String Values</a>:</td><td> </td><td align="left" valign="top"> 465</td></tr> 466<tr><td align="left" valign="top">• <a href="#Comments">Comments</a>:</td><td> </td><td align="left" valign="top"> 467</td></tr> 468<tr><td align="left" valign="top">• <a href="#Include-Directives">Include Directives</a>:</td><td> </td><td align="left" valign="top"> 469</td></tr> 470</table> 471<a name="Configuration-Files-1"></a> 472<h2 class="chapter">2 Configuration Files</h2> 473 474<p><i>Libconfig</i> supports structured, hierarchical configurations. These 475configurations can be read from and written to files and manipulated 476in memory. 477</p> 478<a name="index-setting"></a> 479<a name="index-value"></a> 480<a name="index-scalar-value"></a> 481<a name="index-array"></a> 482<a name="index-group"></a> 483<a name="index-list"></a> 484<a name="index-configuration"></a> 485<p>A <em>configuration</em> consists of a group of <em>settings</em>, which 486associate names with values. A <em>value</em> can be one of the 487following: 488</p> 489<ul> 490<li> A <em>scalar value</em>: integer, 64-bit integer, floating-point number, boolean, 491or string 492</li><li> An <em>array</em>, which is a sequence of scalar values, all of which must have the same type 493</li><li> A <em>group</em>, which is a collection of settings 494</li><li> A <em>list</em>, which is a sequence of values of any type, including other lists 495</li></ul> 496 497<p>Consider the following configuration file for a hypothetical GUI 498application, which illustrates all of the elements of the configuration 499file grammar. 500</p> 501<br> 502<table class="cartouche" border="1"><tr><td> 503<div class="smallexample"> 504<pre class="smallexample"># Example application configuration file 505 506version = "1.0"; 507 508application: 509{ 510 window: 511 { 512 title = "My Application"; 513 size = { w = 640; h = 480; }; 514 pos = { x = 350; y = 250; }; 515 }; 516 517 list = ( ( "abc", 123, true ), 1.234, ( /* an empty list */ ) ); 518 519 books = ( { title = "Treasure Island"; 520 author = "Robert Louis Stevenson"; 521 price = 29.95; 522 qty = 5; }, 523 { title = "Snow Crash"; 524 author = "Neal Stephenson"; 525 price = 9.99; 526 qty = 8; } ); 527 528 misc: 529 { 530 pi = 3.141592654; 531 bigint = 9223372036854775807L; 532 columns = [ "Last Name", "First Name", "MI" ]; 533 bitmask = 0x1FC3; // hex 534 umask = 0027; // octal. Range limited to that of "int" 535 }; 536}; 537</pre></div> 538</td></tr></table> 539<br> 540 541<a name="index-path"></a> 542<p>Settings can be uniquely identified within the configuration by a 543<em>path</em>. The path is a dot-separated sequence of names, beginning 544at a top-level group and ending at the setting itself. Each name in 545the path is the name of a setting; if the setting has no name because 546it is an element in a list or array, an integer index in square 547brackets can be used as the name. 548</p> 549<p>For example, in our hypothetical configuration file, the path to the 550<code>x</code> setting is <code>application.window.pos.x</code>; the path to the 551<code>version</code> setting is simply <code>version</code>; and the path to the 552<code>title</code> setting of the second book in the <code>books</code> list is 553<code>application.books.[1].title</code>. 554</p> 555<p>The datatype of a value is determined from the format of the value 556itself. If the value is enclosed in double quotes, it is treated as a 557string. If it looks like an integer or floating point number, it is 558treated as such. If it is one of the values <code>TRUE</code>, <code>true</code>, 559<code>FALSE</code>, or <code>false</code> (or any other mixed-case version of 560those tokens, e.g., <code>True</code> or <code>FaLsE</code>), it is treated as a 561boolean. If it consists of a comma-separated list of values enclosed 562in square brackets, it is treated as an array. And if it consists of a 563comma-separated list of values enclosed in parentheses, it is treated 564as a list. Any value which does not meet any of these criteria is 565considered invalid and results in a parse error. 566</p> 567<p>All names are case-sensitive. They may consist only of alphanumeric 568characters, dashes (‘<samp>-</samp>’), underscores (‘<samp>_</samp>’), and asterisks 569(‘<samp>*</samp>’), and must begin with a letter or asterisk. No other 570characters are allowed. 571</p> 572<p>In C and C++, integer, 64-bit integer, floating point, and string 573values are mapped to the native types <code>int</code>, <code>long long</code>, 574<code>double</code>, and <code>const char *</code>, respectively. The boolean type 575is mapped to <code>int</code> in C and <code>bool</code> in C++. 576</p> 577<p>The following sections describe the elements of the configuration file 578grammar in additional detail. 579</p> 580<hr> 581<a name="Settings"></a> 582<div class="header"> 583<p> 584Next: <a href="#Groups" accesskey="n" rel="next">Groups</a>, Up: <a href="#Configuration-Files" accesskey="u" rel="up">Configuration Files</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 585</div> 586<a name="Settings-1"></a> 587<h3 class="section">2.1 Settings</h3> 588 589<p>A setting has the form: 590</p> 591<p><i>name</i> <b>=</b> <i>value</i> <b>;</b> 592</p> 593<p>or: 594</p> 595<p><i>name</i> <b>:</b> <i>value</i> <b>;</b> 596</p> 597<p>The trailing semicolon is optional. Whitespace is not significant. 598</p> 599<p>The value may be a scalar value, an array, a group, or a list. 600</p> 601<hr> 602<a name="Groups"></a> 603<div class="header"> 604<p> 605Next: <a href="#Arrays" accesskey="n" rel="next">Arrays</a>, Previous: <a href="#Settings" accesskey="p" rel="prev">Settings</a>, Up: <a href="#Configuration-Files" accesskey="u" rel="up">Configuration Files</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 606</div> 607<a name="Groups-1"></a> 608<h3 class="section">2.2 Groups</h3> 609 610<p>A group has the form: 611</p> 612<p><b>{</b> 613 <i>settings ...</i> 614<b>}</b> 615</p> 616<p>Groups can contain any number of settings, but each setting must have 617a unique name within the group. 618</p> 619<hr> 620<a name="Arrays"></a> 621<div class="header"> 622<p> 623Next: <a href="#Lists" accesskey="n" rel="next">Lists</a>, Previous: <a href="#Groups" accesskey="p" rel="prev">Groups</a>, Up: <a href="#Configuration-Files" accesskey="u" rel="up">Configuration Files</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 624</div> 625<a name="Arrays-1"></a> 626<h3 class="section">2.3 Arrays</h3> 627 628<p>An array has the form: 629</p> 630<p><b>[</b> <i>value</i><b>,</b> <i>value ...</i> <b>]</b> 631</p> 632<p>An array may have zero or more elements, but the elements must all be 633scalar values of the same type. 634</p> 635<p>The last element in an array may be followed by a comma, which will be ignored. 636</p> 637<hr> 638<a name="Lists"></a> 639<div class="header"> 640<p> 641Next: <a href="#Integer-Values" accesskey="n" rel="next">Integer Values</a>, Previous: <a href="#Arrays" accesskey="p" rel="prev">Arrays</a>, Up: <a href="#Configuration-Files" accesskey="u" rel="up">Configuration Files</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 642</div> 643<a name="Lists-1"></a> 644<h3 class="section">2.4 Lists</h3> 645 646<p>A list has the form: 647</p> 648<p><b>(</b> <i>value</i><b>,</b> <i>value ...</i> <b>)</b> 649</p> 650<p>A list may have zero or more elements, each of which can be a scalar 651value, an array, a group, or another list. 652</p> 653<p>The last element in a list may be followed by a comma, which will be ignored. 654</p> 655<hr> 656<a name="Integer-Values"></a> 657<div class="header"> 658<p> 659Next: <a href="#g_t64_002dbit-Integer-Values" accesskey="n" rel="next">64-bit Integer Values</a>, Previous: <a href="#Lists" accesskey="p" rel="prev">Lists</a>, Up: <a href="#Configuration-Files" accesskey="u" rel="up">Configuration Files</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 660</div> 661<a name="Integer-Values-1"></a> 662<h3 class="section">2.5 Integer Values</h3> 663 664<p>Integers can be represented in one of two ways: as a series of one or 665more decimal digits (‘<samp>0</samp>’ - ‘<samp>9</samp>’), with an optional leading 666sign character (‘<samp>+</samp>’ or ‘<samp>-</samp>’); or as a hexadecimal value 667consisting of the characters ‘<samp>0x</samp>’ followed by a series of one or 668more hexadecimal digits (‘<samp>0</samp>’ - ‘<samp>9</samp>’, ‘<samp>A</samp>’ - ‘<samp>F</samp>’, 669‘<samp>a</samp>’ - ‘<samp>f</samp>’). Additionally, octal notation integers (that is, 670those having a leading zero with non-zero value) are also allowed. 671</p> 672<hr> 673<a name="g_t64_002dbit-Integer-Values"></a> 674<div class="header"> 675<p> 676Next: <a href="#Floating-Point-Values" accesskey="n" rel="next">Floating Point Values</a>, Previous: <a href="#Integer-Values" accesskey="p" rel="prev">Integer Values</a>, Up: <a href="#Configuration-Files" accesskey="u" rel="up">Configuration Files</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 677</div> 678<a name="g_t64_002dbit-Integer-Values-1"></a> 679<h3 class="section">2.6 64-bit Integer Values</h3> 680 681<p>Long long (64-bit) integers are represented identically to integers, 682except that an ‘L’ character is appended to indicate a 64-bit 683value. For example, ‘<samp>0L</samp>’ indicates a 64-bit integer value 0. As 684of version 1.5 of the library, the trailing ‘L’ is optional; if the 685integer value exceeds the range of a 32-bit integer, it will 686automatically be interpreted as a 64-bit integer. 687</p> 688<p>The <i>integer</i> and <i>64-bit integer</i> setting types are interchangeable to the 689extent that a conversion between the corresponding native types would not 690result in an overflow or underflow. For example, a <i>long long</i> value can be 691written to a setting that has an <i>integer</i> type, if that value is within the 692range of an <i>int</i>. This rule applies to every API function or method that 693reads a value from or writes a value to a setting: if the type conversion would 694not result in an overflow or underflow, then the call will succeed, and 695otherwise it will fail. This behavior was not well-defined prior to version 1.7 696of the library. 697</p> 698<hr> 699<a name="Floating-Point-Values"></a> 700<div class="header"> 701<p> 702Next: <a href="#Boolean-Values" accesskey="n" rel="next">Boolean Values</a>, Previous: <a href="#g_t64_002dbit-Integer-Values" accesskey="p" rel="prev">64-bit Integer Values</a>, Up: <a href="#Configuration-Files" accesskey="u" rel="up">Configuration Files</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 703</div> 704<a name="Floating-Point-Values-1"></a> 705<h3 class="section">2.7 Floating Point Values</h3> 706 707<p>Floating point values consist of a series of one or more digits, one 708decimal point, an optional leading sign character (‘<samp>+</samp>’ or 709‘<samp>-</samp>’), and an optional exponent. An exponent consists of the 710letter ‘<samp>E</samp>’ or ‘<samp>e</samp>’, an optional sign character, and a series 711of one or more digits. 712</p> 713<hr> 714<a name="Boolean-Values"></a> 715<div class="header"> 716<p> 717Next: <a href="#String-Values" accesskey="n" rel="next">String Values</a>, Previous: <a href="#Floating-Point-Values" accesskey="p" rel="prev">Floating Point Values</a>, Up: <a href="#Configuration-Files" accesskey="u" rel="up">Configuration Files</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 718</div> 719<a name="Boolean-Values-1"></a> 720<h3 class="section">2.8 Boolean Values</h3> 721 722<p>Boolean values may have one of the following values: ‘<samp>true</samp>’, 723‘<samp>false</samp>’, or any mixed-case variation thereof. 724</p> 725<hr> 726<a name="String-Values"></a> 727<div class="header"> 728<p> 729Next: <a href="#Comments" accesskey="n" rel="next">Comments</a>, Previous: <a href="#Boolean-Values" accesskey="p" rel="prev">Boolean Values</a>, Up: <a href="#Configuration-Files" accesskey="u" rel="up">Configuration Files</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 730</div> 731<a name="String-Values-1"></a> 732<h3 class="section">2.9 String Values</h3> 733 734<a name="index-escape-sequence"></a> 735<p>String values consist of arbitrary text delimited by double 736quotes. Literal double quotes can be escaped by preceding them with a 737backslash: ‘<samp>\"</samp>’. The escape sequences ‘<samp>\\</samp>’, ‘<samp>\f</samp>’, 738‘<samp>\n</samp>’, ‘<samp>\r</samp>’, and ‘<samp>\t</samp>’ are also recognized, and have the 739usual meaning. 740</p> 741<p>In addition, the ‘<samp>\x</samp>’ escape sequence is supported; this sequence 742must be followed by <i>exactly two</i> hexadecimal digits, which represent an 7438-bit ASCII value. For example, ‘<samp>\xFF</samp>’ represents the character 744with ASCII code 0xFF. 745</p> 746<p>No other escape sequences are currently supported. 747</p> 748<p>Adjacent strings are automatically concatenated, as in C/C++ source 749code. This is useful for formatting very long strings as sequences of 750shorter strings. For example, the following constructs are equivalent: 751</p> 752<ul> 753<li> <code>"The quick brown fox jumped over the lazy dog."</code> 754 755</li><li> <code>"The quick brown fox"</code> <br> 756<code>" jumped over the lazy dog."</code> 757 758</li><li> <code>"The quick" /* comment */ " brown fox " // another comment</code> <br> 759<code>"jumped over the lazy dog."</code> 760 761</li></ul> 762<hr> 763<a name="Comments"></a> 764<div class="header"> 765<p> 766Next: <a href="#Include-Directives" accesskey="n" rel="next">Include Directives</a>, Previous: <a href="#String-Values" accesskey="p" rel="prev">String Values</a>, Up: <a href="#Configuration-Files" accesskey="u" rel="up">Configuration Files</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 767</div> 768<a name="Comments-1"></a> 769<h3 class="section">2.10 Comments</h3> 770 771<a name="index-comment"></a> 772<p>Three types of comments are allowed within a configuration: 773</p> 774<ul> 775<li> Script-style comments. All text beginning with a ‘<samp>#</samp>’ character 776to the end of the line is ignored. 777 778</li><li> C-style comments. All text, including line breaks, between a starting 779‘<samp>/*</samp>’ sequence and an ending ‘<samp>*/</samp>’ sequence is ignored. 780 781</li><li> C++-style comments. All text beginning with a ‘<samp>//</samp>’ sequence to the 782end of the line is ignored. 783 784</li></ul> 785 786<p>As expected, comment delimiters appearing within quoted strings are 787treated as literal text. 788</p> 789<p>Comments are ignored when the configuration is read in, so they are 790not treated as part of the configuration. Therefore if the 791configuration is written back out to a stream, any comments that were 792present in the original configuration will be lost. 793</p> 794 795<hr> 796<a name="Include-Directives"></a> 797<div class="header"> 798<p> 799Previous: <a href="#Comments" accesskey="p" rel="prev">Comments</a>, Up: <a href="#Configuration-Files" accesskey="u" rel="up">Configuration Files</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 800</div> 801<a name="Include-Directives-1"></a> 802<h3 class="section">2.11 Include Directives</h3> 803 804<a name="index-include-directive"></a> 805<p>A configuration file may “include” the contents of other files 806using an <i>include directive</i>. This directive has the effect of 807inlining the contents of the named file(s) at the point of inclusion. 808</p> 809<p>An include directive must appear on its own line in the input. It has 810the form: 811</p> 812<p><b>@include "</b><i>path</i><b>"</b> 813</p> 814<a name="index-include-function"></a> 815<p>The interpretation of <i>path</i> depends on the currently registered 816<i>include function</i>. The default include function prepends the include 817directory, if any, to <i>path</i>, and then interprets the result as a single, 818literal file path. The application may supply its own include function which 819does variable substitution, wildcard expansion, or other transformations, 820returning a list of zero or more paths to files whose contents should be inlined 821at the point of inclusion. 822</p> 823<p>Any backslashes or double quotes in the path must be escaped as 824‘<samp>\\</samp>’ and ‘<samp>\"</samp>’, respectively. 825</p> 826<p>For example, consider the following two configuration files: 827</p> 828<table class="cartouche" border="1"><tr><td> 829<div class="smallexample"> 830<pre class="smallexample"># file: quote.cfg 831quote = "Criticism may not be agreeable, but it is necessary." 832 " It fulfils the same function as pain in the human" 833 " body. It calls attention to an unhealthy state of" 834 " things.\n" 835 "\t--Winston Churchill"; 836</pre></div> 837</td></tr></table> 838 839<table class="cartouche" border="1"><tr><td> 840<div class="smallexample"> 841<pre class="smallexample"># file: test.cfg 842info: { 843 name = "Winston Churchill"; 844 @include "quote.cfg" 845 country = "UK"; 846}; 847</pre></div> 848</td></tr></table> 849 850<p>The resulting configuration will be equivalent to one in which the 851contents of the file ‘<samp>quote.cfg</samp>’ appeared at the point where the 852include directive is placed. 853</p> 854<p>Include files may be nested to a maximum of 10 levels; exceeding this 855limit results in a parse error. 856</p> 857<p>When the path argument to an <b>@include</b> directive is a relative 858path, then it will be interpreted as being relative to the include 859directory that has been been set by means of 860<code>config_set_include_dir()</code>. If no include directory has been set, 861then it will be taken as being relative to the program’s current 862working directory. 863</p> 864<p>Like comments, include directives are not part of the configuration 865file syntax. They are processed before the configuration itself is 866parsed. Therefore, they are not preserved when the configuration is 867written back out to a stream. There is presently no support for 868programmatically inserting include directives into a configuration. 869</p> 870<hr> 871<a name="The-C-API"></a> 872<div class="header"> 873<p> 874Next: <a href="#The-C_002b_002b-API" accesskey="n" rel="next">The C++ API</a>, Previous: <a href="#Configuration-Files" accesskey="p" rel="prev">Configuration Files</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 875</div> 876<a name="The-C-API-1"></a> 877<h2 class="chapter">3 The C API</h2> 878 879<a name="index-config_005ft"></a> 880<a name="index-config_005fsetting_005ft"></a> 881<p>This chapter describes the C library API. The type <i>config_t</i> 882represents a configuration, and the type <i>config_setting_t</i> represents 883a configuration setting. 884</p> 885<p>The boolean values <code>CONFIG_TRUE</code> and <code>CONFIG_FALSE</code> are 886macros defined as <code>(1)</code> and <code>(0)</code>, respectively. 887</p> 888<dl> 889<dt><a name="index-config_005finit"></a>Function: <em>void</em> <strong>config_init</strong> <em>(<span class="nolinebreak">config_t</span> * <var>config</var><!-- /@w -->)</em></dt> 890<dt><a name="index-config_005fdestroy"></a>Function: <em>void</em> <strong>config_destroy</strong> <em>(<span class="nolinebreak">config_t</span> * <var>config</var><!-- /@w -->)</em></dt> 891<dd> 892<p>These functions initialize and destroy the configuration object <var>config</var>. 893</p> 894<p><code>config_init()</code> initializes the <i>config_t</i> structure pointed to by 895<var>config</var> as a new, empty configuration. 896</p> 897<p><code>config_destroy()</code> destroys the configuration <var>config</var>, 898deallocating all memory associated with the configuration, but does not 899attempt to deallocate the <i>config_t</i> structure itself. 900</p> 901</dd></dl> 902 903<dl> 904<dt><a name="index-config_005fclear"></a>Function: <em>void</em> <strong>config_clear</strong> <em>(<span class="nolinebreak">config_t</span> * <var>config</var><!-- /@w -->)</em></dt> 905<dd> 906<p><b>Since <i>v1.7</i></b> 907</p> 908<p>This function clears the configuration <var>config</var>. All child settings of the 909root setting are recursively destroyed. All other attributes of the configuration 910are left unchanged. 911</p> 912</dd></dl> 913 914<dl> 915<dt><a name="index-config_005fread"></a>Function: <em>int</em> <strong>config_read</strong> <em>(<span class="nolinebreak">config_t</span> * <var>config</var><!-- /@w -->, FILE * <var>stream</var><!-- /@w -->)</em></dt> 916<dd> 917<p>This function reads and parses a configuration from the given 918<var>stream</var> into the configuration object <var>config</var>. It returns 919<code>CONFIG_TRUE</code> on success, or <code>CONFIG_FALSE</code> on failure; the 920<code>config_error_text()</code>, <code>config_error_file()</code>, 921<code>config_error_line()</code>, and <code>config_error_type()</code> functions, 922described below, can be used to obtain information about the error. 923</p> 924</dd></dl> 925 926<dl> 927<dt><a name="index-config_005fread_005ffile"></a>Function: <em>int</em> <strong>config_read_file</strong> <em>(<span class="nolinebreak">config_t</span> * <var>config</var><!-- /@w -->, const char * <var>filename</var><!-- /@w -->)</em></dt> 928<dd> 929<p>This function reads and parses a configuration from the file named 930<var>filename</var> into the configuration object <var>config</var>. It returns 931<code>CONFIG_TRUE</code> on success, or <code>CONFIG_FALSE</code> on failure; the 932<code>config_error_text()</code> and <code>config_error_line()</code> functions, 933described below, can be used to obtain information about the error. 934</p> 935</dd></dl> 936 937<dl> 938<dt><a name="index-config_005fread_005fstring"></a>Function: <em>int</em> <strong>config_read_string</strong> <em>(<span class="nolinebreak">config_t</span> * <var>config</var><!-- /@w -->, const char * <var>str</var><!-- /@w -->)</em></dt> 939<dd> 940<p>This function reads and parses a configuration from the string 941<var>str</var> into the configuration object <var>config</var>. It returns 942<code>CONFIG_TRUE</code> on success, or <code>CONFIG_FALSE</code> on failure; the 943<code>config_error_text()</code> and <code>config_error_line()</code> functions, 944described below, can be used to obtain information about the error. 945</p> 946</dd></dl> 947 948<dl> 949<dt><a name="index-config_005fwrite"></a>Function: <em>void</em> <strong>config_write</strong> <em>(const <span class="nolinebreak">config_t</span> * <var>config</var><!-- /@w -->, FILE * <var>stream</var><!-- /@w -->)</em></dt> 950<dd> 951<p>This function writes the configuration <var>config</var> to the given 952<var>stream</var>. 953</p> 954</dd></dl> 955 956<dl> 957<dt><a name="index-config_005fwrite_005ffile"></a>Function: <em>int</em> <strong>config_write_file</strong> <em>(<span class="nolinebreak">config_t</span> * <var>config</var><!-- /@w -->, const char * <var>filename</var><!-- /@w -->)</em></dt> 958<dd> 959<p>This function writes the configuration <var>config</var> to the file named 960<var>filename</var>. It returns <code>CONFIG_TRUE</code> on success, or 961<code>CONFIG_FALSE</code> on failure. 962</p> 963</dd></dl> 964 965<dl> 966<dt><a name="index-config_005ferror_005ftext"></a>Function: <em>const char *</em> <strong>config_error_text</strong> <em>(const <span class="nolinebreak">config_t</span> * <var>config</var><!-- /@w -->)</em></dt> 967<dt><a name="index-config_005ferror_005ffile"></a>Function: <em>const char *</em> <strong>config_error_file</strong> <em>(const <span class="nolinebreak">config_t</span> * <var>config</var><!-- /@w -->)</em></dt> 968<dt><a name="index-config_005ferror_005fline"></a>Function: <em>int</em> <strong>config_error_line</strong> <em>(const <span class="nolinebreak">config_t</span> * <var>config</var><!-- /@w -->)</em></dt> 969<dd> 970<p>These functions, which are implemented as macros, return the text, 971filename, and line number of the parse error, if one occurred during a 972call to <code>config_read()</code>, <code>config_read_string()</code>, or 973<code>config_read_file()</code>. Storage for the strings returned by 974<code>config_error_text()</code> and <code>config_error_file()</code> are managed 975by the library and released automatically when the configuration is 976destroyed; these strings must not be freed by the caller. If the error 977occurred in text that was read from a string or stream, 978<code>config_error_file()</code> will return NULL. 979</p> 980</dd></dl> 981 982<dl> 983<dt><a name="index-config_005ferror_005ftype"></a>Function: <em>config_error_t</em> <strong>config_error_type</strong> <em>(const <span class="nolinebreak">config_t</span> * <var>config</var><!-- /@w -->)</em></dt> 984<dd><a name="index-config_005ferror_005ft"></a> 985<p>This function, which is implemented as a macro, returns the type of 986error that occurred during the last call to one of the read or write 987functions. The <var>config_error_t</var> type is an enumeration with the 988following values: <code>CONFIG_ERR_NONE</code>, <code>CONFIG_ERR_FILE_IO</code>, 989<code>CONFIG_ERR_PARSE</code>. These represent success, a file I/O error, 990and a parsing error, respectively. 991</p> 992</dd></dl> 993 994<dl> 995<dt><a name="index-config_005fset_005finclude_005fdir"></a>Function: <em>void</em> <strong>config_set_include_dir</strong> <em>(<span class="nolinebreak">config_t</span> *<var>config</var><!-- /@w -->, const char *<var><span class="nolinebreak">include_dir</span></var><!-- /@w -->)</em></dt> 996<dt><a name="index-config_005fget_005finclude_005fdir"></a>Function: <em>const char *</em> <strong>config_get_include_dir</strong> <em>(const <span class="nolinebreak">config_t</span> *<var>config</var><!-- /@w -->)</em></dt> 997<dd> 998<p><code>config_set_include_dir()</code> specifies the include directory, 999<var>include_dir</var>, relative to which the files specified in 1000‘<samp>@include</samp>’ directives will be located for the configuration 1001<var>config</var>. By default, there is no include directory, and all 1002include files are expected to be relative to the current working 1003directory. If <var>include_dir</var> is <code>NULL</code>, the default behavior 1004is reinstated. 1005</p> 1006<p>For example, if the include directory is set to <samp>/usr/local/etc</samp>, 1007the include directive ‘<samp>@include "configs/extra.cfg"</samp>’ would include the 1008file <samp>/usr/local/etc/configs/extra.cfg</samp>. 1009</p> 1010<p><code>config_get_include_dir()</code> returns the current include directory for the 1011configuration <var>config</var>, or <code>NULL</code> if none is set. 1012</p> 1013</dd></dl> 1014 1015<dl> 1016<dt><a name="index-config_005fset_005finclude_005ffunc"></a>Function: <em>void</em> <strong>config_set_include_func</strong> <em>(<span class="nolinebreak">config_include_fn_t</span> <var>func</var><!-- /@w -->)</em></dt> 1017<dd> 1018<p><b>Since <i>v1.7</i></b> 1019</p> 1020<p>Specifies the include function <var>func</var> to use when processing 1021include directives. If <var>func</var> is <code>NULL</code>, the default include function, 1022<code>config_default_include_func()</code>, will be reinstated. 1023</p> 1024<a name="index-config_005finclude_005ffn_005ft"></a> 1025<p>The type <i>config_include_fn_t</i> is a type alias 1026for a function whose signature is: 1027</p> 1028<dl> 1029<dt><a name="index-func"></a>Function: <em>const char **<!-- /@w --></em> <strong>func</strong> <em>(<span class="nolinebreak">config_t</span> *<var>config</var><!-- /@w -->, const char *<var><span class="nolinebreak">include_dir</span></var><!-- /@w -->, const char *<var>path</var><!-- /@w -->, const char **<var>error</var><!-- /@w -->)</em></dt> 1030<dd> 1031<p>The function receives the configuration <var>config</var>, the 1032configuration’s current include directory <var>include_dir</var>, the 1033argument to the include directive <var>path</var>; and a pointer at which 1034to return an error message <var>error</var>. 1035</p> 1036<p>On success, the function should return a <code>NULL</code>-terminated array 1037of paths. Any relative paths must be relative to the program’s current 1038working directory. The contents of these files will be inlined at the point 1039of inclusion, in the order that the paths appear in the 1040array. Both the array and its elements should be heap allocated; the 1041library will take ownership of and eventually free the strings in the 1042array and the array itself. 1043</p> 1044<p>On failure, the function should return <code>NULL</code> and set <var>*error</var> to a 1045static error string which should be used as the parse error for the 1046configuration; the library does not take ownership of or free this string. 1047</p> 1048<p>The default include function, <code>config_default_include_func()</code>, 1049simply returns a <code>NULL</code>-terminated array containing either a copy 1050of <var>path</var> if it’s an absolute path, or a concatenation of 1051<var>include_dir</var> and <var>path</var> if it’s a relative path. 1052</p> 1053</dd></dl> 1054 1055<p>Application-supplied include functions can perform custom tasks like wildcard 1056expansion or variable substitution. For example, consider the include directive: 1057</p> 1058<table class="cartouche" border="1"><tr><td> 1059<div class="smallexample"> 1060<pre class="smallexample">@include "configs/*.cfg" 1061</pre></div> 1062</td></tr></table> 1063 1064<p>The include function would be invoked with the path ‘<samp>configs/*.cfg</samp>’ and 1065could do wildcard expansion on that path, returning a list of paths to files 1066with the file extension ‘<samp>.cfg</samp>’ in the subdirectory ‘<samp>configs</samp>’. Each of 1067these files would then be inlined at the location of the include directive. 1068</p> 1069<p>Tasks like wildcard expansion and variable substitution are non-trivial to 1070implement and typically require platform-specific code. In the interests of 1071keeping the library as compact and platform-independent as possible, 1072implementations of such include functions are not included. 1073</p> 1074</dd></dl> 1075 1076<dl> 1077<dt><a name="index-config_005fget_005ffloat_005fprecision_0028config_005ft-_002aconfig_0029"></a>Function: <em>unsigned short</em> <strong>config_get_float_precision(<span class="nolinebreak">config_t</span> *<var>config</var><!-- /@w -->)</strong></dt> 1078<dt><a name="index-config_005fset_005ffloat_005fprecision_0028config_005ft-_002aconfig_002c"></a>Function: <em>void</em> <strong>config_set_float_precision(<span class="nolinebreak">config_t</span> *<var>config</var><!-- /@w -->,</strong> <em>unsigned short <var>digits</var><!-- /@w -->)</em></dt> 1079<dd> 1080<p><b>Since <i>v1.6</i></b> 1081</p> 1082<p>These functions get and set the number of decimal digits to output after the 1083radix character when writing the configuration to a file or stream. 1084</p> 1085<p>Valid values for <var>digits</var> range from 0 (no decimals) to about 15 1086(implementation defined). This parameter has no effect on parsing. 1087</p> 1088<p>The default float precision is 6. 1089</p> 1090</dd></dl> 1091 1092<dl> 1093<dt><a name="index-config_005fget_005foptions"></a>Function: <em>int</em> <strong>config_get_options</strong> <em>(<span class="nolinebreak">config_t</span> *<var>config</var><!-- /@w -->)</em></dt> 1094<dt><a name="index-config_005fset_005foptions"></a>Function: <em>void</em> <strong>config_set_options</strong> <em>(<span class="nolinebreak">config_t</span> *<var>config</var><!-- /@w -->, int <var>options</var><!-- /@w -->)</em></dt> 1095<dd> 1096<p>These functions get and set the options for the configuration 1097<var>config</var>. The options affect how configurations are read and 1098written. The following options are defined: 1099</p> 1100<dl compact="compact"> 1101<dt><code>CONFIG_OPTION_AUTOCONVERT</code></dt> 1102<dd><p>Turning this option on enables number auto-conversion for 1103the configuration. When this feature is enabled, an attempt to retrieve a 1104floating point setting’s value into an integer (or vice versa), or 1105store an integer to a floating point setting’s value (or vice versa) 1106will cause the library to silently perform the necessary conversion 1107(possibly leading to loss of data), rather than reporting failure. By 1108default this option is turned off. 1109</p> 1110</dd> 1111<dt><code>CONFIG_OPTION_SEMICOLON_SEPARATORS</code></dt> 1112<dd><p>This option controls whether a semicolon (‘;’) is output after each setting 1113when the configuration is written to a file or stream. (The semicolon 1114separators are optional in the configuration syntax.) By default this 1115option is turned on. 1116</p> 1117</dd> 1118<dt><code>CONFIG_OPTION_COLON_ASSIGNMENT_FOR_GROUPS</code></dt> 1119<dd><p>This option controls whether a colon (‘:’) is output between each 1120group setting’s name and its value when the configuration is written to 1121a file or stream. If the option is turned off, an equals sign (‘=’) is 1122output instead. (These tokens are interchangeable in the configuration 1123syntax.) By default this option is turned on. 1124</p> 1125</dd> 1126<dt><code>CONFIG_OPTION_COLON_ASSIGNMENT_FOR_NON_GROUPS</code></dt> 1127<dd><p>This option controls whether a colon (‘:’) is output between each 1128non-group setting’s name and its value when the configuration is written 1129to a file or stream. If the option is turned off, an equals sign (‘=’) 1130is output instead. (These tokens are interchangeable in the configuration 1131syntax.) By default this option is turned off. 1132</p> 1133</dd> 1134<dt><code>CONFIG_OPTION_OPEN_BRACE_ON_SEPARATE_LINE</code></dt> 1135<dd><p>This option controls whether an open brace (‘{’) will be written on its own 1136line when the configuration is written to a file or stream. If the option is 1137turned off, the brace will be written at the end of the previous line. 1138By default this option is turned on. 1139</p> 1140</dd> 1141<dt><code>CONFIG_OPTION_ALLOW_SCIENTIFIC_NOTATION</code></dt> 1142<dd><p>(<b>Since <i>v1.7</i></b>) 1143This option controls whether scientific notation may be used as appropriate 1144when writing floating point values (corresponding to <code>printf()</code> 1145‘<samp>%g</samp>’ format) or should never be used (corresponding to <code>printf()</code> 1146‘<samp>%f</samp>’ format). By default this option is turned off. 1147</p> 1148</dd> 1149<dt><code>CONFIG_OPTION_FSYNC</code></dt> 1150<dd><p>(<b>Since <i>v1.7.1</i></b>) 1151This option controls whether the <code>config_write_file()</code> function performs 1152an <i>fsync</i> operation after writing the configuration and before closing the 1153file. By default this option is turned off. 1154</p></dd> 1155</dl> 1156 1157</dd></dl> 1158 1159<dl> 1160<dt><a name="index-config_005fget_005foption"></a>Function: <em>int</em> <strong>config_get_option</strong> <em>(<span class="nolinebreak">config_t</span> *<var>config</var><!-- /@w -->, int <var>option</var><!-- /@w -->)</em></dt> 1161<dt><a name="index-config_005fset_005foption"></a>Function: <em>void</em> <strong>config_set_option</strong> <em>(<span class="nolinebreak">config_t</span> *<var>config</var><!-- /@w -->, int <var>option</var><!-- /@w -->, int <var>flag</var><!-- /@w -->)</em></dt> 1162<dd> 1163<p><b>Since <i>v1.7</i></b> 1164</p> 1165<p>These functions get and set the given <var>option</var> of the configuration 1166<var>config</var>. The option is enabled if <var>flag</var> is <code>CONFIG_TRUE</code> and 1167disabled if it is <code>CONFIG_FALSE</code>. 1168</p> 1169<p>See <code>config_set_options()</code> above for the list of available options. 1170</p> 1171</dd></dl> 1172 1173 1174<dl> 1175<dt><a name="index-config_005fget_005fauto_005fconvert"></a>Function: <em>int</em> <strong>config_get_auto_convert</strong> <em>(const <span class="nolinebreak">config_t</span> *<var>config</var><!-- /@w -->)</em></dt> 1176<dt><a name="index-config_005fset_005fauto_005fconvert"></a>Function: <em>void</em> <strong>config_set_auto_convert</strong> <em>(<span class="nolinebreak">config_t</span> *<var>config</var><!-- /@w -->, int <var>flag</var><!-- /@w -->)</em></dt> 1177<dd> 1178<p>These functions get and set the <code>CONFIG_OPTION_AUTO_CONVERT</code> 1179option. They are obsoleted by the <code>config_set_option()</code> and 1180<code>config_get_option()</code> functions described above. 1181</p> 1182</dd></dl> 1183 1184<dl> 1185<dt><a name="index-config_005fget_005fdefault_005fformat"></a>Function: <em>short</em> <strong>config_get_default_format</strong> <em>(<span class="nolinebreak">config_t</span> * <var>config</var><!-- /@w -->)</em></dt> 1186<dt><a name="index-config_005fset_005fdefault_005fformat"></a>Function: <em>void</em> <strong>config_set_default_format</strong> <em>(<span class="nolinebreak">config_t</span> * <var>config</var><!-- /@w -->, short <var>format</var><!-- /@w -->)</em></dt> 1187<dd> 1188<p>These functions, which are implemented as macros, get and set the 1189default external format for settings in the configuration 1190<var>config</var>. If a non-default format has not been set for a setting 1191with <code>config_setting_set_format()</code>, this configuration-wide 1192default format will be used instead when that setting is written to a 1193file or stream. 1194</p> 1195</dd></dl> 1196 1197<dl> 1198<dt><a name="index-config_005fget_005ftab_005fwidth"></a>Function: <em>unsigned short</em> <strong>config_get_tab_width</strong> <em>(const <span class="nolinebreak">config_t</span> * <var>config</var><!-- /@w -->)</em></dt> 1199<dt><a name="index-config_005fset_005ftab_005fwidth"></a>Function: <em>void</em> <strong>config_set_tab_width</strong> <em>(<span class="nolinebreak">config_t</span> * <var>config</var><!-- /@w -->, unsigned short <var>width</var><!-- /@w -->)</em></dt> 1200<dd> 1201<p>These functions, which are implemented as macros, get and set the tab 1202width for the configuration <var>config</var>. The tab width affects the 1203formatting of the configuration when it is written to a file or 1204stream: each level of nesting is indented by <var>width</var> spaces, or 1205by a single tab character if <var>width</var> is 0. The tab width has no 1206effect on parsing. 1207</p> 1208<p>Valid tab widths range from 0 to 15. The default tab width is 2. 1209</p> 1210</dd></dl> 1211 1212<dl> 1213<dt><a name="index-config_005flookup_005fint"></a>Function: <em>int</em> <strong>config_lookup_int</strong> <em>(const <span class="nolinebreak">config_t</span> * <var>config</var><!-- /@w -->, const char * <var>path</var><!-- /@w -->, int * <var>value</var><!-- /@w -->)</em></dt> 1214<dt><a name="index-config_005flookup_005fint64"></a>Function: <em>int</em> <strong>config_lookup_int64</strong> <em>(const <span class="nolinebreak">config_t</span> * <var>config</var><!-- /@w -->, const char * <var>path</var><!-- /@w -->, long long * <var>value</var><!-- /@w -->)</em></dt> 1215<dt><a name="index-config_005flookup_005ffloat"></a>Function: <em>int</em> <strong>config_lookup_float</strong> <em>(const <span class="nolinebreak">config_t</span> * <var>config</var><!-- /@w -->, const char * <var>path</var><!-- /@w -->, double * <var>value</var><!-- /@w -->)</em></dt> 1216<dt><a name="index-config_005flookup_005fbool"></a>Function: <em>int</em> <strong>config_lookup_bool</strong> <em>(const <span class="nolinebreak">config_t</span> * <var>config</var><!-- /@w -->, const char * <var>path</var><!-- /@w -->, int * <var>value</var><!-- /@w -->)</em></dt> 1217<dt><a name="index-config_005flookup_005fstring"></a>Function: <em>int</em> <strong>config_lookup_string</strong> <em>(const <span class="nolinebreak">config_t</span> * <var>config</var><!-- /@w -->, const char * <var>path</var><!-- /@w -->, const char ** <var>value</var><!-- /@w -->)</em></dt> 1218<dd> 1219<p>These functions look up the value of the setting in the configuration 1220<var>config</var> specified by the path <var>path</var>. They store the value of 1221the setting at <var>value</var> and return <code>CONFIG_TRUE</code> on 1222success. If the setting was not found or if the type of the value did 1223not match the type requested, they leave the data pointed to by 1224<var>value</var> unmodified and return <code>CONFIG_FALSE</code>. 1225</p> 1226<p>Storage for the string returned by <code>config_lookup_string()</code> is 1227managed by the library and released automatically when the setting is 1228destroyed or when the setting’s value is changed; the string must not 1229be freed by the caller. 1230</p> 1231</dd></dl> 1232 1233<dl> 1234<dt><a name="index-config_005flookup"></a>Function: <em>config_setting_t *</em> <strong>config_lookup</strong> <em>(const <span class="nolinebreak">config_t</span> * <var>config</var><!-- /@w -->, const char * <var>path</var><!-- /@w -->)</em></dt> 1235<dd> 1236<p>This function locates the setting in the configuration <var>config</var> 1237specified by the path <var>path</var>. It returns a pointer to the 1238<code>config_setting_t</code> structure on success, or <code>NULL</code> if the 1239setting was not found. 1240</p> 1241</dd></dl> 1242 1243<dl> 1244<dt><a name="index-config_005fsetting_005flookup"></a>Function: <em>config_setting_t *</em> <strong>config_setting_lookup</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->, const char * <var>path</var><!-- /@w -->)</em></dt> 1245<dd> 1246<p>This function locates a setting by a path <var>path</var> relative to 1247the setting <var>setting</var>. It returns a pointer to the 1248<code>config_setting_t</code> structure on success, or <code>NULL</code> if the 1249setting was not found. 1250</p> 1251</dd></dl> 1252 1253<dl> 1254<dt><a name="index-config_005fsetting_005fget_005fint"></a>Function: <em>int</em> <strong>config_setting_get_int</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->)</em></dt> 1255<dt><a name="index-config_005fsetting_005fget_005fint64"></a>Function: <em>long long</em> <strong>config_setting_get_int64</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->)</em></dt> 1256<dt><a name="index-config_005fsetting_005fget_005ffloat"></a>Function: <em>double</em> <strong>config_setting_get_float</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->)</em></dt> 1257<dt><a name="index-config_005fsetting_005fget_005fbool"></a>Function: <em>int</em> <strong>config_setting_get_bool</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->)</em></dt> 1258<dt><a name="index-config_005fsetting_005fget_005fstring"></a>Function: <em>const char *</em> <strong>config_setting_get_string</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->)</em></dt> 1259<dd> 1260<p>These functions return the value of the given <var>setting</var>. If the 1261type of the setting does not match the type requested, a 0 or 1262<code>NULL</code> value is returned. Storage for the string returned by 1263<code>config_setting_get_string()</code> is managed by the library and 1264released automatically when the setting is destroyed or when the 1265setting’s value is changed; the string must not be freed by the 1266caller. 1267</p> 1268</dd></dl> 1269<dl> 1270<dt><a name="index-config_005fsetting_005fset_005fint"></a>Function: <em>int</em> <strong>config_setting_set_int</strong> <em>(<span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->, int <var>value</var><!-- /@w -->)</em></dt> 1271<dt><a name="index-config_005fsetting_005fset_005fint64"></a>Function: <em>int</em> <strong>config_setting_set_int64</strong> <em>(<span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->, long long <var>value</var><!-- /@w -->)</em></dt> 1272<dt><a name="index-config_005fsetting_005fset_005ffloat"></a>Function: <em>int</em> <strong>config_setting_set_float</strong> <em>(<span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->, double <var>value</var><!-- /@w -->)</em></dt> 1273<dt><a name="index-config_005fsetting_005fset_005fbool"></a>Function: <em>int</em> <strong>config_setting_set_bool</strong> <em>(<span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->, int <var>value</var><!-- /@w -->)</em></dt> 1274<dt><a name="index-config_005fsetting_005fset_005fstring"></a>Function: <em>int</em> <strong>config_setting_set_string</strong> <em>(<span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->, const char * <var>value</var><!-- /@w -->)</em></dt> 1275<dd> 1276<p>These functions set the value of the given <var>setting</var> to 1277<var>value</var>. On success, they return <code>CONFIG_TRUE</code>. If 1278the setting does not match the type of the value, they return 1279<code>CONFIG_FALSE</code>. <code>config_setting_set_string()</code> makes a copy 1280of the passed string <var>value</var>, so it may be subsequently freed or 1281modified by the caller without affecting the value of the setting. 1282</p> 1283</dd></dl> 1284 1285<dl> 1286<dt><a name="index-config_005fsetting_005flookup_005fint"></a>Function: <em>int</em> <strong>config_setting_lookup_int</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->, const char * <var>name</var><!-- /@w -->, int * <var>value</var><!-- /@w -->)</em></dt> 1287<dt><a name="index-config_005fsetting_005flookup_005fint64"></a>Function: <em>int</em> <strong>config_setting_lookup_int64</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->, const char * <var>name</var><!-- /@w -->, long long * <var>value</var><!-- /@w -->)</em></dt> 1288<dt><a name="index-config_005fsetting_005flookup_005ffloat"></a>Function: <em>int</em> <strong>config_setting_lookup_float</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->, const char * <var>name</var><!-- /@w -->, double * <var>value</var><!-- /@w -->)</em></dt> 1289<dt><a name="index-config_005fsetting_005flookup_005fbool"></a>Function: <em>int</em> <strong>config_setting_lookup_bool</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->, const char * <var>name</var><!-- /@w -->, int * <var>value</var><!-- /@w -->)</em></dt> 1290<dt><a name="index-config_005fsetting_005flookup_005fstring"></a>Function: <em>int</em> <strong>config_setting_lookup_string</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->, const char * <var>name</var><!-- /@w -->, const char ** <var>value</var><!-- /@w -->)</em></dt> 1291<dd> 1292<p>These functions look up the value of the child setting named 1293<var>name</var> of the setting <var>setting</var>. They store the value at 1294<var>value</var> and return <code>CONFIG_TRUE</code> on success. If the setting 1295was not found or if the type of the value did not match the type 1296requested, they leave the data pointed to by <var>value</var> unmodified 1297and return <code>CONFIG_FALSE</code>. 1298</p> 1299<p>Storage for the string returned by <code>config_setting_lookup_string()</code> is 1300managed by the library and released automatically when the setting is 1301destroyed or when the setting’s value is changed; the string must not 1302be freed by the caller. 1303</p> 1304</dd></dl> 1305 1306<dl> 1307<dt><a name="index-config_005fsetting_005fget_005fformat"></a>Function: <em>short</em> <strong>config_setting_get_format</strong> <em>(<span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->)</em></dt> 1308<dt><a name="index-config_005fsetting_005fset_005fformat"></a>Function: <em>int</em> <strong>config_setting_set_format</strong> <em>(<span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->, short <var>format</var><!-- /@w -->)</em></dt> 1309<dd> 1310<p>These functions get and set the external format for the setting <var>setting</var>. 1311</p> 1312<a name="index-SettingFormat"></a> 1313<a name="index-format"></a> 1314 1315<p>The <var>format</var> must be one of the constants 1316<code>CONFIG_FORMAT_DEFAULT</code> or <code>CONFIG_FORMAT_HEX</code>. All settings 1317support the <code>CONFIG_FORMAT_DEFAULT</code> format. The 1318<code>CONFIG_FORMAT_HEX</code> format specifies hexadecimal formatting for 1319integer values, and hence only applies to settings of type 1320<code>CONFIG_TYPE_INT</code> and <code>CONFIG_TYPE_INT64</code>. If <var>format</var> 1321is invalid for the given setting, it is ignored. 1322</p> 1323<p>If a non-default format has not been set for the setting, <code>config_setting_get_format()</code> returns the default format for the configuration, as set by <code>config_set_default_format()</code>. 1324</p> 1325<p><code>config_setting_set_format()</code> returns <code>CONFIG_TRUE</code> on 1326success and <code>CONFIG_FALSE</code> on failure. 1327</p> 1328</dd></dl> 1329 1330 1331<dl> 1332<dt><a name="index-config_005fsetting_005fget_005fmember"></a>Function: <em>config_setting_t *</em> <strong>config_setting_get_member</strong> <em>(<span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->, const char * <var>name</var><!-- /@w -->)</em></dt> 1333<dd> 1334<p>This function fetches the child setting named <var>name</var> from the group 1335<var>setting</var>. It returns the requested setting on success, or 1336<code>NULL</code> if the setting was not found or if <var>setting</var> is not a 1337group. 1338</p> 1339</dd></dl> 1340 1341<dl> 1342<dt><a name="index-config_005fsetting_005fget_005felem"></a>Function: <em>config_setting_t *</em> <strong>config_setting_get_elem</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->, unsigned int <var>index</var><!-- /@w -->)</em></dt> 1343<dd> 1344<p>This function fetches the element at the given index <var>index</var> in the 1345setting <var>setting</var>, which must be an array, list, or group. It returns the 1346requested setting on success, or <code>NULL</code> if <var>index</var> is out of 1347range or if <var>setting</var> is not an array, list, or group. 1348</p> 1349</dd></dl> 1350 1351<dl> 1352<dt><a name="index-config_005fsetting_005fget_005fint_005felem"></a>Function: <em>int</em> <strong>config_setting_get_int_elem</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->, int <var>index</var><!-- /@w -->)</em></dt> 1353<dt><a name="index-config_005fsetting_005fget_005fint64_005felem"></a>Function: <em>long long</em> <strong>config_setting_get_int64_elem</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->, int <var>index</var><!-- /@w -->)</em></dt> 1354<dt><a name="index-config_005fsetting_005fget_005ffloat_005felem"></a>Function: <em>double</em> <strong>config_setting_get_float_elem</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->, int <var>index</var><!-- /@w -->)</em></dt> 1355<dt><a name="index-config_005fsetting_005fget_005fbool_005felem"></a>Function: <em>int</em> <strong>config_setting_get_bool_elem</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->, int <var>index</var><!-- /@w -->)</em></dt> 1356<dt><a name="index-config_005fsetting_005fget_005fstring_005felem"></a>Function: <em>const char *</em> <strong>config_setting_get_string_elem</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->, int <var>index</var><!-- /@w -->)</em></dt> 1357<dd> 1358<p>These functions return the value at the specified index <var>index</var> in the 1359setting <var>setting</var>. If the setting is not an array or list, or if 1360the type of the element does not match the type requested, or if 1361<var>index</var> is out of range, they return 0 or <code>NULL</code>. Storage for 1362the string returned by <code>config_setting_get_string_elem()</code> is 1363managed by the library and released automatically when the setting is 1364destroyed or when its value is changed; the string must not be freed 1365by the caller. 1366</p></dd></dl> 1367 1368<dl> 1369<dt><a name="index-config_005fsetting_005fset_005fint_005felem"></a>Function: <em>config_setting_t *</em> <strong>config_setting_set_int_elem</strong> <em>(<span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->, int <var>index</var><!-- /@w -->, int <var>value</var><!-- /@w -->)</em></dt> 1370<dt><a name="index-config_005fsetting_005fset_005fint64_005felem"></a>Function: <em>config_setting_t *</em> <strong>config_setting_set_int64_elem</strong> <em>(<span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->, int <var>index</var><!-- /@w -->, long long <var>value</var><!-- /@w -->)</em></dt> 1371<dt><a name="index-config_005fsetting_005fset_005ffloat_005felem"></a>Function: <em>config_setting_t *</em> <strong>config_setting_set_float_elem</strong> <em>(<span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->, int <var>index</var><!-- /@w -->, double <var>value</var><!-- /@w -->)</em></dt> 1372<dt><a name="index-config_005fsetting_005fset_005fbool_005felem"></a>Function: <em>config_setting_t *</em> <strong>config_setting_set_bool_elem</strong> <em>(<span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->, int <var>index</var><!-- /@w -->, int <var>value</var><!-- /@w -->)</em></dt> 1373<dt><a name="index-config_005fsetting_005fset_005fstring_005felem"></a>Function: <em>config_setting_t *</em> <strong>config_setting_set_string_elem</strong> <em>(<span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->, int <var>index</var><!-- /@w -->, const char * <var>value</var><!-- /@w -->)</em></dt> 1374<dd> 1375<p>These functions set the value at the specified index <var>index</var> in the 1376setting <var>setting</var> to <var>value</var>. If <var>index</var> is negative, a 1377new element is added to the end of the array or list. On success, 1378these functions return a pointer to the setting representing the 1379element. If the setting is not an array or list, or if the setting is 1380an array and the type of the array does not match the type of the 1381value, or if <var>index</var> is out of range, they return 1382<code>NULL</code>. <code>config_setting_set_string_elem()</code> makes a copy of 1383the passed string <var>value</var>, so it may be subsequently freed or 1384modified by the caller without affecting the value of the setting. 1385</p></dd></dl> 1386 1387<dl> 1388<dt><a name="index-config_005fsetting_005fadd"></a>Function: <em>config_setting_t *</em> <strong>config_setting_add</strong> <em>(<span class="nolinebreak">config_setting_t</span> * <var>parent</var><!-- /@w -->, const char * <var>name</var><!-- /@w -->, int <var>type</var><!-- /@w -->)</em></dt> 1389<dd> 1390<p>This function adds a new child setting or element to the setting 1391<var>parent</var>, which must be a group, array, or list. If <var>parent</var> 1392is an array or list, the <var>name</var> parameter is ignored and may be 1393<code>NULL</code>. 1394</p> 1395<p>The function returns the new setting on success, or <code>NULL</code> if 1396<var>parent</var> is not a group, array, or list; or if there is already a 1397child setting of <var>parent</var> named <var>name</var>; or if <var>type</var> is 1398invalid. If <var>type</var> is a scalar type, the new setting will have a 1399default value of 0, 0.0, <code>false</code>, or <code>NULL</code>, as appropriate. 1400</p></dd></dl> 1401 1402<dl> 1403<dt><a name="index-config_005fsetting_005fremove"></a>Function: <em>int</em> <strong>config_setting_remove</strong> <em>(<span class="nolinebreak">config_setting_t</span> * <var>parent</var><!-- /@w -->, const char * <var>name</var><!-- /@w -->)</em></dt> 1404<dd> 1405<p>This function removes and destroys the setting named <var>name</var> from 1406the parent setting <var>parent</var>, which must be a group. Any child 1407settings of the setting are recursively destroyed as well. 1408</p> 1409<p>The <var>name</var> parameter can also specify a setting <i>path</i> relative to 1410the provided <var>parent</var>. 1411(In that case, the setting will be looked up and removed.) 1412</p> 1413<p>The function returns <code>CONFIG_TRUE</code> on success. If <var>parent</var> is 1414not a group, or if it has no setting with the given name, it returns 1415<code>CONFIG_FALSE</code>. 1416</p> 1417</dd></dl> 1418 1419<dl> 1420<dt><a name="index-config_005fsetting_005fremove_005felem"></a>Function: <em>int</em> <strong>config_setting_remove_elem</strong> <em>(<span class="nolinebreak">config_setting_t</span> * <var>parent</var><!-- /@w -->, unsigned int <var>index</var><!-- /@w -->)</em></dt> 1421<dd> 1422<p>This function removes the child setting at the given index <var>index</var> from 1423the setting <var>parent</var>, which must be a group, list, or array. Any 1424child settings of the removed setting are recursively destroyed as 1425well. 1426</p> 1427<p>The function returns <code>CONFIG_TRUE</code> on success. If <var>parent</var> is 1428not a group, list, or array, or if <var>index</var> is out of range, it returns 1429<code>CONFIG_FALSE</code>. 1430</p> 1431</dd></dl> 1432 1433<dl> 1434<dt><a name="index-config_005froot_005fsetting"></a>Function: <em>config_setting_t *</em> <strong>config_root_setting</strong> <em>(const <span class="nolinebreak">config_t</span> * <var>config</var><!-- /@w -->)</em></dt> 1435<dd> 1436<p>This function, which is implemented as a macro, returns the root setting for the configuration <var>config</var>. The root setting is a group. 1437</p> 1438</dd></dl> 1439 1440<dl> 1441<dt><a name="index-config_005fsetting_005fname"></a>Function: <em>const char *</em> <strong>config_setting_name</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->)</em></dt> 1442<dd> 1443<p>This function returns the name of the given <var>setting</var>, or 1444<code>NULL</code> if the setting has no name. Storage for the returned 1445string is managed by the library and released automatically when the 1446setting is destroyed; the string must not be freed by the caller. 1447</p> 1448</dd></dl> 1449 1450<dl> 1451<dt><a name="index-config_005fsetting_005fparent"></a>Function: <em>config_setting_t *</em> <strong>config_setting_parent</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->)</em></dt> 1452<dd> 1453<p>This function returns the parent setting of the given <var>setting</var>, 1454or <code>NULL</code> if <var>setting</var> is the root setting. 1455</p> 1456</dd></dl> 1457 1458<dl> 1459<dt><a name="index-config_005fsetting_005fis_005froot"></a>Function: <em>int</em> <strong>config_setting_is_root</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->)</em></dt> 1460<dd> 1461<p>This function returns <code>CONFIG_TRUE</code> if the given <var>setting</var> is 1462the root setting, and <code>CONFIG_FALSE</code> otherwise. 1463</p> 1464</dd></dl> 1465 1466<dl> 1467<dt><a name="index-config_005fsetting_005findex"></a>Function: <em>int</em> <strong>config_setting_index</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->)</em></dt> 1468<dd> 1469<p>This function returns the index of the given <var>setting</var> within its 1470parent setting. If <var>setting</var> is the root setting, this function 1471returns -1. 1472</p> 1473</dd></dl> 1474 1475<dl> 1476<dt><a name="index-config_005fsetting_005flength"></a>Function: <em>int</em> <strong>config_setting_length</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->)</em></dt> 1477<dd> 1478<p>This function returns the number of settings in a group, or the number of 1479elements in a list or array. For other types of settings, it returns 14800. 1481</p> 1482</dd></dl> 1483 1484<dl> 1485<dt><a name="index-config_005fsetting_005ftype"></a>Function: <em>int</em> <strong>config_setting_type</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->)</em></dt> 1486<dd> 1487<p>This function returns the type of the given <var>setting</var>. The return 1488value is one of the constants 1489<code>CONFIG_TYPE_INT</code>, <code>CONFIG_TYPE_INT64</code>, <code>CONFIG_TYPE_FLOAT</code>, 1490<code>CONFIG_TYPE_STRING</code>, <code>CONFIG_TYPE_BOOL</code>, 1491<code>CONFIG_TYPE_ARRAY</code>, <code>CONFIG_TYPE_LIST</code>, or <code>CONFIG_TYPE_GROUP</code>. 1492</p> 1493</dd></dl> 1494 1495<dl> 1496<dt><a name="index-config_005fsetting_005fis_005fgroup"></a>Function: <em>int</em> <strong>config_setting_is_group</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->)</em></dt> 1497<dt><a name="index-config_005fsetting_005fis_005farray"></a>Function: <em>int</em> <strong>config_setting_is_array</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->)</em></dt> 1498<dt><a name="index-config_005fsetting_005fis_005flist"></a>Function: <em>int</em> <strong>config_setting_is_list</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->)</em></dt> 1499<dd> 1500<p>These convenience functions, which are implemented as macros, test if 1501the setting <var>setting</var> is of a given type. They return 1502<code>CONFIG_TRUE</code> or <code>CONFIG_FALSE</code>. 1503</p> 1504</dd></dl> 1505 1506<dl> 1507<dt><a name="index-config_005fsetting_005fis_005faggregate"></a>Function: <em>int</em> <strong>config_setting_is_aggregate</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->)</em></dt> 1508<dt><a name="index-config_005fsetting_005fis_005fscalar"></a>Function: <em>int</em> <strong>config_setting_is_scalar</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->)</em></dt> 1509<dt><a name="index-config_005fsetting_005fis_005fnumber"></a>Function: <em>int</em> <strong>config_setting_is_number</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->)</em></dt> 1510<dd> 1511<a name="index-aggregate-value"></a> 1512<p>These convenience functions, some of which are implemented as macros, test if 1513the setting <var>setting</var> is of an aggregate type (a group, array, or 1514list), of a scalar type (integer, 64-bit integer, floating point, 1515boolean, or string), and of a number (integer, 64-bit integer, or 1516floating point), respectively. They return <code>CONFIG_TRUE</code> or 1517<code>CONFIG_FALSE</code>. 1518</p> 1519</dd></dl> 1520 1521<dl> 1522<dt><a name="index-config_005fsetting_005fsource_005ffile"></a>Function: <em>const char *</em> <strong>config_setting_source_file</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->)</em></dt> 1523<dd> 1524<p>This function returns the name of the file from which the setting 1525<var>setting</var> was read, or NULL if the setting was not read from a 1526file. This information is useful for reporting application-level 1527errors. Storage for the returned string is managed by the library and 1528released automatically when the configuration is destroyed; the 1529string must not be freed by the caller. 1530</p> 1531</dd></dl> 1532 1533<dl> 1534<dt><a name="index-config_005fsetting_005fsource_005fline"></a>Function: <em>unsigned int</em> <strong>config_setting_source_line</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->)</em></dt> 1535<dd> 1536<p>This function returns the line number of the configuration file or 1537stream at which the setting <var>setting</var> was read, or 0 if no line 1538number is available. This information is useful for reporting 1539application-level errors. 1540</p> 1541</dd></dl> 1542 1543<dl> 1544<dt><a name="index-config_005fset_005fhook"></a>Function: <em>void</em> <strong>config_set_hook</strong> <em>(<span class="nolinebreak">config_t</span> * <var>config</var><!-- /@w -->, void * <var>hook</var><!-- /@w -->)</em></dt> 1545<dt><a name="index-config_005fget_005fhook"></a>Function: <em>void *</em> <strong>config_get_hook</strong> <em>(const <span class="nolinebreak">config_t</span> * <var>config</var><!-- /@w -->)</em></dt> 1546<dd> 1547<p><b>Since <i>v1.7</i></b> 1548</p> 1549<a name="index-hook"></a> 1550<p>These functions make it possible to attach arbitrary data to a configuration 1551structure, for instance a “wrapper” or “peer” object written in 1552another programming language. 1553</p> 1554</dd></dl> 1555 1556<dl> 1557<dt><a name="index-config_005fsetting_005fset_005fhook"></a>Function: <em>void</em> <strong>config_setting_set_hook</strong> <em>(<span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->, void * <var>hook</var><!-- /@w -->)</em></dt> 1558<dt><a name="index-config_005fsetting_005fget_005fhook"></a>Function: <em>void *</em> <strong>config_setting_get_hook</strong> <em>(const <span class="nolinebreak">config_setting_t</span> * <var>setting</var><!-- /@w -->)</em></dt> 1559<dd> 1560<a name="index-hook-1"></a> 1561<p>These functions make it possible to attach arbitrary data to each 1562setting structure, for instance a “wrapper” or “peer” object written in 1563another programming language. The destructor function, if one has been 1564supplied via a call to <code>config_set_destructor()</code>, will be called 1565by the library to dispose of this data when the setting itself is 1566destroyed. There is no default destructor. 1567</p> 1568</dd></dl> 1569 1570<dl> 1571<dt><a name="index-config_005fset_005fdestructor"></a>Function: <em>void</em> <strong>config_set_destructor</strong> <em>(<span class="nolinebreak">config_t</span> * <var>config</var><!-- /@w -->, void (* <var>destructor</var>)(void *)<!-- /@w -->)</em></dt> 1572<dd> 1573<a name="index-destructor-function"></a> 1574<p>This function assigns the destructor function <var>destructor</var> for the 1575configuration <var>config</var>. This function accepts a single <code>void 1576*</code> argument and has no return value. See 1577<code>config_setting_set_hook()</code> above for more information. 1578</p> 1579</dd></dl> 1580 1581<hr> 1582<a name="The-C_002b_002b-API"></a> 1583<div class="header"> 1584<p> 1585Next: <a href="#Example-Programs" accesskey="n" rel="next">Example Programs</a>, Previous: <a href="#The-C-API" accesskey="p" rel="prev">The C API</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 1586</div> 1587<a name="The-C_002b_002b-API-1"></a> 1588<h2 class="chapter">4 The C++ API</h2> 1589 1590<a name="index-Config"></a> 1591<a name="index-Setting"></a> 1592<p>This chapter describes the C++ library API. The class <code>Config</code> 1593represents a configuration, and the class <code>Setting</code> represents a 1594configuration setting. Note that by design, neither of these classes 1595provides a public copy constructor or assignment operator. Therefore, 1596instances of these classes may only be passed between functions via 1597references or pointers. 1598</p> 1599<a name="index-ConfigException"></a> 1600<p>The library defines a group of exceptions, all of which extend the 1601common base exception <code>ConfigException</code>. 1602</p> 1603<a name="index-SettingTypeException"></a> 1604<p>A <code>SettingTypeException</code> is thrown when the type of a setting’s 1605value does not match the type requested. 1606</p> 1607<dl> 1608<dt><a name="index-SettingTypeException-on-SettingTypeException"></a>Method on SettingTypeException: <em></em> <strong>SettingTypeException</strong> <em>(const Setting &<var>setting</var><!-- /@w -->)</em></dt> 1609<dt><a name="index-SettingTypeException-on-SettingTypeException-1"></a>Method on SettingTypeException: <em></em> <strong>SettingTypeException</strong> <em>(const Setting &<var>setting</var><!-- /@w -->, int <var>index</var><!-- /@w -->)</em></dt> 1610<dt><a name="index-SettingTypeException-on-SettingTypeException-2"></a>Method on SettingTypeException: <em></em> <strong>SettingTypeException</strong> <em>(const Setting &<var>setting</var><!-- /@w -->, const char *<var>name</var><!-- /@w -->)</em></dt> 1611<dd> 1612<p>These methods construct <code>SettingTypeException</code> objects for the given <var>setting</var> and/or member <var>index</var> or <var>name</var>. 1613</p> 1614</dd></dl> 1615 1616<a name="index-SettingNotFoundException"></a> 1617<p>A <code>SettingNotFoundException</code> is thrown when a setting is not found. 1618</p> 1619<dl> 1620<dt><a name="index-SettingNotFoundException-on-SettingNotFoundException"></a>Method on SettingNotFoundException: <em></em> <strong>SettingNotFoundException</strong> <em>(const Setting &<var>setting</var><!-- /@w -->, int <var>index</var><!-- /@w -->)</em></dt> 1621<dt><a name="index-SettingNotFoundException-on-SettingNotFoundException-1"></a>Method on SettingNotFoundException: <em></em> <strong>SettingNotFoundException</strong> <em>(const Setting &<var>setting</var><!-- /@w -->, const char *<var>name</var><!-- /@w -->)</em></dt> 1622<dt><a name="index-SettingNotFoundException-on-SettingNotFoundException-2"></a>Method on SettingNotFoundException: <em></em> <strong>SettingNotFoundException</strong> <em>(const char *<var>path</var><!-- /@w -->)</em></dt> 1623<dd> 1624<p>These methods construct <code>SettingTypeException</code> objects for the given <var>setting</var> and member <var>index</var> or <var>name</var>, or path <var>path</var>. 1625</p> 1626</dd></dl> 1627 1628<a name="index-SettingNameException"></a> 1629<p>A <code>SettingNameException</code> is thrown when an attempt is made to add 1630a new setting with a non-unique or invalid name. 1631</p> 1632<dl> 1633<dt><a name="index-SettingNameException-on-SettingNameException"></a>Method on SettingNameException: <em></em> <strong>SettingNameException</strong> <em>(const Setting &<var>setting</var><!-- /@w -->, const char *<var>name</var><!-- /@w -->)</em></dt> 1634<dd> 1635<p>This method constructs a <code>SettingNameExcpetion</code> object for the given <var>setting</var> and member name <var>name</var>. 1636</p> 1637</dd></dl> 1638 1639<a name="index-ParseException"></a> 1640<p>A <code>ParseException</code> is thrown when a parse error occurs while 1641reading a configuration from a stream. 1642</p> 1643<dl> 1644<dt><a name="index-ParseException-on-ParseException"></a>Method on ParseException: <em></em> <strong>ParseException</strong> <em>(const char *<var>file</var><!-- /@w -->, int <var>line</var><!-- /@w -->, const char *<var>error</var><!-- /@w -->)</em></dt> 1645<dd> 1646<p>This method constructs a <code>ParseException</code> object with the given filename <var>file</var>, line number <var>line</var>, and error message <var>error</var>. 1647</p> 1648</dd></dl> 1649 1650<a name="index-FileIOException"></a> 1651<p>A <code>FileIOException</code> is thrown when an I/O error occurs while 1652reading/writing a configuration from/to a file. 1653</p> 1654<a name="index-SettingException"></a> 1655<p><code>SettingTypeException</code>, <code>SettingNotFoundException</code>, and 1656<code>SettingNameException</code> all extend the common base 1657exception <code>SettingException</code>, which provides the following method: 1658</p> 1659<dl> 1660<dt><a name="index-getPath-on-SettingException"></a>Method on SettingException: <em>const char *</em> <strong>getPath</strong> <em>() const</em></dt> 1661<dd> 1662<p>This method returns the path to the setting associated with the exception, or 1663<code>NULL</code> if there is no applicable path. 1664</p> 1665</dd></dl> 1666 1667<p>The remainder of this chapter describes the methods for manipulating 1668configurations and configuration settings. 1669</p> 1670<dl> 1671<dt><a name="index-Config-on-Config"></a>Method on Config: <em></em> <strong>Config</strong> <em>()</em></dt> 1672<dt><a name="index-_007eConfig-on-Config"></a>Method on Config: <em></em> <strong>~Config</strong> <em>()</em></dt> 1673<dd> 1674<p>These methods create and destroy <code>Config</code> objects. 1675</p> 1676</dd></dl> 1677 1678<dl> 1679<dt><a name="index-clear-on-Config"></a>Method on Config: <em>void</em> <strong>clear</strong> <em>()</em></dt> 1680<dd> 1681<p><b>Since <i>v1.7</i></b> 1682</p> 1683<p>This method clears the configuration. All child settings of the root 1684setting are recursively destroyed. All other attributes of the 1685configuration are left unchanged. 1686</p> 1687</dd></dl> 1688 1689<dl> 1690<dt><a name="index-read-on-Config"></a>Method on Config: <em>void</em> <strong>read</strong> <em>(FILE * <var>stream</var><!-- /@w -->)</em></dt> 1691<dt><a name="index-write-on-Config"></a>Method on Config: <em>void</em> <strong>write</strong> <em>(FILE * <var>stream</var><!-- /@w -->) const</em></dt> 1692<dd> 1693<p>The <code>read()</code> method reads and parses a configuration from the given 1694<var>stream</var>. A <code>ParseException</code> is thrown if a parse error occurs. 1695</p> 1696<p>The <code>write()</code> method writes the configuration to the given <var>stream</var>. 1697</p> 1698</dd></dl> 1699 1700<dl> 1701<dt><a name="index-readFile-on-Config"></a>Method on Config: <em>void</em> <strong>readFile</strong> <em>(const char * <var>filename</var><!-- /@w -->)</em></dt> 1702<dt><a name="index-writeFile-on-Config"></a>Method on Config: <em>void</em> <strong>writeFile</strong> <em>(const char * <var>filename</var><!-- /@w -->) const</em></dt> 1703<dd> 1704<p>The <code>readFile()</code> method reads and parses a configuration from the 1705file named <var>filename</var>. A <code>ParseException</code> is thrown if a 1706parse error occurs. A <code>FileIOException</code> is thrown if the file 1707cannot be read. 1708</p> 1709<p>The <code>writeFile()</code> method writes the configuration to the file 1710named <var>filename</var>. A <code>FileIOException</code> is thrown if the file cannot 1711be written. 1712</p> 1713</dd></dl> 1714 1715<dl> 1716<dt><a name="index-readString-on-Config"></a>Method on Config: <em>void</em> <strong>readString</strong> <em>(const char * <var>str</var><!-- /@w -->)</em></dt> 1717<dt><a name="index-readString-on-Config-1"></a>Method on Config: <em>void</em> <strong>readString</strong> <em>(const std::string &<var>str</var><!-- /@w -->)</em></dt> 1718<dd> 1719<p>These methods read and parse a configuration from the string 1720<var>str</var>. A <code>ParseException</code> is thrown if a parse error occurs. 1721</p> 1722</dd></dl> 1723 1724<dl> 1725<dt><a name="index-getError-on-ParseException"></a>Method on ParseException: <em>const char *</em> <strong>getError</strong> <em>() const</em></dt> 1726<dt><a name="index-getFile-on-ParseException"></a>Method on ParseException: <em>const char *</em> <strong>getFile</strong> <em>() const</em></dt> 1727<dt><a name="index-getLine-on-ParseException"></a>Method on ParseException: <em>int</em> <strong>getLine</strong> <em>() const</em></dt> 1728<dd> 1729<p>If a call to <code>readFile()</code>, <code>readString()</code>, or <code>read()</code> 1730resulted in a <code>ParseException</code>, these methods can be called on 1731the exception object to obtain the text, filename, and line number of 1732the parse error. Storage for the strings returned by <code>getError()</code> 1733and <code>getFile()</code> are managed by the library; the strings must not 1734be freed by the caller. 1735</p> 1736</dd></dl> 1737 1738<dl> 1739<dt><a name="index-setIncludeDir-on-Config"></a>Method on Config: <em>void</em> <strong>setIncludeDir</strong> <em>(const char *<var>includeDir</var><!-- /@w -->)</em></dt> 1740<dt><a name="index-getIncludeDir-on-Config"></a>Method on Config: <em>const char *</em> <strong>getIncludeDir</strong> <em>() const</em></dt> 1741<dd> 1742<p>The <code>setIncludeDir()</code> method specifies the include directory, 1743<var>includeDir</var>, relative to which the files specified in 1744‘<samp>@include</samp>’ directives will be located for the configuration. By 1745default, there is no include directory, and all include files are 1746expected to be relative to the current working directory. If 1747<var>includeDir</var> is <code>NULL</code>, the default behavior is reinstated. 1748</p> 1749<p>For example, if the include directory is set to <samp>/usr/local/etc</samp>, 1750the include directive ‘<samp>@include "configs/extra.cfg"</samp>’ would include the 1751file <samp>/usr/local/etc/configs/extra.cfg</samp>. 1752</p> 1753<p><code>getIncludeDir()</code> returns the current include directory for the 1754configuration, or <code>NULL</code> if none is set. 1755</p> 1756</dd></dl> 1757 1758<dl> 1759<dt><a name="index-evaluateIncludePath-on-Config"></a>Method on Config: <em>virtual const char **</em> <strong>evaluateIncludePath</strong> <em>(const char * <var>path</var><!-- /@w -->, const char ** <var>error</var><!-- /@w -->)</em></dt> 1760<dd> 1761<p><b>Since <i>v1.7</i></b> 1762</p> 1763<p>This method is called to evaluate the path of an <code>@include</code> directive. 1764The <var>path</var> is the literal path argument of the directive. The method may 1765be overridden in a subclass to perform tasks like wildcard expansion and 1766variable substitution. 1767</p> 1768<p>On success, the method should return a <code>NULL</code>-terminated array of paths. 1769Any relative paths must be relative to the program’s current working directory. 1770The contents of these files will be inlined at the point of inclusion, in the 1771order that the paths appear in the array. Both the array and its elements should 1772be heap allocated; the library will take ownership of and eventually free the 1773strings in the array and the array itself. 1774</p> 1775<p>On failure, the function should return <code>NULL</code> and set <var>*error</var> to a 1776static error string which should be used as the parse error for the 1777configuration; the library does not take ownership of or free this string. 1778</p> 1779<p>The default implementation simply returns a <code>NULL</code>-terminated array 1780containing either a copy of <var>path</var> if it’s an absolute path, or a 1781concatenation of the include directory and <var>path</var> if it’s a relative path. 1782</p> 1783<p>For more information see <code>config_set_include_func()</code> above. 1784</p> 1785</dd></dl> 1786 1787<dl> 1788<dt><a name="index-getOptions-on-Config"></a>Method on Config: <em>int</em> <strong>getOptions</strong> <em>() const</em></dt> 1789<dt><a name="index-setOptions-on-Config"></a>Method on Config: <em>void</em> <strong>setOptions</strong> <em>(int <var>options</var>)</em></dt> 1790<dd> 1791<a name="index-Config_003a_003aOption"></a> 1792<p>These methods get and set the options for the configuration. The 1793options affect how configurations are read and written. The parameter 1794<var>options</var> should be a bitwise-OR of the following <var>Config::Option</var> 1795enumeration values: 1796</p> 1797<dl compact="compact"> 1798<dt><code>Config::OptionAutoConvert</code></dt> 1799<dd><p>Turning this option on enables number auto-conversion for 1800the configuration. When this feature is enabled, an attempt to retrieve a 1801floating point setting’s value into an integer (or vice versa), or 1802store an integer to a floating point setting’s value (or vice versa) 1803will cause the library to silently perform the necessary conversion 1804(possibly leading to loss of data), rather than reporting failure. By 1805default this option is turned off. 1806</p> 1807</dd> 1808<dt><code>Config::OptionSemicolonSeparators</code></dt> 1809<dd><p>This option controls whether a semicolon (‘;’) is output after each setting 1810when the configuration is written to a file or stream. (The semicolon 1811separators are optional in the configuration syntax.) By default this 1812option is turned on. 1813</p> 1814</dd> 1815<dt><code>Config::OptionColonAssignmentForGroups</code></dt> 1816<dd><p>This option controls whether a colon (‘:’) is output between each 1817group setting’s name and its value when the configuration is written to 1818a file or stream. If the option is turned off, an equals sign (‘=’) is 1819output instead. (These tokens are interchangeable in the configuration 1820syntax.) By default this option is turned on. 1821</p> 1822</dd> 1823<dt><code>Config::OptionColonAssignmentForNonGroups</code></dt> 1824<dd><p>This option controls whether a colon (‘:’) is output between each 1825non-group setting’s name and its value when the configuration is written 1826to a file or stream. If the option is turned off, an equals sign (‘=’) 1827is output instead. (These tokens are interchangeable in the configuration 1828syntax.) By default this option is turned off. 1829</p> 1830</dd> 1831<dt><code>Config::OptionOpenBraceOnSeparateLine</code></dt> 1832<dd><p>This option controls whether an open brace (‘{’) will be written on its own 1833line when the configuration is written to a file or stream. If the option is 1834turned off, the brace will be written at the end of the previous line. 1835By default this option is turned on. 1836</p> 1837</dd> 1838<dt><code>Config::OptionAllowScientificNotation</code></dt> 1839<dd><p>(<b>Since <i>v1.7</i></b>) 1840This option controls whether scientific notation may be used as appropriate 1841when writing floating point values (corresponding to <code>printf()</code> 1842‘<samp>%g</samp>’ format) or should never be used (corresponding to <code>printf()</code> 1843‘<samp>%f</samp>’ format). By default this option is turned off. 1844</p> 1845</dd> 1846<dt><code>Config::OptionFsync</code></dt> 1847<dd><p>(<b>Since <i>v1.7.1</i></b>) 1848This option controls whether the <code>writeFile()</code> method performs an <i>fsync</i> 1849operation after writing the configuration and before closing the file. By 1850default this option is turned off. 1851</p> 1852</dd> 1853</dl> 1854 1855</dd></dl> 1856 1857<dl> 1858<dt><a name="index-getOption-on-Config"></a>Method on Config: <em>bool</em> <strong>getOption</strong> <em>(Config::Option <var>option</var><!-- /@w -->) const</em></dt> 1859<dt><a name="index-setOption-on-Config"></a>Method on Config: <em>void</em> <strong>setOption</strong> <em>(Config::Option <var>option</var><!-- /@w -->, bool <var>flag</var><!-- /@w -->)</em></dt> 1860<dd> 1861<p><b>Since <i>v1.7</i></b> 1862</p> 1863<p>These methods get and set the option <var>option</var> for the configuration. The 1864option is enabled if <var>flag</var> is <code>true</code> and disabled if it is 1865<code>false</code>. 1866</p> 1867<p>See <code>setOptions()</code> above for the list of available options. 1868</p> 1869</dd></dl> 1870 1871<dl> 1872<dt><a name="index-getAutoConvert-on-Config"></a>Method on Config: <em>bool</em> <strong>getAutoConvert</strong> <em>() const</em></dt> 1873<dt><a name="index-setAutoConvert-on-Config"></a>Method on Config: <em>void</em> <strong>setAutoConvert</strong> <em>(bool <var>flag</var>)</em></dt> 1874<dd> 1875<p>These methods get and set the <code>OptionAutoConvert</code> option. They 1876are obsoleted by the <code>setOption()</code> and <code>getOption()</code> 1877methods described above. 1878</p> 1879</dd></dl> 1880 1881<dl> 1882<dt><a name="index-getDefaultFormat-on-Config"></a>Method on Config: <em>Setting::Format</em> <strong>getDefaultFormat</strong> <em>() const</em></dt> 1883<dt><a name="index-setDefaultFormat-on-Config"></a>Method on Config: <em>void</em> <strong>setDefaultFormat</strong> <em>(Setting::Format <var>format</var><!-- /@w -->)</em></dt> 1884<dd> 1885<p>These methods get and set the default external format for settings in 1886the configuration. If a non-default format has not been set for a 1887setting with <code>Setting::setFormat()</code>, this configuration-wide 1888default format will be used instead when that setting is written to a 1889file or stream. 1890</p> 1891</dd></dl> 1892 1893<dl> 1894<dt><a name="index-getTabWidth-on-Config"></a>Method on Config: <em>unsigned short</em> <strong>getTabWidth</strong> <em>() const</em></dt> 1895<dt><a name="index-setTabWidth-on-Config"></a>Method on Config: <em>void</em> <strong>setTabWidth</strong> <em>(unsigned short <var>width</var><!-- /@w -->)</em></dt> 1896<dd> 1897<p>These methods get and set the tab width for the configuration. The tab 1898width affects the formatting of the configuration when it is written 1899to a file or stream: each level of nesting is indented by <var>width</var> 1900spaces, or by a single tab character if <var>width</var> is 0. The tab 1901width has no effect on parsing. 1902</p> 1903<p>Valid tab widths range from 0 to 15. The default tab width is 2. 1904</p> 1905</dd></dl> 1906 1907<dl> 1908<dt><a name="index-getFloatPrecision-on-Config"></a>Method on Config: <em>unsigned short</em> <strong>getFloatPrecision</strong> <em>() const</em></dt> 1909<dt><a name="index-setFloatPrecision-on-Config"></a>Method on Config: <em>void</em> <strong>setFloatPrecision</strong> <em>(unsigned short <var>width</var><!-- /@w -->)</em></dt> 1910<dd> 1911<p>These methods get and set the float precision for the configuration. 1912This parameter influences the formatting of floating point settings in 1913the configuration when it is written to a file or stream. 1914Float precision has no effect on parsing. 1915</p> 1916<p>Valid precisions range from 0 to about 15 (implementation dependent), 1917though the library will accept and store values up to 255. 1918</p> 1919</dd></dl> 1920 1921<dl> 1922<dt><a name="index-getRoot-on-Config"></a>Method on Config: <em>Setting &</em> <strong>getRoot</strong> <em>() const</em></dt> 1923<dd> 1924<p>This method returns the root setting for the configuration, which is a group. 1925</p> 1926</dd></dl> 1927 1928<dl> 1929<dt><a name="index-lookup-on-Config"></a>Method on Config: <em>Setting &</em> <strong>lookup</strong> <em>(const std::string &<var>path</var><!-- /@w -->) const</em></dt> 1930<dt><a name="index-lookup-on-Config-1"></a>Method on Config: <em>Setting &</em> <strong>lookup</strong> <em>(const char * <var>path</var><!-- /@w -->) const</em></dt> 1931<dd> 1932<p>These methods locate the setting specified by the path <var>path</var>. If 1933the requested setting is not found, a <code>SettingNotFoundException</code> is 1934thrown. 1935</p> 1936</dd></dl> 1937<dl> 1938<dt><a name="index-exists-on-Config"></a>Method on Config: <em>bool</em> <strong>exists</strong> <em>(const std::string &<var>path</var><!-- /@w -->) const</em></dt> 1939<dt><a name="index-exists-on-Config-1"></a>Method on Config: <em>bool</em> <strong>exists</strong> <em>(const char *<var>path</var><!-- /@w -->) const</em></dt> 1940<dd> 1941<p>These methods test if a setting with the given <var>path</var> exists in 1942the configuration. They return <code>true</code> if the setting exists, and 1943<code>false</code> otherwise. These methods do not throw exceptions. 1944</p> 1945</dd></dl> 1946 1947<dl> 1948<dt><a name="index-lookupValue-on-Config"></a>Method on Config: <em>bool</em> <strong>lookupValue</strong> <em>(const char *<var>path</var><!-- /@w -->, bool &<var>value</var><!-- /@w -->) const</em></dt> 1949<dt><a name="index-lookupValue-on-Config-1"></a>Method on Config: <em>bool</em> <strong>lookupValue</strong> <em>(const std::string &<var>path</var><!-- /@w -->, bool &<var>value</var><!-- /@w -->) const</em></dt> 1950<dt><a name="index-lookupValue-on-Config-2"></a>Method on Config: <em>bool</em> <strong>lookupValue</strong> <em>(const char *<var>path</var><!-- /@w -->, int &<var>value</var><!-- /@w -->) const</em></dt> 1951<dt><a name="index-lookupValue-on-Config-3"></a>Method on Config: <em>bool</em> <strong>lookupValue</strong> <em>(const std::string &<var>path</var><!-- /@w -->, int &<var>value</var><!-- /@w -->) const</em></dt> 1952<dt><a name="index-lookupValue-on-Config-4"></a>Method on Config: <em>bool</em> <strong>lookupValue</strong> <em>(const char *<var>path</var><!-- /@w -->, unsigned int &<var>value</var><!-- /@w -->) const</em></dt> 1953<dt><a name="index-lookupValue-on-Config-5"></a>Method on Config: <em>bool</em> <strong>lookupValue</strong> <em>(const std::string &<var>path</var><!-- /@w -->, unsigned int &<var>value</var><!-- /@w -->) const</em></dt> 1954<dt><a name="index-lookupValue-on-Config-6"></a>Method on Config: <em>bool</em> <strong>lookupValue</strong> <em>(const char *<var>path</var><!-- /@w -->, long long &<var>value</var><!-- /@w -->) const</em></dt> 1955<dt><a name="index-lookupValue-on-Config-7"></a>Method on Config: <em>bool</em> <strong>lookupValue</strong> <em>(const std::string &<var>path</var><!-- /@w -->, long long &<var>value</var><!-- /@w -->) const</em></dt> 1956<dt><a name="index-lookupValue-on-Config-8"></a>Method on Config: <em>bool</em> <strong>lookupValue</strong> <em>(const char *<var>path</var><!-- /@w -->, float &<var>value</var><!-- /@w -->) const</em></dt> 1957<dt><a name="index-lookupValue-on-Config-9"></a>Method on Config: <em>bool</em> <strong>lookupValue</strong> <em>(const std::string &<var>path</var><!-- /@w -->, float &<var>value</var><!-- /@w -->) const</em></dt> 1958<dt><a name="index-lookupValue-on-Config-10"></a>Method on Config: <em>bool</em> <strong>lookupValue</strong> <em>(const char *<var>path</var><!-- /@w -->, double &<var>value</var><!-- /@w -->) const</em></dt> 1959<dt><a name="index-lookupValue-on-Config-11"></a>Method on Config: <em>bool</em> <strong>lookupValue</strong> <em>(const std::string &<var>path</var><!-- /@w -->, double &<var>value</var><!-- /@w -->) const</em></dt> 1960<dt><a name="index-lookupValue-on-Config-12"></a>Method on Config: <em>bool</em> <strong>lookupValue</strong> <em>(const char *<var>path</var><!-- /@w -->, const char *&<var>value</var><!-- /@w -->) const</em></dt> 1961<dt><a name="index-lookupValue-on-Config-13"></a>Method on Config: <em>bool</em> <strong>lookupValue</strong> <em>(const std::string &<var>path</var><!-- /@w -->, const char *&<var>value</var><!-- /@w -->) const</em></dt> 1962<dt><a name="index-lookupValue-on-Config-14"></a>Method on Config: <em>bool</em> <strong>lookupValue</strong> <em>(const char *<var>path</var><!-- /@w -->, std::string &<var>value</var><!-- /@w -->) const</em></dt> 1963<dt><a name="index-lookupValue-on-Config-15"></a>Method on Config: <em>bool</em> <strong>lookupValue</strong> <em>(const std::string &<var>path</var><!-- /@w -->, std::string &<var>value</var><!-- /@w -->) const</em></dt> 1964<dd> 1965<p>These are convenience methods for looking up the value of a setting 1966with the given <var>path</var>. If the setting is found and is of an 1967appropriate type, the value is stored in <var>value</var> and the method 1968returns <code>true</code>. Otherwise, <var>value</var> is left unmodified and the 1969method returns <code>false</code>. These methods do not throw exceptions. 1970</p> 1971<p>Storage for <i>const char *</i><!-- /@w --> values is managed by the library and 1972released automatically when the setting is destroyed or when its value 1973is changed; the string must not be freed by the caller. For safety and 1974convenience, always assigning string values to a <code>std::string</code> is 1975suggested. 1976</p> 1977<p>Since these methods have boolean return values and do not throw 1978exceptions, they can be used within boolean logic expressions. The following 1979example presents a concise way to look up three values at once and 1980perform error handling if any of them are not found or are of the 1981wrong type: 1982</p> 1983<br> 1984<table class="cartouche" border="1"><tr><td> 1985<div class="smallexample"> 1986<pre class="smallexample">int var1; 1987double var2; 1988const char *var3; 1989 1990if(config.lookupValue("values.var1", var1) 1991 && config.lookupValue("values.var2", var2) 1992 && config.lookupValue("values.var3", var3)) 1993{ 1994 // use var1, var2, var3 1995} 1996else 1997{ 1998 // error handling here 1999} 2000</pre></div> 2001</td></tr></table> 2002 2003<p>This approach also takes advantage of the short-circuit evaluation rules 2004of C++, e.g., if the first lookup fails (returning <code>false</code>), the 2005remaining lookups are skipped entirely. 2006</p> 2007</dd></dl> 2008 2009<dl> 2010<dt><a name="index-operator-bool-_0028_0029-on-Setting"></a>Method on Setting: <em></em> <strong>operator bool ()</strong> <em>const</em></dt> 2011<dt><a name="index-operator-int-_0028_0029-on-Setting"></a>Method on Setting: <em></em> <strong>operator int ()</strong> <em>const</em></dt> 2012<dt><a name="index-operator-unsigned-int-_0028_0029-on-Setting"></a>Method on Setting: <em></em> <strong>operator unsigned int ()</strong> <em>const</em></dt> 2013<dt><a name="index-operator-long-_0028_0029-on-Setting"></a>Method on Setting: <em></em> <strong>operator long ()</strong> <em>const</em></dt> 2014<dt><a name="index-operator-unsigned-long-_0028_0029-on-Setting"></a>Method on Setting: <em></em> <strong>operator unsigned long ()</strong> <em>const</em></dt> 2015<dt><a name="index-operator-long-long-_0028_0029-on-Setting"></a>Method on Setting: <em></em> <strong>operator long long ()</strong> <em>const</em></dt> 2016<dt><a name="index-operator-unsigned-long-long-_0028_0029-on-Setting"></a>Method on Setting: <em></em> <strong>operator unsigned long long ()</strong> <em>const</em></dt> 2017<dt><a name="index-operator-float-_0028_0029-on-Setting"></a>Method on Setting: <em></em> <strong>operator float ()</strong> <em>const</em></dt> 2018<dt><a name="index-operator-double-_0028_0029-on-Setting"></a>Method on Setting: <em></em> <strong>operator double ()</strong> <em>const</em></dt> 2019<dt><a name="index-operator-const-char-_002a-_0028_0029-on-Setting"></a>Method on Setting: <em></em> <strong>operator const char * ()</strong> <em>const</em></dt> 2020<dt><a name="index-operator-std_003a_003astring-_0028_0029-on-Setting"></a>Method on Setting: <em></em> <strong>operator std::string ()</strong> <em>const</em></dt> 2021<dt><a name="index-c_005fstr-on-Setting"></a>Method on Setting: <em>const char *</em> <strong>c_str</strong> <em>() const</em></dt> 2022<dd> 2023<p>These cast operators allow a <code>Setting</code> object to be assigned to a 2024variable of type <i>bool</i> if it is of type <code>TypeBoolean</code>; 2025<i>int</i>, <i>unsigned int</i>; <code>long long</code> or <code>unsigned long long</code> if 2026it is of type <code>TypeInt64</code>, <i>float</i> or <i>double</i> if it is of type 2027<code>TypeFloat</code>; or <i>const char *</i><!-- /@w --> or <i>std::string</i> if it is 2028of type <code>TypeString</code>. 2029</p> 2030<p>Values of type <code>TypeInt</code> or <code>TypeInt64</code> may be assigned to 2031variables of type <i>long</i>, or <i>unsigned long</i>, depending on the 2032sizes of those types on the host system. 2033</p> 2034<p>Storage for <i>const char *</i><!-- /@w --> return values is managed by the 2035library and released automatically when the setting is destroyed or 2036when its value is changed; the string must not be freed by the 2037caller. For safety and convenience, always assigning string return 2038values to a <code>std::string</code> is suggested. 2039</p> 2040<p>The following examples demonstrate this usage: 2041</p> 2042<table class="cartouche" border="1"><tr><td> 2043<div class="smallexample"> 2044<pre class="smallexample">long width = config.lookup("application.window.size.w"); 2045 2046bool splashScreen = config.lookup("application.splash_screen"); 2047 2048std::string title = config.lookup("application.window.title"); 2049</pre></div> 2050</td></tr></table> 2051 2052<p>Note that certain conversions can lead to loss of precision or 2053clipping of values, e.g., assigning a negative value to an <i>unsigned 2054int</i> (in which case the value will be treated as 0), or a 2055double-precision value to a <i>float</i>. The library does not treat 2056these lossy conversions as errors. 2057</p> 2058<p>Perhaps surprisingly, the following code in particular will cause a 2059compiler error: 2060</p> 2061<table class="cartouche" border="1"><tr><td> 2062<div class="smallexample"> 2063<pre class="smallexample">std::string title; 2064. 2065. 2066. 2067title = config.lookup("application.window.title"); 2068</pre></div> 2069</td></tr></table> 2070 2071<p>This is because the assignment operator of <code>std::string</code> is being 2072invoked with a <code>Setting &</code> as an argument. The compiler is unable 2073to make an implicit conversion because both the <code>const char *</code> 2074and the <code>std::string</code> cast operators of <code>Setting</code> are 2075equally appropriate. This is not a bug in <i>libconfig</i>; providing 2076only the <code>const char *</code> cast operator would resolve this 2077particular ambiguity, but would cause assignments to 2078<code>std::string</code> like the one in the previous example to produce a 2079compiler error. (To understand why, see section 11.4.1 of <i>The C++ 2080Programming Language</i>.) 2081</p> 2082<p>The solution to this problem is to use an explicit conversion that 2083avoids the construction of an intermediate <code>std::string</code> object, 2084as follows: 2085</p> 2086<table class="cartouche" border="1"><tr><td> 2087<div class="smallexample"> 2088<pre class="smallexample">std::string title; 2089. 2090. 2091. 2092title = (const char *)config.lookup("application.window.title"); 2093</pre></div> 2094</td></tr></table> 2095 2096<p>Or, alternatively, use the <code>c_str()</code> method, which has the same effect: 2097</p> 2098<table class="cartouche" border="1"><tr><td> 2099<div class="smallexample"> 2100<pre class="smallexample">std::string title; 2101. 2102. 2103. 2104title = config.lookup("application.window.title").c_str(); 2105</pre></div> 2106</td></tr></table> 2107 2108<p>If the assignment is invalid due to a type mismatch, a 2109<code>SettingTypeException</code> is thrown. 2110</p> 2111</dd></dl> 2112 2113<dl> 2114<dt><a name="index-operator_003d-on-Setting"></a>Method on Setting: <em>Setting &</em> <strong>operator=</strong> <em>(bool <var>value</var><!-- /@w -->)</em></dt> 2115<dt><a name="index-operator_003d-on-Setting-1"></a>Method on Setting: <em>Setting &</em> <strong>operator=</strong> <em>(int <var>value</var><!-- /@w -->)</em></dt> 2116<dt><a name="index-operator_003d-on-Setting-2"></a>Method on Setting: <em>Setting &</em> <strong>operator=</strong> <em>(long <var>value</var><!-- /@w -->)</em></dt> 2117<dt><a name="index-operator_003d-on-Setting-3"></a>Method on Setting: <em>Setting &</em> <strong>operator=</strong> <em>(const long long &<var>value</var><!-- /@w -->)</em></dt> 2118<dt><a name="index-operator_003d-on-Setting-4"></a>Method on Setting: <em>Setting &</em> <strong>operator=</strong> <em>(float <var>value</var><!-- /@w -->)</em></dt> 2119<dt><a name="index-operator_003d-on-Setting-5"></a>Method on Setting: <em>Setting &</em> <strong>operator=</strong> <em>(const double &<var>value</var><!-- /@w -->)</em></dt> 2120<dt><a name="index-operator_003d-on-Setting-6"></a>Method on Setting: <em>Setting &</em> <strong>operator=</strong> <em>(const char *<var>value</var><!-- /@w -->)</em></dt> 2121<dt><a name="index-operator_003d-on-Setting-7"></a>Method on Setting: <em>Setting &</em> <strong>operator=</strong> <em>(const std::string &<var>value</var><!-- /@w -->)</em></dt> 2122<dd> 2123<p>These assignment operators allow values of type <i>bool</i>, <i>int</i>, 2124<i>long</i>, <i>long long</i>, <i>float</i>, <i>double</i>, <i>const char *</i>, and 2125<i>std::string</i> to be assigned to a setting. In the case of strings, 2126the library makes a copy of the passed string <var>value</var>, so it may 2127be subsequently freed or modified by the caller without affecting the 2128value of the setting. 2129</p> 2130<p>The following example code looks up a (presumably) integer setting 2131and changes its value: 2132</p> 2133<table class="cartouche" border="1"><tr><td> 2134<div class="smallexample"> 2135<pre class="smallexample">Setting &setting = config.lookup("application.window.size.w"); 2136setting = 1024; 2137</pre></div> 2138</td></tr></table> 2139 2140<p>If the assignment is invalid due to a type mismatch, a 2141<code>SettingTypeException</code> is thrown. 2142</p> 2143</dd></dl> 2144 2145<dl> 2146<dt><a name="index-operator_005b_005d-on-Setting"></a>Method on Setting: <em>Setting &</em> <strong>operator[]</strong> <em>(int <var>index</var><!-- /@w -->) const</em></dt> 2147<dt><a name="index-operator_005b_005d-on-Setting-1"></a>Method on Setting: <em>Setting &</em> <strong>operator[]</strong> <em>(const std::string &<var>name</var><!-- /@w -->) const</em></dt> 2148<dt><a name="index-operator_005b_005d-on-Setting-2"></a>Method on Setting: <em>Setting &</em> <strong>operator[]</strong> <em>(const char *<var>name</var><!-- /@w -->) const</em></dt> 2149<dd> 2150<p>A <code>Setting</code> object may be subscripted with an integer index 2151<var>index</var> if it is an array or list, or with either a string 2152<var>name</var> or an integer index <var>index</var> if it is a group. For example, 2153the following code would produce the string ‘<samp>Last Name</samp>’ when 2154applied to the example configuration in <a href="#Configuration-Files">Configuration Files</a>. 2155</p> 2156<table class="cartouche" border="1"><tr><td> 2157<div class="smallexample"> 2158<pre class="smallexample">Setting& setting = config.lookup("application.misc"); 2159const char *s = setting["columns"][0]; 2160</pre></div> 2161</td></tr></table> 2162 2163<p>If the setting is not an array, list, or group, a 2164<code>SettingTypeException</code> is thrown. If the subscript (<var>index</var> 2165or <var>name</var>) does not refer to a valid element, a 2166<code>SettingNotFoundException</code> is thrown. 2167</p> 2168<p>Iterating over a group’s child settings with an integer index will 2169return the settings in the same order that they appear in the 2170configuration. 2171</p> 2172</dd></dl> 2173 2174<dl> 2175<dt><a name="index-lookup-on-Setting"></a>Method on Setting: <em>Setting &</em> <strong>lookup</strong> <em>(const char * <var>path</var><!-- /@w -->) const</em></dt> 2176<dt><a name="index-lookup-on-Setting-1"></a>Method on Setting: <em>Setting &</em> <strong>lookup</strong> <em>(const std::string &<var>path</var><!-- /@w -->) const</em></dt> 2177<dd> 2178<p>These methods locate a setting by a path <var>path</var> relative to 2179this setting. If requested setting is not found, a 2180<code>SettingNotFoundException</code> is thrown. 2181</p> 2182</dd></dl> 2183 2184<dl> 2185<dt><a name="index-lookupValue-on-Setting"></a>Method on Setting: <em>bool</em> <strong>lookupValue</strong> <em>(const char *<var>name</var><!-- /@w -->, bool &<var>value</var><!-- /@w -->) const</em></dt> 2186<dt><a name="index-lookupValue-on-Setting-1"></a>Method on Setting: <em>bool</em> <strong>lookupValue</strong> <em>(const std::string &<var>name</var><!-- /@w -->, bool &<var>value</var><!-- /@w -->) const</em></dt> 2187<dt><a name="index-lookupValue-on-Setting-2"></a>Method on Setting: <em>bool</em> <strong>lookupValue</strong> <em>(const char *<var>name</var><!-- /@w -->, int &<var>value</var><!-- /@w -->) const</em></dt> 2188<dt><a name="index-lookupValue-on-Setting-3"></a>Method on Setting: <em>bool</em> <strong>lookupValue</strong> <em>(const std::string &<var>name</var><!-- /@w -->, int &<var>value</var><!-- /@w -->) const</em></dt> 2189<dt><a name="index-lookupValue-on-Setting-4"></a>Method on Setting: <em>bool</em> <strong>lookupValue</strong> <em>(const char *<var>name</var><!-- /@w -->, unsigned int &<var>value</var><!-- /@w -->) const</em></dt> 2190<dt><a name="index-lookupValue-on-Setting-5"></a>Method on Setting: <em>bool</em> <strong>lookupValue</strong> <em>(const std::string &<var>name</var><!-- /@w -->, unsigned int &<var>value</var><!-- /@w -->) const</em></dt> 2191<dt><a name="index-lookupValue-on-Setting-6"></a>Method on Setting: <em>bool</em> <strong>lookupValue</strong> <em>(const char *<var>name</var><!-- /@w -->, long long &<var>value</var><!-- /@w -->) const</em></dt> 2192<dt><a name="index-lookupValue-on-Setting-7"></a>Method on Setting: <em>bool</em> <strong>lookupValue</strong> <em>(const std::string &<var>name</var><!-- /@w -->, long long &<var>value</var><!-- /@w -->) const</em></dt> 2193<dt><a name="index-lookupValue-on-Setting-8"></a>Method on Setting: <em>bool</em> <strong>lookupValue</strong> <em>(const char *<var>name</var><!-- /@w -->, unsigned long long &<var>value</var><!-- /@w -->) const</em></dt> 2194<dt><a name="index-lookupValue-on-Setting-9"></a>Method on Setting: <em>bool</em> <strong>lookupValue</strong> <em>(const std::string &<var>name</var><!-- /@w -->, unsigned long long &<var>value</var><!-- /@w -->) const</em></dt> 2195<dt><a name="index-lookupValue-on-Setting-10"></a>Method on Setting: <em>bool</em> <strong>lookupValue</strong> <em>(const char *<var>name</var><!-- /@w -->, float &<var>value</var><!-- /@w -->) const</em></dt> 2196<dt><a name="index-lookupValue-on-Setting-11"></a>Method on Setting: <em>bool</em> <strong>lookupValue</strong> <em>(const std::string &<var>name</var><!-- /@w -->, float &<var>value</var><!-- /@w -->) const</em></dt> 2197<dt><a name="index-lookupValue-on-Setting-12"></a>Method on Setting: <em>bool</em> <strong>lookupValue</strong> <em>(const char *<var>name</var><!-- /@w -->, double &<var>value</var><!-- /@w -->) const</em></dt> 2198<dt><a name="index-lookupValue-on-Setting-13"></a>Method on Setting: <em>bool</em> <strong>lookupValue</strong> <em>(const std::string &<var>name</var><!-- /@w -->, double &<var>value</var><!-- /@w -->) const</em></dt> 2199<dt><a name="index-lookupValue-on-Setting-14"></a>Method on Setting: <em>bool</em> <strong>lookupValue</strong> <em>(const char *<var>name</var><!-- /@w -->, const char *&<var>value</var><!-- /@w -->) const</em></dt> 2200<dt><a name="index-lookupValue-on-Setting-15"></a>Method on Setting: <em>bool</em> <strong>lookupValue</strong> <em>(const std::string &<var>name</var><!-- /@w -->, const char *&<var>value</var><!-- /@w -->) const</em></dt> 2201<dt><a name="index-lookupValue-on-Setting-16"></a>Method on Setting: <em>bool</em> <strong>lookupValue</strong> <em>(const char *<var>name</var><!-- /@w -->, std::string &<var>value</var><!-- /@w -->) const</em></dt> 2202<dt><a name="index-lookupValue-on-Setting-17"></a>Method on Setting: <em>bool</em> <strong>lookupValue</strong> <em>(const std::string &<var>name</var><!-- /@w -->, std::string &<var>value</var><!-- /@w -->) const</em></dt> 2203<dd> 2204<p>These are convenience methods for looking up the value of a child setting 2205with the given <var>name</var>. If the setting is found and is of an 2206appropriate type, the value is stored in <var>value</var> and the method 2207returns <code>true</code>. Otherwise, <var>value</var> is left unmodified and the 2208method returns <code>false</code>. These methods do not throw exceptions. 2209</p> 2210<p>Storage for <i>const char *</i><!-- /@w --> values is managed by the library and 2211released automatically when the setting is destroyed or when its value 2212is changed; the string must not be freed by the caller. For safety and 2213convenience, always assigning string values to a <code>std::string</code> is 2214suggested. 2215</p> 2216<p>Since these methods have boolean return values and do not throw 2217exceptions, they can be used within boolean logic expressions. The following 2218example presents a concise way to look up three values at once and 2219perform error handling if any of them are not found or are of the 2220wrong type: 2221</p> 2222<br> 2223<table class="cartouche" border="1"><tr><td> 2224<div class="smallexample"> 2225<pre class="smallexample">int var1; 2226double var2; 2227const char *var3; 2228 2229if(setting.lookupValue("var1", var1) 2230 && setting.lookupValue("var2", var2) 2231 && setting.lookupValue("var3", var3)) 2232{ 2233 // use var1, var2, var3 2234} 2235else 2236{ 2237 // error handling here 2238} 2239</pre></div> 2240</td></tr></table> 2241 2242<p>This approach also takes advantage of the short-circuit evaluation 2243rules of C++, e.g., if the first lookup fails (returning <code>false</code>), the 2244remaining lookups are skipped entirely. 2245</p> 2246</dd></dl> 2247 2248<dl> 2249<dt><a name="index-add-on-Setting"></a>Method on Setting: <em>Setting &</em> <strong>add</strong> <em>(const std::string &<var>name</var><!-- /@w -->, Setting::Type <var>type</var><!-- /@w -->)</em></dt> 2250<dt><a name="index-add-on-Setting-1"></a>Method on Setting: <em>Setting &</em> <strong>add</strong> <em>(const char *<var>name</var><!-- /@w -->, Setting::Type <var>type</var><!-- /@w -->)</em></dt> 2251<dd> 2252<p>These methods add a new child setting with the given <var>name</var> and 2253<var>type</var> to the setting, which must be a group. They return a 2254reference to the new setting. If the setting already has a child 2255setting with the given name, or if the name is invalid, a 2256<code>SettingNameException</code> is thrown. If the setting is not a group, 2257a <code>SettingTypeException</code> is thrown. 2258</p> 2259<p>Once a setting has been created, neither its name nor type can be 2260changed. 2261</p> 2262</dd></dl> 2263 2264<dl> 2265<dt><a name="index-add-on-Setting-2"></a>Method on Setting: <em>Setting &</em> <strong>add</strong> <em>(Setting::Type <var>type</var><!-- /@w -->)</em></dt> 2266<dd> 2267<p>This method adds a new element to the setting, which must be of type 2268<code>TypeArray</code> or <code>TypeList</code>. If the setting is an array which 2269currently has zero elements, the <var>type</var> parameter (which must be 2270<code>TypeInt</code>, <code>TypeInt64</code>, <code>TypeFloat</code>, <code>TypeBool</code>, 2271or <code>TypeString</code>) determines the type for the array; otherwise it 2272must match the type of the existing elements in the array. 2273</p> 2274<p>The method returns the new setting on success. If <var>type</var> is a 2275scalar type, the new setting will have a default value of 0, 0.0, 2276<code>false</code>, or <code>NULL</code>, as appropriate. 2277</p> 2278<p>The method throws a <code>SettingTypeException</code> if the setting is not 2279an array or list, or if <var>type</var> is invalid. 2280</p> 2281</dd></dl> 2282 2283<dl> 2284<dt><a name="index-remove-on-Setting"></a>Method on Setting: <em>void</em> <strong>remove</strong> <em>(const std::string &<var>name</var><!-- /@w -->)</em></dt> 2285<dt><a name="index-remove-on-Setting-1"></a>Method on Setting: <em>void</em> <strong>remove</strong> <em>(const char *<var>name</var><!-- /@w -->)</em></dt> 2286<dd> 2287<p>These methods remove the child setting with the given <var>name</var> from 2288the setting, which must be a group. Any child settings of the removed 2289setting are recursively destroyed as well. 2290</p> 2291<p>If the setting is not a group, a <code>SettingTypeException</code> is 2292thrown. If the setting does not have a child setting with the given 2293name, a <code>SettingNotFoundException</code> is thrown. 2294</p> 2295</dd></dl> 2296 2297<dl> 2298<dt><a name="index-remove-on-Setting-2"></a>Method on Setting: <em>void</em> <strong>remove</strong> <em>(unsigned int <var>index</var><!-- /@w -->)</em></dt> 2299<dd> 2300<p>This method removes the child setting at the given index <var>index</var> from 2301the setting, which must be a group, list, or array. Any child settings 2302of the removed setting are recursively destroyed as well. 2303</p> 2304<p>If the setting is not a group, list, or array, a 2305<code>SettingTypeException</code> is thrown. If <var>index</var> is out of range, 2306a <code>SettingNotFoundException</code> is thrown. 2307</p> 2308</dd></dl> 2309 2310<dl> 2311<dt><a name="index-getName-on-Setting"></a>Method on Setting: <em>const char *</em> <strong>getName</strong> <em>() const</em></dt> 2312<dd> 2313<p>This method returns the name of the setting, or <code>NULL</code> if the 2314setting has no name. Storage for the returned string is managed by the 2315library and released automatically when the setting is destroyed; the 2316string must not be freed by the caller. For safety and convenience, 2317consider assigning the return value to a <code>std::string</code>. 2318</p> 2319</dd></dl> 2320 2321<dl> 2322<dt><a name="index-getPath-on-Setting"></a>Method on Setting: <em>std::string</em> <strong>getPath</strong> <em>() const</em></dt> 2323<dd> 2324<p>This method returns the complete dot-separated path to the 2325setting. Settings which do not have a name (list and array elements) 2326are represented by their index in square brackets. 2327</p> 2328</dd></dl> 2329 2330<dl> 2331<dt><a name="index-getParent-on-Setting"></a>Method on Setting: <em>Setting &</em> <strong>getParent</strong> <em>() const</em></dt> 2332<dd> 2333<p>This method returns the parent setting of the setting. If the setting 2334is the root setting, a <code>SettingNotFoundException</code> is thrown. 2335</p> 2336</dd></dl> 2337 2338<dl> 2339<dt><a name="index-isRoot-on-Setting"></a>Method on Setting: <em>bool</em> <strong>isRoot</strong> <em>() const</em></dt> 2340<dd> 2341<p>This method returns <code>true</code> if the setting is the root setting, and 2342<code>false</code> otherwise. 2343</p> 2344</dd></dl> 2345 2346<dl> 2347<dt><a name="index-getIndex-on-Setting"></a>Method on Setting: <em>int</em> <strong>getIndex</strong> <em>() const</em></dt> 2348<dd> 2349<p>This method returns the index of the setting within its parent 2350setting. When applied to the root setting, this method returns -1. 2351</p> 2352</dd></dl> 2353 2354<dl> 2355<dt><a name="index-getType-on-Setting"></a>Method on Setting: <em>Setting::Type</em> <strong>getType</strong> <em>() const</em></dt> 2356<dd> 2357<a name="index-Setting_003a_003aType"></a> 2358<p>This method returns the type of the setting. The 2359<code>Setting::Type</code> enumeration consists of the following constants: 2360<code>TypeInt</code>, <code>TypeInt64</code>, <code>TypeFloat</code>, <code>TypeString</code>, 2361<code>TypeBoolean</code>, <code>TypeArray</code>, <code>TypeList</code>, and 2362<code>TypeGroup</code>. 2363</p> 2364</dd></dl> 2365 2366<dl> 2367<dt><a name="index-getFormat-on-Setting"></a>Method on Setting: <em>Setting::Format</em> <strong>getFormat</strong> <em>() const</em></dt> 2368<dt><a name="index-setFormat-on-Setting"></a>Method on Setting: <em>void</em> <strong>setFormat</strong> <em>(Setting::Format <var>format</var><!-- /@w -->)</em></dt> 2369<dd> 2370<p>These methods get and set the external format for the setting. 2371</p> 2372<a name="index-Setting_003a_003aFormat"></a> 2373<p>The <var>Setting::Format</var> enumeration consists of the following 2374constants: <code>FormatDefault</code> and <code>FormatHex</code>. All settings 2375support the <code>FormatDefault</code> format. The <code>FormatHex</code> format 2376specifies hexadecimal formatting for integer values, and hence only 2377applies to settings of type <code>TypeInt</code> and <code>TypeInt64</code>. If 2378<var>format</var> is invalid for the given setting, it is ignored. 2379</p> 2380</dd></dl> 2381 2382<dl> 2383<dt><a name="index-exists-on-Setting"></a>Method on Setting: <em>bool</em> <strong>exists</strong> <em>(const std::string &<var>name</var><!-- /@w -->) const</em></dt> 2384<dt><a name="index-exists-on-Setting-1"></a>Method on Setting: <em>bool</em> <strong>exists</strong> <em>(const char *<var>name</var><!-- /@w -->) const</em></dt> 2385<dd> 2386<p>These methods test if the setting has a child setting with the given 2387<var>name</var>. They return <code>true</code> if the setting exists, and 2388<code>false</code> otherwise. These methods do not throw exceptions. 2389</p> 2390</dd></dl> 2391<dl> 2392<dt><a name="index-begin-on-Setting"></a>Method on Setting: <em>iterator</em> <strong>begin</strong> <em>()</em></dt> 2393<dt><a name="index-end-on-Setting"></a>Method on Setting: <em>iterator</em> <strong>end</strong> <em>()</em></dt> 2394<dt><a name="index-begin-on-Setting-1"></a>Method on Setting: <em>const_iterator</em> <strong>begin</strong> <em>()</em></dt> 2395<dt><a name="index-end-on-Setting-1"></a>Method on Setting: <em>const_iterator</em> <strong>end</strong> <em>()</em></dt> 2396<dd> 2397<p>These methods return STL-style iterators that can be used to enumerate 2398the child settings of a given setting. If the setting is not an array, list, 2399or group, they throw a <code>SettingTypeException</code>. 2400</p> 2401</dd></dl> 2402 2403<dl> 2404<dt><a name="index-getLength-on-Setting"></a>Method on Setting: <em>int</em> <strong>getLength</strong> <em>() const</em></dt> 2405<dd> 2406<p>This method returns the number of settings in a group, or the number of 2407elements in a list or array. For other types of settings, it returns 24080. 2409</p> 2410</dd></dl> 2411 2412<dl> 2413<dt><a name="index-isGroup-on-Setting"></a>Method on Setting: <em>bool</em> <strong>isGroup</strong> <em>() const</em></dt> 2414<dt><a name="index-isArray-on-Setting"></a>Method on Setting: <em>bool</em> <strong>isArray</strong> <em>() const</em></dt> 2415<dt><a name="index-isList-on-Setting"></a>Method on Setting: <em>bool</em> <strong>isList</strong> <em>() const</em></dt> 2416<dd> 2417<p>These convenience methods test if a setting is of a given type. 2418</p> 2419</dd></dl> 2420 2421<dl> 2422<dt><a name="index-isAggregate-on-Setting"></a>Method on Setting: <em>bool</em> <strong>isAggregate</strong> <em>() const</em></dt> 2423<dt><a name="index-isScalar-on-Setting"></a>Method on Setting: <em>bool</em> <strong>isScalar</strong> <em>() const</em></dt> 2424<dt><a name="index-isNumber-on-Setting"></a>Method on Setting: <em>bool</em> <strong>isNumber</strong> <em>() const</em></dt> 2425<dd> 2426<p>These convenience methods test if a setting is of an aggregate type (a 2427group, array, or list), of a scalar type (integer, 64-bit integer, 2428floating point, boolean, or string), and of a number (integer, 64-bit 2429integer, or floating point), respectively. 2430</p> 2431</dd></dl> 2432 2433<dl> 2434<dt><a name="index-getSourceFile-on-Setting"></a>Method on Setting: <em>const char *</em> <strong>getSourceFile</strong> <em>() const</em></dt> 2435<dd> 2436<p>This method returns the name of the file from which the setting was 2437read, or NULL if the setting was not read from a file. This 2438information is useful for reporting application-level errors. Storage 2439for the returned string is managed by the library and released 2440automatically when the configuration is destroyed; the string must 2441not be freed by the caller. 2442</p> 2443</dd></dl> 2444 2445<dl> 2446<dt><a name="index-getSourceLine-on-Setting"></a>Method on Setting: <em>unsigned int</em> <strong>getSourceLine</strong> <em>() const</em></dt> 2447<dd> 2448<p>This method returns the line number of the configuration file or 2449stream at which the setting <var>setting</var> was read, or 0 if no line 2450number is available. This information is useful for reporting 2451application-level errors. 2452</p> 2453</dd></dl> 2454 2455<hr> 2456<a name="Example-Programs"></a> 2457<div class="header"> 2458<p> 2459Next: <a href="#Other-Bindings-and-Implementations" accesskey="n" rel="next">Other Bindings and Implementations</a>, Previous: <a href="#The-C_002b_002b-API" accesskey="p" rel="prev">The C++ API</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 2460</div> 2461<a name="Example-Programs-1"></a> 2462<h2 class="chapter">5 Example Programs</h2> 2463 2464<p>Practical example programs that illustrate how to use <i>libconfig</i> 2465from both C and C++ are included in the <samp>examples</samp> subdirectory 2466of the distribution. These examples include: 2467</p> 2468<dl compact="compact"> 2469<dt><samp>examples/c/example1.c</samp></dt> 2470<dd><p>An example C program that reads a configuration from an existing file 2471<samp>example.cfg</samp> (also located in <samp>examples/c</samp>) and displays 2472some of its contents. 2473</p> 2474</dd> 2475<dt><samp>examples/c++/example1.cpp</samp></dt> 2476<dd><p>The C++ equivalent of <samp>example1.c</samp>. 2477</p> 2478</dd> 2479<dt><samp>examples/c/example2.c</samp></dt> 2480<dd><p>An example C program that reads a configuration from an existing file 2481<samp>example.cfg</samp> (also located in <samp>examples/c</samp>), adds new 2482settings to the configuration, and writes the updated configuration to 2483another file. 2484</p> 2485</dd> 2486<dt><samp>examples/c++/example2.cpp</samp></dt> 2487<dd><p>The C++ equivalent of <samp>example2.c</samp> 2488</p> 2489</dd> 2490<dt><samp>examples/c/example3.c</samp></dt> 2491<dd><p>An example C program that constructs a new configuration in memory and writes it to a file. 2492</p> 2493</dd> 2494<dt><samp>examples/c++/example3.cpp</samp></dt> 2495<dd><p>The C++ equivalent of <samp>example3.c</samp> 2496</p> 2497</dd> 2498<dt><samp>examples/c/example4.c</samp></dt> 2499<dd><p>An example C program that uses a custom include function for processing 2500wildcard includes. Note that this code will not compile on Windows. 2501</p> 2502</dd> 2503</dl> 2504 2505<hr> 2506<a name="Other-Bindings-and-Implementations"></a> 2507<div class="header"> 2508<p> 2509Next: <a href="#License" accesskey="n" rel="next">License</a>, Previous: <a href="#Example-Programs" accesskey="p" rel="prev">Example Programs</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 2510</div> 2511<a name="Other-Bindings-and-Implementations-1"></a> 2512<h2 class="chapter">6 Other Bindings and Implementations</h2> 2513<table class="menu" border="0" cellspacing="0"> 2514<tr><td align="left" valign="top">• <a href="#Bourne-Shell" accesskey="1">Bourne Shell</a>:</td><td> </td><td align="left" valign="top"> 2515</td></tr> 2516<tr><td align="left" valign="top">• <a href="#D" accesskey="2">D</a>:</td><td> </td><td align="left" valign="top"> 2517</td></tr> 2518<tr><td align="left" valign="top">• <a href="#Haskell" accesskey="3">Haskell</a>:</td><td> </td><td align="left" valign="top"> 2519</td></tr> 2520<tr><td align="left" valign="top">• <a href="#Java" accesskey="4">Java</a>:</td><td> </td><td align="left" valign="top"> 2521</td></tr> 2522<tr><td align="left" valign="top">• <a href="#Lisp" accesskey="5">Lisp</a>:</td><td> </td><td align="left" valign="top"> 2523</td></tr> 2524<tr><td align="left" valign="top">• <a href="#Perl" accesskey="6">Perl</a>:</td><td> </td><td align="left" valign="top"> 2525</td></tr> 2526<tr><td align="left" valign="top">• <a href="#Python" accesskey="7">Python</a>:</td><td> </td><td align="left" valign="top"> 2527</td></tr> 2528<tr><td align="left" valign="top">• <a href="#Ruby" accesskey="8">Ruby</a>:</td><td> </td><td align="left" valign="top"> 2529</td></tr> 2530</table> 2531 2532<p>Various open-source libraries have been written that provide access to 2533<i>libconfig</i>-style configuration files from other programming languages. Some 2534of these libraries are wrappers which add new language bindings for 2535<i>libconfig</i> while others are syntax-compatible reimplementations in other 2536languages. 2537</p> 2538<p>Here is a list of some of these implementations. 2539</p> 2540<hr> 2541<a name="Bourne-Shell"></a> 2542<div class="header"> 2543<p> 2544Next: <a href="#D" accesskey="n" rel="next">D</a>, Up: <a href="#Other-Bindings-and-Implementations" accesskey="u" rel="up">Other Bindings and Implementations</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 2545</div> 2546<a name="Bourne-Shell-1"></a> 2547<h3 class="section">6.1 Bourne Shell</h3> 2548 2549<p>Łukasz A. Grabowski’s <i>ls-config</i> provides a means to read and write 2550values in <i>libconfig</i> configuration files from Bourne shell scripts. The 2551implementation is included in the <i>libconfig</i> git repository at 2552<a href="https://github.com/hyperrealm/libconfig">https://github.com/hyperrealm/libconfig</a>, in the <samp>contrib/ls-config</samp> 2553subdirectory. 2554</p> 2555<hr> 2556<a name="D"></a> 2557<div class="header"> 2558<p> 2559Next: <a href="#Haskell" accesskey="n" rel="next">Haskell</a>, Previous: <a href="#Bourne-Shell" accesskey="p" rel="prev">Bourne Shell</a>, Up: <a href="#Other-Bindings-and-Implementations" accesskey="u" rel="up">Other Bindings and Implementations</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 2560</div> 2561<a name="D-1"></a> 2562<h3 class="section">6.2 D</h3> 2563 2564<p>Remi Thebault’s <i>libconfig-d</i> is a port of <i>libconfig</i> to the D programming 2565language. It may be found at <a href="https://code.dlang.org/packages/libconfig-d">https://code.dlang.org/packages/libconfig-d</a>. 2566</p> 2567<hr> 2568<a name="Haskell"></a> 2569<div class="header"> 2570<p> 2571Next: <a href="#Java" accesskey="n" rel="next">Java</a>, Previous: <a href="#D" accesskey="p" rel="prev">D</a>, Up: <a href="#Other-Bindings-and-Implementations" accesskey="u" rel="up">Other Bindings and Implementations</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 2572</div> 2573<a name="Haskell-1"></a> 2574<h3 class="section">6.3 Haskell</h3> 2575 2576<p>Matthew Peddie’s <i>libconfig</i> provides Haskell bindings to 2577<i>libconfig</i>. It may be found at 2578<a href="https://hackage.haskell.org/package/libconfig-0.3.0.0">https://hackage.haskell.org/package/libconfig-0.3.0.0</a>. 2579</p> 2580<hr> 2581<a name="Java"></a> 2582<div class="header"> 2583<p> 2584Next: <a href="#Lisp" accesskey="n" rel="next">Lisp</a>, Previous: <a href="#Haskell" accesskey="p" rel="prev">Haskell</a>, Up: <a href="#Other-Bindings-and-Implementations" accesskey="u" rel="up">Other Bindings and Implementations</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 2585</div> 2586<a name="Java-1"></a> 2587<h3 class="section">6.4 Java</h3> 2588 2589<p>Andrey V. Pleskach has a pure-Java implementation of <i>libconfig</i>. It may be 2590found on github at <a href="https://github.com/willyborankin/libconfig">https://github.com/willyborankin/libconfig</a>. 2591</p> 2592<hr> 2593<a name="Lisp"></a> 2594<div class="header"> 2595<p> 2596Next: <a href="#Perl" accesskey="n" rel="next">Perl</a>, Previous: <a href="#Java" accesskey="p" rel="prev">Java</a>, Up: <a href="#Other-Bindings-and-Implementations" accesskey="u" rel="up">Other Bindings and Implementations</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 2597</div> 2598<a name="Lisp-1"></a> 2599<h3 class="section">6.5 Lisp</h3> 2600 2601<p>Oleg Shalaev’s <i>cl-libconfig</i> provides Common Lisp bindings for <i>libconfig</i>. 2602It may be found on github at <a href="https://github.com/chalaev/cl-libconfig">https://github.com/chalaev/cl-libconfig</a>. 2603</p> 2604<hr> 2605<a name="Perl"></a> 2606<div class="header"> 2607<p> 2608Next: <a href="#Python" accesskey="n" rel="next">Python</a>, Previous: <a href="#Lisp" accesskey="p" rel="prev">Lisp</a>, Up: <a href="#Other-Bindings-and-Implementations" accesskey="u" rel="up">Other Bindings and Implementations</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 2609</div> 2610<a name="Perl-1"></a> 2611<h3 class="section">6.6 Perl</h3> 2612 2613<p>The <i>Conf::Libconfig</i> module provides Perl bindings for <i>libconfig</i>. It may 2614be found on CPAN at <a href="http://search.cpan.org/~cnangel/Conf-Libconfig-0.05/">http://search.cpan.org/~cnangel/Conf-Libconfig-0.05/</a> 2615or on github at <a href="https://github.com/cnangel/Conf-Libconfig">https://github.com/cnangel/Conf-Libconfig</a>. 2616</p> 2617<hr> 2618<a name="Python"></a> 2619<div class="header"> 2620<p> 2621Next: <a href="#Ruby" accesskey="n" rel="next">Ruby</a>, Previous: <a href="#Perl" accesskey="p" rel="prev">Perl</a>, Up: <a href="#Other-Bindings-and-Implementations" accesskey="u" rel="up">Other Bindings and Implementations</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 2622</div> 2623<a name="Python-1"></a> 2624<h3 class="section">6.7 Python</h3> 2625 2626<p>Heiner Tholen’s <i>pylibconfig2</i> is a Python library that is syntax-compatible 2627with <i>libconfig</i>. It may be found at 2628<a href="https://pypi.python.org/pypi/pylibconfig2/0.1.2">https://pypi.python.org/pypi/pylibconfig2/0.1.2</a>. 2629</p> 2630<br> 2631 2632<p>Christian Aichinger’s <i>libconf</i> is another pure-Python implementation with a 2633more permissive license. It may be found at 2634<a href="https://pypi.python.org/pypi/libconf">https://pypi.python.org/pypi/libconf</a> or on github at 2635<a href="https://github.com/Grk0/python-libconf">https://github.com/Grk0/python-libconf</a>. 2636</p> 2637<br> 2638 2639<p>The <i>python-libconfig</i> wrapper provides Python bindings to <i>libconfig</i>. It 2640may be found on github at <a href="https://github.com/cnangel/python-libconfig/">https://github.com/cnangel/python-libconfig/</a>. 2641</p> 2642<hr> 2643<a name="Ruby"></a> 2644<div class="header"> 2645<p> 2646Previous: <a href="#Python" accesskey="p" rel="prev">Python</a>, Up: <a href="#Other-Bindings-and-Implementations" accesskey="u" rel="up">Other Bindings and Implementations</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 2647</div> 2648<a name="Ruby-1"></a> 2649<h3 class="section">6.8 Ruby</h3> 2650 2651<p>Christopher Mark Gore’s <i>ruby-libconfig</i> is a Ruby library that provides Ruby 2652bindings for <i>libconfig</i>. It may be found at 2653<a href="https://rubygems.org/gems/libconfig">https://rubygems.org/gems/libconfig</a> or on github at 2654<a href="https://github.com/cgore/ruby-libconfig">https://github.com/cgore/ruby-libconfig</a>. 2655</p> 2656<br> 2657 2658<p>There is also another Ruby wrapper, <i>libconfig-ruby</i>, that is included in 2659the <i>libconfig</i> git repository at <a href="https://github.com/hyperrealm/libconfig">https://github.com/hyperrealm/libconfig</a>, 2660in the <samp>contrib/libconfig-ruby</samp> subdirectory. 2661</p> 2662<hr> 2663<a name="License"></a> 2664<div class="header"> 2665<p> 2666Next: <a href="#Configuration-File-Grammar" accesskey="n" rel="next">Configuration File Grammar</a>, Previous: <a href="#Other-Bindings-and-Implementations" accesskey="p" rel="prev">Other Bindings and Implementations</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 2667</div> 2668<a name="License-1"></a> 2669<h2 class="appendix">Appendix A License</h2> 2670 2671 2672 2673<div align="center">GNU LESSER GENERAL PUBLIC LICENSE 2674</div><div align="center">Version 2.1, February 1999 2675</div> 2676<br> 2677 2678<p>Copyright © 1991, 1999 Free Software Foundation, Inc., 267959 Temple Place, Suite 330, Boston, MA 02111-1307 USA 2680</p> 2681<p>Everyone is permitted to copy and distribute verbatim copies of this 2682license document, but changing it is not allowed. 2683</p> 2684<p>[This is the first released version of the Lesser GPL. It also counts 2685as the successor of the GNU Library Public License, version 2, hence the 2686version number 2.1.] 2687</p> 2688<br> 2689<div align="center">Preamble 2690</div><br> 2691 2692<p>The licenses for most software are designed to take away your freedom to 2693share and change it. By contrast, the GNU General Public Licenses are 2694intended to guarantee your freedom to share and change free software–to 2695make sure the software is free for all its users. 2696</p> 2697<p>This license, the Lesser General Public License, applies to some 2698specially designated software packages–typically libraries–of the Free 2699Software Foundation and other authors who decide to use it. You can use 2700it too, but we suggest you first think carefully about whether this 2701license or the ordinary General Public License is the better strategy to 2702use in any particular case, based on the explanations below. 2703</p> 2704<p>When we speak of free software, we are referring to freedom of use, not 2705price. Our General Public Licenses are designed to make sure that you 2706have the freedom to distribute copies of free software (and charge for 2707this service if you wish); that you receive source code or can get it if 2708you want it; that you can change the software and use pieces of it in 2709new free programs; and that you are informed that you can do these 2710things. 2711</p> 2712<p>To protect your rights, we need to make restrictions that forbid 2713distributors to deny you these rights or to ask you to surrender these 2714rights. These restrictions translate to certain responsibilities for 2715you if you distribute copies of the library or if you modify it. 2716</p> 2717<p>For example, if you distribute copies of the library, whether gratis or 2718for a fee, you must give the recipients all the rights that we gave you. 2719You must make sure that they, too, receive or can get the source code. 2720If you link other code with the library, you must provide complete 2721object files to the recipients, so that they can relink them with the 2722library after making changes to the library and recompiling it. And you 2723must show them these terms so they know their rights. 2724</p> 2725<p>We protect your rights with a two-step method: (1) we copyright the 2726library, and (2) we offer you this license, which gives you legal 2727permission to copy, distribute and/or modify the library. 2728</p> 2729<p>To protect each distributor, we want to make it very clear that there is 2730no warranty for the free library. Also, if the library is modified by 2731someone else and passed on, the recipients should know that what they 2732have is not the original version, so that the original author’s 2733reputation will not be affected by problems that might be introduced by 2734others. 2735</p> 2736<p>Finally, software patents pose a constant threat to the existence of any 2737free program. We wish to make sure that a company cannot effectively 2738restrict the users of a free program by obtaining a restrictive license 2739from a patent holder. Therefore, we insist that any patent license 2740obtained for a version of the library must be consistent with the full 2741freedom of use specified in this license. 2742</p> 2743<p>Most GNU software, including some libraries, is covered by the ordinary 2744GNU General Public License. This license, the GNU Lesser General Public 2745License, applies to certain designated libraries, and is quite different 2746from the ordinary General Public License. We use this license for 2747certain libraries in order to permit linking those libraries into 2748non-free programs. 2749</p> 2750<p>When a program is linked with a library, whether statically or using a 2751shared library, the combination of the two is legally speaking a 2752combined work, a derivative of the original library. The ordinary 2753General Public License therefore permits such linking only if the entire 2754combination fits its criteria of freedom. The Lesser General Public 2755License permits more lax criteria for linking other code with the 2756library. 2757</p> 2758<p>We call this license the “Lesser” General Public License because it does 2759Less to protect the user’s freedom than the ordinary General Public 2760License. It also provides other free software developers Less of an 2761advantage over competing non-free programs. These disadvantages are the 2762reason we use the ordinary General Public License for many libraries. 2763However, the Lesser license provides advantages in certain special 2764circumstances. 2765</p> 2766<p>For example, on rare occasions, there may be a special need to encourage 2767the widest possible use of a certain library, so that it becomes a 2768de-facto standard. To achieve this, non-free programs must be allowed 2769to use the library. A more frequent case is that a free library does 2770the same job as widely used non-free libraries. In this case, there is 2771little to gain by limiting the free library to free software only, so we 2772use the Lesser General Public License. 2773</p> 2774<p>In other cases, permission to use a particular library in non-free 2775programs enables a greater number of people to use a large body of free 2776software. For example, permission to use the GNU C Library in non-free 2777programs enables many more people to use the whole GNU operating system, 2778as well as its variant, the GNU/Linux operating system. 2779</p> 2780<p>Although the Lesser General Public License is Less protective of the 2781users’ freedom, it does ensure that the user of a program that is linked 2782with the Library has the freedom and the wherewithal to run that program 2783using a modified version of the Library. 2784</p> 2785<p>The precise terms and conditions for copying, distribution and 2786modification follow. Pay close attention to the difference between a 2787“work based on the library” and a “work that uses the library”. The 2788former contains code derived from the library, whereas the latter must 2789be combined with the library in order to run. 2790</p> 2791 2792<div align="center">GNU LESSER GENERAL PUBLIC LICENSE 2793</div><div align="center">TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 2794</div> 2795<ol> 2796<li> 2797<br> 2798</li><li> This License Agreement applies to any software library or other program 2799which contains a notice placed by the copyright holder or other 2800authorized party saying it may be distributed under the terms of this 2801Lesser General Public License (also called “this License”). Each 2802licensee is addressed as “you”. 2803 2804<p>A “library” means a collection of software functions and/or data 2805prepared so as to be conveniently linked with application programs 2806(which use some of those functions and data) to form executables. 2807</p> 2808<p>The “Library”, below, refers to any such software library or work which 2809has been distributed under these terms. A “work based on the Library” 2810means either the Library or any derivative work under copyright law: 2811that is to say, a work containing the Library or a portion of it, either 2812verbatim or with modifications and/or translated straightforwardly into 2813another language. (Hereinafter, translation is included without 2814limitation in the term “modification”.) 2815</p> 2816<p>“Source code” for a work means the preferred form of the work for making 2817modifications to it. For a library, complete source code means all the 2818source code for all modules it contains, plus any associated interface 2819definition files, plus the scripts used to control compilation and 2820installation of the library. 2821</p> 2822<p>Activities other than copying, distribution and modification are not 2823covered by this License; they are outside its scope. The act of running 2824a program using the Library is not restricted, and output from such a 2825program is covered only if its contents constitute a work based on the 2826Library (independent of the use of the Library in a tool for writing 2827it). Whether that is true depends on what the Library does and what the 2828program that uses the Library does. 2829</p> 2830<br> 2831</li><li> You may copy and distribute verbatim copies of the Library’s complete 2832source code as you receive it, in any medium, provided that you 2833conspicuously and appropriately publish on each copy an appropriate 2834copyright notice and disclaimer of warranty; keep intact all the notices 2835that refer to this License and to the absence of any warranty; and 2836distribute a copy of this License along with the Library. 2837 2838<p>You may charge a fee for the physical act of transferring a copy, and 2839you may at your option offer warranty protection in exchange for a fee. 2840</p> 2841<br> 2842</li><li> You may modify your copy or copies of the Library or any portion of it, 2843thus forming a work based on the Library, and copy and distribute such 2844modifications or work under the terms of Section 1 above, provided that 2845you also meet all of these conditions: 2846 2847<ol> 2848<li> The modified work must itself be a software library. 2849 2850<br> 2851</li><li> You must cause the files modified to carry prominent notices stating 2852that you changed the files and the date of any change. 2853 2854<br> 2855</li><li> You must cause the whole of the work to be licensed at no charge to all 2856third parties under the terms of this License. 2857 2858<br> 2859</li><li> If a facility in the modified Library refers to a function or a table of 2860data to be supplied by an application program that uses the facility, 2861other than as an argument passed when the facility is invoked, then you 2862must make a good faith effort to ensure that, in the event an 2863application does not supply such function or table, the facility still 2864operates, and performs whatever part of its purpose remains meaningful. 2865 2866<p>(For example, a function in a library to compute square roots has a 2867purpose that is entirely well-defined independent of the application. 2868Therefore, Subsection 2d requires that any application-supplied function 2869or table used by this function must be optional: if the application does 2870not supply it, the square root function must still compute square 2871roots.) 2872</p> 2873</li></ol> 2874 2875<p>These requirements apply to the modified work as a whole. If 2876identifiable sections of that work are not derived from the Library, and 2877can be reasonably considered independent and separate works in 2878themselves, then this License, and its terms, do not apply to those 2879sections when you distribute them as separate works. But when you 2880distribute the same sections as part of a whole which is a work based on 2881the Library, the distribution of the whole must be on the terms of this 2882License, whose permissions for other licensees extend to the entire 2883whole, and thus to each and every part regardless of who wrote it. 2884</p> 2885<p>Thus, it is not the intent of this section to claim rights or contest 2886your rights to work written entirely by you; rather, the intent is to 2887exercise the right to control the distribution of derivative or 2888collective works based on the Library. 2889</p> 2890<p>In addition, mere aggregation of another work not based on the Library 2891with the Library (or with a work based on the Library) on a volume of a 2892storage or distribution medium does not bring the other work under the 2893scope of this License. 2894</p> 2895<br> 2896</li><li> You may opt to apply the terms of the ordinary GNU General Public 2897License instead of this License to a given copy of the Library. To do 2898this, you must alter all the notices that refer to this License, so that 2899they refer to the ordinary GNU General Public License, version 2, 2900instead of to this License. (If a newer version than version 2 of the 2901ordinary GNU General Public License has appeared, then you can specify 2902that version instead if you wish.) Do not make any other change in 2903these notices. 2904 2905<p>Once this change is made in a given copy, it is irreversible for that 2906copy, so the ordinary GNU General Public License applies to all 2907subsequent copies and derivative works made from that copy. 2908</p> 2909<p>This option is useful when you wish to copy part of the code of the 2910Library into a program that is not a library. 2911</p> 2912<br> 2913</li><li> You may copy and distribute the Library (or a portion or derivative of 2914it, under Section 2) in object code or executable form under the terms 2915of Sections 1 and 2 above provided that you accompany it with the 2916complete corresponding machine-readable source code, which must be 2917distributed under the terms of Sections 1 and 2 above on a medium 2918customarily used for software interchange. 2919 2920<p>If distribution of object code is made by offering access to copy from a 2921designated place, then offering equivalent access to copy the source 2922code from the same place satisfies the requirement to distribute the 2923source code, even though third parties are not compelled to copy the 2924source along with the object code. 2925</p> 2926<br> 2927</li><li> A program that contains no derivative of any portion of the Library, but 2928is designed to work with the Library by being compiled or linked with 2929it, is called a “work that uses the Library”. Such a work, in 2930isolation, is not a derivative work of the Library, and therefore falls 2931outside the scope of this License. 2932 2933<p>However, linking a “work that uses the Library” with the Library creates 2934an executable that is a derivative of the Library (because it contains 2935portions of the Library), rather than a “work that uses the library”. 2936The executable is therefore covered by this License. Section 6 states 2937terms for distribution of such executables. 2938</p> 2939<p>When a “work that uses the Library” uses material from a header file 2940that is part of the Library, the object code for the work may be a 2941derivative work of the Library even though the source code is not. 2942Whether this is true is especially significant if the work can be linked 2943without the Library, or if the work is itself a library. The threshold 2944for this to be true is not precisely defined by law. 2945</p> 2946<p>If such an object file uses only numerical parameters, data structure 2947layouts and accessors, and small macros and small inline functions (ten 2948lines or less in length), then the use of the object file is 2949unrestricted, regardless of whether it is legally a derivative work. 2950(Executables containing this object code plus portions of the Library 2951will still fall under Section 6.) 2952</p> 2953<p>Otherwise, if the work is a derivative of the Library, you may 2954distribute the object code for the work under the terms of Section 6. 2955Any executables containing that work also fall under Section 6, whether 2956or not they are linked directly with the Library itself. 2957</p> 2958<br> 2959</li><li> As an exception to the Sections above, you may also combine or link a 2960“work that uses the Library” with the Library to produce a work 2961containing portions of the Library, and distribute that work under terms 2962of your choice, provided that the terms permit modification of the work 2963for the customer’s own use and reverse engineering for debugging such 2964modifications. 2965 2966<p>You must give prominent notice with each copy of the work that the 2967Library is used in it and that the Library and its use are covered by 2968this License. You must supply a copy of this License. If the work 2969during execution displays copyright notices, you must include the 2970copyright notice for the Library among them, as well as a reference 2971directing the user to the copy of this License. Also, you must do one 2972of these things: 2973</p> 2974<ol> 2975<li> 2976<br> 2977</li><li> Accompany the work with the complete corresponding machine-readable 2978source code for the Library including whatever changes were used in the 2979work (which must be distributed under Sections 1 and 2 above); and, if 2980the work is an executable linked with the Library, with the complete 2981machine-readable “work that uses the Library”, as object code and/or 2982source code, so that the user can modify the Library and then relink to 2983produce a modified executable containing the modified Library. (It is 2984understood that the user who changes the contents of definitions files 2985in the Library will not necessarily be able to recompile the application 2986to use the modified definitions.) 2987 2988<br> 2989</li><li> Use a suitable shared library mechanism for linking with the Library. A 2990suitable mechanism is one that (1) uses at run time a copy of the 2991library already present on the user’s computer system, rather than 2992copying library functions into the executable, and (2) will operate 2993properly with a modified version of the library, if the user installs 2994one, as long as the modified version is interface-compatible with the 2995version that the work was made with. 2996 2997<br> 2998</li><li> Accompany the work with a written offer, valid for at least three years, 2999to give the same user the materials specified in Subsection 6a, above, 3000for a charge no more than the cost of performing this distribution. 3001 3002<br> 3003</li><li> If distribution of the work is made by offering access to copy from a 3004designated place, offer equivalent access to copy the above specified 3005materials from the same place. 3006 3007<br> 3008</li><li> Verify that the user has already received a copy of these materials or 3009that you have already sent this user a copy. 3010 3011</li></ol> 3012 3013<p>For an executable, the required form of the “work that uses the Library” 3014must include any data and utility programs needed for reproducing the 3015executable from it. However, as a special exception, the materials to 3016be distributed need not include anything that is normally distributed 3017(in either source or binary form) with the major components (compiler, 3018kernel, and so on) of the operating system on which the executable runs, 3019unless that component itself accompanies the executable. 3020</p> 3021<p>It may happen that this requirement contradicts the license restrictions 3022of other proprietary libraries that do not normally accompany the 3023operating system. Such a contradiction means you cannot use both them 3024and the Library together in an executable that you distribute. 3025</p> 3026<br> 3027</li><li> You may place library facilities that are a work based on the Library 3028side-by-side in a single library together with other library facilities 3029not covered by this License, and distribute such a combined library, 3030provided that the separate distribution of the work based on the Library 3031and of the other library facilities is otherwise permitted, and provided 3032that you do these two things: 3033 3034<ol> 3035<li> 3036<br> 3037</li><li> Accompany the combined library with a copy of the same work based on the 3038Library, uncombined with any other library facilities. This must be 3039distributed under the terms of the Sections above. 3040 3041<br> 3042</li><li> Give prominent notice with the combined library of the fact that part of 3043it is a work based on the Library, and explaining where to find the 3044accompanying uncombined form of the same work. 3045 3046</li></ol> 3047 3048<br> 3049</li><li> You may not copy, modify, sublicense, link with, or distribute the 3050Library except as expressly provided under this License. Any attempt 3051otherwise to copy, modify, sublicense, link with, or distribute the 3052Library is void, and will automatically terminate your rights under this 3053License. However, parties who have received copies, or rights, from you 3054under this License will not have their licenses terminated so long as 3055such parties remain in full compliance. 3056 3057<br> 3058</li><li> You are not required to accept this License, since you have not signed 3059it. However, nothing else grants you permission to modify or distribute 3060the Library or its derivative works. These actions are prohibited by 3061law if you do not accept this License. Therefore, by modifying or 3062distributing the Library (or any work based on the Library), you 3063indicate your acceptance of this License to do so, and all its terms and 3064conditions for copying, distributing or modifying the Library or works 3065based on it. 3066 3067<br> 3068</li><li> Each time you redistribute the Library (or any work based on the 3069Library), the recipient automatically receives a license from the 3070original licensor to copy, distribute, link with or modify the Library 3071subject to these terms and conditions. You may not impose any further 3072restrictions on the recipients’ exercise of the rights granted herein. 3073You are not responsible for enforcing compliance by third parties with 3074this License. 3075 3076<br> 3077</li><li> If, as a consequence of a court judgment or allegation of patent 3078infringement or for any other reason (not limited to patent issues), 3079conditions are imposed on you (whether by court order, agreement or 3080otherwise) that contradict the conditions of this License, they do not 3081excuse you from the conditions of this License. If you cannot 3082distribute so as to satisfy simultaneously your obligations under this 3083License and any other pertinent obligations, then as a consequence you 3084may not distribute the Library at all. For example, if a patent license 3085would not permit royalty-free redistribution of the Library by all those 3086who receive copies directly or indirectly through you, then the only way 3087you could satisfy both it and this License would be to refrain entirely 3088from distribution of the Library. 3089 3090<p>If any portion of this section is held invalid or unenforceable under 3091any particular circumstance, the balance of the section is intended to 3092apply, and the section as a whole is intended to apply in other 3093circumstances. 3094</p> 3095<p>It is not the purpose of this section to induce you to infringe any 3096patents or other property right claims or to contest validity of any 3097such claims; this section has the sole purpose of protecting the 3098integrity of the free software distribution system which is implemented 3099by public license practices. Many people have made generous 3100contributions to the wide range of software distributed through that 3101system in reliance on consistent application of that system; it is up to 3102the author/donor to decide if he or she is willing to distribute 3103software through any other system and a licensee cannot impose that 3104choice. 3105</p> 3106<p>This section is intended to make thoroughly clear what is believed to be 3107a consequence of the rest of this License. 3108</p> 3109<br> 3110</li><li> If the distribution and/or use of the Library is restricted in certain 3111countries either by patents or by copyrighted interfaces, the original 3112copyright holder who places the Library under this License may add an 3113explicit geographical distribution limitation excluding those countries, 3114so that distribution is permitted only in or among countries not thus 3115excluded. In such case, this License incorporates the limitation as if 3116written in the body of this License. 3117 3118<br> 3119</li><li> The Free Software Foundation may publish revised and/or new versions of 3120the Lesser General Public License from time to time. Such new versions 3121will be similar in spirit to the present version, but may differ in 3122detail to address new problems or concerns. 3123 3124<p>Each version is given a distinguishing version number. If the Library 3125specifies a version number of this License which applies to it and “any 3126later version”, you have the option of following the terms and 3127conditions either of that version or of any later version published by 3128the Free Software Foundation. If the Library does not specify a license 3129version number, you may choose any version ever published by the Free 3130Software Foundation. 3131</p> 3132<br> 3133</li><li> If you wish to incorporate parts of the Library into other free programs 3134whose distribution conditions are incompatible with these, write to the 3135author to ask for permission. For software which is copyrighted by the 3136Free Software Foundation, write to the Free Software Foundation; we 3137sometimes make exceptions for this. Our decision will be guided by the 3138two goals of preserving the free status of all derivatives of our free 3139software and of promoting the sharing and reuse of software generally. 3140 3141<br> 3142<div align="center">NO WARRANTY 3143</div><br> 3144 3145</li><li> BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR 3146THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN 3147OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES 3148PROVIDE THE LIBRARY “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER 3149EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 3150WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE 3151ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH 3152YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL 3153NECESSARY SERVICING, REPAIR OR CORRECTION. 3154 3155<br> 3156</li><li> IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING 3157WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR 3158REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR 3159DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL 3160DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY 3161(INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED 3162INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF 3163THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR 3164OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 3165 3166</li></ol> 3167 3168<br> 3169<div align="center">END OF TERMS AND CONDITIONS 3170</div><br> 3171<div align="center">How to Apply These Terms to Your New Libraries 3172</div> 3173<p>If you develop a new library, and you want it to be of the greatest 3174possible use to the public, we recommend making it free software that 3175everyone can redistribute and change. You can do so by permitting 3176redistribution under these terms (or, alternatively, under the terms of 3177the ordinary General Public License). 3178</p> 3179<p>To apply these terms, attach the following notices to the library. It 3180is safest to attach them to the start of each source file to most 3181effectively convey the exclusion of warranty; and each file should have 3182at least the “copyright” line and a pointer to where the full notice is 3183found. 3184</p> 3185<div class="format"> 3186<pre class="format"><tt> 3187<one line to give the library's name and a brief idea of what it does.> 3188Copyright (C) <year> <name of author> 3189 3190This library is free software; you can redistribute it and/or 3191modify it under the terms of the GNU Lesser General Public 3192License as published by the Free Software Foundation; either 3193version 2 of the License, or (at your option) any later version. 3194 3195This library is distributed in the hope that it will be useful, 3196but WITHOUT ANY WARRANTY; without even the implied warranty of 3197MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 3198Lesser General Public License for more details. 3199 3200You should have received a copy of the GNU Lesser General Public 3201License along with this library; if not, write to the Free Software 3202Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 3203</tt> 3204</pre></div> 3205 3206<p>Also add information on how to contact you by electronic and paper mail. 3207</p> 3208<p>You should also get your employer (if you work as a programmer) or your 3209school, if any, to sign a “copyright disclaimer” for the library, if 3210necessary. Here is a sample; alter the names: 3211</p> 3212<div class="format"> 3213<pre class="format"><tt> 3214Yoyodyne, Inc., hereby disclaims all copyright interest in the 3215library `Frob' (a library for tweaking knobs) written by James Random Hacker. 3216 3217<signature of Ty Coon>, 1 April 1990 3218Ty Coon, President of Vice 3219</tt> 3220</pre></div> 3221 3222<p>That’s all there is to it! 3223</p> 3224 3225<hr> 3226<a name="Configuration-File-Grammar"></a> 3227<div class="header"> 3228<p> 3229Next: <a href="#Function-Index" accesskey="n" rel="next">Function Index</a>, Previous: <a href="#License" accesskey="p" rel="prev">License</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 3230</div> 3231<a name="Configuration-File-Grammar-1"></a> 3232<h2 class="appendix">Appendix B Configuration File Grammar</h2> 3233 3234<p>Below is the BNF grammar for configuration files. Comments and include 3235directives are not part of the grammar, so they are not included here. 3236</p> 3237<br> 3238<div class="example"> 3239<pre class="example"><configuration> ::= 3240 <setting-list> 3241 | <empty> 3242 3243<setting-list> ::= 3244 <setting> 3245 | <setting-list> <setting> 3246 3247<setting> ::= 3248 <name> ( ":" | "=" ) <value> ( ";" | "," | <empty> ) 3249 3250<value> ::= 3251 <scalar-value> 3252 | <array> 3253 | <list> 3254 | <group> 3255 3256<value-list> ::= 3257 <value> 3258 | <value-list> "," <value> 3259 | <value-list> "," 3260 3261<scalar-value> ::= 3262 <boolean> 3263 | <integer> 3264 | <integer64> 3265 | <hex> 3266 | <hex64> 3267 | <float> 3268 | <string> 3269 3270<scalar-value-list> ::= 3271 <scalar-value> 3272 | <scalar-value-list> "," <scalar-value> 3273 | <scalar-value-list> "," 3274 3275<array> ::= 3276 "[" ( <scalar-value-list> | <empty> ) "]" 3277 3278<list> ::= 3279 "(" ( <value-list> | <empty> ) ")" 3280 3281<group> ::= 3282 "{" ( <setting-list> | <empty> ) "}" 3283 3284<empty> ::= 3285</pre></div> 3286 3287<br> 3288<br> 3289<p>Terminals are defined below as regular expressions: 3290</p><br> 3291 3292<table> 3293<tr><td width="20%"><code><boolean></code></td><td width="80%"><code>([Tt][Rr][Uu][Ee])|([Ff][Aa][Ll][Ss][Ee])</code></td></tr> 3294<tr><td width="20%"><code><string></code></td><td width="80%"><code>\"([^\"\\]|\\.)*\"</code></td></tr> 3295<tr><td width="20%"><code><name></code></td><td width="80%"><code>[A-Za-z\*][-A-Za-z0-9_\*]*</code></td></tr> 3296<tr><td width="20%"><code><integer></code></td><td width="80%"><code>[-+]?[0-9]+</code></td></tr> 3297<tr><td width="20%"><code><integer64></code></td><td width="80%"><code>[-+]?[0-9]+L(L)?</code></td></tr> 3298<tr><td width="20%"><code><hex></code></td><td width="80%"><code>0[Xx][0-9A-Fa-f]+</code></td></tr> 3299<tr><td width="20%"><code><hex64></code></td><td width="80%"><code>0[Xx][0-9A-Fa-f]+(L(L)?)?</code></td></tr> 3300<tr><td width="20%"><code><float></code></td><td width="80%"><code>([-+]?([0-9]*)?\.[0-9]*([eE][-+]?[0-9]+)?)|([-+]([0-9]+)(\.[0-9]*)?[eE][-+]?[0-9]+)</code></td></tr> 3301</table> 3302 3303<br> 3304 3305<p>Note that adjacent strings are automatically concatenated. Non-printable 3306characters can be represented within strings using a sequence ‘<samp>\xx</samp>’, 3307representing the ASCII value as two hex digits. 3308</p> 3309<hr> 3310<a name="Function-Index"></a> 3311<div class="header"> 3312<p> 3313Next: <a href="#Type-Index" accesskey="n" rel="next">Type Index</a>, Previous: <a href="#Configuration-File-Grammar" accesskey="p" rel="prev">Configuration File Grammar</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 3314</div> 3315<a name="Function-Index-1"></a> 3316<h2 class="unnumbered">Function Index</h2> 3317 3318<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Function-Index_fn_symbol-1"><b>~</b></a> 3319 3320<br> 3321<a class="summary-letter" href="#Function-Index_fn_letter-A"><b>A</b></a> 3322 3323<a class="summary-letter" href="#Function-Index_fn_letter-B"><b>B</b></a> 3324 3325<a class="summary-letter" href="#Function-Index_fn_letter-C"><b>C</b></a> 3326 3327<a class="summary-letter" href="#Function-Index_fn_letter-E"><b>E</b></a> 3328 3329<a class="summary-letter" href="#Function-Index_fn_letter-F"><b>F</b></a> 3330 3331<a class="summary-letter" href="#Function-Index_fn_letter-G"><b>G</b></a> 3332 3333<a class="summary-letter" href="#Function-Index_fn_letter-I"><b>I</b></a> 3334 3335<a class="summary-letter" href="#Function-Index_fn_letter-L"><b>L</b></a> 3336 3337<a class="summary-letter" href="#Function-Index_fn_letter-O"><b>O</b></a> 3338 3339<a class="summary-letter" href="#Function-Index_fn_letter-P"><b>P</b></a> 3340 3341<a class="summary-letter" href="#Function-Index_fn_letter-R"><b>R</b></a> 3342 3343<a class="summary-letter" href="#Function-Index_fn_letter-S"><b>S</b></a> 3344 3345<a class="summary-letter" href="#Function-Index_fn_letter-W"><b>W</b></a> 3346 3347</td></tr></table> 3348<table class="index-fn" border="0"> 3349<tr><td></td><th align="left">Index Entry</th><td> </td><th align="left"> Section</th></tr> 3350<tr><td colspan="4"> <hr></td></tr> 3351<tr><th><a name="Function-Index_fn_symbol-1">~</a></th><td></td><td></td></tr> 3352<tr><td></td><td valign="top"><a href="#index-_007eConfig-on-Config"><code>~Config on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3353<tr><td colspan="4"> <hr></td></tr> 3354<tr><th><a name="Function-Index_fn_letter-A">A</a></th><td></td><td></td></tr> 3355<tr><td></td><td valign="top"><a href="#index-add-on-Setting"><code>add on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3356<tr><td></td><td valign="top"><a href="#index-add-on-Setting-1"><code>add on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3357<tr><td></td><td valign="top"><a href="#index-add-on-Setting-2"><code>add on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3358<tr><td colspan="4"> <hr></td></tr> 3359<tr><th><a name="Function-Index_fn_letter-B">B</a></th><td></td><td></td></tr> 3360<tr><td></td><td valign="top"><a href="#index-begin-on-Setting"><code>begin on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3361<tr><td></td><td valign="top"><a href="#index-begin-on-Setting-1"><code>begin on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3362<tr><td colspan="4"> <hr></td></tr> 3363<tr><th><a name="Function-Index_fn_letter-C">C</a></th><td></td><td></td></tr> 3364<tr><td></td><td valign="top"><a href="#index-clear-on-Config"><code>clear on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3365<tr><td></td><td valign="top"><a href="#index-Config-on-Config"><code>Config on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3366<tr><td></td><td valign="top"><a href="#index-config_005fclear"><code>config_clear</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3367<tr><td></td><td valign="top"><a href="#index-config_005fdestroy"><code>config_destroy</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3368<tr><td></td><td valign="top"><a href="#index-config_005ferror_005ffile"><code>config_error_file</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3369<tr><td></td><td valign="top"><a href="#index-config_005ferror_005fline"><code>config_error_line</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3370<tr><td></td><td valign="top"><a href="#index-config_005ferror_005ftext"><code>config_error_text</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3371<tr><td></td><td valign="top"><a href="#index-config_005ferror_005ftype"><code>config_error_type</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3372<tr><td></td><td valign="top"><a href="#index-config_005fget_005fauto_005fconvert"><code>config_get_auto_convert</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3373<tr><td></td><td valign="top"><a href="#index-config_005fget_005fdefault_005fformat"><code>config_get_default_format</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3374<tr><td></td><td valign="top"><a href="#index-config_005fget_005ffloat_005fprecision_0028config_005ft-_002aconfig_0029"><code>config_get_float_precision(<span class="nolinebreak">config_t</span> *<var>config</var><!-- /@w -->)</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3375<tr><td></td><td valign="top"><a href="#index-config_005fget_005fhook"><code>config_get_hook</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3376<tr><td></td><td valign="top"><a href="#index-config_005fget_005finclude_005fdir"><code>config_get_include_dir</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3377<tr><td></td><td valign="top"><a href="#index-config_005fget_005foption"><code>config_get_option</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3378<tr><td></td><td valign="top"><a href="#index-config_005fget_005foptions"><code>config_get_options</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3379<tr><td></td><td valign="top"><a href="#index-config_005fget_005ftab_005fwidth"><code>config_get_tab_width</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3380<tr><td></td><td valign="top"><a href="#index-config_005finit"><code>config_init</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3381<tr><td></td><td valign="top"><a href="#index-config_005flookup"><code>config_lookup</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3382<tr><td></td><td valign="top"><a href="#index-config_005flookup_005fbool"><code>config_lookup_bool</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3383<tr><td></td><td valign="top"><a href="#index-config_005flookup_005ffloat"><code>config_lookup_float</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3384<tr><td></td><td valign="top"><a href="#index-config_005flookup_005fint"><code>config_lookup_int</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3385<tr><td></td><td valign="top"><a href="#index-config_005flookup_005fint64"><code>config_lookup_int64</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3386<tr><td></td><td valign="top"><a href="#index-config_005flookup_005fstring"><code>config_lookup_string</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3387<tr><td></td><td valign="top"><a href="#index-config_005fread"><code>config_read</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3388<tr><td></td><td valign="top"><a href="#index-config_005fread_005ffile"><code>config_read_file</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3389<tr><td></td><td valign="top"><a href="#index-config_005fread_005fstring"><code>config_read_string</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3390<tr><td></td><td valign="top"><a href="#index-config_005froot_005fsetting"><code>config_root_setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3391<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fadd"><code>config_setting_add</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3392<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fget_005fbool"><code>config_setting_get_bool</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3393<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fget_005fbool_005felem"><code>config_setting_get_bool_elem</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3394<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fget_005felem"><code>config_setting_get_elem</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3395<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fget_005ffloat"><code>config_setting_get_float</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3396<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fget_005ffloat_005felem"><code>config_setting_get_float_elem</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3397<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fget_005fformat"><code>config_setting_get_format</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3398<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fget_005fhook"><code>config_setting_get_hook</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3399<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fget_005fint"><code>config_setting_get_int</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3400<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fget_005fint64"><code>config_setting_get_int64</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3401<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fget_005fint64_005felem"><code>config_setting_get_int64_elem</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3402<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fget_005fint_005felem"><code>config_setting_get_int_elem</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3403<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fget_005fmember"><code>config_setting_get_member</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3404<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fget_005fstring"><code>config_setting_get_string</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3405<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fget_005fstring_005felem"><code>config_setting_get_string_elem</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3406<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005findex"><code>config_setting_index</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3407<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fis_005faggregate"><code>config_setting_is_aggregate</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3408<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fis_005farray"><code>config_setting_is_array</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3409<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fis_005fgroup"><code>config_setting_is_group</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3410<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fis_005flist"><code>config_setting_is_list</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3411<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fis_005fnumber"><code>config_setting_is_number</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3412<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fis_005froot"><code>config_setting_is_root</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3413<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fis_005fscalar"><code>config_setting_is_scalar</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3414<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005flength"><code>config_setting_length</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3415<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005flookup"><code>config_setting_lookup</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3416<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005flookup_005fbool"><code>config_setting_lookup_bool</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3417<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005flookup_005ffloat"><code>config_setting_lookup_float</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3418<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005flookup_005fint"><code>config_setting_lookup_int</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3419<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005flookup_005fint64"><code>config_setting_lookup_int64</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3420<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005flookup_005fstring"><code>config_setting_lookup_string</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3421<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fname"><code>config_setting_name</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3422<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fparent"><code>config_setting_parent</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3423<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fremove"><code>config_setting_remove</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3424<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fremove_005felem"><code>config_setting_remove_elem</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3425<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fset_005fbool"><code>config_setting_set_bool</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3426<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fset_005fbool_005felem"><code>config_setting_set_bool_elem</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3427<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fset_005ffloat"><code>config_setting_set_float</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3428<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fset_005ffloat_005felem"><code>config_setting_set_float_elem</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3429<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fset_005fformat"><code>config_setting_set_format</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3430<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fset_005fhook"><code>config_setting_set_hook</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3431<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fset_005fint"><code>config_setting_set_int</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3432<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fset_005fint64"><code>config_setting_set_int64</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3433<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fset_005fint64_005felem"><code>config_setting_set_int64_elem</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3434<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fset_005fint_005felem"><code>config_setting_set_int_elem</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3435<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fset_005fstring"><code>config_setting_set_string</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3436<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fset_005fstring_005felem"><code>config_setting_set_string_elem</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3437<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fsource_005ffile"><code>config_setting_source_file</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3438<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005fsource_005fline"><code>config_setting_source_line</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3439<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005ftype"><code>config_setting_type</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3440<tr><td></td><td valign="top"><a href="#index-config_005fset_005fauto_005fconvert"><code>config_set_auto_convert</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3441<tr><td></td><td valign="top"><a href="#index-config_005fset_005fdefault_005fformat"><code>config_set_default_format</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3442<tr><td></td><td valign="top"><a href="#index-config_005fset_005fdestructor"><code>config_set_destructor</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3443<tr><td></td><td valign="top"><a href="#index-config_005fset_005ffloat_005fprecision_0028config_005ft-_002aconfig_002c"><code>config_set_float_precision(<span class="nolinebreak">config_t</span> *<var>config</var><!-- /@w -->,</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3444<tr><td></td><td valign="top"><a href="#index-config_005fset_005fhook"><code>config_set_hook</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3445<tr><td></td><td valign="top"><a href="#index-config_005fset_005finclude_005fdir"><code>config_set_include_dir</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3446<tr><td></td><td valign="top"><a href="#index-config_005fset_005finclude_005ffunc"><code>config_set_include_func</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3447<tr><td></td><td valign="top"><a href="#index-config_005fset_005foption"><code>config_set_option</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3448<tr><td></td><td valign="top"><a href="#index-config_005fset_005foptions"><code>config_set_options</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3449<tr><td></td><td valign="top"><a href="#index-config_005fset_005ftab_005fwidth"><code>config_set_tab_width</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3450<tr><td></td><td valign="top"><a href="#index-config_005fwrite"><code>config_write</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3451<tr><td></td><td valign="top"><a href="#index-config_005fwrite_005ffile"><code>config_write_file</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3452<tr><td></td><td valign="top"><a href="#index-c_005fstr-on-Setting"><code>c_str on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3453<tr><td colspan="4"> <hr></td></tr> 3454<tr><th><a name="Function-Index_fn_letter-E">E</a></th><td></td><td></td></tr> 3455<tr><td></td><td valign="top"><a href="#index-end-on-Setting"><code>end on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3456<tr><td></td><td valign="top"><a href="#index-end-on-Setting-1"><code>end on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3457<tr><td></td><td valign="top"><a href="#index-evaluateIncludePath-on-Config"><code>evaluateIncludePath on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3458<tr><td></td><td valign="top"><a href="#index-exists-on-Config"><code>exists on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3459<tr><td></td><td valign="top"><a href="#index-exists-on-Config-1"><code>exists on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3460<tr><td></td><td valign="top"><a href="#index-exists-on-Setting"><code>exists on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3461<tr><td></td><td valign="top"><a href="#index-exists-on-Setting-1"><code>exists on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3462<tr><td colspan="4"> <hr></td></tr> 3463<tr><th><a name="Function-Index_fn_letter-F">F</a></th><td></td><td></td></tr> 3464<tr><td></td><td valign="top"><a href="#index-func"><code>func</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3465<tr><td colspan="4"> <hr></td></tr> 3466<tr><th><a name="Function-Index_fn_letter-G">G</a></th><td></td><td></td></tr> 3467<tr><td></td><td valign="top"><a href="#index-getAutoConvert-on-Config"><code>getAutoConvert on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3468<tr><td></td><td valign="top"><a href="#index-getDefaultFormat-on-Config"><code>getDefaultFormat on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3469<tr><td></td><td valign="top"><a href="#index-getError-on-ParseException"><code>getError on ParseException</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3470<tr><td></td><td valign="top"><a href="#index-getFile-on-ParseException"><code>getFile on ParseException</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3471<tr><td></td><td valign="top"><a href="#index-getFloatPrecision-on-Config"><code>getFloatPrecision on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3472<tr><td></td><td valign="top"><a href="#index-getFormat-on-Setting"><code>getFormat on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3473<tr><td></td><td valign="top"><a href="#index-getIncludeDir-on-Config"><code>getIncludeDir on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3474<tr><td></td><td valign="top"><a href="#index-getIndex-on-Setting"><code>getIndex on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3475<tr><td></td><td valign="top"><a href="#index-getLength-on-Setting"><code>getLength on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3476<tr><td></td><td valign="top"><a href="#index-getLine-on-ParseException"><code>getLine on ParseException</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3477<tr><td></td><td valign="top"><a href="#index-getName-on-Setting"><code>getName on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3478<tr><td></td><td valign="top"><a href="#index-getOption-on-Config"><code>getOption on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3479<tr><td></td><td valign="top"><a href="#index-getOptions-on-Config"><code>getOptions on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3480<tr><td></td><td valign="top"><a href="#index-getParent-on-Setting"><code>getParent on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3481<tr><td></td><td valign="top"><a href="#index-getPath-on-Setting"><code>getPath on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3482<tr><td></td><td valign="top"><a href="#index-getPath-on-SettingException"><code>getPath on SettingException</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3483<tr><td></td><td valign="top"><a href="#index-getRoot-on-Config"><code>getRoot on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3484<tr><td></td><td valign="top"><a href="#index-getSourceFile-on-Setting"><code>getSourceFile on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3485<tr><td></td><td valign="top"><a href="#index-getSourceLine-on-Setting"><code>getSourceLine on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3486<tr><td></td><td valign="top"><a href="#index-getTabWidth-on-Config"><code>getTabWidth on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3487<tr><td></td><td valign="top"><a href="#index-getType-on-Setting"><code>getType on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3488<tr><td colspan="4"> <hr></td></tr> 3489<tr><th><a name="Function-Index_fn_letter-I">I</a></th><td></td><td></td></tr> 3490<tr><td></td><td valign="top"><a href="#index-isAggregate-on-Setting"><code>isAggregate on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3491<tr><td></td><td valign="top"><a href="#index-isArray-on-Setting"><code>isArray on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3492<tr><td></td><td valign="top"><a href="#index-isGroup-on-Setting"><code>isGroup on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3493<tr><td></td><td valign="top"><a href="#index-isList-on-Setting"><code>isList on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3494<tr><td></td><td valign="top"><a href="#index-isNumber-on-Setting"><code>isNumber on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3495<tr><td></td><td valign="top"><a href="#index-isRoot-on-Setting"><code>isRoot on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3496<tr><td></td><td valign="top"><a href="#index-isScalar-on-Setting"><code>isScalar on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3497<tr><td colspan="4"> <hr></td></tr> 3498<tr><th><a name="Function-Index_fn_letter-L">L</a></th><td></td><td></td></tr> 3499<tr><td></td><td valign="top"><a href="#index-LIBCONFIGXX_005fVER_005fMAJOR"><code>LIBCONFIGXX_VER_MAJOR</code></a>:</td><td> </td><td valign="top"><a href="#Version-Test-Macros">Version Test Macros</a></td></tr> 3500<tr><td></td><td valign="top"><a href="#index-LIBCONFIGXX_005fVER_005fMINOR"><code>LIBCONFIGXX_VER_MINOR</code></a>:</td><td> </td><td valign="top"><a href="#Version-Test-Macros">Version Test Macros</a></td></tr> 3501<tr><td></td><td valign="top"><a href="#index-LIBCONFIGXX_005fVER_005fREVISION"><code>LIBCONFIGXX_VER_REVISION</code></a>:</td><td> </td><td valign="top"><a href="#Version-Test-Macros">Version Test Macros</a></td></tr> 3502<tr><td></td><td valign="top"><a href="#index-LIBCONFIG_005fVER_005fMAJOR"><code>LIBCONFIG_VER_MAJOR</code></a>:</td><td> </td><td valign="top"><a href="#Version-Test-Macros">Version Test Macros</a></td></tr> 3503<tr><td></td><td valign="top"><a href="#index-LIBCONFIG_005fVER_005fMINOR"><code>LIBCONFIG_VER_MINOR</code></a>:</td><td> </td><td valign="top"><a href="#Version-Test-Macros">Version Test Macros</a></td></tr> 3504<tr><td></td><td valign="top"><a href="#index-LIBCONFIG_005fVER_005fREVISION"><code>LIBCONFIG_VER_REVISION</code></a>:</td><td> </td><td valign="top"><a href="#Version-Test-Macros">Version Test Macros</a></td></tr> 3505<tr><td></td><td valign="top"><a href="#index-lookup-on-Config"><code>lookup on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3506<tr><td></td><td valign="top"><a href="#index-lookup-on-Config-1"><code>lookup on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3507<tr><td></td><td valign="top"><a href="#index-lookup-on-Setting"><code>lookup on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3508<tr><td></td><td valign="top"><a href="#index-lookup-on-Setting-1"><code>lookup on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3509<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Config"><code>lookupValue on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3510<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Config-1"><code>lookupValue on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3511<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Config-2"><code>lookupValue on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3512<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Config-3"><code>lookupValue on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3513<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Config-4"><code>lookupValue on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3514<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Config-5"><code>lookupValue on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3515<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Config-6"><code>lookupValue on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3516<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Config-7"><code>lookupValue on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3517<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Config-8"><code>lookupValue on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3518<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Config-9"><code>lookupValue on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3519<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Config-10"><code>lookupValue on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3520<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Config-11"><code>lookupValue on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3521<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Config-12"><code>lookupValue on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3522<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Config-13"><code>lookupValue on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3523<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Config-14"><code>lookupValue on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3524<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Config-15"><code>lookupValue on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3525<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Setting"><code>lookupValue on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3526<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Setting-1"><code>lookupValue on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3527<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Setting-2"><code>lookupValue on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3528<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Setting-3"><code>lookupValue on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3529<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Setting-4"><code>lookupValue on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3530<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Setting-5"><code>lookupValue on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3531<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Setting-6"><code>lookupValue on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3532<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Setting-7"><code>lookupValue on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3533<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Setting-8"><code>lookupValue on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3534<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Setting-9"><code>lookupValue on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3535<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Setting-10"><code>lookupValue on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3536<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Setting-11"><code>lookupValue on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3537<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Setting-12"><code>lookupValue on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3538<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Setting-13"><code>lookupValue on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3539<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Setting-14"><code>lookupValue on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3540<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Setting-15"><code>lookupValue on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3541<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Setting-16"><code>lookupValue on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3542<tr><td></td><td valign="top"><a href="#index-lookupValue-on-Setting-17"><code>lookupValue on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3543<tr><td colspan="4"> <hr></td></tr> 3544<tr><th><a name="Function-Index_fn_letter-O">O</a></th><td></td><td></td></tr> 3545<tr><td></td><td valign="top"><a href="#index-operator-bool-_0028_0029-on-Setting"><code>operator bool () on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3546<tr><td></td><td valign="top"><a href="#index-operator-const-char-_002a-_0028_0029-on-Setting"><code>operator const char * () on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3547<tr><td></td><td valign="top"><a href="#index-operator-double-_0028_0029-on-Setting"><code>operator double () on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3548<tr><td></td><td valign="top"><a href="#index-operator-float-_0028_0029-on-Setting"><code>operator float () on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3549<tr><td></td><td valign="top"><a href="#index-operator-int-_0028_0029-on-Setting"><code>operator int () on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3550<tr><td></td><td valign="top"><a href="#index-operator-long-_0028_0029-on-Setting"><code>operator long () on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3551<tr><td></td><td valign="top"><a href="#index-operator-long-long-_0028_0029-on-Setting"><code>operator long long () on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3552<tr><td></td><td valign="top"><a href="#index-operator-std_003a_003astring-_0028_0029-on-Setting"><code>operator std::string () on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3553<tr><td></td><td valign="top"><a href="#index-operator-unsigned-int-_0028_0029-on-Setting"><code>operator unsigned int () on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3554<tr><td></td><td valign="top"><a href="#index-operator-unsigned-long-_0028_0029-on-Setting"><code>operator unsigned long () on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3555<tr><td></td><td valign="top"><a href="#index-operator-unsigned-long-long-_0028_0029-on-Setting"><code>operator unsigned long long () on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3556<tr><td></td><td valign="top"><a href="#index-operator_003d-on-Setting"><code>operator= on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3557<tr><td></td><td valign="top"><a href="#index-operator_003d-on-Setting-1"><code>operator= on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3558<tr><td></td><td valign="top"><a href="#index-operator_003d-on-Setting-2"><code>operator= on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3559<tr><td></td><td valign="top"><a href="#index-operator_003d-on-Setting-3"><code>operator= on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3560<tr><td></td><td valign="top"><a href="#index-operator_003d-on-Setting-4"><code>operator= on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3561<tr><td></td><td valign="top"><a href="#index-operator_003d-on-Setting-5"><code>operator= on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3562<tr><td></td><td valign="top"><a href="#index-operator_003d-on-Setting-6"><code>operator= on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3563<tr><td></td><td valign="top"><a href="#index-operator_003d-on-Setting-7"><code>operator= on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3564<tr><td></td><td valign="top"><a href="#index-operator_005b_005d-on-Setting"><code>operator[] on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3565<tr><td></td><td valign="top"><a href="#index-operator_005b_005d-on-Setting-1"><code>operator[] on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3566<tr><td></td><td valign="top"><a href="#index-operator_005b_005d-on-Setting-2"><code>operator[] on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3567<tr><td colspan="4"> <hr></td></tr> 3568<tr><th><a name="Function-Index_fn_letter-P">P</a></th><td></td><td></td></tr> 3569<tr><td></td><td valign="top"><a href="#index-ParseException-on-ParseException"><code>ParseException on ParseException</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3570<tr><td colspan="4"> <hr></td></tr> 3571<tr><th><a name="Function-Index_fn_letter-R">R</a></th><td></td><td></td></tr> 3572<tr><td></td><td valign="top"><a href="#index-read-on-Config"><code>read on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3573<tr><td></td><td valign="top"><a href="#index-readFile-on-Config"><code>readFile on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3574<tr><td></td><td valign="top"><a href="#index-readString-on-Config"><code>readString on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3575<tr><td></td><td valign="top"><a href="#index-readString-on-Config-1"><code>readString on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3576<tr><td></td><td valign="top"><a href="#index-remove-on-Setting"><code>remove on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3577<tr><td></td><td valign="top"><a href="#index-remove-on-Setting-1"><code>remove on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3578<tr><td></td><td valign="top"><a href="#index-remove-on-Setting-2"><code>remove on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3579<tr><td colspan="4"> <hr></td></tr> 3580<tr><th><a name="Function-Index_fn_letter-S">S</a></th><td></td><td></td></tr> 3581<tr><td></td><td valign="top"><a href="#index-setAutoConvert-on-Config"><code>setAutoConvert on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3582<tr><td></td><td valign="top"><a href="#index-setDefaultFormat-on-Config"><code>setDefaultFormat on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3583<tr><td></td><td valign="top"><a href="#index-setFloatPrecision-on-Config"><code>setFloatPrecision on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3584<tr><td></td><td valign="top"><a href="#index-setFormat-on-Setting"><code>setFormat on Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3585<tr><td></td><td valign="top"><a href="#index-setIncludeDir-on-Config"><code>setIncludeDir on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3586<tr><td></td><td valign="top"><a href="#index-setOption-on-Config"><code>setOption on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3587<tr><td></td><td valign="top"><a href="#index-setOptions-on-Config"><code>setOptions on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3588<tr><td></td><td valign="top"><a href="#index-setTabWidth-on-Config"><code>setTabWidth on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3589<tr><td></td><td valign="top"><a href="#index-SettingNameException-on-SettingNameException"><code>SettingNameException on SettingNameException</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3590<tr><td></td><td valign="top"><a href="#index-SettingNotFoundException-on-SettingNotFoundException"><code>SettingNotFoundException on SettingNotFoundException</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3591<tr><td></td><td valign="top"><a href="#index-SettingNotFoundException-on-SettingNotFoundException-1"><code>SettingNotFoundException on SettingNotFoundException</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3592<tr><td></td><td valign="top"><a href="#index-SettingNotFoundException-on-SettingNotFoundException-2"><code>SettingNotFoundException on SettingNotFoundException</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3593<tr><td></td><td valign="top"><a href="#index-SettingTypeException-on-SettingTypeException"><code>SettingTypeException on SettingTypeException</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3594<tr><td></td><td valign="top"><a href="#index-SettingTypeException-on-SettingTypeException-1"><code>SettingTypeException on SettingTypeException</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3595<tr><td></td><td valign="top"><a href="#index-SettingTypeException-on-SettingTypeException-2"><code>SettingTypeException on SettingTypeException</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3596<tr><td colspan="4"> <hr></td></tr> 3597<tr><th><a name="Function-Index_fn_letter-W">W</a></th><td></td><td></td></tr> 3598<tr><td></td><td valign="top"><a href="#index-write-on-Config"><code>write on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3599<tr><td></td><td valign="top"><a href="#index-writeFile-on-Config"><code>writeFile on Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3600<tr><td colspan="4"> <hr></td></tr> 3601</table> 3602<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Function-Index_fn_symbol-1"><b>~</b></a> 3603 3604<br> 3605<a class="summary-letter" href="#Function-Index_fn_letter-A"><b>A</b></a> 3606 3607<a class="summary-letter" href="#Function-Index_fn_letter-B"><b>B</b></a> 3608 3609<a class="summary-letter" href="#Function-Index_fn_letter-C"><b>C</b></a> 3610 3611<a class="summary-letter" href="#Function-Index_fn_letter-E"><b>E</b></a> 3612 3613<a class="summary-letter" href="#Function-Index_fn_letter-F"><b>F</b></a> 3614 3615<a class="summary-letter" href="#Function-Index_fn_letter-G"><b>G</b></a> 3616 3617<a class="summary-letter" href="#Function-Index_fn_letter-I"><b>I</b></a> 3618 3619<a class="summary-letter" href="#Function-Index_fn_letter-L"><b>L</b></a> 3620 3621<a class="summary-letter" href="#Function-Index_fn_letter-O"><b>O</b></a> 3622 3623<a class="summary-letter" href="#Function-Index_fn_letter-P"><b>P</b></a> 3624 3625<a class="summary-letter" href="#Function-Index_fn_letter-R"><b>R</b></a> 3626 3627<a class="summary-letter" href="#Function-Index_fn_letter-S"><b>S</b></a> 3628 3629<a class="summary-letter" href="#Function-Index_fn_letter-W"><b>W</b></a> 3630 3631</td></tr></table> 3632 3633<hr> 3634<a name="Type-Index"></a> 3635<div class="header"> 3636<p> 3637Next: <a href="#Concept-Index" accesskey="n" rel="next">Concept Index</a>, Previous: <a href="#Function-Index" accesskey="p" rel="prev">Function Index</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 3638</div> 3639<a name="Type-Index-1"></a> 3640<h2 class="unnumbered">Type Index</h2> 3641 3642<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Type-Index_tp_letter-C"><b>C</b></a> 3643 3644<a class="summary-letter" href="#Type-Index_tp_letter-F"><b>F</b></a> 3645 3646<a class="summary-letter" href="#Type-Index_tp_letter-P"><b>P</b></a> 3647 3648<a class="summary-letter" href="#Type-Index_tp_letter-S"><b>S</b></a> 3649 3650</td></tr></table> 3651<table class="index-tp" border="0"> 3652<tr><td></td><th align="left">Index Entry</th><td> </td><th align="left"> Section</th></tr> 3653<tr><td colspan="4"> <hr></td></tr> 3654<tr><th><a name="Type-Index_tp_letter-C">C</a></th><td></td><td></td></tr> 3655<tr><td></td><td valign="top"><a href="#index-Config"><code>Config</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3656<tr><td></td><td valign="top"><a href="#index-Config_003a_003aOption"><code>Config::Option</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3657<tr><td></td><td valign="top"><a href="#index-ConfigException"><code>ConfigException</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3658<tr><td></td><td valign="top"><a href="#index-config_005ferror_005ft"><code>config_error_t</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3659<tr><td></td><td valign="top"><a href="#index-config_005finclude_005ffn_005ft"><code>config_include_fn_t</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3660<tr><td></td><td valign="top"><a href="#index-config_005fsetting_005ft"><code>config_setting_t</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3661<tr><td></td><td valign="top"><a href="#index-config_005ft"><code>config_t</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3662<tr><td colspan="4"> <hr></td></tr> 3663<tr><th><a name="Type-Index_tp_letter-F">F</a></th><td></td><td></td></tr> 3664<tr><td></td><td valign="top"><a href="#index-FileIOException"><code>FileIOException</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3665<tr><td colspan="4"> <hr></td></tr> 3666<tr><th><a name="Type-Index_tp_letter-P">P</a></th><td></td><td></td></tr> 3667<tr><td></td><td valign="top"><a href="#index-ParseException"><code>ParseException</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3668<tr><td colspan="4"> <hr></td></tr> 3669<tr><th><a name="Type-Index_tp_letter-S">S</a></th><td></td><td></td></tr> 3670<tr><td></td><td valign="top"><a href="#index-Setting"><code>Setting</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3671<tr><td></td><td valign="top"><a href="#index-Setting_003a_003aFormat"><code>Setting::Format</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3672<tr><td></td><td valign="top"><a href="#index-Setting_003a_003aType"><code>Setting::Type</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3673<tr><td></td><td valign="top"><a href="#index-SettingException"><code>SettingException</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3674<tr><td></td><td valign="top"><a href="#index-SettingFormat"><code>SettingFormat</code></a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3675<tr><td></td><td valign="top"><a href="#index-SettingNameException"><code>SettingNameException</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3676<tr><td></td><td valign="top"><a href="#index-SettingNotFoundException"><code>SettingNotFoundException</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3677<tr><td></td><td valign="top"><a href="#index-SettingTypeException"><code>SettingTypeException</code></a>:</td><td> </td><td valign="top"><a href="#The-C_002b_002b-API">The C++ API</a></td></tr> 3678<tr><td colspan="4"> <hr></td></tr> 3679</table> 3680<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Type-Index_tp_letter-C"><b>C</b></a> 3681 3682<a class="summary-letter" href="#Type-Index_tp_letter-F"><b>F</b></a> 3683 3684<a class="summary-letter" href="#Type-Index_tp_letter-P"><b>P</b></a> 3685 3686<a class="summary-letter" href="#Type-Index_tp_letter-S"><b>S</b></a> 3687 3688</td></tr></table> 3689 3690<hr> 3691<a name="Concept-Index"></a> 3692<div class="header"> 3693<p> 3694Previous: <a href="#Type-Index" accesskey="p" rel="prev">Type Index</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Function-Index" title="Index" rel="index">Index</a>]</p> 3695</div> 3696<a name="Concept-Index-1"></a> 3697<h2 class="unnumbered">Concept Index</h2> 3698 3699<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Concept-Index_cp_letter-A"><b>A</b></a> 3700 3701<a class="summary-letter" href="#Concept-Index_cp_letter-C"><b>C</b></a> 3702 3703<a class="summary-letter" href="#Concept-Index_cp_letter-D"><b>D</b></a> 3704 3705<a class="summary-letter" href="#Concept-Index_cp_letter-E"><b>E</b></a> 3706 3707<a class="summary-letter" href="#Concept-Index_cp_letter-F"><b>F</b></a> 3708 3709<a class="summary-letter" href="#Concept-Index_cp_letter-G"><b>G</b></a> 3710 3711<a class="summary-letter" href="#Concept-Index_cp_letter-H"><b>H</b></a> 3712 3713<a class="summary-letter" href="#Concept-Index_cp_letter-I"><b>I</b></a> 3714 3715<a class="summary-letter" href="#Concept-Index_cp_letter-L"><b>L</b></a> 3716 3717<a class="summary-letter" href="#Concept-Index_cp_letter-P"><b>P</b></a> 3718 3719<a class="summary-letter" href="#Concept-Index_cp_letter-S"><b>S</b></a> 3720 3721<a class="summary-letter" href="#Concept-Index_cp_letter-U"><b>U</b></a> 3722 3723<a class="summary-letter" href="#Concept-Index_cp_letter-V"><b>V</b></a> 3724 3725</td></tr></table> 3726<table class="index-cp" border="0"> 3727<tr><td></td><th align="left">Index Entry</th><td> </td><th align="left"> Section</th></tr> 3728<tr><td colspan="4"> <hr></td></tr> 3729<tr><th><a name="Concept-Index_cp_letter-A">A</a></th><td></td><td></td></tr> 3730<tr><td></td><td valign="top"><a href="#index-aggregate-value">aggregate value</a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3731<tr><td></td><td valign="top"><a href="#index-array">array</a>:</td><td> </td><td valign="top"><a href="#Configuration-Files">Configuration Files</a></td></tr> 3732<tr><td colspan="4"> <hr></td></tr> 3733<tr><th><a name="Concept-Index_cp_letter-C">C</a></th><td></td><td></td></tr> 3734<tr><td></td><td valign="top"><a href="#index-comment">comment</a>:</td><td> </td><td valign="top"><a href="#Comments">Comments</a></td></tr> 3735<tr><td></td><td valign="top"><a href="#index-configuration">configuration</a>:</td><td> </td><td valign="top"><a href="#Configuration-Files">Configuration Files</a></td></tr> 3736<tr><td colspan="4"> <hr></td></tr> 3737<tr><th><a name="Concept-Index_cp_letter-D">D</a></th><td></td><td></td></tr> 3738<tr><td></td><td valign="top"><a href="#index-destructor-function">destructor function</a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3739<tr><td colspan="4"> <hr></td></tr> 3740<tr><th><a name="Concept-Index_cp_letter-E">E</a></th><td></td><td></td></tr> 3741<tr><td></td><td valign="top"><a href="#index-escape-sequence">escape sequence</a>:</td><td> </td><td valign="top"><a href="#String-Values">String Values</a></td></tr> 3742<tr><td colspan="4"> <hr></td></tr> 3743<tr><th><a name="Concept-Index_cp_letter-F">F</a></th><td></td><td></td></tr> 3744<tr><td></td><td valign="top"><a href="#index-format">format</a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3745<tr><td colspan="4"> <hr></td></tr> 3746<tr><th><a name="Concept-Index_cp_letter-G">G</a></th><td></td><td></td></tr> 3747<tr><td></td><td valign="top"><a href="#index-group">group</a>:</td><td> </td><td valign="top"><a href="#Configuration-Files">Configuration Files</a></td></tr> 3748<tr><td colspan="4"> <hr></td></tr> 3749<tr><th><a name="Concept-Index_cp_letter-H">H</a></th><td></td><td></td></tr> 3750<tr><td></td><td valign="top"><a href="#index-hook">hook</a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3751<tr><td></td><td valign="top"><a href="#index-hook-1">hook</a>:</td><td> </td><td valign="top"><a href="#The-C-API">The C API</a></td></tr> 3752<tr><td colspan="4"> <hr></td></tr> 3753<tr><th><a name="Concept-Index_cp_letter-I">I</a></th><td></td><td></td></tr> 3754<tr><td></td><td valign="top"><a href="#index-include-directive">include directive</a>:</td><td> </td><td valign="top"><a href="#Include-Directives">Include Directives</a></td></tr> 3755<tr><td></td><td valign="top"><a href="#index-include-function">include function</a>:</td><td> </td><td valign="top"><a href="#Include-Directives">Include Directives</a></td></tr> 3756<tr><td colspan="4"> <hr></td></tr> 3757<tr><th><a name="Concept-Index_cp_letter-L">L</a></th><td></td><td></td></tr> 3758<tr><td></td><td valign="top"><a href="#index-list">list</a>:</td><td> </td><td valign="top"><a href="#Configuration-Files">Configuration Files</a></td></tr> 3759<tr><td></td><td valign="top"><a href="#index-locale">locale</a>:</td><td> </td><td valign="top"><a href="#Internationalization-Issues">Internationalization Issues</a></td></tr> 3760<tr><td colspan="4"> <hr></td></tr> 3761<tr><th><a name="Concept-Index_cp_letter-P">P</a></th><td></td><td></td></tr> 3762<tr><td></td><td valign="top"><a href="#index-path">path</a>:</td><td> </td><td valign="top"><a href="#Configuration-Files">Configuration Files</a></td></tr> 3763<tr><td></td><td valign="top"><a href="#index-pkg_002dconfig">pkg-config</a>:</td><td> </td><td valign="top"><a href="#Compiling-Using-pkg_002dconfig">Compiling Using pkg-config</a></td></tr> 3764<tr><td colspan="4"> <hr></td></tr> 3765<tr><th><a name="Concept-Index_cp_letter-S">S</a></th><td></td><td></td></tr> 3766<tr><td></td><td valign="top"><a href="#index-scalar-value">scalar value</a>:</td><td> </td><td valign="top"><a href="#Configuration-Files">Configuration Files</a></td></tr> 3767<tr><td></td><td valign="top"><a href="#index-setting">setting</a>:</td><td> </td><td valign="top"><a href="#Configuration-Files">Configuration Files</a></td></tr> 3768<tr><td colspan="4"> <hr></td></tr> 3769<tr><th><a name="Concept-Index_cp_letter-U">U</a></th><td></td><td></td></tr> 3770<tr><td></td><td valign="top"><a href="#index-Unicode">Unicode</a>:</td><td> </td><td valign="top"><a href="#Internationalization-Issues">Internationalization Issues</a></td></tr> 3771<tr><td></td><td valign="top"><a href="#index-UTF_002d8">UTF-8</a>:</td><td> </td><td valign="top"><a href="#Internationalization-Issues">Internationalization Issues</a></td></tr> 3772<tr><td colspan="4"> <hr></td></tr> 3773<tr><th><a name="Concept-Index_cp_letter-V">V</a></th><td></td><td></td></tr> 3774<tr><td></td><td valign="top"><a href="#index-value">value</a>:</td><td> </td><td valign="top"><a href="#Configuration-Files">Configuration Files</a></td></tr> 3775<tr><td colspan="4"> <hr></td></tr> 3776</table> 3777<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Concept-Index_cp_letter-A"><b>A</b></a> 3778 3779<a class="summary-letter" href="#Concept-Index_cp_letter-C"><b>C</b></a> 3780 3781<a class="summary-letter" href="#Concept-Index_cp_letter-D"><b>D</b></a> 3782 3783<a class="summary-letter" href="#Concept-Index_cp_letter-E"><b>E</b></a> 3784 3785<a class="summary-letter" href="#Concept-Index_cp_letter-F"><b>F</b></a> 3786 3787<a class="summary-letter" href="#Concept-Index_cp_letter-G"><b>G</b></a> 3788 3789<a class="summary-letter" href="#Concept-Index_cp_letter-H"><b>H</b></a> 3790 3791<a class="summary-letter" href="#Concept-Index_cp_letter-I"><b>I</b></a> 3792 3793<a class="summary-letter" href="#Concept-Index_cp_letter-L"><b>L</b></a> 3794 3795<a class="summary-letter" href="#Concept-Index_cp_letter-P"><b>P</b></a> 3796 3797<a class="summary-letter" href="#Concept-Index_cp_letter-S"><b>S</b></a> 3798 3799<a class="summary-letter" href="#Concept-Index_cp_letter-U"><b>U</b></a> 3800 3801<a class="summary-letter" href="#Concept-Index_cp_letter-V"><b>V</b></a> 3802 3803</td></tr></table> 3804 3805<hr> 3806 3807 3808 3809</body> 3810</html> 3811