3 * Interface definition for a property list.
4 * Started Fall 2000 by David Megginson, david@megginson.com
5 * This code is released into the Public Domain.
7 * See props.html for documentation [replace with URL when available].
19 #include <simgear/compiler.h>
29 #if !defined(SG_HAVE_NATIVE_SGI_COMPILERS)
30 SG_USING_STD(istream);
31 SG_USING_STD(ostream);
35 #pragma warn A sloppy coder has defined ALIAS as a macro!
40 #pragma warn A sloppy coder has defined UNKNOWN as a macro!
45 #pragma warn A sloppy coder has defined BOOL as a macro!
50 #pragma warn A sloppy coder has defined INT as a macro!
55 #pragma warn A sloppy coder has defined LONG as a macro!
60 #pragma warn A sloppy coder has defined FLOAT as a macro!
65 #pragma warn A sloppy coder has defined DOUBLE as a macro!
70 #pragma warn A sloppy coder has defined STRING as a macro!
76 ////////////////////////////////////////////////////////////////////////
79 // This is the mechanism that information-providing routines can
80 // use to link their own values to the property manager. Any
81 // SGValue can be tied to a raw value and then untied again.
82 ////////////////////////////////////////////////////////////////////////
86 * Abstract base class for a raw value.
88 * The property manager is implemented in three layers. The {@link
89 * SGPropertyNode} is the highest and most abstract layer,
90 * representing * an LValue/RValue pair: it * records the position
91 * of the property in the property tree and * contains facilities
92 * for navigation to other nodes. Each node * may contain an {@link
93 * SGValue}, which is guaranteed persistent: the * {@link SGValue}
94 * will not change during a session, even if the * property is bound
95 * and unbound multiple times. The SGValue is the * abstraction of
96 * an RValue: it allows for conversion among all of the different
97 * types, and can be bound to external pointers, functions, methods,
98 * or other data sources. Every SGValue contains an SGRawValue of
99 * a specific type. The SGRawValue (this class) may change frequently
100 * during a session as a value is retyped or bound and unbound to
101 * various data source, but the abstract SGValue layer insulates
102 * the application from those changes. The raw value contains no
103 * facilities for data binding or for type conversion: it is simply
104 * the abstraction of a primitive data type (or a compound data
105 * type, in the case of a string).
107 * The SGValue class always keeps a *copy* of a raw value, not the
108 * original one passed to it; if you override a derived class but do
109 * not replace the {@link #clone} method, strange things will happen.
111 * All raw values must implement {@link #getValue}, {@link #setValue},
112 * and {@link #clone} for the appropriate type.
115 * @see SGPropertyNode */
122 * The default underlying value for this type.
124 * Every raw value has a default; the default is false for a
125 * boolean, 0 for the various numeric values, and "" for a string.
126 * If additional types of raw values are added in the future, they
127 * may need different kinds of default values (such as epoch for a
128 * date type). The default value is used when creating new values.
130 static const T DefaultValue; // Default for this kind of raw value.
136 * Use the default value for this type.
144 virtual ~SGRawValue () {}
148 * Return the underlying value.
150 * @return The actual value for the property.
153 virtual T getValue () const = 0;
157 * Assign a new underlying value.
159 * If the new value cannot be set (because this is a read-only
160 * raw value, or because the new value is not acceptable for
161 * some reason) this method returns false and leaves the original
164 * @param value The actual value for the property.
165 * @return true if the value was set successfully, false otherwise.
168 virtual bool setValue (T value) = 0;
172 * Create a new deep copy of this raw value.
174 * The copy will contain its own version of the underlying value
177 * @return A deep copy of the current object.
179 virtual SGRawValue * clone () const = 0;
184 * An unbound raw value, stored internally.
186 * Instances of this class are created automatically, by default,
187 * by the SGValue class; ordinarily the application should not
191 class SGRawValueInternal : public SGRawValue<T>
196 * Default constructor.
198 * Initialize with the default value for this type.
200 SGRawValueInternal () {}
203 * Explicit value constructor.
205 * Initialize with the underlying value provided.
207 * @param value The initial value for this property.
209 SGRawValueInternal (T value) : _value(value) {}
214 virtual ~SGRawValueInternal () {}
217 * Get the underlying value.
219 virtual T getValue () const { return _value; }
222 * Set the underlying value.
224 virtual bool setValue (T value) { _value = value; return true; }
227 * Create a deep copy of this raw value.
229 virtual SGRawValue<T> * clone () const {
230 return new SGRawValueInternal<T>(_value);
239 * A raw value bound to a pointer.
241 * This is the most efficient way to tie an external value, but also
242 * the most dangerous, because there is no way for the supplier to
243 * perform bounds checking and derived calculations except by polling
244 * the variable to see if it has changed. There is no default
245 * constructor, because this class would be meaningless without a
249 class SGRawValuePointer : public SGRawValue<T>
254 * Explicit pointer constructor.
256 * Create a new raw value bound to the value of the variable
257 * referenced by the pointer.
259 * @param ptr The pointer to the variable to which this raw value
262 SGRawValuePointer (T * ptr) : _ptr(ptr) {}
267 virtual ~SGRawValuePointer () {}
270 * Get the underlying value.
272 * This method will dereference the pointer and return the
275 virtual T getValue () const { return *_ptr; }
278 * Set the underlying value.
280 * This method will dereference the pointer and change the
283 virtual bool setValue (T value) { *_ptr = value; return true; }
286 * Create a copy of this raw value.
288 * The copy will use the same external pointer as the original.
290 virtual SGRawValue<T> * clone () const {
291 return new SGRawValuePointer<T>(_ptr);
300 * A value managed through static functions.
302 * A read-only value will not have a setter; a write-only value will
306 class SGRawValueFunctions : public SGRawValue<T>
311 * The template type of a static getter function.
313 typedef T (*getter_t)();
316 * The template type of a static setter function.
318 typedef void (*setter_t)(T);
321 * Explicit constructor.
323 * Create a new raw value bound to the getter and setter supplied.
325 * @param getter A static function for getting a value, or 0
326 * to read-disable the value.
327 * @param setter A static function for setting a value, or 0
328 * to write-disable the value.
330 SGRawValueFunctions (getter_t getter = 0, setter_t setter = 0)
331 : _getter(getter), _setter(setter) {}
336 virtual ~SGRawValueFunctions () {}
339 * Get the underlying value.
341 * This method will invoke the getter function to get a value.
342 * If no getter function was supplied, this method will always
343 * return the default value for the type.
345 virtual T getValue () const {
346 if (_getter) return (*_getter)();
347 else return SGRawValue<T>::DefaultValue;
351 * Set the underlying value.
353 * This method will invoke the setter function to change the
354 * underlying value. If no setter function was supplied, this
355 * method will return false.
357 virtual bool setValue (T value) {
358 if (_setter) { (*_setter)(value); return true; }
363 * Create a copy of this raw value, bound to the same functions.
365 virtual SGRawValue<T> * clone () const {
366 return new SGRawValueFunctions<T>(_getter,_setter);
376 * An indexed value bound to static functions.
378 * A read-only value will not have a setter; a write-only value will
379 * not have a getter. An indexed value is useful for binding one
380 * of a list of possible values (such as multiple engines for a
381 * plane). The index is hard-coded at creation time.
384 class SGRawValueFunctionsIndexed : public SGRawValue<T>
387 typedef T (*getter_t)(int);
388 typedef void (*setter_t)(int,T);
389 SGRawValueFunctionsIndexed (int index, getter_t getter = 0, setter_t setter = 0)
390 : _index(index), _getter(getter), _setter(setter) {}
391 virtual ~SGRawValueFunctionsIndexed () {}
392 virtual T getValue () const {
393 if (_getter) return (*_getter)(_index);
394 else return SGRawValue<T>::DefaultValue;
396 virtual bool setValue (T value) {
397 if (_setter) { (*_setter)(_index, value); return true; }
400 virtual SGRawValue<T> * clone () const {
401 return new SGRawValueFunctionsIndexed<T>(_index, _getter, _setter);
411 * A value managed through an object and access methods.
413 * A read-only value will not have a setter; a write-only value will
416 template <class C, class T>
417 class SGRawValueMethods : public SGRawValue<T>
420 typedef T (C::*getter_t)() const;
421 typedef void (C::*setter_t)(T);
422 SGRawValueMethods (C &obj, getter_t getter = 0, setter_t setter = 0)
423 : _obj(obj), _getter(getter), _setter(setter) {}
424 virtual ~SGRawValueMethods () {}
425 virtual T getValue () const {
426 if (_getter) { return (_obj.*_getter)(); }
427 else { return SGRawValue<T>::DefaultValue; }
429 virtual bool setValue (T value) {
430 if (_setter) { (_obj.*_setter)(value); return true; }
433 virtual SGRawValue<T> * clone () const {
434 return new SGRawValueMethods<C,T>(_obj, _getter, _setter);
444 * An indexed value managed through an object and access methods.
446 * A read-only value will not have a setter; a write-only value will
449 template <class C, class T>
450 class SGRawValueMethodsIndexed : public SGRawValue<T>
453 typedef T (C::*getter_t)(int) const;
454 typedef void (C::*setter_t)(int, T);
455 SGRawValueMethodsIndexed (C &obj, int index,
456 getter_t getter = 0, setter_t setter = 0)
457 : _obj(obj), _index(index), _getter(getter), _setter(setter) {}
458 virtual ~SGRawValueMethodsIndexed () {}
459 virtual T getValue () const {
460 if (_getter) { return (_obj.*_getter)(_index); }
461 else { return SGRawValue<T>::DefaultValue; }
463 virtual bool setValue (T value) {
464 if (_setter) { (_obj.*_setter)(_index, value); return true; }
467 virtual SGRawValue<T> * clone () const {
468 return new SGRawValueMethodsIndexed<C,T>(_obj, _index, _getter, _setter);
482 * This is the value that property-list clients see. It is a
483 * persistent layer over the possibly-changing raw value; once a
484 * client gets an SGValue from the property manager, the pointer
485 * will be good for the life of the property manager itself, no
486 * matter how often the pointer is tied or untied.
501 SGValue (const SGValue &value);
504 Type getType () const;
506 SGValue * getAlias ();
507 const SGValue * getAlias () const;
508 bool alias (SGValue * alias);
510 bool isAlias () const { return _type == ALIAS; }
512 bool getBoolValue () const;
513 int getIntValue () const;
514 long getLongValue () const;
515 float getFloatValue () const;
516 double getDoubleValue () const;
517 string getStringValue () const;
519 bool setBoolValue (bool value);
520 bool setIntValue (int value);
521 bool setLongValue (long value);
522 bool setFloatValue (float value);
523 bool setDoubleValue (double value);
524 bool setStringValue (string value);
525 bool setUnknownValue (string value);
527 bool isTied () const { return _tied; }
529 bool tie (const SGRawValue<bool> &rawValue, bool useDefault = true);
530 bool tie (const SGRawValue<int> &rawValue, bool useDefault = true);
531 bool tie (const SGRawValue<long> &rawValue, bool useDefault = true);
532 bool tie (const SGRawValue<float> &rawValue, bool useDefault = true);
533 bool tie (const SGRawValue<double> &rawValue, bool useDefault = true);
534 bool tie (const SGRawValue<string> &rawValue, bool useDefault = true);
549 // The right kind of pointer...
552 SGRawValue<bool> * bool_val;
553 SGRawValue<int> * int_val;
554 SGRawValue<long> * long_val;
555 SGRawValue<float> * float_val;
556 SGRawValue<double> * double_val;
557 SGRawValue<string> * string_val;
565 * A node in a property tree.
573 virtual ~SGPropertyNode ();
576 bool hasValue () const { return (_value != 0); }
577 SGValue * getValue () { return _value; }
578 SGValue * getValue (bool create);
579 const SGValue * getValue () const { return _value; }
580 const string &getName () const { return _name; }
581 const int getIndex () const { return _index; }
582 SGPropertyNode * getParent () { return _parent; }
583 const SGPropertyNode * getParent () const { return _parent; }
586 bool alias (SGPropertyNode * target);
587 bool alias (const string &path);
589 bool isAlias () const;
590 SGPropertyNode * getAliasTarget ();
591 const SGPropertyNode * getAliasTarget () const;
594 const int nChildren () const { return _children.size(); }
595 SGPropertyNode * getChild (int position);
596 const SGPropertyNode * getChild (int position) const;
597 SGPropertyNode * getChild (const string &name, int index = 0,
598 bool create = false);
599 const SGPropertyNode * getChild (const string &name, int index = 0) const;
601 vector<SGPropertyNode *> getChildren (const string &name);
602 vector<const SGPropertyNode *> getChildren (const string &name) const;
605 string getPath (bool simplify = false) const;
607 // Relative or absolute paths.
608 SGPropertyNode * getRootNode ();
609 const SGPropertyNode * getRootNode () const;
610 SGPropertyNode * getNode (const string &relative_path, bool create = false);
611 const SGPropertyNode * getNode (const string &relative_path) const;
613 // Value-related stuff.
614 SGValue::Type getType () const;
616 bool getBoolValue () const;
617 int getIntValue () const;
618 long getLongValue () const;
619 float getFloatValue () const;
620 double getDoubleValue () const;
621 string getStringValue () const;
623 bool setBoolValue (bool value);
624 bool setIntValue (int value);
625 bool setLongValue (long value);
626 bool setFloatValue (float value);
627 bool setDoubleValue (double value);
628 bool setStringValue (string value);
629 bool setUnknownValue (string value);
631 bool isTied () const;
633 bool tie (const SGRawValue<bool> &rawValue, bool useDefault = true);
634 bool tie (const SGRawValue<int> &rawValue, bool useDefault = true);
635 bool tie (const SGRawValue<long> &rawValue, bool useDefault = true);
636 bool tie (const SGRawValue<float> &rawValue, bool useDefault = true);
637 bool tie (const SGRawValue<double> &rawValue, bool useDefault = true);
638 bool tie (const SGRawValue<string> &rawValue, bool useDefault = true);
642 // Values from paths.
643 bool hasValue (const string &relative_path) const;
644 SGValue * getValue (const string &relative_path, bool create = false);
645 const SGValue * getValue (const string &relative_path) const;
647 SGValue::Type getType (const string &relative_path) const;
649 bool getBoolValue (const string &relative_path,
650 bool defaultValue = false) const;
651 int getIntValue (const string &relative_path,
652 int defaultValue = 0) const;
653 long getLongValue (const string &relative_path,
654 long defaultValue = 0L) const;
655 float getFloatValue (const string &relative_path,
656 float defaultValue = 0.0) const;
657 double getDoubleValue (const string &relative_path,
658 double defaultValue = 0.0L) const;
659 string getStringValue (const string &relative_path,
660 string defaultValue = "") const;
662 bool setBoolValue (const string &relative_path, bool value);
663 bool setIntValue (const string &relative_path, int value);
664 bool setLongValue (const string &relative_path, long value);
665 bool setFloatValue (const string &relative_path, float value);
666 bool setDoubleValue (const string &relative_path, double value);
667 bool setStringValue (const string &relative_path, string value);
668 bool setUnknownValue (const string &relative_path, string value);
670 bool isTied (const string &relative_path) const;
672 bool tie (const string &relative_path, const SGRawValue<bool> &rawValue,
673 bool useDefault = true);
674 bool tie (const string &relative_path, const SGRawValue<int> &rawValue,
675 bool useDefault = true);
676 bool tie (const string &relative_path, const SGRawValue<long> &rawValue,
677 bool useDefault = true);
678 bool tie (const string &relative_path, const SGRawValue<float> &rawValue,
679 bool useDefault = true);
680 bool tie (const string &relative_path, const SGRawValue<double> &rawValue,
681 bool useDefault = true);
682 bool tie (const string &relative_path, const SGRawValue<string> &rawValue,
683 bool useDefault = true);
685 bool untie (const string &relative_path);
689 SGPropertyNode (const string &name, int index, SGPropertyNode * parent);
693 SGPropertyNode (const SGPropertyNode &node) {}
698 SGPropertyNode * _parent;
699 vector<SGPropertyNode *> _children;
700 mutable SGPropertyNode * _target;
706 ////////////////////////////////////////////////////////////////////////
708 ////////////////////////////////////////////////////////////////////////
710 bool readProperties (istream &input, SGPropertyNode * start_node,
711 const string &base = "");
712 bool readProperties (const string &file, SGPropertyNode * start_node);
713 bool writeProperties (ostream &output, const SGPropertyNode * start_node);
714 bool writeProperties (const string &file, const SGPropertyNode * start_node);
715 bool copyProperties (const SGPropertyNode *in, SGPropertyNode *out);
718 #endif // __PROPS_HXX