canfigger
Canfigger is a small C library that parses configuration files. It reads a
file and represents its contents as a linked list of key-value pairs, each of
which can carry attributes. It also finds the standard directories a program
keeps files in — config, data, cache, state, and the user's Desktop,
Documents and Downloads — and joins paths, using XDG on Linux and macOS and
the Windows equivalents.
Format
This example shows the format canfigger handles:
foo = bar
blue = color, shiny
statement = hello world, obvious
# An option with no value or attributes
FeatureFooEnabled
# key, value with 2 attributes
dhcp-range = 192.168.0.50, 192.168.0.150, 12
# key, value with 9 attributes
solar_system = sun, Mercury, Venus, Earth, Mars, Jupiter, Saturn, Neptune, Uranus, Pluto
You can change the attribute delimiter character by passing it as the second
argument:
canfigger_parse_file(filename_ptr, ':');
Platform path helpers
canfigger_config_dir(appname) — returns the per-application config
directory ($XDG_CONFIG_HOME/appname or $HOME/.config/appname)canfigger_data_dir(appname) — returns the per-application data
directory ($XDG_DATA_HOME/appname or $HOME/.local/share/appname)canfigger_cache_dir(appname) — returns the per-application cache
directory ($XDG_CACHE_HOME/appname or $HOME/.cache/appname)canfigger_state_dir(appname) — returns the per-application state
directory ($XDG_STATE_HOME/appname or $HOME/.local/state/appname), for
data that persists between runs but is not configuration and is not worth
backing upcanfigger_runtime_dir(appname) — returns $XDG_RUNTIME_DIR/appname for
short-lived per-session files (sockets, lock files, secrets). Returns NULL
when there is no usable runtime directory — unset, or failing the spec's
requirements that it exist, be owned by the caller and have mode 0700 — and
always on Windows, which has no equivalent. A NULL return is an ordinary
outcome; pick a fallback suited to the datacanfigger_config_dirs() / canfigger_data_dirs() — return the system
search paths ($XDG_CONFIG_DIRS, $XDG_DATA_DIRS) as a NULL-terminated
array, searched after the per-user directories above. Free with
canfigger_free_dirs(). On Windows the array holds one entry,
%ProgramData%canfigger_config_file(filename) — returns a path directly under the
base config directory, without an application subdirectory
($XDG_CONFIG_HOME/filename or $HOME/.config/filename); useful when
the config file lives at the config root rather than in a per-application
subdirectorycanfigger_find_config_file(appname, filename) — looks for an existing
config file. It checks the user's own config directory first, then each
directory from canfigger_config_dirs() in turn, and returns the path of
the first file it finds. A file in the user's own directory is used instead
of a system-wide one. Pass NULL for appname to look directly under the
config rootscanfigger_user_dir(which) — returns one of the user's visible home
directories: Desktop, Downloads, Templates, Public share, Documents, Music,
Pictures or Videos. On Unix the paths come from the user-dirs.dirs file
that the desktop writes. The desktop translates these names, so the desktop
directory is ~/Desktop on an English system and on a Danish
one. When the file is missing, the result is
See the API documentation for details.
Dependencies
None
Building
meson setup _build
cd _build
ninja
For configuration options, use meson configure (see the Meson
docs for detailed usage).
Tests
meson test (-v)
Example programs
Example programs will be built when you run ninja. If you want to try them
with a different config file, give them the name of a config file as an
argument.
