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_negbit,
  41         lc_opt_type_boolean,
  42         lc_opt_type_negboolean,
  43         lc_opt_type_string,
  44         lc_opt_type_int,
  45         lc_opt_type_double
  46 } lc_opt_type_t;
  47
  48 /**
  49  * Error codes.
  50  */
  51 typedef enum {
  52         lc_opt_err_none = 0,
  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
  62 } lc_opt_err_t;
  63
  64 typedef struct {
  65         int error;
  66         const char *msg;
  67         const char *arg;
  68 } lc_opt_err_info_t;
  69
  70 #define lc_opt_is_error(err) ((err)->error != lc_opt_err_none)
  71
  72 typedef struct lc_opt_entry_t lc_opt_entry_t;
  73
  74 typedef int (lc_opt_callback_t)(const char *name, lc_opt_type_t type, void *data, size_t length, ...);
  75
  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);
  77
  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);
  79
  80 typedef int (lc_opt_error_handler_t)(const char *prefix, const lc_opt_err_info_t *err);
  81
  82 typedef struct {
  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 NULL. */
  88
  89         size_t len;                                             /**< The amount of bytes available at the
  90                                                                                 location value points to. */
  91         lc_opt_callback_t *cb;                  /**< A callback that is called, when the option is set.
  92                                                                         This may never be NULL. */
  93
  94         lc_opt_dump_t *dump;                    /**< A function which is able to format the options value
  95                                                                         into a string. May be 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, value, len, cb, dump, dump_vals) \
 104         { name, desc, type, value, 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, 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, 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, addr, mask, lc_opt_std_cb, lc_opt_std_dump, NULL)
 114
 115 #define LC_OPT_ENT_NEGBIT(name, desc, addr, mask) \
 116         _LC_OPT_ENT(name, desc, lc_opt_type_negbit, addr, mask, lc_opt_std_cb, lc_opt_std_dump, NULL)
 117
 118 #define LC_OPT_ENT_BOOL(name, desc, addr) \
 119         _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
 121 #define LC_OPT_ENT_NEGBOOL(name, desc, addr) \
 122         _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
 124 #define LC_OPT_ENT_STR(name, desc, buf, len) \
 125         _LC_OPT_ENT(name, desc, lc_opt_type_string, buf, len, lc_opt_std_cb, lc_opt_std_dump, NULL)
 126
 127 #define LC_OPT_ENT_CB(name, desc, type, data, len, cb, dump, dump_vals) \
 128         _LC_OPT_ENT(name, desc, type, data, len, cb, dump, dump_vals)
 129
 130 #define LC_OPT_LAST \
 131         _LC_OPT_ENT(NULL, NULL, lc_opt_type_invalid, NULL, 0, NULL, NULL, NULL)
 132
 133 /**
 134  * Get the root option group.
 135  * @return The root option group.
 136  */
 137 lc_opt_entry_t *lc_opt_root_grp(void);
 138
 139 /**
 140  * Check, if a group is the root group
 141  * @param ent   The entry to check for.
 142  * @return      1, if the entry is the root group, 0 otherwise.
 143  */
 144 int lc_opt_grp_is_root(const lc_opt_entry_t *ent);
 145
 146 /**
 147  * Get an option group.
 148  * If the group is not already present, it is created.
 149  * @param parent   The parent group to look in.
 150  * @param name     The name of the group to lookup
 151  * @return         The already present or created group.
 152  */
 153 lc_opt_entry_t *lc_opt_get_grp(lc_opt_entry_t *parent, const char *name);
 154
 155 /**
 156  * Add an option to a group.
 157  * @param grp       The group to add the option to.
 158  * @param name      The name of the option (must be unique inside the group).
 159  * @param desc      A description of the option.
 160  * @param type      The data type of the option (see lc_opt_type_*)
 161  * @param value     A pointer to the memory, where the value shall be stored.
 162  *                                                                      (May be NULL).
 163  * @param length    Amount of bytes available at the memory location
 164  *                  indicated by @p value.
 165  * @param cb        A callback function to be called, as the option's value
 166  *                  is set (may be NULL).
 167  * @param err       Error information to be set (may be NULL).
 168  * @return          The handle for the option.
 169  */
 170 lc_opt_entry_t *lc_opt_add_opt(lc_opt_entry_t *grp,
 171                                                            const char *name,
 172                                                            const char *desc,
 173                                                            lc_opt_type_t type,
 174                                                            void *value, size_t length,
 175                                                            lc_opt_callback_t *cb,
 176                                                            lc_opt_dump_t *dump,
 177                                                            lc_opt_dump_vals_t *dump_vals,
 178                                                            lc_opt_err_info_t *err);
 179
 180 int lc_opt_std_cb(const char *name, lc_opt_type_t type, void *data, size_t length, ...);
 181
 182 int lc_opt_std_dump(char *buf, size_t n, const char *name, lc_opt_type_t type, void *data, size_t length);
 183
 184 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
 186 #define lc_opt_add_opt_int(grp, name, desc, value, err) \
 187         lc_opt_add_opt(grp, name, desc, lc_opt_type_int, value, 0, lc_opt_std_cb, lc_opt_std_dump, NULL, err)
 188
 189 #define lc_opt_add_opt_double(grp, name, desc, value, err) \
 190         lc_opt_add_opt(grp, name, desc, lc_opt_type_double, value, 0, lc_opt_std_cb, lc_opt_std_dump, NULL, err)
 191
 192 #define lc_opt_add_opt_string(grp, name, desc, buf, len, err) \
 193         lc_opt_add_opt(grp, name, desc, lc_opt_type_string, buf, len, lc_opt_std_cb, lc_opt_std_dump, NULL, err)
 194
 195 #define lc_opt_add_opt_bit(grp, name, desc, value, mask, err) \
 196         lc_opt_add_opt(grp, name, desc, lc_opt_type_bit, value, mask, lc_opt_std_cb, lc_opt_std_dump, NULL, err)
 197
 198
 199 /**
 200  * Find a group inside another group.
 201  * @param grp   The group to search inside.
 202  * @param name  The name of the group you are looking for.
 203  * @param err   Error info (may be NULL).
 204  * @return      The group or NULL, if no such group can be found.
 205  */
 206 lc_opt_entry_t *lc_opt_find_grp(const lc_opt_entry_t *grp, const char *name, lc_opt_err_info_t *err);
 207
 208 /**
 209  * Find an option inside another group.
 210  * @param grp   The group to search inside.
 211  * @param name  The name of the option you are looking for.
 212  * @param err   Error info (may be NULL).
 213  * @return      The group or NULL, if no such option can be found.
 214  */
 215 lc_opt_entry_t *lc_opt_find_opt(const lc_opt_entry_t *grp, const char *name, lc_opt_err_info_t *err);
 216
 217 /**
 218  * Resolve a group.
 219  * @param root   The group to start resolving from.
 220  * @param names  A string array containing the path to the group.
 221  * @param n      Number of entries in @p names to consider.
 222  * @param err    Error information (may be NULL).
 223  * @return       The group or NULL, if none is found.
 224  */
 225 lc_opt_entry_t *lc_opt_resolve_grp(const lc_opt_entry_t *root,
 226                 const char * const *names, int n, lc_opt_err_info_t *err);
 227
 228 /**
 229  * Resolve an option.
 230  * @param root   The group to start resolving from.
 231  * @param names  A string array containing the path to the option.
 232  * @param n      Number of entries in @p names to consider.
 233  * @param err    Error information (may be NULL).
 234  * @return       The option or NULL, if none is found.
 235  */
 236 lc_opt_entry_t *lc_opt_resolve_opt(const lc_opt_entry_t *root,
 237                 const char * const *names, int n, lc_opt_err_info_t *err);
 238
 239 /**
 240  * Set the value of an option.
 241  * @param opt    The option to set.
 242  * @param value  The value of the option in a string representation.
 243  * @param err    Error information (may be NULL).
 244  * @return       0, if an error occurred, 1 else.
 245  */
 246 int lc_opt_occurs(lc_opt_entry_t *opt, const char *value, lc_opt_err_info_t *err);
 247
 248 /**
 249  * Convert the option to a string representation.
 250  * @param buf  The string buffer to put the string representation to.
 251  * @param len  The length of @p buf.
 252  * @param ent  The option to process.
 253  * @return     @p buf.
 254  */
 255 char *lc_opt_value_to_string(char *buf, size_t len, const lc_opt_entry_t *ent);
 256
 257 /**
 258  * Get the name of the type of an option.
 259  * @param ent The option.
 260  * @return The name of the type of the option.
 261  */
 262 const char *lc_opt_get_type_name(const lc_opt_entry_t *ent);
 263
 264 /**
 265  * Print the help screen for the given entity to the given file.
 266  */
 267 void lc_opt_print_help(lc_opt_entry_t *ent, FILE *f);
 268
 269 /**
 270  * Print the help screen for the given entity to the given file.
 271  * Use separator instead of '.' and ignore entities above ent,
 272  * i.e. if ent is root.be and has option isa.mach, prints
 273  * isa<separator>mach instead of root.be.isa.mach
 274  */
 275 void lc_opt_print_help_for_entry(lc_opt_entry_t *ent, char separator, FILE *f);
 276
 277 void lc_opt_print_tree(lc_opt_entry_t *ent, FILE *f);
 278
 279 int lc_opt_add_table(lc_opt_entry_t *grp, const lc_opt_table_entry_t *table);
 280
 281 void lc_opt_from_file(const char *filenmame, FILE *f, lc_opt_error_handler_t *handler);
 282
 283 /**
 284  * The same as lc_opt_from_single_arg() only for an array of arguments.
 285  */
 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);
 290
 291 /**
 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.
 298  */
 299 int lc_opt_from_single_arg(const lc_opt_entry_t *grp,
 300                                                    const char *opt_prefix,
 301                                                    const char *arg,
 302                                                    lc_opt_error_handler_t *handler);
 303
 304 /**
 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.
 312  */
 313 const lc_arg_env_t *lc_opt_get_arg_env(void);
 314
 315 /**
 316  * This function tries to open a ini file in the user's homedir
 317  * (On win32 this is \Documents and Settings\Application Data)
 318  * which is called .<ini_name>rc (on win32 <ini_name>.ini)
 319  *
 320  * and an ini file in the current directory which is called <ini_name>.ini on
 321  * both systems.
 322  */
 323 void lc_opt_default_configs(const char *init_name);
 324
 325 #endif