2 libcore: library for basic data structures and algorithms.
3 Copyright (C) 2005 IPD Goos, Universit"at Karlsruhe, Germany
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Lesser General Public
7 License as published by the Free Software Foundation; either
8 version 2.1 of the License, or (at your option) any later version.
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Lesser General Public License for more details.
15 You should have received a copy of the GNU Lesser General Public
16 License along with this library; if not, write to the Free Software
17 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
21 Option management library.
22 This module can read (typed) options from a config file or
23 parse a command line. The options are managed in a tree structure.
31 #include <libcore/lc_printf.h>
34 * The type of an option.
41 lc_opt_type_negboolean,
52 lc_opt_err_no_callback,
53 lc_opt_err_illegal_option_type,
54 lc_opt_err_illegal_format,
55 lc_opt_err_grp_not_found,
56 lc_opt_err_opt_not_found,
57 lc_opt_err_grp_expected,
58 lc_opt_err_opt_already_there,
59 lc_opt_err_file_not_found,
60 lc_opt_err_unknown_value
69 #define lc_opt_is_error(err) ((err)->error != lc_opt_err_none)
71 typedef struct _lc_opt_entry_t lc_opt_entry_t;
73 typedef int (lc_opt_callback_t)(const char *name, lc_opt_type_t type, void *data, size_t length, ...);
75 typedef int (lc_opt_dump_t)(char *buf, size_t n, const char *name, lc_opt_type_t type, void *data, size_t length);
77 typedef int (lc_opt_dump_vals_t)(char *buf, size_t n, const char *name, lc_opt_type_t type, void *data, size_t length);
79 typedef int (lc_opt_error_handler_t)(const char *prefix, const lc_opt_err_info_t *err);
82 const char *name; /**< The name of the option. */
83 const char *desc; /**< A description for the option. */
84 lc_opt_type_t type; /**< The type of the option (see enum). */
85 void *value; /**< A pointer to the area, where the value
86 of the option shall be put to. May be NULL. */
88 size_t len; /**< The amount of bytes available at the
89 location value points to. */
90 lc_opt_callback_t *cb; /**< A callback that is called, when the option is set.
91 This may never be NULL. */
93 lc_opt_dump_t *dump; /**< A function which is able to format the options value
94 into a string. May be NULL. */
96 lc_opt_dump_vals_t *dump_vals; /**< A function which is able to format the possible values
97 for this option into a string. May be NULL. */
100 } lc_opt_table_entry_t;
102 #define _LC_OPT_ENT(name, desc, type, value, len, cb, dump, dump_vals) \
103 { name, desc, type, value, len, cb, dump, dump_vals }
105 #define LC_OPT_ENT_INT(name, desc, addr) \
106 _LC_OPT_ENT(name, desc, lc_opt_type_int, addr, 0, lc_opt_std_cb, lc_opt_std_dump, NULL)
108 #define LC_OPT_ENT_DBL(name, desc, addr) \
109 _LC_OPT_ENT(name, desc, lc_opt_type_double, addr, 0, lc_opt_std_cb, lc_opt_std_dump, NULL)
111 #define LC_OPT_ENT_BIT(name, desc, addr, mask) \
112 _LC_OPT_ENT(name, desc, lc_opt_type_bit, addr, mask, lc_opt_std_cb, lc_opt_std_dump, NULL)
114 #define LC_OPT_ENT_NEGBIT(name, desc, addr, mask) \
115 _LC_OPT_ENT(name, desc, lc_opt_type_negbit, addr, mask, lc_opt_std_cb, lc_opt_std_dump, NULL)
117 #define LC_OPT_ENT_BOOL(name, desc, addr) \
118 _LC_OPT_ENT(name, desc, lc_opt_type_boolean, addr, 0, lc_opt_std_cb, lc_opt_std_dump, lc_opt_bool_dump_vals)
120 #define LC_OPT_ENT_NEGBOOL(name, desc, addr) \
121 _LC_OPT_ENT(name, desc, lc_opt_type_negboolean, addr, 0, lc_opt_std_cb, lc_opt_std_dump, lc_opt_bool_dump_vals)
123 #define LC_OPT_ENT_STR(name, desc, buf, len) \
124 _LC_OPT_ENT(name, desc, lc_opt_type_string, buf, len, lc_opt_std_cb, lc_opt_std_dump, NULL)
126 #define LC_OPT_ENT_CB(name, desc, type, data, len, cb, dump, dump_vals) \
127 _LC_OPT_ENT(name, desc, type, data, len, cb, dump, dump_vals)
129 #define LC_OPT_LAST \
130 _LC_OPT_ENT(NULL, NULL, 0, NULL, 0, NULL, NULL, NULL)
133 * Get the root option group.
134 * @return The root option group.
136 lc_opt_entry_t *lc_opt_root_grp(void);
139 * Check, if a group is the root group
140 * @param ent The entry to check for.
141 * @return 1, if the entry is the root group, 0 otherwise.
143 int lc_opt_grp_is_root(const lc_opt_entry_t *ent);
146 * Get an option group.
147 * If the group is not already present, it is created.
148 * @param parent The parent group to look in.
149 * @param name The name of the group to lookup
150 * @return The already present or created group.
152 lc_opt_entry_t *lc_opt_get_grp(lc_opt_entry_t *parent, const char *name);
155 * Add an option to a group.
156 * @param grp The group to add the option to.
157 * @param name The name of the option (must be unique inside the group).
158 * @param desc A description of the option.
159 * @param type The data type of the option (see lc_opt_type_*)
160 * @param value A pointer to the memory, where the value shall be stored.
162 * @param length Amount of bytes available at the memory location
163 * indicated by @p value.
164 * @param cb A callback function to be called, as the option's value
165 * is set (may be NULL).
166 * @param err Error information to be set (may be NULL).
167 * @return The handle for the option.
169 lc_opt_entry_t *lc_opt_add_opt(lc_opt_entry_t *grp,
173 void *value, size_t length,
174 lc_opt_callback_t *cb,
176 lc_opt_dump_vals_t *dump_vals,
177 lc_opt_err_info_t *err);
179 int lc_opt_std_cb(const char *name, lc_opt_type_t type, void *data, size_t length, ...);
181 int lc_opt_std_dump(char *buf, size_t n, const char *name, lc_opt_type_t type, void *data, size_t length);
183 int lc_opt_bool_dump_vals(char *buf, size_t n, const char *name, lc_opt_type_t type, void *data, size_t length);
185 #define lc_opt_add_opt_int(grp, name, desc, value, err) \
186 lc_opt_add_opt(grp, name, desc, lc_opt_type_int, value, 0, lc_opt_std_cb, lc_opt_std_dump, NULL, err)
188 #define lc_opt_add_opt_double(grp, name, desc, value, err) \
189 lc_opt_add_opt(grp, name, desc, lc_opt_type_double, value, 0, lc_opt_std_cb, lc_opt_std_dump, NULL, err)
191 #define lc_opt_add_opt_string(grp, name, desc, buf, len, err) \
192 lc_opt_add_opt(grp, name, desc, lc_opt_type_string, buf, len, lc_opt_std_cb, lc_opt_std_dump, NULL, err)
194 #define lc_opt_add_opt_bit(grp, name, desc, value, mask, err) \
195 lc_opt_add_opt(grp, name, desc, lc_opt_type_bit, value, mask, lc_opt_std_cb, lc_opt_std_dump, NULL, err)
199 * Find a group inside another group.
200 * @param grp The group to search inside.
201 * @param name The name of the group you are looking for.
202 * @param err Error info (may be NULL).
203 * @return The group or NULL, if no such group can be found.
205 lc_opt_entry_t *lc_opt_find_grp(const lc_opt_entry_t *grp, const char *name, lc_opt_err_info_t *err);
208 * Find an option inside another group.
209 * @param grp The group to search inside.
210 * @param name The name of the option you are looking for.
211 * @param err Error info (may be NULL).
212 * @return The group or NULL, if no such option can be found.
214 lc_opt_entry_t *lc_opt_find_opt(const lc_opt_entry_t *grp, const char *name, lc_opt_err_info_t *err);
218 * @param root The group to start resolving from.
219 * @param names A string array containing the path to the group.
220 * @param n Number of entries in @p names to consider.
221 * @param err Error information (may be NULL).
222 * @return The group or NULL, if none is found.
224 lc_opt_entry_t *lc_opt_resolve_grp(const lc_opt_entry_t *root,
225 const char * const *names, int n, lc_opt_err_info_t *err);
229 * @param root The group to start resolving from.
230 * @param names A string array containing the path to the option.
231 * @param n Number of entries in @p names to consider.
232 * @param err Error information (may be NULL).
233 * @return The option or NULL, if none is found.
235 lc_opt_entry_t *lc_opt_resolve_opt(const lc_opt_entry_t *root,
236 const char * const *names, int n, lc_opt_err_info_t *err);
239 * Set the value of an option.
240 * @param opt The option to set.
241 * @param value The value of the option in a string representation.
242 * @param err Error information (may be NULL).
243 * @return 0, if an error occurred, 1 else.
245 int lc_opt_occurs(lc_opt_entry_t *opt, const char *value, lc_opt_err_info_t *err);
248 * Convert the option to a string representation.
249 * @param buf The string buffer to put the string representation to.
250 * @param len The length of @p buf.
251 * @param ent The option to process.
254 char *lc_opt_value_to_string(char *buf, size_t len, const lc_opt_entry_t *ent);
257 * Get the name of the type of an option.
258 * @param ent The option.
259 * @return The name of the type of the option.
261 const char *lc_opt_get_type_name(const lc_opt_entry_t *ent);
264 * Print the help screen for the given entity to the given file.
266 void lc_opt_print_help(lc_opt_entry_t *ent, FILE *f);
269 * Print the help screen for the given entity to the given file.
270 * Use separator instead of '.' and ignore entities above ent,
271 * i.e. if ent is root.be and has option isa.mach, prints
272 * isa<separator>mach instead of root.be.isa.mach
274 void lc_opt_print_help_for_entry(lc_opt_entry_t *ent, char separator, FILE *f);
276 void lc_opt_print_tree(lc_opt_entry_t *ent, FILE *f);
278 int lc_opt_add_table(lc_opt_entry_t *grp, const lc_opt_table_entry_t *table);
280 void lc_opt_from_file(const char *filenmame, FILE *f, lc_opt_error_handler_t *handler);
283 * The same as lc_opt_from_single_arg() only for an array of arguments.
285 int lc_opt_from_argv(const lc_opt_entry_t *root,
286 const char *opt_prefix,
287 int argc, const char *argv[],
288 lc_opt_error_handler_t *handler);
291 * Set options from a single (command line) argument.
292 * @param root The root group we start resolving from.
293 * @param opt_prefix The option prefix which shall be stripped of (mostly --).
294 * @param arg The command line argument itself.
295 * @param handler An error handler.
296 * @return 1, if the argument was set, 0 if not.
298 int lc_opt_from_single_arg(const lc_opt_entry_t *grp,
299 const char *opt_prefix,
301 lc_opt_error_handler_t *handler);
304 * Get printf environment for the option module.
305 * Currently implemented options are:
306 * %{opt:value} (%V) Value of an option.
307 * %{opt:type} (%T) Type of an option.
308 * %{opt:name} (%O) Name of an option.
309 * %{opt:desc} (%D) Description of an option.
310 * @return The option printf environment.
312 const lc_arg_env_t *lc_opt_get_arg_env(void);
315 * Standard procedure for options initialization.
316 * @param cmnt_name Base name for the file.
317 * @param root The option's root.
318 * @param arg_prefix A prefix that is added to each option.
319 * @param argc Number of entries in @p argv.
320 * @param argv A stadard argument vector.
322 * This function tries to open a ini file in the user's homedir
323 * (On win32 this is \Documents and Settings\Application Data)
324 * which is called .<ini_name>rc (on win32 <ini_name>.ini)
326 * and an ini file in the current directory which is called <ini_name>.ini on
328 * Afterwards, the argument vectors are processed.
330 void lc_opts_init(const char *ini_name, lc_opt_entry_t *root, const char *arg_prefix, int argc, const char **argv);