Statistics
| Branch: | Revision:

root / include / cconfiguration.h @ master

History | View | Annotate | Download (18.6 KB)

1 01873262 Georg Kunz
//==========================================================================
2
//  CCONFIGURATION.H - part of
3
//
4
//                     OMNeT++/OMNEST
5
//            Discrete System Simulation in C++
6
//
7
//
8
//  Declaration of the following classes:
9
//    cConfiguration
10
//
11
//==========================================================================
12
13
/*--------------------------------------------------------------*
14
  Copyright (C) 1992-2008 Andras Varga
15
  Copyright (C) 2006-2008 OpenSim Ltd.
16

17
  This file is distributed WITHOUT ANY WARRANTY. See the file
18
  `license' for details on this and other legal matters.
19
*--------------------------------------------------------------*/
20
21
#ifndef __CCONFIGURATION_H
22
#define __CCONFIGURATION_H
23
24
#include <vector>
25
#include "simkerneldefs.h"
26
#include "cobject.h"
27
28
NAMESPACE_BEGIN
29
30
class cConfigOption;
31
32
/**
33
 * "General", the name of the default configuration
34
 */
35
#define CFGNAME_GENERAL "General"
36
37
/**
38
 * Predefined configuration variables; see cConfigurationEx::getVariable().
39
 * Variables can be referred to using the ${...} syntax in the configuration.
40
 */
41
//@{
42
#define CFGVAR_RUNID            "runid"
43
#define CFGVAR_INIFILE          "inifile"
44
#define CFGVAR_CONFIGNAME       "configname"
45
#define CFGVAR_RUNNUMBER        "runnumber"
46
#define CFGVAR_NETWORK          "network"
47
#define CFGVAR_EXPERIMENT       "experiment"
48
#define CFGVAR_MEASUREMENT      "measurement"
49
#define CFGVAR_REPLICATION      "replication"
50
#define CFGVAR_PROCESSID        "processid"
51
#define CFGVAR_DATETIME         "datetime"
52
#define CFGVAR_RESULTDIR        "resultdir"
53
#define CFGVAR_REPETITION       "repetition"
54
#define CFGVAR_SEEDSET          "seedset"
55
#define CFGVAR_ITERATIONVARS    "iterationvars"   // without $repetition
56
#define CFGVAR_ITERATIONVARS2   "iterationvars2"  // with $repetition
57
//@}
58
59
/**
60
 * Represents the configuration, as accessed by the simulation kernel.
61
 * The configuration object can be accessed with ev.getConfig().
62
 *
63
 * This class logically belongs to the cEnvir facade. (cEnvir presents
64
 * to the simulation kernel the UI, or generally, the program which embeds
65
 * the simulation.) This class provides access to configuration data for
66
 * components such as scheduler classes, parallel simulation algorithms, etc.
67
 * Model code (simple modules) should not directly read the configuration --
68
 * they should rely on module parameters for input.
69
 *
70
 * This class does not deal with module parameters, because they get
71
 * assigned via cEnvir's readParameter() method.
72
 *
73
 * @see cConfigurationEx, cEnvir::getConfig()
74
 * @ingroup EnvirExtensions
75
 */
76
class SIM_API cConfiguration : public cObject
77
{
78
  public:
79
    /**
80
     * Describes a configuration entry.
81
     */
82
    class KeyValue {
83
      public:
84
        virtual ~KeyValue() {}
85
        virtual const char *getKey() const = 0;
86
        virtual const char *getValue() const = 0;
87
        virtual const char *getBaseDirectory() const = 0;
88
    };
89
90
  public:
91
    /** @name String-based getters for configuration options */
92
    //@{
93
    /**
94
     * Returns a configuration value. Valid keys do not contain dots or wildcard characters.
95
     * Returns NULL if key is not found.
96
     */
97
    virtual const char *getConfigValue(const char *key) const = 0;
98
99
    /**
100
     * Like getConfigValue(), but this one returns information about the
101
     * whole inifile entry, not just the value string.
102
     * If the key is not found, a special KeyValue object is returned
103
     * where both key and value are NULL.
104
     *
105
     * Lifetime of the returned object might be limited, so clients
106
     * should not store references to it. Copying the object is not allowed
107
     * either, because KeyValue is a polymorphic type (object slicing!).
108
     */
109
    virtual const KeyValue& getConfigEntry(const char *key) const = 0;
110
111
    /**
112
     * Returns a per-object configuration value. Valid keysuffixes do not contain
113
     * dots or wildcard characters. Returns NULL if key is not found.
114
     * keySuffix is something like "vector-recording-intervals", "ev-output", etc.
115
     */
116
    virtual const char *getPerObjectConfigValue(const char *objectFullPath, const char *keySuffix) const = 0;
117
118
    /**
119
     * Like getPerObjectConfigValue(), but this one returns information about the
120
     * whole inifile entry, not just the value string.
121
     * If the key is not found, a special KeyValue object is returned
122
     * where both key and value are NULL.
123
     *
124
     * Lifetime of the returned object might be limited, so clients
125
     * should not store references to it. Copying the object is not allowed
126
     * either, because KeyValue is a polymorphic type (object slicing!).
127
     */
128
    virtual const KeyValue& getPerObjectConfigEntry(const char *objectFullPath, const char *keySuffix) const = 0;
129
    //@}
130
131
    /** @name Utility functions for parsing config entries */
132
    //@{
133
    static bool parseBool(const char *s, const char *defaultValue, bool fallbackValue=false);
134
    static long parseLong(const char *s, const char *defaultValue, long fallbackValue=0);
135
    static double parseDouble(const char *s, const char *unit, const char *defaultValue, double fallbackValue=0);
136
    static std::string parseString(const char *s, const char *defaultValue, const char *fallbackValue="");
137
    static std::string parseFilename(const char *s, const char *baseDir, const char *defaultValue);
138
    static std::vector<std::string> parseFilenames(const char *s, const char *baseDir, const char *defaultValue);
139
    static std::string adjustPath(const char *s, const char *baseDir, const char *defaultValue);
140
    //@}
141
142
    /** @name Getters for configuration options */
143
    //@{
144
    /**
145
     * Returns a config value without any conversion.
146
     * fallbackValue is returned if the value is not specified in the configuration, and there is no default value.
147
     */
148
    virtual const char *getAsCustom(cConfigOption *option, const char *fallbackValue=NULL);
149
150
    /**
151
     * Returns a config value as bool.
152
     * fallbackValue is returned if the value is not specified in the configuration, and there is no default value.
153
     */
154
    virtual bool getAsBool(cConfigOption *option, bool fallbackValue=false);
155
156
    /**
157
     * Returns a config value as long.
158
     * fallbackValue is returned if the value is not specified in the configuration, and there is no default value.
159
     */
160
    virtual long getAsInt(cConfigOption *option, long fallbackValue=0);
161
162
    /**
163
     * Returns a config value as double.
164
     * fallbackValue is returned if the value is not specified in the configuration, and there is no default value.
165
     */
166
    virtual double getAsDouble(cConfigOption *option, double fallbackValue=0);
167
168
    /**
169
     * Returns a config value as string.
170
     * fallbackValue is returned if the value is not specified in the configuration, and there is no default value.
171
     */
172
    virtual std::string getAsString(cConfigOption *option, const char *fallbackValue="");
173
174
    /**
175
     * Interprets the config value as a path. If it is relative, then it will be
176
     * converted to an absolute path, using the base directory (see the
177
     * getBaseDirectoryFor() method).
178
     */
179
    virtual std::string getAsFilename(cConfigOption *option);
180
181
    /**
182
     * Interprets the config value as a list of paths (file or directory names,
183
     * possibly containing wildcards), separated by spaces. The relative paths
184
     * in the list will be converted to absolute, using the base directory
185
     * (see getBaseDirectoryFor() method).
186
     */
187
    virtual std::vector<std::string> getAsFilenames(cConfigOption *option);
188
189
    /**
190
     * Interprets the config value as a list of directory names, possibly
191
     * containing wildcards, and separated by ";" (Windows), or ":" or ";"
192
     * (other OSes). The relative names in the list will be converted to absolute,
193
     * using the base directory (see getBaseDirectoryFor() method).
194
     */
195
    virtual std::string getAsPath(cConfigOption *option);
196
    //@}
197
198
    /** @name Getters for per-object configuration options */
199
    //@{
200
    /**
201
     * Returns a per-object config value without any conversion.
202
     * fallbackValue is returned if the value is not specified in the configuration, and there is no default value.
203
     */
204
    virtual const char *getAsCustom(const char *objectFullPath, cConfigOption *option, const char *fallbackValue=NULL);
205
206
    /**
207
     * Returns a per-object config value as bool.
208
     * fallbackValue is returned if the value is not specified in the configuration, and there is no default value.
209
     */
210
    virtual bool getAsBool(const char *objectFullPath, cConfigOption *option, bool fallbackValue=false);
211
212
    /**
213
     * Returns a per-object config value as long.
214
     * fallbackValue is returned if the value is not specified in the configuration, and there is no default value.
215
     */
216
    virtual long getAsInt(const char *objectFullPath, cConfigOption *option, long fallbackValue=0);
217
218
    /**
219
     * Returns a per-object config value as double.
220
     * fallbackValue is returned if the value is not specified in the configuration, and there is no default value.
221
     */
222
    virtual double getAsDouble(const char *objectFullPath, cConfigOption *option, double fallbackValue=0);
223
224
    /**
225
     * Returns a per-object config value as string.
226
     * fallbackValue is returned if the value is not specified in the configuration, and there is no default value.
227
     */
228
    virtual std::string getAsString(const char *objectFullPath, cConfigOption *option, const char *fallbackValue="");
229
230
    /**
231
     * Interprets the per-object config value as a path. If it is relative,
232
     * then it will be converted to an absolute path, using the base directory
233
     * (see KeyValue::getBaseDirectory()).
234
     */
235
    virtual std::string getAsFilename(const char *objectFullPath, cConfigOption *option);
236
237
    /**
238
     * Interprets the per-object config value as a list of paths (file or directory
239
     * names, possibly containing wildcards), separated by spaces. The relative paths
240
     * in the list will be converted to absolute, using the base directory
241
     * (see KeyValue::getBaseDirectory()).
242
     */
243
    virtual std::vector<std::string> getAsFilenames(const char *objectFullPath, cConfigOption *option);
244
245
    /**
246
     * Interprets the per-object config value as a list of directory names, possibly
247
     * containing wildcards, and separated by ";" (Windows), or ":" or ";"
248
     * (other OSes). The relative names in the list will be converted to absolute,
249
     * using the base directory (see getBaseDirectoryFor() method).
250
     */
251
    virtual std::string getAsPath(const char *objectFullPath, cConfigOption *option);
252
    //@}
253
254
    /** @name Other methods */
255
    //@{
256
    /**
257
     * Substitutes ${} variables into the given string. The resulting string
258
     * is stored inside the configuration object.
259
     */
260
    virtual const char *substituteVariables(const char *value) = 0;
261
    //@}
262
};
263
264
265
/**
266
 * Represents a configuration suitable for use with the Envir library.
267
 * This class extends cConfiguration with the following functionality:
268
 *
269
 * <ul>
270
 *   <li> Methods for reading module parameters; cEnvir's readParameter()
271
 *        method delegates to them by default.
272
 *   <li> Support for multiple configurations (enumeration, activation, etc.)
273
 *   <li> Parameter Study support: run numbers, iteration variables, unrolling, etc.
274
 *   <li> Other utility functions like dump()
275
 * </ul>
276
 *
277
 * @see cEnvir::getConfigEx()
278
 * @ingroup EnvirExtensions
279
 */
280
class SIM_API cConfigurationEx : public cConfiguration
281
{
282
  public:
283
    /**
284
     * Initializes configuration object from "boot-time" configuration
285
     * (omnetpp.ini). For example, if a particular cConfiguration subclass
286
     * uses a database as data source, it may take the connection parameters
287
     * from the "boot-time" configuration.
288
     */
289
    virtual void initializeFrom(cConfiguration *bootConfig) = 0;
290
291
    /**
292
     * Returns the name of the configuration file. Returns NULL if this object is
293
     * not using a configuration file.
294
     */
295
    virtual const char *getFileName() const = 0;
296
297
    /**
298
     * Validates the configuration: reports obsolete config keys,
299
     * cycles in the section fallback chain, unrecognized keys, etc
300
     * as exceptions.
301
     *
302
     * ignorableConfigKeys is the list of config keys whose presence in the
303
     * configuration should not be reported as errors even if they are not
304
     * declared using cConfigOptions. The list is space-separated, and items may
305
     * contain wildcards. Typically, this list will contain "cmdenv-*" when
306
     * Cmdenv is unavailable (not linked in), "tkenv-*" when Tkenv is unavailable,
307
     * etc, so that validate() does not report those keys in omnetpp.ini as errors.
308
     */
309
    virtual void validate(const char *ignorableConfigKeys=NULL) const = 0;
310
311
    /** @name Activating a configuration */
312
    //@{
313
    /**
314
     * Returns the names of the available configurations.
315
     */
316
    virtual std::vector<std::string> getConfigNames() = 0;
317
318
    /**
319
     * Activates the [Config \<name\>] section. If it does not exist, an error
320
     * gets thrown. [General] is treated as short for [Config General].
321
     * The runNumber must be between 0 and getNumRunsInConfig(name)-1.
322
     */
323
    virtual void activateConfig(const char *configName, int runNumber=0) = 0;
324
325
    /**
326
     * Returns the description of the given configuration.
327
     */
328
    virtual std::string getConfigDescription(const char *configName) const = 0;
329
330
    /**
331
     * Returns the name of the configuration the given configuration extends.
332
     * Only names of *existing* configuration names are returned (that is,
333
     * if "extends" is bogus and refers to a nonexistent configuration,
334
     * this method returns the empty string; also, "General" is only returned
335
     * if such configuration actually exists.)
336
     */
337
    virtual std::string getBaseConfig(const char *configName) const = 0;
338
339
    /**
340
     * Generates Cartesian product of all iterations within the config, and counts them.
341
     */
342
    virtual int getNumRunsInConfig(const char *configName) const = 0;
343
344
    /**
345
     * Generates all runs in the given configuration, and returns a string for each.
346
     * When detailed==false, each run will generate a one-line string with the
347
     * iteration variables; with detailed==true, each run generates a multi-line
348
     * string containing the config entries that contain iterations or iteration
349
     * variable references. This method is primarily for debugging purposes.
350
     */
351
    virtual std::vector<std::string> unrollConfig(const char *configName, bool detailed=true) const = 0;
352
353
    /**
354
     * Returns the name of the currently active configuration.
355
     */
356
    virtual const char *getActiveConfigName() const = 0;
357
358
    /**
359
     * Returns currently active run number. This is the number passed to
360
     * activateConfig(), or 0 if activateConfig() has not been called.
361
     */
362
    virtual int getActiveRunNumber() const = 0;
363
364
    /**
365
     * After activating a configuration, this method can be used to query
366
     * iteration variables and predefined variables. These are the variables
367
     * that can be referred to using the "${...}" syntax in the configuration.
368
     * If the variable does not exist, NULL is returned.
369
     *
370
     * Some of the predefined variables are: "configname", "runnumber", "network",
371
     * "processid", "datetime", "runid", "repetition", "iterationvars";
372
     * these names are also available as symbolic constants, see CFGVAR_CONFIGNAME
373
     * and other CFGVAR_xxx names.
374
     */
375
    virtual const char *getVariable(const char *varname) const = 0;
376
377
    /**
378
     * Returns the names of all iteration variables in the activated configuration.
379
     */
380
    virtual std::vector<const char *> getIterationVariableNames() const = 0;
381
382
    /**
383
     * Returns the names of all predefined variables in the activated configuration.
384
     * See getVariable().
385
     */
386
    virtual std::vector<const char *> getPredefinedVariableNames() const = 0;
387
388
    /**
389
     * Returns the description of the given variable in the activated configuration.
390
     * Returns NULL if the variable does not exist or no description is available.
391
     */
392
    virtual const char *getVariableDescription(const char *varname) const = 0;
393
394
    /**
395
     * For debugging.
396
     */
397
    virtual void dump() const = 0;
398
    //@}
399
400
    /** @name Getting values from the currently active configuration */
401
    //@{
402
403
    /**
404
     * Returns the list of config keys that match the given wildcard pattern.
405
     * The returned keys can be passed to getConfigValue().
406
     */
407
    virtual std::vector<const char *> getMatchingConfigKeys(const char *pattern) const = 0;
408
409
    /**
410
     * Looks up the value of the given parameter in the inifile. The argument
411
     * hasDefaultValue controls whether "=default" entries need to be considered.
412
     * Return value is NULL if the parameter is not specified in the inifile,
413
     * otherwise returns the string after the equal sign.
414
     */
415
    virtual const char *getParameterValue(const char *moduleFullPath, const char *paramName, bool hasDefaultValue) const = 0;
416
417
    /**
418
     * Like getParameterValue(), but this one returns information about the
419
     * whole inifile entry, not just the value string.
420
     * If the key is not found, a special KeyValue object is returned
421
     * where both key and value are NULL.
422
     *
423
     * Lifetime of the returned object might be limited, so clients
424
     * should not store references to it. Copying the object is not allowed
425
     * either, because KeyValue is a polymorphic type (object slicing!).
426
     */
427
    virtual const KeyValue& getParameterEntry(const char *moduleFullPath, const char *paramName, bool hasDefaultValue) const = 0;
428
429
    /**
430
     * This method returns an array of the following form: (key1, value1,
431
     * key2, value2,...), where keys and values correspond to parameter
432
     * assignments in the configuration. This method is inefficient, and
433
     * should not be used for anything else than writing the header of
434
     * result files.
435
     */
436
    virtual std::vector<const char *> getParameterKeyValuePairs() const = 0;
437
438
    /**
439
     * Returns the list of config keys that match the wildcard pattern
440
     * objectFullPath + dot + keySuffixPattern. objectFullPath may either be
441
     * a concrete string without wildcards, or "**" to match anything.
442
     * The returned keys may be used with getPerObjectConfigValue() to obtain
443
     * the corresponding values.
444
     */
445
    virtual std::vector<const char *> getMatchingPerObjectConfigKeys(const char *objectFullPath, const char *keySuffixPattern) const = 0;
446
447
    /**
448
     * Like getMatchingPerObjectConfigKeys(), but returns the suffixes instead
449
     * of the keys. Note: the result may contain duplicates. The returned suffixes
450
     * may be used with getPerObjectConfigValue() to obtain the corresponding values.
451
     */
452
    virtual std::vector<const char *> getMatchingPerObjectConfigKeySuffixes(const char *objectFullPath, const char *keySuffixPattern) const = 0;
453
    //@}
454
};
455
456
NAMESPACE_END
457
458
#endif
459