NAME

conf_walk - parse confetti

LIBRARY

Configuration parser (libconfetti, -lconfetti)

SYNOPSIS

#include <confetti.h>

conf_errno conf_walk(const char *str, const conf_options *opts, conf_err *err, conf_walkcb cb);

DESCRIPTION

The conf_walk() function parses str as Confetti source text and invokes the function cb when it discovers configuration elements, like a directive or the beginning or end of a subdirective. If conf_walk() fails, it returns an error code which is one of conf_errno values and populates err, if provided, with details. The conditions under which each conf_errno constant is returned are documented in RETURN VALUE.

The str and cb arguments are required. All other arguments are optional. The implementation of cb must return the integer zero if parsing should continue, otherwise it can return non-zero to abort parsing.

The behavior of the Confetti parser is controlled with the optional opts argument. See conf_parse(3) for documentation on opts and err.

Walk function

The conf_walkcb function is a callback function invoked by the Confetti parser when it discovers configuration elements. The callback receives five arguments:

void *ud;
conf_mark elem;
int argc;
const conf_arg *argv;
const conf_comment *comnt;

The ud parameter is the user data pointer specified on the opts structure. It is passed through to the callback by the Confetti parser as-is.

The elem parameter represents the configuration element discovered. It is one of the following:

CONF_COMMENT

When the parser discovers a comment. The comnt parameter will be populated the location of the comment in the Confetti source text.

CONF_DIRECTIVE

When the parser discovers a directive. The argc and argv parameters will be populated with the directives arguments.

CONF_BLOCK_ENTER

When the parser is entering a subdirective block for the previously reported directive.

CONF_BLOCK_LEAVE

When the parser is leaving a subdirective block.

RETURN VALUE

The conf_walk() function will return one of the following conf_errno constants. If provided, the err structure will be populated with details about the error.

CONF_OK

When str is parsed without errors.

CONF_NO_MEMORY

If dynamic memory allocation fails. The implementation guarantees all intermediate allocations will be freed to avoid resource leakage.

CONF_BAD_SYNTAX,

If a Confetti syntax error is discovered.

CONF_ILLEGAL_BYTE_SEQUENCE,

If a malformed UTF-8 sequence is found.

CONF_INVALID_OPERATION

If str or cb are NULL.

CONF_MAX_DEPTH_EXCEEDED

If the maximum subdirective nesting depth is exceeded.

CONF_USER_ABORTED

If parsing is aborted. The implementation of cb must return a non-zero integer to indicate that parsing should abort.

LICENSING

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