/libconfig-1.4.8/doc/libconfig.texi
Unknown | 1910 lines | 1435 code | 475 blank | 0 comment | 0 complexity | 72db844a3b5329c8ba894935cfe5491c MD5 | raw file
Possible License(s): LGPL-2.1, LGPL-2.0
Large files files are truncated, but you can click here to view the full file
1\input texinfo.tex @c -*-texinfo-*-
2@c
3@c %**start of header
4
5@c All text is ignored before the setfilename.
6@setfilename libconfig.info
7@settitle libconfig
8
9@set edition 1.4.8
10@set update-date 4 August 2011
11@set subtitle-text A Library For Processing Structured Configuration Files
12@set author-text Mark A.@: Lindner
13
14@comment %**end of header
15
16@dircategory Software libraries
17@direntry
18* libconfig: (libconfig). A Library For Processing Structured Configuration Files
19@end direntry
20
21
22@tex
23\global\emergencystretch = .3\hsize
24@end tex
25
26@setchapternewpage odd
27
28@titlepage
29
30@title libconfig
31@subtitle @value{subtitle-text}
32@subtitle Version @value{edition}
33@subtitle @value{update-date}
34
35@author @value{author-text}
36
37@page
38@vskip 0pt plus 1filll
39Copyright @copyright{} 2005-2011 Mark A Lindner
40
41Permission is granted to make and distribute verbatim copies of
42this manual provided the copyright notice and this permission notice
43are preserved on all copies.
44
45Permission is granted to copy and distribute modified versions of this
46manual under the conditions for verbatim copying, provided that the entire
47resulting derived work is distributed under the terms of a permission
48notice identical to this one.
49
50@end titlepage
51
52@c Give the HTML output a title page that somewhat resembles the printed one
53@ifhtml
54@html
55<hr noshade size=6 color="black">
56<div align=right>@value{subtitle-text}<br>
57Version @value{edition}<br>
58@value{update-date}</div>
59<br><br><br><br>
60<font size=+1>@value{author-text}</font>
61<hr size=3 noshade color="black">
62<br><br>
63@end html
64@end ifhtml
65
66@contents
67
68@ifnottex
69@node Top
70@comment node-name, next, previous, up
71@top libconfig
72@end ifnottex
73
74@menu
75* Introduction::
76* Configuration Files::
77* The C API::
78* The C++ API::
79* Example Programs::
80* Configuration File Grammar::
81* License::
82* Function Index::
83* Type Index::
84* Concept Index::
85@end menu
86
87@node Introduction, Configuration Files, Top, Top
88@comment node-name, next, previous, up
89@menu
90* Why Another Configuration File Library?::
91* Using the Library from a C Program::
92* Using the Library from a C++ Program::
93* Multithreading Issues::
94* Internationalization Issues::
95* Compiling Using pkg-config::
96* Version Test Macros::
97@end menu
98@chapter Introduction
99
100@i{Libconfig} is a library for reading, manipulating, and writing
101structured configuration files. The library features a fully
102reentrant parser and includes bindings for both the C and C++
103programming languages.
104
105The library runs on modern POSIX-compilant systems, such as Linux,
106Solaris, and Mac OS X (Darwin), as well as on Microsoft Windows
1072000/XP and later (with either Microsoft Visual Studio 2005 or later,
108or the GNU toolchain via the MinGW environment).
109
110@node Why Another Configuration File Library?, Using the Library from a C Program, , Introduction
111@comment node-name, next, previous, up
112@section Why Another Configuration File Library?
113
114There are several open-source configuration file libraries available
115as of this writing. This library was written because each of those
116libraries falls short in one or more ways. The main features of
117@i{libconfig} that set it apart from the other libraries are:
118
119@itemize @bullet
120
121@item A fully reentrant parser. Independent configurations can be parsed in concurrent threads at the same time.
122
123@item Both C @i{and} C++ bindings, as well as hooks to allow for the creation of wrappers in other languages.
124
125@item A simple, structured configuration file format that is more
126readable and compact than XML and more flexible than the obsolete but
127prevalent Windows ``INI'' file format.
128
129@item A low-footprint implementation (just 37K for the C library and 76K for
130the C++ library) that is suitable for memory-constrained systems.
131
132@item Proper documentation.
133
134@end itemize
135
136@node Using the Library from a C Program, Using the Library from a C++ Program, Why Another Configuration File Library?, Introduction
137@comment node-name, next, previous, up
138@section Using the Library from a C Program
139
140To use the library from C code, include the following preprocessor
141directive in your source files:
142
143@sp 1
144@smallexample
145#include <libconfig.h>
146@end smallexample
147@sp 1
148
149To link with the library, specify @samp{-lconfig} as an argument to the
150linker.
151
152@node Using the Library from a C++ Program, Multithreading Issues, Using the Library from a C Program, Introduction
153@comment node-name, next, previous, up
154@section Using the Library from a C++ Program
155
156To use the library from C++, include the following preprocessor
157directive in your source files:
158
159@sp 1
160@smallexample
161#include <libconfig.h++>
162@end smallexample
163@sp 1
164
165Or, alternatively:
166
167@sp 1
168@smallexample
169#include <libconfig.hh>
170@end smallexample
171@sp 1
172@page
173The C++ API classes are defined in the namespace @samp{libconfig}, hence the
174following statement may optionally be used:
175
176@sp 1
177@smallexample
178using namespace libconfig;
179@end smallexample
180@sp 1
181
182To link with the library, specify @samp{-lconfig++} as an argument to
183the linker.
184
185@node Multithreading Issues, Internationalization Issues, Using the Library from a C++ Program, Introduction
186@comment node-name, next, previous, up
187@section Multithreading Issues
188
189@i{Libconfig} is fully @dfn{reentrant}; the functions in the library
190do not make use of global variables and do not maintain state between
191successive calls. Therefore two independent configurations may be safely
192manipulated concurrently by two distinct threads.
193
194@i{Libconfig} is not @dfn{thread-safe}. The library is not aware of
195the presence of threads and knows nothing about the host system's
196threading model. Therefore, if an instance of a configuration is to be
197accessed from multiple threads, it must be suitably protected by
198synchronization mechanisms like read-write locks or mutexes; the
199standard rules for safe multithreaded access to shared data must be
200observed.
201
202@i{Libconfig} is not @dfn{async-safe}. Calls should not be made into
203the library from signal handlers, because some of the C library
204routines that it uses may not be async-safe.
205
206@i{Libconfig} is not guaranteed to be @dfn{cancel-safe}. Since it is
207not aware of the host system's threading model, the library does not
208contain any thread cancellation points. In most cases this will not be
209an issue for multithreaded programs. However, be aware that some of
210the routines in the library (namely those that read/write
211configurations from/to files or streams) perform I/O using C library
212routines which may potentially block; whether or not these C library
213routines are cancel-safe depends on the host system.
214
215@node Internationalization Issues, Compiling Using pkg-config, Multithreading Issues, Introduction
216@comment node-name, next, previous, up
217@section Internationalization Issues
218
219@cindex Unicode
220@cindex UTF-8
221@i{Libconfig} does not natively support Unicode configuration files,
222but string values may contain Unicode text encoded in UTF-8; such
223strings will be treated as ordinary 8-bit ASCII text by the
224library. It is the responsibility of the calling program to perform
225the necessary conversions to/from wide (@t{wchar_t}) strings using the
226wide string conversion functions such as @t{mbsrtowcs()} and
227@t{wcsrtombs()} or the @t{iconv()} function of the @i{libiconv}
228library.
229
230@cindex locale
231The textual representation of a floating point value varies by
232locale. However, the @i{libconfig} grammar specifies that
233floating point values are represented using a period (`.') as the
234radix symbol; this is consistent with the grammar of most programming
235languages. When a configuration is read in or written out,
236@i{libconfig} temporarily changes the @t{LC_NUMERIC} category of the
237locale of the calling thread to the ``C'' locale to ensure consistent
238handling of floating point values regardless of the locale(s) in use
239by the calling program.
240
241Note that the MinGW environment does not (as of this writing) provide
242functions for changing the locale of the calling thread. Therefore,
243when using @i{libconfig} in that environment, the calling program is
244responsible for changing the @t{LC_NUMERIC} category of the locale to
245the "C" locale before reading or writing a configuration.
246
247@node Compiling Using pkg-config, Version Test Macros, Internationalization Issues, Introduction
248@comment node-name, next, previous, up
249@section Compiling Using pkg-config
250
251On UNIX systems you can use the @i{pkg-config} utility (version 0.20
252or later) to automatically select the appropriate compiler and linker
253switches for @i{libconfig}. Ensure that the environment variable
254@code{PKG_CONFIG_PATH} contains the absolute path to the
255@file{lib/pkgconfig} subdirectory of the @i{libconfig} installation. Then,
256you can compile and link C programs with @i{libconfig} as follows:
257
258@smallexample
259gcc `pkg-config --cflags libconfig` myprogram.c -o myprogram \
260 `pkg-config --libs libconfig`
261@end smallexample
262@sp 1
263
264And similarly, for C++ programs:
265
266@smallexample
267g++ `pkg-config --cflags libconfig++` myprogram.cpp -o myprogram \
268 `pkg-config --libs libconfig++`
269@end smallexample
270
271@sp 1
272Note the backticks in the above examples.
273
274When 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:
275
276@smallexample
277PKG_CHECK_MODULES([LIBCONFIGXX], [libconfig++ >= 1.4],,
278 AC_MSG_ERROR([libconfig++ 1.4 or newer not found.])
279)
280@end smallexample
281
282In the above example, if @i{libconfig++} version 1.4 or newer is found,
283the Makefile variables @code{LIBCONFIGXX_LIBS} and @code{LIBCONFIGXX_CFLAGS} will be
284set to the appropriate compiler and linker flags for compiling with
285@i{libconfig}, and if it is not found, the configure script will abort
286with an error to that effect.
287
288@node Version Test Macros, , Compiling Using pkg-config, Introduction
289@comment node-name, next, previous, up
290@section Version Test Macros
291
292The @file{libconfig.h} header declares the following macros:
293
294@defmac LIBCONFIG_VER_MAJOR
295@defmacx LIBCONFIG_VER_MINOR
296@defmacx LIBCONFIG_VER_REVISION
297
298These macros represent the major version, minor version, and revision
299of the @i{libconfig} library. For example, in @i{libconfig} 1.4 these
300are defined as @samp{1}, @samp{4}, and @samp{0}, respectively. These
301macros can be used in preprocessor directives to determine which
302@i{libconfig} features and/or APIs are present. For example:
303
304@smallexample
305#if (((LIBCONFIG_VER_MAJOR == 1) && (LIBCONFIG_VER_MINOR >= 4)) \
306 || (LIBCONFIG_VER_MAJOR > 1))
307 /* use features present in libconfig 1.4 and later */
308#endif
309@end smallexample
310
311These macros were introduced in @i{libconfig} 1.4.
312
313@end defmac
314
315Similarly, the @file{libconfig.h++} header declares the following macros:
316
317@defmac LIBCONFIGXX_VER_MAJOR
318@defmacx LIBCONFIGXX_VER_MINOR
319@defmacx LIBCONFIGXX_VER_REVISION
320
321These macros represent the major version, minor version, and revision
322of the @i{libconfig++} library.
323
324@end defmac
325
326@node Configuration Files, The C API, Introduction, Top
327@comment node-name, next, previous, up
328@menu
329* Settings::
330* Groups::
331* Arrays::
332* Lists::
333* Integer Values::
334* 64-bit Integer Values::
335* Floating Point Values::
336* Boolean Values::
337* String Values::
338* Comments::
339* Include Directives::
340@end menu
341@chapter Configuration Files
342
343@i{Libconfig} supports structured, hierarchical configurations. These
344configurations can be read from and written to files and manipulated
345in memory.
346
347@cindex setting
348@cindex value
349@cindex scalar value
350@cindex array
351@cindex group
352@cindex list
353@cindex configuration
354A @dfn{configuration} consists of a group of @dfn{settings}, which
355associate names with values. A @dfn{value} can be one of the
356following:
357
358@itemize @bullet
359@item A @dfn{scalar value}: integer, 64-bit integer, floating-point number, boolean,
360or string
361@item An @dfn{array}, which is a sequence of scalar values, all of which must have the same type
362@item A @dfn{group}, which is a collection of settings
363@item A @dfn{list}, which is a sequence of values of any type, including other lists
364@end itemize
365
366Consider the following configuration file for a hypothetical GUI
367application, which illustrates all of the elements of the configuration
368file grammar.
369
370@sp 1
371@cartouche
372@smallexample
373# Example application configuration file
374
375version = "1.0";
376
377application:
378@{
379 window:
380 @{
381 title = "My Application";
382 size = @{ w = 640; h = 480; @};
383 pos = @{ x = 350; y = 250; @};
384 @};
385
386 list = ( ( "abc", 123, true ), 1.234, ( /* an empty list */) );
387
388 books = ( @{ title = "Treasure Island";
389 author = "Robert Louis Stevenson";
390 price = 29.95;
391 qty = 5; @},
392 @{ title = "Snow Crash";
393 author = "Neal Stephenson";
394 price = 9.99;
395 qty = 8; @} );
396
397 misc:
398 @{
399 pi = 3.141592654;
400 bigint = 9223372036854775807L;
401 columns = [ "Last Name", "First Name", "MI" ];
402 bitmask = 0x1FC3;
403 @};
404@};
405@end smallexample
406@end cartouche
407@sp 1
408
409@cindex path
410Settings can be uniquely identified within the configuration by a
411@dfn{path}. The path is a dot-separated sequence of names, beginning
412at a top-level group and ending at the setting itself. Each name in
413the path is the name of a setting; if the setting has no name because
414it is an element in a list or array, an integer index in square
415brackets can be used as the name.
416
417For example, in our hypothetical configuration file, the path to the
418@code{x} setting is @code{application.window.pos.x}; the path to the
419@code{version} setting is simply @code{version}; and the path to the
420@code{title} setting of the second book in the @code{books} list is
421@code{application.books.[1].title}.
422
423The datatype of a value is determined from the format of the value
424itself. If the value is enclosed in double quotes, it is treated as a
425string. If it looks like an integer or floating point number, it is
426treated as such. If it is one of the values @code{TRUE}, @code{true},
427@code{FALSE}, or @code{false} (or any other mixed-case version of
428those tokens, e.g., @code{True} or @code{FaLsE}), it is treated as a
429boolean. If it consists of a comma-separated list of values enclosed
430in square brackets, it is treated as an array. And if it consists of a
431comma-separated list of values enclosed in parentheses, it is treated
432as a list. Any value which does not meet any of these criteria is
433considered invalid and results in a parse error.
434
435All names are case-sensitive. They may consist only of alphanumeric
436characters, dashes (@samp{-}), underscores (@samp{_}), and asterisks
437(@samp{*}), and must begin with a letter or asterisk. No other
438characters are allowed.
439
440In C and C++, integer, 64-bit integer, floating point, and string
441values are mapped to the types @code{int}, @code{long long},
442@code{double}, and @code{const char *}, respectively. The boolean type
443is mapped to @code{int} in C and @code{bool} in C++.
444
445The following sections describe the elements of the configuration file
446grammar in additional detail.
447
448@node Settings, Groups, , Configuration Files
449@comment node-name, next, previous, up
450@section Settings
451
452A setting has the form:
453
454@i{name} @b{=} @i{value} @b{;}
455
456or:
457
458@i{name} @b{:} @i{value} @b{;}
459
460The trailing semicolon is optional. Whitespace is not significant.
461
462The value may be a scalar value, an array, a group, or a list.
463
464@node Groups, Arrays, Settings, Configuration Files
465@comment node-name, next, previous, up
466@section Groups
467
468A group has the form:
469
470@b{@{}
471 @i{settings ...}
472@b{@}}
473
474Groups can contain any number of settings, but each setting must have
475a unique name within the group.
476
477@node Arrays, Lists, Groups, Configuration Files
478@comment node-name, next, previous, up
479@section Arrays
480
481An array has the form:
482
483@b{[} @i{value}@b{,} @i{value ...} @b{]}
484
485An array may have zero or more elements, but the elements must all be
486scalar values of the same type.
487
488@node Lists, Integer Values, Arrays, Configuration Files
489@comment node-name, next, previous, up
490@section Lists
491
492A list has the form:
493
494@b{(} @i{value}@b{,} @i{value ...} @b{)}
495
496A list may have zero or more elements, each of which can be a scalar
497value, an array, a group, or another list.
498
499@node Integer Values, 64-bit Integer Values, Lists, Configuration Files
500@comment node-name, next, previous, up
501@section Integer Values
502
503Integers can be represented in one of two ways: as a series of one or
504more decimal digits (@samp{0} - @samp{9}), with an optional leading
505sign character (@samp{+} or @samp{-}); or as a hexadecimal value
506consisting of the characters @samp{0x} followed by a series of one or
507more hexadecimal digits (@samp{0} - @samp{9}, @samp{A} - @samp{F},
508@samp{a} - @samp{f}).
509
510@node 64-bit Integer Values, Floating Point Values, Integer Values, Configuration Files
511@comment node-name, next, previous, up
512@section 64-bit Integer Values
513
514Long long (64-bit) integers are represented identically to integers,
515except that an 'L' character is appended to indicate a 64-bit
516value. For example, @samp{0L} indicates a 64-bit integer value 0.
517
518@node Floating Point Values, Boolean Values, 64-bit Integer Values, Configuration Files
519@comment node-name, next, previous, up
520@section Floating Point Values
521
522Floating point values consist of a series of one or more digits, one
523decimal point, an optional leading sign character (@samp{+} or
524@samp{-}), and an optional exponent. An exponent consists of the
525letter @samp{E} or @samp{e}, an optional sign character, and a series
526of one or more digits.
527
528@node Boolean Values, String Values, Floating Point Values, Configuration Files
529@comment node-name, next, previous, up
530@section Boolean Values
531
532Boolean values may have one of the following values: @samp{true},
533@samp{false}, or any mixed-case variation thereof.
534
535@node String Values, Comments, Boolean Values, Configuration Files
536@comment node-name, next, previous, up
537@section String Values
538
539@cindex escape sequence
540String values consist of arbitrary text delimited by double
541quotes. Literal double quotes can be escaped by preceding them with a
542backslash: @samp{\"}. The escape sequences @samp{\\}, @samp{\f},
543@samp{\n}, @samp{\r}, and @samp{\t} are also recognized, and have the
544usual meaning.
545
546In addition, the @samp{\x} escape sequence is supported; this sequence
547must be followed by @i{exactly two} hexadecimal digits, which represent an
5488-bit ASCII value. For example, @samp{\xFF} represents the character
549with ASCII code 0xFF.
550
551No other escape sequences are currently supported.
552
553Adjacent strings are automatically concatenated, as in C/C++ source
554code. This is useful for formatting very long strings as sequences of
555shorter strings. For example, the following constructs are equivalent:
556
557@itemize @bullet
558@item
559@code{"The quick brown fox jumped over the lazy dog."}
560
561@item
562@code{"The quick brown fox"} @*
563@code{" jumped over the lazy dog."}
564
565@item
566@code{"The quick" /* comment */ " brown fox " // another comment} @*
567@code{"jumped over the lazy dog."}
568
569@end itemize
570@page
571@node Comments, Include Directives, String Values, Configuration Files
572@comment node-name, next, previous, up
573@section Comments
574
575@cindex comment
576Three types of comments are allowed within a configuration:
577
578@itemize @bullet
579
580@item Script-style comments. All text beginning with a @samp{#} character
581to the end of the line is ignored.
582
583@item C-style comments. All text, including line breaks, between a starting
584@samp{/*} sequence and an ending @samp{*/} sequence is ignored.
585
586@item C++-style comments. All text beginning with a @samp{//} sequence to the
587end of the line is ignored.
588
589@end itemize
590
591As expected, comment delimiters appearing within quoted strings are
592treated as literal text.
593
594Comments are ignored when the configuration is read in, so they are
595not treated as part of the configuration. Therefore if the
596configuration is written back out to a stream, any comments that were
597present in the original configuration will be lost.
598
599@node Include Directives, , Comments, Configuration Files
600@comment node-name, next, previous, up
601@section Include Directives
602
603@cindex include directive
604A configuration file may ``include'' the contents of another file
605using an @i{include directive}. This directive has the effect of
606inlining the contents of the named file at the point of inclusion.
607
608An include directive must appear on its own line in the input. It has
609the form:
610
611@b{@@include "}@i{filename}@b{"}
612
613Any backslashes or double quotes in the filename must be escaped as
614@samp{\\} and @samp{\"}, respectively.
615
616For example, consider the following two configuration files:
617
618@cartouche
619@smallexample
620# file: quote.cfg
621quote = "Criticism may not be agreeable, but it is necessary."
622 " It fulfils the same function as pain in the human"
623 " body. It calls attention to an unhealthy state of"
624 " things.\n"
625 "\t--Winston Churchill";
626@end smallexample
627@end cartouche
628
629@cartouche
630@smallexample
631# file: test.cfg
632info: @{
633 name = "Winston Churchill";
634 @@include "quote.cfg"
635 country = "UK";
636@};
637@end smallexample
638@end cartouche
639
640Include files may be nested to a maximum of 10 levels; exceeding this
641limit results in a parse error.
642
643Like comments, include directives are not part of the configuration
644file syntax. They are processed before the configuration itself is
645parsed. Therefore, they are not preserved when the configuration is
646written back out to a stream. There is presently no support for
647programmatically inserting include directives into a configuration.
648
649@node The C API, The C++ API, Configuration Files, Top
650@comment node-name, next, previous, up
651@chapter The C API
652
653@tindex config_t
654@tindex config_setting_t
655This chapter describes the C library API. The type @i{config_t}
656represents a configuration, and the type @i{config_setting_t} represents
657a configuration setting.
658
659The boolean values @code{CONFIG_TRUE} and @code{CONFIG_FALSE} are
660macros defined as @code{(1)} and @code{(0)}, respectively.
661
662@deftypefun void config_init (@w{config_t * @var{config}})
663@deftypefunx void config_destroy (@w{config_t * @var{config}})
664
665These functions initialize and destroy the configuration object @var{config}.
666
667@code{config_init()} initializes the @i{config_t} structure pointed to by
668@var{config} as a new, empty configuration.
669
670@code{config_destroy()} destroys the configuration @var{config},
671deallocating all memory associated with the configuration, but does not
672attempt to deallocate the @i{config_t} structure itself.
673
674@end deftypefun
675
676@deftypefun int config_read (@w{config_t * @var{config}}, @w{FILE * @var{stream}})
677
678This function reads and parses a configuration from the given
679@var{stream} into the configuration object @var{config}. It returns
680@code{CONFIG_TRUE} on success, or @code{CONFIG_FALSE} on failure; the
681@code{config_error_text()}, @code{config_error_file()},
682@code{config_error_line()}, and @code{config_error_type()} functions,
683described below, can be used to obtain information about the error.
684
685@end deftypefun
686
687@deftypefun int config_read_file (@w{config_t * @var{config}}, @w{const char * @var{filename}})
688
689This function reads and parses a configuration from the file named
690@var{filename} into the configuration object @var{config}. It returns
691@code{CONFIG_TRUE} on success, or @code{CONFIG_FALSE} on failure; the
692@code{config_error_text()} and @code{config_error_line()} functions,
693described below, can be used to obtain information about the error.
694
695@end deftypefun
696
697@deftypefun int config_read_string (@w{config_t * @var{config}}, @w{const char * @var{str}})
698
699This function reads and parses a configuration from the string
700@var{str} into the configuration object @var{config}. It returns
701@code{CONFIG_TRUE} on success, or @code{CONFIG_FALSE} on failure; the
702@code{config_error_text()} and @code{config_error_line()} functions,
703described below, can be used to obtain information about the error.
704
705@end deftypefun
706
707@deftypefun void config_write (@w{const config_t * @var{config}}, @w{FILE * @var{stream}})
708
709This function writes the configuration @var{config} to the given
710@var{stream}.
711
712@end deftypefun
713
714@deftypefun int config_write_file (@w{config_t * @var{config}}, @w{const char * @var{filename}})
715
716This function writes the configuration @var{config} to the file named
717@var{filename}. It returns @code{CONFIG_TRUE} on success, or
718@code{CONFIG_FALSE} on failure.
719
720@end deftypefun
721
722@deftypefun {const char *} config_error_text (@w{const config_t * @var{config}})
723@deftypefunx {const char *} config_error_file (@w{const config_t * @var{config}})
724@deftypefunx int config_error_line (@w{const config_t * @var{config}})
725
726These functions, which are implemented as macros, return the text,
727filename, and line number of the parse error, if one occurred during a
728call to @code{config_read()}, @code{config_read_string()}, or
729@code{config_read_file()}. Storage for the strings returned by
730@code{config_error_text()} and @code{config_error_file()} are managed
731by the library and released automatically when the configuration is
732destroyed; these strings must not be freed by the caller. If the error
733occurred in text that was read from a string or stream,
734@code{config_error_file()} will return NULL.
735
736@end deftypefun
737
738@deftypefun config_error_t config_error_type (@w{const config_t * @var{config}})
739@tindex config_error_t
740This function, which is implemented as a macro, returns the type of
741error that occurred during the last call to one of the read or write
742functions. The @var{config_error_t} type is an enumeration with the
743following values: @code{CONFIG_ERR_NONE}, @code{CONFIG_ERR_FILE_IO},
744@code{CONFIG_ERR_PARSE}. These represent success, a file I/O error,
745and a parsing error, respectively.
746
747@end deftypefun
748
749@deftypefun void config_set_include_dir (@w{config_t *@var{config}}, @w{const char *@var{include_dir}})
750@deftypefunx {const char *} config_get_include_dir (@w{const config_t *@var{config}})
751
752@code{config_set_include_dir()} specifies the include directory,
753@var{include_dir}, relative to which the files specified in
754@samp{@@include} directives will be located for the configuration
755@var{config}. By default, there is no include directory, and all
756include files are expected to be relative to the current working
757directory. If @var{include_dir} is @code{NULL}, the default behavior
758is reinstated.
759
760For example, if the include directory is set to @file{/usr/local/etc},
761the include directive @samp{@@include "configs/extra.cfg"} would include the
762file @file{/usr/local/etc/configs/extra.cfg}.
763
764@code{config_get_include_dir()} returns the current include directory for the
765configuration @var{config}, or @code{NULL} if none is set.
766
767@end deftypefun
768
769@deftypefun void config_set_auto_convert (@w{config_t *@var{config}}, @w{int @var{flag}})
770@deftypefunx int config_get_auto_convert (@w{const config_t *@var{config}})
771
772@code{config_set_auto_convert()} enables number auto-conversion for
773the configuration @var{config} if @var{flag} is non-zero, and disables
774it otherwise. When this feature is enabled, an attempt to retrieve a
775floating point setting's value into an integer (or vice versa), or
776store an integer to a floating point setting's value (or vice versa)
777will cause the library to silently perform the necessary conversion
778(possibly leading to loss of data), rather than reporting failure. By
779default this feature is disabled.
780
781@code{config_get_auto_convert()} returns @code{CONFIG_TRUE} if number
782auto-conversion is currently enabled for @var{config}; otherwise it
783returns @code{CONFIG_FALSE}.
784
785@end deftypefun
786
787@deftypefun void config_set_default_format (@w{config_t * @var{config}}, @w{short @var{format}})
788@deftypefunx short config_get_default_format (@w{config_t * @var{config}})
789
790These functions, which are implemented as macros, set and get the
791default external format for settings in the configuration
792@var{config}. If a non-default format has not been set for a setting
793with @code{config_setting_set_format()}, this configuration-wide
794default format will be used instead when that setting is written to a
795file or stream.
796
797@end deftypefun
798
799@deftypefun void config_set_tab_width (@w{config_t * @var{config}}, @w{unsigned short @var{width}})
800@deftypefunx {unsigned short} config_get_tab_width (@w{const config_t * @var{config}})
801
802These functions, which are implemented as macros, set and get the tab
803width for the configuration @var{config}. The tab width affects the
804formatting of the configuration when it is written to a file or
805stream: each level of nesting is indented by @var{width} spaces, or
806by a single tab character if @var{width} is 0. The tab width has no
807effect on parsing.
808
809Valid tab widths range from 0 to 15. The default tab width is 2.
810
811@end deftypefun
812
813@deftypefun int config_lookup_int (@w{const config_t * @var{config}}, @w{const char * @var{path}}, @w{int * @var{value}})
814@deftypefunx int config_lookup_int64 (@w{const config_t * @var{config}}, @w{const char * @var{path}}, @w{long long * @var{value}})
815@deftypefunx int config_lookup_float (@w{const config_t * @var{config}}, @w{const char * @var{path}}, @w{double * @var{value}})
816@deftypefunx int config_lookup_bool (@w{const config_t * @var{config}}, @w{const char * @var{path}}, @w{int * @var{value}})
817@deftypefunx int config_lookup_string (@w{const config_t * @var{config}}, @w{const char * @var{path}}, @w{const char ** @var{value}})
818
819These functions look up the value of the setting in the configuration
820@var{config} specified by the path @var{path}. They store the value of
821the setting at @var{value} and return @code{CONFIG_TRUE} on
822success. If the setting was not found or if the type of the value did
823not match the type requested, they leave the data pointed to by
824@var{value} unmodified and return @code{CONFIG_FALSE}.
825
826Storage for the string returned by @code{config_lookup_string()} is
827managed by the library and released automatically when the setting is
828destroyed or when the setting's value is changed; the string must not
829be freed by the caller.
830
831@end deftypefun
832
833@deftypefun {config_setting_t *} config_lookup (@w{const config_t * @var{config}}, @w{const char * @var{path}})
834
835This function locates the setting in the configuration @var{config}
836specified by the path @var{path}. It returns a pointer to the
837@code{config_setting_t} structure on success, or @code{NULL} if the
838setting was not found.
839
840@end deftypefun
841
842@deftypefun int config_setting_get_int (@w{const config_setting_t * @var{setting}})
843@deftypefunx {long long} config_setting_get_int64 (@w{const config_setting_t * @var{setting}})
844@deftypefunx double config_setting_get_float (@w{const config_setting_t * @var{setting}})
845@deftypefunx int config_setting_get_bool (@w{const config_setting_t * @var{setting}})
846@deftypefunx {const char *} config_setting_get_string (@w{const config_setting_t * @var{setting}})
847
848These functions return the value of the given @var{setting}. If the
849type of the setting does not match the type requested, a 0 or
850@code{NULL} value is returned. Storage for the string returned by
851@code{config_setting_get_string()} is managed by the library and
852released automatically when the setting is destroyed or when the
853setting's value is changed; the string must not be freed by the
854caller.
855
856@end deftypefun
857@deftypefun int config_setting_set_int (@w{config_setting_t * @var{setting}}, @w{int @var{value}})
858@deftypefunx int config_setting_set_int64 (@w{config_setting_t * @var{setting}}, @w{long long @var{value}})
859@deftypefunx int config_setting_set_float (@w{config_setting_t * @var{setting}}, @w{double @var{value}})
860@deftypefunx int config_setting_set_bool (@w{config_setting_t * @var{setting}}, @w{int @var{value}})
861@deftypefunx int config_setting_set_string (@w{config_setting_t * @var{setting}}, @w{const char * @var{value}})
862
863These functions set the value of the given @var{setting} to
864@var{value}. On success, they return @code{CONFIG_TRUE}. If
865the setting does not match the type of the value, they return
866@code{CONFIG_FALSE}. @code{config_setting_set_string()} makes a copy
867of the passed string @var{value}, so it may be subsequently freed or
868modified by the caller without affecting the value of the setting.
869
870@end deftypefun
871
872@deftypefun int config_setting_lookup_int (@w{const config_setting_t * @var{setting}}, @w{const char * @var{name}}, @w{int * @var{value}})
873@deftypefunx int config_setting_lookup_int64 (@w{const config_setting_t * @var{setting}}, @w{const char * @var{name}}, @w{long long * @var{value}})
874@deftypefunx int config_setting_lookup_float (@w{const config_setting_t * @var{setting}}, @w{const char * @var{name}}, @w{double * @var{value}})
875@deftypefunx int config_setting_lookup_bool (@w{const config_setting_t * @var{setting}}, @w{const char * @var{name}}, @w{int * @var{value}})
876@deftypefunx int config_setting_lookup_string (@w{const config_setting_t * @var{setting}}, @w{const char * @var{name}}, @w{const char ** @var{value}})
877
878These functions look up the value of the child setting named
879@var{name} of the setting @var{setting}. They store the value at
880@var{value} and return @code{CONFIG_TRUE} on success. If the setting
881was not found or if the type of the value did not match the type
882requested, they leave the data pointed to by @var{value} unmodified
883and return @code{CONFIG_FALSE}.
884
885Storage for the string returned by @code{config_setting_lookup_string()} is
886managed by the library and released automatically when the setting is
887destroyed or when the setting's value is changed; the string must not
888be freed by the caller.
889
890@end deftypefun
891
892@deftypefun short config_setting_get_format (@w{config_setting_t * @var{setting}})
893@deftypefunx int config_setting_set_format (@w{config_setting_t * @var{setting}}, @w{short @var{format}})
894
895These functions get and set the external format for the setting @var{setting}.
896
897@tindex SettingFormat
898@cindex format
899
900The @var{format} must be one of the constants
901@code{CONFIG_FORMAT_DEFAULT} or @code{CONFIG_FORMAT_HEX}. All settings
902support the @code{CONFIG_FORMAT_DEFAULT} format. The
903@code{CONFIG_FORMAT_HEX} format specifies hexadecimal formatting for
904integer values, and hence only applies to settings of type
905@code{CONFIG_TYPE_INT} and @code{CONFIG_TYPE_INT64}. If @var{format}
906is invalid for the given setting, it is ignored.
907
908If 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()}.
909
910@code{config_setting_set_format()} returns @code{CONFIG_TRUE} on
911success and @code{CONFIG_FALSE} on failure.
912
913@end deftypefun
914
915
916@deftypefun {config_setting_t *} config_setting_get_member (@w{config_setting_t * @var{setting}}, @w{const char * @var{name}})
917
918This function fetches the child setting named @var{name} from the group
919@var{setting}. It returns the requested setting on success, or
920@code{NULL} if the setting was not found or if @var{setting} is not a
921group.
922
923@end deftypefun
924
925@deftypefun {config_setting_t *} config_setting_get_elem (@w{const config_setting_t * @var{setting}}, @w{unsigned int @var{index}})
926
927This function fetches the element at the given index @var{index} in the
928setting @var{setting}, which must be an array, list, or group. It returns the
929requested setting on success, or @code{NULL} if @var{index} is out of
930range or if @var{setting} is not an array, list, or group.
931
932@end deftypefun
933
934@deftypefun int config_setting_get_int_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{index}})
935@deftypefunx {long long} config_setting_get_int64_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{index}})
936@deftypefunx double config_setting_get_float_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{index}})
937@deftypefunx int config_setting_get_bool_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{index}})
938@deftypefunx {const char *} config_setting_get_string_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{index}})
939
940These functions return the value at the specified index @var{index} in the
941setting @var{setting}. If the setting is not an array or list, or if
942the type of the element does not match the type requested, or if
943@var{index} is out of range, they return 0 or @code{NULL}. Storage for
944the string returned by @code{config_setting_get_string_elem()} is
945managed by the library and released automatically when the setting is
946destroyed or when its value is changed; the string must not be freed
947by the caller.
948@end deftypefun
949
950@deftypefun {config_setting_t *} config_setting_set_int_elem (@w{config_setting_t * @var{setting}}, @w{int @var{index}}, @w{int @var{value}})
951@deftypefunx {config_setting_t *} config_setting_set_int64_elem (@w{config_setting_t * @var{setting}}, @w{int @var{index}}, @w{long long @var{value}})
952@deftypefunx {config_setting_t *} config_setting_set_float_elem (@w{config_setting_t * @var{setting}}, @w{int @var{index}}, @w{double @var{value}})
953@deftypefunx {config_setting_t *} config_setting_set_bool_elem (@w{config_setting_t * @var{setting}}, @w{int @var{index}}, @w{int @var{value}})
954@deftypefunx {config_setting_t *} config_setting_set_string_elem (@w{config_setting_t * @var{setting}}, @w{int @var{index}}, @w{const char * @var{value}})
955
956These functions set the value at the specified index @var{index} in the
957setting @var{setting} to @var{value}. If @var{index} is negative, a
958new element is added to the end of the array or list. On success,
959these functions return a pointer to the setting representing the
960element. If the setting is not an array or list, or if the setting is
961an array and the type of the array does not match the type of the
962value, or if @var{index} is out of range, they return
963@code{NULL}. @code{config_setting_set_string_elem()} makes a copy of
964the passed string @var{value}, so it may be subsequently freed or
965modified by the caller without affecting the value of the setting.
966@end deftypefun
967
968@deftypefun {config_setting_t *} config_setting_add (@w{config_setting_t * @var{parent}}, @w{const char * @var{name}}, @w{int @var{type}})
969
970This function adds a new child setting or element to the setting
971@var{parent}, which must be a group, array, or list. If @var{parent}
972is an array or list, the @var{name} parameter is ignored and may be
973@code{NULL}.
974
975The function returns the new setting on success, or @code{NULL} if
976@var{parent} is not a group, array, or list; or if there is already a
977child setting of @var{parent} named @var{name}; or if @var{type} is
978invalid. If @var{type} is a scalar type, the new setting will have a
979default value of 0, 0.0, @code{false}, or @code{NULL}, as appropriate.
980@end deftypefun
981
982@deftypefun int config_setting_remove (@w{config_setting_t * @var{parent}}, @w{const char * @var{name}})
983
984This function removes and destroys the setting named @var{name} from
985the parent setting @var{parent}, which must be a group. Any child
986settings of the setting are recursively destroyed as well.
987
988The function returns @code{CONFIG_TRUE} on success. If @var{parent} is
989not a group, or if it has no setting with the given name, it returns
990@code{CONFIG_FALSE}.
991
992@end deftypefun
993
994@deftypefun int config_setting_remove_elem (@w{config_setting_t * @var{parent}}, @w{unsigned int @var{index}})
995
996This function removes the child setting at the given index @var{index} from
997the setting @var{parent}, which must be a group, list, or array. Any
998child settings of the removed setting are recursively destroyed as
999well.
1000
1001The function returns @code{CONFIG_TRUE} on success. If @var{parent} is
1002not a group, list, or array, or if @var{index} is out of range, it returns
1003@code{CONFIG_FALSE}.
1004
1005@end deftypefun
1006
1007@deftypefun {config_setting_t *} config_root_setting (@w{const config_t * @var{config}})
1008
1009This function returns the root setting for the configuration
1010@var{config}. The root setting is a group.
1011
1012@end deftypefun
1013
1014@deftypefun {const char *} config_setting_name (@w{const config_setting_t * @var{setting}})
1015
1016This function returns the name of the given @var{setting}, or
1017@code{NULL} if the setting has no name. Storage for the returned
1018string is managed by the library and released automatically when the
1019setting is destroyed; the string must not be freed by the caller.
1020
1021@end deftypefun
1022
1023@deftypefun {config_setting_t *} config_setting_parent (@w{const config_setting_t * @var{setting}})
1024
1025This function returns the parent setting of the given @var{setting},
1026or @code{NULL} if @var{setting} is the root setting.
1027
1028@end deftypefun
1029
1030@deftypefun int config_setting_is_root (@w{const config_setting_t * @var{setting}})
1031
1032This function returns @code{CONFIG_TRUE} if the given @var{setting} is
1033the root setting, and @code{CONFIG_FALSE} otherwise.
1034
1035@end deftypefun
1036
1037@deftypefun int config_setting_index (@w{const config_setting_t * @var{setting}})
1038
1039This function returns the index of the given @var{setting} within its
1040parent setting. If @var{setting} is the root setting, this function
1041returns -1.
1042
1043@end deftypefun
1044
1045@deftypefun int config_setting_length (@w{const config_setting_t * @var{setting}})
1046
1047This function returns the number of settings in a group, or the number of
1048elements in a list or array. For other types of settings, it returns
10490.
1050
1051@end deftypefun
1052
1053@deftypefun int config_setting_type (@w{const config_setting_t * @var{setting}})
1054
1055This function returns the type of the given @var{setting}. The return
1056value is one of the constants
1057@code{CONFIG_TYPE_INT}, @code{CONFIG_TYPE_INT64}, @code{CONFIG_TYPE_FLOAT},
1058@code{CONFIG_TYPE_STRING}, @code{CONFIG_TYPE_BOOL},
1059@code{CONFIG_TYPE_ARRAY}, @code{CONFIG_TYPE_LIST}, or @code{CONFIG_TYPE_GROUP}.
1060
1061@end deftypefun
1062
1063@deftypefun int config_setting_is_group (@w{const config_setting_t * @var{setting}})
1064@deftypefunx int config_setting_is_array (@w{const config_setting_t * @var{setting}})
1065@deftypefunx int config_setting_is_list (@w{const config_setting_t * @var{setting}})
1066
1067These convenience functions, which are implemented as macros, test if
1068the setting @var{setting} is of a given type. They return
1069@code{CONFIG_TRUE} or @code{CONFIG_FALSE}.
1070
1071@end deftypefun
1072
1073@deftypefun int config_setting_is_aggregate (@w{const config_setting_t * @var{setting}})
1074@deftypefunx int config_setting_is_scalar (@w{const config_setting_t * @var{setting}})
1075@deftypefunx int config_setting_is_number (@w{const config_setting_t * @var{setting}})
1076
1077@cindex aggregate value
1078These convenience functions, which are implemented as macros, test if
1079the setting @var{setting} is of an aggregate type (a group, array, or
1080list), of a scalar type (integer, 64-bit integer, floating point,
1081boolean, or string), and of a number (integer, 64-bit integer, or
1082floating point), respectively. They return @code{CONFIG_TRUE} or
1083@code{CONFIG_FALSE}.
1084
1085@end deftypefun
1086
1087@deftypefun {const char *} config_setting_source_file (@w{const config_setting_t * @var{setting}})
1088
1089This function returns the name of the file from which the setting
1090@var{setting} was read, or NULL if the setting was not read from a
1091file. This information is useful for reporting application-level
1092errors. Storage for the returned string is managed by the library and
1093released automatically when the configuration is destroyed; the
1094string must not be freed by the caller.
1095
1096@end deftypefun
1097
1098@deftypefun {unsigned int} config_setting_source_line (@w{const config_setting_t * @var{setting}})
1099
1100This function returns the line number of the configuration file or
1101stream at which the setting @var{setting} was read, or 0 if no line
1102number is available. This information is useful for reporting
1103application-level errors.
1104
1105@end deftypefun
1106
1107@deftypefun void config_setting_set_hook (@w{config_setting_t * @var{setting}}, @w{void * @var{hook}})
1108@deftypefunx {void *} config_setting_get_hook (@w{const config_setting_t * @var{setting}})
1109
1110These functions make it possible to attach arbitrary data to each
1111setting structure, for instance a ``wrapper'' or ``peer'' object written in
1112another programming language. The destructor function, if one has been
1113supplied via a call to @code{config_set_destructor()}, will be called
1114by the library to dispose of this data when the setting itself is
1115destroyed. There is no default destructor.
1116
1117@end deftypefun
1118
1119@deftypefun void config_set_destructor (@w{config_t * @var{config}}, @w{void (* @var{destructor})(void *)})
1120
1121This function assigns the destructor function @var{destructor} for the
1122configuration @var{config}. This function accepts a single @code{void
1123*} argument and has no return value. See
1124@code{config_setting_set_hook()} above for more information.
1125
1126@end deftypefun
1127
1128@node The C++ API, Example Programs, The C API, Top
1129@comment node-name, next, previous, up
1130@chapter The C++ API
1131
1132@tindex Config
1133@tindex Setting
1134This chapter describes the C++ library API. The class @code{Config}
1135represents a configuration, and the class @code{Setting} represents a
1136configuration setting. Note that by design, neither of these classes
1137provides a public copy constructor or assignment operator. Therefore,
1138instances of these classes may only be passed between functions via
1139references or pointers.
1140
1141@tindex ConfigException
1142The library defines a group of exceptions, all of which extend the
1143common base exception @code{ConfigException}.
1144
1145@tindex SettingTypeException
1146A @code{SettingTypeException} is thrown when the type of a setting's
1147value does not match the type requested.
1148
1149@tindex SettingNotFoundException
1150A @code{SettingNotFoundException} is thrown when a setting is not found.
1151
1152@tindex SettingNameException
1153A @code{SettingNameException} is thrown when an attempt is made to add
1154a new setting with a non-unique or invalid name.
1155
1156@tindex ParseException
1157A @code{ParseException} is thrown when a parse error occurs while
1158reading a configuration from a stream.
1159
1160@tindex FileIOException
1161A @code{FileIOException} is thrown when an I/O error occurs while
1162reading/writing a configuration from/to a file.
1163
1164@tindex SettingException
1165@code{SettingTypeException}, @code{SettingNotFoundException}, and
1166@code{SettingNameException} all extend the common base
1167exception @code{SettingException}, which provides the following method:
1168
1169@deftypemethod SettingException {const char *} getPath ()
1170
1171Returns the path to the setting associated with the exception, or
1172@code{NULL} if there is no applicable path.
1173
1174@end deftypemethod
1175
1176The remainder of this chapter describes the methods for manipulating
1177configurations and configuration settings.
1178
1179@deftypemethod Config {} Config ()
1180@deftypemethodx Config {} ~Config ()
1181
1182These methods create and destroy @code{Config} objects.
1183
1184@end deftypemethod
1185
1186@deftypemethod Config void read (@w{FILE * @var{stream}})
1187@deftypemethodx Config void write (@w{FILE * @var{stream}})
1188
1189The @code{read()} method reads and parses a configuration from the given
1190@var{stream}. A @code{ParseException} is thrown if a parse error occurs.
1191
1192The @code{write()} method writes the configuration to the given @var{stream}.
1193
1194@end deftypemethod
1195
1196@deftypemethod Config void readFile (@w{const char * @var{filename}})
1197@deftypemethodx Config void writeFile (@w{const char * @var{filename}})
1198
1199The @code{readFile()} method reads and parses a configuration from the
1200file named @var{filename}. A @code{ParseException} is thrown if a
1201parse error occurs. A @code{FileIOException} is thrown if the file
1202cannot be read.
1203
1204The @code{writeFile()} method writes the configuration to the file
1205named @var{filename}. A @code{FileIOException} is thrown if the file cannot
1206be written.
1207
1208@end deftypemethod
1209
1210@deftypemethod Config void readString (@w{const char * @var{str}})
1211@deftypemethodx Config void readString (@w{const std::string &@var{str}})
1212
1213These methods read and parse a configuration from the string
1214@var{str}. A @code{ParseException} is thrown if a parse error occurs.
1215
1216@end deftypemethod
1217
1218@deftypemethod ParseException {const char *} getError ()
1219@deftypemethodx ParseException {const char *} getFile ()
1220@deftypemethodx ParseException int getLine ()
1221
1222If a call to @code{readFile()}, @code{readString()}, or @code{read()}
1223resulted in a @code{ParseException}, these methods can be called on
1224the exception object to obtain the text, filename, and line number of
1225the parse error. Storage for the strings returned by @code{getError()}
1226and @code{getFile()} are managed by the library; the strings must not
1227be freed by the caller.
1228
1229@end deftypemethod
1230
1231@deftypemethod Config void setIncludeDir (@w{const char *@var{includeDir}})
1232@deftypemethodx Config {const char *} getIncludeDir ()
1233
1234@code{setIncludeDir()} specifies the include directory,
1235@var{includeDir}, relative to which the files specified in
1236@samp{@@include} directives will be located for the configuration. By
1237default, there is no include directory, and all include files are
1238expected to be relative to the current working directory. If
1239@var{includeDir} is @code{NULL}, the default behavior is reinstated.
1240
1241For example, if the include directory is set to @file{/usr/local/etc},
1242the include directive @samp{@@include "configs/extra.cfg"} would include the
1243file @file{/usr/local/etc/configs/extra.cfg}.
1244
1245@code{getIncludeDir()} returns the current include directory for the
1246configuration, or @code{NULL} if none is set.
1247
1248@end deftypemethod
1249
1250@deftypemethod Config void setAutoConvert (bool @var{flag})
1251@deftypemethodx Config bool getAutoConvert ()
1252
1253@code{setAutoConvert()} enables number auto-conversion for the
1254configuration if @var{flag} is @code{true}, and disables it
1255otherwise. When this feature is enabled, an attempt to assign a
1256floating point setting to an integer (or vice versa), or
1257assign an integer to a floating point setting (or vice versa) will
1258cause the library to silently perform the necessary conversion
1259(possibly leading to loss of data), rather than throwing a
1260@code{SettingTypeException}. By default this feature is disabled.
1261
1262@code{getAutoConvert()} returns @code{true} if number auto-conversion
1263is currently enabled for the configuration; otherwise it returns
1264@code{false}.
1265
1266@end deftypemethod
1267
1268@deftypemethod Config void setDefaultFormat (@w{Setting::Format @var{format}})
1269@deftypemethodx Config Setting::Format getDefaultFormat ()
1270
1271These methods set and get the default external format for settings in
1272the configuration. If a non-default format has not been set for a
1273sett…Large files files are truncated, but you can click here to view the full file