z0b's realm


ncfg ("new cfg" if you want) is a small configuration file reading and writing library. It fully supports UTF-8 and can be compiled with practically any compiler that supports C99. It is small (around 15-20 KiB compiled, can be made even smaller by removing unused functions) and reasonably fast (in one testcase, it parsed about 5.6 MB/s on Windows, and 10.3 MB/s on Linux). The file format is uses is simple and has only a few rules, so you can bend and twist it to suit your needs.

Both C and C++ style -comments are supported, and C -style block comments can be nested. Internally all data is held in a tree-like structure you can modify in every imaginable way. The API is not big at the moment, but it already contains several useful functions.

ncfg is almost feature-complete and can be used in production. It has seen action in several of my own projects. It works and has proven itself useful. The library is documented, but all documentation can always be improved. You can download ncfg and test it yourself to see if it fits in your needs.

Currently, its main features are:

  • Very small and fast
  • Full Unicode support (everything is UTF-8 internally).
  • Cross-platform C99 code that should compile warning-free. Tested with:
    • GCC 4.7.x, 4.8.x, 4.9.x, 5.1 and 6.x (MinGW under Windows 7, GCC under Debian and Ubuntu)
    • Clang 3.x (Debian)
    • Some others (PellesC, Tiny C compiler)
  • The I/O can be customized, so you can load from everywhere you want and save to everywhere you want.
  • Licensed under the zlib/libpng license, so you can link it with practically anything
  • The library has been built mostly by following the YAGNI (You Ain't Gonna Need It) principle. Features are added when needed, not earlier. This keeps things small.

The library cleanly passes Valgrind, plus Clang's static analyzer finds nothing to say about it. GCC 5.1 under Debian reports zero errors and warnings when compiled with -Wall -Wextra -Wpedantic. This does not mean there are no bugs, though.

New in version 0.9.9

  • Improved UTF-8 parsing (noncharacters are handled better)
  • Added parent argument to ncfg_item_new(), ncfg_item_from_int() and ncfg_item_from_float().
  • Documentation improvements
  • Large bump in version number to reflect how close I think ncfg is to "done"

The file format

ncfg uses very simple file format to store everything. It is very flexible and can be abused almost endlessly, if needed.

Everything is stored in items. An item has a name (that is not necessarily unique) and zero or more assigned values (think key-value pairs, but with multiple values per key). The values are just strings. Every item can have any number of child items. This allows you to group items into hierarchies. Values (and item names) that must contain whitespace and/or special character can be escaped and quoted. Both // and /* ... */ work for single-line and multi-line comments, respectively, and they can be nested (unlike in C/C++).

And that pretty much is it. Simple, yet effective.

At the moment there is no preprocessor (or macros) or file inclusion system (but you can merge multiple files by simply loading them in the same instance), but these might be added if needed.

Here's a quick look at what the format looks like:

// a simple message
message "Hello world!";

// more than one value
path_color 115 37 61;

// sometimes you don't need any values at all

// Nested items. Note that items can have both values and child items, at the same time.
vfs {
    file "data/base.zip" {
        mount_point /;

/* disabled in the release version
    directory "development" {
        mount_point /dev;

// copy-pasted from some random Juniper router configuration file
routing-options {
    static {
        route next-hop;

// yes, you can abuse the syntax, but don't overdo it
// (this is just an example, ncfg will happily load and parse this for you,
// but YOU have to write the code that actually interprets this horror)
set a 1 + 2;

if a < 3 {
    set message "A is less than three";
} else if a > 3 {
    set message "A is bigger than three";
} else {
    set message "A is exactly three.";

// and so on, I think you understand the syntax now


The ZIP contains the source files, a simple loader/prettyprinter example, memory I/O example, and an HTML file that vaguely resembles a manual.

ncfg v0.9.9
Size66 KiB (67101 bytes)
ReleasedFeb 23. 2017