Lumiera  0.pre.03
»edityourfreedom«
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
config.h
Go to the documentation of this file.
1 /*
2  CONFIG.h - Lumiera configuration system
3 
4  Copyright (C) Lumiera.org
5  2008, Christian Thaeter <ct@pipapo.org>
6 
7  This program is free software; you can redistribute it and/or
8  modify it under the terms of the GNU General Public License as
9  published by the Free Software Foundation; either version 2 of
10  the License, or (at your option) any later version.
11 
12  This program is distributed in the hope that it will be useful,
13  but WITHOUT ANY WARRANTY; without even the implied warranty of
14  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15  GNU General Public License for more details.
16 
17  You should have received a copy of the GNU General Public License
18  along with this program; if not, write to the Free Software
19  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
20 
21 */
22 
23 
42 #ifndef COMMON_CONFIG_H
43 #define COMMON_CONFIG_H
44 
45 #include "lib/error.h"
46 #include "lib/mutex.h"
47 #include "common/config-lookup.h"
48 #include "common/configitem.h"
49 
50 #include <nobug.h>
51 #include <stdio.h>
52 
53 
54 LUMIERA_ERROR_DECLARE (CONFIG_SYNTAX);
55 LUMIERA_ERROR_DECLARE (CONFIG_SYNTAX_KEY);
56 LUMIERA_ERROR_DECLARE (CONFIG_SYNTAX_VALUE);
57 LUMIERA_ERROR_DECLARE (CONFIG_NO_ENTRY);
58 
59 #define LUMIERA_CONFIG_KEY_CHARS "abcdefghijklmnopqrstuvwxyz0123456789_."
60 #define LUMIERA_CONFIG_ENV_CHARS "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789__"
61 
62 
63 
65 {
66  lumiera_config_lookup keys;
67 
68  lumiera_configitem defaults; /* registered default values */
69  lumiera_configitem files; /* all loaded files */
70  lumiera_configitem TODO_unknown; /* all values which are not part of a file and not default TODO: this will be removed when file support is finished */
71 
72  lumiera_mutex lock;
73 };
74 
75 typedef struct lumiera_config_struct lumiera_config;
76 typedef lumiera_config* LumieraConfig;
77 
81 /* TODO: add here as 'LUMIERA_CONFIG_TYPE(name, ctype)' the _get/_set prototypes are declared automatically below, you still have to implement them in config.c */
82 #define LUMIERA_CONFIG_TYPES \
83  LUMIERA_CONFIG_TYPE(link, const char*) \
84  LUMIERA_CONFIG_TYPE(number, long long) \
85  LUMIERA_CONFIG_TYPE(real, long double) \
86  LUMIERA_CONFIG_TYPE(string, const char*) \
87  LUMIERA_CONFIG_TYPE(wordlist, const char*) \
88  LUMIERA_CONFIG_TYPE(word, const char*) \
89  LUMIERA_CONFIG_TYPE(bool, int)
90 
91 
97 int
98 lumiera_config_init (const char* path);
99 
100 
101 
106 void
108 
109 
110 // * reads '''one''' single configuration file that will include all settings from other files.
111 // * does not read itself but give delegates reading. The actual reading and parsing will be done in configfile object. s.later.
115 int
116 lumiera_config_load (const char* file);
117 
118 
119 //{{{ lumiera_config_save () { LLIST_FOREACH(config_singleton.files, f) { LumieraFile file = (LumieraFile) f; if(lumiera_configfile_isdirty (file)) lumiera_configfile_save(file); } } }}}
120 // * saves all the changed settings to user's configuration files, but recognizes where settings came from and will write them to an appropriate named file. Example: '''changed''' values from ''/usr/local/share/lumiera/plugins/blur.conf'' will be saved into ''~/.lumiera/plugins/blur.conf''
121 // * finds out which files are dirty and which settings have to be written to user's config files.
122 // * does initiate the actual saving procedure by delegating the save to the actual configfile objects, see below.
123 // * empty user configuration files in RAM will be deleted from disk on write.
124 // * checks whether the file has changed since last read, and will print out an error if necessary instead of overriding it without notification.
128 int
130 
131 
132 // * `lumiera_config_purge(const char* filename)` removes all configs loaded from filename
136 int
137 lumiera_config_purge (const char* filename);
138 
139 
143 void
144 lumiera_config_dump (FILE* out);
145 
146 
147 // * {{{ lumiera_config_get(...) }}}
148 // * get a value by key
149 // * handles internally everything as string:string key:value pair.
150 // * lowlevel function
151 // * lumiera_config_integer_get (const char* key, int *value) will return integers instead of strings and return 0 if succeeded and -1 if it failed.
155 const char*
156 lumiera_config_get (const char* key, const char** value);
157 
158 
159 const char*
160 lumiera_config_get_default (const char* key, const char** value);
161 
162 
163 // * {{{ lumiera_config_set(...) }}}
164 // * set a value by key
165 // * handles internally everything as string:string key:value pair.
166 // * lowlevel function
167 // * tag file as dirty
168 // * set will create a new user configuration file if it does not exist yet or will append a line to the existing one in RAM. These files, tagged as 'dirty', will be only written if save() is called.
169 
178 lumiera_config_set (const char* key, const char* delim_value);
179 
180 
190 lumiera_config_setdefault (const char* line);
191 
192 
193 
194 // * {{{int lumiera_config_TYPE_get(const char* key, TYPE* value, const char* default) }}}
195 // High level config interface for different types.
196 // if default is given (!NULL) then value is set to default in case key was not found or any other error occurred.
197 // error code is still set and -1 (fail) is returned in case of an error, but it might be cleared with no ill effects.
198 // NOTE: errors are persistent in our error handler, they must still be cleared, even when ignored.
199 // if default is given then 'KEY_NOT_FOUND' is not a error here, if default is NULL then it is
200 // NOTE2: default values are given as strings, the config loader remembers a given default value and checks if it got changed
201 // when it is _set(). Thus a default value can be suppressed when set/written
205 #define LUMIERA_CONFIG_TYPE(name, type) \
206  const char* \
207  lumiera_config_##name##_get (const char* key, type* value);
209 #undef LUMIERA_CONFIG_TYPE
210 
225 const char*
226 lumiera_config_wordlist_get_nth (const char* key, unsigned nth, const char* delims);
227 
228 
236 int
237 lumiera_config_wordlist_find (const char* key, const char* value, const char* delims);
238 
239 
253 const char*
254 lumiera_config_wordlist_replace (const char* key, const char* value, const char* subst1, const char* subst2, const char* delims);
255 
256 
264 const char*
265 lumiera_config_wordlist_add (const char* key, const char* value, const char* delims);
266 
267 // * {{{ lumiera_config_TYPE_set (const char* key, TYPE*value, const char* fmt) }}}
268 // Highlevel interface for different types, fmt is a printf format specifier for the desired format, when NULL, defaults apply.
272 #define LUMIERA_CONFIG_TYPE(name, type) \
273  LumieraConfigitem \
274  lumiera_config_##name##_set (const char* key, type* value);
276 #undef LUMIERA_CONFIG_TYPE
277 
278 
279 
280 // * {{{ lumiera_config_reset(...) }}}
281 // * reset a value by key to the system default values, thus removes a user's configuration line.
285 int
286 lumiera_config_reset (const char* key);
287 
288 
289 // * Find exact place of a setting.
293 int
294 lumiera_config_info (const char* key, const char** filename, unsigned* line);
295 
296 #endif /*COMMON_CONFIG_H*/
297 /*
298 // Local Variables:
299 // mode: C
300 // c-file-style: "gnu"
301 // indent-tabs-mode: nil
302 // End:
303 */
LUMIERA_CONFIG_TYPES const char * lumiera_config_wordlist_get_nth(const char *key, unsigned nth, const char *delims)
Wordlists Wordlists are lists of single words delimited by any of " \t,;".
int lumiera_config_info(const char *key, const char **filename, unsigned *line)
Definition: config.c:341
Draft for a configuration system (2008).
const char * lumiera_config_wordlist_replace(const char *key, const char *value, const char *subst1, const char *subst2, const char *delims)
Universal word replacement function.
void lumiera_config_destroy()
Destroys the configuration subsystem.
Definition: config.c:114
int lumiera_config_load(const char *file)
Definition: config.c:133
lumiera_configitem * LumieraConfigitem
Definition: configitem.h:62
int lumiera_config_wordlist_find(const char *key, const char *value, const char *delims)
Find the index of a word in a wordlist.
const char * lumiera_config_get(const char *key, const char **value)
Definition: config.c:163
#define LUMIERA_CONFIG_TYPES
Supported high level types: TODO documenting.
Definition: config.h:82
lumiera_config_lookup keys
Definition: config.h:66
int lumiera_config_purge(const char *filename)
Definition: config.c:152
Lumiera error handling (C interface).
int lumiera_config_init(const char *path)
Initialise the configuration subsystem.
Definition: config.c:86
Lookup of configuration keys in a low-level configuration system.
LumieraConfigitem lumiera_config_set(const char *key, const char *delim_value)
Definition: config.c:232
LUMIERA_CONFIG_TYPES int lumiera_config_reset(const char *key)
Definition: config.c:331
Mutual exclusion locking, header.
lumiera_config * LumieraConfig
Definition: config.h:76
lumiera_configitem files
Definition: config.h:69
void lumiera_config_dump(FILE *out)
Does a diagnostic dump of the whole config database.
Definition: config.c:312
const char * lumiera_config_wordlist_add(const char *key, const char *value, const char *delims)
Add a word to the end of a wordlist if it doesn't exist already.
LUMIERA_ERROR_DECLARE(CONFIG_SYNTAX)
lumiera_mutex lock
Definition: config.h:72
int lumiera_config_save()
Definition: config.c:143
lumiera_configitem TODO_unknown
Definition: config.h:70
LumieraConfigitem lumiera_config_setdefault(const char *line)
Installs a default value for a config key.
Definition: config.c:274
const char * lumiera_config_get_default(const char *key, const char **value)
Definition: config.c:210
lumiera_configitem defaults
Definition: config.h:68