diff options
Diffstat (limited to '3rdparty/libconfig/extra/doc')
| -rw-r--r-- | 3rdparty/libconfig/extra/doc/LGPL.texi | 590 | ||||
| -rw-r--r-- | 3rdparty/libconfig/extra/doc/Makefile | 18 | ||||
| -rw-r--r-- | 3rdparty/libconfig/extra/doc/Makefile.in | 18 | ||||
| -rw-r--r-- | 3rdparty/libconfig/extra/doc/libconfig.texi | 1910 |
4 files changed, 2536 insertions, 0 deletions
diff --git a/3rdparty/libconfig/extra/doc/LGPL.texi b/3rdparty/libconfig/extra/doc/LGPL.texi new file mode 100644 index 000000000..e371ac0d0 --- /dev/null +++ b/3rdparty/libconfig/extra/doc/LGPL.texi @@ -0,0 +1,590 @@ +@c \input texinfo.tex @c -*-texinfo-*- +@c +@c %**start of header + +@c All text is ignored before the setfilename. +@setfilename LGPL.info + +@center GNU LESSER GENERAL PUBLIC LICENSE +@center Version 2.1, February 1999 + +@sp 1 + +Copyright @copyright{} 1991, 1999 Free Software Foundation, Inc., +59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + +[This is the first released version of the Lesser GPL. It also counts +as the successor of the GNU Library Public License, version 2, hence the +version number 2.1.] + +@sp 1 +@center Preamble +@sp 1 + +The licenses for most software are designed to take away your freedom to +share and change it. By contrast, the GNU General Public Licenses are +intended to guarantee your freedom to share and change free software--to +make sure the software is free for all its users. + +This license, the Lesser General Public License, applies to some +specially designated software packages--typically libraries--of the Free +Software Foundation and other authors who decide to use it. You can use +it too, but we suggest you first think carefully about whether this +license or the ordinary General Public License is the better strategy to +use in any particular case, based on the explanations below. + +When we speak of free software, we are referring to freedom of use, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish); that you receive source code or can get it if +you want it; that you can change the software and use pieces of it in +new free programs; and that you are informed that you can do these +things. + +To protect your rights, we need to make restrictions that forbid +distributors to deny you these rights or to ask you to surrender these +rights. These restrictions translate to certain responsibilities for +you if you distribute copies of the library or if you modify it. + +For example, if you distribute copies of the library, whether gratis or +for a fee, you must give the recipients all the rights that we gave you. +You must make sure that they, too, receive or can get the source code. +If you link other code with the library, you must provide complete +object files to the recipients, so that they can relink them with the +library after making changes to the library and recompiling it. And you +must show them these terms so they know their rights. + +We protect your rights with a two-step method: (1) we copyright the +library, and (2) we offer you this license, which gives you legal +permission to copy, distribute and/or modify the library. + +To protect each distributor, we want to make it very clear that there is +no warranty for the free library. Also, if the library is modified by +someone else and passed on, the recipients should know that what they +have is not the original version, so that the original author's +reputation will not be affected by problems that might be introduced by +others. + +Finally, software patents pose a constant threat to the existence of any +free program. We wish to make sure that a company cannot effectively +restrict the users of a free program by obtaining a restrictive license +from a patent holder. Therefore, we insist that any patent license +obtained for a version of the library must be consistent with the full +freedom of use specified in this license. + +Most GNU software, including some libraries, is covered by the ordinary +GNU General Public License. This license, the GNU Lesser General Public +License, applies to certain designated libraries, and is quite different +from the ordinary General Public License. We use this license for +certain libraries in order to permit linking those libraries into +non-free programs. + +When a program is linked with a library, whether statically or using a +shared library, the combination of the two is legally speaking a +combined work, a derivative of the original library. The ordinary +General Public License therefore permits such linking only if the entire +combination fits its criteria of freedom. The Lesser General Public +License permits more lax criteria for linking other code with the +library. + +We call this license the ``Lesser'' General Public License because it does +Less to protect the user's freedom than the ordinary General Public +License. It also provides other free software developers Less of an +advantage over competing non-free programs. These disadvantages are the +reason we use the ordinary General Public License for many libraries. +However, the Lesser license provides advantages in certain special +circumstances. + +For example, on rare occasions, there may be a special need to encourage +the widest possible use of a certain library, so that it becomes a +de-facto standard. To achieve this, non-free programs must be allowed +to use the library. A more frequent case is that a free library does +the same job as widely used non-free libraries. In this case, there is +little to gain by limiting the free library to free software only, so we +use the Lesser General Public License. + +In other cases, permission to use a particular library in non-free +programs enables a greater number of people to use a large body of free +software. For example, permission to use the GNU C Library in non-free +programs enables many more people to use the whole GNU operating system, +as well as its variant, the GNU/Linux operating system. + +Although the Lesser General Public License is Less protective of the +users' freedom, it does ensure that the user of a program that is linked +with the Library has the freedom and the wherewithal to run that program +using a modified version of the Library. + +The precise terms and conditions for copying, distribution and +modification follow. Pay close attention to the difference between a +``work based on the library'' and a ``work that uses the library''. The +former contains code derived from the library, whereas the latter must +be combined with the library in order to run. + +@page + +@center GNU LESSER GENERAL PUBLIC LICENSE +@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + +@enumerate 0 + +@sp 1 +@item +This License Agreement applies to any software library or other program +which contains a notice placed by the copyright holder or other +authorized party saying it may be distributed under the terms of this +Lesser General Public License (also called ``this License''). Each +licensee is addressed as ``you''. + +A ``library'' means a collection of software functions and/or data +prepared so as to be conveniently linked with application programs +(which use some of those functions and data) to form executables. + +The ``Library'', below, refers to any such software library or work which +has been distributed under these terms. A ``work based on the Library'' +means either the Library or any derivative work under copyright law: +that is to say, a work containing the Library or a portion of it, either +verbatim or with modifications and/or translated straightforwardly into +another language. (Hereinafter, translation is included without +limitation in the term ``modification''.) + +``Source code'' for a work means the preferred form of the work for making +modifications to it. For a library, complete source code means all the +source code for all modules it contains, plus any associated interface +definition files, plus the scripts used to control compilation and +installation of the library. + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of running +a program using the Library is not restricted, and output from such a +program is covered only if its contents constitute a work based on the +Library (independent of the use of the Library in a tool for writing +it). Whether that is true depends on what the Library does and what the +program that uses the Library does. + +@sp 1 +@item +You may copy and distribute verbatim copies of the Library's complete +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the notices +that refer to this License and to the absence of any warranty; and +distribute a copy of this License along with the Library. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + +@sp 1 +@item +You may modify your copy or copies of the Library or any portion of it, +thus forming a work based on the Library, and copy and distribute such +modifications or work under the terms of Section 1 above, provided that +you also meet all of these conditions: + +@enumerate a + +@item +The modified work must itself be a software library. + +@sp 1 +@item +You must cause the files modified to carry prominent notices stating +that you changed the files and the date of any change. + +@sp 1 +@item +You must cause the whole of the work to be licensed at no charge to all +third parties under the terms of this License. + +@sp 1 +@item +If a facility in the modified Library refers to a function or a table of +data to be supplied by an application program that uses the facility, +other than as an argument passed when the facility is invoked, then you +must make a good faith effort to ensure that, in the event an +application does not supply such function or table, the facility still +operates, and performs whatever part of its purpose remains meaningful. + +(For example, a function in a library to compute square roots has a +purpose that is entirely well-defined independent of the application. +Therefore, Subsection 2d requires that any application-supplied function +or table used by this function must be optional: if the application does +not supply it, the square root function must still compute square +roots.) + +@end enumerate + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Library, and +can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based on +the Library, the distribution of the whole must be on the terms of this +License, whose permissions for other licensees extend to the entire +whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Library. + +In addition, mere aggregation of another work not based on the Library +with the Library (or with a work based on the Library) on a volume of a +storage or distribution medium does not bring the other work under the +scope of this License. + +@sp 1 +@item +You may opt to apply the terms of the ordinary GNU General Public +License instead of this License to a given copy of the Library. To do +this, you must alter all the notices that refer to this License, so that +they refer to the ordinary GNU General Public License, version 2, +instead of to this License. (If a newer version than version 2 of the +ordinary GNU General Public License has appeared, then you can specify +that version instead if you wish.) Do not make any other change in +these notices. + +Once this change is made in a given copy, it is irreversible for that +copy, so the ordinary GNU General Public License applies to all +subsequent copies and derivative works made from that copy. + +This option is useful when you wish to copy part of the code of the +Library into a program that is not a library. + +@sp 1 +@item +You may copy and distribute the Library (or a portion or derivative of +it, under Section 2) in object code or executable form under the terms +of Sections 1 and 2 above provided that you accompany it with the +complete corresponding machine-readable source code, which must be +distributed under the terms of Sections 1 and 2 above on a medium +customarily used for software interchange. + +If distribution of object code is made by offering access to copy from a +designated place, then offering equivalent access to copy the source +code from the same place satisfies the requirement to distribute the +source code, even though third parties are not compelled to copy the +source along with the object code. + +@sp 1 +@item +A program that contains no derivative of any portion of the Library, but +is designed to work with the Library by being compiled or linked with +it, is called a ``work that uses the Library''. Such a work, in +isolation, is not a derivative work of the Library, and therefore falls +outside the scope of this License. + +However, linking a ``work that uses the Library'' with the Library creates +an executable that is a derivative of the Library (because it contains +portions of the Library), rather than a ``work that uses the library''. +The executable is therefore covered by this License. Section 6 states +terms for distribution of such executables. + +When a ``work that uses the Library'' uses material from a header file +that is part of the Library, the object code for the work may be a +derivative work of the Library even though the source code is not. +Whether this is true is especially significant if the work can be linked +without the Library, or if the work is itself a library. The threshold +for this to be true is not precisely defined by law. + +If such an object file uses only numerical parameters, data structure +layouts and accessors, and small macros and small inline functions (ten +lines or less in length), then the use of the object file is +unrestricted, regardless of whether it is legally a derivative work. +(Executables containing this object code plus portions of the Library +will still fall under Section 6.) + +Otherwise, if the work is a derivative of the Library, you may +distribute the object code for the work under the terms of Section 6. +Any executables containing that work also fall under Section 6, whether +or not they are linked directly with the Library itself. + +@sp 1 +@item +As an exception to the Sections above, you may also combine or link a +``work that uses the Library'' with the Library to produce a work +containing portions of the Library, and distribute that work under terms +of your choice, provided that the terms permit modification of the work +for the customer's own use and reverse engineering for debugging such +modifications. + +You must give prominent notice with each copy of the work that the +Library is used in it and that the Library and its use are covered by +this License. You must supply a copy of this License. If the work +during execution displays copyright notices, you must include the +copyright notice for the Library among them, as well as a reference +directing the user to the copy of this License. Also, you must do one +of these things: + +@enumerate a + +@sp 1 +@item +Accompany the work with the complete corresponding machine-readable +source code for the Library including whatever changes were used in the +work (which must be distributed under Sections 1 and 2 above); and, if +the work is an executable linked with the Library, with the complete +machine-readable ``work that uses the Library'', as object code and/or +source code, so that the user can modify the Library and then relink to +produce a modified executable containing the modified Library. (It is +understood that the user who changes the contents of definitions files +in the Library will not necessarily be able to recompile the application +to use the modified definitions.) + +@sp 1 +@item +Use a suitable shared library mechanism for linking with the Library. A +suitable mechanism is one that (1) uses at run time a copy of the +library already present on the user's computer system, rather than +copying library functions into the executable, and (2) will operate +properly with a modified version of the library, if the user installs +one, as long as the modified version is interface-compatible with the +version that the work was made with. + +@sp 1 +@item +Accompany the work with a written offer, valid for at least three years, +to give the same user the materials specified in Subsection 6a, above, +for a charge no more than the cost of performing this distribution. + +@sp 1 +@item +If distribution of the work is made by offering access to copy from a +designated place, offer equivalent access to copy the above specified +materials from the same place. + +@sp 1 +@item +Verify that the user has already received a copy of these materials or +that you have already sent this user a copy. + +@end enumerate + +For an executable, the required form of the ``work that uses the Library'' +must include any data and utility programs needed for reproducing the +executable from it. However, as a special exception, the materials to +be distributed need not include anything that is normally distributed +(in either source or binary form) with the major components (compiler, +kernel, and so on) of the operating system on which the executable runs, +unless that component itself accompanies the executable. + +It may happen that this requirement contradicts the license restrictions +of other proprietary libraries that do not normally accompany the +operating system. Such a contradiction means you cannot use both them +and the Library together in an executable that you distribute. + +@sp 1 +@item +You may place library facilities that are a work based on the Library +side-by-side in a single library together with other library facilities +not covered by this License, and distribute such a combined library, +provided that the separate distribution of the work based on the Library +and of the other library facilities is otherwise permitted, and provided +that you do these two things: + +@enumerate a + +@sp 1 +@item +Accompany the combined library with a copy of the same work based on the +Library, uncombined with any other library facilities. This must be +distributed under the terms of the Sections above. + +@sp 1 +@item +Give prominent notice with the combined library of the fact that part of +it is a work based on the Library, and explaining where to find the +accompanying uncombined form of the same work. + +@end enumerate + +@sp 1 +@item +You may not copy, modify, sublicense, link with, or distribute the +Library except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense, link with, or distribute the +Library is void, and will automatically terminate your rights under this +License. However, parties who have received copies, or rights, from you +under this License will not have their licenses terminated so long as +such parties remain in full compliance. + +@sp 1 +@item +You are not required to accept this License, since you have not signed +it. However, nothing else grants you permission to modify or distribute +the Library or its derivative works. These actions are prohibited by +law if you do not accept this License. Therefore, by modifying or +distributing the Library (or any work based on the Library), you +indicate your acceptance of this License to do so, and all its terms and +conditions for copying, distributing or modifying the Library or works +based on it. + +@sp 1 +@item +Each time you redistribute the Library (or any work based on the +Library), the recipient automatically receives a license from the +original licensor to copy, distribute, link with or modify the Library +subject to these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties with +this License. + +@sp 1 +@item +If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Library at all. For example, if a patent license +would not permit royalty-free redistribution of the Library by all those +who receive copies directly or indirectly through you, then the only way +you could satisfy both it and this License would be to refrain entirely +from distribution of the Library. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply, and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system which is implemented +by public license practices. Many people have made generous +contributions to the wide range of software distributed through that +system in reliance on consistent application of that system; it is up to +the author/donor to decide if he or she is willing to distribute +software through any other system and a licensee cannot impose that +choice. + +This section is intended to make thoroughly clear what is believed to be +a consequence of the rest of this License. + +@sp 1 +@item +If the distribution and/or use of the Library is restricted in certain +countries either by patents or by copyrighted interfaces, the original +copyright holder who places the Library under this License may add an +explicit geographical distribution limitation excluding those countries, +so that distribution is permitted only in or among countries not thus +excluded. In such case, this License incorporates the limitation as if +written in the body of this License. + +@sp 1 +@item +The Free Software Foundation may publish revised and/or new versions of +the Lesser General Public License from time to time. Such new versions +will be similar in spirit to the present version, but may differ in +detail to address new problems or concerns. + +Each version is given a distinguishing version number. If the Library +specifies a version number of this License which applies to it and ``any +later version'', you have the option of following the terms and +conditions either of that version or of any later version published by +the Free Software Foundation. If the Library does not specify a license +version number, you may choose any version ever published by the Free +Software Foundation. + +@sp 1 +@item +If you wish to incorporate parts of the Library into other free programs +whose distribution conditions are incompatible with these, write to the +author to ask for permission. For software which is copyrighted by the +Free Software Foundation, write to the Free Software Foundation; we +sometimes make exceptions for this. Our decision will be guided by the +two goals of preserving the free status of all derivatives of our free +software and of promoting the sharing and reuse of software generally. + +@sp 1 +@center NO WARRANTY +@sp 1 + +@item +BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR +THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE LIBRARY ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER +EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE +ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH +YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL +NECESSARY SERVICING, REPAIR OR CORRECTION. + +@sp 1 +@item +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR +DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL +DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY +(INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED +INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF +THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR +OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + +@end enumerate + +@sp 1 +@center END OF TERMS AND CONDITIONS +@sp 1 +@page +@center How to Apply These Terms to Your New Libraries + +If you develop a new library, and you want it to be of the greatest +possible use to the public, we recommend making it free software that +everyone can redistribute and change. You can do so by permitting +redistribution under these terms (or, alternatively, under the terms of +the ordinary General Public License). + +To apply these terms, attach the following notices to the library. It +is safest to attach them to the start of each source file to most +effectively convey the exclusion of warranty; and each file should have +at least the ``copyright'' line and a pointer to where the full notice is +found. + +@format +@t{ +<one line to give the library's name and a brief idea of what it does.> +Copyright (C) <year> <name of author> + +This library is free software; you can redistribute it and/or +modify it under the terms of the GNU Lesser General Public +License as published by the Free Software Foundation; either +version 2 of the License, or (at your option) any later version. + +This library is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details. + +You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +} +@end format + +Also add information on how to contact you by electronic and paper mail. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a ``copyright disclaimer'' for the library, if +necessary. Here is a sample; alter the names: + +@format +@t{ +Yoyodyne, Inc., hereby disclaims all copyright interest in the +library `Frob' (a library for tweaking knobs) written by James Random Hacker. + +<signature of Ty Coon>, 1 April 1990 +Ty Coon, President of Vice +} +@end format + +That's all there is to it! + +@c @bye diff --git a/3rdparty/libconfig/extra/doc/Makefile b/3rdparty/libconfig/extra/doc/Makefile new file mode 100644 index 000000000..fd84597a6 --- /dev/null +++ b/3rdparty/libconfig/extra/doc/Makefile @@ -0,0 +1,18 @@ +HTMLS = libconfig.html +TEXINFOS = libconfig.texi +MAKEINFOHTML = $(MAKEINFO) --html +MAKEINFO = makeinfo + +all: html + +.SUFFIXES: .html .texi + +libconfig.html: $(TEXINFOS) + +clean: + @-test -z "$(HTMLS)" || rm -rf libconfig.html + +.PHONY: all clean html + +html: $(HTMLS) + $(MAKEINFOHTML) --no-split $(TEXINFOS) diff --git a/3rdparty/libconfig/extra/doc/Makefile.in b/3rdparty/libconfig/extra/doc/Makefile.in new file mode 100644 index 000000000..fd84597a6 --- /dev/null +++ b/3rdparty/libconfig/extra/doc/Makefile.in @@ -0,0 +1,18 @@ +HTMLS = libconfig.html +TEXINFOS = libconfig.texi +MAKEINFOHTML = $(MAKEINFO) --html +MAKEINFO = makeinfo + +all: html + +.SUFFIXES: .html .texi + +libconfig.html: $(TEXINFOS) + +clean: + @-test -z "$(HTMLS)" || rm -rf libconfig.html + +.PHONY: all clean html + +html: $(HTMLS) + $(MAKEINFOHTML) --no-split $(TEXINFOS) diff --git a/3rdparty/libconfig/extra/doc/libconfig.texi b/3rdparty/libconfig/extra/doc/libconfig.texi new file mode 100644 index 000000000..52dca20fc --- /dev/null +++ b/3rdparty/libconfig/extra/doc/libconfig.texi @@ -0,0 +1,1910 @@ +\input texinfo.tex @c -*-texinfo-*- +@c +@c %**start of header + +@c All text is ignored before the setfilename. +@setfilename libconfig.info +@settitle libconfig + +@set edition 1.4.9 +@set update-date 28 September 2012 +@set subtitle-text A Library For Processing Structured Configuration Files +@set author-text Mark A.@: Lindner + +@comment %**end of header + +@dircategory Software libraries +@direntry +* libconfig: (libconfig). A Library For Processing Structured Configuration Files +@end direntry + + +@tex +\global\emergencystretch = .3\hsize +@end tex + +@setchapternewpage odd + +@titlepage + +@title libconfig +@subtitle @value{subtitle-text} +@subtitle Version @value{edition} +@subtitle @value{update-date} + +@author @value{author-text} + +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 2005-2012 Mark A Lindner + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +@end titlepage + +@c Give the HTML output a title page that somewhat resembles the printed one +@ifhtml +@html +<hr noshade size=6 color="black"> +<div align=right>@value{subtitle-text}<br> +Version @value{edition}<br> +@value{update-date}</div> +<br><br><br><br> +<font size=+1>@value{author-text}</font> +<hr size=3 noshade color="black"> +<br><br> +@end html +@end ifhtml + +@contents + +@ifnottex +@node Top +@comment node-name, next, previous, up +@top libconfig +@end ifnottex + +@menu +* Introduction:: +* Configuration Files:: +* The C API:: +* The C++ API:: +* Example Programs:: +* Configuration File Grammar:: +* License:: +* Function Index:: +* Type Index:: +* Concept Index:: +@end menu + +@node Introduction, Configuration Files, Top, Top +@comment node-name, next, previous, up +@menu +* Why Another Configuration File Library?:: +* Using the Library from a C Program:: +* Using the Library from a C++ Program:: +* Multithreading Issues:: +* Internationalization Issues:: +* Compiling Using pkg-config:: +* Version Test Macros:: +@end menu +@chapter Introduction + +@i{Libconfig} is a library for reading, manipulating, and writing +structured configuration files. The library features a fully +reentrant parser and includes bindings for both the C and C++ +programming languages. + +The library runs on modern POSIX-compilant systems, such as Linux, +Solaris, and Mac OS X (Darwin), as well as on Microsoft Windows +2000/XP and later (with either Microsoft Visual Studio 2005 or later, +or the GNU toolchain via the MinGW environment). + +@node Why Another Configuration File Library?, Using the Library from a C Program, , Introduction +@comment node-name, next, previous, up +@section Why Another Configuration File Library? + +There are several open-source configuration file libraries available +as of this writing. This library was written because each of those +libraries falls short in one or more ways. The main features of +@i{libconfig} that set it apart from the other libraries are: + +@itemize @bullet + +@item A fully reentrant parser. Independent configurations can be parsed in concurrent threads at the same time. + +@item Both C @i{and} C++ bindings, as well as hooks to allow for the creation of wrappers in other languages. + +@item A simple, structured configuration file format that is more +readable and compact than XML and more flexible than the obsolete but +prevalent Windows ``INI'' file format. + +@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. + +@end itemize + +@node Using the Library from a C Program, Using the Library from a C++ Program, Why Another Configuration File Library?, Introduction +@comment node-name, next, previous, up +@section Using the Library from a C Program + +To use the library from C code, include the following preprocessor +directive in your source files: + +@sp 1 +@smallexample +#include <libconfig.h> +@end smallexample +@sp 1 + +To link with the library, specify @samp{-lconfig} as an argument to the +linker. + +@node Using the Library from a C++ Program, Multithreading Issues, Using the Library from a C Program, Introduction +@comment node-name, next, previous, up +@section Using the Library from a C++ Program + +To use the library from C++, include the following preprocessor +directive in your source files: + +@sp 1 +@smallexample +#include <libconfig.h++> +@end smallexample +@sp 1 + +Or, alternatively: + +@sp 1 +@smallexample +#include <libconfig.hh> +@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 +@smallexample +using namespace libconfig; +@end smallexample +@sp 1 + +To link with the library, specify @samp{-lconfig++} as an argument to +the linker. + +@node Multithreading Issues, Internationalization Issues, Using the Library from a C++ Program, Introduction +@comment node-name, next, previous, up +@section Multithreading Issues + +@i{Libconfig} is fully @dfn{reentrant}; the functions in the library +do not make use of global variables and do not maintain state between +successive calls. Therefore two independent configurations may be safely +manipulated concurrently by two distinct threads. + +@i{Libconfig} is not @dfn{thread-safe}. The library is not aware of +the presence of threads and knows nothing about the host system's +threading model. Therefore, if an instance of a configuration is to be +accessed from multiple threads, it must be suitably protected by +synchronization mechanisms like read-write locks or mutexes; the +standard rules for safe multithreaded access to shared data must be +observed. + +@i{Libconfig} is not @dfn{async-safe}. Calls should not be made into +the library from signal handlers, because some of the C library +routines that it uses may not be async-safe. + +@i{Libconfig} is not guaranteed to be @dfn{cancel-safe}. Since it is +not aware of the host system's threading model, the library does not +contain any thread cancellation points. In most cases this will not be +an issue for multithreaded programs. However, be aware that some of +the routines in the library (namely those that read/write +configurations from/to files or streams) perform I/O using C library +routines which may potentially block; whether or not these C library +routines are cancel-safe depends on the host system. + +@node Internationalization Issues, Compiling Using pkg-config, Multithreading Issues, Introduction +@comment node-name, next, previous, up +@section Internationalization Issues + +@cindex Unicode +@cindex UTF-8 +@i{Libconfig} does not natively support Unicode configuration files, +but string values may contain Unicode text encoded in UTF-8; such +strings will be treated as ordinary 8-bit ASCII text by the +library. It is the responsibility of the calling program to perform +the necessary conversions to/from wide (@t{wchar_t}) strings using the +wide string conversion functions such as @t{mbsrtowcs()} and +@t{wcsrtombs()} or the @t{iconv()} function of the @i{libiconv} +library. + +@cindex locale +The textual representation of a floating point value varies by +locale. However, the @i{libconfig} grammar specifies that +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 +handling of floating point values regardless of the locale(s) in use +by the calling program. + +Note that the MinGW environment does not (as of this writing) provide +functions for changing the locale of the calling thread. Therefore, +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, 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 +@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: + +@smallexample +gcc `pkg-config --cflags libconfig` myprogram.c -o myprogram \ + `pkg-config --libs libconfig` +@end smallexample +@sp 1 + +And similarly, for C++ programs: + +@smallexample +g++ `pkg-config --cflags libconfig++` myprogram.cpp -o myprogram \ + `pkg-config --libs libconfig++` +@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 +* Settings:: +* Groups:: +* Arrays:: +* Lists:: +* Integer Values:: +* 64-bit Integer Values:: +* Floating Point Values:: +* Boolean Values:: +* String Values:: +* Comments:: +* Include Directives:: +@end menu +@chapter Configuration Files + +@i{Libconfig} supports structured, hierarchical configurations. These +configurations can be read from and written to files and manipulated +in memory. + +@cindex setting +@cindex value +@cindex scalar value +@cindex array +@cindex group +@cindex list +@cindex configuration +A @dfn{configuration} consists of a group of @dfn{settings}, which +associate names with values. A @dfn{value} can be one of the +following: + +@itemize @bullet +@item A @dfn{scalar value}: integer, 64-bit integer, floating-point number, boolean, +or string +@item An @dfn{array}, which is a sequence of scalar values, all of which must have the same type +@item A @dfn{group}, which is a collection of settings +@item A @dfn{list}, which is a sequence of values of any type, including other lists +@end itemize + +Consider the following configuration file for a hypothetical GUI +application, which illustrates all of the elements of the configuration +file grammar. + +@sp 1 +@cartouche +@smallexample +# Example application configuration file + +version = "1.0"; + +application: +@{ + window: + @{ + title = "My Application"; + size = @{ w = 640; h = 480; @}; + pos = @{ x = 350; y = 250; @}; + @}; + + list = ( ( "abc", 123, true ), 1.234, ( /* an empty list */) ); + + books = ( @{ title = "Treasure Island"; + author = "Robert Louis Stevenson"; + price = 29.95; + qty = 5; @}, + @{ title = "Snow Crash"; + author = "Neal Stephenson"; + price = 9.99; + qty = 8; @} ); + + misc: + @{ + pi = 3.141592654; + bigint = 9223372036854775807L; + columns = [ "Last Name", "First Name", "MI" ]; + bitmask = 0x1FC3; + @}; +@}; +@end smallexample +@end cartouche +@sp 1 + +@cindex path +Settings can be uniquely identified within the configuration by a +@dfn{path}. The path is a dot-separated sequence of names, beginning +at a top-level group and ending at the setting itself. Each name in +the path is the name of a setting; if the setting has no name because +it is an element in a list or array, an integer index in square +brackets can be used as the name. + +For example, in our hypothetical configuration file, the path to the +@code{x} setting is @code{application.window.pos.x}; the path to the +@code{version} setting is simply @code{version}; and the path to the +@code{title} setting of the second book in the @code{books} list is +@code{application.books.[1].title}. + +The datatype of a value is determined from the format of the value +itself. If the value is enclosed in double quotes, it is treated as a +string. If it looks like an integer or floating point number, it is +treated as such. If it is one of the values @code{TRUE}, @code{true}, +@code{FALSE}, or @code{false} (or any other mixed-case version of +those tokens, e.g., @code{True} or @code{FaLsE}), it is treated as a +boolean. If it consists of a comma-separated list of values enclosed +in square brackets, it is treated as an array. And if it consists of a +comma-separated list of values enclosed in parentheses, it is treated +as a list. Any value which does not meet any of these criteria is +considered invalid and results in a parse error. + +All names are case-sensitive. They may consist only of alphanumeric +characters, dashes (@samp{-}), underscores (@samp{_}), and asterisks +(@samp{*}), 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 @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++. + +The following sections describe the elements of the configuration file +grammar in additional detail. + +@node Settings, Groups, , Configuration Files +@comment node-name, next, previous, up +@section Settings + +A setting has the form: + +@i{name} @b{=} @i{value} @b{;} + +or: + +@i{name} @b{:} @i{value} @b{;} + +The trailing semicolon is optional. Whitespace is not significant. + +The value may be a scalar value, an array, a group, or a list. + +@node Groups, Arrays, Settings, Configuration Files +@comment node-name, next, previous, up +@section Groups + +A group has the form: + +@b{@{} + @i{settings ...} +@b{@}} + +Groups can contain any number of settings, but each setting must have +a unique name within the group. + +@node Arrays, Lists, Groups, Configuration Files +@comment node-name, next, previous, up +@section Arrays + +An array has the form: + +@b{[} @i{value}@b{,} @i{value ...} @b{]} + +An array may have zero or more elements, but the elements must all be +scalar values of the same type. + +@node Lists, Integer Values, Arrays, Configuration Files +@comment node-name, next, previous, up +@section Lists + +A list has the form: + +@b{(} @i{value}@b{,} @i{value ...} @b{)} + +A list may have zero or more elements, each of which can be a scalar +value, an array, a group, or another list. + +@node Integer Values, 64-bit Integer Values, Lists, Configuration Files +@comment node-name, next, previous, up +@section Integer Values + +Integers can be represented in one of two ways: as a series of one or +more decimal digits (@samp{0} - @samp{9}), with an optional leading +sign character (@samp{+} or @samp{-}); or as a hexadecimal value +consisting of the characters @samp{0x} followed by a series of one or +more hexadecimal digits (@samp{0} - @samp{9}, @samp{A} - @samp{F}, +@samp{a} - @samp{f}). + +@node 64-bit Integer Values, Floating Point Values, Integer Values, Configuration Files +@comment node-name, next, previous, up +@section 64-bit Integer Values + +Long long (64-bit) integers are represented identically to integers, +except that an 'L' character is appended to indicate a 64-bit +value. For example, @samp{0L} indicates a 64-bit integer value 0. + +@node Floating Point Values, Boolean Values, 64-bit Integer Values, Configuration Files +@comment node-name, next, previous, up +@section Floating Point Values + +Floating point values consist of a series of one or more digits, one +decimal point, an optional leading sign character (@samp{+} or +@samp{-}), and an optional exponent. An exponent consists of the +letter @samp{E} or @samp{e}, an optional sign character, and a series +of one or more digits. + +@node Boolean Values, String Values, Floating Point Values, Configuration Files +@comment node-name, next, previous, up +@section Boolean Values + +Boolean values may have one of the following values: @samp{true}, +@samp{false}, or any mixed-case variation thereof. + +@node String Values, Comments, Boolean Values, Configuration Files +@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. + +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 +shorter strings. For example, the following constructs are equivalent: + +@itemize @bullet +@item +@code{"The quick brown fox jumped over the lazy dog."} + +@item +@code{"The quick brown fox"} @* +@code{" jumped over the lazy dog."} + +@item +@code{"The quick" /* comment */ " brown fox " // another comment} @* +@code{"jumped over the lazy dog."} + +@end itemize +@page +@node Comments, Include Directives, String Values, Configuration Files +@comment node-name, next, previous, up +@section Comments + +@cindex comment +Three types of comments are allowed within a configuration: + +@itemize @bullet + +@item Script-style comments. All text beginning with a @samp{#} character +to the end of the line is ignored. + +@item C-style comments. All text, including line breaks, between a starting +@samp{/*} sequence and an ending @samp{*/} sequence is ignored. + +@item C++-style comments. All text beginning with a @samp{//} sequence to the +end of the line is ignored. + +@end itemize + +As expected, comment delimiters appearing within quoted strings are +treated as literal text. + +Comments are ignored when the configuration is read in, so they are +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 + +@tindex config_t +@tindex config_setting_t +This chapter describes the C library API. The type @i{config_t} +represents a configuration, and the type @i{config_setting_t} represents +a configuration setting. + +The boolean values @code{CONFIG_TRUE} and @code{CONFIG_FALSE} are +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}. + +@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 does not +attempt to deallocate the @i{config_t} structure itself. + +@end deftypefun + +@deftypefun int config_read (@w{config_t * @var{config}}, @w{FILE * @var{stream}}) + +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()}, @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 + +@deftypefun int config_read_file (@w{config_t * @var{config}}, @w{const char * @var{filename}}) + +This function reads and parses a configuration from the file named +@var{filename} 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 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 +@var{stream}. + +@end deftypefun + +@deftypefun int config_write_file (@w{config_t * @var{config}}, @w{const char * @var{filename}}) + +This function writes the configuration @var{config} to the file named +@var{filename}. It returns @code{CONFIG_TRUE} on success, or +@code{CONFIG_FALSE} on failure. + +@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, +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 + +@deftypefun void config_set_auto_convert (@w{config_t *@var{config}}, @w{int @var{flag}}) +@deftypefunx int config_get_auto_convert (@w{const config_t *@var{config}}) + +@code{config_set_auto_convert()} enables number auto-conversion for +the configuration @var{config} if @var{flag} is non-zero, and disables +it otherwise. When this feature is enabled, an attempt to retrieve a +floating point setting's value into an integer (or vice versa), or +store an integer to a floating point setting's value (or vice versa) +will cause the library to silently perform the necessary conversion +(possibly leading to loss of data), rather than reporting failure. By +default this feature is disabled. + +@code{config_get_auto_convert()} returns @code{CONFIG_TRUE} if number +auto-conversion is currently enabled for @var{config}; otherwise it +returns @code{CONFIG_FALSE}. + +@end deftypefun + +@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}}) +@deftypefunx int config_lookup_string (@w{const config_t * @var{config}}, @w{const char * @var{path}}, @w{const char ** @var{value}}) + +These functions look up the value of the setting in the configuration +@var{config} specified by the path @var{path}. They store the value of +the setting at @var{value} and return @code{CONFIG_TRUE} on +success. If the setting was not found or if the type of the value did +not match the type requested, they leave the data pointed to by +@var{value} unmodified and return @code{CONFIG_FALSE}. + +Storage for the string returned by @code{config_lookup_string()} is +managed by the library and released automatically when the setting is +destroyed or when the setting's value is changed; the string must not +be freed by the caller. + +@end deftypefun + +@deftypefun {config_setting_t *} config_lookup (@w{const config_t * @var{config}}, @w{const char * @var{path}}) + +This function locates the setting in the configuration @var{config} +specified by the path @var{path}. It returns a pointer to the +@code{config_setting_t} structure on success, or @code{NULL} if the +setting was not found. + +@end deftypefun + +@deftypefun int config_setting_get_int (@w{const config_setting_t * @var{setting}}) +@deftypefunx {long long} config_setting_get_int64 (@w{const config_setting_t * @var{setting}}) +@deftypefunx double config_setting_get_float (@w{const config_setting_t * @var{setting}}) +@deftypefunx int config_setting_get_bool (@w{const config_setting_t * @var{setting}}) +@deftypefunx {const char *} config_setting_get_string (@w{const config_setting_t * @var{setting}}) + +These functions return the value of the given @var{setting}. If the +type of the setting does not match the type requested, a 0 or +@code{NULL} value is returned. Storage for the string returned by +@code{config_setting_get_string()} is managed by the library and +released automatically when the setting is destroyed or when the +setting's value is changed; the string must not be freed by the +caller. + +@end deftypefun +@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}}) +@deftypefunx int config_setting_set_string (@w{config_setting_t * @var{setting}}, @w{const char * @var{value}}) + +These functions set the value of the given @var{setting} to +@var{value}. On success, they return @code{CONFIG_TRUE}. If +the setting does not match the type of the value, they return +@code{CONFIG_FALSE}. @code{config_setting_set_string()} 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. + +@end deftypefun + +@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}}) +@deftypefunx int config_setting_lookup_string (@w{const config_setting_t * @var{setting}}, @w{const char * @var{name}}, @w{const char ** @var{value}}) + +These functions look up the value of the child setting named +@var{name} of the setting @var{setting}. They store the value at +@var{value} and return @code{CONFIG_TRUE} on success. If the setting +was not found or if the type of the value did not match the type +requested, they leave the data pointed to by @var{value} unmodified +and return @code{CONFIG_FALSE}. + +Storage for the string returned by @code{config_setting_lookup_string()} is +managed by the library and released automatically when the setting is +destroyed or when the setting's value is changed; the string must not +be freed by the caller. + +@end deftypefun + +@deftypefun short config_setting_get_format (@w{config_setting_t * @var{setting}}) +@deftypefunx int config_setting_set_format (@w{config_setting_t * @var{setting}}, @w{short @var{format}}) + +These functions get and set the external format for the setting @var{setting}. + +@tindex SettingFormat +@cindex format + +The @var{format} must be one of the constants +@code{CONFIG_FORMAT_DEFAULT} or @code{CONFIG_FORMAT_HEX}. All settings +support the @code{CONFIG_FORMAT_DEFAULT} format. The +@code{CONFIG_FORMAT_HEX} format specifies hexadecimal formatting for +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. + +@end deftypefun + + +@deftypefun {config_setting_t *} config_setting_get_member (@w{config_setting_t * @var{setting}}, @w{const char * @var{name}}) + +This function fetches the child setting named @var{name} from the group +@var{setting}. It returns the requested setting on success, or +@code{NULL} if the setting was not found or if @var{setting} is not a +group. + +@end deftypefun + +@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{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{index} is out of +range or if @var{setting} is not an array, list, or group. + +@end deftypefun + +@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{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{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{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{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{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. +@end deftypefun + +@deftypefun {config_setting_t *} config_setting_add (@w{config_setting_t * @var{parent}}, @w{const char * @var{name}}, @w{int @var{type}}) + +This function adds a new child setting or element to the setting +@var{parent}, which must be a group, array, or list. If @var{parent} +is an array or list, the @var{name} parameter is ignored and may be +@code{NULL}. + +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. 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}}) + +This function removes and destroys the setting named @var{name} from +the parent setting @var{parent}, which must be a group. Any child +settings of the setting are recursively destroyed as well. + +The function returns @code{CONFIG_TRUE} on success. If @var{parent} is +not a group, or if it has no setting with the given name, it returns +@code{CONFIG_FALSE}. + +@end deftypefun + +@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{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{index} is out of range, it returns +@code{CONFIG_FALSE}. + +@end deftypefun + +@deftypefun {config_setting_t *} config_root_setting (@w{const config_t * @var{config}}) + +This function returns the root setting for the configuration +@var{config}. The root setting is a group. + +@end deftypefun + +@deftypefun {const char *} config_setting_name (@w{const config_setting_t * @var{setting}}) + +This function returns the name of the given @var{setting}, or +@code{NULL} if the setting has no name. Storage for the returned +string is managed by the library and released automatically when the +setting is destroyed; the string must not be freed by the caller. + +@end deftypefun + +@deftypefun {config_setting_t *} config_setting_parent (@w{const config_setting_t * @var{setting}}) + +This function returns the parent setting of the given @var{setting}, +or @code{NULL} if @var{setting} is the root setting. + +@end deftypefun + +@deftypefun int config_setting_is_root (@w{const config_setting_t * @var{setting}}) + +This function returns @code{CONFIG_TRUE} if the given @var{setting} is +the root setting, and @code{CONFIG_FALSE} otherwise. + +@end deftypefun + +@deftypefun int config_setting_index (@w{const config_setting_t * @var{setting}}) + +This function returns the index of the given @var{setting} within its +parent setting. If @var{setting} is the root setting, this function +returns -1. + +@end deftypefun + +@deftypefun int config_setting_length (@w{const config_setting_t * @var{setting}}) + +This function returns the number of settings in a group, or the number of +elements in a list or array. For other types of settings, it returns +0. + +@end deftypefun + +@deftypefun int config_setting_type (@w{const config_setting_t * @var{setting}}) + +This function returns the type of the given @var{setting}. The return +value is one of the constants +@code{CONFIG_TYPE_INT}, @code{CONFIG_TYPE_INT64}, @code{CONFIG_TYPE_FLOAT}, +@code{CONFIG_TYPE_STRING}, @code{CONFIG_TYPE_BOOL}, +@code{CONFIG_TYPE_ARRAY}, @code{CONFIG_TYPE_LIST}, or @code{CONFIG_TYPE_GROUP}. + +@end deftypefun + +@deftypefun int config_setting_is_group (@w{const config_setting_t * @var{setting}}) +@deftypefunx int config_setting_is_array (@w{const config_setting_t * @var{setting}}) +@deftypefunx int config_setting_is_list (@w{const config_setting_t * @var{setting}}) + +These convenience functions, which are implemented as macros, test if +the setting @var{setting} is of a given type. They return +@code{CONFIG_TRUE} or @code{CONFIG_FALSE}. + +@end deftypefun + +@deftypefun int config_setting_is_aggregate (@w{const config_setting_t * @var{setting}}) +@deftypefunx int config_setting_is_scalar (@w{const config_setting_t * @var{setting}}) +@deftypefunx int config_setting_is_number (@w{const config_setting_t * @var{setting}}) + +@cindex aggregate value +These convenience functions, which are implemented as macros, test if +the setting @var{setting} is of an aggregate type (a group, array, or +list), of a scalar type (integer, 64-bit integer, floating point, +boolean, or string), and of a number (integer, 64-bit integer, or +floating point), respectively. They return @code{CONFIG_TRUE} or +@code{CONFIG_FALSE}. + +@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 read, or 0 if no line +number is available. This information is useful for reporting +application-level errors. + +@end deftypefun + +@deftypefun void config_setting_set_hook (@w{config_setting_t * @var{setting}}, @w{void * @var{hook}}) +@deftypefunx {void *} config_setting_get_hook (@w{const config_setting_t * @var{setting}}) + +These functions make it possible to attach arbitrary data to each +setting structure, for instance a ``wrapper'' or ``peer'' object written in +another programming language. The destructor function, if one has been +supplied via a call to @code{config_set_destructor()}, will be called +by the library to dispose of this data when the setting itself is +destroyed. There is no default destructor. + +@end deftypefun + +@deftypefun void config_set_destructor (@w{config_t * @var{config}}, @w{void (* @var{destructor})(void *)}) + +This function assigns the destructor function @var{destructor} for the +configuration @var{config}. This function accepts a single @code{void +*} argument and has no return value. See +@code{config_setting_set_hook()} above for more information. + +@end deftypefun + +@node The C++ API, Example Programs, The C API, Top +@comment node-name, next, previous, up +@chapter The C++ API + +@tindex Config +@tindex Setting +This chapter describes the C++ library API. The class @code{Config} +represents a configuration, and the class @code{Setting} represents a +configuration setting. Note that by design, neither of these classes +provides a public copy constructor or assignment operator. Therefore, +instances of these classes may only be passed between functions via +references or pointers. + +@tindex ConfigException +The library defines a group of exceptions, all of which extend the +common base exception @code{ConfigException}. + +@tindex SettingTypeException +A @code{SettingTypeException} is thrown when the type of a setting's +value does not match the type requested. + +@tindex SettingNotFoundException +A @code{SettingNotFoundException} is thrown when a setting is not found. + +@tindex SettingNameException +A @code{SettingNameException} is thrown when an attempt is made to add +a new setting with a non-unique or invalid name. + +@tindex ParseException +A @code{ParseException} is thrown when a parse error occurs while +reading a configuration from a stream. + +@tindex FileIOException +A @code{FileIOException} is thrown when an I/O error occurs while +reading/writing a configuration from/to a file. + +@tindex SettingException +@code{SettingTypeException}, @code{SettingNotFoundException}, and +@code{SettingNameException} all extend the common base +exception @code{SettingException}, which provides the following method: + +@deftypemethod SettingException {const char *} getPath () + +Returns the path to the setting associated with the exception, or +@code{NULL} if there is no applicable path. + +@end deftypemethod + +The remainder of this chapter describes the methods for manipulating +configurations and configuration settings. + +@deftypemethod Config {} Config () +@deftypemethodx Config {} ~Config () + +These methods create and destroy @code{Config} objects. + +@end deftypemethod + +@deftypemethod Config void read (@w{FILE * @var{stream}}) +@deftypemethodx Config void write (@w{FILE * @var{stream}}) + +The @code{read()} method reads and parses a configuration from the given +@var{stream}. A @code{ParseException} is thrown if a parse error occurs. + +The @code{write()} method writes the configuration to the given @var{stream}. + +@end deftypemethod + +@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{writeFile()} method writes the configuration to the file +named @var{filename}. A @code{FileIOException} is thrown if the file cannot +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()}, @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 + +@deftypemethod Config void setAutoConvert (bool @var{flag}) +@deftypemethodx Config bool getAutoConvert () + +@code{setAutoConvert()} enables number auto-conversion for the +configuration if @var{flag} is @code{true}, and disables it +otherwise. When this feature is enabled, an attempt to assign a +floating point setting to an integer (or vice versa), or +assign an integer to a floating point setting (or vice versa) will +cause the library to silently perform the necessary conversion +(possibly leading to loss of data), rather than throwing a +@code{SettingTypeException}. By default this feature is disabled. + +@code{getAutoConvert()} returns @code{true} if number auto-conversion +is currently enabled for the configuration; otherwise it returns +@code{false}. + +@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. + +@end deftypemethod + +@deftypemethod Config {Setting &} lookup (@w{const std::string &@var{path}}) +@deftypemethodx Config {Setting &} lookup (@w{const char * @var{path}}) + +These methods locate the setting specified by the path @var{path}. If +the requested setting is not found, a @code{SettingNotFoundException} is +thrown. + +@end deftypemethod +@deftypemethod Config bool exists (@w{const std::string &@var{path}}) +@deftypemethodx Config bool exists (@w{const char *@var{path}}) + +These methods test if a setting with the given @var{path} exists in +the configuration. They return @code{true} if the setting exists, and +@code{false} otherwise. These methods do not throw exceptions. + +@end deftypemethod + +@deftypemethod Config bool lookupValue (@w{const char *@var{path}}, @w{bool &@var{value}}) +@deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{bool &@var{value}}) + +@deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{int &@var{value}}) +@deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{int &@var{value}}) + +@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 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{float &@var{value}}) +@deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{float &@var{value}}) + +@deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{double &@var{value}}) +@deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{double &@var{value}}) + +@deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{const char *&@var{value}}) +@deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{const char *&@var{value}}) + +@deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{std::string &@var{value}}) +@deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{std::string &@var{value}}) + +These are convenience methods for looking up the value of a setting +with the given @var{path}. If the setting is found and is of an +appropriate type, the value is stored in @var{value} and the method +returns @code{true}. Otherwise, @var{value} is left unmodified and the +method returns @code{false}. These methods do not throw exceptions. + +Storage for @w{@i{const char *}} 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 caller. For safety and +convenience, always assigning string values to a @code{std::string} is +suggested. + +Since these methods have boolean return values and do not throw +exceptions, they can be used within boolean logic expressions. The following +example presents a concise way to look up three values at once and +perform error handling if any of them are not found or are of the +wrong type: + +@sp 1 +@cartouche +@smallexample +int var1; +double var2; +const char *var3; + +if(config.lookupValue("values.var1", var1) + && config.lookupValue("values.var2", var2) + && config.lookupValue("values.var3", var3)) +@{ + // use var1, var2, var3 +@} +else +@{ + // error handling here +@} +@end smallexample +@end cartouche + +This approach also takes advantage of the short-circuit evaluation rules +of C++, e.g., if the first lookup fails (returning @code{false}), the +remaining lookups are skipped entirely. + +@end deftypemethod + +@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}; @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 +caller. For safety and convenience, always assigning string return +values to a @code{std::string} is suggested. + +The following examples demonstrate this usage: + +@cartouche +@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 smallexample +@end cartouche + +Note that certain conversions can lead to loss of precision or +clipping of values, e.g., assigning a negative value to an @i{unsigned +int} (in which case the value will be treated as 0), or a +double-precision value to a @i{float}. The library does not treat +these lossy conversions as errors. + +Perhaps surprisingly, the following code in particular will cause a +compiler error: + +@cartouche +@smallexample +std::string title; +. +. +. +title = config.lookup("application.window.title"); +@end smallexample +@end cartouche + +This is because the assignment operator of @code{std::string} is being +invoked with a @code{Setting &} as an argument. The compiler is unable +to make an implicit conversion because both the @code{const char *} +and the @code{std::string} cast operators of @code{Setting} are +equally appropriate. This is not a bug in @i{libconfig}; providing +only the @code{const char *} cast operator would resolve this +particular ambiguity, but would cause assignments to +@code{std::string} like the one in the previous example to produce a +compiler error. (To understand why, see section 11.4.1 of @i{The C++ +Programming Language}.) + +The solution to this problem is to use an explicit conversion that +avoids the construction of an intermediate @code{std::string} object, +as follows: + +@cartouche +@smallexample +std::string title; +. +. +. +title = (const char *)config.lookup("application.window.title"); +@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 +@code{SettingTypeException} is thrown. + +@end deftypemethod + +@deftypemethod Setting {Setting &} operator= (@w{bool @var{value}}) +@deftypemethodx Setting {Setting &} operator= (@w{int @var{value}}) +@deftypemethodx Setting {Setting &} operator= (@w{long @var{value}}) +@deftypemethodx Setting {Setting &} operator= (@w{const long long &@var{value}}) +@deftypemethodx Setting {Setting &} operator= (@w{float @var{value}}) +@deftypemethodx Setting {Setting &} operator= (@w{const double &@var{value}}) +@deftypemethodx Setting {Setting &} operator= (@w{const char *@var{value}}) +@deftypemethodx Setting {Setting &} operator= (@w{const std::string &@var{value}}) + +These assignment operators allow values of type @i{bool}, @i{int}, +@i{long}, @i{long long}, @i{float}, @i{double}, @i{const char *}, and +@i{std::string} to be assigned to a setting. In the case of strings, +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{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{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 +@smallexample +Setting& setting = config.lookup("application.misc"); +const char *s = setting["columns"][0]; +@end smallexample +@end cartouche + +If the setting is not an array, list, or group, a +@code{SettingTypeException} is thrown. If the subscript (@var{index} +or @var{name}) does not refer to a valid element, a +@code{SettingNotFoundException} is thrown. + +Iterating over a group's child settings with an integer index will +return the settings in the same order that they appear in the +configuration. + +@end deftypemethod + +@deftypemethod Setting bool lookupValue (@w{const char *@var{name}}, @w{bool &@var{value}}) +@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{bool &@var{value}}) + +@deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{int &@var{value}}) +@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{int &@var{value}}) + +@deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{unsigned int &@var{value}}) +@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{unsigned int &@var{value}}) + +@deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{long long &@var{value}}) +@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{long long &@var{value}}) + +@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{float &@var{value}}) +@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{float &@var{value}}) + +@deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{double &@var{value}}) +@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{double &@var{value}}) + +@deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{const char *&@var{value}}) +@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{const char *&@var{value}}) + +@deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{std::string &@var{value}}) +@deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{std::string &@var{value}}) + +These are convenience methods for looking up the value of a child setting +with the given @var{name}. If the setting is found and is of an +appropriate type, the value is stored in @var{value} and the method +returns @code{true}. Otherwise, @var{value} is left unmodified and the +method returns @code{false}. These methods do not throw exceptions. + +Storage for @w{@i{const char *}} 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 caller. For safety and +convenience, always assigning string values to a @code{std::string} is +suggested. + +Since these methods have boolean return values and do not throw +exceptions, they can be used within boolean logic expressions. The following +example presents a concise way to look up three values at once and +perform error handling if any of them are not found or are of the +wrong type: + +@sp 1 +@cartouche +@smallexample +int var1; +double var2; +const char *var3; + +if(setting.lookupValue("var1", var1) + && setting.lookupValue("var2", var2) + && setting.lookupValue("var3", var3)) +@{ + // use var1, var2, var3 +@} +else +@{ + // error handling here +@} +@end smallexample +@end cartouche + +This approach also takes advantage of the short-circuit evaluation +rules of C++, e.g., if the first lookup fails (returning @code{false}), the +remaining lookups are skipped entirely. + +@end deftypemethod + +@deftypemethod Setting {Setting &} add (@w{const std::string &@var{name}}, @w{Setting::Type @var{type}}) +@deftypemethodx Setting {Setting &} add (@w{const char *@var{name}}, @w{Setting::Type @var{type}}) + +These methods add a new child setting with the given @var{name} and +@var{type} to the setting, which must be a group. They return a +reference to the new setting. If the setting already has a child +setting with the given name, or if the name is invalid, a +@code{SettingNameException} is thrown. If the setting is not a group, +a @code{SettingTypeException} is thrown. + +Once a setting has been created, neither its name nor type can be +changed. + +@end deftypemethod + +@deftypemethod Setting {Setting &} add (@w{Setting::Type @var{type}}) + +This method adds a new element to the setting, which must be of type +@code{TypeArray} or @code{TypeList}. If the setting is an array which +currently has zero elements, the @var{type} parameter (which must be +@code{TypeInt}, @code{TypeInt64}, @code{TypeFloat}, @code{TypeBool}, +or @code{TypeString}) determines the type for the array; otherwise it +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}, as appropriate. + +The method throws a @code{SettingTypeException} if the setting is not +an array or list, or if @var{type} is invalid. + +@end deftypemethod + +@deftypemethod Setting void remove (@w{const std::string &@var{name}}) +@deftypemethodx Setting void remove (@w{const char *@var{name}}) + +These methods remove the child setting with the given @var{name} from +the setting, which must be a group. Any child settings of the removed +setting are recursively destroyed as well. + +If the setting is not a group, a @code{SettingTypeException} is +thrown. If the setting does not have a child setting with the given +name, a @code{SettingNotFoundException} is thrown. + +@end deftypemethod + +@deftypemethod Setting void remove (@w{unsigned int @var{index}}) + +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{index} is out of range, +a @code{SettingNotFoundException} is thrown. + +@end deftypemethod + +@deftypemethod Setting {const char *} getName () + +This method returns the name of the setting, or @code{NULL} if the +setting has no name. Storage for the returned string is managed by the +library and released automatically when the setting is destroyed; the +string must not be freed by the caller. For safety and convenience, +consider assigning the return value to a @code{std::string}. + +@end deftypemethod + +@deftypemethod Setting {std::string} getPath () + +This method returns the complete dot-separated path to the +setting. Settings which do not have a name (list and array elements) +are represented by their index in square brackets. + +@end deftypemethod + +@deftypemethod Setting {Setting &} getParent () + +This method returns the parent setting of the setting. If the setting +is the root setting, a @code{SettingNotFoundException} is thrown. + +@end deftypemethod + +@deftypemethod Setting bool isRoot () + +This method returns @code{true} if the setting is the root setting, and +@code{false} otherwise. + +@end deftypemethod + +@deftypemethod Setting int getIndex () + +This method returns the index of the setting within its parent +setting. When applied to the root setting, this method returns -1. + +@end deftypemethod + +@deftypemethod Setting Setting::Type getType () + +@tindex Setting::Type +This method returns the type of the setting. The +@code{Setting::Type} enumeration consists of the following constants: +@code{TypeInt}, @code{TypeInt64}, @code{TypeFloat}, @code{TypeString}, +@code{TypeBoolean}, @code{TypeArray}, @code{TypeList}, and +@code{TypeGroup}. + +@end deftypemethod + +@deftypemethod Setting Setting::Format getFormat () +@deftypemethodx Setting void setFormat (@w{Setting::Format @var{format}}) + +These methods get and set the external format for the setting. + +@tindex Setting::Format +The @var{Setting::Format} enumeration consists of the following +constants: @code{FormatDefault} and @code{FormatHex}. All settings +support the @code{FormatDefault} format. The @code{FormatHex} format +specifies hexadecimal formatting for integer values, and hence only +applies to settings of type @code{TypeInt} and @code{TypeInt64}. If +@var{format} is invalid for the given setting, it is ignored. + +@end deftypemethod + +@deftypemethod Setting bool exists (@w{const std::string &@var{name}}) +@deftypemethodx Setting bool exists (@w{const char *@var{name}}) + +These methods test if the setting has a child setting with the given +@var{name}. They return @code{true} if the setting exists, and +@code{false} otherwise. These methods do not throw exceptions. + +@end deftypemethod + +@deftypemethod Setting int getLength () + +This method returns the number of settings in a group, or the number of +elements in a list or array. For other types of settings, it returns +0. + +@end deftypemethod + +@deftypemethod Setting bool isGroup () +@deftypemethodx Setting bool isArray () +@deftypemethodx Setting bool isList () + +These convenience methods test if a setting is of a given type. + +@end deftypemethod + +@deftypemethod Setting bool isAggregate () +@deftypemethodx Setting bool isScalar () +@deftypemethodx Setting bool isNumber () + +These convenience methods test if a setting is of an aggregate type (a +group, array, or list), of a scalar type (integer, 64-bit integer, +floating point, boolean, or string), and of a number (integer, 64-bit +integer, or 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 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 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 and include +directives are not part of the grammar, so they are not included here. + +@sp 1 +@example +configuration = setting-list | empty + +setting-list = setting | setting-list setting + +setting = name (":" | "=") value (";" | "," | empty) + +value = scalar-value | array | list | group + +value-list = value | value-list "," value + +scalar-value = boolean | integer | integer64 | hex | hex64 | float + | string + +scalar-value-list = scalar-value | scalar-value-list "," scalar-value + +array = "[" (scalar-value-list | empty) "]" + +list = "(" (value-list | empty) ")" + +group = "@{" (setting-list | empty) "@}" + +empty = +@end example + +@sp 2 +Terminals are defined below as regular expressions: +@sp 1 + +@multitable @columnfractions .2 .8 +@item @code{boolean} @tab +@code{([Tt][Rr][Uu][Ee])|([Ff][Aa][Ll][Ss][Ee])} +@item @code{string} @tab +@code{\"([^\"\\]|\\.)*\"} +@item @code{name} @tab +@code{[A-Za-z\*][-A-Za-z0-9_\*]*} +@item @code{integer} @tab +@code{[-+]?[0-9]+} +@item @code{integer64} @tab +@code{[-+]?[0-9]+L(L)?} +@item @code{hex} @tab +@code{0[Xx][0-9A-Fa-f]+} +@item @code{hex64} @tab +@code{0[Xx][0-9A-Fa-f]+L(L)?} +@item @code{float} @tab +@code{([-+]?([0-9]*)?\.[0-9]*([eE][-+]?[0-9]+)?)|([-+]([0-9]+)(\.[0-9]*)?[eE][-+]?[0-9]+)} +@end multitable + +@node License, Function Index, Configuration File Grammar, Top +@comment node-name, next, previous, up +@appendix License + +@include LGPL.texi + +@node Function Index, Type Index, License, Top +@comment node-name, next, previous, up +@unnumbered Function Index + +@printindex fn + +@node Type Index, Concept Index, Function Index, Top +@comment node-name, next, previous, up +@unnumbered Type Index + +@printindex tp + +@node Concept Index, , Type Index, Top +@comment node-name, next, previous, up +@unnumbered Concept Index + +@printindex cp + +@bye |