1\input texinfo.tex @c -*-texinfo-*- 2@c 3@c %**start of header 4 5@c All text is ignored before the setfilename. 6@setfilename libconfig.info 7@settitle libconfig 8 9@set edition 1.7.3 10@set update-date 20 Jun 2021 11@set subtitle-text A Library For Processing Structured Configuration Files 12@set author-text Mark A.@: Lindner 13 14@comment %**end of header 15 16@firstparagraphindent insert 17 18@dircategory Software libraries 19@direntry 20* libconfig: (libconfig). A Library For Processing Structured Configuration Files 21@end direntry 22 23 24@tex 25\global\emergencystretch = .3\hsize 26@end tex 27 28@setchapternewpage odd 29 30@titlepage 31 32@title libconfig 33@subtitle @value{subtitle-text} 34@subtitle Version @value{edition} 35@subtitle @value{update-date} 36 37@author @value{author-text} 38 39@page 40@vskip 0pt plus 1filll 41Copyright @copyright{} 2004-2021 Mark A Lindner 42 43Permission is granted to make and distribute verbatim copies of 44this manual provided the copyright notice and this permission notice 45are preserved on all copies. 46 47Permission is granted to copy and distribute modified versions of this 48manual under the conditions for verbatim copying, provided that the entire 49resulting derived work is distributed under the terms of a permission 50notice identical to this one. 51 52@end titlepage 53 54@c Give the HTML output a title page that somewhat resembles the printed one 55@ifhtml 56@html 57<hr noshade size=6 color="black"> 58<div align=right>@value{subtitle-text}<br> 59Version @value{edition}<br> 60@value{update-date}</div> 61<br><br><br><br> 62<font size=+1>@value{author-text}</font> 63<hr size=3 noshade color="black"> 64<br><br> 65@end html 66@end ifhtml 67 68@contents 69 70@ifnottex 71@node Top 72@comment node-name, next, previous, up 73@top libconfig 74@end ifnottex 75 76@menu 77* Introduction:: 78* Configuration Files:: 79* The C API:: 80* The C++ API:: 81* Example Programs:: 82* Other Bindings and Implementations:: 83* License:: 84* Configuration File Grammar:: 85* Function Index:: 86* Type Index:: 87* Concept Index:: 88@end menu 89 90@node Introduction, Configuration Files, Top, Top 91@comment node-name, next, previous, up 92@menu 93* Why Another Configuration File Library?:: 94* Using the Library from a C Program:: 95* Using the Library from a C++ Program:: 96* Multithreading Issues:: 97* Internationalization Issues:: 98* Compiling Using pkg-config:: 99* Version Test Macros:: 100@end menu 101@chapter Introduction 102 103@i{Libconfig} is a library for reading, manipulating, and writing 104structured configuration files. The library features a fully 105reentrant parser and includes bindings for both the C and C++ 106programming languages. 107 108The library runs on modern POSIX-compilant systems, such as Linux, 109Solaris, and Mac OS X (Darwin), as well as on Microsoft Windows 1102000/XP and later (with either Microsoft Visual Studio 2005 or later, 111or the GNU toolchain via the MinGW environment). 112 113@node Why Another Configuration File Library?, Using the Library from a C Program, , Introduction 114@comment node-name, next, previous, up 115@section Why Another Configuration File Library? 116 117There are several open-source configuration file libraries available 118as of this writing. This library was written because each of those 119libraries falls short in one or more ways. The main features of 120@i{libconfig} that set it apart from the other libraries are: 121 122@itemize @bullet 123 124@item A fully reentrant parser. Independent configurations can be parsed in concurrent threads at the same time. 125 126@item Both C @i{and} C++ bindings, as well as hooks to allow for the creation of wrappers in other languages. 127 128@item A simple, structured configuration file format that is more 129readable and compact than XML and more flexible than the obsolete but 130prevalent Windows ``INI'' file format. 131 132@item A low-footprint implementation (just 37K for the C library and 76K for 133the C++ library) that is suitable for memory-constrained systems. 134 135@item Proper documentation. 136 137@end itemize 138 139@node Using the Library from a C Program, Using the Library from a C++ Program, Why Another Configuration File Library?, Introduction 140@comment node-name, next, previous, up 141@section Using the Library from a C Program 142 143To use the library from C code, include the following preprocessor 144directive in your source files: 145 146@sp 1 147@smallexample 148#include <libconfig.h> 149@end smallexample 150@sp 1 151 152To link with the library, specify @samp{-lconfig} as an argument to the 153linker. 154 155@node Using the Library from a C++ Program, Multithreading Issues, Using the Library from a C Program, Introduction 156@comment node-name, next, previous, up 157@section Using the Library from a C++ Program 158 159To use the library from C++, include the following preprocessor 160directive in your source files: 161 162@sp 1 163@smallexample 164#include <libconfig.h++> 165@end smallexample 166@sp 1 167 168Or, alternatively: 169 170@sp 1 171@smallexample 172#include <libconfig.hh> 173@end smallexample 174@sp 1 175@page 176The C++ API classes are defined in the namespace @samp{libconfig}, hence the 177following statement may optionally be used: 178 179@sp 1 180@smallexample 181using namespace libconfig; 182@end smallexample 183@sp 1 184 185To link with the library, specify @samp{-lconfig++} as an argument to 186the linker. 187 188@node Multithreading Issues, Internationalization Issues, Using the Library from a C++ Program, Introduction 189@comment node-name, next, previous, up 190@section Multithreading Issues 191 192@i{Libconfig} is fully @dfn{reentrant}; the functions in the library 193do not make use of global variables and do not maintain state between 194successive calls. Therefore two independent configurations may be safely 195manipulated concurrently by two distinct threads. 196 197@i{Libconfig} is not @dfn{thread-safe}. The library is not aware of 198the presence of threads and knows nothing about the host system's 199threading model. Therefore, if an instance of a configuration is to be 200accessed from multiple threads, it must be suitably protected by 201synchronization mechanisms like read-write locks or mutexes; the 202standard rules for safe multithreaded access to shared data must be 203observed. 204 205@i{Libconfig} is not @dfn{async-safe}. Calls should not be made into 206the library from signal handlers, because some of the C library 207routines that it uses may not be async-safe. 208 209@i{Libconfig} is not guaranteed to be @dfn{cancel-safe}. Since it is 210not aware of the host system's threading model, the library does not 211contain any thread cancellation points. In most cases this will not be 212an issue for multithreaded programs. However, be aware that some of 213the routines in the library (namely those that read/write 214configurations from/to files or streams) perform I/O using C library 215routines which may potentially block; whether or not these C library 216routines are cancel-safe depends on the host system. 217 218@node Internationalization Issues, Compiling Using pkg-config, Multithreading Issues, Introduction 219@comment node-name, next, previous, up 220@section Internationalization Issues 221 222@cindex Unicode 223@cindex UTF-8 224@i{Libconfig} does not natively support Unicode configuration files, 225but string values may contain Unicode text encoded in UTF-8; such 226strings will be treated as ordinary 8-bit ASCII text by the 227library. It is the responsibility of the calling program to perform 228the necessary conversions to/from wide (@t{wchar_t}) strings using the 229wide string conversion functions such as @t{mbsrtowcs()} and 230@t{wcsrtombs()} or the @t{iconv()} function of the @i{libiconv} 231library. 232 233@cindex locale 234The textual representation of a floating point value varies by 235locale. However, the @i{libconfig} grammar specifies that 236floating point values are represented using a period (`.') as the 237radix symbol; this is consistent with the grammar of most programming 238languages. When a configuration is read in or written out, 239@i{libconfig} temporarily changes the @t{LC_NUMERIC} category of the 240locale of the calling thread to the ``C'' locale to ensure consistent 241handling of floating point values regardless of the locale(s) in use 242by the calling program. 243 244Note that the MinGW environment does not (as of this writing) provide 245functions for changing the locale of the calling thread. Therefore, 246when using @i{libconfig} in that environment, the calling program is 247responsible for changing the @t{LC_NUMERIC} category of the locale to 248the "C" locale before reading or writing a configuration. 249 250@node Compiling Using pkg-config, Version Test Macros, Internationalization Issues, Introduction 251@comment node-name, next, previous, up 252@section Compiling Using pkg-config 253 254@cindex pkg-config 255On UNIX systems you can use the @i{pkg-config} utility (version 0.20 256or later) to automatically select the appropriate compiler and linker 257switches for @i{libconfig}. Ensure that the environment variable 258@code{PKG_CONFIG_PATH} contains the absolute path to the 259@file{lib/pkgconfig} subdirectory of the @i{libconfig} installation. Then, 260you can compile and link C programs with @i{libconfig} as follows: 261 262@smallexample 263gcc `pkg-config --cflags libconfig` myprogram.c -o myprogram \ 264 `pkg-config --libs libconfig` 265@end smallexample 266@sp 1 267 268And similarly, for C++ programs: 269 270@smallexample 271g++ `pkg-config --cflags libconfig++` myprogram.cpp -o myprogram \ 272 `pkg-config --libs libconfig++` 273@end smallexample 274 275@sp 1 276Note the backticks in the above examples. 277 278When 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: 279 280@smallexample 281PKG_CHECK_MODULES([LIBCONFIGXX], [libconfig++ >= 1.4],, 282 AC_MSG_ERROR([libconfig++ 1.4 or newer not found.]) 283) 284@end smallexample 285 286In the above example, if @i{libconfig++} version 1.4 or newer is found, 287the Makefile variables @code{LIBCONFIGXX_LIBS} and @code{LIBCONFIGXX_CFLAGS} will be 288set to the appropriate compiler and linker flags for compiling with 289@i{libconfig}, and if it is not found, the configure script will abort 290with an error to that effect. 291 292@node Version Test Macros, , Compiling Using pkg-config, Introduction 293@comment node-name, next, previous, up 294@section Version Test Macros 295 296The @file{libconfig.h} header declares the following macros: 297 298@defmac LIBCONFIG_VER_MAJOR 299@defmacx LIBCONFIG_VER_MINOR 300@defmacx LIBCONFIG_VER_REVISION 301 302These macros represent the major version, minor version, and revision 303of the @i{libconfig} library. For example, in @i{libconfig} 1.4 these 304are defined as @samp{1}, @samp{4}, and @samp{0}, respectively. These 305macros can be used in preprocessor directives to determine which 306@i{libconfig} features and/or APIs are present. For example: 307 308@smallexample 309#if (((LIBCONFIG_VER_MAJOR == 1) && (LIBCONFIG_VER_MINOR >= 4)) \ 310 || (LIBCONFIG_VER_MAJOR > 1)) 311 /* use features present in libconfig 1.4 and later */ 312#endif 313@end smallexample 314 315These macros were introduced in @i{libconfig} 1.4. 316 317@end defmac 318 319Similarly, the @file{libconfig.h++} header declares the following macros: 320 321@defmac LIBCONFIGXX_VER_MAJOR 322@defmacx LIBCONFIGXX_VER_MINOR 323@defmacx LIBCONFIGXX_VER_REVISION 324 325These macros represent the major version, minor version, and revision 326of the @i{libconfig++} library. 327 328@end defmac 329 330@node Configuration Files, The C API, Introduction, Top 331@comment node-name, next, previous, up 332@menu 333* Settings:: 334* Groups:: 335* Arrays:: 336* Lists:: 337* Integer Values:: 338* 64-bit Integer Values:: 339* Floating Point Values:: 340* Boolean Values:: 341* String Values:: 342* Comments:: 343* Include Directives:: 344@end menu 345@chapter Configuration Files 346 347@i{Libconfig} supports structured, hierarchical configurations. These 348configurations can be read from and written to files and manipulated 349in memory. 350 351@cindex setting 352@cindex value 353@cindex scalar value 354@cindex array 355@cindex group 356@cindex list 357@cindex configuration 358A @dfn{configuration} consists of a group of @dfn{settings}, which 359associate names with values. A @dfn{value} can be one of the 360following: 361 362@itemize @bullet 363@item A @dfn{scalar value}: integer, 64-bit integer, floating-point number, boolean, 364or string 365@item An @dfn{array}, which is a sequence of scalar values, all of which must have the same type 366@item A @dfn{group}, which is a collection of settings 367@item A @dfn{list}, which is a sequence of values of any type, including other lists 368@end itemize 369 370Consider the following configuration file for a hypothetical GUI 371application, which illustrates all of the elements of the configuration 372file grammar. 373 374@sp 1 375@cartouche 376@smallexample 377# Example application configuration file 378 379version = "1.0"; 380 381application: 382@{ 383 window: 384 @{ 385 title = "My Application"; 386 size = @{ w = 640; h = 480; @}; 387 pos = @{ x = 350; y = 250; @}; 388 @}; 389 390 list = ( ( "abc", 123, true ), 1.234, ( /* an empty list */ ) ); 391 392 books = ( @{ title = "Treasure Island"; 393 author = "Robert Louis Stevenson"; 394 price = 29.95; 395 qty = 5; @}, 396 @{ title = "Snow Crash"; 397 author = "Neal Stephenson"; 398 price = 9.99; 399 qty = 8; @} ); 400 401 misc: 402 @{ 403 pi = 3.141592654; 404 bigint = 9223372036854775807L; 405 columns = [ "Last Name", "First Name", "MI" ]; 406 bitmask = 0x1FC3; // hex 407 umask = 0027; // octal. Range limited to that of "int" 408 @}; 409@}; 410@end smallexample 411@end cartouche 412@sp 1 413 414@cindex path 415Settings can be uniquely identified within the configuration by a 416@dfn{path}. The path is a dot-separated sequence of names, beginning 417at a top-level group and ending at the setting itself. Each name in 418the path is the name of a setting; if the setting has no name because 419it is an element in a list or array, an integer index in square 420brackets can be used as the name. 421 422For example, in our hypothetical configuration file, the path to the 423@code{x} setting is @code{application.window.pos.x}; the path to the 424@code{version} setting is simply @code{version}; and the path to the 425@code{title} setting of the second book in the @code{books} list is 426@code{application.books.[1].title}. 427 428The datatype of a value is determined from the format of the value 429itself. If the value is enclosed in double quotes, it is treated as a 430string. If it looks like an integer or floating point number, it is 431treated as such. If it is one of the values @code{TRUE}, @code{true}, 432@code{FALSE}, or @code{false} (or any other mixed-case version of 433those tokens, e.g., @code{True} or @code{FaLsE}), it is treated as a 434boolean. If it consists of a comma-separated list of values enclosed 435in square brackets, it is treated as an array. And if it consists of a 436comma-separated list of values enclosed in parentheses, it is treated 437as a list. Any value which does not meet any of these criteria is 438considered invalid and results in a parse error. 439 440All names are case-sensitive. They may consist only of alphanumeric 441characters, dashes (@samp{-}), underscores (@samp{_}), and asterisks 442(@samp{*}), and must begin with a letter or asterisk. No other 443characters are allowed. 444 445In C and C++, integer, 64-bit integer, floating point, and string 446values are mapped to the native types @code{int}, @code{long long}, 447@code{double}, and @code{const char *}, respectively. The boolean type 448is mapped to @code{int} in C and @code{bool} in C++. 449 450The following sections describe the elements of the configuration file 451grammar in additional detail. 452 453@node Settings, Groups, , Configuration Files 454@comment node-name, next, previous, up 455@section Settings 456 457A setting has the form: 458 459@i{name} @b{=} @i{value} @b{;} 460 461or: 462 463@i{name} @b{:} @i{value} @b{;} 464 465The trailing semicolon is optional. Whitespace is not significant. 466 467The value may be a scalar value, an array, a group, or a list. 468 469@node Groups, Arrays, Settings, Configuration Files 470@comment node-name, next, previous, up 471@section Groups 472 473A group has the form: 474 475@b{@{} 476 @i{settings ...} 477@b{@}} 478 479Groups can contain any number of settings, but each setting must have 480a unique name within the group. 481 482@node Arrays, Lists, Groups, Configuration Files 483@comment node-name, next, previous, up 484@section Arrays 485 486An array has the form: 487 488@b{[} @i{value}@b{,} @i{value ...} @b{]} 489 490An array may have zero or more elements, but the elements must all be 491scalar values of the same type. 492 493The last element in an array may be followed by a comma, which will be ignored. 494 495@node Lists, Integer Values, Arrays, Configuration Files 496@comment node-name, next, previous, up 497@section Lists 498 499A list has the form: 500 501@b{(} @i{value}@b{,} @i{value ...} @b{)} 502 503A list may have zero or more elements, each of which can be a scalar 504value, an array, a group, or another list. 505 506The last element in a list may be followed by a comma, which will be ignored. 507 508@node Integer Values, 64-bit Integer Values, Lists, Configuration Files 509@comment node-name, next, previous, up 510@section Integer Values 511 512Integers can be represented in one of two ways: as a series of one or 513more decimal digits (@samp{0} - @samp{9}), with an optional leading 514sign character (@samp{+} or @samp{-}); or as a hexadecimal value 515consisting of the characters @samp{0x} followed by a series of one or 516more hexadecimal digits (@samp{0} - @samp{9}, @samp{A} - @samp{F}, 517@samp{a} - @samp{f}). Additionally, octal notation integers (that is, 518those having a leading zero with non-zero value) are also allowed. 519 520@node 64-bit Integer Values, Floating Point Values, Integer Values, Configuration Files 521@comment node-name, next, previous, up 522@section 64-bit Integer Values 523 524Long long (64-bit) integers are represented identically to integers, 525except that an `L' character is appended to indicate a 64-bit 526value. For example, @samp{0L} indicates a 64-bit integer value 0. As 527of version 1.5 of the library, the trailing `L' is optional; if the 528integer value exceeds the range of a 32-bit integer, it will 529automatically be interpreted as a 64-bit integer. 530 531The @i{integer} and @i{64-bit integer} setting types are interchangeable to the 532extent that a conversion between the corresponding native types would not 533result in an overflow or underflow. For example, a @i{long long} value can be 534written to a setting that has an @i{integer} type, if that value is within the 535range of an @i{int}. This rule applies to every API function or method that 536reads a value from or writes a value to a setting: if the type conversion would 537not result in an overflow or underflow, then the call will succeed, and 538otherwise it will fail. This behavior was not well-defined prior to version 1.7 539of the library. 540 541@node Floating Point Values, Boolean Values, 64-bit Integer Values, Configuration Files 542@comment node-name, next, previous, up 543@section Floating Point Values 544 545Floating point values consist of a series of one or more digits, one 546decimal point, an optional leading sign character (@samp{+} or 547@samp{-}), and an optional exponent. An exponent consists of the 548letter @samp{E} or @samp{e}, an optional sign character, and a series 549of one or more digits. 550 551@node Boolean Values, String Values, Floating Point Values, Configuration Files 552@comment node-name, next, previous, up 553@section Boolean Values 554 555Boolean values may have one of the following values: @samp{true}, 556@samp{false}, or any mixed-case variation thereof. 557 558@node String Values, Comments, Boolean Values, Configuration Files 559@comment node-name, next, previous, up 560@section String Values 561 562@cindex escape sequence 563String values consist of arbitrary text delimited by double 564quotes. Literal double quotes can be escaped by preceding them with a 565backslash: @samp{\"}. The escape sequences @samp{\\}, @samp{\f}, 566@samp{\n}, @samp{\r}, and @samp{\t} are also recognized, and have the 567usual meaning. 568 569In addition, the @samp{\x} escape sequence is supported; this sequence 570must be followed by @i{exactly two} hexadecimal digits, which represent an 5718-bit ASCII value. For example, @samp{\xFF} represents the character 572with ASCII code 0xFF. 573 574No other escape sequences are currently supported. 575 576Adjacent strings are automatically concatenated, as in C/C++ source 577code. This is useful for formatting very long strings as sequences of 578shorter strings. For example, the following constructs are equivalent: 579 580@itemize @bullet 581@item 582@code{"The quick brown fox jumped over the lazy dog."} 583 584@item 585@code{"The quick brown fox"} @* 586@code{" jumped over the lazy dog."} 587 588@item 589@code{"The quick" /* comment */ " brown fox " // another comment} @* 590@code{"jumped over the lazy dog."} 591 592@end itemize 593@page 594@node Comments, Include Directives, String Values, Configuration Files 595@comment node-name, next, previous, up 596@section Comments 597 598@cindex comment 599Three types of comments are allowed within a configuration: 600 601@itemize @bullet 602 603@item Script-style comments. All text beginning with a @samp{#} character 604to the end of the line is ignored. 605 606@item C-style comments. All text, including line breaks, between a starting 607@samp{/*} sequence and an ending @samp{*/} sequence is ignored. 608 609@item C++-style comments. All text beginning with a @samp{//} sequence to the 610end of the line is ignored. 611 612@end itemize 613 614As expected, comment delimiters appearing within quoted strings are 615treated as literal text. 616 617Comments are ignored when the configuration is read in, so they are 618not treated as part of the configuration. Therefore if the 619configuration is written back out to a stream, any comments that were 620present in the original configuration will be lost. 621 622 623@node Include Directives, , Comments, Configuration Files 624@comment node-name, next, previous, up 625@section Include Directives 626 627@cindex include directive 628A configuration file may ``include'' the contents of other files 629using an @i{include directive}. This directive has the effect of 630inlining the contents of the named file(s) at the point of inclusion. 631 632An include directive must appear on its own line in the input. It has 633the form: 634 635@b{@@include "}@i{path}@b{"} 636 637@cindex include function 638The interpretation of @i{path} depends on the currently registered 639@i{include function}. The default include function prepends the include 640directory, if any, to @i{path}, and then interprets the result as a single, 641literal file path. The application may supply its own include function which 642does variable substitution, wildcard expansion, or other transformations, 643returning a list of zero or more paths to files whose contents should be inlined 644at the point of inclusion. 645 646Any backslashes or double quotes in the path must be escaped as 647@samp{\\} and @samp{\"}, respectively. 648 649For example, consider the following two configuration files: 650 651@cartouche 652@smallexample 653# file: quote.cfg 654quote = "Criticism may not be agreeable, but it is necessary." 655 " It fulfils the same function as pain in the human" 656 " body. It calls attention to an unhealthy state of" 657 " things.\n" 658 "\t--Winston Churchill"; 659@end smallexample 660@end cartouche 661 662@cartouche 663@smallexample 664# file: test.cfg 665info: @{ 666 name = "Winston Churchill"; 667 @@include "quote.cfg" 668 country = "UK"; 669@}; 670@end smallexample 671@end cartouche 672 673The resulting configuration will be equivalent to one in which the 674contents of the file @samp{quote.cfg} appeared at the point where the 675include directive is placed. 676 677Include files may be nested to a maximum of 10 levels; exceeding this 678limit results in a parse error. 679 680When the path argument to an @b{@@include} directive is a relative 681path, then it will be interpreted as being relative to the include 682directory that has been been set by means of 683@code{config_set_include_dir()}. If no include directory has been set, 684then it will be taken as being relative to the program's current 685working directory. 686 687Like comments, include directives are not part of the configuration 688file syntax. They are processed before the configuration itself is 689parsed. Therefore, they are not preserved when the configuration is 690written back out to a stream. There is presently no support for 691programmatically inserting include directives into a configuration. 692 693@node The C API, The C++ API, Configuration Files, Top 694@comment node-name, next, previous, up 695@chapter The C API 696 697@tindex config_t 698@tindex config_setting_t 699This chapter describes the C library API. The type @i{config_t} 700represents a configuration, and the type @i{config_setting_t} represents 701a configuration setting. 702 703The boolean values @code{CONFIG_TRUE} and @code{CONFIG_FALSE} are 704macros defined as @code{(1)} and @code{(0)}, respectively. 705 706@deftypefun void config_init (@w{config_t * @var{config}}) 707@deftypefunx void config_destroy (@w{config_t * @var{config}}) 708 709These functions initialize and destroy the configuration object @var{config}. 710 711@code{config_init()} initializes the @i{config_t} structure pointed to by 712@var{config} as a new, empty configuration. 713 714@code{config_destroy()} destroys the configuration @var{config}, 715deallocating all memory associated with the configuration, but does not 716attempt to deallocate the @i{config_t} structure itself. 717 718@end deftypefun 719 720@deftypefun void config_clear (@w{config_t * @var{config}}) 721 722@b{Since @i{v1.7}} 723 724This function clears the configuration @var{config}. All child settings of the 725root setting are recursively destroyed. All other attributes of the configuration 726are left unchanged. 727 728@end deftypefun 729 730@deftypefun int config_read (@w{config_t * @var{config}}, @w{FILE * @var{stream}}) 731 732This function reads and parses a configuration from the given 733@var{stream} into the configuration object @var{config}. It returns 734@code{CONFIG_TRUE} on success, or @code{CONFIG_FALSE} on failure; the 735@code{config_error_text()}, @code{config_error_file()}, 736@code{config_error_line()}, and @code{config_error_type()} functions, 737described below, can be used to obtain information about the error. 738 739@end deftypefun 740 741@deftypefun int config_read_file (@w{config_t * @var{config}}, @w{const char * @var{filename}}) 742 743This function reads and parses a configuration from the file named 744@var{filename} into the configuration object @var{config}. It returns 745@code{CONFIG_TRUE} on success, or @code{CONFIG_FALSE} on failure; the 746@code{config_error_text()} and @code{config_error_line()} functions, 747described below, can be used to obtain information about the error. 748 749@end deftypefun 750 751@deftypefun int config_read_string (@w{config_t * @var{config}}, @w{const char * @var{str}}) 752 753This function reads and parses a configuration from the string 754@var{str} into the configuration object @var{config}. It returns 755@code{CONFIG_TRUE} on success, or @code{CONFIG_FALSE} on failure; the 756@code{config_error_text()} and @code{config_error_line()} functions, 757described below, can be used to obtain information about the error. 758 759@end deftypefun 760 761@deftypefun void config_write (@w{const config_t * @var{config}}, @w{FILE * @var{stream}}) 762 763This function writes the configuration @var{config} to the given 764@var{stream}. 765 766@end deftypefun 767 768@deftypefun int config_write_file (@w{config_t * @var{config}}, @w{const char * @var{filename}}) 769 770This function writes the configuration @var{config} to the file named 771@var{filename}. It returns @code{CONFIG_TRUE} on success, or 772@code{CONFIG_FALSE} on failure. 773 774@end deftypefun 775 776@deftypefun {const char *} config_error_text (@w{const config_t * @var{config}}) 777@deftypefunx {const char *} config_error_file (@w{const config_t * @var{config}}) 778@deftypefunx int config_error_line (@w{const config_t * @var{config}}) 779 780These functions, which are implemented as macros, return the text, 781filename, and line number of the parse error, if one occurred during a 782call to @code{config_read()}, @code{config_read_string()}, or 783@code{config_read_file()}. Storage for the strings returned by 784@code{config_error_text()} and @code{config_error_file()} are managed 785by the library and released automatically when the configuration is 786destroyed; these strings must not be freed by the caller. If the error 787occurred in text that was read from a string or stream, 788@code{config_error_file()} will return NULL. 789 790@end deftypefun 791 792@deftypefun config_error_t config_error_type (@w{const config_t * @var{config}}) 793@tindex config_error_t 794This function, which is implemented as a macro, returns the type of 795error that occurred during the last call to one of the read or write 796functions. The @var{config_error_t} type is an enumeration with the 797following values: @code{CONFIG_ERR_NONE}, @code{CONFIG_ERR_FILE_IO}, 798@code{CONFIG_ERR_PARSE}. These represent success, a file I/O error, 799and a parsing error, respectively. 800 801@end deftypefun 802 803@deftypefun void config_set_include_dir (@w{config_t *@var{config}}, @w{const char *@var{include_dir}}) 804@deftypefunx {const char *} config_get_include_dir (@w{const config_t *@var{config}}) 805 806@code{config_set_include_dir()} specifies the include directory, 807@var{include_dir}, relative to which the files specified in 808@samp{@@include} directives will be located for the configuration 809@var{config}. By default, there is no include directory, and all 810include files are expected to be relative to the current working 811directory. If @var{include_dir} is @code{NULL}, the default behavior 812is reinstated. 813 814For example, if the include directory is set to @file{/usr/local/etc}, 815the include directive @samp{@@include "configs/extra.cfg"} would include the 816file @file{/usr/local/etc/configs/extra.cfg}. 817 818@code{config_get_include_dir()} returns the current include directory for the 819configuration @var{config}, or @code{NULL} if none is set. 820 821@end deftypefun 822 823@deftypefun void config_set_include_func (@w{config_include_fn_t @var{func}}) 824 825@b{Since @i{v1.7}} 826 827Specifies the include function @var{func} to use when processing 828include directives. If @var{func} is @code{NULL}, the default include function, 829@code{config_default_include_func()}, will be reinstated. 830 831@tindex config_include_fn_t 832The type @i{config_include_fn_t} is a type alias 833for a function whose signature is: 834 835@deftypefun @w{const char **} func (@w{config_t *@var{config}}, @w{const char *@var{include_dir}}, @w{const char *@var{path}}, @w{const char **@var{error}}) 836 837The function receives the configuration @var{config}, the 838configuration's current include directory @var{include_dir}, the 839argument to the include directive @var{path}; and a pointer at which 840to return an error message @var{error}. 841 842On success, the function should return a @code{NULL}-terminated array 843of paths. Any relative paths must be relative to the program's current 844working directory. The contents of these files will be inlined at the point 845of inclusion, in the order that the paths appear in the 846array. Both the array and its elements should be heap allocated; the 847library will take ownership of and eventually free the strings in the 848array and the array itself. 849 850On failure, the function should return @code{NULL} and set @var{*error} to a 851static error string which should be used as the parse error for the 852configuration; the library does not take ownership of or free this string. 853 854The default include function, @code{config_default_include_func()}, 855simply returns a @code{NULL}-terminated array containing either a copy 856of @var{path} if it's an absolute path, or a concatenation of 857@var{include_dir} and @var{path} if it's a relative path. 858 859@end deftypefun 860 861Application-supplied include functions can perform custom tasks like wildcard 862expansion or variable substitution. For example, consider the include directive: 863 864@cartouche 865@smallexample 866@@include "configs/*.cfg" 867@end smallexample 868@end cartouche 869 870The include function would be invoked with the path @samp{configs/*.cfg} and 871could do wildcard expansion on that path, returning a list of paths to files 872with the file extension @samp{.cfg} in the subdirectory @samp{configs}. Each of 873these files would then be inlined at the location of the include directive. 874 875Tasks like wildcard expansion and variable substitution are non-trivial to 876implement and typically require platform-specific code. In the interests of 877keeping the library as compact and platform-independent as possible, 878implementations of such include functions are not included. 879 880@end deftypefun 881 882@deftypefun {unsigned short} config_get_float_precision(@w{config_t *@var{config}}) 883@deftypefunx void config_set_float_precision(@w{config_t *@var{config}}, @w{unsigned short @var{digits}}) 884 885@b{Since @i{v1.6}} 886 887These functions get and set the number of decimal digits to output after the 888radix character when writing the configuration to a file or stream. 889 890Valid values for @var{digits} range from 0 (no decimals) to about 15 891(implementation defined). This parameter has no effect on parsing. 892 893The default float precision is 6. 894 895@end deftypefun 896 897@deftypefun int config_get_options (@w{config_t *@var{config}}) 898@deftypefunx void config_set_options (@w{config_t *@var{config}}, @w{int @var{options}}) 899 900These functions get and set the options for the configuration 901@var{config}. The options affect how configurations are read and 902written. The following options are defined: 903 904@table @code 905 906@item CONFIG_OPTION_AUTOCONVERT 907Turning this option on enables number auto-conversion for 908the configuration. When this feature is enabled, an attempt to retrieve a 909floating point setting's value into an integer (or vice versa), or 910store an integer to a floating point setting's value (or vice versa) 911will cause the library to silently perform the necessary conversion 912(possibly leading to loss of data), rather than reporting failure. By 913default this option is turned off. 914 915@item CONFIG_OPTION_SEMICOLON_SEPARATORS 916This option controls whether a semicolon (`;') is output after each setting 917when the configuration is written to a file or stream. (The semicolon 918separators are optional in the configuration syntax.) By default this 919option is turned on. 920 921@item CONFIG_OPTION_COLON_ASSIGNMENT_FOR_GROUPS 922This option controls whether a colon (`:') is output between each 923group setting's name and its value when the configuration is written to 924a file or stream. If the option is turned off, an equals sign (`=') is 925output instead. (These tokens are interchangeable in the configuration 926syntax.) By default this option is turned on. 927 928@item CONFIG_OPTION_COLON_ASSIGNMENT_FOR_NON_GROUPS 929This option controls whether a colon (`:') is output between each 930non-group setting's name and its value when the configuration is written 931to a file or stream. If the option is turned off, an equals sign (`=') 932is output instead. (These tokens are interchangeable in the configuration 933syntax.) By default this option is turned off. 934 935@item CONFIG_OPTION_OPEN_BRACE_ON_SEPARATE_LINE 936This option controls whether an open brace (`@{') will be written on its own 937line when the configuration is written to a file or stream. If the option is 938turned off, the brace will be written at the end of the previous line. 939By default this option is turned on. 940 941@item CONFIG_OPTION_ALLOW_SCIENTIFIC_NOTATION 942(@b{Since @i{v1.7}}) 943This option controls whether scientific notation may be used as appropriate 944when writing floating point values (corresponding to @code{printf()} 945@samp{%g} format) or should never be used (corresponding to @code{printf()} 946@samp{%f} format). By default this option is turned off. 947 948@item CONFIG_OPTION_FSYNC 949(@b{Since @i{v1.7.1}}) 950This option controls whether the @code{config_write_file()} function performs 951an @i{fsync} operation after writing the configuration and before closing the 952file. By default this option is turned off. 953 954@item CONFIG_OPTION_ALLOW_OVERRIDES 955(@b{Since @i{v1.7.3}}) 956This option controls whether duplicate settings override previous settings 957with the same name. If this option is turned off, duplicate settings are 958rejected. By default this option is turned off. 959 960@end table 961 962@end deftypefun 963 964@deftypefun int config_get_option (@w{config_t *@var{config}}, @w{int @var{option}}) 965@deftypefunx void config_set_option (@w{config_t *@var{config}}, @w{int @var{option}}, @w{int @var{flag}}) 966 967@b{Since @i{v1.7}} 968 969These functions get and set the given @var{option} of the configuration 970@var{config}. The option is enabled if @var{flag} is @code{CONFIG_TRUE} and 971disabled if it is @code{CONFIG_FALSE}. 972 973See @code{config_set_options()} above for the list of available options. 974 975@end deftypefun 976 977 978@deftypefun int config_get_auto_convert (@w{const config_t *@var{config}}) 979@deftypefunx void config_set_auto_convert (@w{config_t *@var{config}}, @w{int @var{flag}}) 980 981These functions get and set the @code{CONFIG_OPTION_AUTO_CONVERT} 982option. They are obsoleted by the @code{config_set_option()} and 983@code{config_get_option()} functions described above. 984 985@end deftypefun 986 987@deftypefun short config_get_default_format (@w{config_t * @var{config}}) 988@deftypefunx void config_set_default_format (@w{config_t * @var{config}}, @w{short @var{format}}) 989 990These functions, which are implemented as macros, get and set the 991default external format for settings in the configuration 992@var{config}. If a non-default format has not been set for a setting 993with @code{config_setting_set_format()}, this configuration-wide 994default format will be used instead when that setting is written to a 995file or stream. 996 997@end deftypefun 998 999@deftypefun {unsigned short} config_get_tab_width (@w{const config_t * @var{config}}) 1000@deftypefunx void config_set_tab_width (@w{config_t * @var{config}}, @w{unsigned short @var{width}}) 1001 1002These functions, which are implemented as macros, get and set the tab 1003width for the configuration @var{config}. The tab width affects the 1004formatting of the configuration when it is written to a file or 1005stream: each level of nesting is indented by @var{width} spaces, or 1006by a single tab character if @var{width} is 0. The tab width has no 1007effect on parsing. 1008 1009Valid tab widths range from 0 to 15. The default tab width is 2. 1010 1011@end deftypefun 1012 1013@deftypefun int config_lookup_int (@w{const config_t * @var{config}}, @w{const char * @var{path}}, @w{int * @var{value}}) 1014@deftypefunx int config_lookup_int64 (@w{const config_t * @var{config}}, @w{const char * @var{path}}, @w{long long * @var{value}}) 1015@deftypefunx int config_lookup_float (@w{const config_t * @var{config}}, @w{const char * @var{path}}, @w{double * @var{value}}) 1016@deftypefunx int config_lookup_bool (@w{const config_t * @var{config}}, @w{const char * @var{path}}, @w{int * @var{value}}) 1017@deftypefunx int config_lookup_string (@w{const config_t * @var{config}}, @w{const char * @var{path}}, @w{const char ** @var{value}}) 1018 1019These functions look up the value of the setting in the configuration 1020@var{config} specified by the path @var{path}. They store the value of 1021the setting at @var{value} and return @code{CONFIG_TRUE} on 1022success. If the setting was not found or if the type of the value did 1023not match the type requested, they leave the data pointed to by 1024@var{value} unmodified and return @code{CONFIG_FALSE}. 1025 1026Storage for the string returned by @code{config_lookup_string()} is 1027managed by the library and released automatically when the setting is 1028destroyed or when the setting's value is changed; the string must not 1029be freed by the caller. 1030 1031@end deftypefun 1032 1033@deftypefun {config_setting_t *} config_lookup (@w{const config_t * @var{config}}, @w{const char * @var{path}}) 1034 1035This function locates the setting in the configuration @var{config} 1036specified by the path @var{path}. It returns a pointer to the 1037@code{config_setting_t} structure on success, or @code{NULL} if the 1038setting was not found. 1039 1040@end deftypefun 1041 1042@deftypefun {config_setting_t *} config_setting_lookup (@w{const config_setting_t * @var{setting}}, @w{const char * @var{path}}) 1043 1044This function locates a setting by a path @var{path} relative to 1045the setting @var{setting}. It returns a pointer to the 1046@code{config_setting_t} structure on success, or @code{NULL} if the 1047setting was not found. 1048 1049@end deftypefun 1050 1051@deftypefun int config_setting_get_int (@w{const config_setting_t * @var{setting}}) 1052@deftypefunx {long long} config_setting_get_int64 (@w{const config_setting_t * @var{setting}}) 1053@deftypefunx double config_setting_get_float (@w{const config_setting_t * @var{setting}}) 1054@deftypefunx int config_setting_get_bool (@w{const config_setting_t * @var{setting}}) 1055@deftypefunx {const char *} config_setting_get_string (@w{const config_setting_t * @var{setting}}) 1056 1057These functions return the value of the given @var{setting}. If the 1058type of the setting does not match the type requested, a 0 or 1059@code{NULL} value is returned. Storage for the string returned by 1060@code{config_setting_get_string()} is managed by the library and 1061released automatically when the setting is destroyed or when the 1062setting's value is changed; the string must not be freed by the 1063caller. 1064 1065@end deftypefun 1066@deftypefun int config_setting_set_int (@w{config_setting_t * @var{setting}}, @w{int @var{value}}) 1067@deftypefunx int config_setting_set_int64 (@w{config_setting_t * @var{setting}}, @w{long long @var{value}}) 1068@deftypefunx int config_setting_set_float (@w{config_setting_t * @var{setting}}, @w{double @var{value}}) 1069@deftypefunx int config_setting_set_bool (@w{config_setting_t * @var{setting}}, @w{int @var{value}}) 1070@deftypefunx int config_setting_set_string (@w{config_setting_t * @var{setting}}, @w{const char * @var{value}}) 1071 1072These functions set the value of the given @var{setting} to 1073@var{value}. On success, they return @code{CONFIG_TRUE}. If 1074the setting does not match the type of the value, they return 1075@code{CONFIG_FALSE}. @code{config_setting_set_string()} makes a copy 1076of the passed string @var{value}, so it may be subsequently freed or 1077modified by the caller without affecting the value of the setting. 1078 1079@end deftypefun 1080 1081@deftypefun int config_setting_lookup_int (@w{const config_setting_t * @var{setting}}, @w{const char * @var{name}}, @w{int * @var{value}}) 1082@deftypefunx int config_setting_lookup_int64 (@w{const config_setting_t * @var{setting}}, @w{const char * @var{name}}, @w{long long * @var{value}}) 1083@deftypefunx int config_setting_lookup_float (@w{const config_setting_t * @var{setting}}, @w{const char * @var{name}}, @w{double * @var{value}}) 1084@deftypefunx int config_setting_lookup_bool (@w{const config_setting_t * @var{setting}}, @w{const char * @var{name}}, @w{int * @var{value}}) 1085@deftypefunx int config_setting_lookup_string (@w{const config_setting_t * @var{setting}}, @w{const char * @var{name}}, @w{const char ** @var{value}}) 1086 1087These functions look up the value of the child setting named 1088@var{name} of the setting @var{setting}. They store the value at 1089@var{value} and return @code{CONFIG_TRUE} on success. If the setting 1090was not found or if the type of the value did not match the type 1091requested, they leave the data pointed to by @var{value} unmodified 1092and return @code{CONFIG_FALSE}. 1093 1094Storage for the string returned by @code{config_setting_lookup_string()} is 1095managed by the library and released automatically when the setting is 1096destroyed or when the setting's value is changed; the string must not 1097be freed by the caller. 1098 1099@end deftypefun 1100 1101@deftypefun short config_setting_get_format (@w{config_setting_t * @var{setting}}) 1102@deftypefunx int config_setting_set_format (@w{config_setting_t * @var{setting}}, @w{short @var{format}}) 1103 1104These functions get and set the external format for the setting @var{setting}. 1105 1106@tindex SettingFormat 1107@cindex format 1108 1109The @var{format} must be one of the constants 1110@code{CONFIG_FORMAT_DEFAULT} or @code{CONFIG_FORMAT_HEX}. All settings 1111support the @code{CONFIG_FORMAT_DEFAULT} format. The 1112@code{CONFIG_FORMAT_HEX} format specifies hexadecimal formatting for 1113integer values, and hence only applies to settings of type 1114@code{CONFIG_TYPE_INT} and @code{CONFIG_TYPE_INT64}. If @var{format} 1115is invalid for the given setting, it is ignored. 1116 1117If 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()}. 1118 1119@code{config_setting_set_format()} returns @code{CONFIG_TRUE} on 1120success and @code{CONFIG_FALSE} on failure. 1121 1122@end deftypefun 1123 1124 1125@deftypefun {config_setting_t *} config_setting_get_member (@w{config_setting_t * @var{setting}}, @w{const char * @var{name}}) 1126 1127This function fetches the child setting named @var{name} from the group 1128@var{setting}. It returns the requested setting on success, or 1129@code{NULL} if the setting was not found or if @var{setting} is not a 1130group. 1131 1132@end deftypefun 1133 1134@deftypefun {config_setting_t *} config_setting_get_elem (@w{const config_setting_t * @var{setting}}, @w{unsigned int @var{index}}) 1135 1136This function fetches the element at the given index @var{index} in the 1137setting @var{setting}, which must be an array, list, or group. It returns the 1138requested setting on success, or @code{NULL} if @var{index} is out of 1139range or if @var{setting} is not an array, list, or group. 1140 1141@end deftypefun 1142 1143@deftypefun int config_setting_get_int_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{index}}) 1144@deftypefunx {long long} config_setting_get_int64_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{index}}) 1145@deftypefunx double config_setting_get_float_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{index}}) 1146@deftypefunx int config_setting_get_bool_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{index}}) 1147@deftypefunx {const char *} config_setting_get_string_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{index}}) 1148 1149These functions return the value at the specified index @var{index} in the 1150setting @var{setting}. If the setting is not an array or list, or if 1151the type of the element does not match the type requested, or if 1152@var{index} is out of range, they return 0 or @code{NULL}. Storage for 1153the string returned by @code{config_setting_get_string_elem()} is 1154managed by the library and released automatically when the setting is 1155destroyed or when its value is changed; the string must not be freed 1156by the caller. 1157@end deftypefun 1158 1159@deftypefun {config_setting_t *} config_setting_set_int_elem (@w{config_setting_t * @var{setting}}, @w{int @var{index}}, @w{int @var{value}}) 1160@deftypefunx {config_setting_t *} config_setting_set_int64_elem (@w{config_setting_t * @var{setting}}, @w{int @var{index}}, @w{long long @var{value}}) 1161@deftypefunx {config_setting_t *} config_setting_set_float_elem (@w{config_setting_t * @var{setting}}, @w{int @var{index}}, @w{double @var{value}}) 1162@deftypefunx {config_setting_t *} config_setting_set_bool_elem (@w{config_setting_t * @var{setting}}, @w{int @var{index}}, @w{int @var{value}}) 1163@deftypefunx {config_setting_t *} config_setting_set_string_elem (@w{config_setting_t * @var{setting}}, @w{int @var{index}}, @w{const char * @var{value}}) 1164 1165These functions set the value at the specified index @var{index} in the 1166setting @var{setting} to @var{value}. If @var{index} is negative, a 1167new element is added to the end of the array or list. On success, 1168these functions return a pointer to the setting representing the 1169element. If the setting is not an array or list, or if the setting is 1170an array and the type of the array does not match the type of the 1171value, or if @var{index} is out of range, they return 1172@code{NULL}. @code{config_setting_set_string_elem()} makes a copy of 1173the passed string @var{value}, so it may be subsequently freed or 1174modified by the caller without affecting the value of the setting. 1175@end deftypefun 1176 1177@deftypefun {config_setting_t *} config_setting_add (@w{config_setting_t * @var{parent}}, @w{const char * @var{name}}, @w{int @var{type}}) 1178 1179This function adds a new child setting or element to the setting 1180@var{parent}, which must be a group, array, or list. If @var{parent} 1181is an array or list, the @var{name} parameter is ignored and may be 1182@code{NULL}. 1183 1184The function returns the new setting on success, or @code{NULL} if 1185@var{parent} is not a group, array, or list; or if there is already a 1186child setting of @var{parent} named @var{name}; or if @var{type} is 1187invalid. If @var{type} is a scalar type, the new setting will have a 1188default value of 0, 0.0, @code{false}, or @code{NULL}, as appropriate. 1189@end deftypefun 1190 1191@deftypefun int config_setting_remove (@w{config_setting_t * @var{parent}}, @w{const char * @var{name}}) 1192 1193This function removes and destroys the setting named @var{name} from 1194the parent setting @var{parent}, which must be a group. Any child 1195settings of the setting are recursively destroyed as well. 1196 1197The @var{name} parameter can also specify a setting @i{path} relative to 1198the provided @var{parent}. 1199(In that case, the setting will be looked up and removed.) 1200 1201The function returns @code{CONFIG_TRUE} on success. If @var{parent} is 1202not a group, or if it has no setting with the given name, it returns 1203@code{CONFIG_FALSE}. 1204 1205@end deftypefun 1206 1207@deftypefun int config_setting_remove_elem (@w{config_setting_t * @var{parent}}, @w{unsigned int @var{index}}) 1208 1209This function removes the child setting at the given index @var{index} from 1210the setting @var{parent}, which must be a group, list, or array. Any 1211child settings of the removed setting are recursively destroyed as 1212well. 1213 1214The function returns @code{CONFIG_TRUE} on success. If @var{parent} is 1215not a group, list, or array, or if @var{index} is out of range, it returns 1216@code{CONFIG_FALSE}. 1217 1218@end deftypefun 1219 1220@deftypefun {config_setting_t *} config_root_setting (@w{const config_t * @var{config}}) 1221 1222This function, which is implemented as a macro, returns the root setting for the configuration @var{config}. The root setting is a group. 1223 1224@end deftypefun 1225 1226@deftypefun {const char *} config_setting_name (@w{const config_setting_t * @var{setting}}) 1227 1228This function returns the name of the given @var{setting}, or 1229@code{NULL} if the setting has no name. Storage for the returned 1230string is managed by the library and released automatically when the 1231setting is destroyed; the string must not be freed by the caller. 1232 1233@end deftypefun 1234 1235@deftypefun {config_setting_t *} config_setting_parent (@w{const config_setting_t * @var{setting}}) 1236 1237This function returns the parent setting of the given @var{setting}, 1238or @code{NULL} if @var{setting} is the root setting. 1239 1240@end deftypefun 1241 1242@deftypefun int config_setting_is_root (@w{const config_setting_t * @var{setting}}) 1243 1244This function returns @code{CONFIG_TRUE} if the given @var{setting} is 1245the root setting, and @code{CONFIG_FALSE} otherwise. 1246 1247@end deftypefun 1248 1249@deftypefun int config_setting_index (@w{const config_setting_t * @var{setting}}) 1250 1251This function returns the index of the given @var{setting} within its 1252parent setting. If @var{setting} is the root setting, this function 1253returns -1. 1254 1255@end deftypefun 1256 1257@deftypefun int config_setting_length (@w{const config_setting_t * @var{setting}}) 1258 1259This function returns the number of settings in a group, or the number of 1260elements in a list or array. For other types of settings, it returns 12610. 1262 1263@end deftypefun 1264 1265@deftypefun int config_setting_type (@w{const config_setting_t * @var{setting}}) 1266 1267This function returns the type of the given @var{setting}. The return 1268value is one of the constants 1269@code{CONFIG_TYPE_INT}, @code{CONFIG_TYPE_INT64}, @code{CONFIG_TYPE_FLOAT}, 1270@code{CONFIG_TYPE_STRING}, @code{CONFIG_TYPE_BOOL}, 1271@code{CONFIG_TYPE_ARRAY}, @code{CONFIG_TYPE_LIST}, or @code{CONFIG_TYPE_GROUP}. 1272 1273@end deftypefun 1274 1275@deftypefun int config_setting_is_group (@w{const config_setting_t * @var{setting}}) 1276@deftypefunx int config_setting_is_array (@w{const config_setting_t * @var{setting}}) 1277@deftypefunx int config_setting_is_list (@w{const config_setting_t * @var{setting}}) 1278 1279These convenience functions, which are implemented as macros, test if 1280the setting @var{setting} is of a given type. They return 1281@code{CONFIG_TRUE} or @code{CONFIG_FALSE}. 1282 1283@end deftypefun 1284 1285@deftypefun int config_setting_is_aggregate (@w{const config_setting_t * @var{setting}}) 1286@deftypefunx int config_setting_is_scalar (@w{const config_setting_t * @var{setting}}) 1287@deftypefunx int config_setting_is_number (@w{const config_setting_t * @var{setting}}) 1288 1289@cindex aggregate value 1290These convenience functions, some of which are implemented as macros, test if 1291the setting @var{setting} is of an aggregate type (a group, array, or 1292list), of a scalar type (integer, 64-bit integer, floating point, 1293boolean, or string), and of a number (integer, 64-bit integer, or 1294floating point), respectively. They return @code{CONFIG_TRUE} or 1295@code{CONFIG_FALSE}. 1296 1297@end deftypefun 1298 1299@deftypefun {const char *} config_setting_source_file (@w{const config_setting_t * @var{setting}}) 1300 1301This function returns the name of the file from which the setting 1302@var{setting} was read, or NULL if the setting was not read from a 1303file. This information is useful for reporting application-level 1304errors. Storage for the returned string is managed by the library and 1305released automatically when the configuration is destroyed; the 1306string must not be freed by the caller. 1307 1308@end deftypefun 1309 1310@deftypefun {unsigned int} config_setting_source_line (@w{const config_setting_t * @var{setting}}) 1311 1312This function returns the line number of the configuration file or 1313stream at which the setting @var{setting} was read, or 0 if no line 1314number is available. This information is useful for reporting 1315application-level errors. 1316 1317@end deftypefun 1318 1319@deftypefun void config_set_hook (@w{config_t * @var{config}}, @w{void * @var{hook}}) 1320@deftypefunx {void *} config_get_hook (@w{const config_t * @var{config}}) 1321 1322@b{Since @i{v1.7}} 1323 1324@cindex hook 1325These functions make it possible to attach arbitrary data to a configuration 1326structure, for instance a ``wrapper'' or ``peer'' object written in 1327another programming language. 1328 1329@end deftypefun 1330 1331@deftypefun void config_setting_set_hook (@w{config_setting_t * @var{setting}}, @w{void * @var{hook}}) 1332@deftypefunx {void *} config_setting_get_hook (@w{const config_setting_t * @var{setting}}) 1333 1334@cindex hook 1335These functions make it possible to attach arbitrary data to each 1336setting structure, for instance a ``wrapper'' or ``peer'' object written in 1337another programming language. The destructor function, if one has been 1338supplied via a call to @code{config_set_destructor()}, will be called 1339by the library to dispose of this data when the setting itself is 1340destroyed. There is no default destructor. 1341 1342@end deftypefun 1343 1344@deftypefun void config_set_destructor (@w{config_t * @var{config}}, @w{void (* @var{destructor})(void *)}) 1345 1346@cindex destructor function 1347This function assigns the destructor function @var{destructor} for the 1348configuration @var{config}. This function accepts a single @code{void 1349*} argument and has no return value. See 1350@code{config_setting_set_hook()} above for more information. 1351 1352@end deftypefun 1353 1354@node The C++ API, Example Programs, The C API, Top 1355@comment node-name, next, previous, up 1356@chapter The C++ API 1357 1358@tindex Config 1359@tindex Setting 1360This chapter describes the C++ library API. The class @code{Config} 1361represents a configuration, and the class @code{Setting} represents a 1362configuration setting. Note that by design, neither of these classes 1363provides a public copy constructor or assignment operator. Therefore, 1364instances of these classes may only be passed between functions via 1365references or pointers. 1366 1367@tindex ConfigException 1368The library defines a group of exceptions, all of which extend the 1369common base exception @code{ConfigException}. 1370 1371@tindex SettingTypeException 1372A @code{SettingTypeException} is thrown when the type of a setting's 1373value does not match the type requested. 1374 1375@deftypemethod SettingTypeException {} SettingTypeException (@w{const Setting &@var{setting}}) 1376@deftypemethodx SettingTypeException {} SettingTypeException (@w{const Setting &@var{setting}}, @w{int @var{index}}) 1377@deftypemethodx SettingTypeException {} SettingTypeException (@w{const Setting &@var{setting}}, @w{const char *@var{name}}) 1378 1379These methods construct @code{SettingTypeException} objects for the given @var{setting} and/or member @var{index} or @var{name}. 1380 1381@end deftypemethod 1382 1383@tindex SettingNotFoundException 1384A @code{SettingNotFoundException} is thrown when a setting is not found. 1385 1386@deftypemethod SettingNotFoundException {} SettingNotFoundException (@w{const Setting &@var{setting}}, @w{int @var{index}}) 1387@deftypemethodx SettingNotFoundException {} SettingNotFoundException (@w{const Setting &@var{setting}}, @w{const char *@var{name}}) 1388@deftypemethodx SettingNotFoundException {} SettingNotFoundException (@w{const char *@var{path}}) 1389 1390These methods construct @code{SettingTypeException} objects for the given @var{setting} and member @var{index} or @var{name}, or path @var{path}. 1391 1392@end deftypemethod 1393 1394@tindex SettingNameException 1395A @code{SettingNameException} is thrown when an attempt is made to add 1396a new setting with a non-unique or invalid name. 1397 1398@deftypemethod SettingNameException {} SettingNameException (@w{const Setting &@var{setting}}, @w{const char *@var{name}}) 1399 1400This method constructs a @code{SettingNameExcpetion} object for the given @var{setting} and member name @var{name}. 1401 1402@end deftypemethod 1403 1404@tindex ParseException 1405A @code{ParseException} is thrown when a parse error occurs while 1406reading a configuration from a stream. 1407 1408@deftypemethod ParseException {} ParseException (@w{const char *@var{file}}, @w{int @var{line}}, @w{const char *@var{error}}) 1409 1410This method constructs a @code{ParseException} object with the given filename @var{file}, line number @var{line}, and error message @var{error}. 1411 1412@end deftypemethod 1413 1414@tindex FileIOException 1415A @code{FileIOException} is thrown when an I/O error occurs while 1416reading/writing a configuration from/to a file. 1417 1418@tindex SettingException 1419@code{SettingTypeException}, @code{SettingNotFoundException}, and 1420@code{SettingNameException} all extend the common base 1421exception @code{SettingException}, which provides the following method: 1422 1423@deftypemethod SettingException {const char *} getPath () const 1424 1425This method returns the path to the setting associated with the exception, or 1426@code{NULL} if there is no applicable path. 1427 1428@end deftypemethod 1429 1430The remainder of this chapter describes the methods for manipulating 1431configurations and configuration settings. 1432 1433@deftypemethod Config {} Config () 1434@deftypemethodx Config {} ~Config () 1435 1436These methods create and destroy @code{Config} objects. 1437 1438@end deftypemethod 1439 1440@deftypemethod Config void clear () 1441 1442@b{Since @i{v1.7}} 1443 1444This method clears the configuration. All child settings of the root 1445setting are recursively destroyed. All other attributes of the 1446configuration are left unchanged. 1447 1448@end deftypemethod 1449 1450@deftypemethod Config void read (@w{FILE * @var{stream}}) 1451@deftypemethodx Config void write (@w{FILE * @var{stream}}) const 1452 1453The @code{read()} method reads and parses a configuration from the given 1454@var{stream}. A @code{ParseException} is thrown if a parse error occurs. 1455 1456The @code{write()} method writes the configuration to the given @var{stream}. 1457 1458@end deftypemethod 1459 1460@deftypemethod Config void readFile (@w{const char * @var{filename}}) 1461@deftypemethodx Config void readFile (@w{const std::string &@var{filename}}) 1462 1463The @code{readFile()} method reads and parses a configuration from the 1464file named @var{filename}. A @code{ParseException} is thrown if a 1465parse error occurs. A @code{FileIOException} is thrown if the file 1466cannot be read. 1467 1468@end deftypemethod 1469 1470@deftypemethod Config void writeFile (@w{const char * @var{filename}}) 1471@deftypemethodx Config void writeFile (@w{const std::string &@var{filename}}) 1472 1473The @code{writeFile()} method writes the configuration to the file 1474named @var{filename}. A @code{FileIOException} is thrown if the file cannot 1475be written. 1476 1477@end deftypemethod 1478 1479@deftypemethod Config void readString (@w{const char * @var{str}}) 1480@deftypemethodx Config void readString (@w{const std::string &@var{str}}) 1481 1482These methods read and parse a configuration from the string 1483@var{str}. A @code{ParseException} is thrown if a parse error occurs. 1484 1485@end deftypemethod 1486 1487@deftypemethod ParseException {const char *} getError () const 1488@deftypemethodx ParseException {const char *} getFile () const 1489@deftypemethodx ParseException int getLine () const 1490 1491If a call to @code{readFile()}, @code{readString()}, or @code{read()} 1492resulted in a @code{ParseException}, these methods can be called on 1493the exception object to obtain the text, filename, and line number of 1494the parse error. Storage for the strings returned by @code{getError()} 1495and @code{getFile()} are managed by the library; the strings must not 1496be freed by the caller. 1497 1498@end deftypemethod 1499 1500@deftypemethod Config void setIncludeDir (@w{const char *@var{includeDir}}) 1501@deftypemethodx Config {const char *} getIncludeDir () const 1502 1503The @code{setIncludeDir()} method specifies the include directory, 1504@var{includeDir}, relative to which the files specified in 1505@samp{@@include} directives will be located for the configuration. By 1506default, there is no include directory, and all include files are 1507expected to be relative to the current working directory. If 1508@var{includeDir} is @code{NULL}, the default behavior is reinstated. 1509 1510For example, if the include directory is set to @file{/usr/local/etc}, 1511the include directive @samp{@@include "configs/extra.cfg"} would include the 1512file @file{/usr/local/etc/configs/extra.cfg}. 1513 1514@code{getIncludeDir()} returns the current include directory for the 1515configuration, or @code{NULL} if none is set. 1516 1517@end deftypemethod 1518 1519@deftypemethod Config {virtual const char **} evaluateIncludePath (@w{const char * @var{path}}, @w{const char ** @var{error}}) 1520 1521@b{Since @i{v1.7}} 1522 1523This method is called to evaluate the path of an @code{@@include} directive. 1524The @var{path} is the literal path argument of the directive. The method may 1525be overridden in a subclass to perform tasks like wildcard expansion and 1526variable substitution. 1527 1528On success, the method should return a @code{NULL}-terminated array of paths. 1529Any relative paths must be relative to the program's current working directory. 1530The contents of these files will be inlined at the point of inclusion, in the 1531order that the paths appear in the array. Both the array and its elements should 1532be heap allocated; the library will take ownership of and eventually free the 1533strings in the array and the array itself. 1534 1535On failure, the function should return @code{NULL} and set @var{*error} to a 1536static error string which should be used as the parse error for the 1537configuration; the library does not take ownership of or free this string. 1538 1539The default implementation simply returns a @code{NULL}-terminated array 1540containing either a copy of @var{path} if it's an absolute path, or a 1541concatenation of the include directory and @var{path} if it's a relative path. 1542 1543For more information see @code{config_set_include_func()} above. 1544 1545@end deftypemethod 1546 1547@deftypemethod Config int getOptions () const 1548@deftypemethodx Config void setOptions (int @var{options}) 1549 1550@tindex Config::Option 1551These methods get and set the options for the configuration. The 1552options affect how configurations are read and written. The parameter 1553@var{options} should be a bitwise-OR of the following @var{Config::Option} 1554enumeration values: 1555 1556@table @code 1557 1558@item Config::OptionAutoConvert 1559Turning this option on enables number auto-conversion for 1560the configuration. When this feature is enabled, an attempt to retrieve a 1561floating point setting's value into an integer (or vice versa), or 1562store an integer to a floating point setting's value (or vice versa) 1563will cause the library to silently perform the necessary conversion 1564(possibly leading to loss of data), rather than reporting failure. By 1565default this option is turned off. 1566 1567@item Config::OptionSemicolonSeparators 1568This option controls whether a semicolon (`;') is output after each setting 1569when the configuration is written to a file or stream. (The semicolon 1570separators are optional in the configuration syntax.) By default this 1571option is turned on. 1572 1573@item Config::OptionColonAssignmentForGroups 1574This option controls whether a colon (`:') is output between each 1575group setting's name and its value when the configuration is written to 1576a file or stream. If the option is turned off, an equals sign (`=') is 1577output instead. (These tokens are interchangeable in the configuration 1578syntax.) By default this option is turned on. 1579 1580@item Config::OptionColonAssignmentForNonGroups 1581This option controls whether a colon (`:') is output between each 1582non-group setting's name and its value when the configuration is written 1583to a file or stream. If the option is turned off, an equals sign (`=') 1584is output instead. (These tokens are interchangeable in the configuration 1585syntax.) By default this option is turned off. 1586 1587@item Config::OptionOpenBraceOnSeparateLine 1588This option controls whether an open brace (`@{') will be written on its own 1589line when the configuration is written to a file or stream. If the option is 1590turned off, the brace will be written at the end of the previous line. 1591By default this option is turned on. 1592 1593@item Config::OptionAllowScientificNotation 1594(@b{Since @i{v1.7}}) 1595This option controls whether scientific notation may be used as appropriate 1596when writing floating point values (corresponding to @code{printf()} 1597@samp{%g} format) or should never be used (corresponding to @code{printf()} 1598@samp{%f} format). By default this option is turned off. 1599 1600@item Config::OptionFsync 1601(@b{Since @i{v1.7.1}}) 1602This option controls whether the @code{writeFile()} method performs an @i{fsync} 1603operation after writing the configuration and before closing the file. By 1604default this option is turned off. 1605 1606@item Config::OptionAllowOverrides 1607(@b{Since @i{v1.7.3}}) 1608This option controls whether duplicate settings override previous settings 1609with the same name. If this option is turned off, duplicate settings are 1610rejected. By default this option is turned off. 1611 1612@end table 1613 1614@end deftypemethod 1615 1616@deftypemethod Config bool getOption (@w{Config::Option @var{option}}) const 1617@deftypemethodx Config void setOption (@w{Config::Option @var{option}}, @w{bool @var{flag}}) 1618 1619@b{Since @i{v1.7}} 1620 1621These methods get and set the option @var{option} for the configuration. The 1622option is enabled if @var{flag} is @code{true} and disabled if it is 1623@code{false}. 1624 1625See @code{setOptions()} above for the list of available options. 1626 1627@end deftypemethod 1628 1629@deftypemethod Config bool getAutoConvert () const 1630@deftypemethodx Config void setAutoConvert (bool @var{flag}) 1631 1632These methods get and set the @code{OptionAutoConvert} option. They 1633are obsoleted by the @code{setOption()} and @code{getOption()} 1634methods described above. 1635 1636@end deftypemethod 1637 1638@deftypemethod Config Setting::Format getDefaultFormat () const 1639@deftypemethodx Config void setDefaultFormat (@w{Setting::Format @var{format}}) 1640 1641These methods get and set the default external format for settings in 1642the configuration. If a non-default format has not been set for a 1643setting with @code{Setting::setFormat()}, this configuration-wide 1644default format will be used instead when that setting is written to a 1645file or stream. 1646 1647@end deftypemethod 1648 1649@deftypemethod Config {unsigned short} getTabWidth () const 1650@deftypemethodx Config void setTabWidth (@w{unsigned short @var{width}}) 1651 1652These methods get and set the tab width for the configuration. The tab 1653width affects the formatting of the configuration when it is written 1654to a file or stream: each level of nesting is indented by @var{width} 1655spaces, or by a single tab character if @var{width} is 0. The tab 1656width has no effect on parsing. 1657 1658Valid tab widths range from 0 to 15. The default tab width is 2. 1659 1660@end deftypemethod 1661 1662@deftypemethod Config {unsigned short} getFloatPrecision () const 1663@deftypemethodx Config void setFloatPrecision (@w{unsigned short @var{width}}) 1664 1665These methods get and set the float precision for the configuration. 1666This parameter influences the formatting of floating point settings in 1667the configuration when it is written to a file or stream. 1668Float precision has no effect on parsing. 1669 1670Valid precisions range from 0 to about 15 (implementation dependent), 1671though the library will accept and store values up to 255. 1672 1673@end deftypemethod 1674 1675@deftypemethod Config {Setting &} getRoot () const 1676 1677This method returns the root setting for the configuration, which is a group. 1678 1679@end deftypemethod 1680 1681@deftypemethod Config {Setting &} lookup (@w{const std::string &@var{path}}) const 1682@deftypemethodx Config {Setting &} lookup (@w{const char * @var{path}}) const 1683 1684These methods locate the setting specified by the path @var{path}. If 1685the requested setting is not found, a @code{SettingNotFoundException} is 1686thrown. 1687 1688@end deftypemethod 1689@deftypemethod Config bool exists (@w{const std::string &@var{path}}) const 1690@deftypemethodx Config bool exists (@w{const char *@var{path}}) const 1691 1692These methods test if a setting with the given @var{path} exists in 1693the configuration. They return @code{true} if the setting exists, and 1694@code{false} otherwise. These methods do not throw exceptions. 1695 1696@end deftypemethod 1697 1698@deftypemethod Config bool lookupValue (@w{const char *@var{path}}, @w{bool &@var{value}}) const 1699@deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{bool &@var{value}}) const 1700 1701@deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{int &@var{value}}) const 1702@deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{int &@var{value}}) const 1703 1704@deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{unsigned int &@var{value}}) const 1705@deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{unsigned int &@var{value}}) const 1706 1707@deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{long long &@var{value}}) const 1708@deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{long long &@var{value}}) const 1709 1710@deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{float &@var{value}}) const 1711@deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{float &@var{value}}) const 1712 1713@deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{double &@var{value}}) const 1714@deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{double &@var{value}}) const 1715 1716@deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{const char *&@var{value}}) const 1717@deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{const char *&@var{value}}) const 1718 1719@deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{std::string &@var{value}}) const 1720@deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{std::string &@var{value}}) const 1721 1722These are convenience methods for looking up the value of a setting 1723with the given @var{path}. If the setting is found and is of an 1724appropriate type, the value is stored in @var{value} and the method 1725returns @code{true}. Otherwise, @var{value} is left unmodified and the 1726method returns @code{false}. These methods do not throw exceptions. 1727 1728Storage for @w{@i{const char *}} values is managed by the library and 1729released automatically when the setting is destroyed or when its value 1730is changed; the string must not be freed by the caller. For safety and 1731convenience, always assigning string values to a @code{std::string} is 1732suggested. 1733 1734Since these methods have boolean return values and do not throw 1735exceptions, they can be used within boolean logic expressions. The following 1736example presents a concise way to look up three values at once and 1737perform error handling if any of them are not found or are of the 1738wrong type: 1739 1740@sp 1 1741@cartouche 1742@smallexample 1743int var1; 1744double var2; 1745const char *var3; 1746 1747if(config.lookupValue("values.var1", var1) 1748 && config.lookupValue("values.var2", var2) 1749 && config.lookupValue("values.var3", var3)) 1750@{ 1751 // use var1, var2, var3 1752@} 1753else 1754@{ 1755 // error handling here 1756@} 1757@end smallexample 1758@end cartouche 1759 1760This approach also takes advantage of the short-circuit evaluation rules 1761of C++, e.g., if the first lookup fails (returning @code{false}), the 1762remaining lookups are skipped entirely. 1763 1764@end deftypemethod 1765 1766@deftypemethod Setting {} {operator bool ()} const 1767@deftypemethodx Setting {} {operator int ()} const 1768@deftypemethodx Setting {} {operator unsigned int ()} const 1769@deftypemethodx Setting {} {operator long ()} const 1770@deftypemethodx Setting {} {operator unsigned long ()} const 1771@deftypemethodx Setting {} {operator long long ()} const 1772@deftypemethodx Setting {} {operator unsigned long long ()} const 1773@deftypemethodx Setting {} {operator float ()} const 1774@deftypemethodx Setting {} {operator double ()} const 1775@deftypemethodx Setting {} {operator const char * ()} const 1776@deftypemethodx Setting {} {operator std::string ()} const 1777@deftypemethodx Setting {const char *} c_str () const 1778 1779These cast operators allow a @code{Setting} object to be assigned to a 1780variable of type @i{bool} if it is of type @code{TypeBoolean}; 1781@i{int}, @i{unsigned int}; @code{long long} or @code{unsigned long long} if 1782it is of type @code{TypeInt64}, @i{float} or @i{double} if it is of type 1783@code{TypeFloat}; or @w{@i{const char *}} or @i{std::string} if it is 1784of type @code{TypeString}. 1785 1786Values of type @code{TypeInt} or @code{TypeInt64} may be assigned to 1787variables of type @i{long}, or @i{unsigned long}, depending on the 1788sizes of those types on the host system. 1789 1790Storage for @w{@i{const char *}} return values is managed by the 1791library and released automatically when the setting is destroyed or 1792when its value is changed; the string must not be freed by the 1793caller. For safety and convenience, always assigning string return 1794values to a @code{std::string} is suggested. 1795 1796The following examples demonstrate this usage: 1797 1798@cartouche 1799@smallexample 1800long width = config.lookup("application.window.size.w"); 1801 1802bool splashScreen = config.lookup("application.splash_screen"); 1803 1804std::string title = config.lookup("application.window.title"); 1805@end smallexample 1806@end cartouche 1807 1808Note that certain conversions can lead to loss of precision or 1809clipping of values, e.g., assigning a negative value to an @i{unsigned 1810int} (in which case the value will be treated as 0), or a 1811double-precision value to a @i{float}. The library does not treat 1812these lossy conversions as errors. 1813 1814Perhaps surprisingly, the following code in particular will cause a 1815compiler error: 1816 1817@cartouche 1818@smallexample 1819std::string title; 1820. 1821. 1822. 1823title = config.lookup("application.window.title"); 1824@end smallexample 1825@end cartouche 1826 1827This is because the assignment operator of @code{std::string} is being 1828invoked with a @code{Setting &} as an argument. The compiler is unable 1829to make an implicit conversion because both the @code{const char *} 1830and the @code{std::string} cast operators of @code{Setting} are 1831equally appropriate. This is not a bug in @i{libconfig}; providing 1832only the @code{const char *} cast operator would resolve this 1833particular ambiguity, but would cause assignments to 1834@code{std::string} like the one in the previous example to produce a 1835compiler error. (To understand why, see section 11.4.1 of @i{The C++ 1836Programming Language}.) 1837 1838The solution to this problem is to use an explicit conversion that 1839avoids the construction of an intermediate @code{std::string} object, 1840as follows: 1841 1842@cartouche 1843@smallexample 1844std::string title; 1845. 1846. 1847. 1848title = (const char *)config.lookup("application.window.title"); 1849@end smallexample 1850@end cartouche 1851 1852Or, alternatively, use the @code{c_str()} method, which has the same effect: 1853 1854@cartouche 1855@smallexample 1856std::string title; 1857. 1858. 1859. 1860title = config.lookup("application.window.title").c_str(); 1861@end smallexample 1862@end cartouche 1863 1864If the assignment is invalid due to a type mismatch, a 1865@code{SettingTypeException} is thrown. 1866 1867@end deftypemethod 1868 1869@deftypemethod Setting {Setting &} operator= (@w{bool @var{value}}) 1870@deftypemethodx Setting {Setting &} operator= (@w{int @var{value}}) 1871@deftypemethodx Setting {Setting &} operator= (@w{long @var{value}}) 1872@deftypemethodx Setting {Setting &} operator= (@w{const long long &@var{value}}) 1873@deftypemethodx Setting {Setting &} operator= (@w{float @var{value}}) 1874@deftypemethodx Setting {Setting &} operator= (@w{const double &@var{value}}) 1875@deftypemethodx Setting {Setting &} operator= (@w{const char *@var{value}}) 1876@deftypemethodx Setting {Setting &} operator= (@w{const std::string &@var{value}}) 1877 1878These assignment operators allow values of type @i{bool}, @i{int}, 1879@i{long}, @i{long long}, @i{float}, @i{double}, @i{const char *}, and 1880@i{std::string} to be assigned to a setting. In the case of strings, 1881the library makes a copy of the passed string @var{value}, so it may 1882be subsequently freed or modified by the caller without affecting the 1883value of the setting. 1884 1885The following example code looks up a (presumably) integer setting 1886and changes its value: 1887 1888@cartouche 1889@smallexample 1890Setting &setting = config.lookup("application.window.size.w"); 1891setting = 1024; 1892@end smallexample 1893@end cartouche 1894 1895If the assignment is invalid due to a type mismatch, a 1896@code{SettingTypeException} is thrown. 1897 1898@end deftypemethod 1899 1900@deftypemethod Setting {Setting &} {operator[]} (@w{int @var{index}}) const 1901@deftypemethodx Setting {Setting &} {operator[]} (@w{const std::string &@var{name}}) const 1902@deftypemethodx Setting {Setting &} {operator[]} (@w{const char *@var{name}}) const 1903 1904A @code{Setting} object may be subscripted with an integer index 1905@var{index} if it is an array or list, or with either a string 1906@var{name} or an integer index @var{index} if it is a group. For example, 1907the following code would produce the string @samp{Last Name} when 1908applied to the example configuration in @ref{Configuration Files}. 1909 1910@cartouche 1911@smallexample 1912Setting& setting = config.lookup("application.misc"); 1913const char *s = setting["columns"][0]; 1914@end smallexample 1915@end cartouche 1916 1917If the setting is not an array, list, or group, a 1918@code{SettingTypeException} is thrown. If the subscript (@var{index} 1919or @var{name}) does not refer to a valid element, a 1920@code{SettingNotFoundException} is thrown. 1921 1922Iterating over a group's child settings with an integer index will 1923return the settings in the same order that they appear in the 1924configuration. 1925 1926@end deftypemethod 1927 1928@deftypemethod Setting {Setting &} lookup (@w{const char * @var{path}}) const 1929@deftypemethodx Setting {Setting &} lookup (@w{const std::string &@var{path}}) const 1930 1931These methods locate a setting by a path @var{path} relative to 1932this setting. If requested setting is not found, a 1933@code{SettingNotFoundException} is thrown. 1934 1935@end deftypemethod 1936 1937@deftypemethod Setting bool lookupValue (@w{const char *@var{name}}, @w{bool &@var{value}}) const 1938@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{bool &@var{value}}) const 1939 1940@deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{int &@var{value}}) const 1941@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{int &@var{value}}) const 1942 1943@deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{unsigned int &@var{value}}) const 1944@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{unsigned int &@var{value}}) const 1945 1946@deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{long long &@var{value}}) const 1947@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{long long &@var{value}}) const 1948 1949@deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{unsigned long long &@var{value}}) const 1950@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{unsigned long long &@var{value}}) const 1951 1952@deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{float &@var{value}}) const 1953@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{float &@var{value}}) const 1954 1955@deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{double &@var{value}}) const 1956@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{double &@var{value}}) const 1957 1958@deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{const char *&@var{value}}) const 1959@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{const char *&@var{value}}) const 1960 1961@deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{std::string &@var{value}}) const 1962@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{std::string &@var{value}}) const 1963 1964These are convenience methods for looking up the value of a child setting 1965with the given @var{name}. If the setting is found and is of an 1966appropriate type, the value is stored in @var{value} and the method 1967returns @code{true}. Otherwise, @var{value} is left unmodified and the 1968method returns @code{false}. These methods do not throw exceptions. 1969 1970Storage for @w{@i{const char *}} values is managed by the library and 1971released automatically when the setting is destroyed or when its value 1972is changed; the string must not be freed by the caller. For safety and 1973convenience, always assigning string values to a @code{std::string} is 1974suggested. 1975 1976Since these methods have boolean return values and do not throw 1977exceptions, they can be used within boolean logic expressions. The following 1978example presents a concise way to look up three values at once and 1979perform error handling if any of them are not found or are of the 1980wrong type: 1981 1982@sp 1 1983@cartouche 1984@smallexample 1985int var1; 1986double var2; 1987const char *var3; 1988 1989if(setting.lookupValue("var1", var1) 1990 && setting.lookupValue("var2", var2) 1991 && setting.lookupValue("var3", var3)) 1992@{ 1993 // use var1, var2, var3 1994@} 1995else 1996@{ 1997 // error handling here 1998@} 1999@end smallexample 2000@end cartouche 2001 2002This approach also takes advantage of the short-circuit evaluation 2003rules of C++, e.g., if the first lookup fails (returning @code{false}), the 2004remaining lookups are skipped entirely. 2005 2006@end deftypemethod 2007 2008@deftypemethod Setting {Setting &} add (@w{const std::string &@var{name}}, @w{Setting::Type @var{type}}) 2009@deftypemethodx Setting {Setting &} add (@w{const char *@var{name}}, @w{Setting::Type @var{type}}) 2010 2011These methods add a new child setting with the given @var{name} and 2012@var{type} to the setting, which must be a group. They return a 2013reference to the new setting. If the setting already has a child 2014setting with the given name, or if the name is invalid, a 2015@code{SettingNameException} is thrown. If the setting is not a group, 2016a @code{SettingTypeException} is thrown. 2017 2018Once a setting has been created, neither its name nor type can be 2019changed. 2020 2021@end deftypemethod 2022 2023@deftypemethod Setting {Setting &} add (@w{Setting::Type @var{type}}) 2024 2025This method adds a new element to the setting, which must be of type 2026@code{TypeArray} or @code{TypeList}. If the setting is an array which 2027currently has zero elements, the @var{type} parameter (which must be 2028@code{TypeInt}, @code{TypeInt64}, @code{TypeFloat}, @code{TypeBool}, 2029or @code{TypeString}) determines the type for the array; otherwise it 2030must match the type of the existing elements in the array. 2031 2032The method returns the new setting on success. If @var{type} is a 2033scalar type, the new setting will have a default value of 0, 0.0, 2034@code{false}, or @code{NULL}, as appropriate. 2035 2036The method throws a @code{SettingTypeException} if the setting is not 2037an array or list, or if @var{type} is invalid. 2038 2039@end deftypemethod 2040 2041@deftypemethod Setting void remove (@w{const std::string &@var{name}}) 2042@deftypemethodx Setting void remove (@w{const char *@var{name}}) 2043 2044These methods remove the child setting with the given @var{name} from 2045the setting, which must be a group. Any child settings of the removed 2046setting are recursively destroyed as well. 2047 2048If the setting is not a group, a @code{SettingTypeException} is 2049thrown. If the setting does not have a child setting with the given 2050name, a @code{SettingNotFoundException} is thrown. 2051 2052@end deftypemethod 2053 2054@deftypemethod Setting void remove (@w{unsigned int @var{index}}) 2055 2056This method removes the child setting at the given index @var{index} from 2057the setting, which must be a group, list, or array. Any child settings 2058of the removed setting are recursively destroyed as well. 2059 2060If the setting is not a group, list, or array, a 2061@code{SettingTypeException} is thrown. If @var{index} is out of range, 2062a @code{SettingNotFoundException} is thrown. 2063 2064@end deftypemethod 2065 2066@deftypemethod Setting {const char *} getName () const 2067 2068This method returns the name of the setting, or @code{NULL} if the 2069setting has no name. Storage for the returned string is managed by the 2070library and released automatically when the setting is destroyed; the 2071string must not be freed by the caller. For safety and convenience, 2072consider assigning the return value to a @code{std::string}. 2073 2074@end deftypemethod 2075 2076@deftypemethod Setting {std::string} getPath () const 2077 2078This method returns the complete dot-separated path to the 2079setting. Settings which do not have a name (list and array elements) 2080are represented by their index in square brackets. 2081 2082@end deftypemethod 2083 2084@deftypemethod Setting {Setting &} getParent () const 2085 2086This method returns the parent setting of the setting. If the setting 2087is the root setting, a @code{SettingNotFoundException} is thrown. 2088 2089@end deftypemethod 2090 2091@deftypemethod Setting bool isRoot () const 2092 2093This method returns @code{true} if the setting is the root setting, and 2094@code{false} otherwise. 2095 2096@end deftypemethod 2097 2098@deftypemethod Setting int getIndex () const 2099 2100This method returns the index of the setting within its parent 2101setting. When applied to the root setting, this method returns -1. 2102 2103@end deftypemethod 2104 2105@deftypemethod Setting Setting::Type getType () const 2106 2107@tindex Setting::Type 2108This method returns the type of the setting. The 2109@code{Setting::Type} enumeration consists of the following constants: 2110@code{TypeInt}, @code{TypeInt64}, @code{TypeFloat}, @code{TypeString}, 2111@code{TypeBoolean}, @code{TypeArray}, @code{TypeList}, and 2112@code{TypeGroup}. 2113 2114@end deftypemethod 2115 2116@deftypemethod Setting Setting::Format getFormat () const 2117@deftypemethodx Setting void setFormat (@w{Setting::Format @var{format}}) 2118 2119These methods get and set the external format for the setting. 2120 2121@tindex Setting::Format 2122The @var{Setting::Format} enumeration consists of the following 2123constants: @code{FormatDefault} and @code{FormatHex}. All settings 2124support the @code{FormatDefault} format. The @code{FormatHex} format 2125specifies hexadecimal formatting for integer values, and hence only 2126applies to settings of type @code{TypeInt} and @code{TypeInt64}. If 2127@var{format} is invalid for the given setting, it is ignored. 2128 2129@end deftypemethod 2130 2131@deftypemethod Setting bool exists (@w{const std::string &@var{name}}) const 2132@deftypemethodx Setting bool exists (@w{const char *@var{name}}) const 2133 2134These methods test if the setting has a child setting with the given 2135@var{name}. They return @code{true} if the setting exists, and 2136@code{false} otherwise. These methods do not throw exceptions. 2137 2138@end deftypemethod 2139@page 2140@deftypemethod Setting iterator begin () 2141@deftypemethodx Setting iterator end () 2142@deftypemethodx Setting const_iterator begin () 2143@deftypemethodx Setting const_iterator end () 2144 2145These methods return STL-style iterators that can be used to enumerate 2146the child settings of a given setting. If the setting is not an array, list, 2147or group, they throw a @code{SettingTypeException}. 2148 2149@end deftypemethod 2150 2151@deftypemethod Setting int getLength () const 2152 2153This method returns the number of settings in a group, or the number of 2154elements in a list or array. For other types of settings, it returns 21550. 2156 2157@end deftypemethod 2158 2159@deftypemethod Setting bool isGroup () const 2160@deftypemethodx Setting bool isArray () const 2161@deftypemethodx Setting bool isList () const 2162 2163These convenience methods test if a setting is of a given type. 2164 2165@end deftypemethod 2166 2167@deftypemethod Setting bool isAggregate () const 2168@deftypemethodx Setting bool isScalar () const 2169@deftypemethodx Setting bool isNumber () const 2170@deftypemethodx Setting bool isString () const 2171 2172These convenience methods test if a setting is of an aggregate type (a 2173group, array, or list), of a scalar type (integer, 64-bit integer, 2174floating point, boolean, or string), of a number (integer, 64-bit 2175integer, or floating point), and of a string respectively. 2176 2177@end deftypemethod 2178 2179@deftypemethod Setting {const char *} getSourceFile () const 2180 2181This method returns the name of the file from which the setting was 2182read, or NULL if the setting was not read from a file. This 2183information is useful for reporting application-level errors. Storage 2184for the returned string is managed by the library and released 2185automatically when the configuration is destroyed; the string must 2186not be freed by the caller. 2187 2188@end deftypemethod 2189 2190@deftypemethod Setting {unsigned int} getSourceLine () const 2191 2192This method returns the line number of the configuration file or 2193stream at which the setting @var{setting} was read, or 0 if no line 2194number is available. This information is useful for reporting 2195application-level errors. 2196 2197@end deftypemethod 2198 2199@node Example Programs, Other Bindings and Implementations, The C++ API, Top 2200@comment node-name, next, previous, up 2201@chapter Example Programs 2202 2203Practical example programs that illustrate how to use @i{libconfig} 2204from both C and C++ are included in the @file{examples} subdirectory 2205of the distribution. These examples include: 2206 2207@table @file 2208 2209@item examples/c/example1.c 2210An example C program that reads a configuration from an existing file 2211@file{example.cfg} (also located in @file{examples/c}) and displays 2212some of its contents. 2213 2214@item examples/c++/example1.cpp 2215The C++ equivalent of @file{example1.c}. 2216 2217@item examples/c/example2.c 2218An example C program that reads a configuration from an existing file 2219@file{example.cfg} (also located in @file{examples/c}), adds new 2220settings to the configuration, and writes the updated configuration to 2221another file. 2222 2223@item examples/c++/example2.cpp 2224The C++ equivalent of @file{example2.c} 2225 2226@item examples/c/example3.c 2227An example C program that constructs a new configuration in memory and writes it to a file. 2228 2229@item examples/c++/example3.cpp 2230The C++ equivalent of @file{example3.c} 2231 2232@item examples/c/example4.c 2233An example C program that uses a custom include function for processing 2234wildcard includes. Note that this code will not compile on Windows. 2235 2236@end table 2237 2238@node Other Bindings and Implementations, License, Example Programs, Top 2239@comment node-name, next, previous, up 2240@chapter Other Bindings and Implementations 2241@menu 2242* Bourne Shell:: 2243* D:: 2244* Haskell:: 2245* Java:: 2246* Lisp:: 2247* Perl:: 2248* Python:: 2249* Ruby:: 2250@end menu 2251 2252Various open-source libraries have been written that provide access to 2253@i{libconfig}-style configuration files from other programming languages. Some 2254of these libraries are wrappers which add new language bindings for 2255@i{libconfig} while others are syntax-compatible reimplementations in other 2256languages. 2257 2258Here is a list of some of these implementations. 2259 2260@node Bourne Shell, D, , Other Bindings and Implementations 2261@comment node-name, next, previous, up 2262@section Bourne Shell 2263 2264@L{}ukasz A. Grabowski's @i{ls-config} provides a means to read and write 2265values in @i{libconfig} configuration files from Bourne shell scripts. The 2266implementation is included in the @i{libconfig} git repository at 2267@url{https://github.com/hyperrealm/libconfig}, in the @file{contrib/ls-config} 2268subdirectory. 2269 2270@node D, Haskell, Bourne Shell, Other Bindings and Implementations 2271@comment node-name, next, previous, up 2272@section D 2273 2274Remi Thebault's @i{libconfig-d} is a port of @i{libconfig} to the D programming 2275language. It may be found at @url{https://code.dlang.org/packages/libconfig-d}. 2276 2277@node Haskell, Java, D, Other Bindings and Implementations 2278@comment node-name, next, previous, up 2279@section Haskell 2280 2281Matthew Peddie's @i{libconfig} provides Haskell bindings to 2282@i{libconfig}. It may be found at 2283@url{https://hackage.haskell.org/package/libconfig-0.3.0.0}. 2284 2285@node Java, Lisp, Haskell, Other Bindings and Implementations 2286@comment node-name, next, previous, up 2287@section Java 2288 2289Andrey V. Pleskach has a pure-Java implementation of @i{libconfig}. It may be 2290found on github at @url{https://github.com/willyborankin/libconfig}. 2291 2292@node Lisp, Perl, Java, Other Bindings and Implementations 2293@comment node-name, next, previous, up 2294@section Lisp 2295 2296Oleg Shalaev's @i{cl-libconfig} provides Common Lisp bindings for @i{libconfig}. 2297It may be found on github at @url{https://github.com/chalaev/cl-libconfig}. 2298 2299@node Perl, Python, Lisp, Other Bindings and Implementations 2300@comment node-name, next, previous, up 2301@section Perl 2302 2303The @i{Conf::Libconfig} module provides Perl bindings for @i{libconfig}. It may 2304be found on CPAN at @url{http://search.cpan.org/~cnangel/Conf-Libconfig-0.05/} 2305or on github at @url{https://github.com/cnangel/Conf-Libconfig}. 2306 2307@node Python, Ruby, Perl, Other Bindings and Implementations 2308@comment node-name, next, previous, up 2309@section Python 2310 2311Heiner Tholen's @i{pylibconfig2} is a Python library that is syntax-compatible 2312with @i{libconfig}. It may be found at 2313@url{https://pypi.python.org/pypi/pylibconfig2/0.1.2}. 2314 2315@sp 1 2316 2317Christian Aichinger's @i{libconf} is another pure-Python implementation with a 2318more permissive license. It may be found at 2319@url{https://pypi.python.org/pypi/libconf} or on github at 2320@url{https://github.com/Grk0/python-libconf}. 2321 2322@sp 1 2323 2324The @i{python-libconfig} wrapper provides Python bindings to @i{libconfig}. It 2325may be found on github at @url{https://github.com/cnangel/python-libconfig/}. 2326 2327@node Ruby, , Python, Other Bindings and Implementations 2328@comment node-name, next, previous, up 2329@section Ruby 2330 2331Christopher Mark Gore's @i{ruby-libconfig} is a Ruby library that provides Ruby 2332bindings for @i{libconfig}. It may be found at 2333@url{https://rubygems.org/gems/libconfig} or on github at 2334@url{https://github.com/cgore/ruby-libconfig}. 2335 2336@sp 1 2337 2338There is also another Ruby wrapper, @i{libconfig-ruby}, that is included in 2339the @i{libconfig} git repository at @url{https://github.com/hyperrealm/libconfig}, 2340in the @file{contrib/libconfig-ruby} subdirectory. 2341 2342@node License, Configuration File Grammar, Other Bindings and Implementations, Top 2343@comment node-name, next, previous, up 2344@appendix License 2345 2346@include LGPL.texi 2347 2348@node Configuration File Grammar, Function Index, License, Top 2349@comment node-name, next, previous, up 2350@appendix Configuration File Grammar 2351 2352Below is the BNF grammar for configuration files. Comments and include 2353directives are not part of the grammar, so they are not included here. 2354 2355@sp 1 2356@example 2357<configuration> ::= 2358 <setting-list> 2359 | <empty> 2360 2361<setting-list> ::= 2362 <setting> 2363 | <setting-list> <setting> 2364 2365<setting> ::= 2366 <name> ( ":" | "=" ) <value> ( ";" | "," | <empty> ) 2367 2368<value> ::= 2369 <scalar-value> 2370 | <array> 2371 | <list> 2372 | <group> 2373 2374<value-list> ::= 2375 <value> 2376 | <value-list> "," <value> 2377 | <value-list> "," 2378 2379<scalar-value> ::= 2380 <boolean> 2381 | <integer> 2382 | <integer64> 2383 | <hex> 2384 | <hex64> 2385 | <float> 2386 | <string> 2387 2388<scalar-value-list> ::= 2389 <scalar-value> 2390 | <scalar-value-list> "," <scalar-value> 2391 | <scalar-value-list> "," 2392 2393<array> ::= 2394 "[" ( <scalar-value-list> | <empty> ) "]" 2395 2396<list> ::= 2397 "(" ( <value-list> | <empty> ) ")" 2398 2399<group> ::= 2400 "@{" ( <setting-list> | <empty> ) "@}" 2401 2402<empty> ::= 2403@end example 2404 2405@sp 2 2406Terminals are defined below as regular expressions: 2407@sp 1 2408 2409@multitable @columnfractions .2 .8 2410@item @code{<boolean>} @tab 2411@code{([Tt][Rr][Uu][Ee])|([Ff][Aa][Ll][Ss][Ee])} 2412@item @code{<string>} @tab 2413@code{\"([^\"\\]|\\.)*\"} 2414@item @code{<name>} @tab 2415@code{[A-Za-z\*][-A-Za-z0-9_\*]*} 2416@item @code{<integer>} @tab 2417@code{[-+]?[0-9]+} 2418@item @code{<integer64>} @tab 2419@code{[-+]?[0-9]+L(L)?} 2420@item @code{<hex>} @tab 2421@code{0[Xx][0-9A-Fa-f]+} 2422@item @code{<hex64>} @tab 2423@code{0[Xx][0-9A-Fa-f]+(L(L)?)?} 2424@item @code{<float>} @tab 2425@code{([-+]?([0-9]*)?\.[0-9]*([eE][-+]?[0-9]+)?)|([-+]([0-9]+)(\.[0-9]*)?[eE][-+]?[0-9]+)} 2426@end multitable 2427 2428@sp 1 2429 2430Note that adjacent strings are automatically concatenated. Non-printable 2431characters can be represented within strings using a sequence @samp{\xx}, 2432representing the ASCII value as two hex digits. 2433 2434@node Function Index, Type Index, Configuration File Grammar, Top 2435@comment node-name, next, previous, up 2436@unnumbered Function Index 2437 2438@printindex fn 2439 2440@node Type Index, Concept Index, Function Index, Top 2441@comment node-name, next, previous, up 2442@unnumbered Type Index 2443 2444@printindex tp 2445 2446@node Concept Index, , Type Index, Top 2447@comment node-name, next, previous, up 2448@unnumbered Concept Index 2449 2450@printindex cp 2451 2452@bye 2453