LC_C_API

The theConfig API. More...

Collaboration diagram for LC_C_API:

Topics
	LcConfig_C_API
	LcConfig PACKAGE - the package is the toplevel structure of the liblcconfig …
	LcConfigC_C_API
	LcConfigC - the class known as lccfg or Config define the main-configuration-handle …
	LcSettingC_C_API
	LcSettingC - the class known as lccfs or Setting define a single config-setting …
	LcRuntimeC_C_API
	LcRuntimeC - access the runtime …
	libconfig
	original-header-file from the libconfig project …

Detailed Description

The theConfig API.

License

...

Introduction

liblcconfig is a library for reading, manipulating, and writing structured configuration files. The library features a fully reentrant parser and includes bindings for both the C and C++ programming languages.

The library runs on modern POSIX-compilant systems, such as Linux, Solaris, and Mac OS X (Darwin), as well as on Microsoft Windows 2000/XP and later (with either Microsoft Visual Studio 2005 or later, or the GNU toolchain via the MinGW environment).

Why Another Configuration File Library?

There are several open-source configuration file libraries available as of this writing. This library was written because each of those libraries falls short in one or more ways. The main features of libconfig that set it apart from the other libraries are:

• A fully reentrant parser. Independent configurations can be parsed in concurrent threads at the same time.

• Both C and C++ bindings, as well as hooks to allow for the creation of wrappers in other languages.

• A simple, structured configuration file format that is more readable and compact than XML and more flexible than the obsolete but prevalent Windows ''INI'' file format.

• A low-footprint implementation (just 37K for the C library and 76K for the C++ library) that is suitable for memory-constrained systems.

• Proper documentation.

Multithreading Issues

liblcconfig is fully reentrant; the functions in the library do not make use of global variables and do not maintain state between successive calls. Therefore two independent configurations may be safely manipulated concurrently by two distinct threads.

liblcconfig is not thread-safe. The library is not aware of the presence of threads and knows nothing about the host system's threading model. Therefore, if an instance of a configuration is to be accessed from multiple threads, it must be suitably protected by synchronization mechanisms like read-write locks or mutexes; the standard rules for safe multithreaded access to shared data must be observed.

liblcconfig is not async-safe. Calls should not be made into the library from signal handlers, because some of the C library routines that it uses may not be async-safe.

liblcconfig is not guaranteed to be cancel-safe. Since it is not aware of the host system's threading model, the library does not contain any thread cancellation points. In most cases this will not be an issue for multithreaded programs. However, be aware that some of the routines in the library (namely those that read/write configurations from/to files or streams) perform I/O using C library routines which may potentially block; whether or not these C library routines are cancel-safe depends on the host system.

Internationalization Issues

liblcconfig does not natively support Unicode configuration files, but string values may contain Unicode text encoded in UTF-8; such strings will be treated as ordinary 8-bit ASCII text by the library. It is the responsibility of the calling program to perform the necessary conversions to/from wide (wchar_t) strings using the wide string conversion functions such as mbsrtowcs() and wcsrtombs() or the iconv() function of the libiconv library.

The textual representation of a floating point value varies by locale. However, the libconfig grammar specifies that floating point values are represented using a period ('.') as the radix symbol; this is consistent with the grammar of most programming languages. When a configuration is read in or written out, libconfig temporarily changes the LC_NUMERIC category of the locale of the calling thread to the ''C'' locale to ensure consistent handling of floating point values regardless of the locale(s) in use by the calling program.

Note that the MinGW environment does not (as of this writing) provide functions for changing the locale of the calling thread. Therefore, when using libconfig in that environment, the calling program is responsible for changing the LC_NUMERIC category of the locale to the "C" locale before reading or writing a configuration.

Configuration Files

liblcconfig supports structured, hierarchical configurations. These configurations can be read from and written to files and manipulated in memory.

A configuration consists of a group of settings, which associate names with values. A value can be one of the following:

• A scalar value: integer, 64-bit integer, floating-point number, boolean, or string
• An array, which is a sequence of scalar values, all of which must have the same type
• A group, which is a collection of settings
• A list, which is a sequence of values of any type, including other lists

Consider the following configuration file for a hypothetical GUI application, which illustrates all of the elements of the configuration file grammar.

# Example application configuration file
 
version = "1.0";
 
application:
{
  window:
  {
    title = "My Application";
    size = { w = 640; h = 480; };
    pos = { x = 350; y = 250; };
  };
 
  list = ( ( "abc", 123, true ), 1.234, ( / * an empty list * / ) );
 
  books = ( { title  = "Treasure Island";
              author = "Robert Louis Stevenson";
              price  = 29.95;
              qty    = 5; },
            { title  = "Snow Crash";
              author = "Neal Stephenson";
              price  = 9.99;
              qty    = 8; } );
 
  misc:
  {
    pi = 3.141592654;
    bigint = 9223372036854775807L;
    columns = [ "Last Name", "First Name", "MI" ];
    bitmask = 0x1FC3;   // hex
    umask = 0027;       // octal. Range limited to that of "int"
  };
};

Settings can be uniquely identified within the configuration by a path. The path is a dot-separated sequence of names, beginning at a top-level group and ending at the setting itself. Each name in the path is the name of a setting; if the setting has no name because it is an element in a list or array, an integer index in square brackets can be used as the name.

For example, in our hypothetical configuration file, the path to the x setting is application.window.pos.x; the path to the version setting is simply version; and the path to the title setting of the second book in the books list is application.books.[1].title.

The datatype of a value is determined from the format of the value itself. If the value is enclosed in double quotes, it is treated as a string. If it looks like an integer or floating point number, it is treated as such. If it is one of the values TRUE, true, FALSE, or false (or any other mixed-case version of those tokens, e.g., True or FaLsE), it is treated as a boolean. If it consists of a comma-separated list of values enclosed in square brackets, it is treated as an array. And if it consists of a comma-separated list of values enclosed in parentheses, it is treated as a list. Any value which does not meet any of these criteria is considered invalid and results in a parse error.

All names are case-sensitive. They may consist only of alphanumeric characters, dashes ('-'), underscores ('_'), and asterisks ('*'), and must begin with a letter or asterisk. No other characters are allowed.

In C and C++, integer, 64-bit integer, floating point, and string values are mapped to the native types int, long long, double, and const char *, respectively. The boolean type is mapped to int in C and bool in C++.

The following sections describe the elements of the configuration file grammar in additional detail.

Settings

A setting has the form:

name = value ;

or:

name : value ;

The trailing semicolon is optional. Whitespace is not significant.

The value may be a scalar value, an array, a group, or a list.

Groups

A group has the form:

{ settings ... }

Groups can contain any number of settings, but each setting must have a unique name within the group.

Arrays

An array has the form:

[ value, value ... ]

An array may have zero or more elements, but the elements must all be scalar values of the same type.

The last element in an array may be followed by a comma, which will be ignored.

Lists

A list has the form:

( value, value ... )

A list may have zero or more elements, each of which can be a scalar value, an array, a group, or another list.

The last element in a list may be followed by a comma, which will be ignored.

Integer Values

Integers can be represented in one of two ways: as a series of one or more decimal digits ('0' - '9'), with an optional leading sign character ('+' or '-'); or as a hexadecimal value consisting of the characters '0x' followed by a series of one or more hexadecimal digits ('0' - '9', 'A' - 'F', 'a' - 'f'). Additionally, octal notation integers (that is, those having a leading zero with non-zero value) are also allowed.

64-bit Integer Values

Long long (64-bit) integers are represented identically to integers, except that an 'L' character is appended to indicate a 64-bit value. For example, '0L' indicates a 64-bit integer value 0. As of version 1.5 of the library, the trailing 'L' is optional; if the integer value exceeds the range of a 32-bit integer, it will automatically be interpreted as a 64-bit integer.

The integer and 64-bit integer setting types are interchangeable to the extent that a conversion between the corresponding native types would not result in an overflow or underflow. For example, a long long value can be written to a setting that has an integer type, if that value is within the range of an int. This rule applies to every API function or method that reads a value from or writes a value to a setting: if the type conversion would not result in an overflow or underflow, then the call will succeed, and otherwise it will fail. This behavior was not well-defined prior to version 1.7 of the library.

Floating Point Values

Floating point values consist of a series of one or more digits, one decimal point, an optional leading sign character ('+' or '-'), and an optional exponent. An exponent consists of the letter 'E' or 'e', an optional sign character, and a series of one or more digits.

Boolean Values

Boolean values may have one of the following values: 'true', 'false', or any mixed-case variation thereof.

String Values

String values consist of arbitrary text delimited by double quotes. Literal double quotes can be escaped by preceding them with a backslash: '\"'. The escape sequences '\\', '\f', '\n', '\r', and '\t' are also recognized, and have the usual meaning.

In addition, the '\x' escape sequence is supported; this sequence must be followed by exactly two hexadecimal digits, which represent an 8-bit ASCII value. For example, '\xFF' represents the character with ASCII code 0xFF.

No other escape sequences are currently supported.

Adjacent strings are automatically concatenated, as in C/C++ source code. This is useful for formatting very long strings as sequences of shorter strings. For example, the following constructs are equivalent:

• "The quick brown fox jumped over the lazy dog."

• "The quick brown fox"
" jumped over the lazy dog."

• "The quick" /‌* comment *‌/ " brown fox " // another comment
"jumped over the lazy dog."

Comments

Three types of comments are allowed within a configuration:

• Script-style comments. All text beginning with a '#' character to the end of the line is ignored.

• C-style comments. All text, including line breaks, between a starting '/‌*' sequence and an ending '*‌/' sequence is ignored.

• C++-style comments. All text beginning with a '//' sequence to the end of the line is ignored.

As expected, comment delimiters appearing within quoted strings are treated as literal text.

Comments are ignored when the configuration is read in, so they are not treated as part of the configuration. Therefore if the configuration is written back out to a stream, any comments that were present in the original configuration will be lost.

Include Directives

A configuration file may ''include'' the contents of other files using an include directive. This directive has the effect of inlining the contents of the named file(s) at the point of inclusion.

An include directive must appear on its own line in the input. It has the form:

@include "path"

The interpretation of path depends on the currently registered include function. The default include function prepends the include directory, if any, to path, and then interprets the result as a single, literal file path. The application may supply its own include function which does variable substitution, wildcard expansion, or other transformations, returning a list of zero or more paths to files whose contents should be inlined at the point of inclusion.

Any backslashes or double quotes in the path must be escaped as '\\' and '\"', respectively.

For example, consider the following two configuration files:

# file: quote.cfg
quote = "Criticism may not be agreeable, but it is necessary."
        " It fulfils the same function as pain in the human"
        " body. It calls attention to an unhealthy state of"
        " things.\\n"
        "\\t--Winston Churchill";

# file: test.cfg
info: {
  name = "Winston Churchill";
  @include "quote.cfg"
  country = "UK";
};

The resulting configuration will be equivalent to one in which the contents of the file 'quote.cfg' appeared at the point where the include directive is placed.

Include files may be nested to a maximum of 10 levels; exceeding this limit results in a parse error.

When the path argument to an @include directive is a relative path, then it will be interpreted as being relative to the include directory that has been been set by means of config_set_include_dir. If no include directory has been set, then it will be taken as being relative to the program's current working directory.

Like comments, include directives are not part of the configuration file syntax. They are processed before the configuration itself is parsed. Therefore, they are not preserved when the configuration is written back out to a stream. There is presently no support for programmatically inserting include directives into a configuration.

The C API

This chapter describes the C library API. The type LcConfigC represents a configuration, and the type LcSettingC represents a configuration setting.

The boolean values CONFIG_TRUE and CONFIG_FALSE are macros defined as (1) and (0), respectively.