src/FDM/JSBSim/input_output/FGPropertyManager.h

   1 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2
   3  Header:       FGPropertyManager.h
   4  Author:       Tony Peden
   5                Based on work originally by David Megginson
   6  Date:         2/2002
   7
   8  ------------- Copyright (C) 2002 -------------
   9
  10  This program is free software; you can redistribute it and/or modify it under
  11  the terms of the GNU Lesser General Public License as published by the Free Software
  12  Foundation; either version 2 of the License, or (at your option) any later
  13  version.
  14
  15  This program is distributed in the hope that it will be useful, but WITHOUT
  16  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  17  FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
  18  details.
  19
  20  You should have received a copy of the GNU Lesser General Public License along with
  21  this program; if not, write to the Free Software Foundation, Inc., 59 Temple
  22  Place - Suite 330, Boston, MA  02111-1307, USA.
  23
  24  Further information about the GNU Lesser General Public License can also be found on
  25  the world wide web at http://www.gnu.org.
  26
  27 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  28 SENTRY
  29 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  30
  31 #ifndef FGPROPERTYMANAGER_H
  32 #define FGPROPERTYMANAGER_H
  33
  34 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  35 INCLUDES
  36 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  37
  38 #include <string>
  39 #ifdef FGFS
  40 #  include <simgear/props/props.hxx>
  41 #else
  42 #  include "simgear/props/props.hxx"
  43 #endif
  44
  45 #include "FGJSBBase.h"
  46
  47 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  48 DEFINITIONS
  49 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  50
  51 #define ID_PROPERTYMANAGER "$Id$"
  52
  53 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  54 FORWARD DECLARATIONS
  55 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  56
  57 using namespace std;
  58
  59 namespace JSBSim {
  60
  61 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  62 CLASS DOCUMENTATION
  63 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  64
  65 /** Class wrapper for property handling.
  66     @author David Megginson, Tony Peden
  67   */
  68
  69 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  70 CLASS DECLARATION
  71 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  72
  73 class FGPropertyManager : public SGPropertyNode, public FGJSBBase
  74 {
  75   private:
  76     static bool suppress_warning;
  77   public:
  78     /// Constructor
  79     FGPropertyManager(void) {suppress_warning = false;}
  80     /// Destructor
  81     virtual ~FGPropertyManager(void) {}
  82
  83     /** Property-ify a name
  84      *  replaces spaces with '-' and, optionally, makes name all lower case
  85      *  @param name string to change
  86      *  @param lowercase true to change all upper case chars to lower
  87      *  NOTE: this function changes its argument and thus relies
  88      *  on pass by value
  89      */
  90     string mkPropertyName(string name, bool lowercase);
  91
  92     /**
  93      * Get a property node.
  94      *
  95      * @param path The path of the node, relative to root.
  96      * @param create true to create the node if it doesn't exist.
  97      * @return The node, or 0 if none exists and none was created.
  98      */
  99     FGPropertyManager*
 100     GetNode (const string &path, bool create = false);
 101
 102     FGPropertyManager*
 103     GetNode (const string &relpath, int index, bool create = false);
 104
 105     /**
 106      * Test whether a given node exists.
 107      *
 108      * @param path The path of the node, relative to root.
 109      * @return true if the node exists, false otherwise.
 110      */
 111     bool HasNode (const string &path);
 112
 113     /**
 114      * Get the name of a node
 115      */
 116     string GetName( void );
 117
 118     /**
 119      * Get the name of a node without underscores, etc.
 120      */
 121     string GetPrintableName( void );
 122
 123     /**
 124      * Get the fully qualified name of a node
 125      * This function is very slow, so is probably useful for debugging only.
 126      */
 127     string GetFullyQualifiedName(void);
 128
 129     /**
 130      * Get a bool value for a property.
 131      *
 132      * This method is convenient but inefficient.  It should be used
 133      * infrequently (i.e. for initializing, loading, saving, etc.),
 134      * not in the main loop.  If you need to get a value frequently,
 135      * it is better to look up the node itself using GetNode and then
 136      * use the node's getBoolValue() method, to avoid the lookup overhead.
 137      *
 138      * @param name The property name.
 139      * @param defaultValue The default value to return if the property
 140      *        does not exist.
 141      * @return The property's value as a bool, or the default value provided.
 142      */
 143     bool GetBool (const string &name, bool defaultValue = false);
 144
 145
 146     /**
 147      * Get an int value for a property.
 148      *
 149      * This method is convenient but inefficient.  It should be used
 150      * infrequently (i.e. for initializing, loading, saving, etc.),
 151      * not in the main loop.  If you need to get a value frequently,
 152      * it is better to look up the node itself using GetNode and then
 153      * use the node's getIntValue() method, to avoid the lookup overhead.
 154      *
 155      * @param name The property name.
 156      * @param defaultValue The default value to return if the property
 157      *        does not exist.
 158      * @return The property's value as an int, or the default value provided.
 159      */
 160     int GetInt (const string &name, int defaultValue = 0);
 161
 162
 163     /**
 164      * Get a long value for a property.
 165      *
 166      * This method is convenient but inefficient.  It should be used
 167      * infrequently (i.e. for initializing, loading, saving, etc.),
 168      * not in the main loop.  If you need to get a value frequently,
 169      * it is better to look up the node itself using GetNode and then
 170      * use the node's getLongValue() method, to avoid the lookup overhead.
 171      *
 172      * @param name The property name.
 173      * @param defaultValue The default value to return if the property
 174      *        does not exist.
 175      * @return The property's value as a long, or the default value provided.
 176      */
 177     int GetLong (const string &name, long defaultValue = 0L);
 178
 179
 180     /**
 181      * Get a float value for a property.
 182      *
 183      * This method is convenient but inefficient.  It should be used
 184      * infrequently (i.e. for initializing, loading, saving, etc.),
 185      * not in the main loop.  If you need to get a value frequently,
 186      * it is better to look up the node itself using GetNode and then
 187      * use the node's getFloatValue() method, to avoid the lookup overhead.
 188      *
 189      * @param name The property name.
 190      * @param defaultValue The default value to return if the property
 191      *        does not exist.
 192      * @return The property's value as a float, or the default value provided.
 193      */
 194     float GetFloat (const string &name, float defaultValue = 0.0);
 195
 196
 197     /**
 198      * Get a double value for a property.
 199      *
 200      * This method is convenient but inefficient.  It should be used
 201      * infrequently (i.e. for initializing, loading, saving, etc.),
 202      * not in the main loop.  If you need to get a value frequently,
 203      * it is better to look up the node itself using GetNode and then
 204      * use the node's getDoubleValue() method, to avoid the lookup overhead.
 205      *
 206      * @param name The property name.
 207      * @param defaultValue The default value to return if the property
 208      *        does not exist.
 209      * @return The property's value as a double, or the default value provided.
 210      */
 211     double GetDouble (const string &name, double defaultValue = 0.0);
 212
 213
 214     /**
 215      * Get a string value for a property.
 216      *
 217      * This method is convenient but inefficient.  It should be used
 218      * infrequently (i.e. for initializing, loading, saving, etc.),
 219      * not in the main loop.  If you need to get a value frequently,
 220      * it is better to look up the node itself using GetNode and then
 221      * use the node's getStringValue() method, to avoid the lookup overhead.
 222      *
 223      * @param name The property name.
 224      * @param defaultValue The default value to return if the property
 225      *        does not exist.
 226      * @return The property's value as a string, or the default value provided.
 227      */
 228     string GetString (const string &name, string defaultValue = "");
 229
 230
 231     /**
 232      * Set a bool value for a property.
 233      *
 234      * Assign a bool value to a property.  If the property does not
 235      * yet exist, it will be created and its type will be set to
 236      * BOOL; if it has a type of UNKNOWN, the type will also be set to
 237      * BOOL; otherwise, the bool value will be converted to the property's
 238      * type.
 239      *
 240      * @param name The property name.
 241      * @param val The new value for the property.
 242      * @return true if the assignment succeeded, false otherwise.
 243      */
 244     bool SetBool (const string &name, bool val);
 245
 246
 247     /**
 248      * Set an int value for a property.
 249      *
 250      * Assign an int value to a property.  If the property does not
 251      * yet exist, it will be created and its type will be set to
 252      * INT; if it has a type of UNKNOWN, the type will also be set to
 253      * INT; otherwise, the bool value will be converted to the property's
 254      * type.
 255      *
 256      * @param name The property name.
 257      * @param val The new value for the property.
 258      * @return true if the assignment succeeded, false otherwise.
 259      */
 260     bool SetInt (const string &name, int val);
 261
 262
 263     /**
 264      * Set a long value for a property.
 265      *
 266      * Assign a long value to a property.  If the property does not
 267      * yet exist, it will be created and its type will be set to
 268      * LONG; if it has a type of UNKNOWN, the type will also be set to
 269      * LONG; otherwise, the bool value will be converted to the property's
 270      * type.
 271      *
 272      * @param name The property name.
 273      * @param val The new value for the property.
 274      * @return true if the assignment succeeded, false otherwise.
 275      */
 276     bool SetLong (const string &name, long val);
 277
 278
 279     /**
 280      * Set a float value for a property.
 281      *
 282      * Assign a float value to a property.  If the property does not
 283      * yet exist, it will be created and its type will be set to
 284      * FLOAT; if it has a type of UNKNOWN, the type will also be set to
 285      * FLOAT; otherwise, the bool value will be converted to the property's
 286      * type.
 287      *
 288      * @param name The property name.
 289      * @param val The new value for the property.
 290      * @return true if the assignment succeeded, false otherwise.
 291      */
 292     bool SetFloat (const string &name, float val);
 293
 294
 295     /**
 296      * Set a double value for a property.
 297      *
 298      * Assign a double value to a property.  If the property does not
 299      * yet exist, it will be created and its type will be set to
 300      * DOUBLE; if it has a type of UNKNOWN, the type will also be set to
 301      * DOUBLE; otherwise, the double value will be converted to the property's
 302      * type.
 303      *
 304      * @param name The property name.
 305      * @param val The new value for the property.
 306      * @return true if the assignment succeeded, false otherwise.
 307      */
 308     bool SetDouble (const string &name, double val);
 309
 310
 311     /**
 312      * Set a string value for a property.
 313      *
 314      * Assign a string value to a property.  If the property does not
 315      * yet exist, it will be created and its type will be set to
 316      * STRING; if it has a type of UNKNOWN, the type will also be set to
 317      * STRING; otherwise, the string value will be converted to the property's
 318      * type.
 319      *
 320      * @param name The property name.
 321      * @param val The new value for the property.
 322      * @return true if the assignment succeeded, false otherwise.
 323      */
 324     bool SetString (const string &name, const string &val);
 325
 326
 327     ////////////////////////////////////////////////////////////////////////
 328     // Convenience functions for setting property attributes.
 329     ////////////////////////////////////////////////////////////////////////
 330
 331
 332     /**
 333      * Set the state of the archive attribute for a property.
 334      *
 335      * If the archive attribute is true, the property will be written
 336      * when a flight is saved; if it is false, the property will be
 337      * skipped.
 338      *
 339      * A warning message will be printed if the property does not exist.
 340      *
 341      * @param name The property name.
 342      * @param state The state of the archive attribute (defaults to true).
 343      */
 344     void SetArchivable (const string &name, bool state = true);
 345
 346
 347     /**
 348      * Set the state of the read attribute for a property.
 349      *
 350      * If the read attribute is true, the property value will be readable;
 351      * if it is false, the property value will always be the default value
 352      * for its type.
 353      *
 354      * A warning message will be printed if the property does not exist.
 355      *
 356      * @param name The property name.
 357      * @param state The state of the read attribute (defaults to true).
 358      */
 359     void SetReadable (const string &name, bool state = true);
 360
 361
 362     /**
 363      * Set the state of the write attribute for a property.
 364      *
 365      * If the write attribute is true, the property value may be modified
 366      * (depending on how it is tied); if the write attribute is false, the
 367      * property value may not be modified.
 368      *
 369      * A warning message will be printed if the property does not exist.
 370      *
 371      * @param name The property name.
 372      * @param state The state of the write attribute (defaults to true).
 373      */
 374     void SetWritable (const string &name, bool state = true);
 375
 376
 377     ////////////////////////////////////////////////////////////////////////
 378     // Convenience functions for tying properties, with logging.
 379     ////////////////////////////////////////////////////////////////////////
 380
 381
 382     /**
 383      * Untie a property from an external data source.
 384      *
 385      * Classes should use this function to release control of any
 386      * properties they are managing.
 387      */
 388     void Untie (const string &name);
 389
 390
 391         // Templates cause ambiguity here
 392
 393     /**
 394      * Tie a property to an external bool variable.
 395      *
 396      * The property's value will automatically mirror the variable's
 397      * value, and vice-versa, until the property is untied.
 398      *
 399      * @param name The property name to tie (full path).
 400      * @param pointer A pointer to the variable.
 401      * @param useDefault true if any existing property value should be
 402      *        copied to the variable; false if the variable should not
 403      *        be modified; defaults to true.
 404      */
 405     void
 406     Tie (const string &name, bool *pointer, bool useDefault = true);
 407
 408
 409     /**
 410      * Tie a property to an external int variable.
 411      *
 412      * The property's value will automatically mirror the variable's
 413      * value, and vice-versa, until the property is untied.
 414      *
 415      * @param name The property name to tie (full path).
 416      * @param pointer A pointer to the variable.
 417      * @param useDefault true if any existing property value should be
 418      *        copied to the variable; false if the variable should not
 419      *        be modified; defaults to true.
 420      */
 421     void
 422     Tie (const string &name, int *pointer, bool useDefault = true);
 423
 424
 425     /**
 426      * Tie a property to an external long variable.
 427      *
 428      * The property's value will automatically mirror the variable's
 429      * value, and vice-versa, until the property is untied.
 430      *
 431      * @param name The property name to tie (full path).
 432      * @param pointer A pointer to the variable.
 433      * @param useDefault true if any existing property value should be
 434      *        copied to the variable; false if the variable should not
 435      *        be modified; defaults to true.
 436      */
 437     void
 438     Tie (const string &name, long *pointer, bool useDefault = true);
 439
 440
 441     /**
 442      * Tie a property to an external float variable.
 443      *
 444      * The property's value will automatically mirror the variable's
 445      * value, and vice-versa, until the property is untied.
 446      *
 447      * @param name The property name to tie (full path).
 448      * @param pointer A pointer to the variable.
 449      * @param useDefault true if any existing property value should be
 450      *        copied to the variable; false if the variable should not
 451      *        be modified; defaults to true.
 452      */
 453     void
 454     Tie (const string &name, float *pointer, bool useDefault = true);
 455
 456     /**
 457      * Tie a property to an external double variable.
 458      *
 459      * The property's value will automatically mirror the variable's
 460      * value, and vice-versa, until the property is untied.
 461      *
 462      * @param name The property name to tie (full path).
 463      * @param pointer A pointer to the variable.
 464      * @param useDefault true if any existing property value should be
 465      *        copied to the variable; false if the variable should not
 466      *        be modified; defaults to true.
 467      */
 468     void
 469     Tie (const string &name, double *pointer, bool useDefault = true);
 470
 471 //============================================================================
 472 //
 473 //  All of the following functions *must* be inlined, otherwise linker
 474 //  errors will result
 475 //
 476 //============================================================================
 477
 478     /* template <class V> void
 479     Tie (const string &name, V (*getter)(), void (*setter)(V) = 0,
 480            bool useDefault = true);
 481
 482     template <class V> void
 483     Tie (const string &name, int index, V (*getter)(int),
 484            void (*setter)(int, V) = 0, bool useDefault = true);
 485
 486     template <class T, class V> void
 487     Tie (const string &name, T * obj, V (T::*getter)() const,
 488            void (T::*setter)(V) = 0, bool useDefault = true);
 489
 490     template <class T, class V> void
 491     Tie (const string &name, T * obj, int index,
 492            V (T::*getter)(int) const, void (T::*setter)(int, V) = 0,
 493            bool useDefault = true); */
 494
 495      /**
 496      * Tie a property to a pair of simple functions.
 497      *
 498      * Every time the property value is queried, the getter (if any) will
 499      * be invoked; every time the property value is modified, the setter
 500      * (if any) will be invoked.  The getter can be 0 to make the property
 501      * unreadable, and the setter can be 0 to make the property
 502      * unmodifiable.
 503      *
 504      * @param name The property name to tie (full path).
 505      * @param getter The getter function, or 0 if the value is unreadable.
 506      * @param setter The setter function, or 0 if the value is unmodifiable.
 507      * @param useDefault true if the setter should be invoked with any existing
 508      *        property value should be; false if the old value should be
 509      *        discarded; defaults to true.
 510      */
 511
 512     template <class V> inline void
 513     Tie (const string &name, V (*getter)(), void (*setter)(V) = 0, bool useDefault = true)
 514     {
 515       if (!tie(name.c_str(), SGRawValueFunctions<V>(getter, setter), useDefault))
 516         cout << "Failed to tie property " << name << " to functions" << endl;
 517       else if (debug_lvl & 0x20)
 518         cout << name << endl;
 519     }
 520
 521
 522     /**
 523      * Tie a property to a pair of indexed functions.
 524      *
 525      * Every time the property value is queried, the getter (if any) will
 526      * be invoked with the index provided; every time the property value
 527      * is modified, the setter (if any) will be invoked with the index
 528      * provided.  The getter can be 0 to make the property unreadable, and
 529      * the setter can be 0 to make the property unmodifiable.
 530      *
 531      * @param name The property name to tie (full path).
 532      * @param index The integer argument to pass to the getter and
 533      *        setter functions.
 534      * @param getter The getter function, or 0 if the value is unreadable.
 535      * @param setter The setter function, or 0 if the value is unmodifiable.
 536      * @param useDefault true if the setter should be invoked with any existing
 537      *        property value should there be one; false if the old value should be
 538      *        discarded; defaults to true.
 539      */
 540     template <class V> inline void Tie (const string &name, int index, V (*getter)(int),
 541                                 void (*setter)(int, V) = 0, bool useDefault = true)
 542     {
 543       if (!tie(name.c_str(), SGRawValueFunctionsIndexed<V>(index, getter, setter), useDefault))
 544         cout << "Failed to tie property " << name << " to indexed functions" << endl;
 545       else if (debug_lvl & 0x20)
 546         cout << name << endl;
 547     }
 548
 549
 550     /**
 551      * Tie a property to a pair of object methods.
 552      *
 553      * Every time the property value is queried, the getter (if any) will
 554      * be invoked; every time the property value is modified, the setter
 555      * (if any) will be invoked.  The getter can be 0 to make the property
 556      * unreadable, and the setter can be 0 to make the property
 557      * unmodifiable.
 558      *
 559      * @param name The property name to tie (full path).
 560      * @param obj The object whose methods should be invoked.
 561      * @param getter The object's getter method, or 0 if the value is
 562      *        unreadable.
 563      * @param setter The object's setter method, or 0 if the value is
 564      *        unmodifiable.
 565      * @param useDefault true if the setter should be invoked with any existing
 566      *        property value should be; false if the old value should be
 567      *        discarded; defaults to true.
 568      */
 569     template <class T, class V> inline void
 570     Tie (const string &name, T * obj, V (T::*getter)() const,
 571            void (T::*setter)(V) = 0, bool useDefault = true)
 572     {
 573       if (!tie(name.c_str(), SGRawValueMethods<T,V>(*obj, getter, setter), useDefault))
 574         cout << "Failed to tie property " << name << " to object methods" << endl;
 575       else if (debug_lvl & 0x20)
 576         cout << name << endl;
 577     }
 578
 579     /**
 580      * Tie a property to a pair of indexed object methods.
 581      *
 582      * Every time the property value is queried, the getter (if any) will
 583      * be invoked with the index provided; every time the property value
 584      * is modified, the setter (if any) will be invoked with the index
 585      * provided.  The getter can be 0 to make the property unreadable, and
 586      * the setter can be 0 to make the property unmodifiable.
 587      *
 588      * @param name The property name to tie (full path).
 589      * @param obj The object whose methods should be invoked.
 590      * @param index The integer argument to pass to the getter and
 591      *        setter methods.
 592      * @param getter The getter method, or 0 if the value is unreadable.
 593      * @param setter The setter method, or 0 if the value is unmodifiable.
 594      * @param useDefault true if the setter should be invoked with any existing
 595      *        property value should be; false if the old value should be
 596      *        discarded; defaults to true.
 597      */
 598     template <class T, class V> inline void
 599     Tie (const string &name, T * obj, int index, V (T::*getter)(int) const,
 600                          void (T::*setter)(int, V) = 0, bool useDefault = true)
 601     {
 602       if (!tie(name.c_str(), SGRawValueMethodsIndexed<T,V>(*obj, index, getter, setter), useDefault))
 603         cout << "Failed to tie property " << name << " to indexed object methods" << endl;
 604       else if (debug_lvl & 0x20)
 605         cout << name << endl;
 606    }
 607 };
 608 }
 609 #endif // FGPROPERTYMANAGER_H
 610