|

Configuration file I/O

Introduction

The Ionflux::Tools::ConfigTree API provides an easy to use and powerful interface to machine- and human-readable (and even human-friendly) configuration files which can be used by any application.

Configuration file syntax

The configuration tree can be generated from a configuration file of the following format:

# <comment>
<tree path> = <value>

Each line consists of either a comment or a tree path assignment, where the tree path conforms to the rules set forth in misc/path-resolution.txt and Template Engine.

Whitespace is ignored at the following positions:

1) at the beginning of a line
2) at the end of a line
3) to the left and right of the '='

Whitespace inside the value is preserved.

A value may span multiple lines. This is accomplished by appending a '\' character to the end of a line.

Array indices may be omitted to fill arrays automatically:

foo[] = bar
foo[] = baz

In this case, the next available index will be accessed, so the above is equal to:

foo[0] = bar
foo[1] = baz

However, if you want to use automatic array indexing along with complex node structures, be aware that each occurence of a missing index will access the next available index. Thus

foo[].bar = 1
foo[].baz = 2
foo[].bar = 3
foo[].baz = 4

is equal to

foo[0].bar = 1
foo[1].baz = 2
foo[2].bar = 3
foo[3].baz = 4

and not, as one might (somewhat carelessly) expect:

foo[0].bar = 1
foo[0].baz = 2
foo[1].bar = 3
foo[1].baz = 4

You can avoid confusion by using automatic arrays in conjunction with nested configuration, which is explained below.

Configuration directives may be nested by using curly braces ({}):

foo = {
    bar = 42
    baz = 23
}

This creates a new context (inside the curly braces) where the 'foo' node is treated as the root node. You can use this feature to create nested automatic array definitions:

foo[] = {
    bar[] = {
        a = 1
        b = 2
    }
    bar[] = {
        c = 3
        d = 4
    }
}

To assign data entries to the root node, or in fact any node, just place quoted strings in the root context of a node:

'This is a data entry in the root node context.'
foo = {
    "This is a data entry in the context of node 'foo'"
    'This is yet another data entry.'
}

Interestingly enough, there are several possiblilities for setting data entries of the root node (or the node currently in the root context). For example:

'Hello world!'
[1] = 'This is another data entry of the root node.'
[] = 'You can use automatic array indexing as well.'

Quoting works as usual, with quote characters " and ' and \ as an escape character.

---