Logo AND Algorithmique Numérique Distribuée

Public GIT Repository
simgrid::config::flag, a more declarative way to describe CLI flags
[simgrid.git] / 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(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       (const char *name, int val);
89 XBT_PUBLIC(void) xbt_cfg_set_double    (const char *name, double val);
90 XBT_PUBLIC(void) xbt_cfg_set_string    (const char *name, const char *val);
91 XBT_PUBLIC(void) xbt_cfg_set_boolean   (const char *name, const char *val);
92 XBT_PUBLIC(void*) xbt_cfg_set_as_string(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    (const char *name, int val);
99 XBT_PUBLIC(void) xbt_cfg_setdefault_double (const char *name, double val);
100 XBT_PUBLIC(void) xbt_cfg_setdefault_string (const char *name, const char *val);
101 XBT_PUBLIC(void) xbt_cfg_setdefault_boolean(const char *name, const char *val);
102
103 /** @brief Return if configuration is set by default*/
104 XBT_PUBLIC(int) xbt_cfg_is_default_value(const char *name);
105
106 /* @} */
107
108 /** @defgroup XBT_cfg_decl Configuration type declaration and memory management
109  *  @ingroup XBT_config
110  *
111  *  @{
112  */
113
114   /** @brief possible content of each configuration cell */
115 typedef enum {
116   xbt_cfgelm_int = 0,                    /**< int */
117   xbt_cfgelm_double,                     /**< double */
118   xbt_cfgelm_string,                    /**< char* */
119   xbt_cfgelm_boolean,                   /**< int */
120   xbt_cfgelm_alias,    /**< redirection from a deprecated name to a better one */
121   //! @cond
122   xbt_cfgelm_any,               /* not shown to users to prevent errors */
123   xbt_cfgelm_type_count
124   //! @endcond
125 } e_xbt_cfgelm_type_t;
126
127 /** Boolean possible values **/
128 struct xbt_boolean_couple {
129   const char *true_val;
130   const char *false_val;
131 };
132
133 /** \brief Callback types. They get the name of the modified entry, and the position of the changed value */
134 typedef void (*xbt_cfg_cb_t) (const char * name);
135 typedef void (*xbt_cfg_cb_ext_t)(const char * name, void* cb_data);
136 typedef void (*xbt_cfg_cb_free_t)(void* cb_data);
137
138 XBT_PUBLIC(xbt_cfg_t) xbt_cfg_new(void);
139 XBT_PUBLIC(void) xbt_cfg_free(xbt_cfg_t * cfg);
140 XBT_PUBLIC(void) xbt_cfg_dump(const char *name, const char *indent, xbt_cfg_t cfg);
141
142  /** @} */
143
144 /** @defgroup XBT_cfg_register  Registering stuff
145  *  @ingroup XBT_config
146  *
147  *  This how to add new variables to an existing configuration set. Use it to make your code configurable.
148  *
149  *  @{
150  */
151 XBT_PUBLIC(void) xbt_cfg_register_double (const char *name, double default_val,    xbt_cfg_cb_t cb_set, const char *desc);
152 XBT_PUBLIC(void) xbt_cfg_register_int    (const char *name, int default_val,       xbt_cfg_cb_t cb_set, const char *desc);
153 XBT_PUBLIC(void) xbt_cfg_register_string (const char *name, const char*default_val,xbt_cfg_cb_t cb_set, const char *desc);
154 XBT_PUBLIC(void) xbt_cfg_register_boolean(const char *name, const char*default_val,xbt_cfg_cb_t cb_set, const char *desc);
155 XBT_PUBLIC(void) xbt_cfg_register_alias(const char *newname, const char *oldname);
156 XBT_PUBLIC(void) xbt_cfg_register_str(xbt_cfg_t * cfg, const char *entry);
157
158 XBT_PUBLIC(void) xbt_cfg_register_ext(
159   const char *name, const char *desc, e_xbt_cfgelm_type_t type,
160   xbt_cfg_cb_ext_t cb, void* data, xbt_cfg_cb_free_t data_free);
161
162 XBT_PUBLIC(void) xbt_cfg_aliases(void);
163 XBT_PUBLIC(void) xbt_cfg_help(void);
164 XBT_PUBLIC(e_xbt_cfgelm_type_t) xbt_cfg_get_type(xbt_cfg_t cfg, const char *name);
165 /*  @} */
166 /** @defgroup XBT_cfg_get Getting the stored values
167  *  @ingroup XBT_config
168  *
169  * This is how to retrieve the values stored in the configuration set. This is only intended to configurable code,
170  * naturally.
171  *
172  * Note that those function return a pointer to the values actually stored in the set. Do not modify them unless you
173  * really know what you're doing. Likewise, do not free the strings after use, they are not copy of the data, but the
174  * data themselves.
175  *
176  *  @{
177  */
178
179 XBT_PUBLIC(int)    xbt_cfg_get_int(const char *name);
180 XBT_PUBLIC(double) xbt_cfg_get_double(const char *name);
181 XBT_PUBLIC(char *) xbt_cfg_get_string(const char *name);
182 XBT_PUBLIC(int)    xbt_cfg_get_boolean(const char *name);
183
184 /** @} */
185
186 SG_END_DECL()
187 #endif                          /* _XBT_CONFIG_H_ */