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 "lc_printf.h"
34 * The type of an option.
42 lc_opt_type_negboolean,
53 lc_opt_err_no_callback,
54 lc_opt_err_illegal_option_type,
55 lc_opt_err_illegal_format,
56 lc_opt_err_grp_not_found,
57 lc_opt_err_opt_not_found,
58 lc_opt_err_grp_expected,
59 lc_opt_err_opt_already_there,
60 lc_opt_err_file_not_found,
61 lc_opt_err_unknown_value
70 #define lc_opt_is_error(err) ((err)->error != lc_opt_err_none)
72 typedef struct lc_opt_entry_t lc_opt_entry_t;
74 typedef int (lc_opt_callback_t)(const char *name, lc_opt_type_t type, void *data, size_t length, ...);
76 typedef int (lc_opt_dump_t)(char *buf, size_t n, const char *name, lc_opt_type_t type, void *data, size_t length);
78 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);
80 typedef int (lc_opt_error_handler_t)(const char *prefix, const lc_opt_err_info_t *err);
83 const char *name; /**< The name of the option. */
84 const char *desc; /**< A description for the option. */
85 lc_opt_type_t type; /**< The type of the option (see enum). */
86 void *value; /**< A pointer to the area, where the value
87 of the option shall be put to. May be
90 size_t len; /**< The amount of bytes available at the
91 location value points to. */
92 lc_opt_callback_t *cb; /**< A callback that is called, when the
93 option is set. This may never be NULL. */
95 lc_opt_dump_t *dump; /**< A function which is able to format the
96 options value into a string. May be
99 lc_opt_dump_vals_t *dump_vals; /**< A function which is able to format the possible values
100 for this option into a string. May be NULL. */
103 } lc_opt_table_entry_t;
105 #define _LC_OPT_ENT(name, desc, type, value, len, cb, dump, dump_vals) \
106 { name, desc, type, value, len, cb, dump, dump_vals }
108 #define LC_OPT_ENT_INT(name, desc, addr) \
109 _LC_OPT_ENT(name, desc, lc_opt_type_int, addr, 0, lc_opt_std_cb, lc_opt_std_dump, NULL)
111 #define LC_OPT_ENT_DBL(name, desc, addr) \
112 _LC_OPT_ENT(name, desc, lc_opt_type_double, addr, 0, lc_opt_std_cb, lc_opt_std_dump, NULL)
114 #define LC_OPT_ENT_BIT(name, desc, addr, mask) \
115 _LC_OPT_ENT(name, desc, lc_opt_type_bit, addr, mask, lc_opt_std_cb, lc_opt_std_dump, NULL)
117 #define LC_OPT_ENT_NEGBIT(name, desc, addr, mask) \
118 _LC_OPT_ENT(name, desc, lc_opt_type_negbit, addr, mask, lc_opt_std_cb, lc_opt_std_dump, NULL)
120 #define LC_OPT_ENT_BOOL(name, desc, addr) \
121 _LC_OPT_ENT(name, desc, lc_opt_type_boolean, addr, 0, lc_opt_std_cb, lc_opt_std_dump, lc_opt_bool_dump_vals)
123 #define LC_OPT_ENT_NEGBOOL(name, desc, addr) \
124 _LC_OPT_ENT(name, desc, lc_opt_type_negboolean, addr, 0, lc_opt_std_cb, lc_opt_std_dump, lc_opt_bool_dump_vals)
126 #define LC_OPT_ENT_STR(name, desc, buf, len) \
127 _LC_OPT_ENT(name, desc, lc_opt_type_string, buf, len, lc_opt_std_cb, lc_opt_std_dump, NULL)
129 #define LC_OPT_ENT_CB(name, desc, type, data, len, cb, dump, dump_vals) \
130 _LC_OPT_ENT(name, desc, type, data, len, cb, dump, dump_vals)
132 #define LC_OPT_LAST \
133 _LC_OPT_ENT(NULL, NULL, lc_opt_type_invalid, NULL, 0, NULL, NULL, NULL)
136 * Get the root option group.
137 * @return The root option group.
139 lc_opt_entry_t *lc_opt_root_grp(void);
142 * Check, if a group is the root group
143 * @param ent The entry to check for.
144 * @return 1, if the entry is the root group, 0 otherwise.
146 int lc_opt_grp_is_root(const lc_opt_entry_t *ent);
149 * Get an option group.
150 * If the group is not already present, it is created.
151 * @param parent The parent group to look in.
152 * @param name The name of the group to lookup
153 * @return The already present or created group.
155 lc_opt_entry_t *lc_opt_get_grp(lc_opt_entry_t *parent, const char *name);
158 * Add an option to a group.
159 * @param grp The group to add the option to.
160 * @param name The name of the option (must be unique inside the group).
161 * @param desc A description of the option.
162 * @param type The data type of the option (see lc_opt_type_*)
163 * @param value A pointer to the memory, where the value shall be stored.
165 * @param length Amount of bytes available at the memory location
166 * indicated by @p value.
167 * @param cb A callback function to be called, as the option's value
168 * is set (may be NULL).
169 * @param err Error information to be set (may be NULL).
170 * @return The handle for the option.
172 lc_opt_entry_t *lc_opt_add_opt(lc_opt_entry_t *grp,
176 void *value, size_t length,
177 lc_opt_callback_t *cb,
179 lc_opt_dump_vals_t *dump_vals,
180 lc_opt_err_info_t *err);
182 int lc_opt_std_cb(const char *name, lc_opt_type_t type, void *data, size_t length, ...);
184 int lc_opt_std_dump(char *buf, size_t n, const char *name, lc_opt_type_t type, void *data, size_t length);
186 int lc_opt_bool_dump_vals(char *buf, size_t n, const char *name, lc_opt_type_t type, void *data, size_t length);
188 #define lc_opt_add_opt_int(grp, name, desc, value, err) \
189 lc_opt_add_opt(grp, name, desc, lc_opt_type_int, value, 0, lc_opt_std_cb, lc_opt_std_dump, NULL, err)
191 #define lc_opt_add_opt_double(grp, name, desc, value, err) \
192 lc_opt_add_opt(grp, name, desc, lc_opt_type_double, value, 0, lc_opt_std_cb, lc_opt_std_dump, NULL, err)
194 #define lc_opt_add_opt_string(grp, name, desc, buf, len, err) \
195 lc_opt_add_opt(grp, name, desc, lc_opt_type_string, buf, len, lc_opt_std_cb, lc_opt_std_dump, NULL, err)
197 #define lc_opt_add_opt_bit(grp, name, desc, value, mask, err) \
198 lc_opt_add_opt(grp, name, desc, lc_opt_type_bit, value, mask, lc_opt_std_cb, lc_opt_std_dump, NULL, err)
202 * Find a group inside another group.
203 * @param grp The group to search inside.
204 * @param name The name of the group you are looking for.
205 * @param err Error info (may be NULL).
206 * @return The group or NULL, if no such group can be found.
208 lc_opt_entry_t *lc_opt_find_grp(const lc_opt_entry_t *grp, const char *name, lc_opt_err_info_t *err);
211 * Find an option inside another group.
212 * @param grp The group to search inside.
213 * @param name The name of the option you are looking for.
214 * @param err Error info (may be NULL).
215 * @return The group or NULL, if no such option can be found.
217 lc_opt_entry_t *lc_opt_find_opt(const lc_opt_entry_t *grp, const char *name, lc_opt_err_info_t *err);
221 * @param root The group to start resolving from.
222 * @param names A string array containing the path to the group.
223 * @param n Number of entries in @p names to consider.
224 * @param err Error information (may be NULL).
225 * @return The group or NULL, if none is found.
227 lc_opt_entry_t *lc_opt_resolve_grp(const lc_opt_entry_t *root,
228 const char * const *names, int n, lc_opt_err_info_t *err);
232 * @param root The group to start resolving from.
233 * @param names A string array containing the path to the option.
234 * @param n Number of entries in @p names to consider.
235 * @param err Error information (may be NULL).
236 * @return The option or NULL, if none is found.
238 lc_opt_entry_t *lc_opt_resolve_opt(const lc_opt_entry_t *root,
239 const char * const *names, int n, lc_opt_err_info_t *err);
242 * Set the value of an option.
243 * @param opt The option to set.
244 * @param value The value of the option in a string representation.
245 * @param err Error information (may be NULL).
246 * @return 0, if an error occurred, 1 else.
248 int lc_opt_occurs(lc_opt_entry_t *opt, const char *value, lc_opt_err_info_t *err);
251 * Convert the option to a string representation.
252 * @param buf The string buffer to put the string representation to.
253 * @param len The length of @p buf.
254 * @param ent The option to process.
257 char *lc_opt_value_to_string(char *buf, size_t len, const lc_opt_entry_t *ent);
260 * Get the name of the type of an option.
261 * @param ent The option.
262 * @return The name of the type of the option.
264 const char *lc_opt_get_type_name(const lc_opt_entry_t *ent);
267 * Print the help screen for the given entity to the given file.
269 void lc_opt_print_help(lc_opt_entry_t *ent, FILE *f);
272 * Print the help screen for the given entity to the given file.
273 * Use separator instead of '.' and ignore entities above ent,
274 * i.e. if ent is root.be and has option isa.mach, prints
275 * isa<separator>mach instead of root.be.isa.mach
277 void lc_opt_print_help_for_entry(lc_opt_entry_t *ent, char separator, FILE *f);
279 void lc_opt_print_tree(lc_opt_entry_t *ent, FILE *f);
281 int lc_opt_add_table(lc_opt_entry_t *grp, const lc_opt_table_entry_t *table);
284 * The same as lc_opt_from_single_arg() only for an array of arguments.
286 int lc_opt_from_argv(const lc_opt_entry_t *root,
287 const char *opt_prefix,
288 int argc, const char *argv[],
289 lc_opt_error_handler_t *handler);
292 * Set options from a single (command line) argument.
293 * @param root The root group we start resolving from.
294 * @param opt_prefix The option prefix which shall be stripped of (mostly --).
295 * @param arg The command line argument itself.
296 * @param handler An error handler.
297 * @return 1, if the argument was set, 0 if not.
299 int lc_opt_from_single_arg(const lc_opt_entry_t *grp,
300 const char *opt_prefix,
302 lc_opt_error_handler_t *handler);
305 * Get printf environment for the option module.
306 * Currently implemented options are:
307 * %{opt:value} (%V) Value of an option.
308 * %{opt:type} (%T) Type of an option.
309 * %{opt:name} (%O) Name of an option.
310 * %{opt:desc} (%D) Description of an option.
311 * @return The option printf environment.
313 const lc_arg_env_t *lc_opt_get_arg_env(void);