diff options
| author | Jonathan McCrohan <jmccrohan@gmail.com> | 2011-12-01 23:47:41 +0000 |
|---|---|---|
| committer | Jonathan McCrohan <jmccrohan@gmail.com> | 2011-12-01 23:47:41 +0000 |
| commit | 1eaceca55c7e62892fd28bfbb5fc03240a48cee3 (patch) | |
| tree | 7243fcd09c57e06e72b15f0044fd2c77babd7843 /doc | |
| parent | d4b5ddf4bcacd692011f5a597025c38a1262d6ca (diff) | |
| parent | 429e46051dba814e7d6c74368eb1bba550222cbe (diff) | |
| download | libconfig-1eaceca55c7e62892fd28bfbb5fc03240a48cee3.tar.gz | |
Merge commit 'upstream/1.4.8'
Conflicts:
debian/changelog
debian/control
debian/libconfig++9-dev.install
debian/libconfig8.install
debian/libconfig9-dev.install
debian/rules
Diffstat (limited to '')
| -rw-r--r-- | aux-build/texinfo.tex (renamed from doc/texinfo.tex) | 0 | ||||
| -rw-r--r-- | doc/Makefile.in | 188 | ||||
| -rw-r--r-- | doc/libconfig.info | 826 | ||||
| -rw-r--r-- | doc/libconfig.texi | 580 |
4 files changed, 1132 insertions, 462 deletions
diff --git a/doc/texinfo.tex b/aux-build/texinfo.tex index c93912a..c93912a 100644 --- a/doc/texinfo.tex +++ b/aux-build/texinfo.tex diff --git a/doc/Makefile.in b/doc/Makefile.in index 108f5b4..784612e 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -1,8 +1,9 @@ -# Makefile.in generated by automake 1.10.1 from Makefile.am. +# Makefile.in generated by automake 1.11.1 from Makefile.am. # @configure_input@ # Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, -# 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. +# 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, +# Inc. # This Makefile.in is free software; the Free Software Foundation # gives unlimited permission to copy and/or distribute it, # with or without modifications, as long as this notice is preserved. @@ -15,8 +16,9 @@ @SET_MAKE@ VPATH = @srcdir@ pkgdatadir = $(datadir)/@PACKAGE@ -pkglibdir = $(libdir)/@PACKAGE@ pkgincludedir = $(includedir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkglibexecdir = $(libexecdir)/@PACKAGE@ am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd install_sh_DATA = $(install_sh) -c -m 644 install_sh_PROGRAM = $(install_sh) -c @@ -34,18 +36,20 @@ host_triplet = @host@ target_triplet = @target@ subdir = doc DIST_COMMON = $(libconfig_TEXINFOS) $(srcdir)/Makefile.am \ - $(srcdir)/Makefile.in texinfo.tex + $(srcdir)/Makefile.in ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 am__aclocal_m4_deps = $(top_srcdir)/configure.ac am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ $(ACLOCAL_M4) -mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs +mkinstalldirs = $(SHELL) $(top_srcdir)/aux-build/mkinstalldirs CONFIG_HEADER = $(top_builddir)/ac_config.h CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = SOURCES = DIST_SOURCES = INFO_DEPS = $(srcdir)/libconfig.info -am__TEXINFO_TEX_DIR = $(srcdir) +TEXINFO_TEX = $(top_srcdir)/aux-build/texinfo.tex +am__TEXINFO_TEX_DIR = $(top_srcdir)/aux-build DVIS = libconfig.dvi PDFS = libconfig.pdf PSS = libconfig.ps @@ -62,7 +66,22 @@ am__vpath_adj = case $$p in \ $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \ *) f=$$p;; \ esac; -am__strip_dir = `echo $$p | sed -e 's|^.*/||'`; +am__strip_dir = f=`echo $$p | sed -e 's|^.*/||'`; +am__install_max = 40 +am__nobase_strip_setup = \ + srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*|]/\\\\&/g'` +am__nobase_strip = \ + for p in $$list; do echo "$$p"; done | sed -e "s|$$srcdirstrip/||" +am__nobase_list = $(am__nobase_strip_setup); \ + for p in $$list; do echo "$$p $$p"; done | \ + sed "s| $$srcdirstrip/| |;"' / .*\//!s/ .*/ ./; s,\( .*\)/[^/]*$$,\1,' | \ + $(AWK) 'BEGIN { files["."] = "" } { files[$$2] = files[$$2] " " $$1; \ + if (++n[$$2] == $(am__install_max)) \ + { print $$2, files[$$2]; n[$$2] = 0; files[$$2] = "" } } \ + END { for (dir in files) print dir, files[dir] }' +am__base_list = \ + sed '$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;$$!N;s/\n/ /g' | \ + sed '$$!N;$$!N;$$!N;$$!N;s/\n/ /g' DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) ACLOCAL = @ACLOCAL@ AMTAR = @AMTAR@ @@ -86,20 +105,20 @@ DEFS = @DEFS@ DEPDIR = @DEPDIR@ DLLTOOL = @DLLTOOL@ DSYMUTIL = @DSYMUTIL@ -ECHO = @ECHO@ +DUMPBIN = @DUMPBIN@ ECHO_C = @ECHO_C@ ECHO_N = @ECHO_N@ ECHO_T = @ECHO_T@ EGREP = @EGREP@ EXEEXT = @EXEEXT@ -F77 = @F77@ -FFLAGS = @FFLAGS@ +FGREP = @FGREP@ GREP = @GREP@ INSTALL = @INSTALL@ INSTALL_DATA = @INSTALL_DATA@ INSTALL_PROGRAM = @INSTALL_PROGRAM@ INSTALL_SCRIPT = @INSTALL_SCRIPT@ INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +LD = @LD@ LDFLAGS = @LDFLAGS@ LEX = @LEX@ LEXLIB = @LEXLIB@ @@ -107,18 +126,23 @@ LEX_OUTPUT_ROOT = @LEX_OUTPUT_ROOT@ LIBOBJS = @LIBOBJS@ LIBS = @LIBS@ LIBTOOL = @LIBTOOL@ +LIPO = @LIPO@ LN_S = @LN_S@ LTLIBOBJS = @LTLIBOBJS@ MAKEINFO = @MAKEINFO@ MKDIR_P = @MKDIR_P@ +NM = @NM@ NMEDIT = @NMEDIT@ OBJDUMP = @OBJDUMP@ OBJEXT = @OBJEXT@ +OTOOL = @OTOOL@ +OTOOL64 = @OTOOL64@ PACKAGE = @PACKAGE@ PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ PACKAGE_NAME = @PACKAGE_NAME@ PACKAGE_STRING = @PACKAGE_STRING@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_URL = @PACKAGE_URL@ PACKAGE_VERSION = @PACKAGE_VERSION@ PATH_SEPARATOR = @PATH_SEPARATOR@ RANLIB = @RANLIB@ @@ -135,7 +159,7 @@ abs_top_builddir = @abs_top_builddir@ abs_top_srcdir = @abs_top_srcdir@ ac_ct_CC = @ac_ct_CC@ ac_ct_CXX = @ac_ct_CXX@ -ac_ct_F77 = @ac_ct_F77@ +ac_ct_DUMPBIN = @ac_ct_DUMPBIN@ am__include = @am__include@ am__leading_dot = @am__leading_dot@ am__quote = @am__quote@ @@ -195,14 +219,14 @@ $(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(am__configure_deps) @for dep in $?; do \ case '$(am__configure_deps)' in \ *$$dep*) \ - cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh \ - && exit 0; \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ exit 1;; \ esac; \ done; \ - echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/Makefile'; \ - cd $(top_srcdir) && \ - $(AUTOMAKE) --gnu doc/Makefile + echo ' cd $(top_srcdir) && $(AUTOMAKE) --gnu doc/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --gnu doc/Makefile .PRECIOUS: Makefile Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status @case '$?' in \ @@ -220,6 +244,7 @@ $(top_srcdir)/configure: $(am__configure_deps) cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh $(ACLOCAL_M4): $(am__aclocal_m4_deps) cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): mostlyclean-libtool: -rm -f *.lo @@ -229,7 +254,7 @@ clean-libtool: .texi.info: restore=: && backupdir="$(am__leading_dot)am$$$$" && \ - am__cwd=`pwd` && cd $(srcdir) && \ + am__cwd=`pwd` && $(am__cd) $(srcdir) && \ rm -rf $$backupdir && mkdir $$backupdir && \ if ($(MAKEINFO) --version) >/dev/null 2>&1; then \ for f in $@ $@-[0-9] $@-[0-9][0-9] $(@:.info=).i[0-9] $(@:.info=).i[0-9][0-9]; do \ @@ -241,10 +266,10 @@ clean-libtool: -o $@ $<; \ then \ rc=0; \ - cd $(srcdir); \ + $(am__cd) $(srcdir); \ else \ rc=$$?; \ - cd $(srcdir) && \ + $(am__cd) $(srcdir) && \ $$restore $$backupdir/* `echo "./$@" | sed 's|[^/]*$$||'`; \ fi; \ rm -rf $$backupdir; exit $$rc @@ -282,16 +307,18 @@ libconfig.html: libconfig.texi $(libconfig_TEXINFOS) uninstall-dvi-am: @$(NORMAL_UNINSTALL) - @list='$(DVIS)'; for p in $$list; do \ - f=$(am__strip_dir) \ + @list='$(DVIS)'; test -n "$(dvidir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ echo " rm -f '$(DESTDIR)$(dvidir)/$$f'"; \ rm -f "$(DESTDIR)$(dvidir)/$$f"; \ done uninstall-html-am: @$(NORMAL_UNINSTALL) - @list='$(HTMLS)'; for p in $$list; do \ - f=$(am__strip_dir) \ + @list='$(HTMLS)'; test -n "$(htmldir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ echo " rm -rf '$(DESTDIR)$(htmldir)/$$f'"; \ rm -rf "$(DESTDIR)$(htmldir)/$$f"; \ done @@ -305,7 +332,8 @@ uninstall-info-am: for file in $$list; do \ relfile=`echo "$$file" | sed 's|^.*/||'`; \ echo " install-info --info-dir='$(DESTDIR)$(infodir)' --remove '$(DESTDIR)$(infodir)/$$relfile'"; \ - install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \ + if install-info --info-dir="$(DESTDIR)$(infodir)" --remove "$(DESTDIR)$(infodir)/$$relfile"; \ + then :; else test ! -f "$(DESTDIR)$(infodir)/$$relfile" || exit 1; fi; \ done; \ else :; fi @$(NORMAL_UNINSTALL) @@ -321,16 +349,18 @@ uninstall-info-am: uninstall-pdf-am: @$(NORMAL_UNINSTALL) - @list='$(PDFS)'; for p in $$list; do \ - f=$(am__strip_dir) \ + @list='$(PDFS)'; test -n "$(pdfdir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ echo " rm -f '$(DESTDIR)$(pdfdir)/$$f'"; \ rm -f "$(DESTDIR)$(pdfdir)/$$f"; \ done uninstall-ps-am: @$(NORMAL_UNINSTALL) - @list='$(PSS)'; for p in $$list; do \ - f=$(am__strip_dir) \ + @list='$(PSS)'; test -n "$(psdir)" || list=; \ + for p in $$list; do \ + $(am__strip_dir) \ echo " rm -f '$(DESTDIR)$(psdir)/$$f'"; \ rm -f "$(DESTDIR)$(psdir)/$$f"; \ done @@ -347,8 +377,8 @@ dist-info: $(INFO_DEPS) for file in $$d/$$base $$d/$$base-[0-9] $$d/$$base-[0-9][0-9] $$d/$$base_i[0-9] $$d/$$base_i[0-9][0-9]; do \ if test -f $$file; then \ relfile=`expr "$$file" : "$$d/\(.*\)"`; \ - test -f $(distdir)/$$relfile || \ - cp -p $$file $(distdir)/$$relfile; \ + test -f "$(distdir)/$$relfile" || \ + cp -p $$file "$(distdir)/$$relfile"; \ else :; fi; \ done; \ done @@ -357,8 +387,11 @@ mostlyclean-aminfo: -rm -rf libconfig.aux libconfig.cp libconfig.cps libconfig.fn libconfig.fns \ libconfig.ky libconfig.kys libconfig.log libconfig.pg \ libconfig.pgs libconfig.tmp libconfig.toc libconfig.tp \ - libconfig.tps libconfig.vr libconfig.vrs libconfig.dvi \ - libconfig.pdf libconfig.ps libconfig.html + libconfig.tps libconfig.vr libconfig.vrs + +clean-aminfo: + -test -z "libconfig.dvi libconfig.pdf libconfig.ps libconfig.html" \ + || rm -rf libconfig.dvi libconfig.pdf libconfig.ps libconfig.html maintainer-clean-aminfo: @list='$(INFO_DEPS)'; for i in $$list; do \ @@ -389,13 +422,17 @@ distdir: $(DISTFILES) if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ if test -d $$d/$$file; then \ dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ - cp -pR $(srcdir)/$$file $(distdir)$$dir || exit 1; \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ fi; \ - cp -pR $$d/$$file $(distdir)$$dir || exit 1; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ else \ - test -f $(distdir)/$$file \ - || cp -p $$d/$$file $(distdir)/$$file \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ || exit 1; \ fi; \ done @@ -429,13 +466,14 @@ clean-generic: distclean-generic: -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) maintainer-clean-generic: @echo "This command is intended for maintainers to use" @echo "it deletes files that may require special tools to rebuild." clean: clean-am -clean-am: clean-generic clean-libtool mostlyclean-am +clean-am: clean-aminfo clean-generic clean-libtool mostlyclean-am distclean: distclean-am -rm -f Makefile @@ -458,11 +496,14 @@ install-dvi: install-dvi-am install-dvi-am: $(DVIS) @$(NORMAL_INSTALL) test -z "$(dvidir)" || $(MKDIR_P) "$(DESTDIR)$(dvidir)" - @list='$(DVIS)'; for p in $$list; do \ + @list='$(DVIS)'; test -n "$(dvidir)" || list=; \ + for p in $$list; do \ if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ - f=$(am__strip_dir) \ - echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(dvidir)/$$f'"; \ - $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(dvidir)/$$f"; \ + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(dvidir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(dvidir)" || exit $$?; \ done install-exec-am: @@ -471,26 +512,31 @@ install-html: install-html-am install-html-am: $(HTMLS) @$(NORMAL_INSTALL) test -z "$(htmldir)" || $(MKDIR_P) "$(DESTDIR)$(htmldir)" - @list='$(HTMLS)'; for p in $$list; do \ + @list='$(HTMLS)'; list2=; test -n "$(htmldir)" || list=; \ + for p in $$list; do \ if test -f "$$p" || test -d "$$p"; then d=; else d="$(srcdir)/"; fi; \ - f=$(am__strip_dir) \ + $(am__strip_dir) \ if test -d "$$d$$p"; then \ echo " $(MKDIR_P) '$(DESTDIR)$(htmldir)/$$f'"; \ $(MKDIR_P) "$(DESTDIR)$(htmldir)/$$f" || exit 1; \ echo " $(INSTALL_DATA) '$$d$$p'/* '$(DESTDIR)$(htmldir)/$$f'"; \ - $(INSTALL_DATA) "$$d$$p"/* "$(DESTDIR)$(htmldir)/$$f"; \ + $(INSTALL_DATA) "$$d$$p"/* "$(DESTDIR)$(htmldir)/$$f" || exit $$?; \ else \ - echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(htmldir)/$$f'"; \ - $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(htmldir)/$$f"; \ + list2="$$list2 $$d$$p"; \ fi; \ - done + done; \ + test -z "$$list2" || { echo "$$list2" | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(htmldir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(htmldir)" || exit $$?; \ + done; } install-info: install-info-am install-info-am: $(INFO_DEPS) @$(NORMAL_INSTALL) test -z "$(infodir)" || $(MKDIR_P) "$(DESTDIR)$(infodir)" @srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`; \ - list='$(INFO_DEPS)'; \ + list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \ for file in $$list; do \ case $$file in \ $(srcdir)/*) file=`echo "$$file" | sed "s|^$$srcdirstrip/||"`;; \ @@ -498,18 +544,19 @@ install-info-am: $(INFO_DEPS) if test -f $$file; then d=.; else d=$(srcdir); fi; \ file_i=`echo "$$file" | sed 's|\.info$$||;s|$$|.i|'`; \ for ifile in $$d/$$file $$d/$$file-[0-9] $$d/$$file-[0-9][0-9] \ - $$d/$$file_i[0-9] $$d/$$file_i[0-9][0-9] ; do \ + $$d/$$file_i[0-9] $$d/$$file_i[0-9][0-9] ; do \ if test -f $$ifile; then \ - relfile=`echo "$$ifile" | sed 's|^.*/||'`; \ - echo " $(INSTALL_DATA) '$$ifile' '$(DESTDIR)$(infodir)/$$relfile'"; \ - $(INSTALL_DATA) "$$ifile" "$(DESTDIR)$(infodir)/$$relfile"; \ + echo "$$ifile"; \ else : ; fi; \ done; \ - done + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(infodir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(infodir)" || exit $$?; done @$(POST_INSTALL) @if (install-info --version && \ install-info --version 2>&1 | sed 1q | grep -i -v debian) >/dev/null 2>&1; then \ - list='$(INFO_DEPS)'; \ + list='$(INFO_DEPS)'; test -n "$(infodir)" || list=; \ for file in $$list; do \ relfile=`echo "$$file" | sed 's|^.*/||'`; \ echo " install-info --info-dir='$(DESTDIR)$(infodir)' '$(DESTDIR)$(infodir)/$$relfile'";\ @@ -523,23 +570,27 @@ install-pdf: install-pdf-am install-pdf-am: $(PDFS) @$(NORMAL_INSTALL) test -z "$(pdfdir)" || $(MKDIR_P) "$(DESTDIR)$(pdfdir)" - @list='$(PDFS)'; for p in $$list; do \ + @list='$(PDFS)'; test -n "$(pdfdir)" || list=; \ + for p in $$list; do \ if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ - f=$(am__strip_dir) \ - echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(pdfdir)/$$f'"; \ - $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(pdfdir)/$$f"; \ - done + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(pdfdir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(pdfdir)" || exit $$?; done install-ps: install-ps-am install-ps-am: $(PSS) @$(NORMAL_INSTALL) test -z "$(psdir)" || $(MKDIR_P) "$(DESTDIR)$(psdir)" - @list='$(PSS)'; for p in $$list; do \ + @list='$(PSS)'; test -n "$(psdir)" || list=; \ + for p in $$list; do \ if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \ - f=$(am__strip_dir) \ - echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(psdir)/$$f'"; \ - $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(psdir)/$$f"; \ - done + echo "$$d$$p"; \ + done | $(am__base_list) | \ + while read files; do \ + echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(psdir)'"; \ + $(INSTALL_DATA) $$files "$(DESTDIR)$(psdir)" || exit $$?; done installcheck-am: maintainer-clean: maintainer-clean-am @@ -565,10 +616,10 @@ uninstall-am: uninstall-dvi-am uninstall-html-am uninstall-info-am \ .MAKE: install-am install-strip -.PHONY: all all-am check check-am clean clean-generic clean-libtool \ - dist-info distclean distclean-generic distclean-libtool \ - distdir dvi dvi-am html html-am info info-am install \ - install-am install-data install-data-am install-dvi \ +.PHONY: all all-am check check-am clean clean-aminfo clean-generic \ + clean-libtool dist-info distclean distclean-generic \ + distclean-libtool distdir dvi dvi-am html html-am info info-am \ + install install-am install-data install-data-am install-dvi \ install-dvi-am install-exec install-exec-am install-html \ install-html-am install-info install-info-am install-man \ install-pdf install-pdf-am install-ps install-ps-am \ @@ -582,6 +633,7 @@ uninstall-am: uninstall-dvi-am uninstall-html-am uninstall-info-am \ html: $(MAKEINFO) --html --no-split $(info_TEXINFOS) + # Tell versions [3.59,3.63) of GNU make to not export all variables. # Otherwise a system limit (for SysV at least) may be exceeded. .NOEXPORT: 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 diff --git a/doc/libconfig.texi b/doc/libconfig.texi index 22f8391..c9bc9fa 100644 --- a/doc/libconfig.texi +++ b/doc/libconfig.texi @@ -1,13 +1,13 @@ \input texinfo.tex @c -*-texinfo-*- -@c +@c @c %**start of header @c All text is ignored before the setfilename. @setfilename libconfig.info @settitle libconfig -@set edition 1.3.2 -@set update-date 18 February 2009 +@set edition 1.4.8 +@set update-date 4 August 2011 @set subtitle-text A Library For Processing Structured Configuration Files @set author-text Mark A.@: Lindner @@ -36,7 +36,7 @@ @page @vskip 0pt plus 1filll -Copyright @copyright{} 2005-2009 Mark A Lindner +Copyright @copyright{} 2005-2011 Mark A Lindner Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -76,6 +76,7 @@ Version @value{edition}<br> * Configuration Files:: * The C API:: * The C++ API:: +* Example Programs:: * Configuration File Grammar:: * License:: * Function Index:: @@ -92,6 +93,7 @@ Version @value{edition}<br> * Multithreading Issues:: * Internationalization Issues:: * Compiling Using pkg-config:: +* Version Test Macros:: @end menu @chapter Introduction @@ -124,7 +126,8 @@ libraries falls short in one or more ways. The main features of readable and compact than XML and more flexible than the obsolete but prevalent Windows ``INI'' file format. -@item A low-footprint implementation (just 38K for the C library and 66K for the C++ library) that is suitable for memory-constrained systems. +@item A low-footprint implementation (just 37K for the C library and 76K for +the C++ library) that is suitable for memory-constrained systems. @item Proper documentation. @@ -138,9 +141,9 @@ To use the library from C code, include the following preprocessor directive in your source files: @sp 1 -@example +@smallexample #include <libconfig.h> -@end example +@end smallexample @sp 1 To link with the library, specify @samp{-lconfig} as an argument to the @@ -154,26 +157,26 @@ To use the library from C++, include the following preprocessor directive in your source files: @sp 1 -@example +@smallexample #include <libconfig.h++> -@end example +@end smallexample @sp 1 Or, alternatively: @sp 1 -@example +@smallexample #include <libconfig.hh> -@end example +@end smallexample @sp 1 @page The C++ API classes are defined in the namespace @samp{libconfig}, hence the following statement may optionally be used: @sp 1 -@example +@smallexample using namespace libconfig; -@end example +@end smallexample @sp 1 To link with the library, specify @samp{-lconfig++} as an argument to @@ -231,7 +234,7 @@ floating point values are represented using a period (`.') as the radix symbol; this is consistent with the grammar of most programming languages. When a configuration is read in or written out, @i{libconfig} temporarily changes the @t{LC_NUMERIC} category of the -locale of the calling thread to the "C" locale to ensure consistent +locale of the calling thread to the ``C'' locale to ensure consistent handling of floating point values regardless of the locale(s) in use by the calling program. @@ -241,33 +244,85 @@ when using @i{libconfig} in that environment, the calling program is responsible for changing the @t{LC_NUMERIC} category of the locale to the "C" locale before reading or writing a configuration. -@node Compiling Using pkg-config, , Internationalization Issues, Introduction +@node Compiling Using pkg-config, Version Test Macros, Internationalization Issues, Introduction @comment node-name, next, previous, up @section Compiling Using pkg-config On UNIX systems you can use the @i{pkg-config} utility (version 0.20 or later) to automatically select the appropriate compiler and linker switches for @i{libconfig}. Ensure that the environment variable -@samp{PKG_CONFIG_PATH} contains the absolute path to the +@code{PKG_CONFIG_PATH} contains the absolute path to the @file{lib/pkgconfig} subdirectory of the @i{libconfig} installation. Then, you can compile and link C programs with @i{libconfig} as follows: -@example +@smallexample gcc `pkg-config --cflags libconfig` myprogram.c -o myprogram \ `pkg-config --libs libconfig` -@end example +@end smallexample @sp 1 And similarly, for C++ programs: -@example +@smallexample g++ `pkg-config --cflags libconfig++` myprogram.cpp -o myprogram \ `pkg-config --libs libconfig++` -@end example +@end smallexample @sp 1 Note the backticks in the above examples. +When using @b{autoconf}, the @code{PKG_CHECK_MODULES} m4 macro may be used to check for the presence of a given version of @i{libconfig}, and set the appropriate Makefile variables automatically. For example: + +@smallexample +PKG_CHECK_MODULES([LIBCONFIGXX], [libconfig++ >= 1.4],, + AC_MSG_ERROR([libconfig++ 1.4 or newer not found.]) +) +@end smallexample + +In the above example, if @i{libconfig++} version 1.4 or newer is found, +the Makefile variables @code{LIBCONFIGXX_LIBS} and @code{LIBCONFIGXX_CFLAGS} will be +set to the appropriate compiler and linker flags for compiling with +@i{libconfig}, and if it is not found, the configure script will abort +with an error to that effect. + +@node Version Test Macros, , Compiling Using pkg-config, Introduction +@comment node-name, next, previous, up +@section Version Test Macros + +The @file{libconfig.h} header declares the following macros: + +@defmac LIBCONFIG_VER_MAJOR +@defmacx LIBCONFIG_VER_MINOR +@defmacx LIBCONFIG_VER_REVISION + +These macros represent the major version, minor version, and revision +of the @i{libconfig} library. For example, in @i{libconfig} 1.4 these +are defined as @samp{1}, @samp{4}, and @samp{0}, respectively. These +macros can be used in preprocessor directives to determine which +@i{libconfig} features and/or APIs are present. For example: + +@smallexample +#if (((LIBCONFIG_VER_MAJOR == 1) && (LIBCONFIG_VER_MINOR >= 4)) \ + || (LIBCONFIG_VER_MAJOR > 1)) + /* use features present in libconfig 1.4 and later */ +#endif +@end smallexample + +These macros were introduced in @i{libconfig} 1.4. + +@end defmac + +Similarly, the @file{libconfig.h++} header declares the following macros: + +@defmac LIBCONFIGXX_VER_MAJOR +@defmacx LIBCONFIGXX_VER_MINOR +@defmacx LIBCONFIGXX_VER_REVISION + +These macros represent the major version, minor version, and revision +of the @i{libconfig++} library. + +@end defmac + @node Configuration Files, The C API, Introduction, Top @comment node-name, next, previous, up @menu @@ -281,6 +336,7 @@ Note the backticks in the above examples. * Boolean Values:: * String Values:: * Comments:: +* Include Directives:: @end menu @chapter Configuration Files @@ -382,7 +438,7 @@ characters, dashes (@samp{-}), underscores (@samp{_}), and asterisks characters are allowed. In C and C++, integer, 64-bit integer, floating point, and string -values are mapped to the types @code{long}, @code{long long}, +values are mapped to the types @code{int}, @code{long long}, @code{double}, and @code{const char *}, respectively. The boolean type is mapped to @code{int} in C and @code{bool} in C++. @@ -401,7 +457,7 @@ or: @i{name} @b{:} @i{value} @b{;} -The trailing semicolon is required. Whitespace is not significant. +The trailing semicolon is optional. Whitespace is not significant. The value may be a scalar value, an array, a group, or a list. @@ -480,11 +536,19 @@ Boolean values may have one of the following values: @samp{true}, @comment node-name, next, previous, up @section String Values +@cindex escape sequence String values consist of arbitrary text delimited by double quotes. Literal double quotes can be escaped by preceding them with a backslash: @samp{\"}. The escape sequences @samp{\\}, @samp{\f}, @samp{\n}, @samp{\r}, and @samp{\t} are also recognized, and have the -usual meaning. No other escape sequences are currently supported. +usual meaning. + +In addition, the @samp{\x} escape sequence is supported; this sequence +must be followed by @i{exactly two} hexadecimal digits, which represent an +8-bit ASCII value. For example, @samp{\xFF} represents the character +with ASCII code 0xFF. + +No other escape sequences are currently supported. Adjacent strings are automatically concatenated, as in C/C++ source code. This is useful for formatting very long strings as sequences of @@ -504,7 +568,7 @@ shorter strings. For example, the following constructs are equivalent: @end itemize @page -@node Comments, , String Values, Configuration Files +@node Comments, Include Directives, String Values, Configuration Files @comment node-name, next, previous, up @section Comments @@ -532,6 +596,56 @@ not treated as part of the configuration. Therefore if the configuration is written back out to a stream, any comments that were present in the original configuration will be lost. +@node Include Directives, , Comments, Configuration Files +@comment node-name, next, previous, up +@section Include Directives + +@cindex include directive +A configuration file may ``include'' the contents of another file +using an @i{include directive}. This directive has the effect of +inlining the contents of the named file at the point of inclusion. + +An include directive must appear on its own line in the input. It has +the form: + +@b{@@include "}@i{filename}@b{"} + +Any backslashes or double quotes in the filename must be escaped as +@samp{\\} and @samp{\"}, respectively. + +For example, consider the following two configuration files: + +@cartouche +@smallexample +# file: quote.cfg +quote = "Criticism may not be agreeable, but it is necessary." + " It fulfils the same function as pain in the human" + " body. It calls attention to an unhealthy state of" + " things.\n" + "\t--Winston Churchill"; +@end smallexample +@end cartouche + +@cartouche +@smallexample +# file: test.cfg +info: @{ + name = "Winston Churchill"; + @@include "quote.cfg" + country = "UK"; +@}; +@end smallexample +@end cartouche + +Include files may be nested to a maximum of 10 levels; exceeding this +limit results in a parse error. + +Like comments, include directives are not part of the configuration +file syntax. They are processed before the configuration itself is +parsed. Therefore, they are not preserved when the configuration is +written back out to a stream. There is presently no support for +programmatically inserting include directives into a configuration. + @node The C API, The C++ API, Configuration Files, Top @comment node-name, next, previous, up @chapter The C API @@ -548,14 +662,14 @@ macros defined as @code{(1)} and @code{(0)}, respectively. @deftypefun void config_init (@w{config_t * @var{config}}) @deftypefunx void config_destroy (@w{config_t * @var{config}}) -These functions initialize and destroy the configuration object @var{config}. +These functions initialize and destroy the configuration object @var{config}. -@code{config_init()} initializes @var{config} as a new, empty -configuration. +@code{config_init()} initializes the @i{config_t} structure pointed to by +@var{config} as a new, empty configuration. @code{config_destroy()} destroys the configuration @var{config}, -deallocating all memory associated with the configuration, but not -including the @i{config_t} structure itself. +deallocating all memory associated with the configuration, but does not +attempt to deallocate the @i{config_t} structure itself. @end deftypefun @@ -564,9 +678,9 @@ including the @i{config_t} structure itself. This function reads and parses a configuration from the given @var{stream} into the configuration object @var{config}. It returns @code{CONFIG_TRUE} on success, or @code{CONFIG_FALSE} on failure; the -@code{config_error_text()} and @code{config_error_line()} -functions, described below, can be used to obtain information about the -error. +@code{config_error_text()}, @code{config_error_file()}, +@code{config_error_line()}, and @code{config_error_type()} functions, +described below, can be used to obtain information about the error. @end deftypefun @@ -580,6 +694,16 @@ described below, can be used to obtain information about the error. @end deftypefun +@deftypefun int config_read_string (@w{config_t * @var{config}}, @w{const char * @var{str}}) + +This function reads and parses a configuration from the string +@var{str} into the configuration object @var{config}. It returns +@code{CONFIG_TRUE} on success, or @code{CONFIG_FALSE} on failure; the +@code{config_error_text()} and @code{config_error_line()} functions, +described below, can be used to obtain information about the error. + +@end deftypefun + @deftypefun void config_write (@w{const config_t * @var{config}}, @w{FILE * @var{stream}}) This function writes the configuration @var{config} to the given @@ -596,14 +720,49 @@ This function writes the configuration @var{config} to the file named @end deftypefun @deftypefun {const char *} config_error_text (@w{const config_t * @var{config}}) +@deftypefunx {const char *} config_error_file (@w{const config_t * @var{config}}) @deftypefunx int config_error_line (@w{const config_t * @var{config}}) -These functions, which are implemented as macros, return the text and -line number of the parse error, if one occurred during a call to -@code{config_read()} or @code{config_read_file()}. Storage for the -string returned by @code{config_error_text()} is managed by the -library and released automatically when the configuration is -destroyed; the string must not be freed by the caller. +These functions, which are implemented as macros, return the text, +filename, and line number of the parse error, if one occurred during a +call to @code{config_read()}, @code{config_read_string()}, or +@code{config_read_file()}. Storage for the strings returned by +@code{config_error_text()} and @code{config_error_file()} are managed +by the library and released automatically when the configuration is +destroyed; these strings must not be freed by the caller. If the error +occurred in text that was read from a string or stream, +@code{config_error_file()} will return NULL. + +@end deftypefun + +@deftypefun config_error_t config_error_type (@w{const config_t * @var{config}}) +@tindex config_error_t +This function, which is implemented as a macro, returns the type of +error that occurred during the last call to one of the read or write +functions. The @var{config_error_t} type is an enumeration with the +following values: @code{CONFIG_ERR_NONE}, @code{CONFIG_ERR_FILE_IO}, +@code{CONFIG_ERR_PARSE}. These represent success, a file I/O error, +and a parsing error, respectively. + +@end deftypefun + +@deftypefun void config_set_include_dir (@w{config_t *@var{config}}, @w{const char *@var{include_dir}}) +@deftypefunx {const char *} config_get_include_dir (@w{const config_t *@var{config}}) + +@code{config_set_include_dir()} specifies the include directory, +@var{include_dir}, relative to which the files specified in +@samp{@@include} directives will be located for the configuration +@var{config}. By default, there is no include directory, and all +include files are expected to be relative to the current working +directory. If @var{include_dir} is @code{NULL}, the default behavior +is reinstated. + +For example, if the include directory is set to @file{/usr/local/etc}, +the include directive @samp{@@include "configs/extra.cfg"} would include the +file @file{/usr/local/etc/configs/extra.cfg}. + +@code{config_get_include_dir()} returns the current include directory for the +configuration @var{config}, or @code{NULL} if none is set. @end deftypefun @@ -625,7 +784,33 @@ returns @code{CONFIG_FALSE}. @end deftypefun -@deftypefun int config_lookup_int (@w{const config_t * @var{config}}, @w{const char * @var{path}}, @w{long * @var{value}}) +@deftypefun void config_set_default_format (@w{config_t * @var{config}}, @w{short @var{format}}) +@deftypefunx short config_get_default_format (@w{config_t * @var{config}}) + +These functions, which are implemented as macros, set and get the +default external format for settings in the configuration +@var{config}. If a non-default format has not been set for a setting +with @code{config_setting_set_format()}, this configuration-wide +default format will be used instead when that setting is written to a +file or stream. + +@end deftypefun + +@deftypefun void config_set_tab_width (@w{config_t * @var{config}}, @w{unsigned short @var{width}}) +@deftypefunx {unsigned short} config_get_tab_width (@w{const config_t * @var{config}}) + +These functions, which are implemented as macros, set and get the tab +width for the configuration @var{config}. The tab width affects the +formatting of the configuration when it is written to a file or +stream: each level of nesting is indented by @var{width} spaces, or +by a single tab character if @var{width} is 0. The tab width has no +effect on parsing. + +Valid tab widths range from 0 to 15. The default tab width is 2. + +@end deftypefun + +@deftypefun int config_lookup_int (@w{const config_t * @var{config}}, @w{const char * @var{path}}, @w{int * @var{value}}) @deftypefunx int config_lookup_int64 (@w{const config_t * @var{config}}, @w{const char * @var{path}}, @w{long long * @var{value}}) @deftypefunx int config_lookup_float (@w{const config_t * @var{config}}, @w{const char * @var{path}}, @w{double * @var{value}}) @deftypefunx int config_lookup_bool (@w{const config_t * @var{config}}, @w{const char * @var{path}}, @w{int * @var{value}}) @@ -654,7 +839,7 @@ setting was not found. @end deftypefun -@deftypefun long config_setting_get_int (@w{const config_setting_t * @var{setting}}) +@deftypefun int config_setting_get_int (@w{const config_setting_t * @var{setting}}) @deftypefunx {long long} config_setting_get_int64 (@w{const config_setting_t * @var{setting}}) @deftypefunx double config_setting_get_float (@w{const config_setting_t * @var{setting}}) @deftypefunx int config_setting_get_bool (@w{const config_setting_t * @var{setting}}) @@ -669,8 +854,7 @@ setting's value is changed; the string must not be freed by the caller. @end deftypefun -@page -@deftypefun int config_setting_set_int (@w{config_setting_t * @var{setting}}, @w{long @var{value}}) +@deftypefun int config_setting_set_int (@w{config_setting_t * @var{setting}}, @w{int @var{value}}) @deftypefunx int config_setting_set_int64 (@w{config_setting_t * @var{setting}}, @w{long long @var{value}}) @deftypefunx int config_setting_set_float (@w{config_setting_t * @var{setting}}, @w{double @var{value}}) @deftypefunx int config_setting_set_bool (@w{config_setting_t * @var{setting}}, @w{int @var{value}}) @@ -685,7 +869,7 @@ modified by the caller without affecting the value of the setting. @end deftypefun -@deftypefun int config_setting_lookup_int (@w{const config_setting_t * @var{setting}}, @w{const char * @var{name}}, @w{long * @var{value}}) +@deftypefun int config_setting_lookup_int (@w{const config_setting_t * @var{setting}}, @w{const char * @var{name}}, @w{int * @var{value}}) @deftypefunx int config_setting_lookup_int64 (@w{const config_setting_t * @var{setting}}, @w{const char * @var{name}}, @w{long long * @var{value}}) @deftypefunx int config_setting_lookup_float (@w{const config_setting_t * @var{setting}}, @w{const char * @var{name}}, @w{double * @var{value}}) @deftypefunx int config_setting_lookup_bool (@w{const config_setting_t * @var{setting}}, @w{const char * @var{name}}, @w{int * @var{value}}) @@ -721,6 +905,8 @@ integer values, and hence only applies to settings of type @code{CONFIG_TYPE_INT} and @code{CONFIG_TYPE_INT64}. If @var{format} is invalid for the given setting, it is ignored. +If a non-default format has not been set for the setting, @code{config_setting_get_format()} returns the default format for the configuration, as set by @code{config_set_default_format()}. + @code{config_setting_set_format()} returns @code{CONFIG_TRUE} on success and @code{CONFIG_FALSE} on failure. @@ -736,44 +922,44 @@ group. @end deftypefun -@deftypefun {config_setting_t *} config_setting_get_elem (@w{const config_setting_t * @var{setting}}, @w{unsigned int @var{idx}}) +@deftypefun {config_setting_t *} config_setting_get_elem (@w{const config_setting_t * @var{setting}}, @w{unsigned int @var{index}}) -This function fetches the element at the given index @var{idx} in the +This function fetches the element at the given index @var{index} in the setting @var{setting}, which must be an array, list, or group. It returns the -requested setting on success, or @code{NULL} if @var{idx} is out of +requested setting on success, or @code{NULL} if @var{index} is out of range or if @var{setting} is not an array, list, or group. @end deftypefun -@deftypefun long config_setting_get_int_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{idx}}) -@deftypefunx {long long} config_setting_get_int64_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{idx}}) -@deftypefunx double config_setting_get_float_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{idx}}) -@deftypefunx int config_setting_get_bool_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{idx}}) -@deftypefunx {const char *} config_setting_get_string_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{idx}}) +@deftypefun int config_setting_get_int_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{index}}) +@deftypefunx {long long} config_setting_get_int64_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{index}}) +@deftypefunx double config_setting_get_float_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{index}}) +@deftypefunx int config_setting_get_bool_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{index}}) +@deftypefunx {const char *} config_setting_get_string_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{index}}) -These functions return the value at the specified index @var{idx} in the +These functions return the value at the specified index @var{index} in the setting @var{setting}. If the setting is not an array or list, or if the type of the element does not match the type requested, or if -@var{idx} is out of range, they return 0 or @code{NULL}. Storage for +@var{index} is out of range, they return 0 or @code{NULL}. Storage for the string returned by @code{config_setting_get_string_elem()} is managed by the library and released automatically when the setting is destroyed or when its value is changed; the string must not be freed by the caller. @end deftypefun -@deftypefun {config_setting_t *} config_setting_set_int_elem (@w{config_setting_t * @var{setting}}, @w{int @var{idx}}, @w{long @var{value}}) -@deftypefunx {config_setting_t *} config_setting_set_int64_elem (@w{config_setting_t * @var{setting}}, @w{int @var{idx}}, @w{long long @var{value}}) -@deftypefunx {config_setting_t *} config_setting_set_float_elem (@w{config_setting_t * @var{setting}}, @w{int @var{idx}}, @w{double @var{value}}) -@deftypefunx {config_setting_t *} config_setting_set_bool_elem (@w{config_setting_t * @var{setting}}, @w{int @var{idx}}, @w{int @var{value}}) -@deftypefunx {config_setting_t *} config_setting_set_string_elem (@w{config_setting_t * @var{setting}}, @w{int @var{idx}}, @w{const char * @var{value}}) +@deftypefun {config_setting_t *} config_setting_set_int_elem (@w{config_setting_t * @var{setting}}, @w{int @var{index}}, @w{int @var{value}}) +@deftypefunx {config_setting_t *} config_setting_set_int64_elem (@w{config_setting_t * @var{setting}}, @w{int @var{index}}, @w{long long @var{value}}) +@deftypefunx {config_setting_t *} config_setting_set_float_elem (@w{config_setting_t * @var{setting}}, @w{int @var{index}}, @w{double @var{value}}) +@deftypefunx {config_setting_t *} config_setting_set_bool_elem (@w{config_setting_t * @var{setting}}, @w{int @var{index}}, @w{int @var{value}}) +@deftypefunx {config_setting_t *} config_setting_set_string_elem (@w{config_setting_t * @var{setting}}, @w{int @var{index}}, @w{const char * @var{value}}) -These functions set the value at the specified index @var{idx} in the -setting @var{setting} to @var{value}. If @var{idx} is negative, a +These functions set the value at the specified index @var{index} in the +setting @var{setting} to @var{value}. If @var{index} is negative, a new element is added to the end of the array or list. On success, these functions return a pointer to the setting representing the element. If the setting is not an array or list, or if the setting is an array and the type of the array does not match the type of the -value, or if @var{idx} is out of range, they return +value, or if @var{index} is out of range, they return @code{NULL}. @code{config_setting_set_string_elem()} makes a copy of the passed string @var{value}, so it may be subsequently freed or modified by the caller without affecting the value of the setting. @@ -789,7 +975,8 @@ is an array or list, the @var{name} parameter is ignored and may be The function returns the new setting on success, or @code{NULL} if @var{parent} is not a group, array, or list; or if there is already a child setting of @var{parent} named @var{name}; or if @var{type} is -invalid. +invalid. If @var{type} is a scalar type, the new setting will have a +default value of 0, 0.0, @code{false}, or @code{NULL}, as appropriate. @end deftypefun @deftypefun int config_setting_remove (@w{config_setting_t * @var{parent}}, @w{const char * @var{name}}) @@ -804,15 +991,15 @@ not a group, or if it has no setting with the given name, it returns @end deftypefun -@deftypefun int config_setting_remove_elem (@w{config_setting_t * @var{parent}}, @w{unsigned int @var{idx}}) +@deftypefun int config_setting_remove_elem (@w{config_setting_t * @var{parent}}, @w{unsigned int @var{index}}) -This function removes the child setting at the given index @var{idx} from +This function removes the child setting at the given index @var{index} from the setting @var{parent}, which must be a group, list, or array. Any child settings of the removed setting are recursively destroyed as well. The function returns @code{CONFIG_TRUE} on success. If @var{parent} is -not a group, list, or array, or if @var{idx} is out of range, it returns +not a group, list, or array, or if @var{index} is out of range, it returns @code{CONFIG_FALSE}. @end deftypefun @@ -897,13 +1084,23 @@ floating point), respectively. They return @code{CONFIG_TRUE} or @end deftypefun +@deftypefun {const char *} config_setting_source_file (@w{const config_setting_t * @var{setting}}) + +This function returns the name of the file from which the setting +@var{setting} was read, or NULL if the setting was not read from a +file. This information is useful for reporting application-level +errors. Storage for the returned string is managed by the library and +released automatically when the configuration is destroyed; the +string must not be freed by the caller. + +@end deftypefun + @deftypefun {unsigned int} config_setting_source_line (@w{const config_setting_t * @var{setting}}) This function returns the line number of the configuration file or -stream at which the setting @var{setting} was parsed. This information -is useful for reporting application-level errors. If the setting was -not read from a file or stream, or if the line number is otherwise -unavailable, the function returns 0. +stream at which the setting @var{setting} was read, or 0 if no line +number is available. This information is useful for reporting +application-level errors. @end deftypefun @@ -928,7 +1125,7 @@ configuration @var{config}. This function accepts a single @code{void @end deftypefun -@node The C++ API, Configuration File Grammar, The C API, Top +@node The C++ API, Example Programs, The C API, Top @comment node-name, next, previous, up @chapter The C++ API @@ -999,9 +1196,10 @@ The @code{write()} method writes the configuration to the given @var{stream}. @deftypemethod Config void readFile (@w{const char * @var{filename}}) @deftypemethodx Config void writeFile (@w{const char * @var{filename}}) -The @code{readFile()} method reads and parses a configuration from the file -named @var{filename}. A @code{ParseException} is thrown if a parse error occurs. A -@code{FileIOException} is thrown if the file cannot be read. +The @code{readFile()} method reads and parses a configuration from the +file named @var{filename}. A @code{ParseException} is thrown if a +parse error occurs. A @code{FileIOException} is thrown if the file +cannot be read. The @code{writeFile()} method writes the configuration to the file named @var{filename}. A @code{FileIOException} is thrown if the file cannot @@ -1009,14 +1207,43 @@ be written. @end deftypemethod +@deftypemethod Config void readString (@w{const char * @var{str}}) +@deftypemethodx Config void readString (@w{const std::string &@var{str}}) + +These methods read and parse a configuration from the string +@var{str}. A @code{ParseException} is thrown if a parse error occurs. + +@end deftypemethod + @deftypemethod ParseException {const char *} getError () +@deftypemethodx ParseException {const char *} getFile () @deftypemethodx ParseException int getLine () -If a call to @code{readFile()} or @code{read()} resulted in a -@code{ParseException}, these methods can be called on the exception -object to obtain the text and line number of the parse error. Storage -for the string returned by @code{getError()} is managed by the -library; the string must not be freed by the caller. +If a call to @code{readFile()}, @code{readString()}, or @code{read()} +resulted in a @code{ParseException}, these methods can be called on +the exception object to obtain the text, filename, and line number of +the parse error. Storage for the strings returned by @code{getError()} +and @code{getFile()} are managed by the library; the strings must not +be freed by the caller. + +@end deftypemethod + +@deftypemethod Config void setIncludeDir (@w{const char *@var{includeDir}}) +@deftypemethodx Config {const char *} getIncludeDir () + +@code{setIncludeDir()} specifies the include directory, +@var{includeDir}, relative to which the files specified in +@samp{@@include} directives will be located for the configuration. By +default, there is no include directory, and all include files are +expected to be relative to the current working directory. If +@var{includeDir} is @code{NULL}, the default behavior is reinstated. + +For example, if the include directory is set to @file{/usr/local/etc}, +the include directive @samp{@@include "configs/extra.cfg"} would include the +file @file{/usr/local/etc/configs/extra.cfg}. + +@code{getIncludeDir()} returns the current include directory for the +configuration, or @code{NULL} if none is set. @end deftypemethod @@ -1038,6 +1265,30 @@ is currently enabled for the configuration; otherwise it returns @end deftypemethod +@deftypemethod Config void setDefaultFormat (@w{Setting::Format @var{format}}) +@deftypemethodx Config Setting::Format getDefaultFormat () + +These methods set and get the default external format for settings in +the configuration. If a non-default format has not been set for a +setting with @code{Setting::setFormat()}, this configuration-wide +default format will be used instead when that setting is written to a +file or stream. + +@end deftypemethod + +@deftypemethod Config void setTabWidth (@w{unsigned short @var{width}}) +@deftypemethodx Config {unsigned short} getTabWidth () + +These methods set and get the tab width for the configuration. The tab +width affects the formatting of the configuration when it is written +to a file or stream: each level of nesting is indented by @var{width} +spaces, or by a single tab character if @var{width} is 0. The tab +width has no effect on parsing. + +Valid tab widths range from 0 to 15. The default tab width is 2. + +@end deftypemethod + @deftypemethod Config {Setting &} getRoot () This method returns the root setting for the configuration, which is a group. @@ -1070,15 +1321,9 @@ the configuration. They return @code{true} if the setting exists, and @deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{unsigned int &@var{value}}) @deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{unsigned int &@var{value}}) -@deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{long &@var{value}}) -@deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{long &@var{value}}) - @deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{long long &@var{value}}) @deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{long long &@var{value}}) -@deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{unsigned long &@var{value}}) -@deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{unsigned long &@var{value}}) - @deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{float &@var{value}}) @deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{float &@var{value}}) @@ -1111,7 +1356,7 @@ wrong type: @sp 1 @cartouche -@example +@smallexample int var1; double var2; const char *var3; @@ -1126,7 +1371,7 @@ else @{ // error handling here @} -@end example +@end smallexample @end cartouche This approach also takes advantage of the short-circuit evaluation rules @@ -1134,27 +1379,31 @@ of C++, e.g., if the first lookup fails (returning @code{false}), the remaining lookups are skipped entirely. @end deftypemethod -@page -@deftypemethod Setting {} {operator bool()} -@deftypemethodx Setting {} {operator int()} -@deftypemethodx Setting {} {operator unsigned int()} -@deftypemethodx Setting {} {operator long()} -@deftypemethodx Setting {} {operator unsigned long()} -@deftypemethodx Setting {} {operator long long()} -@deftypemethodx Setting {} {operator unsigned long long()} -@deftypemethodx Setting {} {operator float()} -@deftypemethodx Setting {} {operator double()} -@deftypemethodx Setting {} {operator const char *()} -@deftypemethodx Setting {} {operator std::string()} + +@deftypemethod Setting {} {operator bool ()} +@deftypemethodx Setting {} {operator int ()} +@deftypemethodx Setting {} {operator unsigned int ()} +@deftypemethodx Setting {} {operator long ()} +@deftypemethodx Setting {} {operator unsigned long ()} +@deftypemethodx Setting {} {operator long long ()} +@deftypemethodx Setting {} {operator unsigned long long ()} +@deftypemethodx Setting {} {operator float ()} +@deftypemethodx Setting {} {operator double ()} +@deftypemethodx Setting {} {operator const char * ()} +@deftypemethodx Setting {} {operator std::string ()} +@deftypemethodx Setting {const char *} c_str () These cast operators allow a @code{Setting} object to be assigned to a variable of type @i{bool} if it is of type @code{TypeBoolean}; -@i{int}, @i{unsigned int}, @i{long}, or @i{unsigned long} if it is of -type @code{TypeInt}; @code{long long} or @code{unsigned long long} if +@i{int}, @i{unsigned int}; @code{long long} or @code{unsigned long long} if it is of type @code{TypeInt64}, @i{float} or @i{double} if it is of type @code{TypeFloat}; or @w{@i{const char *}} or @i{std::string} if it is of type @code{TypeString}. +Values of type @code{TypeInt} or @code{TypeInt64} may be assigned to +variables of type @i{long}, or @i{unsigned long}, depending on the +sizes of those types on the host system. + Storage for @w{@i{const char *}} return values is managed by the library and released automatically when the setting is destroyed or when its value is changed; the string must not be freed by the @@ -1164,13 +1413,13 @@ values to a @code{std::string} is suggested. The following examples demonstrate this usage: @cartouche -@example +@smallexample long width = config.lookup("application.window.size.w"); bool splashScreen = config.lookup("application.splash_screen"); std::string title = config.lookup("application.window.title"); -@end example +@end smallexample @end cartouche Note that certain conversions can lead to loss of precision or @@ -1183,13 +1432,13 @@ Perhaps surprisingly, the following code in particular will cause a compiler error: @cartouche -@example +@smallexample std::string title; . . . title = config.lookup("application.window.title"); -@end example +@end smallexample @end cartouche This is because the assignment operator of @code{std::string} is being @@ -1208,13 +1457,25 @@ avoids the construction of an intermediate @code{std::string} object, as follows: @cartouche -@example +@smallexample std::string title; . . . title = (const char *)config.lookup("application.window.title"); -@end example +@end smallexample +@end cartouche + +Or, alternatively, use the @code{c_str()} method, which has the same effect: + +@cartouche +@smallexample +std::string title; +. +. +. +title = config.lookup("application.window.title").c_str(); +@end smallexample @end cartouche If the assignment is invalid due to a type mismatch, a @@ -1238,30 +1499,40 @@ the library makes a copy of the passed string @var{value}, so it may be subsequently freed or modified by the caller without affecting the value of the setting. +The following example code looks up a (presumably) integer setting +and changes its value: + +@cartouche +@smallexample +Setting &setting = config.lookup("application.window.size.w"); +setting = 1024; +@end smallexample +@end cartouche + If the assignment is invalid due to a type mismatch, a @code{SettingTypeException} is thrown. @end deftypemethod -@deftypemethod Setting {Setting &} {operator[]} (@w{int @var{idx}}) +@deftypemethod Setting {Setting &} {operator[]} (@w{int @var{index}}) @deftypemethodx Setting {Setting &} {operator[]} (@w{const std::string &@var{name}}) @deftypemethodx Setting {Setting &} {operator[]} (@w{const char *@var{name}}) A @code{Setting} object may be subscripted with an integer index -@var{idx} if it is an array or list, or with either a string -@var{name} or an integer index @var{idx} if it is a group. For example, +@var{index} if it is an array or list, or with either a string +@var{name} or an integer index @var{index} if it is a group. For example, the following code would produce the string @samp{Last Name} when applied to the example configuration in @ref{Configuration Files}. @cartouche -@example +@smallexample Setting& setting = config.lookup("application.misc"); const char *s = setting["columns"][0]; -@end example +@end smallexample @end cartouche If the setting is not an array, list, or group, a -@code{SettingTypeException} is thrown. If the subscript (@var{idx} +@code{SettingTypeException} is thrown. If the subscript (@var{index} or @var{name}) does not refer to a valid element, a @code{SettingNotFoundException} is thrown. @@ -1286,12 +1557,6 @@ configuration. @deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{unsigned long long &@var{value}}) @deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{unsigned long long &@var{value}}) -@deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{long &@var{value}}) -@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{long &@var{value}}) - -@deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{unsigned long &@var{value}}) -@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{unsigned long &@var{value}}) - @deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{float &@var{value}}) @deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{float &@var{value}}) @@ -1324,7 +1589,7 @@ wrong type: @sp 1 @cartouche -@example +@smallexample int var1; double var2; const char *var3; @@ -1339,7 +1604,7 @@ else @{ // error handling here @} -@end example +@end smallexample @end cartouche This approach also takes advantage of the short-circuit evaluation @@ -1374,7 +1639,7 @@ must match the type of the existing elements in the array. The method returns the new setting on success. If @var{type} is a scalar type, the new setting will have a default value of 0, 0.0, -@code{false}, or @code{NULL}, depending on the type. +@code{false}, or @code{NULL}, as appropriate. The method throws a @code{SettingTypeException} if the setting is not an array or list, or if @var{type} is invalid. @@ -1394,14 +1659,14 @@ name, a @code{SettingNotFoundException} is thrown. @end deftypemethod -@deftypemethod Setting void remove (@w{unsigned int @var{idx}}) +@deftypemethod Setting void remove (@w{unsigned int @var{index}}) -This method removes the child setting at the given index @var{idx} from +This method removes the child setting at the given index @var{index} from the setting, which must be a group, list, or array. Any child settings of the removed setting are recursively destroyed as well. If the setting is not a group, list, or array, a -@code{SettingTypeException} is thrown. If @var{idx} is out of range, +@code{SettingTypeException} is thrown. If @var{index} is out of range, a @code{SettingNotFoundException} is thrown. @end deftypemethod @@ -1507,32 +1772,75 @@ integer, or floating point), respectively. @end deftypemethod +@deftypemethod Setting {const char *} getSourceFile () + +This function returns the name of the file from which the setting was +read, or NULL if the setting was not read from a file. This +information is useful for reporting application-level errors. Storage +for the returned string is managed by the library and released +automatically when the configuration is destroyed; the string must +not be freed by the caller. + +@end deftypemethod + @deftypemethod Setting {unsigned int} getSourceLine () -This method returns the line number of the configuration file or -stream at which the setting was parsed. This information is useful for -reporting application-level errors. If the setting was not read from a -file or stream, or if the line number is otherwise unavailable, the -method returns 0. +This function returns the line number of the configuration file or +stream at which the setting @var{setting} was read, or 0 if no line +number is available. This information is useful for reporting +application-level errors. @end deftypemethod -@node Configuration File Grammar, License, The C++ API, Top +@node Example Programs, Configuration File Grammar, The C++ API, Top +@comment node-name, next, previous, up +@chapter Example Programs + +Practical example programs that illustrate how to use @i{libconfig} +from both C and C++ are included in the @file{examples} subdirectory +of the distribution. These examples include: + +@table @file + +@item examples/c/example1.c +An example C program that reads a configuration from an existing file +@file{example.cfg} (also located in @file{examples/c}) and displays +some of its contents. + +@item examples/c++/example1.cpp +The C++ equivalent of @file{example1.c}. + +@item examples/c/example2.c +An example C program that reads a configuration from an existing file +@file{example.cfg} (also located in @file{examples/c}), adds new +settings to the configuration, and writes the updated configuration to +another file. + +@item examples/c++/example2.cpp +The C++ equivalent of @file{example2.c} + +@item examples/c/example3.c +An example C program that constructs a new configuration in memory and writes it to a file. + +@item examples/c++/example3.cpp +The C++ equivalent of @file{example3.c} + +@end table + +@node Configuration File Grammar, License, Example Programs, Top @comment node-name, next, previous, up @chapter Configuration File Grammar -Below is the BNF grammar for configuration files. Comments are not part -of the grammar, and hence are not included here. +Below is the BNF grammar for configuration files. Comments and include +directives are not part of the grammar, so they are not included here. @sp 1 @example configuration = setting-list | empty -empty = - setting-list = setting | setting-list setting -setting = name (":" | "=") value ";" +setting = name (":" | "=") value (";" | "," | empty) value = scalar-value | array | list | group @@ -1548,6 +1856,8 @@ array = "[" (scalar-value-list | empty) "]" list = "(" (value-list | empty) ")" group = "@{" (setting-list | empty) "@}" + +empty = @end example @sp 2 |