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.3.1 |
---|
10 | @set update-date 7 September 2008 |
---|
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 |
---|
39 | Copyright @copyright{} 2005-2008 Mark A Lindner |
---|
40 | |
---|
41 | Permission is granted to make and distribute verbatim copies of |
---|
42 | this manual provided the copyright notice and this permission notice |
---|
43 | are preserved on all copies. |
---|
44 | |
---|
45 | Permission is granted to copy and distribute modified versions of this |
---|
46 | manual under the conditions for verbatim copying, provided that the entire |
---|
47 | resulting derived work is distributed under the terms of a permission |
---|
48 | notice 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> |
---|
57 | Version @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 | * Configuration File Grammar:: |
---|
80 | * License:: |
---|
81 | * Function Index:: |
---|
82 | * Type Index:: |
---|
83 | * Concept Index:: |
---|
84 | @end menu |
---|
85 | |
---|
86 | @node Introduction, Configuration Files, Top, Top |
---|
87 | @comment node-name, next, previous, up |
---|
88 | @menu |
---|
89 | * Why Another Configuration File Library?:: |
---|
90 | * Using the Library from a C Program:: |
---|
91 | * Using the Library from a C++ Program:: |
---|
92 | * Multithreading Issues:: |
---|
93 | * Internationalization Issues:: |
---|
94 | * Compiling Using pkg-config:: |
---|
95 | @end menu |
---|
96 | @chapter Introduction |
---|
97 | |
---|
98 | @i{Libconfig} is a library for reading, manipulating, and writing |
---|
99 | structured configuration files. The library features a fully |
---|
100 | reentrant parser and includes bindings for both the C and C++ |
---|
101 | programming languages. |
---|
102 | |
---|
103 | The library runs on modern POSIX-compilant systems, such as Linux, |
---|
104 | Solaris, and Mac OS X (Darwin), as well as on Microsoft Windows |
---|
105 | 2000/XP and later (with either Microsoft Visual Studio 2005 or later, |
---|
106 | or the GNU toolchain via the MinGW environment). |
---|
107 | |
---|
108 | @node Why Another Configuration File Library?, Using the Library from a C Program, , Introduction |
---|
109 | @comment node-name, next, previous, up |
---|
110 | @section Why Another Configuration File Library? |
---|
111 | |
---|
112 | There are several open-source configuration file libraries available |
---|
113 | as of this writing. This library was written because each of those |
---|
114 | libraries falls short in one or more ways. The main features of |
---|
115 | @i{libconfig} that set it apart from the other libraries are: |
---|
116 | |
---|
117 | @itemize @bullet |
---|
118 | |
---|
119 | @item A fully reentrant parser. Independent configurations can be parsed in concurrent threads at the same time. |
---|
120 | |
---|
121 | @item Both C @i{and} C++ bindings, as well as hooks to allow for the creation of wrappers in other languages. |
---|
122 | |
---|
123 | @item A simple, structured configuration file format that is more |
---|
124 | readable and compact than XML and more flexible than the obsolete but |
---|
125 | prevalent Windows ``INI'' file format. |
---|
126 | |
---|
127 | @item A low-footprint implementation (just 38K for the C library and 66K for the C++ library) that is suitable for memory-constrained systems. |
---|
128 | |
---|
129 | @item Proper documentation. |
---|
130 | |
---|
131 | @end itemize |
---|
132 | |
---|
133 | @node Using the Library from a C Program, Using the Library from a C++ Program, Why Another Configuration File Library?, Introduction |
---|
134 | @comment node-name, next, previous, up |
---|
135 | @section Using the Library from a C Program |
---|
136 | |
---|
137 | To use the library from C code, include the following preprocessor |
---|
138 | directive in your source files: |
---|
139 | |
---|
140 | @sp 1 |
---|
141 | @example |
---|
142 | #include <libconfig.h> |
---|
143 | @end example |
---|
144 | @sp 1 |
---|
145 | |
---|
146 | To link with the library, specify @samp{-lconfig} as an argument to the |
---|
147 | linker. |
---|
148 | |
---|
149 | @node Using the Library from a C++ Program, Multithreading Issues, Using the Library from a C Program, Introduction |
---|
150 | @comment node-name, next, previous, up |
---|
151 | @section Using the Library from a C++ Program |
---|
152 | |
---|
153 | To use the library from C++, include the following preprocessor |
---|
154 | directive in your source files: |
---|
155 | |
---|
156 | @sp 1 |
---|
157 | @example |
---|
158 | #include <libconfig.h++> |
---|
159 | @end example |
---|
160 | @sp 1 |
---|
161 | |
---|
162 | Or, alternatively: |
---|
163 | |
---|
164 | @sp 1 |
---|
165 | @example |
---|
166 | #include <libconfig.hh> |
---|
167 | @end example |
---|
168 | @sp 1 |
---|
169 | @page |
---|
170 | The C++ API classes are defined in the namespace @samp{libconfig}, hence the |
---|
171 | following statement may optionally be used: |
---|
172 | |
---|
173 | @sp 1 |
---|
174 | @example |
---|
175 | using namespace libconfig; |
---|
176 | @end example |
---|
177 | @sp 1 |
---|
178 | |
---|
179 | To link with the library, specify @samp{-lconfig++} as an argument to |
---|
180 | the linker. |
---|
181 | |
---|
182 | @node Multithreading Issues, Internationalization Issues, Using the Library from a C++ Program, Introduction |
---|
183 | @comment node-name, next, previous, up |
---|
184 | @section Multithreading Issues |
---|
185 | |
---|
186 | @i{Libconfig} is fully @dfn{reentrant}; the functions in the library |
---|
187 | do not make use of global variables and do not maintain state between |
---|
188 | successive calls. Therefore two independent configurations may be safely |
---|
189 | manipulated concurrently by two distinct threads. |
---|
190 | |
---|
191 | @i{Libconfig} is not @dfn{thread-safe}. The library is not aware of |
---|
192 | the presence of threads and knows nothing about the host system's |
---|
193 | threading model. Therefore, if an instance of a configuration is to be |
---|
194 | accessed from multiple threads, it must be suitably protected by |
---|
195 | synchronization mechanisms like read-write locks or mutexes; the |
---|
196 | standard rules for safe multithreaded access to shared data must be |
---|
197 | observed. |
---|
198 | |
---|
199 | @i{Libconfig} is not @dfn{async-safe}. Calls should not be made into |
---|
200 | the library from signal handlers, because some of the C library |
---|
201 | routines that it uses may not be async-safe. |
---|
202 | |
---|
203 | @i{Libconfig} is not guaranteed to be @dfn{cancel-safe}. Since it is |
---|
204 | not aware of the host system's threading model, the library does not |
---|
205 | contain any thread cancellation points. In most cases this will not be |
---|
206 | an issue for multithreaded programs. However, be aware that some of |
---|
207 | the routines in the library (namely those that read/write |
---|
208 | configurations from/to files or streams) perform I/O using C library |
---|
209 | routines which may potentially block; whether these C library routines |
---|
210 | are cancel-safe or not depends on the host system. |
---|
211 | |
---|
212 | @node Internationalization Issues, Compiling Using pkg-config, Multithreading Issues, Introduction |
---|
213 | @comment node-name, next, previous, up |
---|
214 | @section Internationalization Issues |
---|
215 | |
---|
216 | @cindex Unicode |
---|
217 | @cindex UTF-8 |
---|
218 | @i{Libconfig} does not natively support Unicode configuration files, |
---|
219 | but string values may contain Unicode text encoded in UTF-8; such |
---|
220 | strings will be treated as ordinary 8-bit ASCII text by the |
---|
221 | library. It is the responsibility of the calling program to perform |
---|
222 | the necessary conversions to/from wide (@t{wchar_t}) strings using the |
---|
223 | wide string conversion functions such as @t{mbsrtowcs()} and |
---|
224 | @t{wcsrtombs()} or the @t{iconv()} function of the @i{libiconv} |
---|
225 | library. |
---|
226 | |
---|
227 | @cindex locale |
---|
228 | The textual representation of a floating point value varies by |
---|
229 | locale. However, the @i{libconfig} grammar specifies that |
---|
230 | floating point values are represented using a period (`.') as the |
---|
231 | radix symbol; this is consistent with the grammar of most programming |
---|
232 | languages. When a configuration is read in or written out, |
---|
233 | @i{libconfig} temporarily changes the @t{LC_NUMERIC} category of the |
---|
234 | locale of the calling thread to the "C" locale to ensure consistent |
---|
235 | handling of floating point values regardless of the locale(s) in use |
---|
236 | by the calling program. |
---|
237 | |
---|
238 | Note that the MinGW environment does not (as of this writing) provide |
---|
239 | functions for changing the locale of the calling thread. Therefore, |
---|
240 | when using @i{libconfig} in this environment, the calling program is |
---|
241 | responsible for changing the @t{LC_NUMERIC} category of the locale to |
---|
242 | the "C" locale before reading or writing a configuration. |
---|
243 | |
---|
244 | @node Compiling Using pkg-config, , Internationalization Issues, Introduction |
---|
245 | @comment node-name, next, previous, up |
---|
246 | @section Compiling Using pkg-config |
---|
247 | |
---|
248 | On UNIX systems you can use the @i{pkg-config} utility (version 0.20 |
---|
249 | or later) to automatically select the appropriate compiler and linker |
---|
250 | switches for @i{libconfig}. Ensure that the environment variable |
---|
251 | @samp{PKG_CONFIG_PATH} contains the absolute path to the |
---|
252 | @file{lib/pkgconfig} subdirectory of the libconfig installation. Then, |
---|
253 | you can link C programs with @i{libconfig} as follows: |
---|
254 | |
---|
255 | @example |
---|
256 | gcc `pkg-config --cflags libconfig` myprogram.c -o myprogram \ |
---|
257 | `pkg-config --libs libconfig` |
---|
258 | @end example |
---|
259 | @sp 1 |
---|
260 | |
---|
261 | And similarly, for C++ programs: |
---|
262 | |
---|
263 | @example |
---|
264 | g++ `pkg-config --cflags libconfig++` myprogram.cpp -o myprogram \ |
---|
265 | `pkg-config --libs libconfig++` |
---|
266 | @end example |
---|
267 | |
---|
268 | @sp 1 |
---|
269 | Note the backticks in the above examples. |
---|
270 | |
---|
271 | @node Configuration Files, The C API, Introduction, Top |
---|
272 | @comment node-name, next, previous, up |
---|
273 | @menu |
---|
274 | * Settings:: |
---|
275 | * Groups:: |
---|
276 | * Arrays:: |
---|
277 | * Lists:: |
---|
278 | * Integer Values:: |
---|
279 | * 64-bit Integer Values:: |
---|
280 | * Floating Point Values:: |
---|
281 | * Boolean Values:: |
---|
282 | * String Values:: |
---|
283 | * Comments:: |
---|
284 | @end menu |
---|
285 | @chapter Configuration Files |
---|
286 | |
---|
287 | @i{Libconfig} supports structured, hierarchical configurations. These |
---|
288 | configurations can be read from and written to files and manipulated |
---|
289 | in memory. |
---|
290 | |
---|
291 | @cindex setting |
---|
292 | @cindex value |
---|
293 | @cindex scalar value |
---|
294 | @cindex array |
---|
295 | @cindex group |
---|
296 | @cindex list |
---|
297 | @cindex configuration |
---|
298 | A @dfn{configuration} consists of a group of @dfn{settings}, which |
---|
299 | associate names with values. A @dfn{value} can be one of the |
---|
300 | following: |
---|
301 | |
---|
302 | @itemize @bullet |
---|
303 | @item A @dfn{scalar value}: integer, 64-bit integer, floating-point number, boolean, |
---|
304 | or string |
---|
305 | @item An @dfn{array}, which is a sequence of scalar values, all of which must have the same type |
---|
306 | @item A @dfn{group}, which is a collection of settings |
---|
307 | @item A @dfn{list}, which is a sequence of values of any type, including other lists |
---|
308 | @end itemize |
---|
309 | |
---|
310 | Consider the following configuration file for a hypothetical GUI |
---|
311 | application, which illustrates all of the elements of the configuration |
---|
312 | file grammar. |
---|
313 | |
---|
314 | @sp 1 |
---|
315 | @cartouche |
---|
316 | @smallexample |
---|
317 | # Example application configuration file |
---|
318 | |
---|
319 | version = "1.0"; |
---|
320 | |
---|
321 | application: |
---|
322 | @{ |
---|
323 | window: |
---|
324 | @{ |
---|
325 | title = "My Application"; |
---|
326 | size = @{ w = 640; h = 480; @}; |
---|
327 | pos = @{ x = 350; y = 250; @}; |
---|
328 | @}; |
---|
329 | |
---|
330 | list = ( ( "abc", 123, true ), 1.234, ( /* an empty list */) ); |
---|
331 | |
---|
332 | books = ( @{ title = "Treasure Island"; |
---|
333 | author = "Robert Louis Stevenson"; |
---|
334 | price = 29.95; |
---|
335 | qty = 5; @}, |
---|
336 | @{ title = "Snow Crash"; |
---|
337 | author = "Neal Stephenson"; |
---|
338 | price = 9.99; |
---|
339 | qty = 8; @} ); |
---|
340 | |
---|
341 | misc: |
---|
342 | @{ |
---|
343 | pi = 3.141592654; |
---|
344 | bigint = 9223372036854775807L; |
---|
345 | columns = [ "Last Name", "First Name", "MI" ]; |
---|
346 | bitmask = 0x1FC3; |
---|
347 | @}; |
---|
348 | @}; |
---|
349 | @end smallexample |
---|
350 | @end cartouche |
---|
351 | @sp 1 |
---|
352 | |
---|
353 | @cindex path |
---|
354 | Settings can be uniquely identified within the configuration by a |
---|
355 | @dfn{path}. The path is a dot-separated sequence of names, beginning |
---|
356 | at a top-level group and ending at the setting itself. Each name in |
---|
357 | the path is the name of a setting; if the setting has no name because |
---|
358 | it is an element in a list or array, an integer index in square |
---|
359 | brackets can be used as the name. |
---|
360 | |
---|
361 | For example, in our hypothetical configuration file, the path to the |
---|
362 | @code{x} setting is @code{application.window.pos.x}; the path to the |
---|
363 | @code{version} setting is simply @code{version}; and the path to the |
---|
364 | @code{title} setting of the second book in the @code{books} list is |
---|
365 | @code{application.books.[1].title}. |
---|
366 | |
---|
367 | The datatype of a value is determined from the format of the value |
---|
368 | itself. If the value is enclosed in double quotes, it is treated as a |
---|
369 | string. If it looks like an integer or floating point number, it is |
---|
370 | treated as such. If it is one of the values @code{TRUE}, @code{true}, |
---|
371 | @code{FALSE}, or @code{false} (or any other mixed-case version of |
---|
372 | those tokens, e.g., @code{True} or @code{FaLsE}), it is treated as a |
---|
373 | boolean. If it consists of a comma-separated list of values enclosed |
---|
374 | in square brackets, it is treated as an array. And if it consists of a |
---|
375 | comma-separated list of values enclosed in parentheses, it is treated |
---|
376 | as a list. Any value which does not meet any of these conditions is |
---|
377 | considered invalid and results in a parse error. |
---|
378 | |
---|
379 | All names are case-sensitive. They may consist only of alphanumeric |
---|
380 | characters, dashes (@samp{-}), underscores (@samp{_}), and asterisks |
---|
381 | (@samp{*}), and must begin with a letter or asterisk. No other |
---|
382 | characters are allowed. |
---|
383 | |
---|
384 | In C and C++, integer, 64-bit integer, floating point, and string |
---|
385 | values are mapped to the types @code{long}, @code{long long}, |
---|
386 | @code{double}, and @code{const char *}, respectively. The boolean type |
---|
387 | is mapped to @code{int} in C and @code{bool} in C++. |
---|
388 | |
---|
389 | The following sections describe the elements of the configuration file |
---|
390 | grammar in additional detail. |
---|
391 | |
---|
392 | @node Settings, Groups, , Configuration Files |
---|
393 | @comment node-name, next, previous, up |
---|
394 | @section Settings |
---|
395 | |
---|
396 | A setting has the form: |
---|
397 | |
---|
398 | @i{name} @b{=} @i{value} @b{;} |
---|
399 | |
---|
400 | or: |
---|
401 | |
---|
402 | @i{name} @b{:} @i{value} @b{;} |
---|
403 | |
---|
404 | The trailing semicolon is required. Whitespace is not significant. |
---|
405 | |
---|
406 | The value may be a scalar value, an array, a group, or a list. |
---|
407 | |
---|
408 | @node Groups, Arrays, Settings, Configuration Files |
---|
409 | @comment node-name, next, previous, up |
---|
410 | @section Groups |
---|
411 | |
---|
412 | A group has the form: |
---|
413 | |
---|
414 | @b{@{} |
---|
415 | @i{settings ...} |
---|
416 | @b{@}} |
---|
417 | |
---|
418 | Groups can contain any number of settings, but each setting must have |
---|
419 | a unique name within the group. |
---|
420 | |
---|
421 | @node Arrays, Lists, Groups, Configuration Files |
---|
422 | @comment node-name, next, previous, up |
---|
423 | @section Arrays |
---|
424 | |
---|
425 | An array has the form: |
---|
426 | |
---|
427 | @b{[} @i{value}@b{,} @i{value ...} @b{]} |
---|
428 | |
---|
429 | An array may have zero or more elements, but the elements must all be |
---|
430 | scalar values of the same type. |
---|
431 | |
---|
432 | @node Lists, Integer Values, Arrays, Configuration Files |
---|
433 | @comment node-name, next, previous, up |
---|
434 | @section Lists |
---|
435 | |
---|
436 | A list has the form: |
---|
437 | |
---|
438 | @b{(} @i{value}@b{,} @i{value ...} @b{)} |
---|
439 | |
---|
440 | A list may have zero or more elements, each of which can be a scalar |
---|
441 | value, an array, a group, or another list. |
---|
442 | |
---|
443 | @node Integer Values, 64-bit Integer Values, Lists, Configuration Files |
---|
444 | @comment node-name, next, previous, up |
---|
445 | @section Integer Values |
---|
446 | |
---|
447 | Integers can be represented in one of two ways: as a series of one or |
---|
448 | more decimal digits (@samp{0} - @samp{9}), with an optional leading |
---|
449 | sign character (@samp{+} or @samp{-}); or as a hexadecimal value |
---|
450 | consisting of the characters @samp{0x} followed by a series of one or |
---|
451 | more hexadecimal digits (@samp{0} - @samp{9}, @samp{A} - @samp{F}, |
---|
452 | @samp{a} - @samp{f}). |
---|
453 | |
---|
454 | @node 64-bit Integer Values, Floating Point Values, Integer Values, Configuration Files |
---|
455 | @comment node-name, next, previous, up |
---|
456 | @section 64-bit Integer Values |
---|
457 | |
---|
458 | Long long (64-bit) integers are represented identically to integers, |
---|
459 | except that an 'L' character is appended to indicate a 64-bit |
---|
460 | value. For example, @samp{0L} indicates a 64-bit integer value 0. |
---|
461 | |
---|
462 | @node Floating Point Values, Boolean Values, 64-bit Integer Values, Configuration Files |
---|
463 | @comment node-name, next, previous, up |
---|
464 | @section Floating Point Values |
---|
465 | |
---|
466 | Floating point values consist of a series of one or more digits, one |
---|
467 | decimal point, an optional leading sign character (@samp{+} or |
---|
468 | @samp{-}), and an optional exponent. An exponent consists of the |
---|
469 | letter @samp{E} or @samp{e}, an optional sign character, and a series |
---|
470 | of one or more digits. |
---|
471 | |
---|
472 | @node Boolean Values, String Values, Floating Point Values, Configuration Files |
---|
473 | @comment node-name, next, previous, up |
---|
474 | @section Boolean Values |
---|
475 | |
---|
476 | Boolean values may have one of the following values: @samp{true}, |
---|
477 | @samp{false}, or any mixed-case variation thereof. |
---|
478 | |
---|
479 | @node String Values, Comments, Boolean Values, Configuration Files |
---|
480 | @comment node-name, next, previous, up |
---|
481 | @section String Values |
---|
482 | |
---|
483 | String values consist of arbitrary text delimited by double |
---|
484 | quotes. Literal double quotes can be escaped by preceding them with a |
---|
485 | backslash: @samp{\"}. The escape sequences @samp{\\}, @samp{\f}, |
---|
486 | @samp{\n}, @samp{\r}, and @samp{\t} are also recognized, and have the |
---|
487 | usual meaning. No other escape sequences are currently supported. |
---|
488 | |
---|
489 | Adjacent strings are automatically concatenated, as in C/C++ source |
---|
490 | code. This is useful for formatting very long strings as sequences of |
---|
491 | shorter strings. For example, the following constructs are equivalent: |
---|
492 | |
---|
493 | @itemize @bullet |
---|
494 | @item |
---|
495 | @code{"The quick brown fox jumped over the lazy dog."} |
---|
496 | |
---|
497 | @item |
---|
498 | @code{"The quick brown fox"} @* |
---|
499 | @code{" jumped over the lazy dog."} |
---|
500 | |
---|
501 | @item |
---|
502 | @code{"The quick" /* comment */ " brown fox " // another comment} @* |
---|
503 | @code{"jumped over the lazy dog."} |
---|
504 | |
---|
505 | @end itemize |
---|
506 | @page |
---|
507 | @node Comments, , String Values, Configuration Files |
---|
508 | @comment node-name, next, previous, up |
---|
509 | @section Comments |
---|
510 | |
---|
511 | @cindex comment |
---|
512 | Three types of comments are allowed within a configuration: |
---|
513 | |
---|
514 | @itemize @bullet |
---|
515 | |
---|
516 | @item Script-style comments. All text beginning with a @samp{#} character |
---|
517 | to the end of the line is ignored. |
---|
518 | |
---|
519 | @item C-style comments. All text, including line breaks, between a starting |
---|
520 | @samp{/*} sequence and an ending @samp{*/} sequence is ignored. |
---|
521 | |
---|
522 | @item C++-style comments. All text beginning with a @samp{//} sequence to the |
---|
523 | end of the line is ignored. |
---|
524 | |
---|
525 | @end itemize |
---|
526 | |
---|
527 | As expected, comment delimiters appearing within quoted strings are |
---|
528 | treated as literal text. |
---|
529 | |
---|
530 | Comments are ignored when the configuration is read in, so they are |
---|
531 | not treated as part of the configuration. Therefore if the |
---|
532 | configuration is written back out to a stream, any comments that were |
---|
533 | present in the original configuration will be lost. |
---|
534 | |
---|
535 | @node The C API, The C++ API, Configuration Files, Top |
---|
536 | @comment node-name, next, previous, up |
---|
537 | @chapter The C API |
---|
538 | |
---|
539 | @tindex config_t |
---|
540 | @tindex config_setting_t |
---|
541 | This chapter describes the C library API. The type @i{config_t} |
---|
542 | represents a configuration, and the type @i{config_setting_t} represents |
---|
543 | a configuration setting. |
---|
544 | |
---|
545 | The boolean values @code{CONFIG_TRUE} and @code{CONFIG_FALSE} are |
---|
546 | macros defined as @code{(1)} and @code{(0)}, respectively. |
---|
547 | |
---|
548 | @deftypefun void config_init (@w{config_t * @var{config}}) |
---|
549 | @deftypefunx void config_destroy (@w{config_t * @var{config}}) |
---|
550 | |
---|
551 | These functions initialize and destroy the configuration object @var{config}. |
---|
552 | |
---|
553 | @code{config_init()} initializes @var{config} as a new, empty |
---|
554 | configuration. |
---|
555 | |
---|
556 | @code{config_destroy()} destroys the configuration @var{config}, |
---|
557 | deallocating all memory associated with the configuration, but not |
---|
558 | including the @i{config_t} structure itself. |
---|
559 | |
---|
560 | @end deftypefun |
---|
561 | |
---|
562 | @deftypefun int config_read (@w{config_t * @var{config}}, @w{FILE * @var{stream}}) |
---|
563 | |
---|
564 | This function reads and parses a configuration from the given |
---|
565 | @var{stream} into the configuration object @var{config}. It returns |
---|
566 | @code{CONFIG_TRUE} on success, or @code{CONFIG_FALSE} on failure; the |
---|
567 | @code{config_error_text()} and @code{config_error_line()} |
---|
568 | functions, described below, can be used to obtain information about the |
---|
569 | error. |
---|
570 | |
---|
571 | @end deftypefun |
---|
572 | |
---|
573 | @deftypefun int config_read_file (@w{config_t * @var{config}}, @w{const char * @var{filename}}) |
---|
574 | |
---|
575 | This function reads and parses a configuration from the file named |
---|
576 | @var{filename} into the configuration object @var{config}. It returns |
---|
577 | @code{CONFIG_TRUE} on success, or @code{CONFIG_FALSE} on failure; the |
---|
578 | @code{config_error_text()} and @code{config_error_line()} functions, |
---|
579 | described below, can be used to obtain information about the error. |
---|
580 | |
---|
581 | @end deftypefun |
---|
582 | |
---|
583 | @deftypefun void config_write (@w{const config_t * @var{config}}, @w{FILE * @var{stream}}) |
---|
584 | |
---|
585 | This function writes the configuration @var{config} to the given |
---|
586 | @var{stream}. |
---|
587 | |
---|
588 | @end deftypefun |
---|
589 | |
---|
590 | @deftypefun int config_write_file (@w{config_t * @var{config}}, @w{const char * @var{filename}}) |
---|
591 | |
---|
592 | This function writes the configuration @var{config} to the file named |
---|
593 | @var{filename}. It returns @code{CONFIG_TRUE} on success, or |
---|
594 | @code{CONFIG_FALSE} on failure. |
---|
595 | |
---|
596 | @end deftypefun |
---|
597 | |
---|
598 | @deftypefun {const char *} config_error_text (@w{const config_t * @var{config}}) |
---|
599 | @deftypefunx int config_error_line (@w{const config_t * @var{config}}) |
---|
600 | |
---|
601 | These functions, which are implemented as macros, return the text and |
---|
602 | line number of the parse error, if one occurred during a call to |
---|
603 | @code{config_read()} or @code{config_read_file()}. Storage for the |
---|
604 | string returned by @code{config_error_text()} is managed by the |
---|
605 | library and released automatically when the configuration is |
---|
606 | destroyed; the string must not be freed by the caller. |
---|
607 | |
---|
608 | @end deftypefun |
---|
609 | |
---|
610 | @deftypefun void config_set_auto_convert (@w{config_t *@var{config}}, @w{int @var{flag}}) |
---|
611 | @deftypefunx int config_get_auto_convert (@w{const config_t *@var{config}}) |
---|
612 | |
---|
613 | @code{config_set_auto_convert()} enables number auto-conversion for |
---|
614 | the configuration @var{config} if @var{flag} is non-zero, and disables |
---|
615 | it otherwise. When this feature is enabled, an attempt to retrieve a |
---|
616 | floating point setting's value into an integer (or vice versa), or |
---|
617 | store an integer to a floating point setting's value (or vice versa) |
---|
618 | will cause the library to silently perform the necessary conversion |
---|
619 | (possibly leading to loss of data), rather than reporting failure. By |
---|
620 | default this feature is disabled. |
---|
621 | |
---|
622 | @code{config_get_auto_convert()} returns @code{CONFIG_TRUE} if number |
---|
623 | auto-conversion is currently enabled for @var{config}; otherwise it |
---|
624 | returns @code{CONFIG_FALSE}. |
---|
625 | |
---|
626 | @end deftypefun |
---|
627 | |
---|
628 | @deftypefun long config_lookup_int (@w{const config_t * @var{config}}, @w{const char * @var{path}}) |
---|
629 | @deftypefunx {long long} config_lookup_int64 (@w{const config_t * @var{config}}, @w{const char * @var{path}}) |
---|
630 | @deftypefunx double config_lookup_float (@w{const config_t * @var{config}}, @w{const char * @var{path}}) |
---|
631 | @deftypefunx int config_lookup_bool (@w{const config_t * @var{config}}, @w{const char * @var{path}}) |
---|
632 | @deftypefunx {const char *} config_lookup_string (@w{const config_t * @var{config}}, @w{const char * @var{path}}) |
---|
633 | |
---|
634 | These functions locate the setting in the configuration @var{config} |
---|
635 | specified by the path @var{path}. They return the value of the setting |
---|
636 | on success, or a 0 or @code{NULL} value if the setting was not found or |
---|
637 | if the type of the value did not match the type requested. |
---|
638 | |
---|
639 | Storage for the string returned by @code{config_lookup_string()} is |
---|
640 | managed by the library and released automatically when the setting is |
---|
641 | destroyed or when the setting's value is changed; the string must not |
---|
642 | be freed by the caller. |
---|
643 | |
---|
644 | @end deftypefun |
---|
645 | |
---|
646 | @deftypefun {config_setting_t *} config_lookup (@w{const config_t * @var{config}}, @w{const char * @var{path}}) |
---|
647 | |
---|
648 | This function locates the setting in the configuration @var{config} |
---|
649 | specified by the path @var{path}. It returns a pointer to the |
---|
650 | @code{config_setting_t} structure on success, or @code{NULL} if the |
---|
651 | setting was not found. |
---|
652 | |
---|
653 | @end deftypefun |
---|
654 | |
---|
655 | @deftypefun long config_setting_get_int (@w{const config_setting_t * @var{setting}}) |
---|
656 | @deftypefunx {long long} config_setting_get_int64 (@w{const config_setting_t * @var{setting}}) |
---|
657 | @deftypefunx double config_setting_get_float (@w{const config_setting_t * @var{setting}}) |
---|
658 | @deftypefunx int config_setting_get_bool (@w{const config_setting_t * @var{setting}}) |
---|
659 | @deftypefunx {const char *} config_setting_get_string (@w{const config_setting_t * @var{setting}}) |
---|
660 | |
---|
661 | These functions return the value of the given @var{setting}. If the |
---|
662 | type of the setting does not match the type requested, a 0 or |
---|
663 | @code{NULL} value is returned. Storage for the string returned by |
---|
664 | @code{config_setting_get_string()} is managed by the library and |
---|
665 | released automatically when the setting is destroyed or when the |
---|
666 | setting's value is changed; the string must not be freed by the |
---|
667 | caller. |
---|
668 | |
---|
669 | @end deftypefun |
---|
670 | @page |
---|
671 | @deftypefun int config_setting_set_int (@w{config_setting_t * @var{setting}}, @w{long @var{value}}) |
---|
672 | @deftypefunx int config_setting_set_int64 (@w{config_setting_t * @var{setting}}, @w{long long @var{value}}) |
---|
673 | @deftypefunx int config_setting_set_float (@w{config_setting_t * @var{setting}}, @w{double @var{value}}) |
---|
674 | @deftypefunx int config_setting_set_bool (@w{config_setting_t * @var{setting}}, @w{int @var{value}}) |
---|
675 | @deftypefunx int config_setting_set_string (@w{config_setting_t * @var{setting}}, @w{const char * @var{value}}) |
---|
676 | |
---|
677 | These functions set the value of the given @var{setting} to |
---|
678 | @var{value}. On success, they return @code{CONFIG_TRUE}. If |
---|
679 | the setting does not match the type of the value, they return |
---|
680 | @code{CONFIG_FALSE}. @code{config_setting_set_string()} makes a copy |
---|
681 | of the passed string @var{value}, so it may be subsequently freed or |
---|
682 | modified by the caller without affecting the value of the setting. |
---|
683 | |
---|
684 | @end deftypefun |
---|
685 | |
---|
686 | @deftypefun short config_setting_get_format (@w{config_setting_t * @var{setting}}) |
---|
687 | @deftypefunx int config_setting_set_format (@w{config_setting_t * @var{setting}}, @w{short @var{format}}) |
---|
688 | |
---|
689 | These functions get and set the external format for the setting @var{setting}. |
---|
690 | |
---|
691 | @tindex SettingFormat |
---|
692 | @cindex format |
---|
693 | |
---|
694 | The @var{format} must be one of the constants |
---|
695 | @code{CONFIG_FORMAT_DEFAULT} or @code{CONFIG_FORMAT_HEX}. All settings |
---|
696 | support the @code{CONFIG_FORMAT_DEFAULT} format. The |
---|
697 | @code{CONFIG_FORMAT_HEX} format specifies hexadecimal formatting for |
---|
698 | integer values, and hence only applies to settings of type |
---|
699 | @code{CONFIG_TYPE_INT} and @code{CONFIG_TYPE_INT64}. If @var{format} |
---|
700 | is invalid for the given setting, it is ignored. |
---|
701 | |
---|
702 | @code{config_setting_set_format()} returns @code{CONFIG_TRUE} on |
---|
703 | success and @code{CONFIG_FALSE} on failure. |
---|
704 | |
---|
705 | @end deftypefun |
---|
706 | |
---|
707 | |
---|
708 | @deftypefun {config_setting_t *} config_setting_get_member (@w{config_setting_t * @var{setting}}, @w{const char * @var{name}}) |
---|
709 | |
---|
710 | This function fetches the child setting named @var{name} from the group |
---|
711 | @var{setting}. It returns the requested setting on success, or |
---|
712 | @code{NULL} if the setting was not found or if @var{setting} is not a |
---|
713 | group. |
---|
714 | |
---|
715 | @end deftypefun |
---|
716 | |
---|
717 | @deftypefun {config_setting_t *} config_setting_get_elem (@w{const config_setting_t * @var{setting}}, @w{unsigned int @var{idx}}) |
---|
718 | |
---|
719 | This function fetches the element at the given index @var{idx} in the |
---|
720 | setting @var{setting}, which must be an array, list, or group. It returns the |
---|
721 | requested setting on success, or @code{NULL} if @var{idx} is out of |
---|
722 | range or if @var{setting} is not an array, list, or group. |
---|
723 | |
---|
724 | @end deftypefun |
---|
725 | @page |
---|
726 | @deftypefun long config_setting_get_int_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{idx}}) |
---|
727 | @deftypefunx {long long} config_setting_get_int64_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{idx}}) |
---|
728 | @deftypefunx double config_setting_get_float_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{idx}}) |
---|
729 | @deftypefunx int config_setting_get_bool_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{idx}}) |
---|
730 | @deftypefunx {const char *} config_setting_get_string_elem (@w{const config_setting_t * @var{setting}}, @w{int @var{idx}}) |
---|
731 | |
---|
732 | These functions return the value at the specified index @var{idx} in the |
---|
733 | setting @var{setting}. If the setting is not an array or list, or if |
---|
734 | the type of the element does not match the type requested, or if |
---|
735 | @var{idx} is out of range, they return 0 or @code{NULL}. Storage for |
---|
736 | the string returned by @code{config_setting_get_string_elem()} is |
---|
737 | managed by the library and released automatically when the setting is |
---|
738 | destroyed or when its value is changed; the string must not be freed |
---|
739 | by the caller. |
---|
740 | @end deftypefun |
---|
741 | |
---|
742 | @deftypefun {config_setting_t *} config_setting_set_int_elem (@w{config_setting_t * @var{setting}}, @w{int @var{idx}}, @w{long @var{value}}) |
---|
743 | @deftypefunx {config_setting_t *} config_setting_set_int64_elem (@w{config_setting_t * @var{setting}}, @w{int @var{idx}}, @w{long long @var{value}}) |
---|
744 | @deftypefunx {config_setting_t *} config_setting_set_float_elem (@w{config_setting_t * @var{setting}}, @w{int @var{idx}}, @w{double @var{value}}) |
---|
745 | @deftypefunx {config_setting_t *} config_setting_set_bool_elem (@w{config_setting_t * @var{setting}}, @w{int @var{idx}}, @w{int @var{value}}) |
---|
746 | @deftypefunx {config_setting_t *} config_setting_set_string_elem (@w{config_setting_t * @var{setting}}, @w{int @var{idx}}, @w{const char * @var{value}}) |
---|
747 | |
---|
748 | These functions set the value at the specified index @var{idx} in the |
---|
749 | setting @var{setting} to @var{value}. If @var{idx} is negative, a |
---|
750 | new element is added to the end of the array or list. On success, |
---|
751 | these functions return a pointer to the setting representing the |
---|
752 | element. If the setting is not an array or list, or if the setting is |
---|
753 | an array and the type of the array does not match the type of the |
---|
754 | value, or if @var{idx} is out of range, they return |
---|
755 | @code{NULL}. @code{config_setting_set_string_elem()} makes a copy of |
---|
756 | the passed string @var{value}, so it may be subsequently freed or |
---|
757 | modified by the caller without affecting the value of the setting. |
---|
758 | @end deftypefun |
---|
759 | |
---|
760 | @deftypefun {config_setting_t *} config_setting_add (@w{config_setting_t * @var{parent}}, @w{const char * @var{name}}, @w{int @var{type}}) |
---|
761 | |
---|
762 | This function adds a new child setting or element to the setting |
---|
763 | @var{parent}, which must be a group, array, or list. If @var{parent} |
---|
764 | is an array or list, the @var{name} parameter is ignored and may be |
---|
765 | @code{NULL}. |
---|
766 | |
---|
767 | The function returns the new setting on success, or @code{NULL} if |
---|
768 | @var{parent} is not a group, array, or list; or if there is already a |
---|
769 | child setting of @var{parent} named @var{name}; or if @var{type} is |
---|
770 | invalid. |
---|
771 | @end deftypefun |
---|
772 | |
---|
773 | @deftypefun int config_setting_remove (@w{config_setting_t * @var{parent}}, @w{const char * @var{name}}) |
---|
774 | |
---|
775 | This function removes and destroys the setting named @var{name} from |
---|
776 | the parent setting @var{parent}, which must be a group. Any child |
---|
777 | settings of the setting are recursively destroyed as well. |
---|
778 | |
---|
779 | The function returns @code{CONFIG_TRUE} on success. If @var{parent} is |
---|
780 | not a group, or if it has no setting with the given name, it returns |
---|
781 | @code{CONFIG_FALSE}. |
---|
782 | |
---|
783 | @end deftypefun |
---|
784 | |
---|
785 | @deftypefun int config_setting_remove_elem (@w{config_setting_t * @var{parent}}, @w{unsigned int @var{idx}}) |
---|
786 | |
---|
787 | This function removes the child setting at the given index @var{idx} from |
---|
788 | the setting @var{parent}, which must be a group, list, or array. Any |
---|
789 | child settings of the removed setting are recursively destroyed as |
---|
790 | well. |
---|
791 | |
---|
792 | The function returns @code{CONFIG_TRUE} on success. If @var{parent} is |
---|
793 | not a group, list, or array, or if @var{idx} is out of range, it returns |
---|
794 | @code{CONFIG_FALSE}. |
---|
795 | |
---|
796 | @end deftypefun |
---|
797 | |
---|
798 | @deftypefun {config_setting_t *} config_root_setting (@w{const config_t * @var{config}}) |
---|
799 | |
---|
800 | This function returns the root setting for the configuration |
---|
801 | @var{config}. The root setting is a group. |
---|
802 | |
---|
803 | @end deftypefun |
---|
804 | |
---|
805 | @deftypefun {const char *} config_setting_name (@w{const config_setting_t * @var{setting}}) |
---|
806 | |
---|
807 | This function returns the name of the given @var{setting}, or |
---|
808 | @code{NULL} if the setting has no name. Storage for the returned |
---|
809 | string is managed by the library and released automatically when the |
---|
810 | setting is destroyed; the string must not be freed by the caller. |
---|
811 | |
---|
812 | @end deftypefun |
---|
813 | |
---|
814 | @deftypefun {config_setting_t *} config_setting_parent (@w{const config_setting_t * @var{setting}}) |
---|
815 | |
---|
816 | This function returns the parent setting of the given @var{setting}, |
---|
817 | or @code{NULL} if @var{setting} is the root setting. |
---|
818 | |
---|
819 | @end deftypefun |
---|
820 | |
---|
821 | @deftypefun int config_setting_is_root (@w{const config_setting_t * @var{setting}}) |
---|
822 | |
---|
823 | This function returns @code{CONFIG_TRUE} if the given @var{setting} is |
---|
824 | the root setting, and @code{CONFIG_FALSE} otherwise. |
---|
825 | |
---|
826 | @end deftypefun |
---|
827 | |
---|
828 | @deftypefun int config_setting_index (@w{const config_setting_t * @var{setting}}) |
---|
829 | |
---|
830 | This function returns the index of the given @var{setting} within its |
---|
831 | parent setting. If @var{setting} is the root setting, this function |
---|
832 | returns -1. |
---|
833 | |
---|
834 | @end deftypefun |
---|
835 | |
---|
836 | @deftypefun int config_setting_length (@w{const config_setting_t * @var{setting}}) |
---|
837 | |
---|
838 | This function returns the number of settings in a group, or the number of |
---|
839 | elements in a list or array. For other types of settings, it returns |
---|
840 | 0. |
---|
841 | |
---|
842 | @end deftypefun |
---|
843 | |
---|
844 | @deftypefun int config_setting_type (@w{const config_setting_t * @var{setting}}) |
---|
845 | |
---|
846 | This function returns the type of the given @var{setting}. The return |
---|
847 | value is one of the constants |
---|
848 | @code{CONFIG_TYPE_INT}, @code{CONFIG_TYPE_INT64}, @code{CONFIG_TYPE_FLOAT}, |
---|
849 | @code{CONFIG_TYPE_STRING}, @code{CONFIG_TYPE_BOOL}, |
---|
850 | @code{CONFIG_TYPE_ARRAY}, @code{CONFIG_TYPE_LIST}, or @code{CONFIG_TYPE_GROUP}. |
---|
851 | |
---|
852 | @end deftypefun |
---|
853 | |
---|
854 | @deftypefun int config_setting_is_group (@w{const config_setting_t * @var{setting}}) |
---|
855 | @deftypefunx int config_setting_is_array (@w{const config_setting_t * @var{setting}}) |
---|
856 | @deftypefunx int config_setting_is_list (@w{const config_setting_t * @var{setting}}) |
---|
857 | |
---|
858 | These convenience functions, which are implemented as macros, test if |
---|
859 | the setting @var{setting} is of a given type. They return |
---|
860 | @code{CONFIG_TRUE} or @code{CONFIG_FALSE}. |
---|
861 | |
---|
862 | @end deftypefun |
---|
863 | |
---|
864 | @deftypefun int config_setting_is_aggregate (@w{const config_setting_t * @var{setting}}) |
---|
865 | @deftypefunx int config_setting_is_scalar (@w{const config_setting_t * @var{setting}}) |
---|
866 | @deftypefunx int config_setting_is_number (@w{const config_setting_t * @var{setting}}) |
---|
867 | |
---|
868 | @cindex aggregate value |
---|
869 | These convenience functions, which are implemented as macros, test if |
---|
870 | the setting @var{setting} is of an aggregate type (a group, array, or |
---|
871 | list), of a scalar type (integer, 64-bit integer, floating point, |
---|
872 | boolean, or string), and of a number (integer, 64-bit integer, or |
---|
873 | floating point), respectively. They return @code{CONFIG_TRUE} or |
---|
874 | @code{CONFIG_FALSE}. |
---|
875 | |
---|
876 | @end deftypefun |
---|
877 | |
---|
878 | @deftypefun {unsigned int} config_setting_source_line (@w{const config_setting_t * @var{setting}}) |
---|
879 | |
---|
880 | This function returns the line number of the configuration file or |
---|
881 | stream at which the setting @var{setting} was parsed. This information |
---|
882 | is useful for reporting application-level errors. If the setting was |
---|
883 | not read from a file or stream, or if the line number is otherwise |
---|
884 | unavailable, the function returns 0. |
---|
885 | |
---|
886 | @end deftypefun |
---|
887 | |
---|
888 | @deftypefun void config_setting_set_hook (@w{config_setting_t * @var{setting}}, @w{void * @var{hook}}) |
---|
889 | @deftypefunx {void *} config_setting_get_hook (@w{const config_setting_t * @var{setting}}) |
---|
890 | |
---|
891 | These functions make it possible to attach arbitrary data to each |
---|
892 | setting structure, for instance a ``wrapper'' or ``peer'' object written in |
---|
893 | another programming language. The destructor function, if one has been |
---|
894 | supplied via a call to @code{config_set_destructor()}, will be called |
---|
895 | by the library to dispose of this data when the setting itself is |
---|
896 | destroyed. There is no default destructor. |
---|
897 | |
---|
898 | @end deftypefun |
---|
899 | |
---|
900 | @deftypefun void config_set_destructor (@w{config_t * @var{config}}, @w{void (* @var{destructor})(void *)}) |
---|
901 | |
---|
902 | This function assigns the destructor function @var{destructor} for the |
---|
903 | configuration @var{config}. This function accepts a single @code{void |
---|
904 | *} argument and has no return value. See |
---|
905 | @code{config_setting_set_hook()} above for more information. |
---|
906 | |
---|
907 | @end deftypefun |
---|
908 | |
---|
909 | @node The C++ API, Configuration File Grammar, The C API, Top |
---|
910 | @comment node-name, next, previous, up |
---|
911 | @chapter The C++ API |
---|
912 | |
---|
913 | @tindex Config |
---|
914 | @tindex Setting |
---|
915 | This chapter describes the C++ library API. The class @code{Config} |
---|
916 | represents a configuration, and the class @code{Setting} represents a |
---|
917 | configuration setting. Note that by design, neither of these classes |
---|
918 | provides a public copy constructor or assignment operator. Therefore, |
---|
919 | instances of these classes may only be passed between functions via |
---|
920 | references or pointers. |
---|
921 | |
---|
922 | @tindex ConfigException |
---|
923 | The library defines a group of exceptions, all of which extend the |
---|
924 | common base exception @code{ConfigException}. |
---|
925 | |
---|
926 | @tindex SettingTypeException |
---|
927 | A @code{SettingTypeException} is thrown when the type of a setting's |
---|
928 | value does not match the type requested. |
---|
929 | |
---|
930 | @tindex SettingNotFoundException |
---|
931 | A @code{SettingNotFoundException} is thrown when a setting is not found. |
---|
932 | |
---|
933 | @tindex SettingNameException |
---|
934 | A @code{SettingNameException} is thrown when an attempt is made to add |
---|
935 | a new setting with a non-unique or invalid name. |
---|
936 | |
---|
937 | @tindex ParseException |
---|
938 | A @code{ParseException} is thrown when a parse error occurs while |
---|
939 | reading a configuration from a stream. |
---|
940 | |
---|
941 | @tindex FileIOException |
---|
942 | A @code{FileIOException} is thrown when an I/O error occurs while |
---|
943 | reading/writing a configuration from/to a file. |
---|
944 | |
---|
945 | @tindex SettingException |
---|
946 | @code{SettingTypeException}, @code{SettingNotFoundException}, and |
---|
947 | @code{SettingNameException} all extend the common base |
---|
948 | exception @code{SettingException}, which provides the following method: |
---|
949 | |
---|
950 | @deftypemethod SettingException {const char *} getPath () |
---|
951 | |
---|
952 | Returns the path to the setting associated with the exception, or |
---|
953 | @code{NULL} if there is no applicable path. |
---|
954 | |
---|
955 | @end deftypemethod |
---|
956 | |
---|
957 | The remainder of this chapter describes the methods for manipulating |
---|
958 | configurations and configuration settings. |
---|
959 | |
---|
960 | @deftypemethod Config {} Config () |
---|
961 | @deftypemethodx Config {} ~Config () |
---|
962 | |
---|
963 | These methods create and destroy @code{Config} objects. |
---|
964 | |
---|
965 | @end deftypemethod |
---|
966 | |
---|
967 | @deftypemethod Config void read (@w{FILE * @var{stream}}) |
---|
968 | @deftypemethodx Config void write (@w{FILE * @var{stream}}) |
---|
969 | |
---|
970 | The @code{read()} method reads and parses a configuration from the given |
---|
971 | @var{stream}. A @code{ParseException} is thrown if a parse error occurs. |
---|
972 | |
---|
973 | The @code{write()} method writes the configuration to the given @var{stream}. |
---|
974 | |
---|
975 | @end deftypemethod |
---|
976 | |
---|
977 | @deftypemethod Config void readFile (@w{const char * @var{filename}}) |
---|
978 | @deftypemethodx Config void writeFile (@w{const char * @var{filename}}) |
---|
979 | |
---|
980 | The @code{readFile()} method reads and parses a configuration from the file |
---|
981 | named @var{filename}. A @code{ParseException} is thrown if a parse error occurs. A |
---|
982 | @code{FileIOException} is thrown if the file cannot be read. |
---|
983 | |
---|
984 | The @code{writeFile()} method writes the configuration to the file |
---|
985 | named @var{filename}. A @code{FileIOException} is thrown if the file cannot |
---|
986 | be written. |
---|
987 | |
---|
988 | @end deftypemethod |
---|
989 | |
---|
990 | @deftypemethod ParseException {const char *} getError () |
---|
991 | @deftypemethodx ParseException int getLine () |
---|
992 | |
---|
993 | If a call to @code{readFile()} or @code{read()} resulted in a |
---|
994 | @code{ParseException}, these methods can be called on the exception |
---|
995 | object to obtain the text and line number of the parse error. Storage |
---|
996 | for the string returned by @code{getError()} is managed by the |
---|
997 | library; the string must not be freed by the caller. |
---|
998 | |
---|
999 | @end deftypemethod |
---|
1000 | |
---|
1001 | @deftypemethod Config void setAutoConvert (bool @var{flag}) |
---|
1002 | @deftypemethodx Config bool getAutoConvert () |
---|
1003 | |
---|
1004 | @code{setAutoConvert()} enables number auto-conversion for the |
---|
1005 | configuration if @var{flag} is @code{true}, and disables it |
---|
1006 | otherwise. When this feature is enabled, an attempt to assign a |
---|
1007 | floating point setting to an integer (or vice versa), or |
---|
1008 | assign an integer to a floating point setting (or vice versa) will |
---|
1009 | cause the library to silently perform the necessary conversion |
---|
1010 | (possibly leading to loss of data), rather than throwing a |
---|
1011 | @code{SettingTypeException}. By default this feature is disabled. |
---|
1012 | |
---|
1013 | @code{getAutoConvert()} returns @code{true} if number auto-conversion |
---|
1014 | is currently enabled for the configuration; otherwise it returns |
---|
1015 | @code{false}. |
---|
1016 | |
---|
1017 | @end deftypemethod |
---|
1018 | |
---|
1019 | @deftypemethod Config {Setting &} getRoot () |
---|
1020 | |
---|
1021 | This method returns the root setting for the configuration, which is a group. |
---|
1022 | |
---|
1023 | @end deftypemethod |
---|
1024 | |
---|
1025 | @deftypemethod Config {Setting &} lookup (@w{const std::string &@var{path}}) |
---|
1026 | @deftypemethodx Config {Setting &} lookup (@w{const char * @var{path}}) |
---|
1027 | |
---|
1028 | These methods locate the setting specified by the path @var{path}. If |
---|
1029 | the requested setting is not found, a @code{SettingNotFoundException} is |
---|
1030 | thrown. |
---|
1031 | |
---|
1032 | @end deftypemethod |
---|
1033 | @deftypemethod Config bool exists (@w{const std::string &@var{path}}) |
---|
1034 | @deftypemethodx Config bool exists (@w{const char *@var{path}}) |
---|
1035 | |
---|
1036 | These methods test if a setting with the given @var{path} exists in |
---|
1037 | the configuration. They return @code{true} if the setting exists, and |
---|
1038 | @var{false} otherwise. These methods do not throw exceptions. |
---|
1039 | |
---|
1040 | @end deftypemethod |
---|
1041 | |
---|
1042 | @deftypemethod Config bool lookupValue (@w{const char *@var{path}}, @w{bool &@var{value}}) |
---|
1043 | @deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{bool &@var{value}}) |
---|
1044 | |
---|
1045 | @deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{int &@var{value}}) |
---|
1046 | @deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{int &@var{value}}) |
---|
1047 | |
---|
1048 | @deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{unsigned int &@var{value}}) |
---|
1049 | @deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{unsigned int &@var{value}}) |
---|
1050 | |
---|
1051 | @deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{long &@var{value}}) |
---|
1052 | @deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{long &@var{value}}) |
---|
1053 | |
---|
1054 | @deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{long long &@var{value}}) |
---|
1055 | @deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{long long &@var{value}}) |
---|
1056 | |
---|
1057 | @deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{unsigned long &@var{value}}) |
---|
1058 | @deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{unsigned long &@var{value}}) |
---|
1059 | |
---|
1060 | @deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{float &@var{value}}) |
---|
1061 | @deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{float &@var{value}}) |
---|
1062 | |
---|
1063 | @deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{double &@var{value}}) |
---|
1064 | @deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{double &@var{value}}) |
---|
1065 | |
---|
1066 | @deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{const char *&@var{value}}) |
---|
1067 | @deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{const char *&@var{value}}) |
---|
1068 | |
---|
1069 | @deftypemethodx Config bool lookupValue (@w{const char *@var{path}}, @w{std::string &@var{value}}) |
---|
1070 | @deftypemethodx Config bool lookupValue (@w{const std::string &@var{path}}, @w{std::string &@var{value}}) |
---|
1071 | |
---|
1072 | These are convenience methods for looking up the value of a setting |
---|
1073 | with the given @var{path}. If the setting is found and is of an |
---|
1074 | appropriate type, the value is stored in @var{value} and the method |
---|
1075 | returns @code{true}. Otherwise, @var{value} is left unmodified and the |
---|
1076 | method returns @var{false}. These methods do not throw exceptions. |
---|
1077 | |
---|
1078 | Storage for @w{@i{const char *}} values is managed by the library and |
---|
1079 | released automatically when the setting is destroyed or when its value |
---|
1080 | is changed; the string must not be freed by the caller. For safety and |
---|
1081 | convenience, always assigning string values to a @code{std::string} is |
---|
1082 | suggested. |
---|
1083 | |
---|
1084 | Since these methods have boolean return values and do not throw |
---|
1085 | exceptions, they can be used within boolean logic expressions. The following |
---|
1086 | example presents a concise way to look up three values at once and |
---|
1087 | perform error handling if any of them are not found or are of the |
---|
1088 | wrong type: |
---|
1089 | |
---|
1090 | @sp 1 |
---|
1091 | @cartouche |
---|
1092 | @example |
---|
1093 | int var1; |
---|
1094 | double var2; |
---|
1095 | const char *var3; |
---|
1096 | |
---|
1097 | if(config.lookupValue("values.var1", var1) |
---|
1098 | && config.lookupValue("values.var2", var2) |
---|
1099 | && config.lookupValue("values.var3", var3)) |
---|
1100 | @{ |
---|
1101 | // use var1, var2, var3 |
---|
1102 | @} |
---|
1103 | else |
---|
1104 | @{ |
---|
1105 | // error handling here |
---|
1106 | @} |
---|
1107 | @end example |
---|
1108 | @end cartouche |
---|
1109 | |
---|
1110 | This approach also takes advantage of the short-circuit evaluation rules |
---|
1111 | of C++, i.e., if the first lookup fails (returning @code{false}), the |
---|
1112 | remaining lookups are skipped entirely. |
---|
1113 | |
---|
1114 | @end deftypemethod |
---|
1115 | @page |
---|
1116 | @deftypemethod Setting {} {operator bool()} |
---|
1117 | @deftypemethodx Setting {} {operator int()} |
---|
1118 | @deftypemethodx Setting {} {operator unsigned int()} |
---|
1119 | @deftypemethodx Setting {} {operator long()} |
---|
1120 | @deftypemethodx Setting {} {operator unsigned long()} |
---|
1121 | @deftypemethodx Setting {} {operator long long()} |
---|
1122 | @deftypemethodx Setting {} {operator unsigned long long()} |
---|
1123 | @deftypemethodx Setting {} {operator float()} |
---|
1124 | @deftypemethodx Setting {} {operator double()} |
---|
1125 | @deftypemethodx Setting {} {operator const char *()} |
---|
1126 | @deftypemethodx Setting {} {operator std::string()} |
---|
1127 | |
---|
1128 | These cast operators allow a @code{Setting} object to be assigned to a |
---|
1129 | variable of type @i{bool} if it is of type @code{TypeBoolean}; |
---|
1130 | @i{int}, @i{unsigned int}, @i{long}, or @i{unsigned long} if it is of |
---|
1131 | type @code{TypeInt}; @code{long long} or @code{unsigned long long} if |
---|
1132 | it is of type @code{TypeInt64}, @i{float} or @i{double} if it is of type |
---|
1133 | @code{TypeFloat}; or @w{@i{const char *}} or @i{std::string} if it is |
---|
1134 | of type @code{TypeString}. |
---|
1135 | |
---|
1136 | Storage for @w{@i{const char *}} return values is managed by the |
---|
1137 | library and released automatically when the setting is destroyed or |
---|
1138 | when its value is changed; the string must not be freed by the |
---|
1139 | caller. For safety and convenience, always assigning string return |
---|
1140 | values to a @code{std::string} is suggested. |
---|
1141 | |
---|
1142 | The following examples demonstrate this usage: |
---|
1143 | |
---|
1144 | @cartouche |
---|
1145 | @example |
---|
1146 | long width = config.lookup("application.window.size.w"); |
---|
1147 | |
---|
1148 | bool splashScreen = config.lookup("application.splash_screen"); |
---|
1149 | |
---|
1150 | std::string title = config.lookup("application.window.title"); |
---|
1151 | @end example |
---|
1152 | @end cartouche |
---|
1153 | |
---|
1154 | Note that certain conversions can lead to loss of precision or |
---|
1155 | clipping of values, e.g., assigning a negative value to an @i{unsigned |
---|
1156 | int} (in which case the value will be treated as 0), or a |
---|
1157 | double-precision value to a @i{float}. The library does not treat |
---|
1158 | these lossy conversions as errors. |
---|
1159 | |
---|
1160 | Perhaps surprisingly, the following code in particular will cause a |
---|
1161 | compiler error: |
---|
1162 | |
---|
1163 | @cartouche |
---|
1164 | @example |
---|
1165 | std::string title; |
---|
1166 | . |
---|
1167 | . |
---|
1168 | . |
---|
1169 | title = config.lookup("application.window.title"); |
---|
1170 | @end example |
---|
1171 | @end cartouche |
---|
1172 | |
---|
1173 | This is because the assignment operator of @code{std::string} is being |
---|
1174 | invoked with a @code{Setting &} as an argument. The compiler is unable |
---|
1175 | to make an implicit conversion because both the @code{const char *} |
---|
1176 | and the @code{std::string} cast operators of @code{Setting} are |
---|
1177 | equally appropriate. This is not a bug in @i{libconfig}; providing |
---|
1178 | only the @code{const char *} cast operator would resolve this |
---|
1179 | particular ambiguity, but would cause assignments to |
---|
1180 | @code{std::string} like the one in the previous example to produce a |
---|
1181 | compiler error. (To understand why, see section 11.4.1 of @i{The C++ |
---|
1182 | Programming Language}.) |
---|
1183 | |
---|
1184 | The solution to this problem is to use an explicit conversion that |
---|
1185 | avoids the construction of an intermediate @code{std::string} object, |
---|
1186 | as follows: |
---|
1187 | |
---|
1188 | @cartouche |
---|
1189 | @example |
---|
1190 | std::string title; |
---|
1191 | . |
---|
1192 | . |
---|
1193 | . |
---|
1194 | title = (const char *)config.lookup("application.window.title"); |
---|
1195 | @end example |
---|
1196 | @end cartouche |
---|
1197 | |
---|
1198 | If the assignment is invalid due to a type mismatch, a |
---|
1199 | @code{SettingTypeException} is thrown. |
---|
1200 | |
---|
1201 | @end deftypemethod |
---|
1202 | |
---|
1203 | @deftypemethod Setting {Setting &} operator= (@w{bool @var{value}}) |
---|
1204 | @deftypemethodx Setting {Setting &} operator= (@w{int @var{value}}) |
---|
1205 | @deftypemethodx Setting {Setting &} operator= (@w{long @var{value}}) |
---|
1206 | @deftypemethodx Setting {Setting &} operator= (@w{const long long &@var{value}}) |
---|
1207 | @deftypemethodx Setting {Setting &} operator= (@w{float @var{value}}) |
---|
1208 | @deftypemethodx Setting {Setting &} operator= (@w{const double &@var{value}}) |
---|
1209 | @deftypemethodx Setting {Setting &} operator= (@w{const char *@var{value}}) |
---|
1210 | @deftypemethodx Setting {Setting &} operator= (@w{const std::string &@var{value}}) |
---|
1211 | |
---|
1212 | These assignment operators allow values of type @i{bool}, @i{int}, |
---|
1213 | @i{long}, @i{long long}, @i{float}, @i{double}, @i{const char *}, and |
---|
1214 | @i{std::string} to be assigned to a setting. In the case of strings, |
---|
1215 | the library makes a copy of the passed string @var{value}, so it may |
---|
1216 | be subsequently freed or modified by the caller without affecting the |
---|
1217 | value of the setting. |
---|
1218 | |
---|
1219 | If the assignment is invalid due to a type mismatch, a |
---|
1220 | @code{SettingTypeException} is thrown. |
---|
1221 | |
---|
1222 | @end deftypemethod |
---|
1223 | |
---|
1224 | @deftypemethod Setting {Setting &} {operator[]} (@w{int @var{idx}}) |
---|
1225 | @deftypemethodx Setting {Setting &} {operator[]} (@w{const std::string &@var{name}}) |
---|
1226 | @deftypemethodx Setting {Setting &} {operator[]} (@w{const char *@var{name}}) |
---|
1227 | |
---|
1228 | A @code{Setting} object may be subscripted with an integer index |
---|
1229 | @var{idx} if it is an array or list, or with either a string |
---|
1230 | @var{name} or an integer index @var{idx} if it is a group. For example, |
---|
1231 | the following code would produce the string @samp{Last Name} when |
---|
1232 | applied to the example configuration in @ref{Configuration Files}. |
---|
1233 | |
---|
1234 | @cartouche |
---|
1235 | @example |
---|
1236 | Setting& setting = config.lookup("application.misc"); |
---|
1237 | const char *s = setting["columns"][0]; |
---|
1238 | @end example |
---|
1239 | @end cartouche |
---|
1240 | |
---|
1241 | If the setting is not an array, list, or group, a |
---|
1242 | @code{SettingTypeException} is thrown. If the subscript (@var{idx} |
---|
1243 | or @var{name}) does not refer to a valid element, a |
---|
1244 | @code{SettingNotFoundException} is thrown. |
---|
1245 | |
---|
1246 | Iterating over a group's child settings with an integer index will |
---|
1247 | return the settings in the same order that they appear in the |
---|
1248 | configuration. |
---|
1249 | |
---|
1250 | @end deftypemethod |
---|
1251 | |
---|
1252 | @deftypemethod Setting bool lookupValue (@w{const char *@var{name}}, @w{bool &@var{value}}) |
---|
1253 | @deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{bool &@var{value}}) |
---|
1254 | |
---|
1255 | @deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{int &@var{value}}) |
---|
1256 | @deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{int &@var{value}}) |
---|
1257 | |
---|
1258 | @deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{unsigned int &@var{value}}) |
---|
1259 | @deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{unsigned int &@var{value}}) |
---|
1260 | |
---|
1261 | @deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{long long &@var{value}}) |
---|
1262 | @deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{long long &@var{value}}) |
---|
1263 | |
---|
1264 | @deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{unsigned long long &@var{value}}) |
---|
1265 | @deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{unsigned long long &@var{value}}) |
---|
1266 | |
---|
1267 | @deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{long &@var{value}}) |
---|
1268 | @deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{long &@var{value}}) |
---|
1269 | |
---|
1270 | @deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{unsigned long &@var{value}}) |
---|
1271 | @deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{unsigned long &@var{value}}) |
---|
1272 | |
---|
1273 | @deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{float &@var{value}}) |
---|
1274 | @deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{float &@var{value}}) |
---|
1275 | |
---|
1276 | @deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{double &@var{value}}) |
---|
1277 | @deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{double &@var{value}}) |
---|
1278 | |
---|
1279 | @deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{const char *&@var{value}}) |
---|
1280 | @deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{const char *&@var{value}}) |
---|
1281 | |
---|
1282 | @deftypemethodx Setting bool lookupValue (@w{const char *@var{name}}, @w{std::string &@var{value}}) |
---|
1283 | @deftypemethodx Setting bool lookupValue (@w{const std::string &@var{name}}, @w{std::string &@var{value}}) |
---|
1284 | |
---|
1285 | These are convenience methods for looking up the value of a child setting |
---|
1286 | with the given @var{name}. If the setting is found and is of an |
---|
1287 | appropriate type, the value is stored in @var{value} and the method |
---|
1288 | returns @code{true}. Otherwise, @var{value} is left unmodified and the |
---|
1289 | method returns @var{false}. These methods do not throw exceptions. |
---|
1290 | |
---|
1291 | Storage for @w{@i{const char *}} values is managed by the library and |
---|
1292 | released automatically when the setting is destroyed or when its value |
---|
1293 | is changed; the string must not be freed by the caller. For safety and |
---|
1294 | convenience, always assigning string values to a @code{std::string} is |
---|
1295 | suggested. |
---|
1296 | |
---|
1297 | Since these methods have boolean return values and do not throw |
---|
1298 | exceptions, they can be used within boolean logic expressions. The following |
---|
1299 | example presents a concise way to look up three values at once and |
---|
1300 | perform error handling if any of them are not found or are of the |
---|
1301 | wrong type: |
---|
1302 | |
---|
1303 | @sp 1 |
---|
1304 | @cartouche |
---|
1305 | @example |
---|
1306 | int var1; |
---|
1307 | double var2; |
---|
1308 | const char *var3; |
---|
1309 | |
---|
1310 | if(setting.lookupValue("var1", var1) |
---|
1311 | && setting.lookupValue("var2", var2) |
---|
1312 | && setting.lookupValue("var3", var3)) |
---|
1313 | @{ |
---|
1314 | // use var1, var2, var3 |
---|
1315 | @} |
---|
1316 | else |
---|
1317 | @{ |
---|
1318 | // error handling here |
---|
1319 | @} |
---|
1320 | @end example |
---|
1321 | @end cartouche |
---|
1322 | |
---|
1323 | This approach also takes advantage of the short-circuit evaluation |
---|
1324 | rules of C++, e.g., if the first lookup fails (returning @code{false}), the |
---|
1325 | remaining lookups are skipped entirely. |
---|
1326 | |
---|
1327 | @end deftypemethod |
---|
1328 | |
---|
1329 | @deftypemethod Setting {Setting &} add (@w{const std::string &@var{name}}, @w{Setting::Type @var{type}}) |
---|
1330 | @deftypemethodx Setting {Setting &} add (@w{const char *@var{name}}, @w{Setting::Type @var{type}}) |
---|
1331 | |
---|
1332 | These methods add a new child setting with the given @var{name} and |
---|
1333 | @var{type} to the setting, which must be a group. They return a |
---|
1334 | reference to the new setting. If the setting already has a child |
---|
1335 | setting with the given name, or if the name is invalid, a |
---|
1336 | @code{SettingNameException} is thrown. If the setting is not a group, |
---|
1337 | a @code{SettingTypeException} is thrown. |
---|
1338 | |
---|
1339 | Once a setting has been created, neither its name nor type can be |
---|
1340 | changed. |
---|
1341 | |
---|
1342 | @end deftypemethod |
---|
1343 | |
---|
1344 | @deftypemethod Setting {Setting &} add (@w{Setting::Type @var{type}}) |
---|
1345 | |
---|
1346 | This method adds a new element to the setting, which must be of type |
---|
1347 | @code{TypeArray} or @code{TypeList}. If the setting is an array which |
---|
1348 | currently has zero elements, the @var{type} parameter (which must be |
---|
1349 | @code{TypeInt}, @code{TypeInt64}, @code{TypeFloat}, @code{TypeBool}, |
---|
1350 | or @code{TypeString}) determines the type for the array; otherwise it |
---|
1351 | must match the type of the existing elements in the array. |
---|
1352 | |
---|
1353 | The method returns the new setting on success. If @var{type} is a |
---|
1354 | scalar type, the new setting will have a default value of 0, 0.0, |
---|
1355 | @code{false}, or @code{NULL}, depending on the type. |
---|
1356 | |
---|
1357 | The method throws a @code{SettingTypeException} if the setting is not |
---|
1358 | an array or list, or if @var{type} is invalid. |
---|
1359 | |
---|
1360 | @end deftypemethod |
---|
1361 | |
---|
1362 | @deftypemethod Setting void remove (@w{const std::string &@var{name}}) |
---|
1363 | @deftypemethodx Setting void remove (@w{const char *@var{name}}) |
---|
1364 | |
---|
1365 | These methods remove the child setting with the given @var{name} from |
---|
1366 | the setting, which must be a group. Any child settings of the removed |
---|
1367 | setting are recursively destroyed as well. |
---|
1368 | |
---|
1369 | If the setting is not a group, a @code{SettingTypeException} is |
---|
1370 | thrown. If the setting does not have a child setting with the given |
---|
1371 | name, a @code{SettingNotFoundException} is thrown. |
---|
1372 | |
---|
1373 | @end deftypemethod |
---|
1374 | |
---|
1375 | @deftypemethod Setting void remove (@w{unsigned int @var{idx}}) |
---|
1376 | |
---|
1377 | This method removes the child setting at the given index @var{idx} from |
---|
1378 | the setting, which must be a group, list, or array. Any child settings |
---|
1379 | of the removed setting are recursively destroyed as well. |
---|
1380 | |
---|
1381 | If the setting is not a group, list, or array, a |
---|
1382 | @code{SettingTypeException} is thrown. If @var{idx} is out of range, |
---|
1383 | a @code{SettingNotFoundException} is thrown. |
---|
1384 | |
---|
1385 | @end deftypemethod |
---|
1386 | |
---|
1387 | @deftypemethod Setting {const char *} getName () |
---|
1388 | |
---|
1389 | This method returns the name of the setting, or @code{NULL} if the |
---|
1390 | setting has no name. Storage for the returned string is managed by the |
---|
1391 | library and released automatically when the setting is destroyed; the |
---|
1392 | string must not be freed by the caller. For safety and convenience, |
---|
1393 | consider assigning the return value to a @code{std::string}. |
---|
1394 | |
---|
1395 | @end deftypemethod |
---|
1396 | |
---|
1397 | @deftypemethod Setting {std::string} getPath () |
---|
1398 | |
---|
1399 | This method returns the complete dot-separated path to the |
---|
1400 | setting. Settings which do not have a name (list and array elements) |
---|
1401 | are represented by their index in square brackets. |
---|
1402 | |
---|
1403 | @end deftypemethod |
---|
1404 | |
---|
1405 | @deftypemethod Setting {Setting &} getParent () |
---|
1406 | |
---|
1407 | This method returns the parent setting of the setting. If the setting |
---|
1408 | is the root setting, a @code{SettingNotFoundException} is thrown. |
---|
1409 | |
---|
1410 | @end deftypemethod |
---|
1411 | |
---|
1412 | @deftypemethod Setting bool isRoot () |
---|
1413 | |
---|
1414 | This method returns @i{true} if the setting is the root setting, and |
---|
1415 | @i{false} otherwise. |
---|
1416 | |
---|
1417 | @end deftypemethod |
---|
1418 | |
---|
1419 | @deftypemethod Setting int getIndex () |
---|
1420 | |
---|
1421 | This method returns the index of the setting within its parent |
---|
1422 | setting. When applied to the root setting, this method returns -1. |
---|
1423 | |
---|
1424 | @end deftypemethod |
---|
1425 | |
---|
1426 | @deftypemethod Setting Setting::Type getType () |
---|
1427 | |
---|
1428 | @tindex Setting::Type |
---|
1429 | This method returns the type of the setting. The |
---|
1430 | @code{Setting::Type} enumeration consists of the following constants: |
---|
1431 | @code{TypeInt}, @code{TypeInt64}, @code{TypeFloat}, @code{TypeString}, |
---|
1432 | @code{TypeBoolean}, @code{TypeArray}, @code{TypeList}, or |
---|
1433 | @code{TypeGroup}. |
---|
1434 | |
---|
1435 | @end deftypemethod |
---|
1436 | |
---|
1437 | @deftypemethod Setting Setting::Format getFormat () |
---|
1438 | @deftypemethodx Setting void setFormat (@w{Setting::Format @var{format}}) |
---|
1439 | |
---|
1440 | These methods get and set the external format for the setting. |
---|
1441 | |
---|
1442 | @tindex Setting::Format |
---|
1443 | The @var{Setting::Format} enumeration consists of the following |
---|
1444 | constants: @code{FormatDefault}, @code{FormatHex}. All settings |
---|
1445 | support the @code{FormatDefault} format. The @code{FormatHex} format |
---|
1446 | specifies hexadecimal formatting for integer values, and hence only |
---|
1447 | applies to settings of type @code{TypeInt} and @code{TypeInt64}. If |
---|
1448 | @var{format} is invalid for the given setting, it is ignored. |
---|
1449 | |
---|
1450 | @end deftypemethod |
---|
1451 | |
---|
1452 | @deftypemethod Setting bool exists (@w{const std::string &@var{name}}) |
---|
1453 | @deftypemethodx Setting bool exists (@w{const char *@var{name}}) |
---|
1454 | |
---|
1455 | These methods test if the setting has a child setting with the given |
---|
1456 | @var{name}. They return @code{true} if the setting exists, and |
---|
1457 | @var{false} otherwise. These methods do not throw exceptions. |
---|
1458 | |
---|
1459 | @end deftypemethod |
---|
1460 | |
---|
1461 | @deftypemethod Setting int getLength () |
---|
1462 | |
---|
1463 | This method returns the number of settings in a group, or the number of |
---|
1464 | elements in a list or array. For other types of settings, it returns |
---|
1465 | 0. |
---|
1466 | |
---|
1467 | @end deftypemethod |
---|
1468 | |
---|
1469 | @deftypemethod Setting bool isGroup () |
---|
1470 | @deftypemethodx Setting bool isArray () |
---|
1471 | @deftypemethodx Setting bool isList () |
---|
1472 | |
---|
1473 | These convenience methods test if a setting is of a given type. |
---|
1474 | |
---|
1475 | @end deftypemethod |
---|
1476 | |
---|
1477 | @deftypemethod Setting bool isAggregate () |
---|
1478 | @deftypemethodx Setting bool isScalar () |
---|
1479 | @deftypemethodx Setting bool isNumber () |
---|
1480 | |
---|
1481 | These convenience methods test if a setting is of an aggregate type (a |
---|
1482 | group, array, or list), of a scalar type (integer, 64-bit integer, |
---|
1483 | floating point, boolean, or string), and of a number (integer or |
---|
1484 | floating point), respectively. |
---|
1485 | |
---|
1486 | @end deftypemethod |
---|
1487 | |
---|
1488 | @deftypemethod Setting {unsigned int} getSourceLine () |
---|
1489 | |
---|
1490 | This method returns the line number of the configuration file or |
---|
1491 | stream at which the setting was parsed. This information is useful for |
---|
1492 | reporting application-level errors. If the setting was not read from a |
---|
1493 | file or stream, or if the line number is otherwise unavailable, the |
---|
1494 | method returns 0. |
---|
1495 | |
---|
1496 | @end deftypemethod |
---|
1497 | |
---|
1498 | @node Configuration File Grammar, License, The C++ API, Top |
---|
1499 | @comment node-name, next, previous, up |
---|
1500 | @chapter Configuration File Grammar |
---|
1501 | |
---|
1502 | Below is the BNF grammar for configuration files. Comments are not part |
---|
1503 | of the grammar, and hence are not included here. |
---|
1504 | |
---|
1505 | @sp 1 |
---|
1506 | @example |
---|
1507 | configuration = setting-list | empty |
---|
1508 | |
---|
1509 | empty = |
---|
1510 | |
---|
1511 | setting-list = setting | setting-list setting |
---|
1512 | |
---|
1513 | setting = name (":" | "=") value ";" |
---|
1514 | |
---|
1515 | value = scalar-value | array | list | group |
---|
1516 | |
---|
1517 | value-list = value | value-list "," value |
---|
1518 | |
---|
1519 | scalar-value = boolean | integer | integer64 | hex | hex64 | float |
---|
1520 | | string |
---|
1521 | |
---|
1522 | scalar-value-list = scalar-value | scalar-value-list "," scalar-value |
---|
1523 | |
---|
1524 | array = "[" (scalar-value-list | empty) "]" |
---|
1525 | |
---|
1526 | list = "(" (value-list | empty) ")" |
---|
1527 | |
---|
1528 | group = "@{" (setting-list | empty) "@}" |
---|
1529 | @end example |
---|
1530 | |
---|
1531 | @sp 2 |
---|
1532 | Terminals are defined below as regular expressions: |
---|
1533 | @sp 1 |
---|
1534 | |
---|
1535 | @multitable @columnfractions .2 .8 |
---|
1536 | @item @code{boolean} @tab |
---|
1537 | @code{([Tt][Rr][Uu][Ee])|([Ff][Aa][Ll][Ss][Ee])} |
---|
1538 | @item @code{string} @tab |
---|
1539 | @code{\"([^\"\\]|\\.)*\"} |
---|
1540 | @item @code{name} @tab |
---|
1541 | @code{[A-Za-z\*][-A-Za-z0-9_\*]*} |
---|
1542 | @item @code{integer} @tab |
---|
1543 | @code{[-+]?[0-9]+} |
---|
1544 | @item @code{integer64} @tab |
---|
1545 | @code{[-+]?[0-9]+L(L)?} |
---|
1546 | @item @code{hex} @tab |
---|
1547 | @code{0[Xx][0-9A-Fa-f]+} |
---|
1548 | @item @code{hex64} @tab |
---|
1549 | @code{0[Xx][0-9A-Fa-f]+L(L)?} |
---|
1550 | @item @code{float} @tab |
---|
1551 | @code{([-+]?([0-9]*)?\.[0-9]*([eE][-+]?[0-9]+)?)|([-+]([0-9]+)(\.[0-9]*)?[eE][-+]?[0-9]+)} |
---|
1552 | @end multitable |
---|
1553 | |
---|
1554 | @node License, Function Index, Configuration File Grammar, Top |
---|
1555 | @comment node-name, next, previous, up |
---|
1556 | @appendix License |
---|
1557 | |
---|
1558 | @include LGPL.texi |
---|
1559 | |
---|
1560 | @node Function Index, Type Index, License, Top |
---|
1561 | @comment node-name, next, previous, up |
---|
1562 | @unnumbered Function Index |
---|
1563 | |
---|
1564 | @printindex fn |
---|
1565 | |
---|
1566 | @node Type Index, Concept Index, Function Index, Top |
---|
1567 | @comment node-name, next, previous, up |
---|
1568 | @unnumbered Type Index |
---|
1569 | |
---|
1570 | @printindex tp |
---|
1571 | |
---|
1572 | @node Concept Index, , Type Index, Top |
---|
1573 | @comment node-name, next, previous, up |
---|
1574 | @unnumbered Concept Index |
---|
1575 | |
---|
1576 | @printindex cp |
---|
1577 | |
---|
1578 | @bye |
---|