nsz Git - libfirm/blob - ir/libcore/lc_opts.h

   1 /*
   2  * This file is part of libFirm.
   3  * Copyright (C) 2012 IPD Goos, Universit"at Karlsruhe, Germany
   4  */
   5
   6 /*
   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.
  10 */
  11
  12 #ifndef _LC_OPTS_H
  13 #define _LC_OPTS_H
  14
  15 #include <stdio.h>
  16
  17 #include "lc_printf.h"
  18
  19 /**
  20  * The type of an option.
  21  */
  22 typedef enum {
  23         lc_opt_type_invalid,
  24         lc_opt_type_enum,
  25         lc_opt_type_bit,
  26         lc_opt_type_boolean,
  27         lc_opt_type_string,
  28         lc_opt_type_int,
  29         lc_opt_type_double
  30 } lc_opt_type_t;
  31
  32 /**
  33  * Error codes.
  34  */
  35 typedef enum {
  36         lc_opt_err_none = 0,
  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
  46 } lc_opt_err_t;
  47
  48 typedef struct {
  49         int error;
  50         const char *msg;
  51         const char *arg;
  52 } lc_opt_err_info_t;
  53
  54 #define lc_opt_is_error(err) ((err)->error != lc_opt_err_none)
  55
  56 typedef struct lc_opt_entry_t lc_opt_entry_t;
  57
  58 typedef int (lc_opt_callback_t)(const char *name, lc_opt_type_t type, void *data, size_t length, ...);
  59
  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);
  61
  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);
  63
  64 typedef int (lc_opt_error_handler_t)(const char *prefix, const lc_opt_err_info_t *err);
  65
  66 typedef struct {
  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
  72                                              NULL. */
  73
  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. */
  78
  79         lc_opt_dump_t *dump;            /**< A function which is able to format the
  80                                              options value into a string. May be
  81                                              NULL. */
  82
  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. */
  85
  86
  87 } lc_opt_table_entry_t;
  88
  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 }
  91
  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)
  94
  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)
  97
  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)
 100
 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)
 103
 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)
 107
 108 #define LC_OPT_LAST \
 109         _LC_OPT_ENT(NULL, NULL, lc_opt_type_invalid, void, NULL, 0, NULL, NULL, NULL)
 110
 111 /**
 112  * Get the root option group.
 113  * @return The root option group.
 114  */
 115 lc_opt_entry_t *lc_opt_root_grp(void);
 116
 117 /**
 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.
 121  */
 122 int lc_opt_grp_is_root(const lc_opt_entry_t *ent);
 123
 124 /**
 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.
 130  */
 131 lc_opt_entry_t *lc_opt_get_grp(lc_opt_entry_t *parent, const char *name);
 132
 133 /**
 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.
 140  *                  (May be NULL).
 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.
 147  */
 148 lc_opt_entry_t *lc_opt_add_opt(lc_opt_entry_t *grp,
 149                                const char *name,
 150                                const char *desc,
 151                                lc_opt_type_t type,
 152                                void *value, size_t length,
 153                                lc_opt_callback_t *cb,
 154                                lc_opt_dump_t *dump,
 155                                lc_opt_dump_vals_t *dump_vals,
 156                                lc_opt_err_info_t *err);
 157
 158 int lc_opt_std_cb(const char *name, lc_opt_type_t type, void *data, size_t length, ...);
 159
 160 int lc_opt_std_dump(char *buf, size_t n, const char *name, lc_opt_type_t type, void *data, size_t length);
 161
 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);
 163
 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)
 166
 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)
 169
 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)
 172
 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)
 175
 176
 177 /**
 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.
 183  */
 184 lc_opt_entry_t *lc_opt_find_grp(const lc_opt_entry_t *grp, const char *name, lc_opt_err_info_t *err);
 185
 186 /**
 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.
 192  */
 193 lc_opt_entry_t *lc_opt_find_opt(const lc_opt_entry_t *grp, const char *name, lc_opt_err_info_t *err);
 194
 195 /**
 196  * Resolve a group.
 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.
 202  */
 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);
 205
 206 /**
 207  * Resolve an option.
 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.
 213  */
 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);
 216
 217 /**
 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.
 223  */
 224 int lc_opt_occurs(lc_opt_entry_t *opt, const char *value, lc_opt_err_info_t *err);
 225
 226 /**
 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.
 231  * @return     @p buf.
 232  */
 233 char *lc_opt_value_to_string(char *buf, size_t len, const lc_opt_entry_t *ent);
 234
 235 /**
 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.
 239  */
 240 const char *lc_opt_get_type_name(const lc_opt_entry_t *ent);
 241
 242 /**
 243  * Print the help screen for the given entity to the given file.
 244  */
 245 void lc_opt_print_help(lc_opt_entry_t *ent, FILE *f);
 246
 247 /**
 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
 252  */
 253 void lc_opt_print_help_for_entry(lc_opt_entry_t *ent, char separator, FILE *f);
 254
 255 void lc_opt_print_tree(lc_opt_entry_t *ent, FILE *f);
 256
 257 int lc_opt_add_table(lc_opt_entry_t *grp, const lc_opt_table_entry_t *table);
 258
 259 /**
 260  * The same as lc_opt_from_single_arg() only for an array of arguments.
 261  */
 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);
 266
 267 /**
 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.
 274  */
 275 int lc_opt_from_single_arg(const lc_opt_entry_t *grp,
 276                            const char *opt_prefix,
 277                            const char *arg,
 278                            lc_opt_error_handler_t *handler);
 279
 280 /**
 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.
 288  */
 289 const lc_arg_env_t *lc_opt_get_arg_env(void);
 290
 291 #endif