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

   1 /*
   2   libcore: library for basic data structures and algorithms.
   3   Copyright (C) 2005  IPD Goos, Universit"at Karlsruhe, Germany
   4
   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.
   9
  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.
  14
  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
  18 */
  19
  20 /*
  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.
  24 */
  25
  26 #ifndef _LC_OPTS_H
  27 #define _LC_OPTS_H
  28
  29 #include <stdio.h>
  30
  31 #include "lc_printf.h"
  32
  33 /**
  34  * The type of an option.
  35  */
  36 typedef enum {
  37         lc_opt_type_invalid,
  38         lc_opt_type_enum,
  39         lc_opt_type_bit,
  40         lc_opt_type_boolean,
  41         lc_opt_type_string,
  42         lc_opt_type_int,
  43         lc_opt_type_double
  44 } lc_opt_type_t;
  45
  46 /**
  47  * Error codes.
  48  */
  49 typedef enum {
  50         lc_opt_err_none = 0,
  51         lc_opt_err_no_callback,
  52         lc_opt_err_illegal_option_type,
  53         lc_opt_err_illegal_format,
  54         lc_opt_err_grp_not_found,
  55         lc_opt_err_opt_not_found,
  56         lc_opt_err_grp_expected,
  57         lc_opt_err_opt_already_there,
  58         lc_opt_err_file_not_found,
  59         lc_opt_err_unknown_value
  60 } lc_opt_err_t;
  61
  62 typedef struct {
  63         int error;
  64         const char *msg;
  65         const char *arg;
  66 } lc_opt_err_info_t;
  67
  68 #define lc_opt_is_error(err) ((err)->error != lc_opt_err_none)
  69
  70 typedef struct lc_opt_entry_t lc_opt_entry_t;
  71
  72 typedef int (lc_opt_callback_t)(const char *name, lc_opt_type_t type, void *data, size_t length, ...);
  73
  74 typedef int (lc_opt_dump_t)(char *buf, size_t n, const char *name, lc_opt_type_t type, void *data, size_t length);
  75
  76 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);
  77
  78 typedef int (lc_opt_error_handler_t)(const char *prefix, const lc_opt_err_info_t *err);
  79
  80 typedef struct {
  81         const char *name;               /**< The name of the option. */
  82         const char *desc;               /**< A description for the option. */
  83         lc_opt_type_t type;             /**< The type of the option (see enum). */
  84         void *value;                    /**< A pointer to the area, where the value
  85                                              of the option shall be put to. May be
  86                                              NULL. */
  87
  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
  91                                              option is set. This may never be NULL. */
  92
  93         lc_opt_dump_t *dump;            /**< A function which is able to format the
  94                                              options value into a string. May be
  95                                              NULL. */
  96
  97         lc_opt_dump_vals_t *dump_vals;  /**< A function which is able to format the possible values
  98                                              for this option into a string. May be NULL. */
  99
 100
 101 } lc_opt_table_entry_t;
 102
 103 #define _LC_OPT_ENT(name, desc, type, val_type, value, len, cb, dump, dump_vals) \
 104         { name, desc, type, 1 ? (value) : (val_type*)0 /* Produces a warning, if var has wrong type. */, len, cb, dump, dump_vals }
 105
 106 #define LC_OPT_ENT_INT(name, desc, addr) \
 107         _LC_OPT_ENT(name, desc, lc_opt_type_int, int, addr, 0, lc_opt_std_cb, lc_opt_std_dump, NULL)
 108
 109 #define LC_OPT_ENT_DBL(name, desc, addr) \
 110         _LC_OPT_ENT(name, desc, lc_opt_type_double, double, addr, 0, lc_opt_std_cb, lc_opt_std_dump, NULL)
 111
 112 #define LC_OPT_ENT_BIT(name, desc, addr, mask) \
 113         _LC_OPT_ENT(name, desc, lc_opt_type_bit, unsigned, addr, mask, lc_opt_std_cb, lc_opt_std_dump, NULL)
 114
 115 #define LC_OPT_ENT_BOOL(name, desc, addr) \
 116         _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)
 117
 118 typedef char lc_opt_str_t[];
 119 #define LC_OPT_ENT_STR(name, desc, buf) \
 120         _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)
 121
 122 #define LC_OPT_LAST \
 123         _LC_OPT_ENT(NULL, NULL, lc_opt_type_invalid, void, NULL, 0, NULL, NULL, NULL)
 124
 125 /**
 126  * Get the root option group.
 127  * @return The root option group.
 128  */
 129 lc_opt_entry_t *lc_opt_root_grp(void);
 130
 131 /**
 132  * Check, if a group is the root group
 133  * @param ent   The entry to check for.
 134  * @return      1, if the entry is the root group, 0 otherwise.
 135  */
 136 int lc_opt_grp_is_root(const lc_opt_entry_t *ent);
 137
 138 /**
 139  * Get an option group.
 140  * If the group is not already present, it is created.
 141  * @param parent   The parent group to look in.
 142  * @param name     The name of the group to lookup
 143  * @return         The already present or created group.
 144  */
 145 lc_opt_entry_t *lc_opt_get_grp(lc_opt_entry_t *parent, const char *name);
 146
 147 /**
 148  * Add an option to a group.
 149  * @param grp       The group to add the option to.
 150  * @param name      The name of the option (must be unique inside the group).
 151  * @param desc      A description of the option.
 152  * @param type      The data type of the option (see lc_opt_type_*)
 153  * @param value     A pointer to the memory, where the value shall be stored.
 154  *                  (May be NULL).
 155  * @param length    Amount of bytes available at the memory location
 156  *                  indicated by @p value.
 157  * @param cb        A callback function to be called, as the option's value
 158  *                  is set (may be NULL).
 159  * @param err       Error information to be set (may be NULL).
 160  * @return          The handle for the option.
 161  */
 162 lc_opt_entry_t *lc_opt_add_opt(lc_opt_entry_t *grp,
 163                                const char *name,
 164                                const char *desc,
 165                                lc_opt_type_t type,
 166                                void *value, size_t length,
 167                                lc_opt_callback_t *cb,
 168                                lc_opt_dump_t *dump,
 169                                lc_opt_dump_vals_t *dump_vals,
 170                                lc_opt_err_info_t *err);
 171
 172 int lc_opt_std_cb(const char *name, lc_opt_type_t type, void *data, size_t length, ...);
 173
 174 int lc_opt_std_dump(char *buf, size_t n, const char *name, lc_opt_type_t type, void *data, size_t length);
 175
 176 int lc_opt_bool_dump_vals(char *buf, size_t n, const char *name, lc_opt_type_t type, void *data, size_t length);
 177
 178 #define lc_opt_add_opt_int(grp, name, desc, value, err) \
 179         lc_opt_add_opt(grp, name, desc, lc_opt_type_int, value, 0, lc_opt_std_cb, lc_opt_std_dump, NULL, err)
 180
 181 #define lc_opt_add_opt_double(grp, name, desc, value, err) \
 182         lc_opt_add_opt(grp, name, desc, lc_opt_type_double, value, 0, lc_opt_std_cb, lc_opt_std_dump, NULL, err)
 183
 184 #define lc_opt_add_opt_string(grp, name, desc, buf, len, err) \
 185         lc_opt_add_opt(grp, name, desc, lc_opt_type_string, buf, len, lc_opt_std_cb, lc_opt_std_dump, NULL, err)
 186
 187 #define lc_opt_add_opt_bit(grp, name, desc, value, mask, err) \
 188         lc_opt_add_opt(grp, name, desc, lc_opt_type_bit, value, mask, lc_opt_std_cb, lc_opt_std_dump, NULL, err)
 189
 190
 191 /**
 192  * Find a group inside another group.
 193  * @param grp   The group to search inside.
 194  * @param name  The name of the group you are looking for.
 195  * @param err   Error info (may be NULL).
 196  * @return      The group or NULL, if no such group can be found.
 197  */
 198 lc_opt_entry_t *lc_opt_find_grp(const lc_opt_entry_t *grp, const char *name, lc_opt_err_info_t *err);
 199
 200 /**
 201  * Find an option inside another group.
 202  * @param grp   The group to search inside.
 203  * @param name  The name of the option you are looking for.
 204  * @param err   Error info (may be NULL).
 205  * @return      The group or NULL, if no such option can be found.
 206  */
 207 lc_opt_entry_t *lc_opt_find_opt(const lc_opt_entry_t *grp, const char *name, lc_opt_err_info_t *err);
 208
 209 /**
 210  * Resolve a group.
 211  * @param root   The group to start resolving from.
 212  * @param names  A string array containing the path to the group.
 213  * @param n      Number of entries in @p names to consider.
 214  * @param err    Error information (may be NULL).
 215  * @return       The group or NULL, if none is found.
 216  */
 217 lc_opt_entry_t *lc_opt_resolve_grp(const lc_opt_entry_t *root,
 218                 const char * const *names, int n, lc_opt_err_info_t *err);
 219
 220 /**
 221  * Resolve an option.
 222  * @param root   The group to start resolving from.
 223  * @param names  A string array containing the path to the option.
 224  * @param n      Number of entries in @p names to consider.
 225  * @param err    Error information (may be NULL).
 226  * @return       The option or NULL, if none is found.
 227  */
 228 lc_opt_entry_t *lc_opt_resolve_opt(const lc_opt_entry_t *root,
 229                 const char * const *names, int n, lc_opt_err_info_t *err);
 230
 231 /**
 232  * Set the value of an option.
 233  * @param opt    The option to set.
 234  * @param value  The value of the option in a string representation.
 235  * @param err    Error information (may be NULL).
 236  * @return       0, if an error occurred, 1 else.
 237  */
 238 int lc_opt_occurs(lc_opt_entry_t *opt, const char *value, lc_opt_err_info_t *err);
 239
 240 /**
 241  * Convert the option to a string representation.
 242  * @param buf  The string buffer to put the string representation to.
 243  * @param len  The length of @p buf.
 244  * @param ent  The option to process.
 245  * @return     @p buf.
 246  */
 247 char *lc_opt_value_to_string(char *buf, size_t len, const lc_opt_entry_t *ent);
 248
 249 /**
 250  * Get the name of the type of an option.
 251  * @param ent The option.
 252  * @return The name of the type of the option.
 253  */
 254 const char *lc_opt_get_type_name(const lc_opt_entry_t *ent);
 255
 256 /**
 257  * Print the help screen for the given entity to the given file.
 258  */
 259 void lc_opt_print_help(lc_opt_entry_t *ent, FILE *f);
 260
 261 /**
 262  * Print the help screen for the given entity to the given file.
 263  * Use separator instead of '.' and ignore entities above ent,
 264  * i.e. if ent is root.be and has option isa.mach, prints
 265  * isa<separator>mach instead of root.be.isa.mach
 266  */
 267 void lc_opt_print_help_for_entry(lc_opt_entry_t *ent, char separator, FILE *f);
 268
 269 void lc_opt_print_tree(lc_opt_entry_t *ent, FILE *f);
 270
 271 int lc_opt_add_table(lc_opt_entry_t *grp, const lc_opt_table_entry_t *table);
 272
 273 /**
 274  * The same as lc_opt_from_single_arg() only for an array of arguments.
 275  */
 276 int lc_opt_from_argv(const lc_opt_entry_t *root,
 277                      const char *opt_prefix,
 278                      int argc, const char *argv[],
 279                      lc_opt_error_handler_t *handler);
 280
 281 /**
 282  * Set options from a single (command line) argument.
 283  * @param root          The root group we start resolving from.
 284  * @param opt_prefix    The option prefix which shall be stripped of (mostly --).
 285  * @param arg           The command line argument itself.
 286  * @param handler       An error handler.
 287  * @return              1, if the argument was set, 0 if not.
 288  */
 289 int lc_opt_from_single_arg(const lc_opt_entry_t *grp,
 290                            const char *opt_prefix,
 291                            const char *arg,
 292                            lc_opt_error_handler_t *handler);
 293
 294 /**
 295  * Get printf environment for the option module.
 296  * Currently implemented options are:
 297  * %{opt:value} (%V)       Value of an option.
 298  * %{opt:type}  (%T)       Type of an option.
 299  * %{opt:name}  (%O)       Name of an option.
 300  * %{opt:desc}  (%D)       Description of an option.
 301  * @return The option printf environment.
 302  */
 303 const lc_arg_env_t *lc_opt_get_arg_env(void);
 304
 305 #endif