include/xbt/config.h

   1 /* config - Dictionary where the type of each cell is provided.            */
   2
   3 /* This is useful to build named structs, like option or property sets.     */
   4
   5 /* Copyright (c) 2004-2007, 2009-2014. The SimGrid Team.
   6  * All rights reserved.                                                     */
   7
   8 /* This program is free software; you can redistribute it and/or modify it
   9  * under the terms of the license (GNU LGPL) which comes with this package. */
  10
  11 #ifndef _XBT_CONFIG_H_
  12 #define _XBT_CONFIG_H_
  13
  14 #include "xbt/dynar.h"
  15 #include <stdarg.h>
  16
  17 SG_BEGIN_DECL()
  18
  19 /** @addtogroup XBT_config
  20  *  @brief Changing the configuration of SimGrid components (grounding feature)
  21  *
  22  *  All modules of the SimGrid toolkit can be configured with this API.
  23  *  User modules and libraries can also use these facilities to handle their own configuration.
  24  *
  25  *  A configuration set contain several \e variables which have a unique name in the set and can take a given type of
  26  *  value. For example, it may contain a \a size variable, accepting \e int values.
  27  *
  28  *  It is impossible to set a value to a variable which has not been registered before.
  29  *  Usually, the module registers all the options it accepts in the configuration set, during its initialization and
  30  *  user code then set and unset values.
  31  *
  32  *  The easiest way to register a variable is to use the xbt_str_register_str function, which accepts a string
  33  *  representation of the config element descriptor. The syntax is the following:
  34  *  \verbatim <name>:<min nb>_to_<max nb>_<type>\endverbatim
  35  *
  36  *  For example, <tt>size:1_to_1_int</tt> describes a variable called \e size which must take exactly one value, and
  37  *  the value being an integer. Set the maximum to 0 to disable the upper bound on data count.
  38  *
  39  *  Another example could be <tt>outputfiles:0_to_10_string</tt> which describes a variable called \e outputfiles and
  40  *  which can take between 0 and 10 strings as value.
  41  *
  42  *  To some extend, configuration sets can be seen as typed hash structures.
  43  *
  44  *  \section XBT_cfg_ex Example of use
  45  *
  46  *  \dontinclude config.c
  47  *
  48  *  First, let's create a configuration set with some registered variables.
  49  *  This must be done by the configurable library before the user interactions.
  50  *
  51  *  \skip make_set
  52  *  \until end_of_make_set
  53  *
  54  *  Now, set and get a single value
  55  *  \skip get_single_value
  56  *  \skip int
  57  *  \until cfg_free
  58  *
  59  *  And now, set and get a multiple value
  60  *  \skip get_multiple_value
  61  *  \skip dyn
  62  *  \until cfg_free
  63  *
  64  *  All those functions throws mismatch_error if asked to deal with an  unregistered variable.
  65  *  \skip myset
  66  *  \until cfg_free
  67  */
  68 /** @defgroup XBT_cfg_use User interface: changing values
  69  *  @ingroup XBT_config
  70  *
  71  * This is the only interface you should use unless you want to let your own code become configurable with this.
  72  *
  73  * If the variable accept at most one value, those functions replace the current value with the provided one. If max>1,
  74  * the provided value is appended to the list.
  75  *
  76  * string values are strdup'ed before use, so you can (and should) free your copy
  77  *
  78  * @{
  79  */
  80 /** @brief Configuration set's data type is opaque. */
  81 typedef void* xbt_cfg_t;
  82
  83 XBT_PUBLIC(void) xbt_cfg_set(xbt_cfg_t cfg, const char *name, ...);
  84 XBT_PUBLIC(void) xbt_cfg_set_vargs(xbt_cfg_t cfg, const char *name, va_list pa);
  85 XBT_PUBLIC(void) xbt_cfg_set_parse(xbt_cfg_t cfg, const char *options);
  86
  87 /* Set the value of the cell \a name in \a cfg with the provided value.*/
  88 XBT_PUBLIC(void) xbt_cfg_set_int(xbt_cfg_t cfg, const char *name, int val);
  89 XBT_PUBLIC(void) xbt_cfg_set_double(xbt_cfg_t cfg, const char *name, double val);
  90 XBT_PUBLIC(void) xbt_cfg_set_string(xbt_cfg_t cfg, const char *name, const char *val);
  91 XBT_PUBLIC(void) xbt_cfg_set_boolean(xbt_cfg_t cfg, const char *name, const char *val);
  92 XBT_PUBLIC(void*) xbt_cfg_set_as_string(xbt_cfg_t cfg, const char *name, const char *val);
  93
  94 /*
  95   Set the default value of the cell \a name in \a cfg with the provided value.
  96   If it was already set to something (possibly from the command line), do nothing.
  97  */
  98 XBT_PUBLIC(void) xbt_cfg_setdefault_int(xbt_cfg_t cfg, const char *name, int val);
  99 XBT_PUBLIC(void) xbt_cfg_setdefault_double(xbt_cfg_t cfg, const char *name, double val);
 100 XBT_PUBLIC(void) xbt_cfg_setdefault_string(xbt_cfg_t cfg, const char *name, const char *val);
 101 XBT_PUBLIC(void) xbt_cfg_setdefault_boolean(xbt_cfg_t cfg, const char *name, const char *val);
 102
 103 /** @brief Remove the provided value from the cell #name in #cfg. */
 104 XBT_PUBLIC(void) xbt_cfg_rm_int(xbt_cfg_t cfg, const char *name, int val);
 105 XBT_PUBLIC(void) xbt_cfg_rm_double(xbt_cfg_t cfg, const char *name, double val);
 106 XBT_PUBLIC(void) xbt_cfg_rm_string(xbt_cfg_t cfg, const char *name, const char *val);
 107 XBT_PUBLIC(void) xbt_cfg_rm_boolean(xbt_cfg_t cfg, const char *name, int val);
 108
 109 /** @brief Remove the value at position \e pos from the config \e cfg */
 110 XBT_PUBLIC(void) xbt_cfg_rm_at(xbt_cfg_t cfg, const char *name, int pos);
 111
 112 /** @brief rm every values */
 113 XBT_PUBLIC(void) xbt_cfg_empty(xbt_cfg_t cfg, const char *name);
 114
 115 /** @brief Return if configuration is set by default*/
 116 XBT_PUBLIC(int) xbt_cfg_is_default_value(xbt_cfg_t cfg, const char *name);
 117
 118 /* @} */
 119
 120 /** @defgroup XBT_cfg_decl Configuration type declaration and memory management
 121  *  @ingroup XBT_config
 122  *
 123  *  @{
 124  */
 125
 126   /** @brief possible content of each configuration cell */
 127 typedef enum {
 128   xbt_cfgelm_int = 0,                    /**< int */
 129   xbt_cfgelm_double,                     /**< double */
 130   xbt_cfgelm_string,                    /**< char* */
 131   xbt_cfgelm_boolean,                   /**< int */
 132   xbt_cfgelm_alias,    /**< redirection from a deprecated name to a better one */
 133   //! @cond
 134   xbt_cfgelm_any,               /* not shown to users to prevent errors */
 135   xbt_cfgelm_type_count
 136   //! @endcond
 137 } e_xbt_cfgelm_type_t;
 138
 139 /** Boolean possible values **/
 140 struct xbt_boolean_couple {
 141   const char *true_val;
 142   const char *false_val;
 143 };
 144
 145 /** \brief Callback types. They get the name of the modified entry, and the position of the changed value */
 146 typedef void (*xbt_cfg_cb_t) (const char *, int);
 147
 148 XBT_PUBLIC(xbt_cfg_t) xbt_cfg_new(void);
 149 XBT_PUBLIC(void) xbt_cfg_cpy(xbt_cfg_t tocopy,  /* OUT */xbt_cfg_t * whereto);
 150 XBT_PUBLIC(void) xbt_cfg_free(xbt_cfg_t * cfg);
 151 XBT_PUBLIC(void) xbt_cfg_dump(const char *name, const char *indent, xbt_cfg_t cfg);
 152
 153  /** @} */
 154
 155 /** @defgroup XBT_cfg_register  Registering stuff
 156  *  @ingroup XBT_config
 157  *
 158  *  This how to add new variables to an existing configuration set. Use it to make your code configurable.
 159  *
 160  *  @{
 161  */
 162 XBT_PUBLIC(void) xbt_cfg_register(xbt_cfg_t * cfg, const char *name, const char *description,
 163     e_xbt_cfgelm_type_t type, int min, int max, xbt_cfg_cb_t cb_set);
 164 XBT_PUBLIC(void) xbt_cfg_register_double (xbt_cfg_t * cfg, const char *name, const char *desc, double default_val,    xbt_cfg_cb_t cb_set);
 165 XBT_PUBLIC(void) xbt_cfg_register_int    (xbt_cfg_t * cfg, const char *name, const char *desc, int default_val,       xbt_cfg_cb_t cb_set);
 166 XBT_PUBLIC(void) xbt_cfg_register_string (xbt_cfg_t * cfg, const char *name, const char *desc, const char*default_val,xbt_cfg_cb_t cb_set);
 167 XBT_PUBLIC(void) xbt_cfg_register_boolean(xbt_cfg_t * cfg, const char *name, const char *desc, const char*default_val,xbt_cfg_cb_t cb_set);
 168 XBT_PUBLIC(void) xbt_cfg_register_alias(xbt_cfg_t * cfg, const char *newname, const char *oldname);
 169 XBT_PUBLIC(void) xbt_cfg_unregister(xbt_cfg_t cfg, const char *name);
 170 XBT_PUBLIC(void) xbt_cfg_register_str(xbt_cfg_t * cfg, const char *entry);
 171
 172 XBT_PUBLIC(void) xbt_cfg_aliases(xbt_cfg_t cfg);
 173 XBT_PUBLIC(void) xbt_cfg_help(xbt_cfg_t cfg);
 174 XBT_PUBLIC(void) xbt_cfg_check(xbt_cfg_t cfg);
 175 XBT_PUBLIC(e_xbt_cfgelm_type_t) xbt_cfg_get_type(xbt_cfg_t cfg, const char *name);
 176 /*  @} */
 177 /** @defgroup XBT_cfg_get Getting the stored values
 178  *  @ingroup XBT_config
 179  *
 180  * This is how to retrieve the values stored in the configuration set. This is only intended to configurable code,
 181  * naturally.
 182  *
 183  * Note that those function return a pointer to the values actually stored in the set. Do not modify them unless you
 184  * really know what you're doing. Likewise, do not free the strings after use, they are not copy of the data, but the
 185  * data themselves.
 186  *
 187  *  @{
 188  */
 189
 190 XBT_PUBLIC(int) xbt_cfg_get_int(xbt_cfg_t cfg, const char *name);
 191 XBT_PUBLIC(double) xbt_cfg_get_double(xbt_cfg_t cfg, const char *name);
 192 XBT_PUBLIC(char *) xbt_cfg_get_string(xbt_cfg_t cfg, const char *name);
 193 XBT_PUBLIC(int) xbt_cfg_get_boolean(xbt_cfg_t cfg, const char *name);
 194 XBT_PUBLIC(xbt_dynar_t) xbt_cfg_get_dynar(xbt_cfg_t cfg, const char *name);
 195
 196 XBT_PUBLIC(int) xbt_cfg_get_int_at(xbt_cfg_t cfg, const char *name, int pos);
 197 XBT_PUBLIC(double) xbt_cfg_get_double_at(xbt_cfg_t cfg, const char *name, int pos);
 198 XBT_PUBLIC(char *) xbt_cfg_get_string_at(xbt_cfg_t cfg, const char *name, int pos);
 199 XBT_PUBLIC(int) xbt_cfg_get_boolean_at(xbt_cfg_t cfg, const char *name, int pos);
 200
 201 /** @} */
 202
 203 SG_END_DECL()
 204 #endif                          /* _XBT_CONFIG_H_ */