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