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_data_dir (const char *appname)
	Return the platform data 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);
}

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 103 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 125 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_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.

Definition at line 553 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 564 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);
}

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 351 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.

Definition at line 575 of file canfigger.c.