Introduction

ncfg is a general-purpose configuration file parser/saving library. It is written in plain C99 and should compile warnings and errors free pretty much anywhere, even under Windows (if you use MinGW). At the moment, MSVC cannot compile this, because it lacks C99 support.

ncfg is a low-level library. It isn't the most easiest library to use, but it does its job. It currently implements only the bare minimum things needed and not much else.

Compilation

ncfg has no specific makefile yet. At the moment, it is compiled on the command line like this:

gcc -Wall -s -O2 -o ncfg.o -c ncfg.c -std=c99
ar rs libncfg.a ncfg.o

Install the library by simply copying the files libncfg.a and ncfg.h into appropriate directories.

Compiler support

The following table lists the current compiler support. The code should compile cleanly with maximum warnings.

MSVC users either have to use MinGW GCC or modify the library themselves to make it compile. I won't accept "patches" that makes ncfg compile under MSVC, that would be a downgrade.

Using ncfg

Items and sections

Everything in ncfg is stored in items. Every item has a name (that is not necessarily unique), plus zero or more attached values. Yes, the item does not necessarily need any values, just the name is enough. There is no limit on how many values item can have. The values also have no length limitation. You could create an item named "book" and give it one value that contains a megabyte's worth of text and ncfg would not flinch at it.

You can group items into sections. Every section (except the automatically managed root section) has a parent item, which also gives the section a name. The sections can be nested freely and they can be empty.

Any item can have a child section, even items that have values. The values belong to the item, not to the child section. The next example creates an item match that has one value, *.txt, but it also has a child section. The item action also has a child section, that has one item that has no values:

match "*.txt" {
    action move {
        warn-if-exists;
    }

    directory $(TARGET)/txt;
}

Note that while item names cannot contain the slash, its values can:

path /;

The reason you can't use forward slashes in item names is that it becomes impossible to know which slash is an actual path separator and which slash belongs in the name. You can't use slashes in file names either.

Path names and path segments

Every item (and section) is referred through what is called "path name". It is identical to a file name that includes the directory names. The path name contains the names of the parent items (or sections) separated by slashes (/) and at the end of it is the name of the actual item.

If you have an item test, its path name is just that, test, and nothing else. If you create another item, say parent, add a child section under it and then attach the item test to that section, the item's path name would be parent/test. You just keep adding the parent sections and slashes.

The file format

Unlike its predecessor, ncfg has a very simple file format. The format is still divided into two main categories: sections and items.

The parser is a free-form, meaning you can use newlines, tabs and other whitespace as much as you want. Only whitespace breaks things into separate tokens. This means that ab;cd; means an item whose name is ab;cd and not two items (ab and cd). This reduces the amount of escaping you must do, but it might lead to gotchas if you aren't aware of this.

Items

Every item declaration begins with the item's name, followed by the (optional) values and it ends in a semicolon:

message "Hello world";
coordinates 14 39;
optimize;

The above example creates three items. The first, named message has one value: Hello world. The quotes are needed only if he value has embedded whitespace, and they're automatically removed and inserted again when the file is saved, if needed. The second item, coordinates has two values, 14 and 39. Note that both of those numbers are actually text strings, ncfg treats everything as a string. The last one, optimize has no values. It just exists.

Because the semicolon ends an item declaration, you can put them all on the same line:

message "Hello world"; coordinates 14 39; optimize;

If the item has a child section, then the { and } (denoting the section's start and end) come before the semicolon. In fact, the semicolon is is not needed at all if you have a child section:

file {
    name data/archive.zip;
    mount_point /;
}

This creates an item file which has a child section. The child section has no name, but its name indirectly is file, since that item is its parent item. The items name and mount_point are both in that section and can be accessed by first getting a pointer to the file section, then by iterating the linked list in the file's child_section structure.

You must put a whitespace between the item's name and the {, otherwise ncfg does not pick it up.

As said, semicolons are not needed if you have a child section. It is not an error to use them, though. ncfg ignores unnecessary semicolons:

vfs {
    file {
        name data/archive.zip;
        mount_point /;
    }

    file {
        name dev/new_data.zip;
        mount_point /new;
    };
};;;;;

However, after you end an item with a semicolon, you cannot "go back" to it and add a child section. Either you declare the child section right away, or you don't declare it at all. So the following will result in a syntax error, because the item has already ended and the section has nothing where it could be assigned to:

file; {
    name data/archive.zip;
    mount_point /;
}

Escaping characters

In item names and values, certain characters must be escaped to prevent ncfg from interpreting them. These characters are:

ncfg automatically escapes these when saving files, so you don't have to do it. Any other character can be passed as-is.

Not that in some cases, if the escaped character happens to be a part of a string or identifier, then you don't have to escape them. Consider this example:

item\a;

In this case, the \ does not need to be escaped, because it is not standalone. If it was the first or the last character, then it needs to be escaped.

Note that no matter what you do, you cannot use forward slashes (/) in item names! They work fine in the values.

Binary data

ncfg's file format is text-only and you should refrain from abusing it to store binary data. But if you really need to store binary data, encode it first.

Sections

As you can see from the previous chapter, sections begin with { and they end in }. Items between those belong in that section. Sections can be nested freely. But you MUST end every section you start. Otherwise you'll get an unbalanced nesting level error if you try to load the file.

An implicit section called "root section" exists. Every item that is not inside { and } is placed in this section. The root section is automatically created and deleted by ncfg. You can delete it, but you can't do anything unless you recreate it first.

Sections have no names in ncfg, but the parent item's name can be thought as a name for the section. The root section is an exception, it never has a name.

Comments

ncfg supports C and C++ -style comments. A C-style comment begins with /* and continues until an ending */ is found. C++ -style comment begins with a // and continues until the line end. C-style comments can be nested, ncfg keeps track of the nesting level and only the last */ finally terminates the whole comment.

LibCFG did not handle /*, */ and // inside strings correctly. But ncfg does. This means, for example, that you can write URLs just fine and they are not interpreted as C++-style comments (while in LibCFG you had to escape the slashes).

So this works just as expected:

url http://www.google.com;

The API reference

Structures

ncfg has several important structures.

cfg_t

Purpose

The cfg_t structure is the main handle in ncfg. You can't do much with the library if you don't allocate an instance of cfg_t structure. Actually, an "instance" is a bit of a misnomer, since you don't actually initialize the library anywhere. But cfg_t stores the actual tree data, contains error number and error row/column numbers, I/O data and various other important things. So, in essence, one cfg_t instance represents ONE configuration file. You'll probably have multiple instances allocated simultaneously and that's fine: they don't interfere with each other. You can even reuse existing instances if you want.

Strictly speaking, you don't need this. You can create the tree all by yourself. You just can't save it easily, plus some future tasks might be difficult or impossible. So you should still create and use this.

Members

cfg_section_t

Purpose

A section stores zero or more child items. They have an optional "owner" item. Sections can be nested, but they always require separate owner items, since an item can only have one child section.

Members

cfg_item_t

Purpose

Items are where the actual configuration data is stored. They have a key that identifies them (not necessarily a unique name) plus zero or more associated values (which are always strings). They optionally have a child section. The items are stored in doubly-linked lists in their owner sections.

Members

cfg_io_functions_t

Purpose

A structure containing pointers to the I/O functions. You can use it to override ncfg's internal stdio I/O functions. To see how exactly these functions work, you'll have to check the source code. Most likely you'll only have to use this structure if you want to create a memory buffer reader/writer.

Members

cfg_io_data_t

Purpose

This structure contains the file handle and a pointer to your own custom I/O data you might need. It is passed to all I/O functions and they can do whatever they want with it.

Members

Functions

Allocating and freeing a library instance

Sections

struct cfg_section_t *s = NULL;

cfg_section_new(&s);

// oops, didn't want to create it anyway...
cfg_section_delete(&s);

struct cfg_section_t *s = NULL;
struct cfg_item_t *i = NULL;

cfg_section_new(&s);
cfg_item_new(&i, "some_item", 0, NULL);

// add the item into the section
cfg_section_add_item(s, i);

// or never mind
cfg_section_remove_item(s, i);

Items

struct cfg_item_t *itemA = NULL,
                  *itemB = NULL;

char *values[] =
{
    "Hello",
    "world!"
};

cfg_item_new(&itemA, "item A", 0, NULL);
cfg_item_new(&itemB, "item B", 2, &values);

...

cfg_item_delete(&itemA);
cfg_item_delete(&itemB);

struct cfg_item_t *item = NULL;

cfg_item_new(&item, "example", 0, NULL);
cfg_item_delete(&item);

// 'item' is now NULL

vfs {
    file {
        name data/archive.zip;
        mount_point /;
    }

    file {
        name dev/new_data.zip;
        mount_point /new;
    }
}

struct cfg_t *conf = NULL;

cfg_new(&conf);
cfg_load("test.cfg");

char *path = cfg_item_get_full_path(cfg_get_item(conf->root, "vfs/file/mount_point", 0, NULL));

if (path) {
    printf("%s\n", path);
    free(path);
}

cfg_delete(&conf);

vfs/file/mount_point

Accessing sections, items and values and managing the tree

some_item a b c "Hello world" d;

struct cfg_item_t *item = ...;

printf("%s\n", cfg_item_get_value(item, 0, "invalid index"));
printf("%s\n", cfg_item_get_value(item, 3, "invalid index"));
printf("%s\n", cfg_item_get_value(item, 5, "invalid index"));

a
Hello World
invalid index

Loading and saving

struct cfg_t *cfg = NULL;

cfg_new(&cfg);

if (!cfg_load(cfg, "filename.cfg")) {
    // something went wrong, check cfg->error_code
} else {
    // you can now access the data via cfg->root
}

cfg_delete(&cfg);

struct cfg_t *cfg = NULL;

cfg_new(&cfg);

// create the items and sections here

if (!cfg_save(cfg, "filename.cfg", 0, NULL)) {
    // something went wrong, check cfg->error_code
}

cfg_delete(&cfg);

struct cfg_t *cfg = NULL;

cfg_new(&cfg);

// create the items and sections here

const char *headers[] =
{
    "This is just an example on how to use the comment headers.",
    "This is the second line."
};

if (!cfg_save(cfg, "filename.cfg", 2, &headers)) {
    // something went wrong, check cfg->error_code
}

cfg_delete(&cfg);

// This is just an example on how to use the comment headers.
// This is the second line.
(actual data here)

Utility functions

struct cfg_t *cfg = NULL;

cfg_new(&cfg);

cfg_load(cfg, "file1.cfg");
cfg_load(cfg, "file2.cfg");
cfg_load(cfg, "file3.cfg");

// now we have three files' worth of data loaded in memory

...

// start from scratch
cfg_reset_root(cfg);
cfg_load(cfg, "file4.cfg");

// now only file4.cfg's data exists in memory

struct cfg_t *cfg = NULL;

cfg_new(&cfg);

if (!cfg_load(cfg, "file.cfg")) {
    printf("%s (%d)\nLine: %u\nColumn: %u\n",
        cfg_error_code_to_string(cfg->error_code), cfg->error_code,
        cfg->error_row, cfg->error_col);

    cfg_delete(&cfg);
    return 1;
}

// no errors

Other useful functions

Error codes and their meanings

The following table lists all error codes ncfg currently uses. The "structure" column contains an X if the error code updates the row/column numbers in the cfg_t structure.

TODO

Version history

Version 0.9.2 (released on August 4 2013) is the first publicly released version, so everything is new.

Known bugs

• Some characters are escaped when they don't need escaping (if they appear inside a string). While this is a bug, it is not fatal, because the escaped characters are read back correctly when the file is loaded again. So this is mostly an annoyance.
• cfg_get_item does not handle trailing slashes correctly.
• The column numbers are not always exact in all error situations. The column number handling is a mess, I should rewrite that part anyway.
• Valgrind says ncfg is clean, but I'm sure there are memory bugs lurking in there, somewhere...

Future versions

I am unable to say when new versions will be released. I am following YAGNI principle with ncfg (You Aint Gonna Need It), so features are added only when they're needed. Having said that, I do have a list of things I'll probably add at some point:

• Bug fixes
• cfg_get_item sucks. It's unnecessarily complex and limited and it doesn't support every possible path variation.
• This documentation sucks. Not enough examples, the grammar is bad and it just sucks. It's the worst documentation I've ever written.
• Implement a built-in memory buffer reader/writer. It's a common operation to read from memory buffers, common enough that it should be built-in.
• Sibling section pointers
• A thin (and optional) C++ wrapper class/classes
• Speed and memory usage optimizations
• Custom callbacks in the parser, for expanding and modifying the input data on-the-fly
• Simple expression evaluator (and using existing item values as input)
• File inclusion system and possibly a C-style macro expansion system

If you come up with useful ideas for new features, don't hesitate to contact me.

Licenses

The library itself

Like its predecessor, ncfg is licensed under the zlib/libpng license:

ncfg v0.9.2 Copyright (c) 2012-2013 Jarmo Pietiläinen

This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.

Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.

The documentation

This documentation is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.

Contact information

You can contact me via e-email. My address and other projects I've done can be found on my home page at http://z0b.kapsi.fi/. I am open to new ideas, suggestions and other criticism.