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