NAME

confetti - configuration language and parser library

LIBRARY

Configuration parser (libconfetti, -lconfetti)

SYNOPSIS

#include <confetti.h>

DESCRIPTION

Confetti is a configuration language that combines the readability of Unix configuration files with the flexibility of S-expressions. It is minimalistic, untyped, and unopinionated. Schema conformance is validated by the user application.

Parsing

Confetti-conformant source text is formally known as a configuration unit. A configuration unit might correspond with a file in a file system, but that correspondence is not required.

The Confetti library is implemented in C11 and provides two public interfaces for processing configuration units:

The first interface visits configuration elements in a configuration unit without building an in-memory representation of the unit. This is achieved by invoking a user-provided callback function as the parser discovers configuration elements. See conf_walk(3) for details.

The second interface builds an in-memory representation of the configuration unit which can be inspected in a freeform way. This approach will be familiar as most parsers build an in-memory representation for freeform traversal. See conf_parse(3) for details.

Functions

The Confetti C API consists of fewer than a dozen functions:

conf_walk(3): Parse a configuration unit and incrementally invoke a function callback as the parser discovers configuration elements.
conf_parse(3): Parse a configuration unit into an in-memory representation for freeform traversal.
conf_free(3): Free a configuration unit returned from conf_parse(3).
conf_get_root(3): Returns a pseudo directive representing the top-level of the configuration unit.
conf_get_comment(3): Get a comment from the configuration unit.
conf_get_comment_count(3): Number of comments in the configuration unit.
conf_get_directive(3): Get a subdirective from a directive.
conf_get_directive_count(3): Number of subdirectives belonging to a directive.
conf_get_argument(3): Get an argument belonging to a directive.
conf_get_argument_count(3): Number of arguments belonging to a directive.

EXAMPLE

The following is an example of a Confetti-conformant configuration unit:

# This is a comment.

probe-device eth0 eth1

user * {
    login anonymous
    password "${ENV:ANONPASS}"
    machine 167.89.14.1
    proxy {
        try-ports 582 583 584
    }
}

user "Joe Williams" {
    login joe
    machine 167.89.14.1
}

Complete code examples demonstrating how to parse Confetti source text with the C API are included with the source distribution.

INTERNET RESOURCES

The website for Confetti, which hosts learning materials, examples, and the specification, is published at https://confetti.hgs3.me.

The source code for the Confetti C library is published at https://github.com/hgs3/confetti. If you need support or encounter a bug, then please report it on the issue tracker.

LICENSING

Confetti is Open Source software distributed under the MIT License. Please see the LICENSE file included with the Confetti distribution for details.