canfigger v0.3.2 Lightweight config file parser library

Loading...
Searching...
No Matches
Data Structures | Macros | Functions
canfigger.h File Reference

Public API for the Canfigger configuration file parser. More...

`#include "canfigger_version.h"`

Go to the source code of this file.

## Data Structures
struct | attributes
| Internal iteration state for a node's attribute list. More...
struct | Canfigger
| A single node in the parsed configuration linked list. More...

## Macros
#define | CANFIGGER_CHECK_VERSION(maj, min)
| Compile-time version check.

## Functions
struct Canfigger * | canfigger_parse_file (const char *file, const int delimiter)
| Parse a configuration file into a linked list of key-value nodes.
void | canfigger_free_current_key_node_advance (struct Canfigger **node)
| Free the current node and advance the list pointer to the next node.
void | canfigger_free_current_attr_str_advance (struct attributes *attributes, char **attr)
| Free the current attribute string and advance to the next attribute.
void | canfigger_free_list (struct Canfigger **node)
| Free all remaining nodes in the list.
char * | canfigger_config_dir (const char *appname)
| Return the platform config directory for an application.
char * | canfigger_config_file (const char *filename)
| Return the path to a config file in the platform base config directory.
char * | canfigger_data_dir (const char *appname)
| Return the platform data directory for an application.
char * | canfigger_cache_dir (const char *appname)
| Return the platform cache directory for an application.
char * | canfigger_path_join (const char *dir, const char *file)
| Join a directory path and a filename with the platform separator.

## Detailed Description

Public API for the Canfigger configuration file parser.

Canfigger parses plain-text configuration files into a singly-linked list of key-value nodes. Each node may also carry a list of attributes — extra comma-separated (or user-specified delimiter) fields that follow the value on the same line.

File format (one entry per line):

key = value
key = value, attr1, attr2
key = list, item1, item2, item3
# comment lines are ignored
[section headers are ignored]

The = sign separates the key from the value. The delimiter character (passed to canfigger_parse_file()) separates the value from the first attribute, and each subsequent attribute from the next. A UTF-8 BOM at the start of the file is silently skipped.

Typical usage:

struct Canfigger *list = canfigger_parse_file("app.conf", ',');
while (list) {
// use list->key and list->value
canfigger_free_current_key_node_advance(&list);
}
canfigger_parse_file
struct Canfigger * canfigger_parse_file(const char *file, const int delimiter)
Parse a configuration file into a linked list of key-value nodes.
Definition canfigger.c:356
canfigger_free_current_key_node_advance
void canfigger_free_current_key_node_advance(struct Canfigger **node)
Free the current node and advance the list pointer to the next node.
Definition canfigger.c:125
Canfigger
A single node in the parsed configuration linked list.
Definition canfigger.h:127

Part of canfigger (https://github.com/andy5995/canfigger).

Definition in file canfigger.h.

## Data Structure Documentation

## ◆ attributes

struct attributes

Internal iteration state for a node's attribute list.

This struct is allocated and owned by the library. Callers should not read or modify its fields directly; use canfigger_free_current_attr_str_advance() to iterate.

Definition at line 104 of file canfigger.h.

Data Fields
char * | current |
char * | iter_ptr |
char * | str |

## ◆ Canfigger

struct Canfigger

A single node in the parsed configuration linked list.

Each node represents one key-value entry from the configuration file. Nodes are heap-allocated by canfigger_parse_file() and must be freed with canfigger_free_current_key_node_advance() or canfigger_free_list().

Definition at line 126 of file canfigger.h.

Data Fields
struct attributes * | attributes |
char * | key |
struct Canfigger * | next |
char * | value |

## Macro Definition Documentation

## ◆ CANFIGGER_CHECK_VERSION

#define CANFIGGER_CHECK_VERSION | ( |  | maj,
|  |  | min )

Value:
(CANFIGGER_VERSION_MAJOR > (maj) || \
(CANFIGGER_VERSION_MAJOR == (maj) && CANFIGGER_VERSION_MINOR >= (min)))

Compile-time version check.

Evaluates to a non-zero value if the canfigger headers are at least the given major and minor version. Useful for conditional compilation when a feature was added in a known release:

#if CANFIGGER_CHECK_VERSION(0, 4)
// use API added in 0.4
#endif

Parameters

  maj | Required major version.
  min | Required minor version.

Definition at line 80 of file canfigger.h.

## Function Documentation

## ◆ canfigger_cache_dir()

char * canfigger_cache_dir | ( | const char * | appname | ) |

Return the platform cache directory for an application.

On Unix, honours `$XDG_CACHE_HOME` if set; otherwise uses `$HOME/`.cache/appname. On Windows, uses `LOCALAPPDATA%\appname`.

The returned string is heap-allocated; the caller must free it.

Parameters

  appname | Application name appended as a subdirectory.

Returns
  Malloc'd path string, or NULL on failure or if `appname` is NULL/empty.

Definition at line 621 of file canfigger.c.

## ◆ canfigger_config_dir()

char * canfigger_config_dir | ( | const char * | appname | ) |

Return the platform config directory for an application.

On Unix, honours `$XDG_CONFIG_HOME` if set; otherwise uses `$HOME/`.config/appname. On Windows, uses `APPDATA%\appname`.

The returned string is heap-allocated; the caller must free it.

Parameters

  appname | Application name appended as a subdirectory.

Returns
  Malloc'd path string, or NULL on failure or if `appname` is NULL/empty.

char *dir = canfigger_config_dir("myapp");
if (dir) {
char *path = canfigger_path_join(dir, "settings.conf");
free(dir);
// open path ...
free(path);
}
canfigger_config_dir
char * canfigger_config_dir(const char *appname)
Return the platform config directory for an application.
Definition canfigger.c:571
canfigger_path_join
char * canfigger_path_join(const char *dir, const char *file)
Join a directory path and a filename with the platform separator.
Definition canfigger.c:632

Definition at line 571 of file canfigger.c.

## ◆ canfigger_config_file()

char * canfigger_config_file | ( | const char * | filename | ) |

Return the path to a config file in the platform base config directory.

Joins the base config directory with `filename`, without inserting an application-name subdirectory. On Unix, honours `$XDG_CONFIG_HOME` if set; otherwise uses `$HOME/`.config/filename. On Windows, uses `APPDATA%\filename`.

Use this when the config file lives directly under the config root rather than in a per-application subdirectory (e.g. `$HOME/`.config/apprc rather than `$HOME/`.config/app/apprc).

The returned string is heap-allocated; the caller must free it.

Parameters

  filename | Config file name (or relative sub-path) to append.

Returns
  Malloc'd path string, or NULL on failure or if `filename` is NULL or empty.

char *path = canfigger_config_file("apprc");
if (path) {
struct Canfigger *list = canfigger_parse_file(path, ',');
free(path);
// use list ...
}
canfigger_config_file
char * canfigger_config_file(const char *filename)
Return the path to a config file in the platform base config directory.
Definition canfigger.c:582

Definition at line 582 of file canfigger.c.

## ◆ canfigger_data_dir()

char * canfigger_data_dir | ( | const char * | appname | ) |

Return the platform data directory for an application.

Intended for user-generated data (saves, state, cache) — not bundled application assets. On Unix, honours `$XDG_DATA_HOME` if set; otherwise uses `$HOME/`.local/share/appname. On Windows, uses `LOCALAPPDATA%\appname`.

The returned string is heap-allocated; the caller must free it.

Parameters

  appname | Application name appended as a subdirectory.

Returns
  Malloc'd path string, or NULL on failure or if `appname` is NULL/empty.

Definition at line 610 of file canfigger.c.

## ◆ canfigger_free_current_attr_str_advance()

void canfigger_free_current_attr_str_advance | ( | struct attributes * | attributes,
|  | char ** | attr )

Free the current attribute string and advance to the next attribute.

On the first call for a given node, `*attr` must be NULL; the function loads the first attribute into `*attr`. On each subsequent call it frees the previous attribute string and loads the next. Sets `*attr` to NULL when no more attributes remain, or if `attributes` is NULL.

Typical usage:

char *attr = NULL;
canfigger_free_current_attr_str_advance(node->attributes, &attr);
while (attr) {
// use attr
canfigger_free_current_attr_str_advance(node->attributes, &attr);
}
canfigger_free_current_attr_str_advance
void canfigger_free_current_attr_str_advance(struct attributes *attributes, char **attr)
Free the current attribute string and advance to the next attribute.
Definition canfigger.c:86

Parameters

  attributes | Pointer to the attributes structure of the current node (may be NULL, in which case `*attr` is set to NULL).
  attr | Output parameter; set to the next attribute string on success, or NULL when the list is exhausted.

Definition at line 86 of file canfigger.c.

## ◆ canfigger_free_current_key_node_advance()

void canfigger_free_current_key_node_advance | ( | struct Canfigger ** | node | ) |

Free the current node and advance the list pointer to the next node.

Releases all memory owned by `*node` (key, value, and any attributes), then sets `*node` to the next node in the list. Call this at the end of each loop iteration when walking the list:

while (list)
canfigger_free_current_key_node_advance(&list);

Parameters

  node | Double pointer to the current node; updated to point to the next node (or NULL at end of list) before returning.

Definition at line 125 of file canfigger.c.

## ◆ canfigger_free_list()

void canfigger_free_list | ( | struct Canfigger ** | node | ) |

Free all remaining nodes in the list.

Equivalent to calling canfigger_free_current_key_node_advance() in a loop until the list is empty. Use this for early-exit cleanup when you need to discard a partially-iterated list.

Parameters

  node | Double pointer to the current (or head) node; set to NULL on return.

Definition at line 166 of file canfigger.c.

## ◆ canfigger_parse_file()

struct Canfigger * canfigger_parse_file | ( | const char * | file,
|  | const int | delimiter )

Parse a configuration file into a linked list of key-value nodes.

Reads `file`, strips a leading UTF-8 BOM if present, and returns a singly-linked list where each node holds one key-value entry. Lines beginning with `#` or ``[ and blank lines are ignored.

The `delimiter` character separates the value from the first attribute and each subsequent attribute from the next. Pass a character that does not appear in your values if you do not use attributes (e.g. `'`,').

The caller owns the returned list and must free it with canfigger_free_current_key_node_advance() (while iterating) or canfigger_free_list() (to discard the whole list at once).

Parameters

  file | Path to the configuration file.
  delimiter | Character that separates the value from attributes on a line.

Returns
  Head of the linked list, or NULL if the file cannot be opened, is empty, or a memory allocation failure occurs.

Definition at line 356 of file canfigger.c.

## ◆ canfigger_path_join()

char * canfigger_path_join | ( | const char * | dir,
|  | const char * | file )

Join a directory path and a filename with the platform separator.

A separator is inserted between `dir` and `file` unless `dir` already ends with `/` or `\`.

The returned string is heap-allocated; the caller must free it.

Parameters

  dir | Directory portion of the path.
  file | Filename (or relative sub-path) to append.

Returns
  Malloc'd joined path string, or NULL if either argument is NULL or empty, or on allocation failure.

char *path = canfigger_path_join("/home/user/.config/myapp", "settings.conf");
if (path) {
struct Canfigger *list = canfigger_parse_file(path, ',');
free(path);
// use list ...
}

Definition at line 632 of file canfigger.c.