dot.conf API description
=====================================================================
1. dot.conf types
---------------------------------------------------------------------
1.0. typedefs
1.1. constants
1.2. macros
1.3. structures
1.3.1. configfile_t
1.3.2. configoption_t
1.3.3. command_t
The API is built around the main data structures
configfile_t
configoption_t
and command_t
Two other types are context_t and info_t, but these are only typedefs
from void!
configfile_t is the dotconf 'session' structure building the glue
between the various API parts. It stores things like the stream,
current filename or the line currently read. When using dot.conf
the first thing for the programmer to do is to receive a valid
configfile_t structure with the ->dotconf_create API call.
1.0. dot.conf's typedefs
==============================
typedef void context_t;
typedef void info_t;
typedef const char *(*dotconf_callback_t)(command_t *, context_t *);
^^^^^^^^^^^^^^^^^^
the type of function called for each encountered command
typedef int (*dotconf_errorhandler_t)(configfile_t *, int,
^^^^^^^^^^^^^^^^^^^^^^ unsigned long, const char *);
the type of the errorhandler callback
typedef const char *(*dotconf_contextchecker_t)(command_t *, unsigned long);
^^^^^^^^^^^^^^^^^^^^^^^^
the type of the contextchecker
1.1. dot.conf's constants
==============================
CFG_BUFSIZE 4096
max length of one line
CFG_MAX_OPTION 32
max length of an option name
CFG_MAX_VALUE 4064
max length of an options value
CFG_MAX_FILENAME 256
max length of a filename (used when Include'ing)
CFG_VALUES 16
max # of parameters an option can take. if an options
gets more than CFG_VALUES parameters, the last one holds
the complete remaining unparsed string is passed
in list[CFG_VALUES-1].
CFG_INCLUDEPATH_ENV "DC_INCLUDEPATH"
the name of the environment variable used to find the
search path for Include'ed files.
1.2. dot.conf's macros
==============================
DOTCONF_CB(__name)
conveniently declare / define a callback function.
FUNC_ERRORHANDLER(__name)
conveniently declare / define the errorhandler callback
1.3.1. configfile_t
==============================
FILE *stream
the stream opened by dotconf_create. this field should only be
used by dotconf_get_next_line for reading
char eof
eof is set to one as soon as the END OF FILE has been reached.
size_t size
this field is only used if there was a here-document to be handled.
for here-documents dotconf allocates as much memory as the filesize.
The result of the necessary stat() call is cached in this field.
Do never rely on the value of this field!!
context_t *context
the application's pointer to the context memory block. this field
is set by dotconf_create, and used to fill in the corresponding
field of the command_t when calling a command's callback
configoption_t const **config_options
a list of configuration options dotconf's dotconf_handle_command
can understand. Never write to this field yourself, use
dotconf_register_command to handle this for you.
int config_option_count
the number of modules that registered their options including
dotconf's internal options and the core options of the app as given
to dotconf_create.
char *filename
the name of the configuration file
unsigned long line
the line pointer in the file currently parsed
unsigned long flags
the run-time flags as passed to dotconf_create. this value
can be changed at run-time to have dot.conf act different at different
stages of the configuration file (i.e. switch case (in)sensitive matching)
char *includepath
the include-path for dot.conf's internal 'Include' option.
This field is set by dotconf_create to one of these possibilities in
order:
- If the variable named by CFG_INCLUDEPATH_ENV is set in the
environment, includepath is set to the value of that variable.
- If the name of the configuration file passed to dotconf_create
contains a fully qualified path, includepath is set to that path
without the file name.
- If the name of the configuration file passed to dotconf_create
contains a relative path, includepath is set to the fullly
qualified path where the configuration file is stored without the
configuration file name.
- Otherwise, includepath is not set.
dotconf_errorhandler_t errorhandler
the errorhandler of the app; after creating your configfile_t set this
field to your errorhandler function or leave it as NULL
dotconf_contextchecker_t contextchecker
the contextchecker is responsible for telling dot.conf whether a
command is valid in the current context. this callback is useful
if you create several container commands that behave different
according to their nesting (see Apache's Files, Directory and VirtualHost).
int (*cmp_func)(const char *, const char *, size_t)
the function used to compare the first word of a buffer line with
all commands registered in config_options. this will be set by the core
to be strncmp or strncasecmp depending on the matching type you chose
via the flags. again, changing this at any point during the parsing
will have an immediate effect.
1.3.2. configoption_t
==============================
const char *name
the name of the configuration option dot.conf should understand
int type
the type of the data your app expects. possible values are:
ARG_NONE - your app does not expect any args; dot.conf will not parse
any args even if some were given.
ARG_RAW - unparsed string with whatever was on the line
line continuation has been handled, environment variable
substitution not.
ARG_STR - the first argument (i.e. anything up to the first unquoted,
unescaped whitespace character
ARG_INT - like ARG_STR, but atoi() is called on the value found
ARG_TOGGLE - your app gets 0 for off, and 1 for on; recognized values are
On/Off, 1/0, Yes/No
ARG_LIST - the application expects several ARG_STRs in a char **list.
ARG_NAME - fallback to catch unknown commands. This is for instance
especially useful to parse files like Apache's mime.types.
If an ARG_NAME is given as the last item of the command table,
dot.conf handles the commands as known, and does everything
it would have done for an ARG_LIST option.
Note: Modules cannot install an ARG_NAME handler. That is the
sole right of the core application code.
dotconf_callback_t callback
the function to be called if the given command name is encountered
info_t *info
additional info for the callback to operate with
unsigned long context
the context flag; this will be passed to the apps configchecker
1.3.3. command_t
==============================
const char *name
the name of the configuration option as in the app's command table.
for ARG_NAME type options this is the name of the unmatched/unknown
command.
configoption_t *option
a pointer to the full entry of the command table that corresponds to
the current option
struct {
long value;
char *str;
char **list;
double dvalue;
} data
the data found when parsing.
data.value - this is used for ARG_INT and ARG_TOGGLE options
data.str - is only used for ARG_STR type options
data.list - list is filled for ARG_LIST and ARG_NAME options
data.list is terminated by a NULL entry
data.dvalue - this is used for ARG_DOUBLE options
int arg_count
only set for ARG_LIST items; this is set to the number of items in
data.list. the last item of the list is data.list[arg_count-1].
configfile_t *configfile
the dot.conf session currently active
context_t *context
the context pointer you passed to dotconf_create when generating your
configfile_t *.
2. Function Reference
---------------------------------------------------------------------
2.1. dotconf_create
2.2. dotconf_cleanup
2.3. dotconf_register_options
2.4. dotconf_command_loop
2.5. dotconf_command_loop_until_error
2.6. dotconf_get_next_line
2.7. dotconf_handle_command
2.8. dotconf_warning
2.1. dotconf_create
==============================
configfile_t *dotconf_create(char *filename, const configoption_t *options,
context_t *context, unsigned long flags);
description:
dotconf_create returns a pointer to a configfile_t structure after
initializing it. The values you pass are stored in it for future
reference.
parameters:
char *filename
the filename of the configuration file you want to parse in
this session. The filename is only read by dot.conf.
const configoption_t *options
this parameter lets dot.conf know about the commands you want
it to understand. The configoption_t's tell dot.conf which
of your callbacks is responsible for a specific command.
context_t *context
in context you can pass a pointer to the structure
holding anything necessary to keep a context when parsing.
This pointer is passed to your command callbacks as a field
in command_t, so you can access it at any time.
unsigned long flags
this parameters sets the runtime flags to consider when
parsing. This controls important core functionality.
Possible flags are :
NONE :
no flags (0)
CASE_INSENSITIVE :
match option names case insensitive
DONT_SUBSTITUTE :
do not call substitute_env after read_arg
NO_INLINE_COMMENTS :
do not stop parsing arguments after a #-sign on a line
DUPLICATE_OPTION_NAMES :
allow for duplicate option names in different contexts
The first one without an error from the contextchecker
is used.
return value:
configfile_t *
the dot.conf session structure, which is to be used in every
call to another dot.conf API function. NULL is returned in case of a failure
sideeffects:
the returned configfile_t* is malloc()ed, and the field 'stream' is
fopen()ed. Do not clean this by hand, but use dotconf_cleanup instead.
2.2. dotconf_cleanup
==============================
void dotconf_cleanup(configfile_t *configfile);
description:
dotconf_cleanup cleans up behind whatever dotconf_create and friends
did to and with the configfile_t* that is given as the argument.
parameters:
configfile_t *configfile
the dot.conf session structure as returned by dotconf_create.
return value:
void
2.3. dotconf_register_options
==============================
int dotconf_register_options(configfile_t *configfile,
const configoption_t *options);
description:
this function registers additional known configuration commands at
runtime. the next time dot.conf needs to match an option, these
newly registered options are taken into account.
parameters:
configfile_t *configfile
the dot.conf session structure as returned by dotconf_create
const configoption_t *options
this parameter lets dot.conf know about the commands you want
it to understand. The configoption_t's tell dot.conf which
of your callbacks is responsible for a specific command.
return value:
int
dotconf_register_options returns non-zero on success and zero
on failure. The only possible failure condition is the failure
to allocate memory.
If the function fails, configfile is untouched.
2.4. dotconf_command_loop
==============================
int dotconf_command_loop(configfile_t *configfile);
description:
this function iterates through all lines of the configuration file
passing the buffer filled by dotconf_get_next_line to
dotconf_handle_command. On error dotconf_command_loop calls
dotconf_warning.
parameters:
configfile_t *configfile
the dot.conf session structure as returned by dotconf_create
return value:
int
dotconf_command_loop returns zero on failure and non-zero for success.
success means, that the parsing is done now.
2.5. dotconf_command_loop_until_error
==============================
const char *dotconf_command_loop_until_error(configfile_t *configfile);
description:
this function iterates through all lines of the configuration file
passing the buffer filled by dotconf_get_next_line to
dotconf_handle_command. On error this function exits returning the
error.
parameters:
configfile_t *configfile
the dot.conf session structure as returned by dotconf_create
return value:
const char *
dotconf_command_loop_until error returns the first error it stumbles over
or NULL if everything went fine
2.6. dotconf_get_next_line
==============================
int dotconf_get_next_line(char *buffer,
size_t bufsize, configfile_t *configfile);
description:
this function reads the next line from the configfile, increments
line counter, and handles the line continuation.
parameters:
char *buffer
the buffer where the line should be written to
size_t bufsize
the size of the buffer
configfile_t *configfile
the dot.conf session structure as returned by dotconf_create
return value:
int
zero indicates success, and non-zero means that some error occurred
2.7. dotconf_handle_command
==============================
const char *dotconf_handle_command(configfile_t *configfile, char *buffer);
description:
handles commands. This function further parses the line buffer and
tries to match up the first word found as the command. If the command
exists it parses all commands arguments and stuffs them into a
command_t structure. Where appropriate here-documents or quotings are
handled, and the environment variable substitution is tried on every
ARG_STR / ARG_LIST command argument except here-documents.
parameters:
configfile_t *configfile
the dot.conf session structure as returned by dotconf_create
char *buffer
the buffer as filled by dotconf_get_next_line
return value:
const char *
the error message as returned by the command callbacks for instance;
NULL if everything went ok.
2.8. dotconf_warning
==============================
int dotconf_warning(configfile_t *configfile,
int type, unsigned long errnum, const char *fmt, ...);
description:
dotconf_warning is responsible for dispatching any messages either
through the internal handler (i.e. fprintf) or through the app's
errorhandler.
parameters:
configfile_t *configfile
the dot.conf session structure as returned by dotconf_create
int type
type of the message; analogous to syslog-style types:
DCLOG_EMERG, DCLOG_ALERT, DCLOG_CRIT, DCLOG_ERR, DCLOG_WARNING,
DCLOG_NOTICE, DCLOG_INFO, DCLOG_DEBUG
unsigned long errnum
the error number. this is up to the app what values to put here.
I suggest using numbers above ERR_USER for own error numbers to
not be conflicting with dotconf's internal error numbers.
const char *fmt, ...
a printf style message format. the message will be prepared via
vsnprintf before passing it to your errorhandler.
return value:
int
the value returned here affects how dotconf_command_loop reacts to errors.
a value of zero, which is returned by the internal handler, will
make the command loop to read on. non-zero tells the loop to immediately
exit after printing the error.