diff options
| author | Jonathan McCrohan <jmccrohan@gmail.com> | 2011-12-01 22:56:23 +0000 |
|---|---|---|
| committer | Jonathan McCrohan <jmccrohan@gmail.com> | 2011-12-01 22:56:23 +0000 |
| commit | 429e46051dba814e7d6c74368eb1bba550222cbe (patch) | |
| tree | ed1dd43cd23c69f156aae2165006a16a66262cef /doc/libconfig.info | |
| parent | 58bf1382be0cbcf3f9649286fd2719b789a1595f (diff) | |
| download | libconfig-429e46051dba814e7d6c74368eb1bba550222cbe.tar.gz | |
Imported Upstream version 1.4.8upstream/1.4.8
Diffstat (limited to 'doc/libconfig.info')
| -rw-r--r-- | doc/libconfig.info | 826 |
1 files changed, 567 insertions, 259 deletions
diff --git a/doc/libconfig.info b/doc/libconfig.info index 51dbfc6..0a0e813 100644 --- a/doc/libconfig.info +++ b/doc/libconfig.info @@ -1,4 +1,4 @@ -This is libconfig.info, produced by makeinfo version 4.11 from +This is libconfig.info, produced by makeinfo version 4.13 from libconfig.texi. INFO-DIR-SECTION Software libraries @@ -18,6 +18,7 @@ libconfig * Configuration Files:: * The C API:: * The C++ API:: +* Example Programs:: * Configuration File Grammar:: * License:: * Function Index:: @@ -35,6 +36,7 @@ File: libconfig.info, Node: Introduction, Next: Configuration Files, Prev: To * Multithreading Issues:: * Internationalization Issues:: * Compiling Using pkg-config:: +* Version Test Macros:: 1 Introduction ************** @@ -70,7 +72,7 @@ libconfig that set it apart from the other libraries are: readable and compact than XML and more flexible than the obsolete but prevalent Windows "INI" file format. - * A low-footprint implementation (just 38K for the C library and 66K + * A low-footprint implementation (just 37K for the C library and 76K for the C++ library) that is suitable for memory-constrained systems. @@ -183,7 +185,7 @@ responsible for changing the LC_NUMERIC category of the locale to the "C" locale before reading or writing a configuration. -File: libconfig.info, Node: Compiling Using pkg-config, Prev: Internationalization Issues, Up: Introduction +File: libconfig.info, Node: Compiling Using pkg-config, Next: Version Test Macros, Prev: Internationalization Issues, Up: Introduction 1.6 Compiling Using pkg-config ============================== @@ -207,6 +209,54 @@ link C programs with libconfig as follows: Note the backticks in the above examples. + When using autoconf, the `PKG_CHECK_MODULES' m4 macro may be used to +check for the presence of a given version of libconfig, and set the +appropriate Makefile variables automatically. For example: + + PKG_CHECK_MODULES([LIBCONFIGXX], [libconfig++ >= 1.4],, + AC_MSG_ERROR([libconfig++ 1.4 or newer not found.]) + ) + + In the above example, if libconfig++ version 1.4 or newer is found, +the Makefile variables `LIBCONFIGXX_LIBS' and `LIBCONFIGXX_CFLAGS' will +be set to the appropriate compiler and linker flags for compiling with +libconfig, and if it is not found, the configure script will abort with +an error to that effect. + + +File: libconfig.info, Node: Version Test Macros, Prev: Compiling Using pkg-config, Up: Introduction + +1.7 Version Test Macros +======================= + +The `libconfig.h' header declares the following macros: + + -- Macro: LIBCONFIG_VER_MAJOR + -- Macro: LIBCONFIG_VER_MINOR + -- Macro: LIBCONFIG_VER_REVISION + These macros represent the major version, minor version, and + revision of the libconfig library. For example, in libconfig 1.4 + these are defined as `1', `4', and `0', respectively. These macros + can be used in preprocessor directives to determine which + libconfig features and/or APIs are present. For example: + + #if (((LIBCONFIG_VER_MAJOR == 1) && (LIBCONFIG_VER_MINOR >= 4)) \ + || (LIBCONFIG_VER_MAJOR > 1)) + /* use features present in libconfig 1.4 and later */ + #endif + + These macros were introduced in libconfig 1.4. + + + Similarly, the `libconfig.h++' header declares the following macros: + + -- Macro: LIBCONFIGXX_VER_MAJOR + -- Macro: LIBCONFIGXX_VER_MINOR + -- Macro: LIBCONFIGXX_VER_REVISION + These macros represent the major version, minor version, and + revision of the libconfig++ library. + + File: libconfig.info, Node: Configuration Files, Next: The C API, Prev: Introduction, Up: Top @@ -222,6 +272,7 @@ File: libconfig.info, Node: Configuration Files, Next: The C API, Prev: Intro * Boolean Values:: * String Values:: * Comments:: +* Include Directives:: 2 Configuration Files ********************* @@ -312,9 +363,9 @@ characters, dashes (`-'), underscores (`_'), and asterisks (`*'), and must begin with a letter or asterisk. No other characters are allowed. In C and C++, integer, 64-bit integer, floating point, and string -values are mapped to the types `long', `long long', `double', and -`const char *', respectively. The boolean type is mapped to `int' in C -and `bool' in C++. +values are mapped to the types `int', `long long', `double', and `const +char *', respectively. The boolean type is mapped to `int' in C and +`bool' in C++. The following sections describe the elements of the configuration file grammar in additional detail. @@ -333,7 +384,7 @@ A setting has the form: name : value ; - The trailing semicolon is required. Whitespace is not significant. + The trailing semicolon is optional. Whitespace is not significant. The value may be a scalar value, an array, a group, or a list. @@ -427,8 +478,14 @@ File: libconfig.info, Node: String Values, Next: Comments, Prev: Boolean Valu String values consist of arbitrary text delimited by double quotes. Literal double quotes can be escaped by preceding them with a backslash: `\"'. The escape sequences `\\', `\f', `\n', `\r', and `\t' -are also recognized, and have the usual meaning. No other escape -sequences are currently supported. +are also recognized, and have the usual meaning. + + In addition, the `\x' escape sequence is supported; this sequence +must be followed by exactly two hexadecimal digits, which represent an +8-bit ASCII value. For example, `\xFF' represents the character with +ASCII code 0xFF. + + No other escape sequences are currently supported. Adjacent strings are automatically concatenated, as in C/C++ source code. This is useful for formatting very long strings as sequences of @@ -444,7 +501,7 @@ shorter strings. For example, the following constructs are equivalent: -File: libconfig.info, Node: Comments, Prev: String Values, Up: Configuration Files +File: libconfig.info, Node: Comments, Next: Include Directives, Prev: String Values, Up: Configuration Files 2.10 Comments ============= @@ -470,6 +527,49 @@ configuration is written back out to a stream, any comments that were present in the original configuration will be lost. +File: libconfig.info, Node: Include Directives, Prev: Comments, Up: Configuration Files + +2.11 Include Directives +======================= + +A configuration file may "include" the contents of another file using +an include directive. This directive has the effect of inlining the +contents of the named file at the point of inclusion. + + An include directive must appear on its own line in the input. It has +the form: + + @include "filename" + + Any backslashes or double quotes in the filename must be escaped as +`\\' and `\"', respectively. + + For example, consider the following two configuration files: + + # file: quote.cfg + quote = "Criticism may not be agreeable, but it is necessary." + " It fulfils the same function as pain in the human" + " body. It calls attention to an unhealthy state of" + " things.\n" + "\t--Winston Churchill"; + + # file: test.cfg + info: { + name = "Winston Churchill"; + @include "quote.cfg" + country = "UK"; + }; + + Include files may be nested to a maximum of 10 levels; exceeding this +limit results in a parse error. + + Like comments, include directives are not part of the configuration +file syntax. They are processed before the configuration itself is +parsed. Therefore, they are not preserved when the configuration is +written back out to a stream. There is presently no support for +programmatically inserting include directives into a configuration. + + File: libconfig.info, Node: The C API, Next: The C++ API, Prev: Configuration Files, Up: Top 3 The C API @@ -487,18 +587,20 @@ defined as `(1)' and `(0)', respectively. These functions initialize and destroy the configuration object CONFIG. - `config_init()' initializes CONFIG as a new, empty configuration. + `config_init()' initializes the config_t structure pointed to by + CONFIG as a new, empty configuration. `config_destroy()' destroys the configuration CONFIG, deallocating - all memory associated with the configuration, but not including - the config_t structure itself. + all memory associated with the configuration, but does not attempt + to deallocate the config_t structure itself. -- Function: int config_read (config_t * CONFIG, FILE * STREAM) This function reads and parses a configuration from the given STREAM into the configuration object CONFIG. It returns `CONFIG_TRUE' on success, or `CONFIG_FALSE' on failure; the - `config_error_text()' and `config_error_line()' functions, + `config_error_text()', `config_error_file()', + `config_error_line()', and `config_error_type()' functions, described below, can be used to obtain information about the error. @@ -511,6 +613,15 @@ defined as `(1)' and `(0)', respectively. described below, can be used to obtain information about the error. + -- Function: int config_read_string (config_t * CONFIG, + const char * STR) + This function reads and parses a configuration from the string STR + into the configuration object CONFIG. It returns `CONFIG_TRUE' on + success, or `CONFIG_FALSE' on failure; the `config_error_text()' + and `config_error_line()' functions, described below, can be used + to obtain information about the error. + + -- Function: void config_write (const config_t * CONFIG, FILE * STREAM) This function writes the configuration CONFIG to the given STREAM. @@ -523,13 +634,45 @@ defined as `(1)' and `(0)', respectively. -- Function: const char * config_error_text (const config_t * CONFIG) + -- Function: const char * config_error_file (const config_t * CONFIG) -- Function: int config_error_line (const config_t * CONFIG) - These functions, which are implemented as macros, return the text - and line number of the parse error, if one occurred during a call - to `config_read()' or `config_read_file()'. Storage for the string - returned by `config_error_text()' is managed by the library and - released automatically when the configuration is destroyed; the - string must not be freed by the caller. + These functions, which are implemented as macros, return the text, + filename, and line number of the parse error, if one occurred + during a call to `config_read()', `config_read_string()', or + `config_read_file()'. Storage for the strings returned by + `config_error_text()' and `config_error_file()' are managed by the + library and released automatically when the configuration is + destroyed; these strings must not be freed by the caller. If the + error occurred in text that was read from a string or stream, + `config_error_file()' will return NULL. + + + -- Function: config_error_t config_error_type (const config_t * CONFIG) + This function, which is implemented as a macro, returns the type of + error that occurred during the last call to one of the read or + write functions. The CONFIG_ERROR_T type is an enumeration with the + following values: `CONFIG_ERR_NONE', `CONFIG_ERR_FILE_IO', + `CONFIG_ERR_PARSE'. These represent success, a file I/O error, and + a parsing error, respectively. + + + -- Function: void config_set_include_dir (config_t *CONFIG, + const char *INCLUDE_DIR) + -- Function: const char * config_get_include_dir + (const config_t *CONFIG) + `config_set_include_dir()' specifies the include directory, + INCLUDE_DIR, relative to which the files specified in `@include' + directives will be located for the configuration CONFIG. By + default, there is no include directory, and all include files are + expected to be relative to the current working directory. If + INCLUDE_DIR is `NULL', the default behavior is reinstated. + + For example, if the include directory is set to `/usr/local/etc', + the include directive `@include "configs/extra.cfg"' would include + the file `/usr/local/etc/configs/extra.cfg'. + + `config_get_include_dir()' returns the current include directory + for the configuration CONFIG, or `NULL' if none is set. -- Function: void config_set_auto_convert (config_t *CONFIG, int FLAG) @@ -548,8 +691,33 @@ defined as `(1)' and `(0)', respectively. returns `CONFIG_FALSE'. + -- Function: void config_set_default_format (config_t * CONFIG, + short FORMAT) + -- Function: short config_get_default_format (config_t * CONFIG) + These functions, which are implemented as macros, set and get the + default external format for settings in the configuration CONFIG. + If a non-default format has not been set for a setting with + `config_setting_set_format()', this configuration-wide default + format will be used instead when that setting is written to a file + or stream. + + + -- Function: void config_set_tab_width (config_t * CONFIG, + unsigned short WIDTH) + -- Function: unsigned short config_get_tab_width + (const config_t * CONFIG) + These functions, which are implemented as macros, set and get the + tab width for the configuration CONFIG. The tab width affects the + formatting of the configuration when it is written to a file or + stream: each level of nesting is indented by WIDTH spaces, or by a + single tab character if WIDTH is 0. The tab width has no effect on + parsing. + + Valid tab widths range from 0 to 15. The default tab width is 2. + + -- Function: int config_lookup_int (const config_t * CONFIG, - const char * PATH, long * VALUE) + const char * PATH, int * VALUE) -- Function: int config_lookup_int64 (const config_t * CONFIG, const char * PATH, long long * VALUE) -- Function: int config_lookup_float (const config_t * CONFIG, @@ -579,7 +747,7 @@ defined as `(1)' and `(0)', respectively. was not found. - -- Function: long config_setting_get_int + -- Function: int config_setting_get_int (const config_setting_t * SETTING) -- Function: long long config_setting_get_int64 (const config_setting_t * SETTING) @@ -599,7 +767,7 @@ defined as `(1)' and `(0)', respectively. -- Function: int config_setting_set_int (config_setting_t * SETTING, - long VALUE) + int VALUE) -- Function: int config_setting_set_int64 (config_setting_t * SETTING, long long VALUE) -- Function: int config_setting_set_float (config_setting_t * SETTING, @@ -618,7 +786,7 @@ defined as `(1)' and `(0)', respectively. -- Function: int config_setting_lookup_int (const config_setting_t * SETTING, const char * NAME, - long * VALUE) + int * VALUE) -- Function: int config_setting_lookup_int64 (const config_setting_t * SETTING, const char * NAME, long long * VALUE) @@ -659,6 +827,10 @@ defined as `(1)' and `(0)', respectively. `CONFIG_TYPE_INT64'. If FORMAT is invalid for the given setting, it is ignored. + If a non-default format has not been set for the setting, + `config_setting_get_format()' returns the default format for the + configuration, as set by `config_set_default_format()'. + `config_setting_set_format()' returns `CONFIG_TRUE' on success and `CONFIG_FALSE' on failure. @@ -671,49 +843,49 @@ defined as `(1)' and `(0)', respectively. -- Function: config_setting_t * config_setting_get_elem - (const config_setting_t * SETTING, unsigned int IDX) - This function fetches the element at the given index IDX in the + (const config_setting_t * SETTING, unsigned int INDEX) + This function fetches the element at the given index INDEX in the setting SETTING, which must be an array, list, or group. It - returns the requested setting on success, or `NULL' if IDX is out - of range or if SETTING is not an array, list, or group. + returns the requested setting on success, or `NULL' if INDEX is + out of range or if SETTING is not an array, list, or group. - -- Function: long config_setting_get_int_elem - (const config_setting_t * SETTING, int IDX) + -- Function: int config_setting_get_int_elem + (const config_setting_t * SETTING, int INDEX) -- Function: long long config_setting_get_int64_elem - (const config_setting_t * SETTING, int IDX) + (const config_setting_t * SETTING, int INDEX) -- Function: double config_setting_get_float_elem - (const config_setting_t * SETTING, int IDX) + (const config_setting_t * SETTING, int INDEX) -- Function: int config_setting_get_bool_elem - (const config_setting_t * SETTING, int IDX) + (const config_setting_t * SETTING, int INDEX) -- Function: const char * config_setting_get_string_elem - (const config_setting_t * SETTING, int IDX) - These functions return the value at the specified index IDX in the - setting SETTING. If the setting is not an array or list, or if the - type of the element does not match the type requested, or if IDX - is out of range, they return 0 or `NULL'. Storage for the string - returned by `config_setting_get_string_elem()' is managed by the - library and released automatically when the setting is destroyed - or when its value is changed; the string must not be freed by the - caller. + (const config_setting_t * SETTING, int INDEX) + These functions return the value at the specified index INDEX in + the setting SETTING. If the setting is not an array or list, or if + the type of the element does not match the type requested, or if + INDEX is out of range, they return 0 or `NULL'. Storage for the + string returned by `config_setting_get_string_elem()' is managed + by the library and released automatically when the setting is + destroyed or when its value is changed; the string must not be + freed by the caller. -- Function: config_setting_t * config_setting_set_int_elem - (config_setting_t * SETTING, int IDX, long VALUE) + (config_setting_t * SETTING, int INDEX, int VALUE) -- Function: config_setting_t * config_setting_set_int64_elem - (config_setting_t * SETTING, int IDX, long long VALUE) + (config_setting_t * SETTING, int INDEX, long long VALUE) -- Function: config_setting_t * config_setting_set_float_elem - (config_setting_t * SETTING, int IDX, double VALUE) + (config_setting_t * SETTING, int INDEX, double VALUE) -- Function: config_setting_t * config_setting_set_bool_elem - (config_setting_t * SETTING, int IDX, int VALUE) + (config_setting_t * SETTING, int INDEX, int VALUE) -- Function: config_setting_t * config_setting_set_string_elem - (config_setting_t * SETTING, int IDX, const char * VALUE) - These functions set the value at the specified index IDX in the - setting SETTING to VALUE. If IDX is negative, a new element is + (config_setting_t * SETTING, int INDEX, const char * VALUE) + These functions set the value at the specified index INDEX in the + setting SETTING to VALUE. If INDEX is negative, a new element is added to the end of the array or list. On success, these functions return a pointer to the setting representing the element. If the setting is not an array or list, or if the setting is an array and the type of the array does not match the type of the value, or if - IDX is out of range, they return `NULL'. + INDEX is out of range, they return `NULL'. `config_setting_set_string_elem()' makes a copy of the passed string VALUE, so it may be subsequently freed or modified by the caller without affecting the value of the setting. @@ -726,7 +898,9 @@ defined as `(1)' and `(0)', respectively. The function returns the new setting on success, or `NULL' if PARENT is not a group, array, or list; or if there is already a - child setting of PARENT named NAME; or if TYPE is invalid. + child setting of PARENT named NAME; or if TYPE is invalid. If TYPE + is a scalar type, the new setting will have a default value of 0, + 0.0, `false', or `NULL', as appropriate. -- Function: int config_setting_remove (config_setting_t * PARENT, const char * NAME) @@ -740,14 +914,14 @@ defined as `(1)' and `(0)', respectively. -- Function: int config_setting_remove_elem - (config_setting_t * PARENT, unsigned int IDX) - This function removes the child setting at the given index IDX from - the setting PARENT, which must be a group, list, or array. Any + (config_setting_t * PARENT, unsigned int INDEX) + This function removes the child setting at the given index INDEX + from the setting PARENT, which must be a group, list, or array. Any child settings of the removed setting are recursively destroyed as well. The function returns `CONFIG_TRUE' on success. If PARENT is not a - group, list, or array, or if IDX is out of range, it returns + group, list, or array, or if INDEX is out of range, it returns `CONFIG_FALSE'. @@ -824,13 +998,22 @@ defined as `(1)' and `(0)', respectively. `CONFIG_FALSE'. + -- Function: const char * config_setting_source_file + (const config_setting_t * SETTING) + This function returns the name of the file from which the setting + SETTING was read, or NULL if the setting was not read from a file. + This information is useful for reporting application-level errors. + Storage for the returned string is managed by the library and + released automatically when the configuration is destroyed; the + string must not be freed by the caller. + + -- Function: unsigned int config_setting_source_line (const config_setting_t * SETTING) This function returns the line number of the configuration file or - stream at which the setting SETTING was parsed. This information - is useful for reporting application-level errors. If the setting - was not read from a file or stream, or if the line number is - otherwise unavailable, the function returns 0. + stream at which the setting SETTING was read, or 0 if no line + number is available. This information is useful for reporting + application-level errors. -- Function: void config_setting_set_hook (config_setting_t * SETTING, @@ -854,7 +1037,7 @@ defined as `(1)' and `(0)', respectively. -File: libconfig.info, Node: The C++ API, Next: Configuration File Grammar, Prev: The C API, Up: Top +File: libconfig.info, Node: The C++ API, Next: Example Programs, Prev: The C API, Up: Top 4 The C++ API ************* @@ -919,13 +1102,38 @@ configurations and configuration settings. be written. + -- Method on Config: void readString (const char * STR) + -- Method on Config: void readString (const std::string &STR) + These methods read and parse a configuration from the string STR. + A `ParseException' is thrown if a parse error occurs. + + -- Method on ParseException: const char * getError () + -- Method on ParseException: const char * getFile () -- Method on ParseException: int getLine () - If a call to `readFile()' or `read()' resulted in a - `ParseException', these methods can be called on the exception - object to obtain the text and line number of the parse error. - Storage for the string returned by `getError()' is managed by the - library; the string must not be freed by the caller. + If a call to `readFile()', `readString()', or `read()' resulted in + a `ParseException', these methods can be called on the exception + object to obtain the text, filename, and line number of the parse + error. Storage for the strings returned by `getError()' and + `getFile()' are managed by the library; the strings must not be + freed by the caller. + + + -- Method on Config: void setIncludeDir (const char *INCLUDEDIR) + -- Method on Config: const char * getIncludeDir () + `setIncludeDir()' specifies the include directory, INCLUDEDIR, + relative to which the files specified in `@include' directives + will be located for the configuration. By default, there is no + include directory, and all include files are expected to be + relative to the current working directory. If INCLUDEDIR is + `NULL', the default behavior is reinstated. + + For example, if the include directory is set to `/usr/local/etc', + the include directive `@include "configs/extra.cfg"' would include + the file `/usr/local/etc/configs/extra.cfg'. + + `getIncludeDir()' returns the current include directory for the + configuration, or `NULL' if none is set. -- Method on Config: void setAutoConvert (bool FLAG) @@ -944,6 +1152,26 @@ configurations and configuration settings. `false'. + -- Method on Config: void setDefaultFormat (Setting::Format FORMAT) + -- Method on Config: Setting::Format getDefaultFormat () + These methods set and get the default external format for settings + in the configuration. If a non-default format has not been set for + a setting with `Setting::setFormat()', this configuration-wide + default format will be used instead when that setting is written + to a file or stream. + + + -- Method on Config: void setTabWidth (unsigned short WIDTH) + -- Method on Config: unsigned short getTabWidth () + These methods set and get the tab width for the configuration. The + tab width affects the formatting of the configuration when it is + written to a file or stream: each level of nesting is indented by + WIDTH spaces, or by a single tab character if WIDTH is 0. The tab + width has no effect on parsing. + + Valid tab widths range from 0 to 15. The default tab width is 2. + + -- Method on Config: Setting & getRoot () This method returns the root setting for the configuration, which is a group. @@ -973,17 +1201,10 @@ configurations and configuration settings. unsigned int &VALUE) -- Method on Config: bool lookupValue (const std::string &PATH, unsigned int &VALUE) - -- Method on Config: bool lookupValue (const char *PATH, long &VALUE) - -- Method on Config: bool lookupValue (const std::string &PATH, - long &VALUE) -- Method on Config: bool lookupValue (const char *PATH, long long &VALUE) -- Method on Config: bool lookupValue (const std::string &PATH, long long &VALUE) - -- Method on Config: bool lookupValue (const char *PATH, - unsigned long &VALUE) - -- Method on Config: bool lookupValue (const std::string &PATH, - unsigned long &VALUE) -- Method on Config: bool lookupValue (const char *PATH, float &VALUE) -- Method on Config: bool lookupValue (const std::string &PATH, float &VALUE) @@ -1037,23 +1258,27 @@ configurations and configuration settings. the remaining lookups are skipped entirely. - -- Method on Setting: operator bool() - -- Method on Setting: operator int() - -- Method on Setting: operator unsigned int() - -- Method on Setting: operator long() - -- Method on Setting: operator unsigned long() - -- Method on Setting: operator long long() - -- Method on Setting: operator unsigned long long() - -- Method on Setting: operator float() - -- Method on Setting: operator double() - -- Method on Setting: operator const char *() - -- Method on Setting: operator std::string() + -- Method on Setting: operator bool () + -- Method on Setting: operator int () + -- Method on Setting: operator unsigned int () + -- Method on Setting: operator long () + -- Method on Setting: operator unsigned long () + -- Method on Setting: operator long long () + -- Method on Setting: operator unsigned long long () + -- Method on Setting: operator float () + -- Method on Setting: operator double () + -- Method on Setting: operator const char * () + -- Method on Setting: operator std::string () + -- Method on Setting: const char * c_str () These cast operators allow a `Setting' object to be assigned to a variable of type bool if it is of type `TypeBoolean'; int, - unsigned int, long, or unsigned long if it is of type `TypeInt'; - `long long' or `unsigned long long' if it is of type `TypeInt64', - float or double if it is of type `TypeFloat'; or const char * or - std::string if it is of type `TypeString'. + unsigned int; `long long' or `unsigned long long' if it is of type + `TypeInt64', float or double if it is of type `TypeFloat'; or + const char * or std::string if it is of type `TypeString'. + + Values of type `TypeInt' or `TypeInt64' may be assigned to + variables of type long, or unsigned long, depending on the sizes + of those types on the host system. Storage for const char * return values is managed by the library and released automatically when the setting is destroyed or when @@ -1105,6 +1330,15 @@ configurations and configuration settings. . title = (const char *)config.lookup("application.window.title"); + Or, alternatively, use the `c_str()' method, which has the same + effect: + + std::string title; + . + . + . + title = config.lookup("application.window.title").c_str(); + If the assignment is invalid due to a type mismatch, a `SettingTypeException' is thrown. @@ -1124,24 +1358,30 @@ configurations and configuration settings. or modified by the caller without affecting the value of the setting. + The following example code looks up a (presumably) integer setting + and changes its value: + + Setting &setting = config.lookup("application.window.size.w"); + setting = 1024; + If the assignment is invalid due to a type mismatch, a `SettingTypeException' is thrown. - -- Method on Setting: Setting & operator[] (int IDX) + -- Method on Setting: Setting & operator[] (int INDEX) -- Method on Setting: Setting & operator[] (const std::string &NAME) -- Method on Setting: Setting & operator[] (const char *NAME) - A `Setting' object may be subscripted with an integer index IDX if - it is an array or list, or with either a string NAME or an integer - index IDX if it is a group. For example, the following code would - produce the string `Last Name' when applied to the example - configuration in *note Configuration Files::. + A `Setting' object may be subscripted with an integer index INDEX + if it is an array or list, or with either a string NAME or an + integer index INDEX if it is a group. For example, the following + code would produce the string `Last Name' when applied to the + example configuration in *note Configuration Files::. Setting& setting = config.lookup("application.misc"); const char *s = setting["columns"][0]; If the setting is not an array, list, or group, a - `SettingTypeException' is thrown. If the subscript (IDX or NAME) + `SettingTypeException' is thrown. If the subscript (INDEX or NAME) does not refer to a valid element, a `SettingNotFoundException' is thrown. @@ -1168,13 +1408,6 @@ configurations and configuration settings. unsigned long long &VALUE) -- Method on Setting: bool lookupValue (const std::string &NAME, unsigned long long &VALUE) - -- Method on Setting: bool lookupValue (const char *NAME, long &VALUE) - -- Method on Setting: bool lookupValue (const std::string &NAME, - long &VALUE) - -- Method on Setting: bool lookupValue (const char *NAME, - unsigned long &VALUE) - -- Method on Setting: bool lookupValue (const std::string &NAME, - unsigned long &VALUE) -- Method on Setting: bool lookupValue (const char *NAME, float &VALUE) -- Method on Setting: bool lookupValue (const std::string &NAME, float &VALUE) @@ -1254,7 +1487,7 @@ configurations and configuration settings. The method returns the new setting on success. If TYPE is a scalar type, the new setting will have a default value of 0, 0.0, - `false', or `NULL', depending on the type. + `false', or `NULL', as appropriate. The method throws a `SettingTypeException' if the setting is not an array or list, or if TYPE is invalid. @@ -1271,13 +1504,13 @@ configurations and configuration settings. a `SettingNotFoundException' is thrown. - -- Method on Setting: void remove (unsigned int IDX) - This method removes the child setting at the given index IDX from + -- Method on Setting: void remove (unsigned int INDEX) + This method removes the child setting at the given index INDEX from the setting, which must be a group, list, or array. Any child settings of the removed setting are recursively destroyed as well. If the setting is not a group, list, or array, a - `SettingTypeException' is thrown. If IDX is out of range, a + `SettingTypeException' is thrown. If INDEX is out of range, a `SettingNotFoundException' is thrown. @@ -1359,31 +1592,72 @@ configurations and configuration settings. (integer, 64-bit integer, or floating point), respectively. + -- Method on Setting: const char * getSourceFile () + This function returns the name of the file from which the setting + was read, or NULL if the setting was not read from a file. This + information is useful for reporting application-level errors. + Storage for the returned string is managed by the library and + released automatically when the configuration is destroyed; the + string must not be freed by the caller. + + -- Method on Setting: unsigned int getSourceLine () - This method returns the line number of the configuration file or - stream at which the setting was parsed. This information is useful - for reporting application-level errors. If the setting was not - read from a file or stream, or if the line number is otherwise - unavailable, the method returns 0. + This function returns the line number of the configuration file or + stream at which the setting SETTING was read, or 0 if no line + number is available. This information is useful for reporting + application-level errors. + + + +File: libconfig.info, Node: Example Programs, Next: Configuration File Grammar, Prev: The C++ API, Up: Top + +5 Example Programs +****************** + +Practical example programs that illustrate how to use libconfig from +both C and C++ are included in the `examples' subdirectory of the +distribution. These examples include: + +`examples/c/example1.c' + An example C program that reads a configuration from an existing + file `example.cfg' (also located in `examples/c') and displays + some of its contents. + +`examples/c++/example1.cpp' + The C++ equivalent of `example1.c'. + +`examples/c/example2.c' + An example C program that reads a configuration from an existing + file `example.cfg' (also located in `examples/c'), adds new + settings to the configuration, and writes the updated + configuration to another file. + +`examples/c++/example2.cpp' + The C++ equivalent of `example2.c' + +`examples/c/example3.c' + An example C program that constructs a new configuration in memory + and writes it to a file. + +`examples/c++/example3.cpp' + The C++ equivalent of `example3.c' -File: libconfig.info, Node: Configuration File Grammar, Next: License, Prev: The C++ API, Up: Top +File: libconfig.info, Node: Configuration File Grammar, Next: License, Prev: Example Programs, Up: Top -5 Configuration File Grammar +6 Configuration File Grammar **************************** -Below is the BNF grammar for configuration files. Comments are not part -of the grammar, and hence are not included here. +Below is the BNF grammar for configuration files. Comments and include +directives are not part of the grammar, so they are not included here. configuration = setting-list | empty - empty = - setting-list = setting | setting-list setting - setting = name (":" | "=") value ";" + setting = name (":" | "=") value (";" | "," | empty) value = scalar-value | array | list | group @@ -1400,6 +1674,8 @@ of the grammar, and hence are not included here. group = "{" (setting-list | empty) "}" + empty = + Terminals are defined below as regular expressions: @@ -1984,116 +2260,142 @@ Function Index * Menu: -* add on Setting: The C++ API. (line 378) +* add on Setting: The C++ API. (line 428) +* c_str on Setting: The C++ API. (line 234) * Config on Config: The C++ API. (line 43) * config_destroy: The C API. (line 15) -* config_error_line: The C API. (line 55) -* config_error_text: The C API. (line 54) -* config_get_auto_convert: The C API. (line 65) +* config_error_file: The C API. (line 66) +* config_error_line: The C API. (line 67) +* config_error_text: The C API. (line 65) +* config_error_type: The C API. (line 79) +* config_get_auto_convert: The C API. (line 108) +* config_get_default_format: The C API. (line 125) +* config_get_include_dir: The C API. (line 91) +* config_get_tab_width: The C API. (line 137) * config_init: The C API. (line 14) -* config_lookup: The C API. (line 104) -* config_lookup_bool: The C API. (line 87) -* config_lookup_float: The C API. (line 85) -* config_lookup_int: The C API. (line 81) -* config_lookup_int64: The C API. (line 83) -* config_lookup_string: The C API. (line 89) -* config_read: The C API. (line 26) -* config_read_file: The C API. (line 35) -* config_root_setting: The C API. (line 284) -* config_set_auto_convert: The C API. (line 64) -* config_set_destructor: The C API. (line 378) -* config_setting_add: The C API. (line 251) -* config_setting_get_bool: The C API. (line 118) -* config_setting_get_bool_elem: The C API. (line 217) -* config_setting_get_elem: The C API. (line 203) -* config_setting_get_float: The C API. (line 116) -* config_setting_get_float_elem: The C API. (line 215) -* config_setting_get_format: The C API. (line 177) -* config_setting_get_hook: The C API. (line 368) -* config_setting_get_int: The C API. (line 112) -* config_setting_get_int64: The C API. (line 114) -* config_setting_get_int64_elem: The C API. (line 213) -* config_setting_get_int_elem: The C API. (line 211) -* config_setting_get_member: The C API. (line 196) -* config_setting_get_string: The C API. (line 120) -* config_setting_get_string_elem: The C API. (line 219) -* config_setting_index: The C API. (line 310) -* config_setting_is_aggregate: The C API. (line 343) -* config_setting_is_array: The C API. (line 334) -* config_setting_is_group: The C API. (line 332) -* config_setting_is_list: The C API. (line 336) -* config_setting_is_number: The C API. (line 347) -* config_setting_is_root: The C API. (line 304) -* config_setting_is_scalar: The C API. (line 345) -* config_setting_length: The C API. (line 317) -* config_setting_lookup_bool: The C API. (line 159) -* config_setting_lookup_float: The C API. (line 156) -* config_setting_lookup_int: The C API. (line 150) -* config_setting_lookup_int64: The C API. (line 153) -* config_setting_lookup_string: The C API. (line 162) -* config_setting_name: The C API. (line 290) -* config_setting_parent: The C API. (line 298) -* config_setting_remove: The C API. (line 261) -* config_setting_remove_elem: The C API. (line 272) -* config_setting_set_bool: The C API. (line 137) -* config_setting_set_bool_elem: The C API. (line 236) -* config_setting_set_float: The C API. (line 135) -* config_setting_set_float_elem: The C API. (line 234) -* config_setting_set_format: The C API. (line 179) -* config_setting_set_hook: The C API. (line 366) -* config_setting_set_int: The C API. (line 131) -* config_setting_set_int64: The C API. (line 133) -* config_setting_set_int64_elem: The C API. (line 232) -* config_setting_set_int_elem: The C API. (line 230) -* config_setting_set_string: The C API. (line 139) -* config_setting_set_string_elem: The C API. (line 238) -* config_setting_source_line: The C API. (line 357) -* config_setting_type: The C API. (line 323) -* config_write: The C API. (line 43) -* config_write_file: The C API. (line 48) -* exists on Config: The C++ API. (line 104) -* exists on Setting: The C++ API. (line 479) -* getAutoConvert on Config: The C++ API. (line 77) -* getError on ParseException: The C++ API. (line 67) -* getFormat on Setting: The C++ API. (line 467) -* getIndex on Setting: The C++ API. (line 455) -* getLength on Setting: The C++ API. (line 486) -* getLine on ParseException: The C++ API. (line 68) -* getName on Setting: The C++ API. (line 429) -* getParent on Setting: The C++ API. (line 444) -* getPath on Setting: The C++ API. (line 438) +* config_lookup: The C API. (line 172) +* config_lookup_bool: The C API. (line 155) +* config_lookup_float: The C API. (line 153) +* config_lookup_int: The C API. (line 149) +* config_lookup_int64: The C API. (line 151) +* config_lookup_string: The C API. (line 157) +* config_read: The C API. (line 27) +* config_read_file: The C API. (line 37) +* config_read_string: The C API. (line 46) +* config_root_setting: The C API. (line 358) +* config_set_auto_convert: The C API. (line 107) +* config_set_default_format: The C API. (line 124) +* config_set_destructor: The C API. (line 461) +* config_set_include_dir: The C API. (line 89) +* config_set_tab_width: The C API. (line 135) +* config_setting_add: The C API. (line 323) +* config_setting_get_bool: The C API. (line 186) +* config_setting_get_bool_elem: The C API. (line 289) +* config_setting_get_elem: The C API. (line 275) +* config_setting_get_float: The C API. (line 184) +* config_setting_get_float_elem: The C API. (line 287) +* config_setting_get_format: The C API. (line 245) +* config_setting_get_hook: The C API. (line 451) +* config_setting_get_int: The C API. (line 180) +* config_setting_get_int64: The C API. (line 182) +* config_setting_get_int64_elem: The C API. (line 285) +* config_setting_get_int_elem: The C API. (line 283) +* config_setting_get_member: The C API. (line 268) +* config_setting_get_string: The C API. (line 188) +* config_setting_get_string_elem: The C API. (line 291) +* config_setting_index: The C API. (line 384) +* config_setting_is_aggregate: The C API. (line 417) +* config_setting_is_array: The C API. (line 408) +* config_setting_is_group: The C API. (line 406) +* config_setting_is_list: The C API. (line 410) +* config_setting_is_number: The C API. (line 421) +* config_setting_is_root: The C API. (line 378) +* config_setting_is_scalar: The C API. (line 419) +* config_setting_length: The C API. (line 391) +* config_setting_lookup_bool: The C API. (line 227) +* config_setting_lookup_float: The C API. (line 224) +* config_setting_lookup_int: The C API. (line 218) +* config_setting_lookup_int64: The C API. (line 221) +* config_setting_lookup_string: The C API. (line 230) +* config_setting_name: The C API. (line 364) +* config_setting_parent: The C API. (line 372) +* config_setting_remove: The C API. (line 335) +* config_setting_remove_elem: The C API. (line 346) +* config_setting_set_bool: The C API. (line 205) +* config_setting_set_bool_elem: The C API. (line 308) +* config_setting_set_float: The C API. (line 203) +* config_setting_set_float_elem: The C API. (line 306) +* config_setting_set_format: The C API. (line 247) +* config_setting_set_hook: The C API. (line 449) +* config_setting_set_int: The C API. (line 199) +* config_setting_set_int64: The C API. (line 201) +* config_setting_set_int64_elem: The C API. (line 304) +* config_setting_set_int_elem: The C API. (line 302) +* config_setting_set_string: The C API. (line 207) +* config_setting_set_string_elem: The C API. (line 310) +* config_setting_source_file: The C API. (line 431) +* config_setting_source_line: The C API. (line 441) +* config_setting_type: The C API. (line 397) +* config_write: The C API. (line 54) +* config_write_file: The C API. (line 59) +* exists on Config: The C++ API. (line 149) +* exists on Setting: The C++ API. (line 529) +* getAutoConvert on Config: The C++ API. (line 102) +* getDefaultFormat on Config: The C++ API. (line 118) +* getError on ParseException: The C++ API. (line 73) +* getFile on ParseException: The C++ API. (line 74) +* getFormat on Setting: The C++ API. (line 517) +* getIncludeDir on Config: The C++ API. (line 85) +* getIndex on Setting: The C++ API. (line 505) +* getLength on Setting: The C++ API. (line 536) +* getLine on ParseException: The C++ API. (line 75) +* getName on Setting: The C++ API. (line 479) +* getParent on Setting: The C++ API. (line 494) +* getPath on Setting: The C++ API. (line 488) * getPath on SettingException: The C++ API. (line 35) -* getRoot on Config: The C++ API. (line 92) -* getSourceLine on Setting: The C++ API. (line 507) -* getType on Setting: The C++ API. (line 460) -* isAggregate on Setting: The C++ API. (line 498) -* isArray on Setting: The C++ API. (line 493) -* isGroup on Setting: The C++ API. (line 492) -* isList on Setting: The C++ API. (line 494) -* isNumber on Setting: The C++ API. (line 500) -* isRoot on Setting: The C++ API. (line 450) -* isScalar on Setting: The C++ API. (line 499) -* lookup on Config: The C++ API. (line 97) -* lookupValue on Config: The C++ API. (line 111) -* lookupValue on Setting: The C++ API. (line 298) -* operator bool() on Setting: The C++ API. (line 185) -* operator const char *() on Setting: The C++ API. (line 194) -* operator double() on Setting: The C++ API. (line 193) -* operator float() on Setting: The C++ API. (line 192) -* operator int() on Setting: The C++ API. (line 186) -* operator long long() on Setting: The C++ API. (line 190) -* operator long() on Setting: The C++ API. (line 188) -* operator std::string() on Setting: The C++ API. (line 195) -* operator unsigned int() on Setting: The C++ API. (line 187) -* operator unsigned long long() on Setting: The C++ API. (line 191) -* operator unsigned long() on Setting: The C++ API. (line 189) -* operator= on Setting: The C++ API. (line 257) -* operator[] on Setting: The C++ API. (line 276) +* getRoot on Config: The C++ API. (line 137) +* getSourceFile on Setting: The C++ API. (line 557) +* getSourceLine on Setting: The C++ API. (line 566) +* getTabWidth on Config: The C++ API. (line 127) +* getType on Setting: The C++ API. (line 510) +* isAggregate on Setting: The C++ API. (line 548) +* isArray on Setting: The C++ API. (line 543) +* isGroup on Setting: The C++ API. (line 542) +* isList on Setting: The C++ API. (line 544) +* isNumber on Setting: The C++ API. (line 550) +* isRoot on Setting: The C++ API. (line 500) +* isScalar on Setting: The C++ API. (line 549) +* LIBCONFIG_VER_MAJOR: Version Test Macros. (line 9) +* LIBCONFIG_VER_MINOR: Version Test Macros. (line 10) +* LIBCONFIG_VER_REVISION: Version Test Macros. (line 11) +* LIBCONFIGXX_VER_MAJOR: Version Test Macros. (line 28) +* LIBCONFIGXX_VER_MINOR: Version Test Macros. (line 29) +* LIBCONFIGXX_VER_REVISION: Version Test Macros. (line 30) +* lookup on Config: The C++ API. (line 142) +* lookupValue on Config: The C++ API. (line 156) +* lookupValue on Setting: The C++ API. (line 355) +* operator bool () on Setting: The C++ API. (line 223) +* operator const char * () on Setting: The C++ API. (line 232) +* operator double () on Setting: The C++ API. (line 231) +* operator float () on Setting: The C++ API. (line 230) +* operator int () on Setting: The C++ API. (line 224) +* operator long () on Setting: The C++ API. (line 226) +* operator long long () on Setting: The C++ API. (line 228) +* operator std::string () on Setting: The C++ API. (line 233) +* operator unsigned int () on Setting: The C++ API. (line 225) +* operator unsigned long () on Setting: The C++ API. (line 227) +* operator unsigned long long () on Setting: The C++ API. (line 229) +* operator= on Setting: The C++ API. (line 308) +* operator[] on Setting: The C++ API. (line 333) * read on Config: The C++ API. (line 48) * readFile on Config: The C++ API. (line 56) -* remove on Setting: The C++ API. (line 408) -* setAutoConvert on Config: The C++ API. (line 76) -* setFormat on Setting: The C++ API. (line 468) +* readString on Config: The C++ API. (line 67) +* remove on Setting: The C++ API. (line 458) +* setAutoConvert on Config: The C++ API. (line 101) +* setDefaultFormat on Config: The C++ API. (line 117) +* setFormat on Setting: The C++ API. (line 518) +* setIncludeDir on Config: The C++ API. (line 84) +* setTabWidth on Config: The C++ API. (line 126) * write on Config: The C++ API. (line 49) * writeFile on Config: The C++ API. (line 57) * ~Config on Config: The C++ API. (line 44) @@ -2108,16 +2410,17 @@ Type Index * Menu: * Config: The C++ API. (line 6) +* config_error_t: The C API. (line 79) * config_setting_t: The C API. (line 6) * config_t: The C API. (line 6) * ConfigException: The C++ API. (line 13) * FileIOException: The C++ API. (line 27) * ParseException: The C++ API. (line 24) * Setting: The C++ API. (line 6) -* Setting::Format: The C++ API. (line 470) -* Setting::Type: The C++ API. (line 460) +* Setting::Format: The C++ API. (line 520) +* Setting::Type: The C++ API. (line 510) * SettingException: The C++ API. (line 30) -* SettingFormat: The C API. (line 182) +* SettingFormat: The C API. (line 250) * SettingNameException: The C++ API. (line 21) * SettingNotFoundException: The C++ API. (line 19) * SettingTypeException: The C++ API. (line 16) @@ -2131,52 +2434,57 @@ Concept Index * Menu: -* aggregate value: The C API. (line 347) -* array: Configuration Files. (line 23) +* aggregate value: The C API. (line 421) +* array: Configuration Files. (line 24) * comment: Comments. (line 6) -* configuration: Configuration Files. (line 23) -* format: The C API. (line 182) -* group: Configuration Files. (line 23) -* list: Configuration Files. (line 23) +* configuration: Configuration Files. (line 24) +* escape sequence: String Values. (line 6) +* format: The C API. (line 250) +* group: Configuration Files. (line 24) +* include directive: Include Directives. (line 6) +* list: Configuration Files. (line 24) * locale: Internationalization Issues. (line 14) -* path: Configuration Files. (line 76) -* scalar value: Configuration Files. (line 23) -* setting: Configuration Files. (line 23) +* path: Configuration Files. (line 77) +* scalar value: Configuration Files. (line 24) +* setting: Configuration Files. (line 24) * Unicode: Internationalization Issues. (line 6) * UTF-8: Internationalization Issues. (line 6) -* value: Configuration Files. (line 23) +* value: Configuration Files. (line 24) Tag Table: Node: Top245 -Node: Introduction511 -Node: Why Another Configuration File Library?1323 -Node: Using the Library from a C Program2399 -Node: Using the Library from a C++ Program2867 -Node: Multithreading Issues3532 -Node: Internationalization Issues5099 -Node: Compiling Using pkg-config6622 -Node: Configuration Files7484 -Node: Settings11311 -Node: Groups11629 -Node: Arrays11903 -Node: Lists12175 -Node: Integer Values12461 -Node: 64-bit Integer Values12925 -Node: Floating Point Values13304 -Node: Boolean Values13761 -Node: String Values14033 -Node: Comments14922 -Node: The C API15802 -Node: The C++ API33339 -Node: Configuration File Grammar55291 -Node: License56588 -Node: Function Index84682 -Node: Type Index93076 -Node: Concept Index94241 +Node: Introduction532 +Node: Why Another Configuration File Library?1368 +Node: Using the Library from a C Program2444 +Node: Using the Library from a C++ Program2912 +Node: Multithreading Issues3577 +Node: Internationalization Issues5144 +Node: Compiling Using pkg-config6667 +Node: Version Test Macros8197 +Node: Configuration Files9383 +Node: Settings13232 +Node: Groups13550 +Node: Arrays13824 +Node: Lists14096 +Node: Integer Values14382 +Node: 64-bit Integer Values14846 +Node: Floating Point Values15225 +Node: Boolean Values15682 +Node: String Values15954 +Node: Comments17074 +Node: Include Directives17981 +Node: The C API19454 +Node: The C++ API41050 +Node: Example Programs65375 +Node: Configuration File Grammar66483 +Node: License67822 +Node: Function Index95916 +Node: Type Index106208 +Node: Concept Index107446 End Tag Table |