diff options
Diffstat (limited to 'doc/libconfig.texi')
| -rw-r--r-- | doc/libconfig.texi | 580 |
1 files changed, 445 insertions, 135 deletions
diff --git a/doc/libconfig.texi b/doc/libconfig.texi index 22f8391..c9bc9fa 100644 --- a/doc/libconfig.texi +++ b/doc/libconfig.texi @@ -1,13 +1,13 @@ \input texinfo.tex @c -*-texinfo-*- -@c +@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 edition 1.4.8 +@set update-date 4 August 2011 @set subtitle-text A Library For Processing Structured Configuration Files @set author-text Mark A.@: Lindner @@ -36,7 +36,7 @@ @page @vskip 0pt plus 1filll -Copyright @copyright{} 2005-2009 Mark A Lindner +Copyright @copyright{} 2005-2011 Mark A Lindner Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -76,6 +76,7 @@ Version @value{edition}<br> * Configuration Files:: * The C API:: * The C++ API:: +* Example Programs:: * Configuration File Grammar:: * License:: * Function Index:: @@ -92,6 +93,7 @@ Version @value{edition}<br> * Multithreading Issues:: * Internationalization Issues:: * Compiling Using pkg-config:: +* Version Test Macros:: @end menu @chapter Introduction @@ -124,7 +126,8 @@ libraries falls short in one or more ways. The main features of 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 A low-footprint implementation (just 37K for the C library and 76K for +the C++ library) that is suitable for memory-constrained systems. @item Proper documentation. @@ -138,9 +141,9 @@ To use the library from C code, include the following preprocessor directive in your source files: @sp 1 -@example +@smallexample #include <libconfig.h> -@end example +@end smallexample @sp 1 To link with the library, specify @samp{-lconfig} as an argument to the @@ -154,26 +157,26 @@ To use the library from C++, include the following preprocessor directive in your source files: @sp 1 -@example +@smallexample #include <libconfig.h++> -@end example +@end smallexample @sp 1 Or, alternatively: @sp 1 -@example +@smallexample #include <libconfig.hh> -@end example +@end smallexample @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 +@smallexample using namespace libconfig; -@end example +@end smallexample @sp 1 To link with the library, specify @samp{-lconfig++} as an argument to @@ -231,7 +234,7 @@ 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 +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. @@ -241,33 +244,85 @@ 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 +@node Compiling Using pkg-config, Version Test Macros, 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 +@code{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 +@smallexample gcc `pkg-config --cflags libconfig` myprogram.c -o myprogram \ `pkg-config --libs libconfig` -@end example +@end smallexample @sp 1 And similarly, for C++ programs: -@example +@smallexample g++ `pkg-config --cflags libconfig++` myprogram.cpp -o myprogram \ `pkg-config --libs libconfig++` -@end example +@end smallexample @sp 1 Note the backticks in the above examples. +When using @b{autoconf}, the @code{PKG_CHECK_MODULES} m4 macro may be used to check for the presence of a given version of @i{libconfig}, and set the appropriate Makefile variables automatically. For example: + +@smallexample +PKG_CHECK_MODULES([LIBCONFIGXX], [libconfig++ >= 1.4],, + AC_MSG_ERROR([libconfig++ 1.4 or newer not found.]) +) +@end smallexample + +In the above example, if @i{libconfig++} version 1.4 or newer is found, +the Makefile variables @code{LIBCONFIGXX_LIBS} and @code{LIBCONFIGXX_CFLAGS} will be +set to the appropriate compiler and linker flags for compiling with +@i{libconfig}, and if it is not found, the configure script will abort +with an error to that effect. + +@node Version Test Macros, , Compiling Using pkg-config, Introduction +@comment node-name, next, previous, up +@section Version Test Macros + +The @file{libconfig.h} header declares the following macros: + +@defmac LIBCONFIG_VER_MAJOR +@defmacx LIBCONFIG_VER_MINOR +@defmacx LIBCONFIG_VER_REVISION + +These macros represent the major version, minor version, and revision +of the @i{libconfig} library. For example, in @i{libconfig} 1.4 these +are defined as @samp{1}, @samp{4}, and @samp{0}, respectively. These +macros can be used in preprocessor directives to determine which +@i{libconfig} features and/or APIs are present. For example: + +@smallexample +#if (((LIBCONFIG_VER_MAJOR == 1) && (LIBCONFIG_VER_MINOR >= 4)) \ + || (LIBCONFIG_VER_MAJOR > 1)) + /* use features present in libconfig 1.4 and later */ +#endif +@end smallexample + +These macros were introduced in @i{libconfig} 1.4. + +@end defmac + +Similarly, the @file{libconfig.h++} header declares the following macros: + +@defmac LIBCONFIGXX_VER_MAJOR +@defmacx LIBCONFIGXX_VER_MINOR +@defmacx LIBCONFIGXX_VER_REVISION + +These macros represent the major version, minor version, and revision +of the @i{libconfig++} library. + +@end defmac + @node Configuration Files, The C API, Introduction, Top @comment node-name, next, previous, up @menu @@ -281,6 +336,7 @@ Note the backticks in the above examples. * Boolean Values:: * String Values:: * Comments:: +* Include Directives:: @end menu @chapter Configuration Files @@ -382,7 +438,7 @@ characters, dashes (@samp{-}), underscores (@samp{_}), and asterisks 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}, +values are mapped to the types @code{int}, @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++. @@ -401,7 +457,7 @@ or: @i{name} @b{:} @i{value} @b{;} -The trailing semicolon is required. Whitespace is not significant. +The trailing semicolon is optional. Whitespace is not significant. The value may be a scalar value, an array, a group, or a list. @@ -480,11 +536,19 @@ Boolean values may have one of the following values: @samp{true}, @comment node-name, next, previous, up @section String Values +@cindex escape sequence 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. +usual meaning. + +In addition, the @samp{\x} escape sequence is supported; this sequence +must be followed by @i{exactly two} hexadecimal digits, which represent an +8-bit ASCII value. For example, @samp{\xFF} represents the character +with ASCII code 0xFF. + +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 @@ -504,7 +568,7 @@ shorter strings. For example, the following constructs are equivalent: @end itemize @page -@node Comments, , String Values, Configuration Files +@node Comments, Include Directives, String Values, Configuration Files @comment node-name, next, previous, up @section Comments @@ -532,6 +596,56 @@ 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 Include Directives, , Comments, Configuration Files +@comment node-name, next, previous, up +@section Include Directives + +@cindex include directive +A configuration file may ``include'' the contents of another file +using an @i{include directive}. This directive has the effect of +inlining the contents of the named file at the point of inclusion. + +An include directive must appear on its own line in the input. It has +the form: + +@b{@@include "}@i{filename}@b{"} + +Any backslashes or double quotes in the filename must be escaped as +@samp{\\} and @samp{\"}, respectively. + +For example, consider the following two configuration files: + +@cartouche +@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"; +@end smallexample +@end cartouche + +@cartouche +@smallexample +# file: test.cfg +info: @{ + name = "Winston Churchill"; + @@include "quote.cfg" + country = "UK"; +@}; +@end smallexample +@end cartouche + +Include files may be nested to a maximum of 10 levels; exceeding this +limit results in a parse error. + +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. + @node The C API, The C++ API, Configuration Files, Top @comment node-name, next, previous, up @chapter The C API @@ -548,14 +662,14 @@ 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}. +These functions initialize and destroy the configuration object @var{config}. -@code{config_init()} initializes @var{config} as a new, empty -configuration. +@code{config_init()} initializes the @i{config_t} structure pointed to by +@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. +deallocating all memory associated with the configuration, but does not +attempt to deallocate the @i{config_t} structure itself. @end deftypefun @@ -564,9 +678,9 @@ including the @i{config_t} structure itself. 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. +@code{config_error_text()}, @code{config_error_file()}, +@code{config_error_line()}, and @code{config_error_type()} functions, +described below, can be used to obtain information about the error. @end deftypefun @@ -580,6 +694,16 @@ described below, can be used to obtain information about the error. @end deftypefun +@deftypefun int config_read_string (@w{config_t * @var{config}}, @w{const char * @var{str}}) + +This function reads and parses a configuration from the string +@var{str} 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 @@ -596,14 +720,49 @@ This function writes the configuration @var{config} to the file named @end deftypefun @deftypefun {const char *} config_error_text (@w{const config_t * @var{config}}) +@deftypefunx {const char *} config_error_file (@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. +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{config_read_string()}, or +@code{config_read_file()}. Storage for the strings returned by +@code{config_error_text()} and @code{config_error_file()} 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()} will return NULL. + +@end deftypefun + +@deftypefun config_error_t config_error_type (@w{const config_t * @var{config}}) +@tindex config_error_t +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} type is an enumeration with the +following values: @code{CONFIG_ERR_NONE}, @code{CONFIG_ERR_FILE_IO}, +@code{CONFIG_ERR_PARSE}. These represent success, a file I/O error, +and a parsing error, respectively. + +@end deftypefun + +@deftypefun void config_set_include_dir (@w{config_t *@var{config}}, @w{const char *@var{include_dir}}) +@deftypefunx {const char *} config_get_include_dir (@w{const config_t *@var{config}}) + +@code{config_set_include_dir()} specifies the include directory, +@var{include_dir}, relative to which the files specified in +@samp{@@include} directives will be located for the configuration +@var{config}. 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} is @code{NULL}, the default behavior +is reinstated. + +For example, if the include directory is set to @file{/usr/local/etc}, +the include directive @samp{@@include "configs/extra.cfg"} would include the +file @file{/usr/local/etc/configs/extra.cfg}. + +@code{config_get_include_dir()} returns the current include directory for the +configuration @var{config}, or @code{NULL} if none is set. @end deftypefun @@ -625,7 +784,33 @@ 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}}) +@deftypefun void config_set_default_format (@w{config_t * @var{config}}, @w{short @var{format}}) +@deftypefunx short config_get_default_format (@w{config_t * @var{config}}) + +These functions, which are implemented as macros, set and get the +default external format for settings in the configuration +@var{config}. If a non-default format has not been set for a setting +with @code{config_setting_set_format()}, this configuration-wide +default format will be used instead when that setting is written to a +file or stream. + +@end deftypefun + +@deftypefun void config_set_tab_width (@w{config_t * @var{config}}, @w{unsigned short @var{width}}) +@deftypefunx {unsigned short} config_get_tab_width (@w{const config_t * @var{config}}) + +These functions, which are implemented as macros, set and get the tab +width for the configuration @var{config}. 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} spaces, or +by a single tab character if @var{width} is 0. The tab width has no +effect on parsing. + +Valid tab widths range from 0 to 15. The default tab width is 2. + +@end deftypefun + +@deftypefun int config_lookup_int (@w{const config_t * @var{config}}, @w{const char * @var{path}}, @w{int * @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}}) @@ -654,7 +839,7 @@ setting was not found. @end deftypefun -@deftypefun long config_setting_get_int (@w{const config_setting_t * @var{setting}}) +@deftypefun int 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}}) @@ -669,8 +854,7 @@ 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}}) +@deftypefun int config_setting_set_int (@w{config_setting_t * @var{setting}}, @w{int @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}}) @@ -685,7 +869,7 @@ 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}}) +@deftypefun int config_setting_lookup_int (@w{const config_setting_t * @var{setting}}, @w{const char * @var{name}}, @w{int * @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}}) @@ -721,6 +905,8 @@ 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. +If a non-default format has not been set for the setting, @code{config_setting_get_format()} returns the default format for the configuration, as set by @code{config_set_default_format()}. + @code{config_setting_set_format()} returns @code{CONFIG_TRUE} on success and @code{CONFIG_FALSE} on failure. @@ -736,44 +922,44 @@ group. @end deftypefun -@deftypefun {config_setting_t *} config_setting_get_elem (@w{const config_setting_t * @var{setting}}, @w{unsigned int @var{idx}}) +@deftypefun {config_setting_t *} config_setting_get_elem (@w{const config_setting_t * @var{setting}}, @w{unsigned int @var{index}}) -This function fetches the element at the given index @var{idx} in the +This function fetches the element at the given index @var{index} 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 +requested setting on success, or @code{NULL} if @var{index} 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}}) +@deftypefun int config_setting_get_int_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{index}}) +@deftypefunx {long long} config_setting_get_int64_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{index}}) +@deftypefunx double config_setting_get_float_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{index}}) +@deftypefunx int config_setting_get_bool_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{index}}) +@deftypefunx {const char *} config_setting_get_string_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{index}}) -These functions return the value at the specified index @var{idx} in the +These functions return the value at the specified index @var{index} 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 +@var{index} 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}}) +@deftypefun {config_setting_t *} config_setting_set_int_elem (@w{config_setting_t * @var{setting}}, @w{int @var{index}}, @w{int @var{value}}) +@deftypefunx {config_setting_t *} config_setting_set_int64_elem (@w{config_setting_t * @var{setting}}, @w{int @var{index}}, @w{long long @var{value}}) +@deftypefunx {config_setting_t *} config_setting_set_float_elem (@w{config_setting_t * @var{setting}}, @w{int @var{index}}, @w{double @var{value}}) +@deftypefunx {config_setting_t *} config_setting_set_bool_elem (@w{config_setting_t * @var{setting}}, @w{int @var{index}}, @w{int @var{value}}) +@deftypefunx {config_setting_t *} config_setting_set_string_elem (@w{config_setting_t * @var{setting}}, @w{int @var{index}}, @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 +These functions set the value at the specified index @var{index} in the +setting @var{setting} to @var{value}. If @var{index} 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 +value, or if @var{index} 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. @@ -789,7 +975,8 @@ is an array or list, the @var{name} parameter is ignored and may be 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. +invalid. If @var{type} is a scalar type, the new setting will have a +default value of 0, 0.0, @code{false}, or @code{NULL}, as appropriate. @end deftypefun @deftypefun int config_setting_remove (@w{config_setting_t * @var{parent}}, @w{const char * @var{name}}) @@ -804,15 +991,15 @@ not a group, or if it has no setting with the given name, it returns @end deftypefun -@deftypefun int config_setting_remove_elem (@w{config_setting_t * @var{parent}}, @w{unsigned int @var{idx}}) +@deftypefun int config_setting_remove_elem (@w{config_setting_t * @var{parent}}, @w{unsigned int @var{index}}) -This function removes the child setting at the given index @var{idx} from +This function removes the child setting at the given index @var{index} 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 +not a group, list, or array, or if @var{index} is out of range, it returns @code{CONFIG_FALSE}. @end deftypefun @@ -897,13 +1084,23 @@ floating point), respectively. They return @code{CONFIG_TRUE} or @end deftypefun +@deftypefun {const char *} config_setting_source_file (@w{const config_setting_t * @var{setting}}) + +This function returns the name of the file from which the setting +@var{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. + +@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. +stream at which the setting @var{setting} was read, or 0 if no line +number is available. This information is useful for reporting +application-level errors. @end deftypefun @@ -928,7 +1125,7 @@ configuration @var{config}. This function accepts a single @code{void @end deftypefun -@node The C++ API, Configuration File Grammar, The C API, Top +@node The C++ API, Example Programs, The C API, Top @comment node-name, next, previous, up @chapter The C++ API @@ -999,9 +1196,10 @@ The @code{write()} method writes the configuration to the given @var{stream}. @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{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 @@ -1009,14 +1207,43 @@ be written. @end deftypemethod +@deftypemethod Config void readString (@w{const char * @var{str}}) +@deftypemethodx Config void readString (@w{const std::string &@var{str}}) + +These methods read and parse a configuration from the string +@var{str}. A @code{ParseException} is thrown if a parse error occurs. + +@end deftypemethod + @deftypemethod ParseException {const char *} getError () +@deftypemethodx ParseException {const char *} getFile () @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. +If a call to @code{readFile()}, @code{readString()}, or @code{read()} +resulted in a @code{ParseException}, 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()} +and @code{getFile()} are managed by the library; the strings must not +be freed by the caller. + +@end deftypemethod + +@deftypemethod Config void setIncludeDir (@w{const char *@var{includeDir}}) +@deftypemethodx Config {const char *} getIncludeDir () + +@code{setIncludeDir()} specifies the include directory, +@var{includeDir}, relative to which the files specified in +@samp{@@include} 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} is @code{NULL}, the default behavior is reinstated. + +For example, if the include directory is set to @file{/usr/local/etc}, +the include directive @samp{@@include "configs/extra.cfg"} would include the +file @file{/usr/local/etc/configs/extra.cfg}. + +@code{getIncludeDir()} returns the current include directory for the +configuration, or @code{NULL} if none is set. @end deftypemethod @@ -1038,6 +1265,30 @@ is currently enabled for the configuration; otherwise it returns @end deftypemethod +@deftypemethod Config void setDefaultFormat (@w{Setting::Format @var{format}}) +@deftypemethodx Config Setting::Format getDefaultFormat () + +These methods set and get 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()}, this configuration-wide +default format will be used instead when that setting is written to a +file or stream. + +@end deftypemethod + +@deftypemethod Config void setTabWidth (@w{unsigned short @var{width}}) +@deftypemethodx Config {unsigned short} getTabWidth () + +These methods set and get 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} +spaces, or by a single tab character if @var{width} is 0. The tab +width has no effect on parsing. + +Valid tab widths range from 0 to 15. The default tab width is 2. + +@end deftypemethod + @deftypemethod Config {Setting &} getRoot () This method returns the root setting for the configuration, which is a group. @@ -1070,15 +1321,9 @@ the configuration. They return @code{true} if the setting exists, and @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}}) @@ -1111,7 +1356,7 @@ wrong type: @sp 1 @cartouche -@example +@smallexample int var1; double var2; const char *var3; @@ -1126,7 +1371,7 @@ else @{ // error handling here @} -@end example +@end smallexample @end cartouche This approach also takes advantage of the short-circuit evaluation rules @@ -1134,27 +1379,31 @@ 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()} + +@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 ()} +@deftypemethodx Setting {const char *} c_str () 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 +@i{int}, @i{unsigned int}; @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}. +Values of type @code{TypeInt} or @code{TypeInt64} may be assigned to +variables of type @i{long}, or @i{unsigned long}, depending on the +sizes of those types on the host system. + 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 @@ -1164,13 +1413,13 @@ values to a @code{std::string} is suggested. The following examples demonstrate this usage: @cartouche -@example +@smallexample 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 smallexample @end cartouche Note that certain conversions can lead to loss of precision or @@ -1183,13 +1432,13 @@ Perhaps surprisingly, the following code in particular will cause a compiler error: @cartouche -@example +@smallexample std::string title; . . . title = config.lookup("application.window.title"); -@end example +@end smallexample @end cartouche This is because the assignment operator of @code{std::string} is being @@ -1208,13 +1457,25 @@ avoids the construction of an intermediate @code{std::string} object, as follows: @cartouche -@example +@smallexample std::string title; . . . title = (const char *)config.lookup("application.window.title"); -@end example +@end smallexample +@end cartouche + +Or, alternatively, use the @code{c_str()} method, which has the same effect: + +@cartouche +@smallexample +std::string title; +. +. +. +title = config.lookup("application.window.title").c_str(); +@end smallexample @end cartouche If the assignment is invalid due to a type mismatch, a @@ -1238,30 +1499,40 @@ 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. +The following example code looks up a (presumably) integer setting +and changes its value: + +@cartouche +@smallexample +Setting &setting = config.lookup("application.window.size.w"); +setting = 1024; +@end smallexample +@end cartouche + 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}}) +@deftypemethod Setting {Setting &} {operator[]} (@w{int @var{index}}) @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, +@var{index} if it is an array or list, or with either a string +@var{name} or an integer index @var{index} 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 +@smallexample Setting& setting = config.lookup("application.misc"); const char *s = setting["columns"][0]; -@end example +@end smallexample @end cartouche If the setting is not an array, list, or group, a -@code{SettingTypeException} is thrown. If the subscript (@var{idx} +@code{SettingTypeException} is thrown. If the subscript (@var{index} or @var{name}) does not refer to a valid element, a @code{SettingNotFoundException} is thrown. @@ -1286,12 +1557,6 @@ configuration. @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}}) @@ -1324,7 +1589,7 @@ wrong type: @sp 1 @cartouche -@example +@smallexample int var1; double var2; const char *var3; @@ -1339,7 +1604,7 @@ else @{ // error handling here @} -@end example +@end smallexample @end cartouche This approach also takes advantage of the short-circuit evaluation @@ -1374,7 +1639,7 @@ 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. +@code{false}, or @code{NULL}, as appropriate. The method throws a @code{SettingTypeException} if the setting is not an array or list, or if @var{type} is invalid. @@ -1394,14 +1659,14 @@ name, a @code{SettingNotFoundException} is thrown. @end deftypemethod -@deftypemethod Setting void remove (@w{unsigned int @var{idx}}) +@deftypemethod Setting void remove (@w{unsigned int @var{index}}) -This method removes the child setting at the given index @var{idx} from +This method removes the child setting at the given index @var{index} 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, +@code{SettingTypeException} is thrown. If @var{index} is out of range, a @code{SettingNotFoundException} is thrown. @end deftypemethod @@ -1507,32 +1772,75 @@ integer, or floating point), respectively. @end deftypemethod +@deftypemethod Setting {const char *} getSourceFile () + +This function 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. + +@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. +This function returns the line number of the configuration file or +stream at which the setting @var{setting} was read, or 0 if no line +number is available. This information is useful for reporting +application-level errors. @end deftypemethod -@node Configuration File Grammar, License, The C++ API, Top +@node Example Programs, Configuration File Grammar, The C++ API, Top +@comment node-name, next, previous, up +@chapter Example Programs + +Practical example programs that illustrate how to use @i{libconfig} +from both C and C++ are included in the @file{examples} subdirectory +of the distribution. These examples include: + +@table @file + +@item examples/c/example1.c +An example C program that reads a configuration from an existing file +@file{example.cfg} (also located in @file{examples/c}) and displays +some of its contents. + +@item examples/c++/example1.cpp +The C++ equivalent of @file{example1.c}. + +@item examples/c/example2.c +An example C program that reads a configuration from an existing file +@file{example.cfg} (also located in @file{examples/c}), adds new +settings to the configuration, and writes the updated configuration to +another file. + +@item examples/c++/example2.cpp +The C++ equivalent of @file{example2.c} + +@item examples/c/example3.c +An example C program that constructs a new configuration in memory and writes it to a file. + +@item examples/c++/example3.cpp +The C++ equivalent of @file{example3.c} + +@end table + +@node Configuration File Grammar, License, Example Programs, 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. +Below is the BNF grammar for configuration files. Comments and include +directives are not part of the grammar, so they are not included here. @sp 1 @example configuration = setting-list | empty -empty = - setting-list = setting | setting-list setting -setting = name (":" | "=") value ";" +setting = name (":" | "=") value (";" | "," | empty) value = scalar-value | array | list | group @@ -1548,6 +1856,8 @@ array = "[" (scalar-value-list | empty) "]" list = "(" (value-list | empty) ")" group = "@{" (setting-list | empty) "@}" + +empty = @end example @sp 2 |