2 * This file is part of libFirm.
3 * Copyright (C) 2012 IPD Goos, Universit"at Karlsruhe, Germany
7 Option management library.
8 This module can read (typed) options from a config file or
9 parse a command line. The options are managed in a tree structure.
17 #include "lc_printf.h"
20 * The type of an option.
37 lc_opt_err_no_callback,
38 lc_opt_err_illegal_option_type,
39 lc_opt_err_illegal_format,
40 lc_opt_err_grp_not_found,
41 lc_opt_err_opt_not_found,
42 lc_opt_err_grp_expected,
43 lc_opt_err_opt_already_there,
44 lc_opt_err_file_not_found,
45 lc_opt_err_unknown_value
54 #define lc_opt_is_error(err) ((err)->error != lc_opt_err_none)
56 typedef struct lc_opt_entry_t lc_opt_entry_t;
58 typedef int (lc_opt_callback_t)(const char *name, lc_opt_type_t type, void *data, size_t length, ...);
60 typedef int (lc_opt_dump_t)(char *buf, size_t n, const char *name, lc_opt_type_t type, void *data, size_t length);
62 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);
64 typedef int (lc_opt_error_handler_t)(const char *prefix, const lc_opt_err_info_t *err);
67 const char *name; /**< The name of the option. */
68 const char *desc; /**< A description for the option. */
69 lc_opt_type_t type; /**< The type of the option (see enum). */
70 void *value; /**< A pointer to the area, where the value
71 of the option shall be put to. May be
74 size_t len; /**< The amount of bytes available at the
75 location value points to. */
76 lc_opt_callback_t *cb; /**< A callback that is called, when the
77 option is set. This may never be NULL. */
79 lc_opt_dump_t *dump; /**< A function which is able to format the
80 options value into a string. May be
83 lc_opt_dump_vals_t *dump_vals; /**< A function which is able to format the possible values
84 for this option into a string. May be NULL. */
87 } lc_opt_table_entry_t;
89 #define _LC_OPT_ENT(name, desc, type, val_type, value, len, cb, dump, dump_vals) \
90 { name, desc, type, 1 ? (value) : (val_type*)0 /* Produces a warning, if var has wrong type. */, len, cb, dump, dump_vals }
92 #define LC_OPT_ENT_INT(name, desc, addr) \
93 _LC_OPT_ENT(name, desc, lc_opt_type_int, int, addr, 0, lc_opt_std_cb, lc_opt_std_dump, NULL)
95 #define LC_OPT_ENT_DBL(name, desc, addr) \
96 _LC_OPT_ENT(name, desc, lc_opt_type_double, double, addr, 0, lc_opt_std_cb, lc_opt_std_dump, NULL)
98 #define LC_OPT_ENT_BIT(name, desc, addr, mask) \
99 _LC_OPT_ENT(name, desc, lc_opt_type_bit, unsigned, addr, mask, lc_opt_std_cb, lc_opt_std_dump, NULL)
101 #define LC_OPT_ENT_BOOL(name, desc, addr) \
102 _LC_OPT_ENT(name, desc, lc_opt_type_boolean, int, addr, 0, lc_opt_std_cb, lc_opt_std_dump, lc_opt_bool_dump_vals)
104 typedef char lc_opt_str_t[];
105 #define LC_OPT_ENT_STR(name, desc, buf) \
106 _LC_OPT_ENT(name, desc, lc_opt_type_string, lc_opt_str_t, buf, sizeof(*buf), lc_opt_std_cb, lc_opt_std_dump, NULL)
108 #define LC_OPT_LAST \
109 _LC_OPT_ENT(NULL, NULL, lc_opt_type_invalid, void, NULL, 0, NULL, NULL, NULL)
112 * Get the root option group.
113 * @return The root option group.
115 lc_opt_entry_t *lc_opt_root_grp(void);
118 * Check, if a group is the root group
119 * @param ent The entry to check for.
120 * @return 1, if the entry is the root group, 0 otherwise.
122 int lc_opt_grp_is_root(const lc_opt_entry_t *ent);
125 * Get an option group.
126 * If the group is not already present, it is created.
127 * @param parent The parent group to look in.
128 * @param name The name of the group to lookup
129 * @return The already present or created group.
131 lc_opt_entry_t *lc_opt_get_grp(lc_opt_entry_t *parent, const char *name);
134 * Add an option to a group.
135 * @param grp The group to add the option to.
136 * @param name The name of the option (must be unique inside the group).
137 * @param desc A description of the option.
138 * @param type The data type of the option (see lc_opt_type_*)
139 * @param value A pointer to the memory, where the value shall be stored.
141 * @param length Amount of bytes available at the memory location
142 * indicated by @p value.
143 * @param cb A callback function to be called, as the option's value
144 * is set (may be NULL).
145 * @param err Error information to be set (may be NULL).
146 * @return The handle for the option.
148 lc_opt_entry_t *lc_opt_add_opt(lc_opt_entry_t *grp,
152 void *value, size_t length,
153 lc_opt_callback_t *cb,
155 lc_opt_dump_vals_t *dump_vals,
156 lc_opt_err_info_t *err);
158 int lc_opt_std_cb(const char *name, lc_opt_type_t type, void *data, size_t length, ...);
160 int lc_opt_std_dump(char *buf, size_t n, const char *name, lc_opt_type_t type, void *data, size_t length);
162 int lc_opt_bool_dump_vals(char *buf, size_t n, const char *name, lc_opt_type_t type, void *data, size_t length);
164 #define lc_opt_add_opt_int(grp, name, desc, value, err) \
165 lc_opt_add_opt(grp, name, desc, lc_opt_type_int, value, 0, lc_opt_std_cb, lc_opt_std_dump, NULL, err)
167 #define lc_opt_add_opt_double(grp, name, desc, value, err) \
168 lc_opt_add_opt(grp, name, desc, lc_opt_type_double, value, 0, lc_opt_std_cb, lc_opt_std_dump, NULL, err)
170 #define lc_opt_add_opt_string(grp, name, desc, buf, len, err) \
171 lc_opt_add_opt(grp, name, desc, lc_opt_type_string, buf, len, lc_opt_std_cb, lc_opt_std_dump, NULL, err)
173 #define lc_opt_add_opt_bit(grp, name, desc, value, mask, err) \
174 lc_opt_add_opt(grp, name, desc, lc_opt_type_bit, value, mask, lc_opt_std_cb, lc_opt_std_dump, NULL, err)
178 * Find a group inside another group.
179 * @param grp The group to search inside.
180 * @param name The name of the group you are looking for.
181 * @param err Error info (may be NULL).
182 * @return The group or NULL, if no such group can be found.
184 lc_opt_entry_t *lc_opt_find_grp(const lc_opt_entry_t *grp, const char *name, lc_opt_err_info_t *err);
187 * Find an option inside another group.
188 * @param grp The group to search inside.
189 * @param name The name of the option you are looking for.
190 * @param err Error info (may be NULL).
191 * @return The group or NULL, if no such option can be found.
193 lc_opt_entry_t *lc_opt_find_opt(const lc_opt_entry_t *grp, const char *name, lc_opt_err_info_t *err);
197 * @param root The group to start resolving from.
198 * @param names A string array containing the path to the group.
199 * @param n Number of entries in @p names to consider.
200 * @param err Error information (may be NULL).
201 * @return The group or NULL, if none is found.
203 lc_opt_entry_t *lc_opt_resolve_grp(const lc_opt_entry_t *root,
204 const char * const *names, int n, lc_opt_err_info_t *err);
208 * @param root The group to start resolving from.
209 * @param names A string array containing the path to the option.
210 * @param n Number of entries in @p names to consider.
211 * @param err Error information (may be NULL).
212 * @return The option or NULL, if none is found.
214 lc_opt_entry_t *lc_opt_resolve_opt(const lc_opt_entry_t *root,
215 const char * const *names, int n, lc_opt_err_info_t *err);
218 * Set the value of an option.
219 * @param opt The option to set.
220 * @param value The value of the option in a string representation.
221 * @param err Error information (may be NULL).
222 * @return 0, if an error occurred, 1 else.
224 int lc_opt_occurs(lc_opt_entry_t *opt, const char *value, lc_opt_err_info_t *err);
227 * Convert the option to a string representation.
228 * @param buf The string buffer to put the string representation to.
229 * @param len The length of @p buf.
230 * @param ent The option to process.
233 char *lc_opt_value_to_string(char *buf, size_t len, const lc_opt_entry_t *ent);
236 * Get the name of the type of an option.
237 * @param ent The option.
238 * @return The name of the type of the option.
240 const char *lc_opt_get_type_name(const lc_opt_entry_t *ent);
243 * Print the help screen for the given entity to the given file.
245 void lc_opt_print_help(lc_opt_entry_t *ent, FILE *f);
248 * Print the help screen for the given entity to the given file.
249 * Use separator instead of '.' and ignore entities above ent,
250 * i.e. if ent is root.be and has option isa.mach, prints
251 * isa<separator>mach instead of root.be.isa.mach
253 void lc_opt_print_help_for_entry(lc_opt_entry_t *ent, char separator, FILE *f);
255 void lc_opt_print_tree(lc_opt_entry_t *ent, FILE *f);
257 int lc_opt_add_table(lc_opt_entry_t *grp, const lc_opt_table_entry_t *table);
260 * The same as lc_opt_from_single_arg() only for an array of arguments.
262 int lc_opt_from_argv(const lc_opt_entry_t *root,
263 const char *opt_prefix,
264 int argc, const char *argv[],
265 lc_opt_error_handler_t *handler);
268 * Set options from a single (command line) argument.
269 * @param root The root group we start resolving from.
270 * @param opt_prefix The option prefix which shall be stripped of (mostly --).
271 * @param arg The command line argument itself.
272 * @param handler An error handler.
273 * @return 1, if the argument was set, 0 if not.
275 int lc_opt_from_single_arg(const lc_opt_entry_t *grp,
276 const char *opt_prefix,
278 lc_opt_error_handler_t *handler);
281 * Get printf environment for the option module.
282 * Currently implemented options are:
283 * %{opt:value} (%V) Value of an option.
284 * %{opt:type} (%T) Type of an option.
285 * %{opt:name} (%O) Name of an option.
286 * %{opt:desc} (%D) Description of an option.
287 * @return The option printf environment.
289 const lc_arg_env_t *lc_opt_get_arg_env(void);