diff options
Diffstat (limited to 'docs/libconfig_manual.html')
| -rw-r--r-- | docs/libconfig_manual.html | 3810 |
1 files changed, 3810 insertions, 0 deletions
diff --git a/docs/libconfig_manual.html b/docs/libconfig_manual.html new file mode 100644 index 0000000..2b5da07 --- /dev/null +++ b/docs/libconfig_manual.html @@ -0,0 +1,3810 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Created by GNU Texinfo 6.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>libconfig</title> + +<meta name="description" content="libconfig"> +<meta name="keywords" content="libconfig"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="#Top" rel="start" title="Top"> +<link href="#Function-Index" rel="index" title="Function Index"> +<link href="#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="dir.html#Top" rel="up" title="(dir)"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.indentedblock {margin-right: 0em} +blockquote.smallindentedblock {margin-right: 0em; font-size: smaller} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smalllisp {margin-left: 3.2em} +kbd {font-style: oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nolinebreak {white-space: nowrap} +span.roman {font-family: initial; font-weight: normal} +span.sansserif {font-family: sans-serif; font-weight: normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en"> +<h1 class="settitle" align="center">libconfig</h1> + + + + + + + + + +<hr noshade size=6 color="black"> +<div align=right>A Library For Processing Structured Configuration Files<br> +Version 1.7.2<br> +5 Jan 2018</div> +<br><br><br><br> +<font size=+1>Mark A. Lindner</font> +<hr size=3 noshade color="black"> +<br><br> + +<a name="SEC_Contents"></a> +<h2 class="contents-heading">Table of Contents</h2> + +<div class="contents"> + +<ul class="no-bullet"> + <li><a name="toc-Introduction-1" href="#Introduction">1 Introduction</a> + <ul class="no-bullet"> + <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> + <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> + <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> + <li><a name="toc-Multithreading-Issues-1" href="#Multithreading-Issues">1.4 Multithreading Issues</a></li> + <li><a name="toc-Internationalization-Issues-1" href="#Internationalization-Issues">1.5 Internationalization Issues</a></li> + <li><a name="toc-Compiling-Using-pkg_002dconfig-1" href="#Compiling-Using-pkg_002dconfig">1.6 Compiling Using pkg-config</a></li> + <li><a name="toc-Version-Test-Macros-1" href="#Version-Test-Macros">1.7 Version Test Macros</a></li> + </ul></li> + <li><a name="toc-Configuration-Files-1" href="#Configuration-Files">2 Configuration Files</a> + <ul class="no-bullet"> + <li><a name="toc-Settings-1" href="#Settings">2.1 Settings</a></li> + <li><a name="toc-Groups-1" href="#Groups">2.2 Groups</a></li> + <li><a name="toc-Arrays-1" href="#Arrays">2.3 Arrays</a></li> + <li><a name="toc-Lists-1" href="#Lists">2.4 Lists</a></li> + <li><a name="toc-Integer-Values-1" href="#Integer-Values">2.5 Integer Values</a></li> + <li><a name="toc-64_002dbit-Integer-Values-1" href="#g_t64_002dbit-Integer-Values">2.6 64-bit Integer Values</a></li> + <li><a name="toc-Floating-Point-Values-1" href="#Floating-Point-Values">2.7 Floating Point Values</a></li> + <li><a name="toc-Boolean-Values-1" href="#Boolean-Values">2.8 Boolean Values</a></li> + <li><a name="toc-String-Values-1" href="#String-Values">2.9 String Values</a></li> + <li><a name="toc-Comments-1" href="#Comments">2.10 Comments</a></li> + <li><a name="toc-Include-Directives-1" href="#Include-Directives">2.11 Include Directives</a></li> + </ul></li> + <li><a name="toc-The-C-API-1" href="#The-C-API">3 The C API</a></li> + <li><a name="toc-The-C_002b_002b-API-1" href="#The-C_002b_002b-API">4 The C++ API</a></li> + <li><a name="toc-Example-Programs-1" href="#Example-Programs">5 Example Programs</a></li> + <li><a name="toc-Other-Bindings-and-Implementations-1" href="#Other-Bindings-and-Implementations">6 Other Bindings and Implementations</a> + <ul class="no-bullet"> + <li><a name="toc-Bourne-Shell-1" href="#Bourne-Shell">6.1 Bourne Shell</a></li> + <li><a name="toc-D-1" href="#D">6.2 D</a></li> + <li><a name="toc-Haskell-1" href="#Haskell">6.3 Haskell</a></li> + <li><a name="toc-Java-1" href="#Java">6.4 Java</a></li> + <li><a name="toc-Lisp-1" href="#Lisp">6.5 Lisp</a></li> + <li><a name="toc-Perl-1" href="#Perl">6.6 Perl</a></li> + <li><a name="toc-Python-1" href="#Python">6.7 Python</a></li> + <li><a name="toc-Ruby-1" href="#Ruby">6.8 Ruby</a></li> + </ul></li> + <li><a name="toc-License-1" href="#License">Appendix A License</a></li> + <li><a name="toc-Configuration-File-Grammar-1" href="#Configuration-File-Grammar">Appendix B Configuration File Grammar</a></li> + <li><a name="toc-Function-Index-1" href="#Function-Index">Function Index</a></li> + <li><a name="toc-Type-Index-1" href="#Type-Index">Type Index</a></li> + <li><a name="toc-Concept-Index-1" href="#Concept-Index">Concept Index</a></li> +</ul> +</div> + + +<a name="Top"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="libconfig"></a> +<h1 class="top">libconfig</h1> + +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Introduction" accesskey="1">Introduction</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="#Configuration-Files" accesskey="2">Configuration Files</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<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"> +</td></tr> +<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"> +</td></tr> +<tr><td align="left" valign="top">• <a href="#Example-Programs" accesskey="5">Example Programs</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<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"> +</td></tr> +<tr><td align="left" valign="top">• <a href="#License" accesskey="7">License</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<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"> +</td></tr> +<tr><td align="left" valign="top">• <a href="#Function-Index" accesskey="9">Function Index</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="#Type-Index">Type Index</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="#Concept-Index">Concept Index</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +</table> + +<hr> +<a name="Introduction"></a> +<div class="header"> +<p> +Next: <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> +</div> +<table class="menu" border="0" cellspacing="0"> +<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"> +</td></tr> +<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"> +</td></tr> +<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"> +</td></tr> +<tr><td align="left" valign="top">• <a href="#Multithreading-Issues" accesskey="4">Multithreading Issues</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="#Internationalization-Issues" accesskey="5">Internationalization Issues</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<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"> +</td></tr> +<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"> +</td></tr> +</table> +<a name="Introduction-1"></a> +<h2 class="chapter">1 Introduction</h2> + +<p><i>Libconfig</i> is a library for reading, manipulating, and writing +structured configuration files. The library features a fully +reentrant parser and includes bindings for both the C and C++ +programming languages. +</p> +<p>The library runs on modern POSIX-compilant systems, such as Linux, +Solaris, and Mac OS X (Darwin), as well as on Microsoft Windows +2000/XP and later (with either Microsoft Visual Studio 2005 or later, +or the GNU toolchain via the MinGW environment). +</p> +<hr> +<a name="Why-Another-Configuration-File-Library_003f"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="Why-Another-Configuration-File-Library_003f-1"></a> +<h3 class="section">1.1 Why Another Configuration File Library?</h3> + +<p>There are several open-source configuration file libraries available +as of this writing. This library was written because each of those +libraries falls short in one or more ways. The main features of +<i>libconfig</i> that set it apart from the other libraries are: +</p> +<ul> +<li> A fully reentrant parser. Independent configurations can be parsed in concurrent threads at the same time. + +</li><li> Both C <i>and</i> C++ bindings, as well as hooks to allow for the creation of wrappers in other languages. + +</li><li> A simple, structured configuration file format that is more +readable and compact than XML and more flexible than the obsolete but +prevalent Windows “INI” file format. + +</li><li> A low-footprint implementation (just 37K for the C library and 76K for +the C++ library) that is suitable for memory-constrained systems. + +</li><li> Proper documentation. + +</li></ul> + +<hr> +<a name="Using-the-Library-from-a-C-Program"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="Using-the-Library-from-a-C-Program-1"></a> +<h3 class="section">1.2 Using the Library from a C Program</h3> + +<p>To use the library from C code, include the following preprocessor +directive in your source files: +</p> +<br> +<div class="smallexample"> +<pre class="smallexample">#include <libconfig.h> +</pre></div> +<br> + +<p>To link with the library, specify ‘<samp>-lconfig</samp>’ as an argument to the +linker. +</p> +<hr> +<a name="Using-the-Library-from-a-C_002b_002b-Program"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="Using-the-Library-from-a-C_002b_002b-Program-1"></a> +<h3 class="section">1.3 Using the Library from a C++ Program</h3> + +<p>To use the library from C++, include the following preprocessor +directive in your source files: +</p> +<br> +<div class="smallexample"> +<pre class="smallexample">#include <libconfig.h++> +</pre></div> +<br> + +<p>Or, alternatively: +</p> +<br> +<div class="smallexample"> +<pre class="smallexample">#include <libconfig.hh> +</pre></div> +<br> +<p>The C++ API classes are defined in the namespace ‘<samp>libconfig</samp>’, hence the +following statement may optionally be used: +</p> +<br> +<div class="smallexample"> +<pre class="smallexample">using namespace libconfig; +</pre></div> +<br> + +<p>To link with the library, specify ‘<samp>-lconfig++</samp>’ as an argument to +the linker. +</p> +<hr> +<a name="Multithreading-Issues"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="Multithreading-Issues-1"></a> +<h3 class="section">1.4 Multithreading Issues</h3> + +<p><i>Libconfig</i> is fully <em>reentrant</em>; the functions in the library +do not make use of global variables and do not maintain state between +successive calls. Therefore two independent configurations may be safely +manipulated concurrently by two distinct threads. +</p> +<p><i>Libconfig</i> is not <em>thread-safe</em>. The library is not aware of +the presence of threads and knows nothing about the host system’s +threading model. Therefore, if an instance of a configuration is to be +accessed from multiple threads, it must be suitably protected by +synchronization mechanisms like read-write locks or mutexes; the +standard rules for safe multithreaded access to shared data must be +observed. +</p> +<p><i>Libconfig</i> is not <em>async-safe</em>. Calls should not be made into +the library from signal handlers, because some of the C library +routines that it uses may not be async-safe. +</p> +<p><i>Libconfig</i> is not guaranteed to be <em>cancel-safe</em>. Since it is +not aware of the host system’s threading model, the library does not +contain any thread cancellation points. In most cases this will not be +an issue for multithreaded programs. However, be aware that some of +the routines in the library (namely those that read/write +configurations from/to files or streams) perform I/O using C library +routines which may potentially block; whether or not these C library +routines are cancel-safe depends on the host system. +</p> +<hr> +<a name="Internationalization-Issues"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="Internationalization-Issues-1"></a> +<h3 class="section">1.5 Internationalization Issues</h3> + +<a name="index-Unicode"></a> +<a name="index-UTF_002d8"></a> +<p><i>Libconfig</i> does not natively support Unicode configuration files, +but string values may contain Unicode text encoded in UTF-8; such +strings will be treated as ordinary 8-bit ASCII text by the +library. It is the responsibility of the calling program to perform +the necessary conversions to/from wide (<tt>wchar_t</tt>) strings using the +wide string conversion functions such as <tt>mbsrtowcs()</tt> and +<tt>wcsrtombs()</tt> or the <tt>iconv()</tt> function of the <i>libiconv</i> +library. +</p> +<a name="index-locale"></a> +<p>The textual representation of a floating point value varies by +locale. However, the <i>libconfig</i> grammar specifies that +floating point values are represented using a period (‘.’) as the +radix symbol; this is consistent with the grammar of most programming +languages. When a configuration is read in or written out, +<i>libconfig</i> temporarily changes the <tt>LC_NUMERIC</tt> category of the +locale of the calling thread to the “C” locale to ensure consistent +handling of floating point values regardless of the locale(s) in use +by the calling program. +</p> +<p>Note that the MinGW environment does not (as of this writing) provide +functions for changing the locale of the calling thread. Therefore, +when using <i>libconfig</i> in that environment, the calling program is +responsible for changing the <tt>LC_NUMERIC</tt> category of the locale to +the "C" locale before reading or writing a configuration. +</p> +<hr> +<a name="Compiling-Using-pkg_002dconfig"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="Compiling-Using-pkg_002dconfig-1"></a> +<h3 class="section">1.6 Compiling Using pkg-config</h3> + +<a name="index-pkg_002dconfig"></a> +<p>On UNIX systems you can use the <i>pkg-config</i> utility (version 0.20 +or later) to automatically select the appropriate compiler and linker +switches for <i>libconfig</i>. Ensure that the environment variable +<code>PKG_CONFIG_PATH</code> contains the absolute path to the +<samp>lib/pkgconfig</samp> subdirectory of the <i>libconfig</i> installation. Then, +you can compile and link C programs with <i>libconfig</i> as follows: +</p> +<div class="smallexample"> +<pre class="smallexample">gcc `pkg-config --cflags libconfig` myprogram.c -o myprogram \ + `pkg-config --libs libconfig` +</pre></div> +<br> + +<p>And similarly, for C++ programs: +</p> +<div class="smallexample"> +<pre class="smallexample">g++ `pkg-config --cflags libconfig++` myprogram.cpp -o myprogram \ + `pkg-config --libs libconfig++` +</pre></div> + +<br> +<p>Note the backticks in the above examples. +</p> +<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: +</p> +<div class="smallexample"> +<pre class="smallexample">PKG_CHECK_MODULES([LIBCONFIGXX], [libconfig++ >= 1.4],, + AC_MSG_ERROR([libconfig++ 1.4 or newer not found.]) +) +</pre></div> + +<p>In the above example, if <i>libconfig++</i> version 1.4 or newer is found, +the Makefile variables <code>LIBCONFIGXX_LIBS</code> and <code>LIBCONFIGXX_CFLAGS</code> will be +set to the appropriate compiler and linker flags for compiling with +<i>libconfig</i>, and if it is not found, the configure script will abort +with an error to that effect. +</p> +<hr> +<a name="Version-Test-Macros"></a> +<div class="header"> +<p> +Previous: <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> +</div> +<a name="Version-Test-Macros-1"></a> +<h3 class="section">1.7 Version Test Macros</h3> + +<p>The <samp>libconfig.h</samp> header declares the following macros: +</p> +<dl> +<dt><a name="index-LIBCONFIG_005fVER_005fMAJOR"></a>Macro: <strong>LIBCONFIG_VER_MAJOR</strong></dt> +<dt><a name="index-LIBCONFIG_005fVER_005fMINOR"></a>Macro: <strong>LIBCONFIG_VER_MINOR</strong></dt> +<dt><a name="index-LIBCONFIG_005fVER_005fREVISION"></a>Macro: <strong>LIBCONFIG_VER_REVISION</strong></dt> +<dd> +<p>These macros represent the major version, minor version, and revision +of the <i>libconfig</i> library. For example, in <i>libconfig</i> 1.4 these +are defined as ‘<samp>1</samp>’, ‘<samp>4</samp>’, and ‘<samp>0</samp>’, respectively. These +macros can be used in preprocessor directives to determine which +<i>libconfig</i> features and/or APIs are present. For example: +</p> +<div class="smallexample"> +<pre class="smallexample">#if (((LIBCONFIG_VER_MAJOR == 1) && (LIBCONFIG_VER_MINOR >= 4)) \ + || (LIBCONFIG_VER_MAJOR > 1)) + /* use features present in libconfig 1.4 and later */ +#endif +</pre></div> + +<p>These macros were introduced in <i>libconfig</i> 1.4. +</p> +</dd></dl> + +<p>Similarly, the <samp>libconfig.h++</samp> header declares the following macros: +</p> +<dl> +<dt><a name="index-LIBCONFIGXX_005fVER_005fMAJOR"></a>Macro: <strong>LIBCONFIGXX_VER_MAJOR</strong></dt> +<dt><a name="index-LIBCONFIGXX_005fVER_005fMINOR"></a>Macro: <strong>LIBCONFIGXX_VER_MINOR</strong></dt> +<dt><a name="index-LIBCONFIGXX_005fVER_005fREVISION"></a>Macro: <strong>LIBCONFIGXX_VER_REVISION</strong></dt> +<dd> +<p>These macros represent the major version, minor version, and revision +of the <i>libconfig++</i> library. +</p> +</dd></dl> + +<hr> +<a name="Configuration-Files"></a> +<div class="header"> +<p> +Next: <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> +</div> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Settings" accesskey="1">Settings</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="#Groups" accesskey="2">Groups</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="#Arrays" accesskey="3">Arrays</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="#Lists" accesskey="4">Lists</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="#Integer-Values" accesskey="5">Integer Values</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<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"> +</td></tr> +<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"> +</td></tr> +<tr><td align="left" valign="top">• <a href="#Boolean-Values" accesskey="8">Boolean Values</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="#String-Values" accesskey="9">String Values</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="#Comments">Comments</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="#Include-Directives">Include Directives</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +</table> +<a name="Configuration-Files-1"></a> +<h2 class="chapter">2 Configuration Files</h2> + +<p><i>Libconfig</i> supports structured, hierarchical configurations. These +configurations can be read from and written to files and manipulated +in memory. +</p> +<a name="index-setting"></a> +<a name="index-value"></a> +<a name="index-scalar-value"></a> +<a name="index-array"></a> +<a name="index-group"></a> +<a name="index-list"></a> +<a name="index-configuration"></a> +<p>A <em>configuration</em> consists of a group of <em>settings</em>, which +associate names with values. A <em>value</em> can be one of the +following: +</p> +<ul> +<li> A <em>scalar value</em>: integer, 64-bit integer, floating-point number, boolean, +or string +</li><li> An <em>array</em>, which is a sequence of scalar values, all of which must have the same type +</li><li> A <em>group</em>, which is a collection of settings +</li><li> A <em>list</em>, which is a sequence of values of any type, including other lists +</li></ul> + +<p>Consider the following configuration file for a hypothetical GUI +application, which illustrates all of the elements of the configuration +file grammar. +</p> +<br> +<table class="cartouche" border="1"><tr><td> +<div class="smallexample"> +<pre class="smallexample"># Example application configuration file + +version = "1.0"; + +application: +{ + window: + { + title = "My Application"; + size = { w = 640; h = 480; }; + pos = { x = 350; y = 250; }; + }; + + list = ( ( "abc", 123, true ), 1.234, ( /* an empty list */ ) ); + + books = ( { title = "Treasure Island"; + author = "Robert Louis Stevenson"; + price = 29.95; + qty = 5; }, + { title = "Snow Crash"; + author = "Neal Stephenson"; + price = 9.99; + qty = 8; } ); + + misc: + { + pi = 3.141592654; + bigint = 9223372036854775807L; + columns = [ "Last Name", "First Name", "MI" ]; + bitmask = 0x1FC3; // hex + umask = 0027; // octal. Range limited to that of "int" + }; +}; +</pre></div> +</td></tr></table> +<br> + +<a name="index-path"></a> +<p>Settings can be uniquely identified within the configuration by a +<em>path</em>. The path is a dot-separated sequence of names, beginning +at a top-level group and ending at the setting itself. Each name in +the path is the name of a setting; if the setting has no name because +it is an element in a list or array, an integer index in square +brackets can be used as the name. +</p> +<p>For example, in our hypothetical configuration file, the path to the +<code>x</code> setting is <code>application.window.pos.x</code>; the path to the +<code>version</code> setting is simply <code>version</code>; and the path to the +<code>title</code> setting of the second book in the <code>books</code> list is +<code>application.books.[1].title</code>. +</p> +<p>The datatype of a value is determined from the format of the value +itself. If the value is enclosed in double quotes, it is treated as a +string. If it looks like an integer or floating point number, it is +treated as such. If it is one of the values <code>TRUE</code>, <code>true</code>, +<code>FALSE</code>, or <code>false</code> (or any other mixed-case version of +those tokens, e.g., <code>True</code> or <code>FaLsE</code>), it is treated as a +boolean. If it consists of a comma-separated list of values enclosed +in square brackets, it is treated as an array. And if it consists of a +comma-separated list of values enclosed in parentheses, it is treated +as a list. Any value which does not meet any of these criteria is +considered invalid and results in a parse error. +</p> +<p>All names are case-sensitive. They may consist only of alphanumeric +characters, dashes (‘<samp>-</samp>’), underscores (‘<samp>_</samp>’), and asterisks +(‘<samp>*</samp>’), and must begin with a letter or asterisk. No other +characters are allowed. +</p> +<p>In C and C++, integer, 64-bit integer, floating point, and string +values are mapped to the native types <code>int</code>, <code>long long</code>, +<code>double</code>, and <code>const char *</code>, respectively. The boolean type +is mapped to <code>int</code> in C and <code>bool</code> in C++. +</p> +<p>The following sections describe the elements of the configuration file +grammar in additional detail. +</p> +<hr> +<a name="Settings"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="Settings-1"></a> +<h3 class="section">2.1 Settings</h3> + +<p>A setting has the form: +</p> +<p><i>name</i> <b>=</b> <i>value</i> <b>;</b> +</p> +<p>or: +</p> +<p><i>name</i> <b>:</b> <i>value</i> <b>;</b> +</p> +<p>The trailing semicolon is optional. Whitespace is not significant. +</p> +<p>The value may be a scalar value, an array, a group, or a list. +</p> +<hr> +<a name="Groups"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="Groups-1"></a> +<h3 class="section">2.2 Groups</h3> + +<p>A group has the form: +</p> +<p><b>{</b> + <i>settings ...</i> +<b>}</b> +</p> +<p>Groups can contain any number of settings, but each setting must have +a unique name within the group. +</p> +<hr> +<a name="Arrays"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="Arrays-1"></a> +<h3 class="section">2.3 Arrays</h3> + +<p>An array has the form: +</p> +<p><b>[</b> <i>value</i><b>,</b> <i>value ...</i> <b>]</b> +</p> +<p>An array may have zero or more elements, but the elements must all be +scalar values of the same type. +</p> +<p>The last element in an array may be followed by a comma, which will be ignored. +</p> +<hr> +<a name="Lists"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="Lists-1"></a> +<h3 class="section">2.4 Lists</h3> + +<p>A list has the form: +</p> +<p><b>(</b> <i>value</i><b>,</b> <i>value ...</i> <b>)</b> +</p> +<p>A list may have zero or more elements, each of which can be a scalar +value, an array, a group, or another list. +</p> +<p>The last element in a list may be followed by a comma, which will be ignored. +</p> +<hr> +<a name="Integer-Values"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="Integer-Values-1"></a> +<h3 class="section">2.5 Integer Values</h3> + +<p>Integers can be represented in one of two ways: as a series of one or +more decimal digits (‘<samp>0</samp>’ - ‘<samp>9</samp>’), with an optional leading +sign character (‘<samp>+</samp>’ or ‘<samp>-</samp>’); or as a hexadecimal value +consisting of the characters ‘<samp>0x</samp>’ followed by a series of one or +more hexadecimal digits (‘<samp>0</samp>’ - ‘<samp>9</samp>’, ‘<samp>A</samp>’ - ‘<samp>F</samp>’, +‘<samp>a</samp>’ - ‘<samp>f</samp>’). Additionally, octal notation integers (that is, +those having a leading zero with non-zero value) are also allowed. +</p> +<hr> +<a name="g_t64_002dbit-Integer-Values"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="g_t64_002dbit-Integer-Values-1"></a> +<h3 class="section">2.6 64-bit Integer Values</h3> + +<p>Long long (64-bit) integers are represented identically to integers, +except that an ‘L’ character is appended to indicate a 64-bit +value. For example, ‘<samp>0L</samp>’ indicates a 64-bit integer value 0. As +of version 1.5 of the library, the trailing ‘L’ is optional; if the +integer value exceeds the range of a 32-bit integer, it will +automatically be interpreted as a 64-bit integer. +</p> +<p>The <i>integer</i> and <i>64-bit integer</i> setting types are interchangeable to the +extent that a conversion between the corresponding native types would not +result in an overflow or underflow. For example, a <i>long long</i> value can be +written to a setting that has an <i>integer</i> type, if that value is within the +range of an <i>int</i>. This rule applies to every API function or method that +reads a value from or writes a value to a setting: if the type conversion would +not result in an overflow or underflow, then the call will succeed, and +otherwise it will fail. This behavior was not well-defined prior to version 1.7 +of the library. +</p> +<hr> +<a name="Floating-Point-Values"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="Floating-Point-Values-1"></a> +<h3 class="section">2.7 Floating Point Values</h3> + +<p>Floating point values consist of a series of one or more digits, one +decimal point, an optional leading sign character (‘<samp>+</samp>’ or +‘<samp>-</samp>’), and an optional exponent. An exponent consists of the +letter ‘<samp>E</samp>’ or ‘<samp>e</samp>’, an optional sign character, and a series +of one or more digits. +</p> +<hr> +<a name="Boolean-Values"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="Boolean-Values-1"></a> +<h3 class="section">2.8 Boolean Values</h3> + +<p>Boolean values may have one of the following values: ‘<samp>true</samp>’, +‘<samp>false</samp>’, or any mixed-case variation thereof. +</p> +<hr> +<a name="String-Values"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="String-Values-1"></a> +<h3 class="section">2.9 String Values</h3> + +<a name="index-escape-sequence"></a> +<p>String values consist of arbitrary text delimited by double +quotes. Literal double quotes can be escaped by preceding them with a +backslash: ‘<samp>\"</samp>’. The escape sequences ‘<samp>\\</samp>’, ‘<samp>\f</samp>’, +‘<samp>\n</samp>’, ‘<samp>\r</samp>’, and ‘<samp>\t</samp>’ are also recognized, and have the +usual meaning. +</p> +<p>In addition, the ‘<samp>\x</samp>’ escape sequence is supported; this sequence +must be followed by <i>exactly two</i> hexadecimal digits, which represent an +8-bit ASCII value. For example, ‘<samp>\xFF</samp>’ represents the character +with ASCII code 0xFF. +</p> +<p>No other escape sequences are currently supported. +</p> +<p>Adjacent strings are automatically concatenated, as in C/C++ source +code. This is useful for formatting very long strings as sequences of +shorter strings. For example, the following constructs are equivalent: +</p> +<ul> +<li> <code>"The quick brown fox jumped over the lazy dog."</code> + +</li><li> <code>"The quick brown fox"</code> <br> +<code>" jumped over the lazy dog."</code> + +</li><li> <code>"The quick" /* comment */ " brown fox " // another comment</code> <br> +<code>"jumped over the lazy dog."</code> + +</li></ul> +<hr> +<a name="Comments"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="Comments-1"></a> +<h3 class="section">2.10 Comments</h3> + +<a name="index-comment"></a> +<p>Three types of comments are allowed within a configuration: +</p> +<ul> +<li> Script-style comments. All text beginning with a ‘<samp>#</samp>’ character +to the end of the line is ignored. + +</li><li> C-style comments. All text, including line breaks, between a starting +‘<samp>/*</samp>’ sequence and an ending ‘<samp>*/</samp>’ sequence is ignored. + +</li><li> C++-style comments. All text beginning with a ‘<samp>//</samp>’ sequence to the +end of the line is ignored. + +</li></ul> + +<p>As expected, comment delimiters appearing within quoted strings are +treated as literal text. +</p> +<p>Comments are ignored when the configuration is read in, so they are +not treated as part of the configuration. Therefore if the +configuration is written back out to a stream, any comments that were +present in the original configuration will be lost. +</p> + +<hr> +<a name="Include-Directives"></a> +<div class="header"> +<p> +Previous: <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> +</div> +<a name="Include-Directives-1"></a> +<h3 class="section">2.11 Include Directives</h3> + +<a name="index-include-directive"></a> +<p>A configuration file may “include” the contents of other files +using an <i>include directive</i>. This directive has the effect of +inlining the contents of the named file(s) at the point of inclusion. +</p> +<p>An include directive must appear on its own line in the input. It has +the form: +</p> +<p><b>@include "</b><i>path</i><b>"</b> +</p> +<a name="index-include-function"></a> +<p>The interpretation of <i>path</i> depends on the currently registered +<i>include function</i>. The default include function prepends the include +directory, if any, to <i>path</i>, and then interprets the result as a single, +literal file path. The application may supply its own include function which +does variable substitution, wildcard expansion, or other transformations, +returning a list of zero or more paths to files whose contents should be inlined +at the point of inclusion. +</p> +<p>Any backslashes or double quotes in the path must be escaped as +‘<samp>\\</samp>’ and ‘<samp>\"</samp>’, respectively. +</p> +<p>For example, consider the following two configuration files: +</p> +<table class="cartouche" border="1"><tr><td> +<div class="smallexample"> +<pre class="smallexample"># file: quote.cfg +quote = "Criticism may not be agreeable, but it is necessary." + " It fulfils the same function as pain in the human" + " body. It calls attention to an unhealthy state of" + " things.\n" + "\t--Winston Churchill"; +</pre></div> +</td></tr></table> + +<table class="cartouche" border="1"><tr><td> +<div class="smallexample"> +<pre class="smallexample"># file: test.cfg +info: { + name = "Winston Churchill"; + @include "quote.cfg" + country = "UK"; +}; +</pre></div> +</td></tr></table> + +<p>The resulting configuration will be equivalent to one in which the +contents of the file ‘<samp>quote.cfg</samp>’ appeared at the point where the +include directive is placed. +</p> +<p>Include files may be nested to a maximum of 10 levels; exceeding this +limit results in a parse error. +</p> +<p>When the path argument to an <b>@include</b> directive is a relative +path, then it will be interpreted as being relative to the include +directory that has been been set by means of +<code>config_set_include_dir()</code>. If no include directory has been set, +then it will be taken as being relative to the program’s current +working directory. +</p> +<p>Like comments, include directives are not part of the configuration +file syntax. They are processed before the configuration itself is +parsed. Therefore, they are not preserved when the configuration is +written back out to a stream. There is presently no support for +programmatically inserting include directives into a configuration. +</p> +<hr> +<a name="The-C-API"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="The-C-API-1"></a> +<h2 class="chapter">3 The C API</h2> + +<a name="index-config_005ft"></a> +<a name="index-config_005fsetting_005ft"></a> +<p>This chapter describes the C library API. The type <i>config_t</i> +represents a configuration, and the type <i>config_setting_t</i> represents +a configuration setting. +</p> +<p>The boolean values <code>CONFIG_TRUE</code> and <code>CONFIG_FALSE</code> are +macros defined as <code>(1)</code> and <code>(0)</code>, respectively. +</p> +<dl> +<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> +<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> +<dd> +<p>These functions initialize and destroy the configuration object <var>config</var>. +</p> +<p><code>config_init()</code> initializes the <i>config_t</i> structure pointed to by +<var>config</var> as a new, empty configuration. +</p> +<p><code>config_destroy()</code> destroys the configuration <var>config</var>, +deallocating all memory associated with the configuration, but does not +attempt to deallocate the <i>config_t</i> structure itself. +</p> +</dd></dl> + +<dl> +<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> +<dd> +<p><b>Since <i>v1.7</i></b> +</p> +<p>This function clears the configuration <var>config</var>. All child settings of the +root setting are recursively destroyed. All other attributes of the configuration +are left unchanged. +</p> +</dd></dl> + +<dl> +<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> +<dd> +<p>This function reads and parses a configuration from the given +<var>stream</var> into the configuration object <var>config</var>. It returns +<code>CONFIG_TRUE</code> on success, or <code>CONFIG_FALSE</code> on failure; the +<code>config_error_text()</code>, <code>config_error_file()</code>, +<code>config_error_line()</code>, and <code>config_error_type()</code> functions, +described below, can be used to obtain information about the error. +</p> +</dd></dl> + +<dl> +<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> +<dd> +<p>This function reads and parses a configuration from the file named +<var>filename</var> into the configuration object <var>config</var>. It returns +<code>CONFIG_TRUE</code> on success, or <code>CONFIG_FALSE</code> on failure; the +<code>config_error_text()</code> and <code>config_error_line()</code> functions, +described below, can be used to obtain information about the error. +</p> +</dd></dl> + +<dl> +<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> +<dd> +<p>This function reads and parses a configuration from the string +<var>str</var> into the configuration object <var>config</var>. It returns +<code>CONFIG_TRUE</code> on success, or <code>CONFIG_FALSE</code> on failure; the +<code>config_error_text()</code> and <code>config_error_line()</code> functions, +described below, can be used to obtain information about the error. +</p> +</dd></dl> + +<dl> +<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> +<dd> +<p>This function writes the configuration <var>config</var> to the given +<var>stream</var>. +</p> +</dd></dl> + +<dl> +<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> +<dd> +<p>This function writes the configuration <var>config</var> to the file named +<var>filename</var>. It returns <code>CONFIG_TRUE</code> on success, or +<code>CONFIG_FALSE</code> on failure. +</p> +</dd></dl> + +<dl> +<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> +<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> +<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> +<dd> +<p>These functions, which are implemented as macros, return the text, +filename, and line number of the parse error, if one occurred during a +call to <code>config_read()</code>, <code>config_read_string()</code>, or +<code>config_read_file()</code>. Storage for the strings returned by +<code>config_error_text()</code> and <code>config_error_file()</code> are managed +by the library and released automatically when the configuration is +destroyed; these strings must not be freed by the caller. If the error +occurred in text that was read from a string or stream, +<code>config_error_file()</code> will return NULL. +</p> +</dd></dl> + +<dl> +<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> +<dd><a name="index-config_005ferror_005ft"></a> +<p>This function, which is implemented as a macro, returns the type of +error that occurred during the last call to one of the read or write +functions. The <var>config_error_t</var> type is an enumeration with the +following values: <code>CONFIG_ERR_NONE</code>, <code>CONFIG_ERR_FILE_IO</code>, +<code>CONFIG_ERR_PARSE</code>. These represent success, a file I/O error, +and a parsing error, respectively. +</p> +</dd></dl> + +<dl> +<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> +<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> +<dd> +<p><code>config_set_include_dir()</code> specifies the include directory, +<var>include_dir</var>, relative to which the files specified in +‘<samp>@include</samp>’ directives will be located for the configuration +<var>config</var>. By default, there is no include directory, and all +include files are expected to be relative to the current working +directory. If <var>include_dir</var> is <code>NULL</code>, the default behavior +is reinstated. +</p> +<p>For example, if the include directory is set to <samp>/usr/local/etc</samp>, +the include directive ‘<samp>@include "configs/extra.cfg"</samp>’ would include the +file <samp>/usr/local/etc/configs/extra.cfg</samp>. +</p> +<p><code>config_get_include_dir()</code> returns the current include directory for the +configuration <var>config</var>, or <code>NULL</code> if none is set. +</p> +</dd></dl> + +<dl> +<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> +<dd> +<p><b>Since <i>v1.7</i></b> +</p> +<p>Specifies the include function <var>func</var> to use when processing +include directives. If <var>func</var> is <code>NULL</code>, the default include function, +<code>config_default_include_func()</code>, will be reinstated. +</p> +<a name="index-config_005finclude_005ffn_005ft"></a> +<p>The type <i>config_include_fn_t</i> is a type alias +for a function whose signature is: +</p> +<dl> +<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> +<dd> +<p>The function receives the configuration <var>config</var>, the +configuration’s current include directory <var>include_dir</var>, the +argument to the include directive <var>path</var>; and a pointer at which +to return an error message <var>error</var>. +</p> +<p>On success, the function should return a <code>NULL</code>-terminated array +of paths. Any relative paths must be relative to the program’s current +working directory. The contents of these files will be inlined at the point +of inclusion, in the order that the paths appear in the +array. Both the array and its elements should be heap allocated; the +library will take ownership of and eventually free the strings in the +array and the array itself. +</p> +<p>On failure, the function should return <code>NULL</code> and set <var>*error</var> to a +static error string which should be used as the parse error for the +configuration; the library does not take ownership of or free this string. +</p> +<p>The default include function, <code>config_default_include_func()</code>, +simply returns a <code>NULL</code>-terminated array containing either a copy +of <var>path</var> if it’s an absolute path, or a concatenation of +<var>include_dir</var> and <var>path</var> if it’s a relative path. +</p> +</dd></dl> + +<p>Application-supplied include functions can perform custom tasks like wildcard +expansion or variable substitution. For example, consider the include directive: +</p> +<table class="cartouche" border="1"><tr><td> +<div class="smallexample"> +<pre class="smallexample">@include "configs/*.cfg" +</pre></div> +</td></tr></table> + +<p>The include function would be invoked with the path ‘<samp>configs/*.cfg</samp>’ and +could do wildcard expansion on that path, returning a list of paths to files +with the file extension ‘<samp>.cfg</samp>’ in the subdirectory ‘<samp>configs</samp>’. Each of +these files would then be inlined at the location of the include directive. +</p> +<p>Tasks like wildcard expansion and variable substitution are non-trivial to +implement and typically require platform-specific code. In the interests of +keeping the library as compact and platform-independent as possible, +implementations of such include functions are not included. +</p> +</dd></dl> + +<dl> +<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> +<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> +<dd> +<p><b>Since <i>v1.6</i></b> +</p> +<p>These functions get and set the number of decimal digits to output after the +radix character when writing the configuration to a file or stream. +</p> +<p>Valid values for <var>digits</var> range from 0 (no decimals) to about 15 +(implementation defined). This parameter has no effect on parsing. +</p> +<p>The default float precision is 6. +</p> +</dd></dl> + +<dl> +<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> +<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> +<dd> +<p>These functions get and set the options for the configuration +<var>config</var>. The options affect how configurations are read and +written. The following options are defined: +</p> +<dl compact="compact"> +<dt><code>CONFIG_OPTION_AUTOCONVERT</code></dt> +<dd><p>Turning this option on enables number auto-conversion for +the configuration. When this feature is enabled, an attempt to retrieve a +floating point setting’s value into an integer (or vice versa), or +store an integer to a floating point setting’s value (or vice versa) +will cause the library to silently perform the necessary conversion +(possibly leading to loss of data), rather than reporting failure. By +default this option is turned off. +</p> +</dd> +<dt><code>CONFIG_OPTION_SEMICOLON_SEPARATORS</code></dt> +<dd><p>This option controls whether a semicolon (‘;’) is output after each setting +when the configuration is written to a file or stream. (The semicolon +separators are optional in the configuration syntax.) By default this +option is turned on. +</p> +</dd> +<dt><code>CONFIG_OPTION_COLON_ASSIGNMENT_FOR_GROUPS</code></dt> +<dd><p>This option controls whether a colon (‘:’) is output between each +group setting’s name and its value when the configuration is written to +a file or stream. If the option is turned off, an equals sign (‘=’) is +output instead. (These tokens are interchangeable in the configuration +syntax.) By default this option is turned on. +</p> +</dd> +<dt><code>CONFIG_OPTION_COLON_ASSIGNMENT_FOR_NON_GROUPS</code></dt> +<dd><p>This option controls whether a colon (‘:’) is output between each +non-group setting’s name and its value when the configuration is written +to a file or stream. If the option is turned off, an equals sign (‘=’) +is output instead. (These tokens are interchangeable in the configuration +syntax.) By default this option is turned off. +</p> +</dd> +<dt><code>CONFIG_OPTION_OPEN_BRACE_ON_SEPARATE_LINE</code></dt> +<dd><p>This option controls whether an open brace (‘{’) will be written on its own +line when the configuration is written to a file or stream. If the option is +turned off, the brace will be written at the end of the previous line. +By default this option is turned on. +</p> +</dd> +<dt><code>CONFIG_OPTION_ALLOW_SCIENTIFIC_NOTATION</code></dt> +<dd><p>(<b>Since <i>v1.7</i></b>) +This option controls whether scientific notation may be used as appropriate +when writing floating point values (corresponding to <code>printf()</code> +‘<samp>%g</samp>’ format) or should never be used (corresponding to <code>printf()</code> +‘<samp>%f</samp>’ format). By default this option is turned off. +</p> +</dd> +<dt><code>CONFIG_OPTION_FSYNC</code></dt> +<dd><p>(<b>Since <i>v1.7.1</i></b>) +This option controls whether the <code>config_write_file()</code> function performs +an <i>fsync</i> operation after writing the configuration and before closing the +file. By default this option is turned off. +</p></dd> +</dl> + +</dd></dl> + +<dl> +<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> +<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> +<dd> +<p><b>Since <i>v1.7</i></b> +</p> +<p>These functions get and set the given <var>option</var> of the configuration +<var>config</var>. The option is enabled if <var>flag</var> is <code>CONFIG_TRUE</code> and +disabled if it is <code>CONFIG_FALSE</code>. +</p> +<p>See <code>config_set_options()</code> above for the list of available options. +</p> +</dd></dl> + + +<dl> +<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> +<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> +<dd> +<p>These functions get and set the <code>CONFIG_OPTION_AUTO_CONVERT</code> +option. They are obsoleted by the <code>config_set_option()</code> and +<code>config_get_option()</code> functions described above. +</p> +</dd></dl> + +<dl> +<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> +<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> +<dd> +<p>These functions, which are implemented as macros, get and set the +default external format for settings in the configuration +<var>config</var>. If a non-default format has not been set for a setting +with <code>config_setting_set_format()</code>, this configuration-wide +default format will be used instead when that setting is written to a +file or stream. +</p> +</dd></dl> + +<dl> +<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> +<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> +<dd> +<p>These functions, which are implemented as macros, get and set the tab +width for the configuration <var>config</var>. The tab width affects the +formatting of the configuration when it is written to a file or +stream: each level of nesting is indented by <var>width</var> spaces, or +by a single tab character if <var>width</var> is 0. The tab width has no +effect on parsing. +</p> +<p>Valid tab widths range from 0 to 15. The default tab width is 2. +</p> +</dd></dl> + +<dl> +<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> +<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> +<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> +<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> +<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> +<dd> +<p>These functions look up the value of the setting in the configuration +<var>config</var> specified by the path <var>path</var>. They store the value of +the setting at <var>value</var> and return <code>CONFIG_TRUE</code> on +success. If the setting was not found or if the type of the value did +not match the type requested, they leave the data pointed to by +<var>value</var> unmodified and return <code>CONFIG_FALSE</code>. +</p> +<p>Storage for the string returned by <code>config_lookup_string()</code> is +managed by the library and released automatically when the setting is +destroyed or when the setting’s value is changed; the string must not +be freed by the caller. +</p> +</dd></dl> + +<dl> +<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> +<dd> +<p>This function locates the setting in the configuration <var>config</var> +specified by the path <var>path</var>. It returns a pointer to the +<code>config_setting_t</code> structure on success, or <code>NULL</code> if the +setting was not found. +</p> +</dd></dl> + +<dl> +<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> +<dd> +<p>This function locates a setting by a path <var>path</var> relative to +the setting <var>setting</var>. It returns a pointer to the +<code>config_setting_t</code> structure on success, or <code>NULL</code> if the +setting was not found. +</p> +</dd></dl> + +<dl> +<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> +<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> +<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> +<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> +<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> +<dd> +<p>These functions return the value of the given <var>setting</var>. If the +type of the setting does not match the type requested, a 0 or +<code>NULL</code> value is returned. Storage for the string returned by +<code>config_setting_get_string()</code> is managed by the library and +released automatically when the setting is destroyed or when the +setting’s value is changed; the string must not be freed by the +caller. +</p> +</dd></dl> +<dl> +<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> +<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> +<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> +<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> +<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> +<dd> +<p>These functions set the value of the given <var>setting</var> to +<var>value</var>. On success, they return <code>CONFIG_TRUE</code>. If +the setting does not match the type of the value, they return +<code>CONFIG_FALSE</code>. <code>config_setting_set_string()</code> makes a copy +of the passed string <var>value</var>, so it may be subsequently freed or +modified by the caller without affecting the value of the setting. +</p> +</dd></dl> + +<dl> +<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> +<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> +<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> +<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> +<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> +<dd> +<p>These functions look up the value of the child setting named +<var>name</var> of the setting <var>setting</var>. They store the value at +<var>value</var> and return <code>CONFIG_TRUE</code> on success. If the setting +was not found or if the type of the value did not match the type +requested, they leave the data pointed to by <var>value</var> unmodified +and return <code>CONFIG_FALSE</code>. +</p> +<p>Storage for the string returned by <code>config_setting_lookup_string()</code> is +managed by the library and released automatically when the setting is +destroyed or when the setting’s value is changed; the string must not +be freed by the caller. +</p> +</dd></dl> + +<dl> +<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> +<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> +<dd> +<p>These functions get and set the external format for the setting <var>setting</var>. +</p> +<a name="index-SettingFormat"></a> +<a name="index-format"></a> + +<p>The <var>format</var> must be one of the constants +<code>CONFIG_FORMAT_DEFAULT</code> or <code>CONFIG_FORMAT_HEX</code>. All settings +support the <code>CONFIG_FORMAT_DEFAULT</code> format. The +<code>CONFIG_FORMAT_HEX</code> format specifies hexadecimal formatting for +integer values, and hence only applies to settings of type +<code>CONFIG_TYPE_INT</code> and <code>CONFIG_TYPE_INT64</code>. If <var>format</var> +is invalid for the given setting, it is ignored. +</p> +<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>. +</p> +<p><code>config_setting_set_format()</code> returns <code>CONFIG_TRUE</code> on +success and <code>CONFIG_FALSE</code> on failure. +</p> +</dd></dl> + + +<dl> +<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> +<dd> +<p>This function fetches the child setting named <var>name</var> from the group +<var>setting</var>. It returns the requested setting on success, or +<code>NULL</code> if the setting was not found or if <var>setting</var> is not a +group. +</p> +</dd></dl> + +<dl> +<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> +<dd> +<p>This function fetches the element at the given index <var>index</var> in the +setting <var>setting</var>, which must be an array, list, or group. It returns the +requested setting on success, or <code>NULL</code> if <var>index</var> is out of +range or if <var>setting</var> is not an array, list, or group. +</p> +</dd></dl> + +<dl> +<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> +<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> +<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> +<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> +<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> +<dd> +<p>These functions return the value at the specified index <var>index</var> in the +setting <var>setting</var>. If the setting is not an array or list, or if +the type of the element does not match the type requested, or if +<var>index</var> is out of range, they return 0 or <code>NULL</code>. Storage for +the string returned by <code>config_setting_get_string_elem()</code> is +managed by the library and released automatically when the setting is +destroyed or when its value is changed; the string must not be freed +by the caller. +</p></dd></dl> + +<dl> +<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> +<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> +<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> +<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> +<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> +<dd> +<p>These functions set the value at the specified index <var>index</var> in the +setting <var>setting</var> to <var>value</var>. If <var>index</var> is negative, a +new element is added to the end of the array or list. On success, +these functions return a pointer to the setting representing the +element. If the setting is not an array or list, or if the setting is +an array and the type of the array does not match the type of the +value, or if <var>index</var> is out of range, they return +<code>NULL</code>. <code>config_setting_set_string_elem()</code> makes a copy of +the passed string <var>value</var>, so it may be subsequently freed or +modified by the caller without affecting the value of the setting. +</p></dd></dl> + +<dl> +<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> +<dd> +<p>This function adds a new child setting or element to the setting +<var>parent</var>, which must be a group, array, or list. If <var>parent</var> +is an array or list, the <var>name</var> parameter is ignored and may be +<code>NULL</code>. +</p> +<p>The function returns the new setting on success, or <code>NULL</code> if +<var>parent</var> is not a group, array, or list; or if there is already a +child setting of <var>parent</var> named <var>name</var>; or if <var>type</var> is +invalid. If <var>type</var> is a scalar type, the new setting will have a +default value of 0, 0.0, <code>false</code>, or <code>NULL</code>, as appropriate. +</p></dd></dl> + +<dl> +<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> +<dd> +<p>This function removes and destroys the setting named <var>name</var> from +the parent setting <var>parent</var>, which must be a group. Any child +settings of the setting are recursively destroyed as well. +</p> +<p>The <var>name</var> parameter can also specify a setting <i>path</i> relative to +the provided <var>parent</var>. +(In that case, the setting will be looked up and removed.) +</p> +<p>The function returns <code>CONFIG_TRUE</code> on success. If <var>parent</var> is +not a group, or if it has no setting with the given name, it returns +<code>CONFIG_FALSE</code>. +</p> +</dd></dl> + +<dl> +<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> +<dd> +<p>This function removes the child setting at the given index <var>index</var> from +the setting <var>parent</var>, which must be a group, list, or array. Any +child settings of the removed setting are recursively destroyed as +well. +</p> +<p>The function returns <code>CONFIG_TRUE</code> on success. If <var>parent</var> is +not a group, list, or array, or if <var>index</var> is out of range, it returns +<code>CONFIG_FALSE</code>. +</p> +</dd></dl> + +<dl> +<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> +<dd> +<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. +</p> +</dd></dl> + +<dl> +<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> +<dd> +<p>This function returns the name of the given <var>setting</var>, or +<code>NULL</code> if the setting has no name. Storage for the returned +string is managed by the library and released automatically when the +setting is destroyed; the string must not be freed by the caller. +</p> +</dd></dl> + +<dl> +<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> +<dd> +<p>This function returns the parent setting of the given <var>setting</var>, +or <code>NULL</code> if <var>setting</var> is the root setting. +</p> +</dd></dl> + +<dl> +<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> +<dd> +<p>This function returns <code>CONFIG_TRUE</code> if the given <var>setting</var> is +the root setting, and <code>CONFIG_FALSE</code> otherwise. +</p> +</dd></dl> + +<dl> +<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> +<dd> +<p>This function returns the index of the given <var>setting</var> within its +parent setting. If <var>setting</var> is the root setting, this function +returns -1. +</p> +</dd></dl> + +<dl> +<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> +<dd> +<p>This function returns the number of settings in a group, or the number of +elements in a list or array. For other types of settings, it returns +0. +</p> +</dd></dl> + +<dl> +<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> +<dd> +<p>This function returns the type of the given <var>setting</var>. The return +value is one of the constants +<code>CONFIG_TYPE_INT</code>, <code>CONFIG_TYPE_INT64</code>, <code>CONFIG_TYPE_FLOAT</code>, +<code>CONFIG_TYPE_STRING</code>, <code>CONFIG_TYPE_BOOL</code>, +<code>CONFIG_TYPE_ARRAY</code>, <code>CONFIG_TYPE_LIST</code>, or <code>CONFIG_TYPE_GROUP</code>. +</p> +</dd></dl> + +<dl> +<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> +<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> +<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> +<dd> +<p>These convenience functions, which are implemented as macros, test if +the setting <var>setting</var> is of a given type. They return +<code>CONFIG_TRUE</code> or <code>CONFIG_FALSE</code>. +</p> +</dd></dl> + +<dl> +<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> +<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> +<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> +<dd> +<a name="index-aggregate-value"></a> +<p>These convenience functions, some of which are implemented as macros, test if +the setting <var>setting</var> is of an aggregate type (a group, array, or +list), of a scalar type (integer, 64-bit integer, floating point, +boolean, or string), and of a number (integer, 64-bit integer, or +floating point), respectively. They return <code>CONFIG_TRUE</code> or +<code>CONFIG_FALSE</code>. +</p> +</dd></dl> + +<dl> +<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> +<dd> +<p>This function returns the name of the file from which the setting +<var>setting</var> was read, or NULL if the setting was not read from a +file. This information is useful for reporting application-level +errors. Storage for the returned string is managed by the library and +released automatically when the configuration is destroyed; the +string must not be freed by the caller. +</p> +</dd></dl> + +<dl> +<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> +<dd> +<p>This function returns the line number of the configuration file or +stream at which the setting <var>setting</var> was read, or 0 if no line +number is available. This information is useful for reporting +application-level errors. +</p> +</dd></dl> + +<dl> +<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> +<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> +<dd> +<p><b>Since <i>v1.7</i></b> +</p> +<a name="index-hook"></a> +<p>These functions make it possible to attach arbitrary data to a configuration +structure, for instance a “wrapper” or “peer” object written in +another programming language. +</p> +</dd></dl> + +<dl> +<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> +<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> +<dd> +<a name="index-hook-1"></a> +<p>These functions make it possible to attach arbitrary data to each +setting structure, for instance a “wrapper” or “peer” object written in +another programming language. The destructor function, if one has been +supplied via a call to <code>config_set_destructor()</code>, will be called +by the library to dispose of this data when the setting itself is +destroyed. There is no default destructor. +</p> +</dd></dl> + +<dl> +<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> +<dd> +<a name="index-destructor-function"></a> +<p>This function assigns the destructor function <var>destructor</var> for the +configuration <var>config</var>. This function accepts a single <code>void +*</code> argument and has no return value. See +<code>config_setting_set_hook()</code> above for more information. +</p> +</dd></dl> + +<hr> +<a name="The-C_002b_002b-API"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="The-C_002b_002b-API-1"></a> +<h2 class="chapter">4 The C++ API</h2> + +<a name="index-Config"></a> +<a name="index-Setting"></a> +<p>This chapter describes the C++ library API. The class <code>Config</code> +represents a configuration, and the class <code>Setting</code> represents a +configuration setting. Note that by design, neither of these classes +provides a public copy constructor or assignment operator. Therefore, +instances of these classes may only be passed between functions via +references or pointers. +</p> +<a name="index-ConfigException"></a> +<p>The library defines a group of exceptions, all of which extend the +common base exception <code>ConfigException</code>. +</p> +<a name="index-SettingTypeException"></a> +<p>A <code>SettingTypeException</code> is thrown when the type of a setting’s +value does not match the type requested. +</p> +<dl> +<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> +<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> +<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> +<dd> +<p>These methods construct <code>SettingTypeException</code> objects for the given <var>setting</var> and/or member <var>index</var> or <var>name</var>. +</p> +</dd></dl> + +<a name="index-SettingNotFoundException"></a> +<p>A <code>SettingNotFoundException</code> is thrown when a setting is not found. +</p> +<dl> +<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> +<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> +<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> +<dd> +<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>. +</p> +</dd></dl> + +<a name="index-SettingNameException"></a> +<p>A <code>SettingNameException</code> is thrown when an attempt is made to add +a new setting with a non-unique or invalid name. +</p> +<dl> +<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> +<dd> +<p>This method constructs a <code>SettingNameExcpetion</code> object for the given <var>setting</var> and member name <var>name</var>. +</p> +</dd></dl> + +<a name="index-ParseException"></a> +<p>A <code>ParseException</code> is thrown when a parse error occurs while +reading a configuration from a stream. +</p> +<dl> +<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> +<dd> +<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>. +</p> +</dd></dl> + +<a name="index-FileIOException"></a> +<p>A <code>FileIOException</code> is thrown when an I/O error occurs while +reading/writing a configuration from/to a file. +</p> +<a name="index-SettingException"></a> +<p><code>SettingTypeException</code>, <code>SettingNotFoundException</code>, and +<code>SettingNameException</code> all extend the common base +exception <code>SettingException</code>, which provides the following method: +</p> +<dl> +<dt><a name="index-getPath-on-SettingException"></a>Method on SettingException: <em>const char *</em> <strong>getPath</strong> <em>() const</em></dt> +<dd> +<p>This method returns the path to the setting associated with the exception, or +<code>NULL</code> if there is no applicable path. +</p> +</dd></dl> + +<p>The remainder of this chapter describes the methods for manipulating +configurations and configuration settings. +</p> +<dl> +<dt><a name="index-Config-on-Config"></a>Method on Config: <em></em> <strong>Config</strong> <em>()</em></dt> +<dt><a name="index-_007eConfig-on-Config"></a>Method on Config: <em></em> <strong>~Config</strong> <em>()</em></dt> +<dd> +<p>These methods create and destroy <code>Config</code> objects. +</p> +</dd></dl> + +<dl> +<dt><a name="index-clear-on-Config"></a>Method on Config: <em>void</em> <strong>clear</strong> <em>()</em></dt> +<dd> +<p><b>Since <i>v1.7</i></b> +</p> +<p>This method clears the configuration. All child settings of the root +setting are recursively destroyed. All other attributes of the +configuration are left unchanged. +</p> +</dd></dl> + +<dl> +<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> +<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> +<dd> +<p>The <code>read()</code> method reads and parses a configuration from the given +<var>stream</var>. A <code>ParseException</code> is thrown if a parse error occurs. +</p> +<p>The <code>write()</code> method writes the configuration to the given <var>stream</var>. +</p> +</dd></dl> + +<dl> +<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> +<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> +<dd> +<p>The <code>readFile()</code> method reads and parses a configuration from the +file named <var>filename</var>. A <code>ParseException</code> is thrown if a +parse error occurs. A <code>FileIOException</code> is thrown if the file +cannot be read. +</p> +<p>The <code>writeFile()</code> method writes the configuration to the file +named <var>filename</var>. A <code>FileIOException</code> is thrown if the file cannot +be written. +</p> +</dd></dl> + +<dl> +<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> +<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> +<dd> +<p>These methods read and parse a configuration from the string +<var>str</var>. A <code>ParseException</code> is thrown if a parse error occurs. +</p> +</dd></dl> + +<dl> +<dt><a name="index-getError-on-ParseException"></a>Method on ParseException: <em>const char *</em> <strong>getError</strong> <em>() const</em></dt> +<dt><a name="index-getFile-on-ParseException"></a>Method on ParseException: <em>const char *</em> <strong>getFile</strong> <em>() const</em></dt> +<dt><a name="index-getLine-on-ParseException"></a>Method on ParseException: <em>int</em> <strong>getLine</strong> <em>() const</em></dt> +<dd> +<p>If a call to <code>readFile()</code>, <code>readString()</code>, or <code>read()</code> +resulted in a <code>ParseException</code>, these methods can be called on +the exception object to obtain the text, filename, and line number of +the parse error. Storage for the strings returned by <code>getError()</code> +and <code>getFile()</code> are managed by the library; the strings must not +be freed by the caller. +</p> +</dd></dl> + +<dl> +<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> +<dt><a name="index-getIncludeDir-on-Config"></a>Method on Config: <em>const char *</em> <strong>getIncludeDir</strong> <em>() const</em></dt> +<dd> +<p>The <code>setIncludeDir()</code> method specifies the include directory, +<var>includeDir</var>, relative to which the files specified in +‘<samp>@include</samp>’ directives will be located for the configuration. By +default, there is no include directory, and all include files are +expected to be relative to the current working directory. If +<var>includeDir</var> is <code>NULL</code>, the default behavior is reinstated. +</p> +<p>For example, if the include directory is set to <samp>/usr/local/etc</samp>, +the include directive ‘<samp>@include "configs/extra.cfg"</samp>’ would include the +file <samp>/usr/local/etc/configs/extra.cfg</samp>. +</p> +<p><code>getIncludeDir()</code> returns the current include directory for the +configuration, or <code>NULL</code> if none is set. +</p> +</dd></dl> + +<dl> +<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> +<dd> +<p><b>Since <i>v1.7</i></b> +</p> +<p>This method is called to evaluate the path of an <code>@include</code> directive. +The <var>path</var> is the literal path argument of the directive. The method may +be overridden in a subclass to perform tasks like wildcard expansion and +variable substitution. +</p> +<p>On success, the method should return a <code>NULL</code>-terminated array of paths. +Any relative paths must be relative to the program’s current working directory. +The contents of these files will be inlined at the point of inclusion, in the +order that the paths appear in the array. Both the array and its elements should +be heap allocated; the library will take ownership of and eventually free the +strings in the array and the array itself. +</p> +<p>On failure, the function should return <code>NULL</code> and set <var>*error</var> to a +static error string which should be used as the parse error for the +configuration; the library does not take ownership of or free this string. +</p> +<p>The default implementation simply returns a <code>NULL</code>-terminated array +containing either a copy of <var>path</var> if it’s an absolute path, or a +concatenation of the include directory and <var>path</var> if it’s a relative path. +</p> +<p>For more information see <code>config_set_include_func()</code> above. +</p> +</dd></dl> + +<dl> +<dt><a name="index-getOptions-on-Config"></a>Method on Config: <em>int</em> <strong>getOptions</strong> <em>() const</em></dt> +<dt><a name="index-setOptions-on-Config"></a>Method on Config: <em>void</em> <strong>setOptions</strong> <em>(int <var>options</var>)</em></dt> +<dd> +<a name="index-Config_003a_003aOption"></a> +<p>These methods get and set the options for the configuration. The +options affect how configurations are read and written. The parameter +<var>options</var> should be a bitwise-OR of the following <var>Config::Option</var> +enumeration values: +</p> +<dl compact="compact"> +<dt><code>Config::OptionAutoConvert</code></dt> +<dd><p>Turning this option on enables number auto-conversion for +the configuration. When this feature is enabled, an attempt to retrieve a +floating point setting’s value into an integer (or vice versa), or +store an integer to a floating point setting’s value (or vice versa) +will cause the library to silently perform the necessary conversion +(possibly leading to loss of data), rather than reporting failure. By +default this option is turned off. +</p> +</dd> +<dt><code>Config::OptionSemicolonSeparators</code></dt> +<dd><p>This option controls whether a semicolon (‘;’) is output after each setting +when the configuration is written to a file or stream. (The semicolon +separators are optional in the configuration syntax.) By default this +option is turned on. +</p> +</dd> +<dt><code>Config::OptionColonAssignmentForGroups</code></dt> +<dd><p>This option controls whether a colon (‘:’) is output between each +group setting’s name and its value when the configuration is written to +a file or stream. If the option is turned off, an equals sign (‘=’) is +output instead. (These tokens are interchangeable in the configuration +syntax.) By default this option is turned on. +</p> +</dd> +<dt><code>Config::OptionColonAssignmentForNonGroups</code></dt> +<dd><p>This option controls whether a colon (‘:’) is output between each +non-group setting’s name and its value when the configuration is written +to a file or stream. If the option is turned off, an equals sign (‘=’) +is output instead. (These tokens are interchangeable in the configuration +syntax.) By default this option is turned off. +</p> +</dd> +<dt><code>Config::OptionOpenBraceOnSeparateLine</code></dt> +<dd><p>This option controls whether an open brace (‘{’) will be written on its own +line when the configuration is written to a file or stream. If the option is +turned off, the brace will be written at the end of the previous line. +By default this option is turned on. +</p> +</dd> +<dt><code>Config::OptionAllowScientificNotation</code></dt> +<dd><p>(<b>Since <i>v1.7</i></b>) +This option controls whether scientific notation may be used as appropriate +when writing floating point values (corresponding to <code>printf()</code> +‘<samp>%g</samp>’ format) or should never be used (corresponding to <code>printf()</code> +‘<samp>%f</samp>’ format). By default this option is turned off. +</p> +</dd> +<dt><code>Config::OptionFsync</code></dt> +<dd><p>(<b>Since <i>v1.7.1</i></b>) +This option controls whether the <code>writeFile()</code> method performs an <i>fsync</i> +operation after writing the configuration and before closing the file. By +default this option is turned off. +</p> +</dd> +</dl> + +</dd></dl> + +<dl> +<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> +<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> +<dd> +<p><b>Since <i>v1.7</i></b> +</p> +<p>These methods get and set the option <var>option</var> for the configuration. The +option is enabled if <var>flag</var> is <code>true</code> and disabled if it is +<code>false</code>. +</p> +<p>See <code>setOptions()</code> above for the list of available options. +</p> +</dd></dl> + +<dl> +<dt><a name="index-getAutoConvert-on-Config"></a>Method on Config: <em>bool</em> <strong>getAutoConvert</strong> <em>() const</em></dt> +<dt><a name="index-setAutoConvert-on-Config"></a>Method on Config: <em>void</em> <strong>setAutoConvert</strong> <em>(bool <var>flag</var>)</em></dt> +<dd> +<p>These methods get and set the <code>OptionAutoConvert</code> option. They +are obsoleted by the <code>setOption()</code> and <code>getOption()</code> +methods described above. +</p> +</dd></dl> + +<dl> +<dt><a name="index-getDefaultFormat-on-Config"></a>Method on Config: <em>Setting::Format</em> <strong>getDefaultFormat</strong> <em>() const</em></dt> +<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> +<dd> +<p>These methods get and set the default external format for settings in +the configuration. If a non-default format has not been set for a +setting with <code>Setting::setFormat()</code>, this configuration-wide +default format will be used instead when that setting is written to a +file or stream. +</p> +</dd></dl> + +<dl> +<dt><a name="index-getTabWidth-on-Config"></a>Method on Config: <em>unsigned short</em> <strong>getTabWidth</strong> <em>() const</em></dt> +<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> +<dd> +<p>These methods get and set the tab width for the configuration. The tab +width affects the formatting of the configuration when it is written +to a file or stream: each level of nesting is indented by <var>width</var> +spaces, or by a single tab character if <var>width</var> is 0. The tab +width has no effect on parsing. +</p> +<p>Valid tab widths range from 0 to 15. The default tab width is 2. +</p> +</dd></dl> + +<dl> +<dt><a name="index-getFloatPrecision-on-Config"></a>Method on Config: <em>unsigned short</em> <strong>getFloatPrecision</strong> <em>() const</em></dt> +<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> +<dd> +<p>These methods get and set the float precision for the configuration. +This parameter influences the formatting of floating point settings in +the configuration when it is written to a file or stream. +Float precision has no effect on parsing. +</p> +<p>Valid precisions range from 0 to about 15 (implementation dependent), +though the library will accept and store values up to 255. +</p> +</dd></dl> + +<dl> +<dt><a name="index-getRoot-on-Config"></a>Method on Config: <em>Setting &</em> <strong>getRoot</strong> <em>() const</em></dt> +<dd> +<p>This method returns the root setting for the configuration, which is a group. +</p> +</dd></dl> + +<dl> +<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> +<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> +<dd> +<p>These methods locate the setting specified by the path <var>path</var>. If +the requested setting is not found, a <code>SettingNotFoundException</code> is +thrown. +</p> +</dd></dl> +<dl> +<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> +<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> +<dd> +<p>These methods test if a setting with the given <var>path</var> exists in +the configuration. They return <code>true</code> if the setting exists, and +<code>false</code> otherwise. These methods do not throw exceptions. +</p> +</dd></dl> + +<dl> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<dd> +<p>These are convenience methods for looking up the value of a setting +with the given <var>path</var>. If the setting is found and is of an +appropriate type, the value is stored in <var>value</var> and the method +returns <code>true</code>. Otherwise, <var>value</var> is left unmodified and the +method returns <code>false</code>. These methods do not throw exceptions. +</p> +<p>Storage for <i>const char *</i><!-- /@w --> values is managed by the library and +released automatically when the setting is destroyed or when its value +is changed; the string must not be freed by the caller. For safety and +convenience, always assigning string values to a <code>std::string</code> is +suggested. +</p> +<p>Since these methods have boolean return values and do not throw +exceptions, they can be used within boolean logic expressions. The following +example presents a concise way to look up three values at once and +perform error handling if any of them are not found or are of the +wrong type: +</p> +<br> +<table class="cartouche" border="1"><tr><td> +<div class="smallexample"> +<pre class="smallexample">int var1; +double var2; +const char *var3; + +if(config.lookupValue("values.var1", var1) + && config.lookupValue("values.var2", var2) + && config.lookupValue("values.var3", var3)) +{ + // use var1, var2, var3 +} +else +{ + // error handling here +} +</pre></div> +</td></tr></table> + +<p>This approach also takes advantage of the short-circuit evaluation rules +of C++, e.g., if the first lookup fails (returning <code>false</code>), the +remaining lookups are skipped entirely. +</p> +</dd></dl> + +<dl> +<dt><a name="index-operator-bool-_0028_0029-on-Setting"></a>Method on Setting: <em></em> <strong>operator bool ()</strong> <em>const</em></dt> +<dt><a name="index-operator-int-_0028_0029-on-Setting"></a>Method on Setting: <em></em> <strong>operator int ()</strong> <em>const</em></dt> +<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> +<dt><a name="index-operator-long-_0028_0029-on-Setting"></a>Method on Setting: <em></em> <strong>operator long ()</strong> <em>const</em></dt> +<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> +<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> +<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> +<dt><a name="index-operator-float-_0028_0029-on-Setting"></a>Method on Setting: <em></em> <strong>operator float ()</strong> <em>const</em></dt> +<dt><a name="index-operator-double-_0028_0029-on-Setting"></a>Method on Setting: <em></em> <strong>operator double ()</strong> <em>const</em></dt> +<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> +<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> +<dt><a name="index-c_005fstr-on-Setting"></a>Method on Setting: <em>const char *</em> <strong>c_str</strong> <em>() const</em></dt> +<dd> +<p>These cast operators allow a <code>Setting</code> object to be assigned to a +variable of type <i>bool</i> if it is of type <code>TypeBoolean</code>; +<i>int</i>, <i>unsigned int</i>; <code>long long</code> or <code>unsigned long long</code> if +it is of type <code>TypeInt64</code>, <i>float</i> or <i>double</i> if it is of type +<code>TypeFloat</code>; or <i>const char *</i><!-- /@w --> or <i>std::string</i> if it is +of type <code>TypeString</code>. +</p> +<p>Values of type <code>TypeInt</code> or <code>TypeInt64</code> may be assigned to +variables of type <i>long</i>, or <i>unsigned long</i>, depending on the +sizes of those types on the host system. +</p> +<p>Storage for <i>const char *</i><!-- /@w --> return values is managed by the +library and released automatically when the setting is destroyed or +when its value is changed; the string must not be freed by the +caller. For safety and convenience, always assigning string return +values to a <code>std::string</code> is suggested. +</p> +<p>The following examples demonstrate this usage: +</p> +<table class="cartouche" border="1"><tr><td> +<div class="smallexample"> +<pre class="smallexample">long width = config.lookup("application.window.size.w"); + +bool splashScreen = config.lookup("application.splash_screen"); + +std::string title = config.lookup("application.window.title"); +</pre></div> +</td></tr></table> + +<p>Note that certain conversions can lead to loss of precision or +clipping of values, e.g., assigning a negative value to an <i>unsigned +int</i> (in which case the value will be treated as 0), or a +double-precision value to a <i>float</i>. The library does not treat +these lossy conversions as errors. +</p> +<p>Perhaps surprisingly, the following code in particular will cause a +compiler error: +</p> +<table class="cartouche" border="1"><tr><td> +<div class="smallexample"> +<pre class="smallexample">std::string title; +. +. +. +title = config.lookup("application.window.title"); +</pre></div> +</td></tr></table> + +<p>This is because the assignment operator of <code>std::string</code> is being +invoked with a <code>Setting &</code> as an argument. The compiler is unable +to make an implicit conversion because both the <code>const char *</code> +and the <code>std::string</code> cast operators of <code>Setting</code> are +equally appropriate. This is not a bug in <i>libconfig</i>; providing +only the <code>const char *</code> cast operator would resolve this +particular ambiguity, but would cause assignments to +<code>std::string</code> like the one in the previous example to produce a +compiler error. (To understand why, see section 11.4.1 of <i>The C++ +Programming Language</i>.) +</p> +<p>The solution to this problem is to use an explicit conversion that +avoids the construction of an intermediate <code>std::string</code> object, +as follows: +</p> +<table class="cartouche" border="1"><tr><td> +<div class="smallexample"> +<pre class="smallexample">std::string title; +. +. +. +title = (const char *)config.lookup("application.window.title"); +</pre></div> +</td></tr></table> + +<p>Or, alternatively, use the <code>c_str()</code> method, which has the same effect: +</p> +<table class="cartouche" border="1"><tr><td> +<div class="smallexample"> +<pre class="smallexample">std::string title; +. +. +. +title = config.lookup("application.window.title").c_str(); +</pre></div> +</td></tr></table> + +<p>If the assignment is invalid due to a type mismatch, a +<code>SettingTypeException</code> is thrown. +</p> +</dd></dl> + +<dl> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<dd> +<p>These assignment operators allow values of type <i>bool</i>, <i>int</i>, +<i>long</i>, <i>long long</i>, <i>float</i>, <i>double</i>, <i>const char *</i>, and +<i>std::string</i> to be assigned to a setting. In the case of strings, +the library makes a copy of the passed string <var>value</var>, so it may +be subsequently freed or modified by the caller without affecting the +value of the setting. +</p> +<p>The following example code looks up a (presumably) integer setting +and changes its value: +</p> +<table class="cartouche" border="1"><tr><td> +<div class="smallexample"> +<pre class="smallexample">Setting &setting = config.lookup("application.window.size.w"); +setting = 1024; +</pre></div> +</td></tr></table> + +<p>If the assignment is invalid due to a type mismatch, a +<code>SettingTypeException</code> is thrown. +</p> +</dd></dl> + +<dl> +<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> +<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> +<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> +<dd> +<p>A <code>Setting</code> object may be subscripted with an integer index +<var>index</var> if it is an array or list, or with either a string +<var>name</var> or an integer index <var>index</var> if it is a group. For example, +the following code would produce the string ‘<samp>Last Name</samp>’ when +applied to the example configuration in <a href="#Configuration-Files">Configuration Files</a>. +</p> +<table class="cartouche" border="1"><tr><td> +<div class="smallexample"> +<pre class="smallexample">Setting& setting = config.lookup("application.misc"); +const char *s = setting["columns"][0]; +</pre></div> +</td></tr></table> + +<p>If the setting is not an array, list, or group, a +<code>SettingTypeException</code> is thrown. If the subscript (<var>index</var> +or <var>name</var>) does not refer to a valid element, a +<code>SettingNotFoundException</code> is thrown. +</p> +<p>Iterating over a group’s child settings with an integer index will +return the settings in the same order that they appear in the +configuration. +</p> +</dd></dl> + +<dl> +<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> +<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> +<dd> +<p>These methods locate a setting by a path <var>path</var> relative to +this setting. If requested setting is not found, a +<code>SettingNotFoundException</code> is thrown. +</p> +</dd></dl> + +<dl> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<dd> +<p>These are convenience methods for looking up the value of a child setting +with the given <var>name</var>. If the setting is found and is of an +appropriate type, the value is stored in <var>value</var> and the method +returns <code>true</code>. Otherwise, <var>value</var> is left unmodified and the +method returns <code>false</code>. These methods do not throw exceptions. +</p> +<p>Storage for <i>const char *</i><!-- /@w --> values is managed by the library and +released automatically when the setting is destroyed or when its value +is changed; the string must not be freed by the caller. For safety and +convenience, always assigning string values to a <code>std::string</code> is +suggested. +</p> +<p>Since these methods have boolean return values and do not throw +exceptions, they can be used within boolean logic expressions. The following +example presents a concise way to look up three values at once and +perform error handling if any of them are not found or are of the +wrong type: +</p> +<br> +<table class="cartouche" border="1"><tr><td> +<div class="smallexample"> +<pre class="smallexample">int var1; +double var2; +const char *var3; + +if(setting.lookupValue("var1", var1) + && setting.lookupValue("var2", var2) + && setting.lookupValue("var3", var3)) +{ + // use var1, var2, var3 +} +else +{ + // error handling here +} +</pre></div> +</td></tr></table> + +<p>This approach also takes advantage of the short-circuit evaluation +rules of C++, e.g., if the first lookup fails (returning <code>false</code>), the +remaining lookups are skipped entirely. +</p> +</dd></dl> + +<dl> +<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> +<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> +<dd> +<p>These methods add a new child setting with the given <var>name</var> and +<var>type</var> to the setting, which must be a group. They return a +reference to the new setting. If the setting already has a child +setting with the given name, or if the name is invalid, a +<code>SettingNameException</code> is thrown. If the setting is not a group, +a <code>SettingTypeException</code> is thrown. +</p> +<p>Once a setting has been created, neither its name nor type can be +changed. +</p> +</dd></dl> + +<dl> +<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> +<dd> +<p>This method adds a new element to the setting, which must be of type +<code>TypeArray</code> or <code>TypeList</code>. If the setting is an array which +currently has zero elements, the <var>type</var> parameter (which must be +<code>TypeInt</code>, <code>TypeInt64</code>, <code>TypeFloat</code>, <code>TypeBool</code>, +or <code>TypeString</code>) determines the type for the array; otherwise it +must match the type of the existing elements in the array. +</p> +<p>The method returns the new setting on success. If <var>type</var> is a +scalar type, the new setting will have a default value of 0, 0.0, +<code>false</code>, or <code>NULL</code>, as appropriate. +</p> +<p>The method throws a <code>SettingTypeException</code> if the setting is not +an array or list, or if <var>type</var> is invalid. +</p> +</dd></dl> + +<dl> +<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> +<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> +<dd> +<p>These methods remove the child setting with the given <var>name</var> from +the setting, which must be a group. Any child settings of the removed +setting are recursively destroyed as well. +</p> +<p>If the setting is not a group, a <code>SettingTypeException</code> is +thrown. If the setting does not have a child setting with the given +name, a <code>SettingNotFoundException</code> is thrown. +</p> +</dd></dl> + +<dl> +<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> +<dd> +<p>This method removes the child setting at the given index <var>index</var> from +the setting, which must be a group, list, or array. Any child settings +of the removed setting are recursively destroyed as well. +</p> +<p>If the setting is not a group, list, or array, a +<code>SettingTypeException</code> is thrown. If <var>index</var> is out of range, +a <code>SettingNotFoundException</code> is thrown. +</p> +</dd></dl> + +<dl> +<dt><a name="index-getName-on-Setting"></a>Method on Setting: <em>const char *</em> <strong>getName</strong> <em>() const</em></dt> +<dd> +<p>This method returns the name of the setting, or <code>NULL</code> if the +setting has no name. Storage for the returned string is managed by the +library and released automatically when the setting is destroyed; the +string must not be freed by the caller. For safety and convenience, +consider assigning the return value to a <code>std::string</code>. +</p> +</dd></dl> + +<dl> +<dt><a name="index-getPath-on-Setting"></a>Method on Setting: <em>std::string</em> <strong>getPath</strong> <em>() const</em></dt> +<dd> +<p>This method returns the complete dot-separated path to the +setting. Settings which do not have a name (list and array elements) +are represented by their index in square brackets. +</p> +</dd></dl> + +<dl> +<dt><a name="index-getParent-on-Setting"></a>Method on Setting: <em>Setting &</em> <strong>getParent</strong> <em>() const</em></dt> +<dd> +<p>This method returns the parent setting of the setting. If the setting +is the root setting, a <code>SettingNotFoundException</code> is thrown. +</p> +</dd></dl> + +<dl> +<dt><a name="index-isRoot-on-Setting"></a>Method on Setting: <em>bool</em> <strong>isRoot</strong> <em>() const</em></dt> +<dd> +<p>This method returns <code>true</code> if the setting is the root setting, and +<code>false</code> otherwise. +</p> +</dd></dl> + +<dl> +<dt><a name="index-getIndex-on-Setting"></a>Method on Setting: <em>int</em> <strong>getIndex</strong> <em>() const</em></dt> +<dd> +<p>This method returns the index of the setting within its parent +setting. When applied to the root setting, this method returns -1. +</p> +</dd></dl> + +<dl> +<dt><a name="index-getType-on-Setting"></a>Method on Setting: <em>Setting::Type</em> <strong>getType</strong> <em>() const</em></dt> +<dd> +<a name="index-Setting_003a_003aType"></a> +<p>This method returns the type of the setting. The +<code>Setting::Type</code> enumeration consists of the following constants: +<code>TypeInt</code>, <code>TypeInt64</code>, <code>TypeFloat</code>, <code>TypeString</code>, +<code>TypeBoolean</code>, <code>TypeArray</code>, <code>TypeList</code>, and +<code>TypeGroup</code>. +</p> +</dd></dl> + +<dl> +<dt><a name="index-getFormat-on-Setting"></a>Method on Setting: <em>Setting::Format</em> <strong>getFormat</strong> <em>() const</em></dt> +<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> +<dd> +<p>These methods get and set the external format for the setting. +</p> +<a name="index-Setting_003a_003aFormat"></a> +<p>The <var>Setting::Format</var> enumeration consists of the following +constants: <code>FormatDefault</code> and <code>FormatHex</code>. All settings +support the <code>FormatDefault</code> format. The <code>FormatHex</code> format +specifies hexadecimal formatting for integer values, and hence only +applies to settings of type <code>TypeInt</code> and <code>TypeInt64</code>. If +<var>format</var> is invalid for the given setting, it is ignored. +</p> +</dd></dl> + +<dl> +<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> +<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> +<dd> +<p>These methods test if the setting has a child setting with the given +<var>name</var>. They return <code>true</code> if the setting exists, and +<code>false</code> otherwise. These methods do not throw exceptions. +</p> +</dd></dl> +<dl> +<dt><a name="index-begin-on-Setting"></a>Method on Setting: <em>iterator</em> <strong>begin</strong> <em>()</em></dt> +<dt><a name="index-end-on-Setting"></a>Method on Setting: <em>iterator</em> <strong>end</strong> <em>()</em></dt> +<dt><a name="index-begin-on-Setting-1"></a>Method on Setting: <em>const_iterator</em> <strong>begin</strong> <em>()</em></dt> +<dt><a name="index-end-on-Setting-1"></a>Method on Setting: <em>const_iterator</em> <strong>end</strong> <em>()</em></dt> +<dd> +<p>These methods return STL-style iterators that can be used to enumerate +the child settings of a given setting. If the setting is not an array, list, +or group, they throw a <code>SettingTypeException</code>. +</p> +</dd></dl> + +<dl> +<dt><a name="index-getLength-on-Setting"></a>Method on Setting: <em>int</em> <strong>getLength</strong> <em>() const</em></dt> +<dd> +<p>This method returns the number of settings in a group, or the number of +elements in a list or array. For other types of settings, it returns +0. +</p> +</dd></dl> + +<dl> +<dt><a name="index-isGroup-on-Setting"></a>Method on Setting: <em>bool</em> <strong>isGroup</strong> <em>() const</em></dt> +<dt><a name="index-isArray-on-Setting"></a>Method on Setting: <em>bool</em> <strong>isArray</strong> <em>() const</em></dt> +<dt><a name="index-isList-on-Setting"></a>Method on Setting: <em>bool</em> <strong>isList</strong> <em>() const</em></dt> +<dd> +<p>These convenience methods test if a setting is of a given type. +</p> +</dd></dl> + +<dl> +<dt><a name="index-isAggregate-on-Setting"></a>Method on Setting: <em>bool</em> <strong>isAggregate</strong> <em>() const</em></dt> +<dt><a name="index-isScalar-on-Setting"></a>Method on Setting: <em>bool</em> <strong>isScalar</strong> <em>() const</em></dt> +<dt><a name="index-isNumber-on-Setting"></a>Method on Setting: <em>bool</em> <strong>isNumber</strong> <em>() const</em></dt> +<dd> +<p>These convenience methods test if a setting is of an aggregate type (a +group, array, or list), of a scalar type (integer, 64-bit integer, +floating point, boolean, or string), and of a number (integer, 64-bit +integer, or floating point), respectively. +</p> +</dd></dl> + +<dl> +<dt><a name="index-getSourceFile-on-Setting"></a>Method on Setting: <em>const char *</em> <strong>getSourceFile</strong> <em>() const</em></dt> +<dd> +<p>This method returns the name of the file from which the setting was +read, or NULL if the setting was not read from a file. This +information is useful for reporting application-level errors. Storage +for the returned string is managed by the library and released +automatically when the configuration is destroyed; the string must +not be freed by the caller. +</p> +</dd></dl> + +<dl> +<dt><a name="index-getSourceLine-on-Setting"></a>Method on Setting: <em>unsigned int</em> <strong>getSourceLine</strong> <em>() const</em></dt> +<dd> +<p>This method returns the line number of the configuration file or +stream at which the setting <var>setting</var> was read, or 0 if no line +number is available. This information is useful for reporting +application-level errors. +</p> +</dd></dl> + +<hr> +<a name="Example-Programs"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="Example-Programs-1"></a> +<h2 class="chapter">5 Example Programs</h2> + +<p>Practical example programs that illustrate how to use <i>libconfig</i> +from both C and C++ are included in the <samp>examples</samp> subdirectory +of the distribution. These examples include: +</p> +<dl compact="compact"> +<dt><samp>examples/c/example1.c</samp></dt> +<dd><p>An example C program that reads a configuration from an existing file +<samp>example.cfg</samp> (also located in <samp>examples/c</samp>) and displays +some of its contents. +</p> +</dd> +<dt><samp>examples/c++/example1.cpp</samp></dt> +<dd><p>The C++ equivalent of <samp>example1.c</samp>. +</p> +</dd> +<dt><samp>examples/c/example2.c</samp></dt> +<dd><p>An example C program that reads a configuration from an existing file +<samp>example.cfg</samp> (also located in <samp>examples/c</samp>), adds new +settings to the configuration, and writes the updated configuration to +another file. +</p> +</dd> +<dt><samp>examples/c++/example2.cpp</samp></dt> +<dd><p>The C++ equivalent of <samp>example2.c</samp> +</p> +</dd> +<dt><samp>examples/c/example3.c</samp></dt> +<dd><p>An example C program that constructs a new configuration in memory and writes it to a file. +</p> +</dd> +<dt><samp>examples/c++/example3.cpp</samp></dt> +<dd><p>The C++ equivalent of <samp>example3.c</samp> +</p> +</dd> +<dt><samp>examples/c/example4.c</samp></dt> +<dd><p>An example C program that uses a custom include function for processing +wildcard includes. Note that this code will not compile on Windows. +</p> +</dd> +</dl> + +<hr> +<a name="Other-Bindings-and-Implementations"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="Other-Bindings-and-Implementations-1"></a> +<h2 class="chapter">6 Other Bindings and Implementations</h2> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Bourne-Shell" accesskey="1">Bourne Shell</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="#D" accesskey="2">D</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="#Haskell" accesskey="3">Haskell</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="#Java" accesskey="4">Java</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="#Lisp" accesskey="5">Lisp</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="#Perl" accesskey="6">Perl</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="#Python" accesskey="7">Python</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="#Ruby" accesskey="8">Ruby</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +</table> + +<p>Various open-source libraries have been written that provide access to +<i>libconfig</i>-style configuration files from other programming languages. Some +of these libraries are wrappers which add new language bindings for +<i>libconfig</i> while others are syntax-compatible reimplementations in other +languages. +</p> +<p>Here is a list of some of these implementations. +</p> +<hr> +<a name="Bourne-Shell"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="Bourne-Shell-1"></a> +<h3 class="section">6.1 Bourne Shell</h3> + +<p>Łukasz A. Grabowski’s <i>ls-config</i> provides a means to read and write +values in <i>libconfig</i> configuration files from Bourne shell scripts. The +implementation is included in the <i>libconfig</i> git repository at +<a href="https://github.com/hyperrealm/libconfig">https://github.com/hyperrealm/libconfig</a>, in the <samp>contrib/ls-config</samp> +subdirectory. +</p> +<hr> +<a name="D"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="D-1"></a> +<h3 class="section">6.2 D</h3> + +<p>Remi Thebault’s <i>libconfig-d</i> is a port of <i>libconfig</i> to the D programming +language. It may be found at <a href="https://code.dlang.org/packages/libconfig-d">https://code.dlang.org/packages/libconfig-d</a>. +</p> +<hr> +<a name="Haskell"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="Haskell-1"></a> +<h3 class="section">6.3 Haskell</h3> + +<p>Matthew Peddie’s <i>libconfig</i> provides Haskell bindings to +<i>libconfig</i>. It may be found at +<a href="https://hackage.haskell.org/package/libconfig-0.3.0.0">https://hackage.haskell.org/package/libconfig-0.3.0.0</a>. +</p> +<hr> +<a name="Java"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="Java-1"></a> +<h3 class="section">6.4 Java</h3> + +<p>Andrey V. Pleskach has a pure-Java implementation of <i>libconfig</i>. It may be +found on github at <a href="https://github.com/willyborankin/libconfig">https://github.com/willyborankin/libconfig</a>. +</p> +<hr> +<a name="Lisp"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="Lisp-1"></a> +<h3 class="section">6.5 Lisp</h3> + +<p>Oleg Shalaev’s <i>cl-libconfig</i> provides Common Lisp bindings for <i>libconfig</i>. +It may be found on github at <a href="https://github.com/chalaev/cl-libconfig">https://github.com/chalaev/cl-libconfig</a>. +</p> +<hr> +<a name="Perl"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="Perl-1"></a> +<h3 class="section">6.6 Perl</h3> + +<p>The <i>Conf::Libconfig</i> module provides Perl bindings for <i>libconfig</i>. It may +be 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> +or on github at <a href="https://github.com/cnangel/Conf-Libconfig">https://github.com/cnangel/Conf-Libconfig</a>. +</p> +<hr> +<a name="Python"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="Python-1"></a> +<h3 class="section">6.7 Python</h3> + +<p>Heiner Tholen’s <i>pylibconfig2</i> is a Python library that is syntax-compatible +with <i>libconfig</i>. It may be found at +<a href="https://pypi.python.org/pypi/pylibconfig2/0.1.2">https://pypi.python.org/pypi/pylibconfig2/0.1.2</a>. +</p> +<br> + +<p>Christian Aichinger’s <i>libconf</i> is another pure-Python implementation with a +more permissive license. It may be found at +<a href="https://pypi.python.org/pypi/libconf">https://pypi.python.org/pypi/libconf</a> or on github at +<a href="https://github.com/Grk0/python-libconf">https://github.com/Grk0/python-libconf</a>. +</p> +<br> + +<p>The <i>python-libconfig</i> wrapper provides Python bindings to <i>libconfig</i>. It +may be found on github at <a href="https://github.com/cnangel/python-libconfig/">https://github.com/cnangel/python-libconfig/</a>. +</p> +<hr> +<a name="Ruby"></a> +<div class="header"> +<p> +Previous: <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> +</div> +<a name="Ruby-1"></a> +<h3 class="section">6.8 Ruby</h3> + +<p>Christopher Mark Gore’s <i>ruby-libconfig</i> is a Ruby library that provides Ruby +bindings for <i>libconfig</i>. It may be found at +<a href="https://rubygems.org/gems/libconfig">https://rubygems.org/gems/libconfig</a> or on github at +<a href="https://github.com/cgore/ruby-libconfig">https://github.com/cgore/ruby-libconfig</a>. +</p> +<br> + +<p>There is also another Ruby wrapper, <i>libconfig-ruby</i>, that is included in +the <i>libconfig</i> git repository at <a href="https://github.com/hyperrealm/libconfig">https://github.com/hyperrealm/libconfig</a>, +in the <samp>contrib/libconfig-ruby</samp> subdirectory. +</p> +<hr> +<a name="License"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="License-1"></a> +<h2 class="appendix">Appendix A License</h2> + + + +<div align="center">GNU LESSER GENERAL PUBLIC LICENSE +</div><div align="center">Version 2.1, February 1999 +</div> +<br> + +<p>Copyright © 1991, 1999 Free Software Foundation, Inc., +59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +</p> +<p>Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. +</p> +<p>[This is the first released version of the Lesser GPL. It also counts +as the successor of the GNU Library Public License, version 2, hence the +version number 2.1.] +</p> +<br> +<div align="center">Preamble +</div><br> + +<p>The licenses for most software are designed to take away your freedom to +share and change it. By contrast, the GNU General Public Licenses are +intended to guarantee your freedom to share and change free software–to +make sure the software is free for all its users. +</p> +<p>This license, the Lesser General Public License, applies to some +specially designated software packages–typically libraries–of the Free +Software Foundation and other authors who decide to use it. You can use +it too, but we suggest you first think carefully about whether this +license or the ordinary General Public License is the better strategy to +use in any particular case, based on the explanations below. +</p> +<p>When we speak of free software, we are referring to freedom of use, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish); that you receive source code or can get it if +you want it; that you can change the software and use pieces of it in +new free programs; and that you are informed that you can do these +things. +</p> +<p>To protect your rights, we need to make restrictions that forbid +distributors to deny you these rights or to ask you to surrender these +rights. These restrictions translate to certain responsibilities for +you if you distribute copies of the library or if you modify it. +</p> +<p>For example, if you distribute copies of the library, whether gratis or +for a fee, you must give the recipients all the rights that we gave you. +You must make sure that they, too, receive or can get the source code. +If you link other code with the library, you must provide complete +object files to the recipients, so that they can relink them with the +library after making changes to the library and recompiling it. And you +must show them these terms so they know their rights. +</p> +<p>We protect your rights with a two-step method: (1) we copyright the +library, and (2) we offer you this license, which gives you legal +permission to copy, distribute and/or modify the library. +</p> +<p>To protect each distributor, we want to make it very clear that there is +no warranty for the free library. Also, if the library is modified by +someone else and passed on, the recipients should know that what they +have is not the original version, so that the original author’s +reputation will not be affected by problems that might be introduced by +others. +</p> +<p>Finally, software patents pose a constant threat to the existence of any +free program. We wish to make sure that a company cannot effectively +restrict the users of a free program by obtaining a restrictive license +from a patent holder. Therefore, we insist that any patent license +obtained for a version of the library must be consistent with the full +freedom of use specified in this license. +</p> +<p>Most GNU software, including some libraries, is covered by the ordinary +GNU General Public License. This license, the GNU Lesser General Public +License, applies to certain designated libraries, and is quite different +from the ordinary General Public License. We use this license for +certain libraries in order to permit linking those libraries into +non-free programs. +</p> +<p>When a program is linked with a library, whether statically or using a +shared library, the combination of the two is legally speaking a +combined work, a derivative of the original library. The ordinary +General Public License therefore permits such linking only if the entire +combination fits its criteria of freedom. The Lesser General Public +License permits more lax criteria for linking other code with the +library. +</p> +<p>We call this license the “Lesser” General Public License because it does +Less to protect the user’s freedom than the ordinary General Public +License. It also provides other free software developers Less of an +advantage over competing non-free programs. These disadvantages are the +reason we use the ordinary General Public License for many libraries. +However, the Lesser license provides advantages in certain special +circumstances. +</p> +<p>For example, on rare occasions, there may be a special need to encourage +the widest possible use of a certain library, so that it becomes a +de-facto standard. To achieve this, non-free programs must be allowed +to use the library. A more frequent case is that a free library does +the same job as widely used non-free libraries. In this case, there is +little to gain by limiting the free library to free software only, so we +use the Lesser General Public License. +</p> +<p>In other cases, permission to use a particular library in non-free +programs enables a greater number of people to use a large body of free +software. For example, permission to use the GNU C Library in non-free +programs enables many more people to use the whole GNU operating system, +as well as its variant, the GNU/Linux operating system. +</p> +<p>Although the Lesser General Public License is Less protective of the +users’ freedom, it does ensure that the user of a program that is linked +with the Library has the freedom and the wherewithal to run that program +using a modified version of the Library. +</p> +<p>The precise terms and conditions for copying, distribution and +modification follow. Pay close attention to the difference between a +“work based on the library” and a “work that uses the library”. The +former contains code derived from the library, whereas the latter must +be combined with the library in order to run. +</p> + +<div align="center">GNU LESSER GENERAL PUBLIC LICENSE +</div><div align="center">TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +</div> +<ol> +<li> +<br> +</li><li> This License Agreement applies to any software library or other program +which contains a notice placed by the copyright holder or other +authorized party saying it may be distributed under the terms of this +Lesser General Public License (also called “this License”). Each +licensee is addressed as “you”. + +<p>A “library” means a collection of software functions and/or data +prepared so as to be conveniently linked with application programs +(which use some of those functions and data) to form executables. +</p> +<p>The “Library”, below, refers to any such software library or work which +has been distributed under these terms. A “work based on the Library” +means either the Library or any derivative work under copyright law: +that is to say, a work containing the Library or a portion of it, either +verbatim or with modifications and/or translated straightforwardly into +another language. (Hereinafter, translation is included without +limitation in the term “modification”.) +</p> +<p>“Source code” for a work means the preferred form of the work for making +modifications to it. For a library, complete source code means all the +source code for all modules it contains, plus any associated interface +definition files, plus the scripts used to control compilation and +installation of the library. +</p> +<p>Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of running +a program using the Library is not restricted, and output from such a +program is covered only if its contents constitute a work based on the +Library (independent of the use of the Library in a tool for writing +it). Whether that is true depends on what the Library does and what the +program that uses the Library does. +</p> +<br> +</li><li> You may copy and distribute verbatim copies of the Library’s complete +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the notices +that refer to this License and to the absence of any warranty; and +distribute a copy of this License along with the Library. + +<p>You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. +</p> +<br> +</li><li> You may modify your copy or copies of the Library or any portion of it, +thus forming a work based on the Library, and copy and distribute such +modifications or work under the terms of Section 1 above, provided that +you also meet all of these conditions: + +<ol> +<li> The modified work must itself be a software library. + +<br> +</li><li> You must cause the files modified to carry prominent notices stating +that you changed the files and the date of any change. + +<br> +</li><li> You must cause the whole of the work to be licensed at no charge to all +third parties under the terms of this License. + +<br> +</li><li> If a facility in the modified Library refers to a function or a table of +data to be supplied by an application program that uses the facility, +other than as an argument passed when the facility is invoked, then you +must make a good faith effort to ensure that, in the event an +application does not supply such function or table, the facility still +operates, and performs whatever part of its purpose remains meaningful. + +<p>(For example, a function in a library to compute square roots has a +purpose that is entirely well-defined independent of the application. +Therefore, Subsection 2d requires that any application-supplied function +or table used by this function must be optional: if the application does +not supply it, the square root function must still compute square +roots.) +</p> +</li></ol> + +<p>These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Library, and +can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based on +the Library, the distribution of the whole must be on the terms of this +License, whose permissions for other licensees extend to the entire +whole, and thus to each and every part regardless of who wrote it. +</p> +<p>Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Library. +</p> +<p>In addition, mere aggregation of another work not based on the Library +with the Library (or with a work based on the Library) on a volume of a +storage or distribution medium does not bring the other work under the +scope of this License. +</p> +<br> +</li><li> You may opt to apply the terms of the ordinary GNU General Public +License instead of this License to a given copy of the Library. To do +this, you must alter all the notices that refer to this License, so that +they refer to the ordinary GNU General Public License, version 2, +instead of to this License. (If a newer version than version 2 of the +ordinary GNU General Public License has appeared, then you can specify +that version instead if you wish.) Do not make any other change in +these notices. + +<p>Once this change is made in a given copy, it is irreversible for that +copy, so the ordinary GNU General Public License applies to all +subsequent copies and derivative works made from that copy. +</p> +<p>This option is useful when you wish to copy part of the code of the +Library into a program that is not a library. +</p> +<br> +</li><li> You may copy and distribute the Library (or a portion or derivative of +it, under Section 2) in object code or executable form under the terms +of Sections 1 and 2 above provided that you accompany it with the +complete corresponding machine-readable source code, which must be +distributed under the terms of Sections 1 and 2 above on a medium +customarily used for software interchange. + +<p>If distribution of object code is made by offering access to copy from a +designated place, then offering equivalent access to copy the source +code from the same place satisfies the requirement to distribute the +source code, even though third parties are not compelled to copy the +source along with the object code. +</p> +<br> +</li><li> A program that contains no derivative of any portion of the Library, but +is designed to work with the Library by being compiled or linked with +it, is called a “work that uses the Library”. Such a work, in +isolation, is not a derivative work of the Library, and therefore falls +outside the scope of this License. + +<p>However, linking a “work that uses the Library” with the Library creates +an executable that is a derivative of the Library (because it contains +portions of the Library), rather than a “work that uses the library”. +The executable is therefore covered by this License. Section 6 states +terms for distribution of such executables. +</p> +<p>When a “work that uses the Library” uses material from a header file +that is part of the Library, the object code for the work may be a +derivative work of the Library even though the source code is not. +Whether this is true is especially significant if the work can be linked +without the Library, or if the work is itself a library. The threshold +for this to be true is not precisely defined by law. +</p> +<p>If such an object file uses only numerical parameters, data structure +layouts and accessors, and small macros and small inline functions (ten +lines or less in length), then the use of the object file is +unrestricted, regardless of whether it is legally a derivative work. +(Executables containing this object code plus portions of the Library +will still fall under Section 6.) +</p> +<p>Otherwise, if the work is a derivative of the Library, you may +distribute the object code for the work under the terms of Section 6. +Any executables containing that work also fall under Section 6, whether +or not they are linked directly with the Library itself. +</p> +<br> +</li><li> As an exception to the Sections above, you may also combine or link a +“work that uses the Library” with the Library to produce a work +containing portions of the Library, and distribute that work under terms +of your choice, provided that the terms permit modification of the work +for the customer’s own use and reverse engineering for debugging such +modifications. + +<p>You must give prominent notice with each copy of the work that the +Library is used in it and that the Library and its use are covered by +this License. You must supply a copy of this License. If the work +during execution displays copyright notices, you must include the +copyright notice for the Library among them, as well as a reference +directing the user to the copy of this License. Also, you must do one +of these things: +</p> +<ol> +<li> +<br> +</li><li> Accompany the work with the complete corresponding machine-readable +source code for the Library including whatever changes were used in the +work (which must be distributed under Sections 1 and 2 above); and, if +the work is an executable linked with the Library, with the complete +machine-readable “work that uses the Library”, as object code and/or +source code, so that the user can modify the Library and then relink to +produce a modified executable containing the modified Library. (It is +understood that the user who changes the contents of definitions files +in the Library will not necessarily be able to recompile the application +to use the modified definitions.) + +<br> +</li><li> Use a suitable shared library mechanism for linking with the Library. A +suitable mechanism is one that (1) uses at run time a copy of the +library already present on the user’s computer system, rather than +copying library functions into the executable, and (2) will operate +properly with a modified version of the library, if the user installs +one, as long as the modified version is interface-compatible with the +version that the work was made with. + +<br> +</li><li> Accompany the work with a written offer, valid for at least three years, +to give the same user the materials specified in Subsection 6a, above, +for a charge no more than the cost of performing this distribution. + +<br> +</li><li> If distribution of the work is made by offering access to copy from a +designated place, offer equivalent access to copy the above specified +materials from the same place. + +<br> +</li><li> Verify that the user has already received a copy of these materials or +that you have already sent this user a copy. + +</li></ol> + +<p>For an executable, the required form of the “work that uses the Library” +must include any data and utility programs needed for reproducing the +executable from it. However, as a special exception, the materials to +be distributed need not include anything that is normally distributed +(in either source or binary form) with the major components (compiler, +kernel, and so on) of the operating system on which the executable runs, +unless that component itself accompanies the executable. +</p> +<p>It may happen that this requirement contradicts the license restrictions +of other proprietary libraries that do not normally accompany the +operating system. Such a contradiction means you cannot use both them +and the Library together in an executable that you distribute. +</p> +<br> +</li><li> You may place library facilities that are a work based on the Library +side-by-side in a single library together with other library facilities +not covered by this License, and distribute such a combined library, +provided that the separate distribution of the work based on the Library +and of the other library facilities is otherwise permitted, and provided +that you do these two things: + +<ol> +<li> +<br> +</li><li> Accompany the combined library with a copy of the same work based on the +Library, uncombined with any other library facilities. This must be +distributed under the terms of the Sections above. + +<br> +</li><li> Give prominent notice with the combined library of the fact that part of +it is a work based on the Library, and explaining where to find the +accompanying uncombined form of the same work. + +</li></ol> + +<br> +</li><li> You may not copy, modify, sublicense, link with, or distribute the +Library except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense, link with, or distribute the +Library is void, and will automatically terminate your rights under this +License. However, parties who have received copies, or rights, from you +under this License will not have their licenses terminated so long as +such parties remain in full compliance. + +<br> +</li><li> You are not required to accept this License, since you have not signed +it. However, nothing else grants you permission to modify or distribute +the Library or its derivative works. These actions are prohibited by +law if you do not accept this License. Therefore, by modifying or +distributing the Library (or any work based on the Library), you +indicate your acceptance of this License to do so, and all its terms and +conditions for copying, distributing or modifying the Library or works +based on it. + +<br> +</li><li> Each time you redistribute the Library (or any work based on the +Library), the recipient automatically receives a license from the +original licensor to copy, distribute, link with or modify the Library +subject to these terms and conditions. You may not impose any further +restrictions on the recipients’ exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties with +this License. + +<br> +</li><li> If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Library at all. For example, if a patent license +would not permit royalty-free redistribution of the Library by all those +who receive copies directly or indirectly through you, then the only way +you could satisfy both it and this License would be to refrain entirely +from distribution of the Library. + +<p>If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply, and the section as a whole is intended to apply in other +circumstances. +</p> +<p>It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system which is implemented +by public license practices. Many people have made generous +contributions to the wide range of software distributed through that +system in reliance on consistent application of that system; it is up to +the author/donor to decide if he or she is willing to distribute +software through any other system and a licensee cannot impose that +choice. +</p> +<p>This section is intended to make thoroughly clear what is believed to be +a consequence of the rest of this License. +</p> +<br> +</li><li> If the distribution and/or use of the Library is restricted in certain +countries either by patents or by copyrighted interfaces, the original +copyright holder who places the Library under this License may add an +explicit geographical distribution limitation excluding those countries, +so that distribution is permitted only in or among countries not thus +excluded. In such case, this License incorporates the limitation as if +written in the body of this License. + +<br> +</li><li> The Free Software Foundation may publish revised and/or new versions of +the Lesser General Public License from time to time. Such new versions +will be similar in spirit to the present version, but may differ in +detail to address new problems or concerns. + +<p>Each version is given a distinguishing version number. If the Library +specifies a version number of this License which applies to it and “any +later version”, you have the option of following the terms and +conditions either of that version or of any later version published by +the Free Software Foundation. If the Library does not specify a license +version number, you may choose any version ever published by the Free +Software Foundation. +</p> +<br> +</li><li> If you wish to incorporate parts of the Library into other free programs +whose distribution conditions are incompatible with these, write to the +author to ask for permission. For software which is copyrighted by the +Free Software Foundation, write to the Free Software Foundation; we +sometimes make exceptions for this. Our decision will be guided by the +two goals of preserving the free status of all derivatives of our free +software and of promoting the sharing and reuse of software generally. + +<br> +<div align="center">NO WARRANTY +</div><br> + +</li><li> BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR +THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE LIBRARY “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER +EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE +ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH +YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL +NECESSARY SERVICING, REPAIR OR CORRECTION. + +<br> +</li><li> IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR +DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL +DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY +(INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED +INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF +THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR +OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + +</li></ol> + +<br> +<div align="center">END OF TERMS AND CONDITIONS +</div><br> +<div align="center">How to Apply These Terms to Your New Libraries +</div> +<p>If you develop a new library, and you want it to be of the greatest +possible use to the public, we recommend making it free software that +everyone can redistribute and change. You can do so by permitting +redistribution under these terms (or, alternatively, under the terms of +the ordinary General Public License). +</p> +<p>To apply these terms, attach the following notices to the library. It +is safest to attach them to the start of each source file to most +effectively convey the exclusion of warranty; and each file should have +at least the “copyright” line and a pointer to where the full notice is +found. +</p> +<div class="format"> +<pre class="format"><tt> +<one line to give the library's name and a brief idea of what it does.> +Copyright (C) <year> <name of author> + +This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2 of the License, or (at your option) any later version. + +This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details. + +You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +</tt> +</pre></div> + +<p>Also add information on how to contact you by electronic and paper mail. +</p> +<p>You should also get your employer (if you work as a programmer) or your +school, if any, to sign a “copyright disclaimer” for the library, if +necessary. Here is a sample; alter the names: +</p> +<div class="format"> +<pre class="format"><tt> +Yoyodyne, Inc., hereby disclaims all copyright interest in the +library `Frob' (a library for tweaking knobs) written by James Random Hacker. + +<signature of Ty Coon>, 1 April 1990 +Ty Coon, President of Vice +</tt> +</pre></div> + +<p>That’s all there is to it! +</p> + +<hr> +<a name="Configuration-File-Grammar"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="Configuration-File-Grammar-1"></a> +<h2 class="appendix">Appendix B Configuration File Grammar</h2> + +<p>Below is the BNF grammar for configuration files. Comments and include +directives are not part of the grammar, so they are not included here. +</p> +<br> +<div class="example"> +<pre class="example"><configuration> ::= + <setting-list> + | <empty> + +<setting-list> ::= + <setting> + | <setting-list> <setting> + +<setting> ::= + <name> ( ":" | "=" ) <value> ( ";" | "," | <empty> ) + +<value> ::= + <scalar-value> + | <array> + | <list> + | <group> + +<value-list> ::= + <value> + | <value-list> "," <value> + | <value-list> "," + +<scalar-value> ::= + <boolean> + | <integer> + | <integer64> + | <hex> + | <hex64> + | <float> + | <string> + +<scalar-value-list> ::= + <scalar-value> + | <scalar-value-list> "," <scalar-value> + | <scalar-value-list> "," + +<array> ::= + "[" ( <scalar-value-list> | <empty> ) "]" + +<list> ::= + "(" ( <value-list> | <empty> ) ")" + +<group> ::= + "{" ( <setting-list> | <empty> ) "}" + +<empty> ::= +</pre></div> + +<br> +<br> +<p>Terminals are defined below as regular expressions: +</p><br> + +<table> +<tr><td width="20%"><code><boolean></code></td><td width="80%"><code>([Tt][Rr][Uu][Ee])|([Ff][Aa][Ll][Ss][Ee])</code></td></tr> +<tr><td width="20%"><code><string></code></td><td width="80%"><code>\"([^\"\\]|\\.)*\"</code></td></tr> +<tr><td width="20%"><code><name></code></td><td width="80%"><code>[A-Za-z\*][-A-Za-z0-9_\*]*</code></td></tr> +<tr><td width="20%"><code><integer></code></td><td width="80%"><code>[-+]?[0-9]+</code></td></tr> +<tr><td width="20%"><code><integer64></code></td><td width="80%"><code>[-+]?[0-9]+L(L)?</code></td></tr> +<tr><td width="20%"><code><hex></code></td><td width="80%"><code>0[Xx][0-9A-Fa-f]+</code></td></tr> +<tr><td width="20%"><code><hex64></code></td><td width="80%"><code>0[Xx][0-9A-Fa-f]+(L(L)?)?</code></td></tr> +<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> +</table> + +<br> + +<p>Note that adjacent strings are automatically concatenated. Non-printable +characters can be represented within strings using a sequence ‘<samp>\xx</samp>’, +representing the ASCII value as two hex digits. +</p> +<hr> +<a name="Function-Index"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="Function-Index-1"></a> +<h2 class="unnumbered">Function Index</h2> + +<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Function-Index_fn_symbol-1"><b>~</b></a> + +<br> +<a class="summary-letter" href="#Function-Index_fn_letter-A"><b>A</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-B"><b>B</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-C"><b>C</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-E"><b>E</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-F"><b>F</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-G"><b>G</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-I"><b>I</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-L"><b>L</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-O"><b>O</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-P"><b>P</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-R"><b>R</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-S"><b>S</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-W"><b>W</b></a> + +</td></tr></table> +<table class="index-fn" border="0"> +<tr><td></td><th align="left">Index Entry</th><td> </td><th align="left"> Section</th></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Function-Index_fn_symbol-1">~</a></th><td></td><td></td></tr> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Function-Index_fn_letter-A">A</a></th><td></td><td></td></tr> +<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> +<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> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Function-Index_fn_letter-B">B</a></th><td></td><td></td></tr> +<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> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Function-Index_fn_letter-C">C</a></th><td></td><td></td></tr> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Function-Index_fn_letter-E">E</a></th><td></td><td></td></tr> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Function-Index_fn_letter-F">F</a></th><td></td><td></td></tr> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Function-Index_fn_letter-G">G</a></th><td></td><td></td></tr> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Function-Index_fn_letter-I">I</a></th><td></td><td></td></tr> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Function-Index_fn_letter-L">L</a></th><td></td><td></td></tr> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Function-Index_fn_letter-O">O</a></th><td></td><td></td></tr> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Function-Index_fn_letter-P">P</a></th><td></td><td></td></tr> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Function-Index_fn_letter-R">R</a></th><td></td><td></td></tr> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Function-Index_fn_letter-S">S</a></th><td></td><td></td></tr> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Function-Index_fn_letter-W">W</a></th><td></td><td></td></tr> +<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> +<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> +<tr><td colspan="4"> <hr></td></tr> +</table> +<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Function-Index_fn_symbol-1"><b>~</b></a> + +<br> +<a class="summary-letter" href="#Function-Index_fn_letter-A"><b>A</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-B"><b>B</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-C"><b>C</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-E"><b>E</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-F"><b>F</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-G"><b>G</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-I"><b>I</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-L"><b>L</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-O"><b>O</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-P"><b>P</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-R"><b>R</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-S"><b>S</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-W"><b>W</b></a> + +</td></tr></table> + +<hr> +<a name="Type-Index"></a> +<div class="header"> +<p> +Next: <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> +</div> +<a name="Type-Index-1"></a> +<h2 class="unnumbered">Type Index</h2> + +<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Type-Index_tp_letter-C"><b>C</b></a> + +<a class="summary-letter" href="#Type-Index_tp_letter-F"><b>F</b></a> + +<a class="summary-letter" href="#Type-Index_tp_letter-P"><b>P</b></a> + +<a class="summary-letter" href="#Type-Index_tp_letter-S"><b>S</b></a> + +</td></tr></table> +<table class="index-tp" border="0"> +<tr><td></td><th align="left">Index Entry</th><td> </td><th align="left"> Section</th></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Type-Index_tp_letter-C">C</a></th><td></td><td></td></tr> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Type-Index_tp_letter-F">F</a></th><td></td><td></td></tr> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Type-Index_tp_letter-P">P</a></th><td></td><td></td></tr> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Type-Index_tp_letter-S">S</a></th><td></td><td></td></tr> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<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> +<tr><td colspan="4"> <hr></td></tr> +</table> +<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Type-Index_tp_letter-C"><b>C</b></a> + +<a class="summary-letter" href="#Type-Index_tp_letter-F"><b>F</b></a> + +<a class="summary-letter" href="#Type-Index_tp_letter-P"><b>P</b></a> + +<a class="summary-letter" href="#Type-Index_tp_letter-S"><b>S</b></a> + +</td></tr></table> + +<hr> +<a name="Concept-Index"></a> +<div class="header"> +<p> +Previous: <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> +</div> +<a name="Concept-Index-1"></a> +<h2 class="unnumbered">Concept Index</h2> + +<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Concept-Index_cp_letter-A"><b>A</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-C"><b>C</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-D"><b>D</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-E"><b>E</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-F"><b>F</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-G"><b>G</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-H"><b>H</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-I"><b>I</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-L"><b>L</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-P"><b>P</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-S"><b>S</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-U"><b>U</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-V"><b>V</b></a> + +</td></tr></table> +<table class="index-cp" border="0"> +<tr><td></td><th align="left">Index Entry</th><td> </td><th align="left"> Section</th></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-A">A</a></th><td></td><td></td></tr> +<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> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-C">C</a></th><td></td><td></td></tr> +<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> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-D">D</a></th><td></td><td></td></tr> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-E">E</a></th><td></td><td></td></tr> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-F">F</a></th><td></td><td></td></tr> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-G">G</a></th><td></td><td></td></tr> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-H">H</a></th><td></td><td></td></tr> +<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> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-I">I</a></th><td></td><td></td></tr> +<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> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-L">L</a></th><td></td><td></td></tr> +<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> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-P">P</a></th><td></td><td></td></tr> +<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> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-S">S</a></th><td></td><td></td></tr> +<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> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-U">U</a></th><td></td><td></td></tr> +<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> +<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> +<tr><td colspan="4"> <hr></td></tr> +<tr><th><a name="Concept-Index_cp_letter-V">V</a></th><td></td><td></td></tr> +<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> +<tr><td colspan="4"> <hr></td></tr> +</table> +<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Concept-Index_cp_letter-A"><b>A</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-C"><b>C</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-D"><b>D</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-E"><b>E</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-F"><b>F</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-G"><b>G</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-H"><b>H</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-I"><b>I</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-L"><b>L</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-P"><b>P</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-S"><b>S</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-U"><b>U</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-V"><b>V</b></a> + +</td></tr></table> + +<hr> + + + +</body> +</html> |