Skip to content

L
libconfig
Commit 7ef44826 authored by Mark Lindner's avatar Mark Lindner
Browse files
Options

Documentation updates.

parent 01bc2250
Hide whitespace changes
Inline Side-by-side
Showing with 213 additions and 90 deletions
ChangeLog
View file @ 7ef44826
......@@ -2,52 +2,53 @@
2017-10-24 Mark Lindner <markl@avalon>
* INSTALL - Added information about installing from a git snapshot
* configure.ac - Bumped version to 1.7
* doc/libconfig.texi - Updated documentation
* examples/c/Makefile.am, examples/c/example4.c, examples/c/example4.cfg,
examples/c/cfg_includes/*.cfg - New example program
* lib/Makefile.am - bumped library version to 11:0:0; added new source
files
* lib/grammar.c, lib/grammar.y, lib/scanner.c, lib/scanner.h - regenerated
* lib/grammar.y - allow optional trailing comma in lists and arrays
* *.vcproj - updated with new source files, library dependency
* lib/libconfig.c, lib/libconfig.h - various code cleanup;
reworked options API; moved some value parsing logic into lib/util.c
and lib/util.h; added new option
CONFIG_OPTION_ALLOW_SCIENTIFIC_NOTATION; bugfix to disallow adding a
group to a list or array; changed default float precision from 2 to 6;
fixed conversion between int and int64 types; added config_clear();
added support for include functions; added config_set_hook() and
config_get_hook()
* lib/libconfigcpp.c++, lib/libconfig.h++ - moved Option enum from Setting
to Config; added OptionAllowScientificNotation; added clear();
reworked options API; added evaluateIncludePath(); fixed casting to
unsigned int (don't clip negative values to 0)
* lib/parsectx.c, lib/parsectx.h - code cleanup
* lib/scanctx.c, lib/scanctx.h - added support for include functions;
code cleanup; removed non-portable directory reading code;
* lib/scanner.l - added support for include functions; moved some parsing
code to lib/util.c and lib/util.h; code cleanup
* lib/strbuf.c, lib/strbuf.h - added strbuf_append_char(); code cleanup
* lib/strvec.c, lib/strvec.h - new functions for managing arrays of
string pointers (for filename lists)
* lib/util.c, lib/util.h - value parsing and formatting code and memory
management macros and functions extracted from other files
* lib/wincompat.h - new macros for testing relative paths; replaced
INT32_MAX/INT32_MIN with INT_MAX/INT_MIN.
* tests/tests.c - fixed test failures and improper testing of int type
conversions
* INSTALL - Added information about installing from a git snapshot
* configure.ac - Bumped version to 1.7
* doc/libconfig.texi - Updated documentation, added new chapter on
libconfig bindings/implementations for other languages
* examples/c/Makefile.am, examples/c/example4.c, examples/c/example4.cfg,
examples/c/cfg_includes/*.cfg - New example program
* lib/Makefile.am - bumped library version to 11:0:0; added new source
files
* lib/grammar.c, lib/grammar.y, lib/scanner.c, lib/scanner.h - regenerated
* lib/grammar.y - allow optional trailing comma in lists and arrays
* *.vcproj - updated with new source files, library dependency
* lib/libconfig.c, lib/libconfig.h - various code cleanup;
reworked options API; moved some value parsing logic into lib/util.c
and lib/util.h; added new option
CONFIG_OPTION_ALLOW_SCIENTIFIC_NOTATION; bugfix to disallow adding a
group to a list or array; changed default float precision from 2 to 6;
fixed conversion between int and int64 types; added config_clear();
added support for include functions; added config_set_hook() and
config_get_hook()
* lib/libconfigcpp.c++, lib/libconfig.h++ - moved Option enum from Setting
to Config; added OptionAllowScientificNotation; added clear();
reworked options API; added evaluateIncludePath(); fixed casting to
unsigned int (don't clip negative values to 0)
* lib/parsectx.c, lib/parsectx.h - code cleanup
* lib/scanctx.c, lib/scanctx.h - added support for include functions;
code cleanup; removed non-portable directory reading code;
* lib/scanner.l - added support for include functions; moved some parsing
code to lib/util.c and lib/util.h; code cleanup
* lib/strbuf.c, lib/strbuf.h - added strbuf_append_char(); code cleanup
* lib/strvec.c, lib/strvec.h - new functions for managing arrays of
string pointers (for filename lists)
* lib/util.c, lib/util.h - value parsing and formatting code and memory
management macros and functions extracted from other files
* lib/wincompat.h - new macros for testing relative paths; replaced
INT32_MAX/INT32_MIN with INT_MAX/INT_MIN.
* tests/tests.c - fixed test failures and improper testing of int type
conversions
----- version 1.6 ------
2015-12-31 Jose Luis Tallon <jltallon@adv-solutions.net>
* Added include_dir feature (support for Debian-style conf.d/
includes) (pull request #36)
* Added include_dir feature (support for Debian-style conf.d/
includes) (pull request #36)
* Added octal_ints feature (support for integer expressed in octal,
useful for permissions and masks in UNIX-like systems (pull req #42)
* Added octal_ints feature (support for integer expressed in octal,
useful for permissions and masks in UNIX-like systems (pull req #42)
* Fixed "Removing a setting removes all siblings" (issue #41)
Props random85
......@@ -58,11 +59,11 @@
* Make libconfig usable from CMake (pull request/issue #28)
Props thfi
* Documentation fixes
* Documentation fixes
- Copyright and examples
- Included TeX patch from Debian (fixes FTBS with TeXlive)
* Resync Debian packaging
* Resync Debian packaging
includes updated packages for GCC5 transition
2015-10-14 Thomas Fischer <fischer@unix-ag.uni-kl.de>
......
TODO
View file @ 7ef44826
......@@ -11,11 +11,6 @@ intended purpose of this library. I think something like sqlite is better
suited for that sort of thing.
* Add an option for safe type conversions; that is, report an error
rather than silently truncating out-of-range values to 0 (namely int64 ->
int).
* Add support for copying settings from one configuration to another. Need a
recursive function to copy a setting and call itself on all child settings.
......@@ -36,7 +31,7 @@ suited for that sort of thing.
add a lot of complexity to the library.
* Add limited support for preserving comments?
* Add limited support for preserving comments.
* Add support for unicode strings? A bit problematic, since flex doesn't
......
doc/libconfig.texi
View file @ 7ef44826
......@@ -77,8 +77,9 @@ Version @value{edition}<br>
* The C API::
* The C++ API::
* Example Programs::
* Configuration File Grammar::
* Other Bindings and Implementations::
* License::
* Configuration File Grammar::
* Function Index::
* Type Index::
* Concept Index::
......@@ -667,18 +668,18 @@ info: @{
@end cartouche
The resulting configuration will be equivalent to one in which the
contents of the ``quote.cfg`` file appeared at the point where the
contents of the file @samp{quote.cfg} appeared at the point where the
include directive is placed.
Include files may be nested to a maximum of 10 levels; exceeding this
limit results in a parse error.
When the path argument to an @b{@@include} directive
begins with a PATH_SEPARATOR ('/' or '\'), it is considered to be absolute.
Alternatively, when an include directory has been set by means of a
@b{config_set_include_dir} call, the directory and/or filename will be
taken as relative to that directory. Otherwise, the name is interpreted as
relative to the program's current working directory.
When the path argument to an @b{@@include} directive is a relative
path, then it will be interpreted as being relative to the include
directory that has been been set by means of
@code{config_set_include_dir()}. If no include directory has been set,
then it will be taken as being relative to the program's current
working directory.
Like comments, include directives are not part of the configuration
file syntax. They are processed before the configuration itself is
......@@ -1271,7 +1272,7 @@ the setting @var{setting} is of a given type. They return
@deftypefunx int config_setting_is_number (@w{const config_setting_t * @var{setting}})
@cindex aggregate value
These convenience functions, which are implemented as macros, test if
These convenience functions, some of which are implemented as macros, test if
the setting @var{setting} is of an aggregate type (a group, array, or
list), of a scalar type (integer, 64-bit integer, floating point,
boolean, or string), and of a number (integer, 64-bit integer, or
......@@ -2159,7 +2160,7 @@ application-level errors.
@end deftypemethod
@node Example Programs, Configuration File Grammar, The C++ API, Top
@node Example Programs, Other Bindings and Implementations, The C++ API, Top
@comment node-name, next, previous, up
@chapter Example Programs
......@@ -2198,37 +2199,165 @@ wildcard includes. Note that this code will not compile on Windows.
@end table
@node Configuration File Grammar, License, Example Programs, Top
@node Other Bindings and Implementations, License, Example Programs, Top
@comment node-name, next, previous, up
@chapter Configuration File Grammar
@chapter Other Bindings and Implementations
@menu
* Bourne Shell::
* D::
* Haskell::
* Java::
* Lisp::
* Perl::
* Python::
* Ruby::
@end menu
Below is the BNF grammar for configuration files. Comments and include
directives are not part of the grammar, so they are not included here.
Various open-source libraries have been written that provide access to
@i{libconfig}-style configuration files from other programming languages. Some
of these libraries are wrappers which add new language bindings for
@i{libconfig} while others are syntax-compatible reimplementations in other
languages.
@sp 1
@example
configuration = setting-list | empty
Here is a list of some of these implementations.
@node Bourne Shell, D, , Other Bindings and Implementations
@comment node-name, next, previous, up
@section Bourne Shell
setting-list = setting | setting-list setting
@L{}ukasz A. Grabowski's @i{ls-config} provides a means to read and write
values in @i{libconfig} configuration files from Bourne shell scripts. The
implementation is included in the @i{libconfig} git repository at
@url{https://github.com/hyperrealm/libconfig}, in the @file{contrib/ls-config}
subdirectory.
setting = name (":" | "=") value (";" | "," | empty)
@node D, Haskell, Bourne Shell, Other Bindings and Implementations
@comment node-name, next, previous, up
@section D
Remi Thebault's @i{libconfig-d} is a port of @i{libconfig} to the D programming
language. It may be found at @url{https://code.dlang.org/packages/libconfig-d}.
@node Haskell, Java, D, Other Bindings and Implementations
@comment node-name, next, previous, up
@section Haskell
value = scalar-value | array | list | group
Matthew Peddie's @i{libconfig} provides Haskell bindings to
@i{libconfig}. It may be found at
@url{https://hackage.haskell.org/package/libconfig-0.3.0.0}.
value-list = value | value-list "," value
@node Java, Lisp, Haskell, Other Bindings and Implementations
@comment node-name, next, previous, up
@section Java
scalar-value = boolean | integer | integer64 | hex | hex64 | float
| string
Andrey V. Pleskach has a pure-Java implementation of @i{libconfig}. It may be
found on github at @url{https://github.com/willyborankin/libconfig}.
scalar-value-list = scalar-value | scalar-value-list "," scalar-value
@node Lisp, Perl, Java, Other Bindings and Implementations
@comment node-name, next, previous, up
@section Lisp
array = "[" (scalar-value-list | empty) "]"
Oleg Shalaev's @i{cl-libconfig} provides Common Lisp bindings for @i{libconfig}.
It may be found on github at @url{https://github.com/chalaev/cl-libconfig}.
@node Perl, Python, Lisp, Other Bindings and Implementations
@comment node-name, next, previous, up
@section Perl
The @i{Conf::Libconfig} module provides Perl bindings for @i{libconfig}. It may
be found on CPAN at @url{http://search.cpan.org/~cnangel/Conf-Libconfig-0.05/}
or on github at @url{https://github.com/cnangel/Conf-Libconfig}.
@node Python, Ruby, Perl, Other Bindings and Implementations
@comment node-name, next, previous, up
@section Python
list = "(" (value-list | empty) ")"
Heiner Tholen's @i{pylibconfig2} is a Python library that is syntax-compatible
with @i{libconfig}. It may be found at
@url{https://pypi.python.org/pypi/pylibconfig2/0.1.2}.
group = "@{" (setting-list | empty) "@}"
Christian Aichinger's @i{libconf} is another pure-Python implementation with a
more permissive license. It may be found at
@url{https://pypi.python.org/pypi/libconf} or on github at
@url{https://github.com/Grk0/python-libconf}.
empty =
The @i{python-libconfig} wrapper provides Python bindings to @i{libconfig}. It
may be found on github at @url{https://github.com/cnangel/python-libconfig/}.
@node Ruby, , Python, Other Bindings and Implementations
@comment node-name, next, previous, up
@section Ruby
Christopher Mark Gore's @i{ruby-libconfig} is a Ruby library that provides Ruby
bindings for @i{libconfig}. It may be found at
@url{https://rubygems.org/gems/libconfig/versions/0.0.1} or on github at
@url{https://github.com/cgore/ruby-libconfig}.
There is also another Ruby wrapper, @i{libconfig-ruby}, that is included in
the @i{libconfig} git repository at @url{https://github.com/hyperrealm/libconfig},
in the @file{contrib/libconfig-ruby} subdirectory.
@node License, Configuration File Grammar, Other Bindings and Implementations, Top
@comment node-name, next, previous, up
@appendix License
@include LGPL.texi
@node Configuration File Grammar, Function Index, License, Top
@comment node-name, next, previous, up
@appendix Configuration File Grammar
Below is the BNF grammar for configuration files. Comments and include
directives are not part of the grammar, so they are not included here.
@sp 1
@example
<configuration> ::=
<setting-list>
| <empty>
<setting-list> ::=
<setting>
| <setting-list> <setting>
<setting> ::=
<name> ( ":" | "=" ) <value> ( ";" | "," | <empty> )
<value> ::=
<scalar-value>
| <array>
| <list>
| <group>
<value-list> ::=
<value>
| <value-list> "," <value>
| <value-list> ","
<scalar-value> ::=
<boolean>
| <integer>
| <integer64>
| <hex>
| <hex64>
| <float>
| <string>
<scalar-value-list> ::=
<scalar-value>
| <scalar-value-list> "," <scalar-value>
| <scalar-value-list> ","
<array> ::=
"[" ( <scalar-value-list> | <empty> ) "]"
<list> ::=
"(" ( <value-list> | <empty> ) ")"
<group> ::=
"@{" ( <setting-list> | <empty> ) "@}"
<empty> ::=
@end example
@sp 2
......@@ -2236,31 +2365,29 @@ Terminals are defined below as regular expressions:
@sp 1
@multitable @columnfractions .2 .8
@item @code{boolean} @tab
@item @code{<boolean>} @tab
@code{([Tt][Rr][Uu][Ee])|([Ff][Aa][Ll][Ss][Ee])}
@item @code{string} @tab
@item @code{<string>} @tab
@code{\"([^\"\\]|\\.)*\"}
@item @code{name} @tab
@item @code{<name>} @tab
@code{[A-Za-z\*][-A-Za-z0-9_\*]*}
@item @code{integer} @tab
@item @code{<integer>} @tab
@code{[-+]?[0-9]+}
@item @code{integer64} @tab
@item @code{<integer64>} @tab
@code{[-+]?[0-9]+L(L)?}
@item @code{hex} @tab
@item @code{<hex>} @tab
@code{0[Xx][0-9A-Fa-f]+}
@item @code{hex64} @tab
@item @code{<hex64>} @tab
@code{0[Xx][0-9A-Fa-f]+(L(L)?)?}
@item @code{float} @tab
@item @code{<float>} @tab
@code{([-+]?([0-9]*)?\.[0-9]*([eE][-+]?[0-9]+)?)|([-+]([0-9]+)(\.[0-9]*)?[eE][-+]?[0-9]+)}
@end multitable
@node License, Function Index, Configuration File Grammar, Top
@comment node-name, next, previous, up
@appendix License
@include LGPL.texi
Note that adjacent strings are automatically concatenated. Non-printable
characters can be represented within strings using a sequence @samp{\xx},
representing the ASCII value as two hex digits.
@node Function Index, Type Index, License, Top
@node Function Index, Type Index, Configuration File Grammar, Top
@comment node-name, next, previous, up
@unnumbered Function Index
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment