Robot Simulator of the Robotics Group for Self-Organization of Control  0.8.0
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
configurable.h
Go to the documentation of this file.
1 /***************************************************************************
2  * Copyright (C) 2005-2011 LpzRobots development team *
3  * Georg Martius <georg dot martius at web dot de> *
4  * Frank Guettler <guettler at informatik dot uni-leipzig dot de *
5  * Frank Hesse <frank at nld dot ds dot mpg dot de> *
6  * Ralf Der <ralfder at mis dot mpg dot de> *
7  * *
8  * This program is free software; you can redistribute it and/or modify *
9  * it under the terms of the GNU General Public License as published by *
10  * the Free Software Foundation; either version 2 of the License, or *
11  * (at your option) any later version. *
12  * *
13  * This program is distributed in the hope that it will be useful, *
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of *
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
16  * GNU General Public License for more details. *
17  * *
18  * You should have received a copy of the GNU General Public License *
19  * along with this program; if not, write to the *
20  * Free Software Foundation, Inc., *
21  * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *
22  * *
23  ***************************************************************************/
24 #ifndef __CONFIGURABLE_H
25 #define __CONFIGURABLE_H
26 
27 #include <iostream>
28 #include <cstdlib>
29 
30 #include <limits>
31 #include <list>
32 #include <utility>
33 #include <string>
34 #include <map>
35 #include "stl_adds.h"
36 #include "backcaller.h"
37 
38 /**
39  Abstact class for configurable objects. Sort of Hashmap interface. Parameters are double, int or boolean values
40 
41  The Configurator is a (planned) external tool that can be used for changing the values of configurable objects.
42 
43  * Protocoll for Configurator:
44  \code
45  To Configurator (BNF notation):
46  Conf := <Comp>*
47  Comp := <CompName> <Pair>*
48  CompName := [<string>][<int>]<newline>
49  Pair := <alphanum>=<double><newline>
50  \endcode
51  the remaining tags are self explanatory
52 
53  Example
54  \code
55  [Component name which can contain spaces and digits and .,- ][ID1]
56  key1 = value1
57  key2 = value2
58  .
59  .
60  [Other Component name which can contain spaces and digits and .,- ][ID2]
61  key3 = value3
62  \endcode
63 
64  Answer: (from Communicator to Simulation environment)\n
65  1. On change of a parameter:
66  \code
67  [ID] key=newvalue
68  \endcode
69  or
70  \code
71  key=newvalue
72  \endcode
73  the latter one means that the parameter is changed in all components
74 
75  2. Request of the description as defined above.
76  \code
77  #Something I don\'t care
78  \endcode
79  */
80 
81 class Configurable : public BackCaller
82 {
83  public:
84 
85  typedef std::string paramkey;
86  typedef std::string paramdescr;
87  // params of type double
88  typedef double paramval;
89  typedef std::list<std::pair<paramkey, paramval> > paramlist;
90  typedef std::map<paramkey, paramval*> parammap;
91 
92  // params of type bool
93  typedef bool parambool;
94  typedef std::list<std::pair<paramkey, parambool> > paramboollist;
95  typedef std::map<paramkey, parambool*> paramboolmap;
96 
97  // params of type int
98  typedef int paramint;
99  typedef std::list<std::pair<paramkey, paramint> > paramintlist;
100  typedef std::map<paramkey, paramint*> paramintmap;
101 
102  typedef std::map<paramkey, paramdescr> paramdescrmap;
103 
104  // stuff for bounds
105  typedef std::pair<paramval, paramval> paramvalBounds;
106  typedef std::map<paramkey, paramvalBounds> paramvalBoundsMap;
107  #define valDefMaxBound 10.0
108  #define valDefMinBound -10.0
109 
110  typedef std::pair<paramint, paramint> paramintBounds;
111  typedef std::map<paramkey, paramintBounds> paramintBoundsMap;
112  #define intDefMinBound -10
113  #define intDefMaxBound 10
114 
115  typedef std::pair<paramkey, paramval*> paramvalpair;
116  typedef std::pair<paramkey, parambool*> paramboolpair;
117  typedef std::pair<paramkey, paramint*> paramintpair;
118 
119  typedef std::vector<Configurable*> configurableList;
120 
121  /// nice predicate function for finding by ID
122  struct matchId : public std::unary_function<Configurable*, bool>
123  {
124  matchId(int id) :
125  id(id)
126  {
127  }
128  int id;
130  {
131  return c->id == id;
132  }
133  };
134 
136  {
137  id = rand();
138  }
139  /// intialise with name and revision (use "$ID$")
140  Configurable(const std::string& name, const std::string& revision) :
141  name(name), revision(revision)
142  {
143  id = rand();
144  }
145 
146 // Configurable(const Configurable& copy)
147 // :id(copy.id), name(copy.name), revision(revision),
148 // mapOfValues(mapOfValues), mapOfBoolean(mapOfBoolean), mapOfInteger(mapOfInteger)
149 // {
150 // }
151 
152 
153  virtual ~Configurable()
154  {
155  }
156 
157  /**
158  Is called when a parameter was changes via setParam(). Note that
159  it is not called of parameters of childs are changed, then there notifyOnChange() method
160  is called. The key and of the changed parameter
161  (use getParam() to retrieve its actual value).
162  Overload this function when special actions have to be taken on parameter changes.
163  */
164  virtual void notifyOnChange(const paramkey& key){}
165 
166  /**
167  This is the new style for adding configurable parameters. Just call this function
168  for each parameter and you are done.
169  If you need to do some special treatment for setting (or getting) of the parameter
170  you can handle this by overloading getParam and setParam
171  */
172  virtual void addParameter(const paramkey& key, paramval* val,
173  paramval minBound, paramval maxBound,
174  const paramdescr& descr = paramdescr() ) {
175  mapOfValues[key] = val;
176  if (minBound>*val) minBound = (*val)>0 ? 0 : (*val)*2;
177  if (maxBound<*val) maxBound = (*val)>0 ? (*val)*2 : 0;
178  if(!descr.empty()) mapOfDescr[key] = descr;
179  mapOfValBounds[key]=paramvalBounds(minBound,maxBound);
180  }
181 
182  /// See addParameter(const paramkey& key, paramval* val, paramval minBound, paramval maxBound, const paramdescr& descr)
183  virtual void addParameter(const paramkey& key, paramval* val,
184  const paramdescr& descr = paramdescr()){
185  addParameter(key,val,valDefMinBound, valDefMaxBound, descr);
186  }
187 
188 
189  /**
190  See addParameter(const paramkey& key, paramval* val) but for bool values
191  */
192  virtual void addParameter(const paramkey& key, parambool* val,
193  const paramdescr& descr = paramdescr()) {
194  mapOfBoolean[key] = val;
195  if(!descr.empty()) mapOfDescr[key] = descr;
196  }
197 
198  /**
199  See addParameter(const paramkey& key, paramval* val) but for int values
200  */
201  virtual void addParameter(const paramkey& key, paramint* val,
202  paramint minBound, paramint maxBound,
203  const paramdescr& descr = paramdescr()) {
204  mapOfInteger[key] = val;
205  if (minBound>*val) minBound = (*val)>0 ? 0 : (*val)*2;
206  if (maxBound<*val) maxBound = (*val)>0 ? (*val)*2 : 0;
207  if(!descr.empty()) mapOfDescr[key] = descr;
208  mapOfIntBounds[key]=paramintBounds(minBound,maxBound);
209  }
210 
211  virtual void addParameter(const paramkey& key, paramint* val,
212  const paramdescr& descr = paramdescr()){
213  addParameter(key,val,intDefMinBound, intDefMaxBound, descr);
214  }
215 
216  /**
217  This function is only provided for convenience. It does the same as addParameter but set the
218  variable to the default value
219  */
220  virtual void addParameterDef(const paramkey& key, paramval* val, paramval def,
221  paramval minBound, paramval maxBound,
222  const paramdescr& descr = paramdescr()){
223  *val = def;
224  addParameter(key,val, minBound, maxBound, descr);
225  }
226 
227  virtual void addParameterDef(const paramkey& key, paramval* val, paramval def,
228  const paramdescr& descr = paramdescr()){
229  addParameterDef(key,val,def,valDefMinBound, valDefMaxBound, descr);
230  }
231 
232 
233  /// See addParameterDef(const paramkey&, paramval*, paramval)
234  virtual void addParameterDef(const paramkey& key, parambool* val, parambool def,
235  const paramdescr& descr = paramdescr()) {
236  *val = def;
237  addParameter(key,val,descr);
238  }
239 
240  /// See addParameterDef(const paramkey&, paramval*, paramval)
241  virtual void addParameterDef(const paramkey& key, paramint* val, paramint def,
242  paramint minBound, paramint maxBound,
243  const paramdescr& descr = paramdescr()) {
244  *val = def;
245  addParameter(key,val, minBound, maxBound, descr);
246  }
247 
248  virtual void addParameterDef(const paramkey& key, paramint* val, paramint def,
249  const paramdescr& descr = paramdescr()) {
250  addParameterDef(key,val,def,intDefMinBound, intDefMaxBound, descr);
251  }
252 
253  /// sets a description for the given parameter
254  virtual void setParamDescr(const paramkey& key, const paramdescr& descr,
255  bool traverseChildren = true);
256 
257 
258  /// return the id of the configurable objects, which is created by random on initialisation
259  int getId() const {
260  return id;
261  }
262 
263  /// return the name of the object
264  virtual paramkey getName() const {
265  return name;
266  }
267 
268  /// returns the revision of the object
269  virtual paramkey getRevision() const {
270  return revision;
271  }
272 
273  /**
274  * Sets the name of the configurable.
275  * @param name the name to set
276  * @param callSetNameOfInspectable if true and if this instance is also inspectable,
277  * call automatically setNameOfInspectable(name).
278  */
279  virtual void setName(const paramkey& name, bool callSetNameOfInspectable = true);
280 
281  /// sets the revision Hint: { return "$ID$"; }
282  virtual void setRevision(const paramkey& revision) {
283  this->revision = revision;
284  }
285 
286  /** returns the value of the requested parameter
287  or 0 (+ error message to stderr) if unknown.
288  */
289  virtual paramval getParam(const paramkey& key, bool traverseChildren = true) const;
290 
291  /**
292  * Returns if the requested parameter is part of the configurable or their children
293  * @param key to search for
294  * @return true if key found, otherwise false
295  */
296  virtual bool hasParam(const paramkey& key, bool traverseChildren = true) const;
297 
298  /** sets the value of the given parameter
299  or does nothing if unknown.
300  */
301  virtual bool setParam(const paramkey& key, paramval val, bool traverseChildren = true);
302 
303  /**
304  * Sets the bounds (minBound and maxBound) of the given parameter.
305  * Not useful for parambool.
306  * If minBound=maxBound, it is threated as that no bound is given.
307  */
308  virtual void setParamBounds(const paramkey& key, paramval minBound, paramval maxBound, bool traverseChildren = true);
309 
310  virtual void setParamBounds(const paramkey& key, paramint minBound, paramint maxBound, bool traverseChildren = true);
311 
312  virtual void setParamBounds(const paramkey& key, paramvalBounds bounds, bool traverseChildren = true);
313 
314  virtual void setParamBounds(const paramkey& key, paramintBounds bounds, bool traverseChildren = true);
315 
316  /** The list of all parameters with there value as allocated lists.
317  Note that these are only parameters that are managed manually (with setParam, getParam)
318  @see getAllParamNames()
319  @return list of key-value pairs
320  */
321  virtual paramlist getParamList() const {
322  return paramlist(); // return an empty list
323  }
324 
325  /// returns all names that are configureable
326  virtual std::list<paramkey> getAllParamNames(bool traverseChildren = true);
327 
328  virtual parammap getParamValMap() const {
329  return mapOfValues;
330  }
331 
332  virtual paramintmap getParamIntMap() const {
333  return mapOfInteger;
334  }
335 
336  virtual paramboolmap getParamBoolMap() const {
337  return mapOfBoolean;
338  }
339 
340  /// returns the description for the given parameter
341  virtual paramdescr getParamDescr(const paramkey& key, bool traverseChildren = true) const;
342 
343  virtual paramvalBounds getParamvalBounds(const paramkey& key, bool traverseChildren = true) const;
344 
345  virtual paramintBounds getParamintBounds(const paramkey& key, bool traverseChildren = true) const;
346 
347  virtual bool hasParamDescr(const paramkey& key, bool traverseChildren = true) const;
348 
349  virtual bool hasParamvalBounds(const paramkey& key, bool traverseChildren = true) const;
350 
351  virtual bool hasParamintBounds(const paramkey& key, bool traverseChildren = true) const;
352 
353  /** stores the key values paires into the file : filenamestem.cfg
354  including the comments given in the list
355  */
356  virtual bool storeCfg(const char* filenamestem, const std::list<std::string>& comments = std::list<std::string>());
357  /** restores the key values paires from the file : filenamestem.cfg */
358  virtual bool restoreCfg(const char* filenamestem);
359  /// prints the keys, values and descriptions to the file. Each line is prefixed
360  void print(FILE* f, const char* prefix, int columns=90, bool traverseChildren = true) const;
361 
362  /// parses the configuration from the given file
363  bool parse(FILE* f, const char* prefix = 0, bool traverseChildren = true);
364 
365  /**
366  * Adds a configurable as a child object.
367  * @param conf the instance to add
368  */
369  virtual void addConfigurable(Configurable* conf);
370 
371  /**
372  * Removes a configurable as a child object.
373  * @param conf the instance to remove
374  */
375  virtual void removeConfigurable(Configurable* conf);
376 
377  /**
378  * Returns the list containing all configurable children.
379  */
380  virtual const configurableList& getConfigurables() const;
381 
382  /**
383  * Indicates that the configurable itself or the configurable children
384  * attached to this configurable have changed.
385  * This method must be called manually so that the Configurator GUI can react
386  * at the changes.
387  * This is done through the callbackable interface
388  * (using CallbackableType CALLBACK_CONFIGURABLE_CHANGED).
389  */
390  virtual void configurableChanged();
391 
393 
394  protected:
395  /// copies the internal params of the given configurable
396  void copyParameters(const Configurable&, bool traverseChildren = true);
397 
398  // internal function to print only description in multiline fasion
399  void printdescr(FILE* f, const char* prefix, const paramkey& key,
400  int columns, int indent) const;
401 
402 
403  private:
404  int id;
405  paramkey name;
406  paramkey revision;
407 
408  parammap mapOfValues;
409  paramboolmap mapOfBoolean;
410  paramintmap mapOfInteger;
411  paramdescrmap mapOfDescr;
412 
413  paramvalBoundsMap mapOfValBounds;
414  paramintBoundsMap mapOfIntBounds;
415 
416  void initParamBounds(const paramkey& key);
417 
418  configurableList ListOfConfigurableChildren;
419  Configurable* parent;
420 };
421 
422 #endif // __CONFIGURABLE_H
virtual bool restoreCfg(const char *filenamestem)
restores the key values paires from the file : filenamestem.cfg
Definition: configurable.cpp:53
virtual void addParameter(const paramkey &key, paramval *val, const paramdescr &descr=paramdescr())
See addParameter(const paramkey& key, paramval* val, paramval minBound, paramval maxBound, const paramdescr& descr)
Definition: configurable.h:183
std::list< std::pair< paramkey, paramint > > paramintlist
Definition: configurable.h:99
virtual bool setParam(const paramkey &key, paramval val, bool traverseChildren=true)
sets the value of the given parameter or does nothing if unknown.
Definition: configurable.cpp:111
virtual paramlist getParamList() const
The list of all parameters with there value as allocated lists.
Definition: configurable.h:321
bool parambool
Definition: configurable.h:93
virtual bool hasParamDescr(const paramkey &key, bool traverseChildren=true) const
Definition: configurable.cpp:183
virtual void setName(const paramkey &name, bool callSetNameOfInspectable=true)
Sets the name of the configurable.
Definition: configurable.cpp:445
void copyParameters(const Configurable &, bool traverseChildren=true)
copies the internal params of the given configurable
Definition: configurable.cpp:196
std::pair< paramkey, paramint * > paramintpair
Definition: configurable.h:117
std::string paramkey
Definition: configurable.h:85
virtual void addConfigurable(Configurable *conf)
Adds a configurable as a child object.
Definition: configurable.cpp:427
virtual bool storeCfg(const char *filenamestem, const std::list< std::string > &comments=std::list< std::string >())
stores the key values paires into the file : filenamestem.cfg including the comments given in the lis...
Definition: configurable.cpp:37
std::string paramdescr
Definition: configurable.h:86
charArray paramkey
Definition: avrtypes.h:36
std::list< std::pair< paramkey, paramval > > paramlist
Definition: configurable.h:89
virtual paramintmap getParamIntMap() const
Definition: configurable.h:332
std::vector< Configurable * > configurableList
Definition: configurable.h:119
#define intDefMaxBound
Definition: configurable.h:113
Configurable(const std::string &name, const std::string &revision)
intialise with name and revision (use "$ID$")
Definition: configurable.h:140
virtual void addParameterDef(const paramkey &key, parambool *val, parambool def, const paramdescr &descr=paramdescr())
See addParameterDef(const paramkey&, paramval*, paramval)
Definition: configurable.h:234
virtual paramkey getRevision() const
returns the revision of the object
Definition: configurable.h:269
void printdescr(FILE *f, const char *prefix, const paramkey &key, int columns, int indent) const
Definition: configurable.cpp:364
void print(FILE *f, const char *prefix, int columns=90, bool traverseChildren=true) const
prints the keys, values and descriptions to the file. Each line is prefixed
Definition: configurable.cpp:308
virtual paramdescr getParamDescr(const paramkey &key, bool traverseChildren=true) const
returns the description for the given parameter
Definition: configurable.cpp:170
virtual parammap getParamValMap() const
Definition: configurable.h:328
matchId(int id)
Definition: configurable.h:124
unsigned long CallbackableType
Definition: backcaller.h:45
double paramval
Definition: configurable.h:88
std::map< paramkey, paramintBounds > paramintBoundsMap
Definition: configurable.h:111
virtual ~Configurable()
Definition: configurable.h:153
std::pair< paramkey, paramval * > paramvalpair
Definition: configurable.h:115
std::pair< paramkey, parambool * > paramboolpair
Definition: configurable.h:116
#define valDefMaxBound
Definition: configurable.h:107
virtual void addParameterDef(const paramkey &key, paramint *val, paramint def, paramint minBound, paramint maxBound, const paramdescr &descr=paramdescr())
See addParameterDef(const paramkey&, paramval*, paramval)
Definition: configurable.h:241
virtual paramval getParam(const paramkey &key, bool traverseChildren=true) const
returns the value of the requested parameter or 0 (+ error message to stderr) if unknown.
Definition: configurable.cpp:67
virtual void addParameter(const paramkey &key, parambool *val, const paramdescr &descr=paramdescr())
See addParameter(const paramkey& key, paramval* val) but for bool values.
Definition: configurable.h:192
#define valDefMinBound
Definition: configurable.h:108
virtual void removeConfigurable(Configurable *conf)
Removes a configurable as a child object.
Definition: configurable.cpp:432
nice predicate function for finding by ID
Definition: configurable.h:122
double paramval
Definition: avrtypes.h:37
std::map< paramkey, paramval * > parammap
Definition: configurable.h:90
virtual bool hasParamintBounds(const paramkey &key, bool traverseChildren=true) const
Definition: configurable.cpp:249
virtual void addParameter(const paramkey &key, paramval *val, paramval minBound, paramval maxBound, const paramdescr &descr=paramdescr())
This is the new style for adding configurable parameters.
Definition: configurable.h:172
virtual void addParameter(const paramkey &key, paramint *val, const paramdescr &descr=paramdescr())
Definition: configurable.h:211
Abstact class for configurable objects.
Definition: configurable.h:81
virtual paramboolmap getParamBoolMap() const
Definition: configurable.h:336
virtual void setRevision(const paramkey &revision)
sets the revision Hint: { return "$ID$"; }
Definition: configurable.h:282
virtual std::list< paramkey > getAllParamNames(bool traverseChildren=true)
returns all names that are configureable
Definition: configurable.cpp:145
static const CallbackableType CALLBACK_CONFIGURABLE_CHANGED
Definition: configurable.h:392
std::map< paramkey, paramint * > paramintmap
Definition: configurable.h:100
virtual void addParameterDef(const paramkey &key, paramint *val, paramint def, const paramdescr &descr=paramdescr())
Definition: configurable.h:248
int paramint
Definition: configurable.h:98
virtual void addParameter(const paramkey &key, paramint *val, paramint minBound, paramint maxBound, const paramdescr &descr=paramdescr())
See addParameter(const paramkey& key, paramval* val) but for int values.
Definition: configurable.h:201
virtual void addParameterDef(const paramkey &key, paramval *val, paramval def, paramval minBound, paramval maxBound, const paramdescr &descr=paramdescr())
This function is only provided for convenience.
Definition: configurable.h:220
Configurable()
Definition: configurable.h:135
virtual void setParamBounds(const paramkey &key, paramval minBound, paramval maxBound, bool traverseChildren=true)
Sets the bounds (minBound and maxBound) of the given parameter.
Definition: configurable.cpp:262
std::pair< paramval, paramval > paramvalBounds
Definition: configurable.h:105
std::list< std::pair< paramkey, parambool > > paramboollist
Definition: configurable.h:94
std::map< paramkey, paramdescr > paramdescrmap
Definition: configurable.h:102
virtual bool hasParam(const paramkey &key, bool traverseChildren=true) const
Returns if the requested parameter is part of the configurable or their children. ...
Definition: configurable.cpp:96
virtual void notifyOnChange(const paramkey &key)
Is called when a parameter was changes via setParam().
Definition: configurable.h:164
std::map< paramkey, paramvalBounds > paramvalBoundsMap
Definition: configurable.h:106
virtual void addParameterDef(const paramkey &key, paramval *val, paramval def, const paramdescr &descr=paramdescr())
Definition: configurable.h:227
virtual void configurableChanged()
Indicates that the configurable itself or the configurable children attached to this configurable hav...
Definition: configurable.cpp:441
bool parse(FILE *f, const char *prefix=0, bool traverseChildren=true)
parses the configuration from the given file
Definition: configurable.cpp:384
std::map< paramkey, parambool * > paramboolmap
Definition: configurable.h:95
virtual bool hasParamvalBounds(const paramkey &key, bool traverseChildren=true) const
Definition: configurable.cpp:223
int id
Definition: configurable.h:128
bool operator()(Configurable *c)
Definition: configurable.h:129
#define intDefMinBound
Definition: configurable.h:112
virtual paramintBounds getParamintBounds(const paramkey &key, bool traverseChildren=true) const
Definition: configurable.cpp:235
Class prototype which provides functions to handle callbackable classes.
Definition: backcaller.h:42
int getId() const
return the id of the configurable objects, which is created by random on initialisation ...
Definition: configurable.h:259
virtual void setParamDescr(const paramkey &key, const paramdescr &descr, bool traverseChildren=true)
sets a description for the given parameter
Definition: configurable.cpp:292
virtual paramvalBounds getParamvalBounds(const paramkey &key, bool traverseChildren=true) const
Definition: configurable.cpp:210
int c
Definition: hexapod.cpp:56
virtual paramkey getName() const
return the name of the object
Definition: configurable.h:264
virtual const configurableList & getConfigurables() const
Returns the list containing all configurable children.
Definition: configurable.cpp:437
std::pair< paramint, paramint > paramintBounds
Definition: configurable.h:110