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