diff options
Diffstat (limited to 'doc/libconfig.texi')
| -rw-r--r-- | doc/libconfig.texi | 183 |
1 files changed, 159 insertions, 24 deletions
diff --git a/doc/libconfig.texi b/doc/libconfig.texi index 52dca20..f6f89eb 100644 --- a/doc/libconfig.texi +++ b/doc/libconfig.texi @@ -6,8 +6,8 @@ @setfilename libconfig.info @settitle libconfig -@set edition 1.4.9 -@set update-date 28 September 2012 +@set edition 1.5 +@set update-date 21 Sep 2014 @set subtitle-text A Library For Processing Structured Configuration Files @set author-text Mark A.@: Lindner @@ -36,7 +36,7 @@ @page @vskip 0pt plus 1filll -Copyright @copyright{} 2005-2012 Mark A Lindner +Copyright @copyright{} 2005-2014 Mark A Lindner Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -766,21 +766,60 @@ configuration @var{config}, or @code{NULL} if none is set. @end deftypefun -@deftypefun void config_set_auto_convert (@w{config_t *@var{config}}, @w{int @var{flag}}) -@deftypefunx int config_get_auto_convert (@w{const config_t *@var{config}}) +@deftypefun void config_set_options (@w{config_t *@var{config}}, @w{int @var{options}}) +@deftypefunx int config_get_options (@w{config_t *@var{config}}) + +These functions set and get the options for the configuration +@var{config}. The options affect how configurations are read and +written. The following options are defined: + +@table @code -@code{config_set_auto_convert()} enables number auto-conversion for -the configuration @var{config} if @var{flag} is non-zero, and disables -it otherwise. When this feature is enabled, an attempt to retrieve a +@item CONFIG_OPTION_AUTOCONVERT +Turning this option on enables number auto-conversion for +the configuration. When this feature is enabled, an attempt to retrieve a floating point setting's value into an integer (or vice versa), or store an integer to a floating point setting's value (or vice versa) will cause the library to silently perform the necessary conversion (possibly leading to loss of data), rather than reporting failure. By -default this feature is disabled. +default this option is turned off. + +@item CONFIG_OPTION_SEMICOLON_SEPARATORS +This option controls whether a semicolon (`;') is output after each setting +when the configuration is written to a file or stream. (The semicolon +separators are optional in the configuration syntax.) By default this +option is turned on. + +@item CONFIG_OPTION_COLON_ASSIGNMENT_FOR_GROUPS +This option controls whether a colon (`:') is output between each +group setting's name and its value when the configuration is written to +a file or stream. If the option is turned off, an equals sign (`=') is +output instead. (These tokens are interchangeable in the configuration +syntax.) By default this option is turned on. + +@item CONFIG_OPTION_COLON_ASSIGNMENT_FOR_NON_GROUPS +This option controls whether a colon (`:') is output between each +non-group setting's name and its value when the configuration is written +to a file or stream. If the option is turned off, an equals sign (`=') +is output instead. (These tokens are interchangeable in the configuration +syntax.) By default this option is turned off. + +@item CONFIG_OPTION_OPEN_BRACE_ON_SEPARATE_LINE +This option controls whether an open brace (`@{') will be written on its own +line when the configuration is written to a file or stream. If the option is +turned off, the brace will be written at the end of the previous line. +By default this option is turned on. + +@end table + +@end deftypefun + +@deftypefun void config_set_auto_convert (@w{config_t *@var{config}}, @w{int @var{flag}}) +@deftypefunx int config_get_auto_convert (@w{const config_t *@var{config}}) -@code{config_get_auto_convert()} returns @code{CONFIG_TRUE} if number -auto-conversion is currently enabled for @var{config}; otherwise it -returns @code{CONFIG_FALSE}. +These functions get and set the @code{CONFIG_OPTION_AUTO_CONVERT} +option. They are obsoleted by the @code{config_set_options()} and +@code{config_get_options()} functions described above. @end deftypefun @@ -839,6 +878,15 @@ setting was not found. @end deftypefun +@deftypefun {config_setting_t *} config_setting_lookup (@w{const config_setting_t * @var{setting}}, @w{const char * @var{path}}) + +This function locates a setting by a path @var{path} relative to +the setting @var{setting}. It returns a pointer to the +@code{config_setting_t} structure on success, or @code{NULL} if the +setting was not found. + +@end deftypefun + @deftypefun int config_setting_get_int (@w{const config_setting_t * @var{setting}}) @deftypefunx {long long} config_setting_get_int64 (@w{const config_setting_t * @var{setting}}) @deftypefunx double config_setting_get_float (@w{const config_setting_t * @var{setting}}) @@ -1146,17 +1194,45 @@ common base exception @code{ConfigException}. A @code{SettingTypeException} is thrown when the type of a setting's value does not match the type requested. +@deftypemethod SettingTypeException {} SettingTypeException (@w{const Setting &@var{setting}}) +@deftypemethodx SettingTypeException {} SettingTypeException (@w{const Setting &@var{setting}}, @w{int @var{index}}) +@deftypemethodx SettingTypeException {} SettingTypeException (@w{const Setting &@var{setting}}, @w{const char *@var{name}}) + +These methods construct @code{SettingTypeException} objects for the given @var{setting} and/or member @var{index} or @var{name}. + +@end deftypemethod + @tindex SettingNotFoundException A @code{SettingNotFoundException} is thrown when a setting is not found. +@deftypemethod SettingNotFoundException {} SettingNotFoundException (@w{const Setting &@var{setting}}, @w{int @var{index}}) +@deftypemethodx SettingNotFoundException {} SettingNotFoundException (@w{const Setting &@var{setting}}, @w{const char *@var{name}}) +@deftypemethodx SettingNotFoundException {} SettingNotFoundException (@w{const char *@var{path}}) + +These methods construct @code{SettingTypeException} objects for the given @var{setting} and member @var{index} or @var{name}, or path @var{path}. + +@end deftypemethod + @tindex SettingNameException A @code{SettingNameException} is thrown when an attempt is made to add a new setting with a non-unique or invalid name. +@deftypemethod SettingNameException {} SettingNameException (@w{const Setting &@var{setting}}, @w{const char *@var{name}}) + +This method constructs a @code{SettingNameExcpetion} object for the given @var{setting} and member name @var{name}. + +@end deftypemethod + @tindex ParseException A @code{ParseException} is thrown when a parse error occurs while reading a configuration from a stream. +@deftypemethod ParseException {} ParseException (@w{const char *@var{file}}, @w{int @var{line}}, @w{const char *@var{error}}) + +This method constructs a @code{ParseException} object with the given filename @var{file}, line number @var{line}, and error message @var{error}. + +@end deftypemethod + @tindex FileIOException A @code{FileIOException} is thrown when an I/O error occurs while reading/writing a configuration from/to a file. @@ -1247,21 +1323,60 @@ configuration, or @code{NULL} if none is set. @end deftypemethod +@deftypemethod Config void setOptions (int @var{options}) +@deftypemethodx Config int getOptions () + +These methods set and get the options for the configuration. The +options affect how configurations are read and written. The following +options are defined: + +@table @code + +@item OptionAutoConvert +Turning this option on enables number auto-conversion for +the configuration. When this feature is enabled, an attempt to retrieve a +floating point setting's value into an integer (or vice versa), or +store an integer to a floating point setting's value (or vice versa) +will cause the library to silently perform the necessary conversion +(possibly leading to loss of data), rather than reporting failure. By +default this option is turned off. + +@item OptionSemicolonSeparators +This option controls whether a semicolon (`;') is output after each setting +when the configuration is written to a file or stream. (The semicolon +separators are optional in the configuration syntax.) By default this +option is turned on. + +@item OptionColonAssignmentForGroups +This option controls whether a colon (`:') is output between each +group setting's name and its value when the configuration is written to +a file or stream. If the option is turned off, an equals sign (`=') is +output instead. (These tokens are interchangeable in the configuration +syntax.) By default this option is turned on. + +@item OptionColonAssignmentForNonGroups +This option controls whether a colon (`:') is output between each +non-group setting's name and its value when the configuration is written +to a file or stream. If the option is turned off, an equals sign (`=') +is output instead. (These tokens are interchangeable in the configuration +syntax.) By default this option is turned off. + +@item OptionOpenBraceOnSeparateLine +This option controls whether an open brace (`@{') will be written on its own +line when the configuration is written to a file or stream. If the option is +turned off, the brace will be written at the end of the previous line. +By default this option is turned on. + +@end table + +@end deftypemethod + @deftypemethod Config void setAutoConvert (bool @var{flag}) @deftypemethodx Config bool getAutoConvert () -@code{setAutoConvert()} enables number auto-conversion for the -configuration if @var{flag} is @code{true}, and disables it -otherwise. When this feature is enabled, an attempt to assign a -floating point setting to an integer (or vice versa), or -assign an integer to a floating point setting (or vice versa) will -cause the library to silently perform the necessary conversion -(possibly leading to loss of data), rather than throwing a -@code{SettingTypeException}. By default this feature is disabled. - -@code{getAutoConvert()} returns @code{true} if number auto-conversion -is currently enabled for the configuration; otherwise it returns -@code{false}. +These methods get and set the @code{OptionAutoConvert} option. They +are obsoleted by the @code{setOptions()} and @code{getOptions()} +methods described above. @end deftypemethod @@ -1542,6 +1657,15 @@ configuration. @end deftypemethod +@deftypemethod Setting {Setting &} lookup (@w{const char * @var{path}}) +@deftypemethodx Setting {Setting &} lookup (@w{const std::string &@var{path}}) + +This function locates a setting by a path @var{path} relative to +this setting. If requested setting is not found, a +@code{SettingNotFoundException} is thrown. + +@end deftypemethod + @deftypemethod Setting bool lookupValue (@w{const char *@var{name}}, @w{bool &@var{value}}) @deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{bool &@var{value}}) @@ -1744,6 +1868,17 @@ These methods test if the setting has a child setting with the given @code{false} otherwise. These methods do not throw exceptions. @end deftypemethod +@page +@deftypemethod Setting iterator begin () +@deftypemethodx Setting iterator end () +@deftypemethodx Setting const_iterator begin () +@deftypemethodx Setting const_iterator end () + +These methods return STL-style iterators that can be used to enumerate +the child settings of a given setting. If the setting is not an array, list, +or group, they throw a @code{SettingTypeException}. + +@end deftypemethod @deftypemethod Setting int getLength () |