Imported Upstream version 1.3.2upstream/1.3.2

1 files changed, 1600 insertions, 0 deletions

diff --git a/doc/libconfig.texi b/doc/libconfig.texi
new file mode 100644
index 0000000..22f8391
--- /dev/null
+++ b/doc/libconfig.texi
@@ -0,0 +1,1600 @@
+\input texinfo.tex    @c -*-texinfo-*-
+@c 
+@c %**start of header
+
+@c All text is ignored before the setfilename.
+@setfilename libconfig.info
+@settitle libconfig
+
+@set edition 1.3.2
+@set update-date 18 February 2009
+@set subtitle-text A Library For Processing Structured Configuration Files
+@set author-text Mark A.@: Lindner
+
+@comment %**end of header
+
+@dircategory Software libraries
+@direntry
+* libconfig: (libconfig).       A Library For Processing Structured Configuration Files
+@end direntry
+
+
+@tex
+\global\emergencystretch = .3\hsize
+@end tex
+
+@setchapternewpage odd
+
+@titlepage
+
+@title libconfig
+@subtitle @value{subtitle-text}
+@subtitle Version @value{edition}
+@subtitle @value{update-date}
+
+@author @value{author-text}
+
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 2005-2009  Mark A Lindner
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+@end titlepage
+
+@c Give the HTML output a title page that somewhat resembles the printed one
+@ifhtml
+@html
+<hr noshade size=6 color="black">
+<div align=right>@value{subtitle-text}<br>
+Version @value{edition}<br>
+@value{update-date}</div>
+<br><br><br><br>
+<font size=+1>@value{author-text}</font>
+<hr size=3 noshade color="black">
+<br><br>
+@end html
+@end ifhtml
+
+@contents
+
+@ifnottex
+@node Top
+@comment  node-name,  next,  previous,  up
+@top libconfig
+@end ifnottex
+
+@menu
+* Introduction::
+* Configuration Files::
+* The C API::
+* The C++ API::
+* Configuration File Grammar::
+* License::
+* Function Index::
+* Type Index::
+* Concept Index::
+@end menu
+
+@node Introduction, Configuration Files, Top, Top
+@comment  node-name,  next,  previous,  up
+@menu
+* Why Another Configuration File Library?::
+* Using the Library from a C Program::
+* Using the Library from a C++ Program::
+* Multithreading Issues::
+* Internationalization Issues::
+* Compiling Using pkg-config::
+@end menu
+@chapter Introduction
+
+@i{Libconfig} 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.
+
+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).
+
+@node Why Another Configuration File Library?, Using the Library from a C Program, , Introduction
+@comment  node-name,  next,  previous,  up
+@section Why Another Configuration File Library?
+
+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} that set it apart from the other libraries are:
+
+@itemize @bullet
+
+@item A fully reentrant parser. Independent configurations can be parsed in concurrent threads at the same time.
+
+@item Both C @i{and} C++ bindings, as well as hooks to allow for the creation of wrappers in other languages.
+
+@item 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.
+
+@item A low-footprint implementation (just 38K for the C library and 66K for the C++ library) that is suitable for memory-constrained systems.
+
+@item Proper documentation.
+
+@end itemize
+
+@node Using the Library from a C Program, Using the Library from a C++ Program, Why Another Configuration File Library?, Introduction
+@comment  node-name,  next,  previous,  up
+@section Using the Library from a C Program
+
+To use the library from C code, include the following preprocessor
+directive in your source files:
+
+@sp 1
+@example
+#include <libconfig.h>
+@end example
+@sp 1
+
+To link with the library, specify @samp{-lconfig} as an argument to the
+linker.
+
+@node Using the Library from a C++ Program, Multithreading Issues, Using the Library from a C Program, Introduction
+@comment  node-name,  next,  previous,  up
+@section Using the Library from a C++ Program
+
+To use the library from C++, include the following preprocessor
+directive in your source files:
+
+@sp 1
+@example
+#include <libconfig.h++>
+@end example
+@sp 1
+
+Or, alternatively:
+
+@sp 1
+@example
+#include <libconfig.hh>
+@end example
+@sp 1
+@page
+The C++ API classes are defined in the namespace @samp{libconfig}, hence the
+following statement may optionally be used:
+
+@sp 1
+@example
+using namespace libconfig;
+@end example
+@sp 1
+
+To link with the library, specify @samp{-lconfig++} as an argument to
+the linker.
+
+@node Multithreading Issues, Internationalization Issues, Using the Library from a C++ Program, Introduction
+@comment  node-name,  next,  previous,  up
+@section Multithreading Issues
+
+@i{Libconfig} is fully @dfn{reentrant}; 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.
+
+@i{Libconfig} is not @dfn{thread-safe}. 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.
+
+@i{Libconfig} is not @dfn{async-safe}. 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.
+
+@i{Libconfig} is not guaranteed to be @dfn{cancel-safe}. 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.
+
+@node Internationalization Issues, Compiling Using pkg-config, Multithreading Issues, Introduction
+@comment  node-name,  next,  previous,  up
+@section Internationalization Issues
+
+@cindex Unicode
+@cindex UTF-8
+@i{Libconfig} 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 (@t{wchar_t}) strings using the
+wide string conversion functions such as @t{mbsrtowcs()} and
+@t{wcsrtombs()} or the @t{iconv()} function of the @i{libiconv}
+library.
+
+@cindex locale
+The textual representation of a floating point value varies by
+locale. However, the @i{libconfig} 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} temporarily changes the @t{LC_NUMERIC} 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.
+
+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} in that environment, the calling program is
+responsible for changing the @t{LC_NUMERIC} category of the locale to
+the "C" locale before reading or writing a configuration.
+
+@node Compiling Using pkg-config, , Internationalization Issues, Introduction
+@comment  node-name,  next,  previous,  up
+@section Compiling Using pkg-config
+
+On UNIX systems you can use the @i{pkg-config} utility (version 0.20
+or later) to automatically select the appropriate compiler and linker
+switches for @i{libconfig}. Ensure that the environment variable
+@samp{PKG_CONFIG_PATH} contains the absolute path to the
+@file{lib/pkgconfig} subdirectory of the @i{libconfig} installation. Then,
+you can compile and link C programs with @i{libconfig} as follows:
+
+@example
+gcc `pkg-config --cflags libconfig` myprogram.c -o myprogram \
+    `pkg-config --libs libconfig`
+@end example
+@sp 1
+
+And similarly, for C++ programs:
+
+@example
+g++ `pkg-config --cflags libconfig++` myprogram.cpp -o myprogram \
+    `pkg-config --libs libconfig++`
+@end example
+
+@sp 1
+Note the backticks in the above examples.
+
+@node Configuration Files, The C API, Introduction, Top
+@comment  node-name,  next,  previous,  up
+@menu
+* Settings::
+* Groups::
+* Arrays::
+* Lists::
+* Integer Values::
+* 64-bit Integer Values::
+* Floating Point Values::
+* Boolean Values::
+* String Values::
+* Comments::
+@end menu
+@chapter Configuration Files
+
+@i{Libconfig} supports structured, hierarchical configurations. These
+configurations can be read from and written to files and manipulated
+in memory.
+
+@cindex setting
+@cindex value
+@cindex scalar value
+@cindex array
+@cindex group
+@cindex list
+@cindex configuration
+A @dfn{configuration} consists of a group of @dfn{settings}, which
+associate names with values. A @dfn{value} can be one of the
+following:
+
+@itemize @bullet
+@item A @dfn{scalar value}: integer, 64-bit integer, floating-point number, boolean,
+or string
+@item An @dfn{array}, which is a sequence of scalar values, all of which must have the same type
+@item A @dfn{group}, which is a collection of settings
+@item A @dfn{list}, which is a sequence of values of any type, including other lists
+@end itemize
+
+Consider the following configuration file for a hypothetical GUI
+application, which illustrates all of the elements of the configuration
+file grammar.
+
+@sp 1
+@cartouche
+@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;
+  @};
+@};
+@end smallexample
+@end cartouche
+@sp 1
+
+@cindex path
+Settings can be uniquely identified within the configuration by a
+@dfn{path}. 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.
+
+For example, in our hypothetical configuration file, the path to the
+@code{x} setting is @code{application.window.pos.x}; the path to the
+@code{version} setting is simply @code{version}; and the path to the
+@code{title} setting of the second book in the @code{books} list is
+@code{application.books.[1].title}.
+
+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{true},
+@code{FALSE}, or @code{false} (or any other mixed-case version of
+those tokens, e.g., @code{True} or @code{FaLsE}), 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.
+
+All names are case-sensitive. They may consist only of alphanumeric
+characters, dashes (@samp{-}), underscores (@samp{_}), and asterisks
+(@samp{*}), and must begin with a letter or asterisk. No other
+characters are allowed.
+
+In C and C++, integer, 64-bit integer, floating point, and string
+values are mapped to the types @code{long}, @code{long long},
+@code{double}, and @code{const char *}, respectively. The boolean type
+is mapped to @code{int} in C and @code{bool} in C++.
+
+The following sections describe the elements of the configuration file
+grammar in additional detail.
+
+@node Settings, Groups, , Configuration Files
+@comment  node-name,  next,  previous,  up
+@section Settings
+
+A setting has the form:
+
+@i{name} @b{=} @i{value} @b{;}
+
+or:
+
+@i{name} @b{:} @i{value} @b{;}
+
+The trailing semicolon is required. Whitespace is not significant.
+
+The value may be a scalar value, an array, a group, or a list.
+
+@node Groups, Arrays, Settings, Configuration Files
+@comment  node-name,  next,  previous,  up
+@section Groups
+
+A group has the form:
+
+@b{@{}
+   @i{settings ...}
+@b{@}}
+
+Groups can contain any number of settings, but each setting must have
+a unique name within the group.
+
+@node Arrays, Lists, Groups, Configuration Files
+@comment  node-name,  next,  previous,  up
+@section Arrays
+
+An array has the form:
+
+@b{[} @i{value}@b{,} @i{value ...} @b{]}
+
+An array may have zero or more elements, but the elements must all be
+scalar values of the same type.
+
+@node Lists, Integer Values, Arrays, Configuration Files
+@comment  node-name,  next,  previous,  up
+@section Lists
+
+A list has the form:
+
+@b{(} @i{value}@b{,} @i{value ...} @b{)}
+
+A list may have zero or more elements, each of which can be a scalar
+value, an array, a group, or another list.
+
+@node Integer Values, 64-bit Integer Values, Lists, Configuration Files
+@comment  node-name,  next,  previous,  up
+@section Integer Values
+
+Integers can be represented in one of two ways: as a series of one or
+more decimal digits (@samp{0} - @samp{9}), with an optional leading
+sign character (@samp{+} or @samp{-}); or as a hexadecimal value
+consisting of the characters @samp{0x} followed by a series of one or
+more hexadecimal digits (@samp{0} - @samp{9}, @samp{A} - @samp{F},
+@samp{a} - @samp{f}).
+
+@node 64-bit Integer Values, Floating Point Values, Integer Values, Configuration Files
+@comment  node-name,  next,  previous,  up
+@section 64-bit Integer Values
+
+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} indicates a 64-bit integer value 0.
+
+@node Floating Point Values, Boolean Values, 64-bit Integer Values, Configuration Files
+@comment  node-name,  next,  previous,  up
+@section Floating Point Values
+
+Floating point values consist of a series of one or more digits, one
+decimal point, an optional leading sign character (@samp{+} or
+@samp{-}), and an optional exponent. An exponent consists of the
+letter @samp{E} or @samp{e}, an optional sign character, and a series
+of one or more digits.
+
+@node Boolean Values, String Values, Floating Point Values, Configuration Files
+@comment  node-name,  next,  previous,  up
+@section Boolean Values
+
+Boolean values may have one of the following values: @samp{true},
+@samp{false}, or any mixed-case variation thereof.
+
+@node String Values, Comments, Boolean Values, Configuration Files
+@comment  node-name,  next,  previous,  up
+@section String Values
+
+String values consist of arbitrary text delimited by double
+quotes. Literal double quotes can be escaped by preceding them with a
+backslash: @samp{\"}. The escape sequences @samp{\\}, @samp{\f},
+@samp{\n}, @samp{\r}, and @samp{\t} are also recognized, and have the
+usual meaning. No other escape sequences are currently supported.
+
+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:
+
+@itemize @bullet
+@item
+@code{"The quick brown fox jumped over the lazy dog."}
+
+@item
+@code{"The quick brown fox"} @*
+@code{" jumped over the lazy dog."}
+
+@item
+@code{"The quick" /* comment */ " brown fox " // another comment} @*
+@code{"jumped over the lazy dog."}
+
+@end itemize
+@page
+@node Comments, , String Values, Configuration Files
+@comment  node-name,  next,  previous,  up
+@section Comments
+
+@cindex comment
+Three types of comments are allowed within a configuration:
+
+@itemize @bullet
+
+@item Script-style comments. All text beginning with a @samp{#} character
+to the end of the line is ignored.
+
+@item C-style comments. All text, including line breaks, between a starting
+@samp{/*} sequence and an ending @samp{*/} sequence is ignored.
+
+@item C++-style comments. All text beginning with a @samp{//} sequence to the
+end of the line is ignored.
+
+@end itemize
+
+As expected, comment delimiters appearing within quoted strings are
+treated as literal text.
+
+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.
+
+@node The C API, The C++ API, Configuration Files, Top
+@comment  node-name,  next,  previous,  up
+@chapter The C API
+
+@tindex config_t
+@tindex config_setting_t
+This chapter describes the C library API. The type @i{config_t}
+represents a configuration, and the type @i{config_setting_t} represents
+a configuration setting.
+
+The boolean values @code{CONFIG_TRUE} and @code{CONFIG_FALSE} are
+macros defined as @code{(1)} and @code{(0)}, respectively.
+
+@deftypefun void config_init (@w{config_t * @var{config}})
+@deftypefunx void config_destroy (@w{config_t * @var{config}})
+
+These functions initialize and destroy the configuration object @var{config}. 
+
+@code{config_init()} initializes @var{config} as a new, empty
+configuration.
+
+@code{config_destroy()} destroys the configuration @var{config},
+deallocating all memory associated with the configuration, but not
+including the @i{config_t} structure itself.
+
+@end deftypefun
+
+@deftypefun int config_read (@w{config_t * @var{config}}, @w{FILE * @var{stream}})
+
+This function reads and parses a configuration from the given
+@var{stream} into the configuration object @var{config}. It returns
+@code{CONFIG_TRUE} on success, or @code{CONFIG_FALSE} on failure; the
+@code{config_error_text()} and @code{config_error_line()}
+functions, described below, can be used to obtain information about the
+error.
+
+@end deftypefun
+
+@deftypefun int config_read_file (@w{config_t * @var{config}}, @w{const char * @var{filename}})
+
+This function reads and parses a configuration from the file named
+@var{filename} into the configuration object @var{config}. It returns
+@code{CONFIG_TRUE} on success, or @code{CONFIG_FALSE} on failure; the
+@code{config_error_text()} and @code{config_error_line()} functions,
+described below, can be used to obtain information about the error.
+
+@end deftypefun
+
+@deftypefun void config_write (@w{const config_t * @var{config}}, @w{FILE * @var{stream}})
+
+This function writes the configuration @var{config} to the given
+@var{stream}.
+
+@end deftypefun
+
+@deftypefun int config_write_file (@w{config_t * @var{config}}, @w{const char * @var{filename}})
+
+This function writes the configuration @var{config} to the file named
+@var{filename}. It returns @code{CONFIG_TRUE} on success, or
+@code{CONFIG_FALSE} on failure.
+
+@end deftypefun
+
+@deftypefun {const char *} config_error_text (@w{const config_t * @var{config}})
+@deftypefunx int config_error_line (@w{const config_t * @var{config}})
+
+These functions, which are implemented as macros, return the text and
+line number of the parse error, if one occurred during a call to
+@code{config_read()} or @code{config_read_file()}. Storage for the
+string returned by @code{config_error_text()} is managed by the
+library and released automatically when the configuration is
+destroyed; the string must not be freed by the caller.
+
+@end deftypefun
+
+@deftypefun void config_set_auto_convert (@w{config_t *@var{config}}, @w{int @var{flag}})
+@deftypefunx int config_get_auto_convert (@w{const config_t *@var{config}})
+
+@code{config_set_auto_convert()} enables number auto-conversion for
+the configuration @var{config} if @var{flag} is non-zero, and disables
+it otherwise. 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 feature is disabled.
+
+@code{config_get_auto_convert()} returns @code{CONFIG_TRUE} if number
+auto-conversion is currently enabled for @var{config}; otherwise it
+returns @code{CONFIG_FALSE}.
+
+@end deftypefun
+
+@deftypefun int config_lookup_int (@w{const config_t * @var{config}}, @w{const char * @var{path}}, @w{long * @var{value}})
+@deftypefunx int config_lookup_int64 (@w{const config_t * @var{config}}, @w{const char * @var{path}}, @w{long long * @var{value}})
+@deftypefunx int config_lookup_float (@w{const config_t * @var{config}}, @w{const char * @var{path}}, @w{double * @var{value}})
+@deftypefunx int config_lookup_bool (@w{const config_t * @var{config}}, @w{const char * @var{path}}, @w{int * @var{value}})
+@deftypefunx int config_lookup_string (@w{const config_t * @var{config}}, @w{const char * @var{path}}, @w{const char ** @var{value}})
+
+These functions look up the value of the setting in the configuration
+@var{config} specified by the path @var{path}. They store the value of
+the setting at @var{value} and return @code{CONFIG_TRUE} 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} unmodified and return @code{CONFIG_FALSE}.
+
+Storage for the string returned by @code{config_lookup_string()} 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.
+
+@end deftypefun
+
+@deftypefun {config_setting_t *} config_lookup (@w{const config_t * @var{config}}, @w{const char * @var{path}})
+
+This function locates the setting in the configuration @var{config}
+specified by the path @var{path}. It returns a pointer to the
+@code{config_setting_t} structure on success, or @code{NULL} if the
+setting was not found.
+
+@end deftypefun
+
+@deftypefun long config_setting_get_int (@w{const config_setting_t * @var{setting}})
+@deftypefunx {long long} config_setting_get_int64 (@w{const config_setting_t * @var{setting}})
+@deftypefunx double config_setting_get_float (@w{const config_setting_t * @var{setting}})
+@deftypefunx int config_setting_get_bool (@w{const config_setting_t * @var{setting}})
+@deftypefunx {const char *} config_setting_get_string (@w{const config_setting_t * @var{setting}})
+
+These functions return the value of the given @var{setting}. If the
+type of the setting does not match the type requested, a 0 or
+@code{NULL} value is returned. Storage for the string returned by
+@code{config_setting_get_string()} 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.
+
+@end deftypefun
+@page
+@deftypefun int config_setting_set_int (@w{config_setting_t * @var{setting}}, @w{long @var{value}})
+@deftypefunx int config_setting_set_int64 (@w{config_setting_t * @var{setting}}, @w{long long @var{value}})
+@deftypefunx int config_setting_set_float (@w{config_setting_t * @var{setting}}, @w{double @var{value}})
+@deftypefunx int config_setting_set_bool (@w{config_setting_t * @var{setting}}, @w{int @var{value}})
+@deftypefunx int config_setting_set_string (@w{config_setting_t * @var{setting}}, @w{const char * @var{value}})
+
+These functions set the value of the given @var{setting} to
+@var{value}. On success, they return @code{CONFIG_TRUE}. If
+the setting does not match the type of the value, they return
+@code{CONFIG_FALSE}. @code{config_setting_set_string()} makes a copy
+of the passed string @var{value}, so it may be subsequently freed or
+modified by the caller without affecting the value of the setting.
+
+@end deftypefun
+
+@deftypefun int config_setting_lookup_int (@w{const config_setting_t * @var{setting}}, @w{const char * @var{name}}, @w{long * @var{value}})
+@deftypefunx int config_setting_lookup_int64 (@w{const config_setting_t * @var{setting}}, @w{const char * @var{name}}, @w{long long * @var{value}})
+@deftypefunx int config_setting_lookup_float (@w{const config_setting_t * @var{setting}}, @w{const char * @var{name}}, @w{double * @var{value}})
+@deftypefunx int config_setting_lookup_bool (@w{const config_setting_t * @var{setting}}, @w{const char * @var{name}}, @w{int * @var{value}})
+@deftypefunx int config_setting_lookup_string (@w{const config_setting_t * @var{setting}}, @w{const char * @var{name}}, @w{const char ** @var{value}})
+
+These functions look up the value of the child setting named
+@var{name} of the setting @var{setting}. They store the value at
+@var{value} and return @code{CONFIG_TRUE} 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} unmodified
+and return @code{CONFIG_FALSE}.
+
+Storage for the string returned by @code{config_setting_lookup_string()} 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.
+
+@end deftypefun
+
+@deftypefun short config_setting_get_format (@w{config_setting_t * @var{setting}})
+@deftypefunx int config_setting_set_format (@w{config_setting_t * @var{setting}}, @w{short @var{format}})
+
+These functions get and set the external format for the setting @var{setting}.
+
+@tindex SettingFormat
+@cindex format
+
+The @var{format} must be one of the constants
+@code{CONFIG_FORMAT_DEFAULT} or @code{CONFIG_FORMAT_HEX}. All settings
+support the @code{CONFIG_FORMAT_DEFAULT} format. The
+@code{CONFIG_FORMAT_HEX} format specifies hexadecimal formatting for
+integer values, and hence only applies to settings of type
+@code{CONFIG_TYPE_INT} and @code{CONFIG_TYPE_INT64}.  If @var{format}
+is invalid for the given setting, it is ignored.
+
+@code{config_setting_set_format()} returns @code{CONFIG_TRUE} on
+success and @code{CONFIG_FALSE} on failure.
+
+@end deftypefun
+
+
+@deftypefun {config_setting_t *} config_setting_get_member (@w{config_setting_t * @var{setting}}, @w{const char * @var{name}})
+
+This function fetches the child setting named @var{name} from the group
+@var{setting}. It returns the requested setting on success, or
+@code{NULL} if the setting was not found or if @var{setting} is not a
+group.
+
+@end deftypefun
+
+@deftypefun {config_setting_t *} config_setting_get_elem (@w{const config_setting_t * @var{setting}}, @w{unsigned int @var{idx}})
+
+This function fetches the element at the given index @var{idx} in the
+setting @var{setting}, which must be an array, list, or group. It returns the
+requested setting on success, or @code{NULL} if @var{idx} is out of
+range or if @var{setting} is not an array, list, or group.
+
+@end deftypefun
+
+@deftypefun long config_setting_get_int_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{idx}})
+@deftypefunx {long long} config_setting_get_int64_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{idx}})
+@deftypefunx double config_setting_get_float_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{idx}})
+@deftypefunx int config_setting_get_bool_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{idx}})
+@deftypefunx {const char *} config_setting_get_string_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{idx}})
+
+These functions return the value at the specified index @var{idx} in the
+setting @var{setting}. 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{idx} is out of range, they return 0 or @code{NULL}. Storage for
+the string returned by @code{config_setting_get_string_elem()} 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.
+@end deftypefun
+
+@deftypefun {config_setting_t *} config_setting_set_int_elem (@w{config_setting_t * @var{setting}}, @w{int @var{idx}}, @w{long @var{value}})
+@deftypefunx {config_setting_t *} config_setting_set_int64_elem (@w{config_setting_t * @var{setting}}, @w{int @var{idx}}, @w{long long @var{value}})
+@deftypefunx {config_setting_t *} config_setting_set_float_elem (@w{config_setting_t * @var{setting}}, @w{int @var{idx}}, @w{double @var{value}})
+@deftypefunx {config_setting_t *} config_setting_set_bool_elem (@w{config_setting_t * @var{setting}}, @w{int @var{idx}}, @w{int @var{value}})
+@deftypefunx {config_setting_t *} config_setting_set_string_elem (@w{config_setting_t * @var{setting}}, @w{int @var{idx}}, @w{const char * @var{value}})
+
+These functions set the value at the specified index @var{idx} in the
+setting @var{setting} to @var{value}. If @var{idx} 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{idx} is out of range, they return
+@code{NULL}. @code{config_setting_set_string_elem()} makes a copy of
+the passed string @var{value}, so it may be subsequently freed or
+modified by the caller without affecting the value of the setting.
+@end deftypefun
+
+@deftypefun {config_setting_t *} config_setting_add (@w{config_setting_t * @var{parent}}, @w{const char * @var{name}}, @w{int @var{type}})
+
+This function adds a new child setting or element to the setting
+@var{parent}, which must be a group, array, or list. If @var{parent}
+is an array or list, the @var{name} parameter is ignored and may be
+@code{NULL}.
+
+The function returns the new setting on success, or @code{NULL} if
+@var{parent} is not a group, array, or list; or if there is already a
+child setting of @var{parent} named @var{name}; or if @var{type} is
+invalid.
+@end deftypefun
+
+@deftypefun int config_setting_remove (@w{config_setting_t * @var{parent}}, @w{const char * @var{name}})
+
+This function removes and destroys the setting named @var{name} from
+the parent setting @var{parent}, which must be a group. Any child
+settings of the setting are recursively destroyed as well.
+
+The function returns @code{CONFIG_TRUE} on success. If @var{parent} is
+not a group, or if it has no setting with the given name, it returns
+@code{CONFIG_FALSE}.
+
+@end deftypefun
+
+@deftypefun int config_setting_remove_elem (@w{config_setting_t * @var{parent}}, @w{unsigned int @var{idx}})
+
+This function removes the child setting at the given index @var{idx} from
+the setting @var{parent}, which must be a group, list, or array. Any
+child settings of the removed setting are recursively destroyed as
+well.
+
+The function returns @code{CONFIG_TRUE} on success. If @var{parent} is
+not a group, list, or array, or if @var{idx} is out of range, it returns
+@code{CONFIG_FALSE}.
+
+@end deftypefun
+
+@deftypefun {config_setting_t *} config_root_setting (@w{const config_t * @var{config}})
+
+This function returns the root setting for the configuration
+@var{config}. The root setting is a group.
+
+@end deftypefun
+
+@deftypefun {const char *} config_setting_name (@w{const config_setting_t * @var{setting}})
+
+This function returns the name of the given @var{setting}, or
+@code{NULL} 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.
+
+@end deftypefun
+
+@deftypefun {config_setting_t *} config_setting_parent (@w{const config_setting_t * @var{setting}})
+
+This function returns the parent setting of the given @var{setting},
+or @code{NULL} if @var{setting} is the root setting.
+
+@end deftypefun
+
+@deftypefun int config_setting_is_root (@w{const config_setting_t * @var{setting}})
+
+This function returns @code{CONFIG_TRUE} if the given @var{setting} is
+the root setting, and @code{CONFIG_FALSE} otherwise.
+
+@end deftypefun
+
+@deftypefun int config_setting_index (@w{const config_setting_t * @var{setting}})
+
+This function returns the index of the given @var{setting} within its
+parent setting. If @var{setting} is the root setting, this function
+returns -1.
+
+@end deftypefun
+
+@deftypefun int config_setting_length (@w{const config_setting_t * @var{setting}})
+
+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.
+
+@end deftypefun
+
+@deftypefun int config_setting_type (@w{const config_setting_t * @var{setting}})
+
+This function returns the type of the given @var{setting}. The return
+value is one of the constants
+@code{CONFIG_TYPE_INT}, @code{CONFIG_TYPE_INT64}, @code{CONFIG_TYPE_FLOAT},
+@code{CONFIG_TYPE_STRING}, @code{CONFIG_TYPE_BOOL},
+@code{CONFIG_TYPE_ARRAY}, @code{CONFIG_TYPE_LIST}, or @code{CONFIG_TYPE_GROUP}.
+
+@end deftypefun
+
+@deftypefun int config_setting_is_group (@w{const config_setting_t * @var{setting}})
+@deftypefunx int config_setting_is_array (@w{const config_setting_t * @var{setting}})
+@deftypefunx int config_setting_is_list (@w{const config_setting_t * @var{setting}})
+
+These convenience functions, which are implemented as macros, test if
+the setting @var{setting} is of a given type. They return
+@code{CONFIG_TRUE} or @code{CONFIG_FALSE}.
+
+@end deftypefun
+
+@deftypefun int config_setting_is_aggregate (@w{const config_setting_t * @var{setting}})
+@deftypefunx int config_setting_is_scalar (@w{const config_setting_t * @var{setting}})
+@deftypefunx int config_setting_is_number (@w{const config_setting_t * @var{setting}})
+
+@cindex aggregate value
+These convenience functions, which are implemented as macros, test if
+the setting @var{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. They return @code{CONFIG_TRUE} or
+@code{CONFIG_FALSE}.
+
+@end deftypefun
+
+@deftypefun {unsigned int} config_setting_source_line (@w{const config_setting_t * @var{setting}})
+
+This function returns the line number of the configuration file or
+stream at which the setting @var{setting} was parsed. This information
+is useful for reporting application-level errors. If the setting was
+not read from a file or stream, or if the line number is otherwise
+unavailable, the function returns 0.
+
+@end deftypefun
+
+@deftypefun void config_setting_set_hook (@w{config_setting_t * @var{setting}}, @w{void * @var{hook}})
+@deftypefunx {void *} config_setting_get_hook (@w{const config_setting_t * @var{setting}})
+
+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()}, will be called
+by the library to dispose of this data when the setting itself is
+destroyed. There is no default destructor.
+
+@end deftypefun
+
+@deftypefun void config_set_destructor (@w{config_t * @var{config}}, @w{void (* @var{destructor})(void *)})
+
+This function assigns the destructor function @var{destructor} for the
+configuration @var{config}. This function accepts a single @code{void
+*} argument and has no return value. See
+@code{config_setting_set_hook()} above for more information.
+
+@end deftypefun
+
+@node The C++ API, Configuration File Grammar, The C API, Top
+@comment  node-name,  next,  previous,  up
+@chapter The C++ API
+
+@tindex Config
+@tindex Setting
+This chapter describes the C++ library API. The class @code{Config}
+represents a configuration, and the class @code{Setting} 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.
+
+@tindex ConfigException
+The library defines a group of exceptions, all of which extend the
+common base exception @code{ConfigException}.
+
+@tindex SettingTypeException
+A @code{SettingTypeException} is thrown when the type of a setting's
+value does not match the type requested.
+
+@tindex SettingNotFoundException
+A @code{SettingNotFoundException} is thrown when a setting is not found.
+
+@tindex SettingNameException
+A @code{SettingNameException} is thrown when an attempt is made to add
+a new setting with a non-unique or invalid name.
+
+@tindex ParseException
+A @code{ParseException} is thrown when a parse error occurs while
+reading a configuration from a stream.
+
+@tindex FileIOException
+A @code{FileIOException} is thrown when an I/O error occurs while
+reading/writing a configuration from/to a file.
+
+@tindex SettingException
+@code{SettingTypeException}, @code{SettingNotFoundException}, and
+@code{SettingNameException} all extend the common base
+exception @code{SettingException}, which provides the following method:
+
+@deftypemethod SettingException {const char *} getPath ()
+
+Returns the path to the setting associated with the exception, or
+@code{NULL} if there is no applicable path.
+
+@end deftypemethod
+
+The remainder of this chapter describes the methods for manipulating
+configurations and configuration settings.
+
+@deftypemethod Config {} Config ()
+@deftypemethodx Config {} ~Config ()
+
+These methods create and destroy @code{Config} objects. 
+
+@end deftypemethod
+
+@deftypemethod Config void read (@w{FILE * @var{stream}})
+@deftypemethodx Config void write (@w{FILE * @var{stream}})
+
+The @code{read()} method reads and parses a configuration from the given
+@var{stream}. A @code{ParseException} is thrown if a parse error occurs.
+
+The @code{write()} method writes the configuration to the given @var{stream}.
+
+@end deftypemethod
+
+@deftypemethod Config void readFile (@w{const char * @var{filename}})
+@deftypemethodx Config void writeFile (@w{const char * @var{filename}})
+
+The @code{readFile()} method reads and parses a configuration from the file
+named @var{filename}. A @code{ParseException} is thrown if a parse error occurs. A
+@code{FileIOException} is thrown if the file cannot be read.
+
+The @code{writeFile()} method writes the configuration to the file
+named @var{filename}. A @code{FileIOException} is thrown if the file cannot
+be written.
+
+@end deftypemethod
+
+@deftypemethod ParseException {const char *} getError ()
+@deftypemethodx ParseException int getLine ()
+
+If a call to @code{readFile()} or @code{read()} resulted in a
+@code{ParseException}, these methods can be called on the exception
+object to obtain the text and line number of the parse error. Storage
+for the string returned by @code{getError()} is managed by the
+library; the string must not be freed by the caller.
+
+@end deftypemethod
+
+@deftypemethod Config void setAutoConvert (bool @var{flag})
+@deftypemethodx Config bool getAutoConvert ()
+
+@code{setAutoConvert()} enables number auto-conversion for the
+configuration if @var{flag} is @code{true}, and disables it
+otherwise. When this feature is enabled, an attempt to assign a
+floating point setting to an integer (or vice versa), or
+assign an integer to a floating point setting (or vice versa) will
+cause the library to silently perform the necessary conversion
+(possibly leading to loss of data), rather than throwing a
+@code{SettingTypeException}. By default this feature is disabled.
+
+@code{getAutoConvert()} returns @code{true} if number auto-conversion
+is currently enabled for the configuration; otherwise it returns
+@code{false}.
+
+@end deftypemethod
+
+@deftypemethod Config {Setting &} getRoot ()
+
+This method returns the root setting for the configuration, which is a group.
+
+@end deftypemethod
+
+@deftypemethod Config {Setting &} lookup (@w{const std::string &@var{path}})
+@deftypemethodx Config {Setting &} lookup (@w{const char * @var{path}})
+
+These methods locate the setting specified by the path @var{path}. If
+the requested setting is not found, a @code{SettingNotFoundException} is
+thrown.
+
+@end deftypemethod
+@deftypemethod Config bool exists (@w{const std::string &@var{path}})
+@deftypemethodx Config bool exists (@w{const char *@var{path}})
+
+These methods test if a setting with the given @var{path} exists in
+the configuration. They return @code{true} if the setting exists, and
+@code{false} otherwise. These methods do not throw exceptions.
+
+@end deftypemethod
+
+@deftypemethod Config bool lookupValue (@w{const char *@var{path}}, @w{bool &@var{value}})
+@deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{bool &@var{value}})
+
+@deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{int &@var{value}})
+@deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{int &@var{value}})
+
+@deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{unsigned int &@var{value}})
+@deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{unsigned int &@var{value}})
+
+@deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{long &@var{value}})
+@deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{long &@var{value}})
+
+@deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{long long &@var{value}})
+@deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{long long &@var{value}})
+
+@deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{unsigned long &@var{value}})
+@deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{unsigned long &@var{value}})
+
+@deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{float &@var{value}})
+@deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{float &@var{value}})
+
+@deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{double &@var{value}})
+@deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{double &@var{value}})
+
+@deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{const char *&@var{value}})
+@deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{const char *&@var{value}})
+
+@deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{std::string &@var{value}})
+@deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{std::string &@var{value}})
+
+These are convenience methods for looking up the value of a setting
+with the given @var{path}. If the setting is found and is of an
+appropriate type, the value is stored in @var{value} and the method
+returns @code{true}. Otherwise, @var{value} is left unmodified and the
+method returns @code{false}. These methods do not throw exceptions.
+
+Storage for @w{@i{const char *}} 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} is
+suggested.
+
+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:
+
+@sp 1
+@cartouche
+@example
+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
+@}
+@end example
+@end cartouche
+
+This approach also takes advantage of the short-circuit evaluation rules
+of C++, e.g., if the first lookup fails (returning @code{false}), the
+remaining lookups are skipped entirely.
+
+@end deftypemethod
+@page
+@deftypemethod Setting {} {operator bool()}
+@deftypemethodx Setting {} {operator int()}
+@deftypemethodx Setting {} {operator unsigned int()}
+@deftypemethodx Setting {} {operator long()}
+@deftypemethodx Setting {} {operator unsigned long()}
+@deftypemethodx Setting {} {operator long long()}
+@deftypemethodx Setting {} {operator unsigned long long()}
+@deftypemethodx Setting {} {operator float()}
+@deftypemethodx Setting {} {operator double()}
+@deftypemethodx Setting {} {operator const char *()}
+@deftypemethodx Setting {} {operator std::string()}
+
+These cast operators allow a @code{Setting} object to be assigned to a
+variable of type @i{bool} if it is of type @code{TypeBoolean};
+@i{int}, @i{unsigned int}, @i{long}, or @i{unsigned long} if it is of
+type @code{TypeInt}; @code{long long} or @code{unsigned long long} if
+it is of type @code{TypeInt64}, @i{float} or @i{double} if it is of type
+@code{TypeFloat}; or @w{@i{const char *}} or @i{std::string} if it is
+of type @code{TypeString}.
+
+Storage for @w{@i{const char *}} 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} is suggested.
+
+The following examples demonstrate this usage:
+
+@cartouche
+@example
+long width = config.lookup("application.window.size.w");
+
+bool splashScreen = config.lookup("application.splash_screen");
+
+std::string title = config.lookup("application.window.title");
+@end example
+@end cartouche
+
+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} (in which case the value will be treated as 0), or a
+double-precision value to a @i{float}. The library does not treat
+these lossy conversions as errors.
+
+Perhaps surprisingly, the following code in particular will cause a
+compiler error:
+
+@cartouche
+@example
+std::string title;
+.
+.
+.
+title = config.lookup("application.window.title");
+@end example
+@end cartouche
+
+This is because the assignment operator of @code{std::string} is being
+invoked with a @code{Setting &} as an argument. The compiler is unable
+to make an implicit conversion because both the @code{const char *}
+and the @code{std::string} cast operators of @code{Setting} are
+equally appropriate. This is not a bug in @i{libconfig}; providing
+only the @code{const char *} cast operator would resolve this
+particular ambiguity, but would cause assignments to
+@code{std::string} 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}.)
+
+The solution to this problem is to use an explicit conversion that
+avoids the construction of an intermediate @code{std::string} object,
+as follows:
+
+@cartouche
+@example
+std::string title;
+.
+.
+.
+title = (const char *)config.lookup("application.window.title");
+@end example
+@end cartouche
+
+If the assignment is invalid due to a type mismatch, a
+@code{SettingTypeException} is thrown.
+
+@end deftypemethod
+
+@deftypemethod Setting {Setting &} operator= (@w{bool @var{value}})
+@deftypemethodx Setting {Setting &} operator= (@w{int @var{value}})
+@deftypemethodx Setting {Setting &} operator= (@w{long @var{value}})
+@deftypemethodx Setting {Setting &} operator= (@w{const long long &@var{value}})
+@deftypemethodx Setting {Setting &} operator= (@w{float @var{value}})
+@deftypemethodx Setting {Setting &} operator= (@w{const double &@var{value}})
+@deftypemethodx Setting {Setting &} operator= (@w{const char *@var{value}})
+@deftypemethodx Setting {Setting &} operator= (@w{const std::string &@var{value}})
+
+These assignment operators allow values of type @i{bool}, @i{int},
+@i{long}, @i{long long}, @i{float}, @i{double}, @i{const char *}, and
+@i{std::string} to be assigned to a setting. In the case of strings,
+the library makes a copy of the passed string @var{value}, so it may
+be subsequently freed or modified by the caller without affecting the
+value of the setting.
+
+If the assignment is invalid due to a type mismatch, a
+@code{SettingTypeException} is thrown.
+
+@end deftypemethod
+
+@deftypemethod Setting {Setting &} {operator[]} (@w{int @var{idx}})
+@deftypemethodx Setting {Setting &} {operator[]} (@w{const std::string &@var{name}})
+@deftypemethodx Setting {Setting &} {operator[]} (@w{const char *@var{name}})
+
+A @code{Setting} object may be subscripted with an integer index
+@var{idx} if it is an array or list, or with either a string
+@var{name} or an integer index @var{idx} if it is a group. For example,
+the following code would produce the string @samp{Last Name} when
+applied to the example configuration in @ref{Configuration Files}.
+
+@cartouche
+@example
+Setting& setting = config.lookup("application.misc");
+const char *s = setting["columns"][0];
+@end example
+@end cartouche
+
+If the setting is not an array, list, or group, a
+@code{SettingTypeException} is thrown. If the subscript (@var{idx}
+or @var{name}) does not refer to a valid element, a
+@code{SettingNotFoundException} is thrown.
+
+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.
+
+@end deftypemethod
+
+@deftypemethod Setting bool lookupValue (@w{const char *@var{name}}, @w{bool &@var{value}})
+@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{bool &@var{value}})
+
+@deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{int &@var{value}})
+@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{int &@var{value}})
+
+@deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{unsigned int &@var{value}})
+@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{unsigned int &@var{value}})
+
+@deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{long long &@var{value}})
+@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{long long &@var{value}})
+
+@deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{unsigned long long &@var{value}})
+@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{unsigned long long &@var{value}})
+
+@deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{long &@var{value}})
+@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{long &@var{value}})
+
+@deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{unsigned long &@var{value}})
+@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{unsigned long &@var{value}})
+
+@deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{float &@var{value}})
+@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{float &@var{value}})
+
+@deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{double &@var{value}})
+@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{double &@var{value}})
+
+@deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{const char *&@var{value}})
+@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{const char *&@var{value}})
+
+@deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{std::string &@var{value}})
+@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{std::string &@var{value}})
+
+These are convenience methods for looking up the value of a child setting
+with the given @var{name}. If the setting is found and is of an
+appropriate type, the value is stored in @var{value} and the method
+returns @code{true}. Otherwise, @var{value} is left unmodified and the
+method returns @code{false}. These methods do not throw exceptions.
+
+Storage for @w{@i{const char *}} 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} is
+suggested.
+
+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:
+
+@sp 1
+@cartouche
+@example
+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
+@}
+@end example
+@end cartouche
+
+This approach also takes advantage of the short-circuit evaluation
+rules of C++, e.g., if the first lookup fails (returning @code{false}), the
+remaining lookups are skipped entirely.
+
+@end deftypemethod
+
+@deftypemethod Setting {Setting &} add (@w{const std::string &@var{name}}, @w{Setting::Type @var{type}})
+@deftypemethodx Setting {Setting &} add (@w{const char *@var{name}}, @w{Setting::Type @var{type}})
+
+These methods add a new child setting with the given @var{name} and
+@var{type} 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} is thrown. If the setting is not a group,
+a @code{SettingTypeException} is thrown.
+
+Once a setting has been created, neither its name nor type can be
+changed.
+
+@end deftypemethod
+
+@deftypemethod Setting {Setting &} add (@w{Setting::Type @var{type}})
+
+This method adds a new element to the setting, which must be of type
+@code{TypeArray} or @code{TypeList}. If the setting is an array which
+currently has zero elements, the @var{type} parameter (which must be
+@code{TypeInt}, @code{TypeInt64}, @code{TypeFloat}, @code{TypeBool},
+or @code{TypeString}) determines the type for the array; otherwise it
+must match the type of the existing elements in the array.
+
+The method returns the new setting on success. If @var{type} is a
+scalar type, the new setting will have a default value of 0, 0.0,
+@code{false}, or @code{NULL}, depending on the type.
+
+The method throws a @code{SettingTypeException} if the setting is not
+an array or list, or if @var{type} is invalid.
+
+@end deftypemethod
+
+@deftypemethod Setting void remove (@w{const std::string &@var{name}})
+@deftypemethodx Setting void remove (@w{const char *@var{name}})
+
+These methods remove the child setting with the given @var{name} from
+the setting, which must be a group. Any child settings of the removed
+setting are recursively destroyed as well.
+
+If the setting is not a group, a @code{SettingTypeException} is
+thrown.  If the setting does not have a child setting with the given
+name, a @code{SettingNotFoundException} is thrown.
+
+@end deftypemethod
+
+@deftypemethod Setting void remove (@w{unsigned int @var{idx}})
+
+This method removes the child setting at the given index @var{idx} from
+the setting, which must be a group, list, or array. Any child settings
+of the removed setting are recursively destroyed as well.
+
+If the setting is not a group, list, or array, a
+@code{SettingTypeException} is thrown.  If @var{idx} is out of range,
+a @code{SettingNotFoundException} is thrown.
+
+@end deftypemethod
+
+@deftypemethod Setting {const char *} getName ()
+
+This method returns the name of the setting, or @code{NULL} 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}.
+
+@end deftypemethod
+
+@deftypemethod Setting {std::string} getPath ()
+
+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.
+
+@end deftypemethod
+
+@deftypemethod Setting {Setting &} getParent ()
+
+This method returns the parent setting of the setting. If the setting
+is the root setting, a @code{SettingNotFoundException} is thrown.
+
+@end deftypemethod
+
+@deftypemethod Setting bool isRoot ()
+
+This method returns @code{true} if the setting is the root setting, and
+@code{false} otherwise.
+
+@end deftypemethod
+
+@deftypemethod Setting int getIndex ()
+
+This method returns the index of the setting within its parent
+setting. When applied to the root setting, this method returns -1.
+
+@end deftypemethod
+
+@deftypemethod Setting Setting::Type getType ()
+
+@tindex Setting::Type
+This method returns the type of the setting. The
+@code{Setting::Type} enumeration consists of the following constants:
+@code{TypeInt}, @code{TypeInt64}, @code{TypeFloat}, @code{TypeString},
+@code{TypeBoolean}, @code{TypeArray}, @code{TypeList}, and
+@code{TypeGroup}.
+
+@end deftypemethod
+
+@deftypemethod Setting Setting::Format getFormat ()
+@deftypemethodx Setting void setFormat (@w{Setting::Format @var{format}})
+
+These methods get and set the external format for the setting.
+
+@tindex Setting::Format
+The @var{Setting::Format} enumeration consists of the following
+constants: @code{FormatDefault} and @code{FormatHex}. All settings
+support the @code{FormatDefault} format. The @code{FormatHex} format
+specifies hexadecimal formatting for integer values, and hence only
+applies to settings of type @code{TypeInt} and @code{TypeInt64}. If
+@var{format} is invalid for the given setting, it is ignored.
+
+@end deftypemethod
+
+@deftypemethod Setting bool exists (@w{const std::string &@var{name}})
+@deftypemethodx Setting bool exists (@w{const char *@var{name}})
+
+These methods test if the setting has a child setting with the given
+@var{name}. They return @code{true} if the setting exists, and
+@code{false} otherwise. These methods do not throw exceptions.
+
+@end deftypemethod
+
+@deftypemethod Setting int getLength ()
+
+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.
+
+@end deftypemethod
+
+@deftypemethod Setting bool isGroup ()
+@deftypemethodx Setting bool isArray ()
+@deftypemethodx Setting bool isList ()
+
+These convenience methods test if a setting is of a given type.
+
+@end deftypemethod
+
+@deftypemethod Setting bool isAggregate ()
+@deftypemethodx Setting bool isScalar ()
+@deftypemethodx Setting bool isNumber ()
+
+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.
+
+@end deftypemethod
+
+@deftypemethod Setting {unsigned int} getSourceLine ()
+
+This method returns the line number of the configuration file or
+stream at which the setting was parsed. This information is useful for
+reporting application-level errors. If the setting was not read from a
+file or stream, or if the line number is otherwise unavailable, the
+method returns 0.
+
+@end deftypemethod
+
+@node Configuration File Grammar, License, The C++ API, Top
+@comment  node-name,  next,  previous,  up
+@chapter Configuration File Grammar
+
+Below is the BNF grammar for configuration files. Comments are not part
+of the grammar, and hence are not included here.
+
+@sp 1
+@example
+configuration = setting-list | empty
+
+empty =
+
+setting-list = setting | setting-list setting
+
+setting = name (":" | "=") value ";"
+
+value = scalar-value | array | list | group
+
+value-list = value | value-list "," value
+
+scalar-value = boolean | integer | integer64 | hex | hex64 | float
+               | string
+
+scalar-value-list = scalar-value | scalar-value-list "," scalar-value
+
+array = "[" (scalar-value-list | empty) "]"
+
+list = "(" (value-list | empty) ")"
+
+group = "@{" (setting-list | empty) "@}"
+@end example
+
+@sp 2
+Terminals are defined below as regular expressions:
+@sp 1
+
+@multitable @columnfractions .2 .8
+@item @code{boolean} @tab
+@code{([Tt][Rr][Uu][Ee])|([Ff][Aa][Ll][Ss][Ee])}
+@item @code{string} @tab
+@code{\"([^\"\\]|\\.)*\"}
+@item @code{name} @tab
+@code{[A-Za-z\*][-A-Za-z0-9_\*]*}
+@item @code{integer} @tab
+@code{[-+]?[0-9]+}
+@item @code{integer64} @tab
+@code{[-+]?[0-9]+L(L)?}
+@item @code{hex} @tab
+@code{0[Xx][0-9A-Fa-f]+}
+@item @code{hex64} @tab
+@code{0[Xx][0-9A-Fa-f]+L(L)?}
+@item @code{float} @tab
+@code{([-+]?([0-9]*)?\.[0-9]*([eE][-+]?[0-9]+)?)|([-+]([0-9]+)(\.[0-9]*)?[eE][-+]?[0-9]+)}
+@end multitable
+
+@node License, Function Index, Configuration File Grammar, Top
+@comment  node-name,  next,  previous,  up
+@appendix License
+
+@include LGPL.texi
+
+@node Function Index, Type Index, License, Top
+@comment  node-name,  next,  previous,  up
+@unnumbered Function Index
+
+@printindex fn
+
+@node Type Index, Concept Index, Function Index, Top
+@comment  node-name,  next,  previous,  up
+@unnumbered Type Index
+
+@printindex tp
+
+@node Concept Index, , Type Index, Top
+@comment  node-name,  next,  previous,  up
+@unnumbered Concept Index
+
+@printindex cp
+
+@bye