1#pragma once
2
3// This module implements a configuration parser. Clients can query the
4// contents of a configuration file through the interface provided here.
5// The current implementation is read-only; mutations are only kept in
6// memory. This parser supports the INI file format.
7
8// Implementation notes:
9// - Key/value pairs that are not within a section are assumed to be under
10//   the |CONFIG_DEFAULT_SECTION| section.
11// - Multiple sections with the same name will be merged as if they were in
12//   a single section.
13// - Empty sections with no key/value pairs will be treated as if they do
14//   not exist. In other words, |config_has_section| will return false for
15//   empty sections.
16// - Duplicate keys in a section will overwrite previous values.
17
18#include <stdbool.h>
19
20// The default section name to use if a key/value pair is not defined within
21// a section.
22#define CONFIG_DEFAULT_SECTION "Global"
23
24struct config_t;
25typedef struct config_t config_t;
26
27// Loads the specified file and returns a handle to the config file. If there
28// was a problem loading the file or allocating memory, this function returns
29// NULL. Clients must call |config_free| on the returned handle when it is no
30// longer required. |filename| must not be NULL and must point to a readable
31// file on the filesystem.
32config_t *config_new(const char *filename);
33
34// Frees resources associated with the config file. No further operations may
35// be performed on the |config| object after calling this function. |config|
36// may be NULL.
37void config_free(config_t *config);
38
39// Returns true if the config file contains a section named |section|. If
40// the section has no key/value pairs in it, this function will return false.
41// |config| and |section| must not be NULL.
42bool config_has_section(const config_t *config, const char *section);
43
44// Returns true if the config file has a key named |key| under |section|.
45// Returns false otherwise. |config|, |section|, and |key| must not be NULL.
46bool config_has_key(const config_t *config, const char *section, const char *key);
47
48// Returns the integral value for a given |key| in |section|. If |section|
49// or |key| do not exist, or the value cannot be fully converted to an integer,
50// this function returns |def_value|. |config|, |section|, and |key| must not
51// be NULL.
52int config_get_int(const config_t *config, const char *section, const char *key, int def_value);
53
54// Returns the boolean value for a given |key| in |section|. If |section|
55// or |key| do not exist, or the value cannot be converted to a boolean, this
56// function returns |def_value|. |config|, |section|, and |key| must not be NULL.
57bool config_get_bool(const config_t *config, const char *section, const char *key, bool def_value);
58
59// Returns the string value for a given |key| in |section|. If |section| or
60// |key| do not exist, this function returns |def_value|. The returned string
61// is owned by the config module and must not be freed. |config|, |section|,
62// and |key| must not be NULL. |def_value| may be NULL.
63const char *config_get_string(const config_t *config, const char *section, const char *key, const char *def_value);
64
65// Sets an integral value for the |key| in |section|. If |key| or |section| do
66// not already exist, this function creates them. |config|, |section|, and |key|
67// must not be NULL.
68void config_set_int(config_t *config, const char *section, const char *key, int value);
69
70// Sets a boolean value for the |key| in |section|. If |key| or |section| do
71// not already exist, this function creates them. |config|, |section|, and |key|
72// must not be NULL.
73void config_set_bool(config_t *config, const char *section, const char *key, bool value);
74
75// Sets a string value for the |key| in |section|. If |key| or |section| do
76// not already exist, this function creates them. |config|, |section|, |key|, and
77// |value| must not be NULL.
78void config_set_string(config_t *config, const char *section, const char *key, const char *value);
79