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].
15 #include <simgear/compiler.h>
25 #if !defined(SG_HAVE_NATIVE_SGI_COMPILERS)
26 SG_USING_STD(istream);
27 SG_USING_STD(ostream);
31 #pragma warn A sloppy coder has defined ALIAS as a macro!
36 #pragma warn A sloppy coder has defined UNSPECIFIED as a macro!
41 #pragma warn A sloppy coder has defined BOOL as a macro!
46 #pragma warn A sloppy coder has defined INT as a macro!
51 #pragma warn A sloppy coder has defined LONG as a macro!
56 #pragma warn A sloppy coder has defined FLOAT as a macro!
61 #pragma warn A sloppy coder has defined DOUBLE as a macro!
66 #pragma warn A sloppy coder has defined STRING as a macro!
72 ////////////////////////////////////////////////////////////////////////
75 // This is the mechanism that information-providing routines can
76 // use to link their own values to the property manager. Any
77 // SGValue can be tied to a raw value and then untied again.
78 ////////////////////////////////////////////////////////////////////////
82 * Abstract base class for a raw value.
84 * The property manager is implemented in three layers. The {@link
85 * SGPropertyNode} is the highest and most abstract layer,
86 * representing * an LValue/RValue pair: it * records the position
87 * of the property in the property tree and * contains facilities
88 * for navigation to other nodes. Each node * may contain an {@link
89 * SGValue}, which is guaranteed persistent: the * {@link SGValue}
90 * will not change during a session, even if the * property is bound
91 * and unbound multiple times. The SGValue is the * abstraction of
92 * an RValue: it allows for conversion among all of the different
93 * types, and can be bound to external pointers, functions, methods,
94 * or other data sources. Every SGValue contains an SGRawValue of
95 * a specific type. The SGRawValue (this class) may change frequently
96 * during a session as a value is retyped or bound and unbound to
97 * various data source, but the abstract SGValue layer insulates
98 * the application from those changes. The raw value contains no
99 * facilities for data binding or for type conversion: it is simply
100 * the abstraction of a primitive data type (or a compound data
101 * type, in the case of a string).
103 * The SGValue class always keeps a *copy* of a raw value, not the
104 * original one passed to it; if you override a derived class but do
105 * not replace the {@link #clone} method, strange things will happen.
107 * All raw values must implement {@link #getValue}, {@link #setValue},
108 * and {@link #clone} for the appropriate type.
111 * @see SGPropertyNode */
118 * The default underlying value for this type.
120 * Every raw value has a default; the default is false for a
121 * boolean, 0 for the various numeric values, and "" for a string.
122 * If additional types of raw values are added in the future, they
123 * may need different kinds of default values (such as epoch for a
124 * date type). The default value is used when creating new values.
126 static const T DefaultValue; // Default for this kind of raw value.
132 * Use the default value for this type.
140 virtual ~SGRawValue () {}
144 * Return the underlying value.
146 * @return The actual value for the property.
149 virtual T getValue () const = 0;
153 * Assign a new underlying value.
155 * If the new value cannot be set (because this is a read-only
156 * raw value, or because the new value is not acceptable for
157 * some reason) this method returns false and leaves the original
160 * @param value The actual value for the property.
161 * @return true if the value was set successfully, false otherwise.
164 virtual bool setValue (T value) = 0;
168 * Create a new deep copy of this raw value.
170 * The copy will contain its own version of the underlying value
173 * @return A deep copy of the current object.
175 virtual SGRawValue * clone () const = 0;
180 * An unbound raw value, stored internally.
182 * Instances of this class are created automatically, by default,
183 * by the SGValue class; ordinarily the application should not
187 class SGRawValueInternal : public SGRawValue<T>
192 * Default constructor.
194 * Initialize with the default value for this type.
196 SGRawValueInternal () {}
199 * Explicit value constructor.
201 * Initialize with the underlying value provided.
203 * @param value The initial value for this property.
205 SGRawValueInternal (T value) : _value(value) {}
210 virtual ~SGRawValueInternal () {}
213 * Get the underlying value.
215 virtual T getValue () const { return _value; }
218 * Set the underlying value.
220 virtual bool setValue (T value) { _value = value; return true; }
223 * Create a deep copy of this raw value.
225 virtual SGRawValue<T> * clone () const {
226 return new SGRawValueInternal<T>(_value);
235 * A raw value bound to a pointer.
237 * This is the most efficient way to tie an external value, but also
238 * the most dangerous, because there is no way for the supplier to
239 * perform bounds checking and derived calculations except by polling
240 * the variable to see if it has changed. There is no default
241 * constructor, because this class would be meaningless without a
245 class SGRawValuePointer : public SGRawValue<T>
250 * Explicit pointer constructor.
252 * Create a new raw value bound to the value of the variable
253 * referenced by the pointer.
255 * @param ptr The pointer to the variable to which this raw value
258 SGRawValuePointer (T * ptr) : _ptr(ptr) {}
263 virtual ~SGRawValuePointer () {}
266 * Get the underlying value.
268 * This method will dereference the pointer and return the
271 virtual T getValue () const { return *_ptr; }
274 * Set the underlying value.
276 * This method will dereference the pointer and change the
279 virtual bool setValue (T value) { *_ptr = value; return true; }
282 * Create a copy of this raw value.
284 * The copy will use the same external pointer as the original.
286 virtual SGRawValue<T> * clone () const {
287 return new SGRawValuePointer<T>(_ptr);
296 * A value managed through static functions.
298 * A read-only value will not have a setter; a write-only value will
302 class SGRawValueFunctions : public SGRawValue<T>
307 * The template type of a static getter function.
309 typedef T (*getter_t)();
312 * The template type of a static setter function.
314 typedef void (*setter_t)(T);
317 * Explicit constructor.
319 * Create a new raw value bound to the getter and setter supplied.
321 * @param getter A static function for getting a value, or 0
322 * to read-disable the value.
323 * @param setter A static function for setting a value, or 0
324 * to write-disable the value.
326 SGRawValueFunctions (getter_t getter = 0, setter_t setter = 0)
327 : _getter(getter), _setter(setter) {}
332 virtual ~SGRawValueFunctions () {}
335 * Get the underlying value.
337 * This method will invoke the getter function to get a value.
338 * If no getter function was supplied, this method will always
339 * return the default value for the type.
341 virtual T getValue () const {
342 if (_getter) return (*_getter)();
343 else return SGRawValue<T>::DefaultValue;
347 * Set the underlying value.
349 * This method will invoke the setter function to change the
350 * underlying value. If no setter function was supplied, this
351 * method will return false.
353 virtual bool setValue (T value) {
354 if (_setter) { (*_setter)(value); return true; }
359 * Create a copy of this raw value, bound to the same functions.
361 virtual SGRawValue<T> * clone () const {
362 return new SGRawValueFunctions<T>(_getter,_setter);
372 * An indexed value bound to static functions.
374 * A read-only value will not have a setter; a write-only value will
375 * not have a getter. An indexed value is useful for binding one
376 * of a list of possible values (such as multiple engines for a
377 * plane). The index is hard-coded at creation time.
380 class SGRawValueFunctionsIndexed : public SGRawValue<T>
383 typedef T (*getter_t)(int);
384 typedef void (*setter_t)(int,T);
385 SGRawValueFunctionsIndexed (int index, getter_t getter = 0, setter_t setter = 0)
386 : _index(index), _getter(getter), _setter(setter) {}
387 virtual ~SGRawValueFunctionsIndexed () {}
388 virtual T getValue () const {
389 if (_getter) return (*_getter)(_index);
390 else return SGRawValue<T>::DefaultValue;
392 virtual bool setValue (T value) {
393 if (_setter) { (*_setter)(_index, value); return true; }
396 virtual SGRawValue<T> * clone () const {
397 return new SGRawValueFunctionsIndexed<T>(_index, _getter, _setter);
407 * A value managed through an object and access methods.
409 * A read-only value will not have a setter; a write-only value will
412 template <class C, class T>
413 class SGRawValueMethods : public SGRawValue<T>
416 typedef T (C::*getter_t)() const;
417 typedef void (C::*setter_t)(T);
418 SGRawValueMethods (C &obj, getter_t getter = 0, setter_t setter = 0)
419 : _obj(obj), _getter(getter), _setter(setter) {}
420 virtual ~SGRawValueMethods () {}
421 virtual T getValue () const {
422 if (_getter) { return (_obj.*_getter)(); }
423 else { return SGRawValue<T>::DefaultValue; }
425 virtual bool setValue (T value) {
426 if (_setter) { (_obj.*_setter)(value); return true; }
429 virtual SGRawValue<T> * clone () const {
430 return new SGRawValueMethods<C,T>(_obj, _getter, _setter);
440 * An indexed value managed through an object and access methods.
442 * A read-only value will not have a setter; a write-only value will
445 template <class C, class T>
446 class SGRawValueMethodsIndexed : public SGRawValue<T>
449 typedef T (C::*getter_t)(int) const;
450 typedef void (C::*setter_t)(int, T);
451 SGRawValueMethodsIndexed (C &obj, int index,
452 getter_t getter = 0, setter_t setter = 0)
453 : _obj(obj), _index(index), _getter(getter), _setter(setter) {}
454 virtual ~SGRawValueMethodsIndexed () {}
455 virtual T getValue () const {
456 if (_getter) { return (_obj.*_getter)(_index); }
457 else { return SGRawValue<T>::DefaultValue; }
459 virtual bool setValue (T value) {
460 if (_setter) { (_obj.*_setter)(_index, value); return true; }
463 virtual SGRawValue<T> * clone () const {
464 return new SGRawValueMethodsIndexed<C,T>(_obj, _index, _getter, _setter);
476 * A node in a property tree.
485 * Property value types.
501 * Access mode attributes.
503 * <p>The ARCHIVE attribute is strictly advisory, and controls
504 * whether the property should normally be saved and restored.</p>
514 * Default constructor.
522 SGPropertyNode (const SGPropertyNode &node);
528 virtual ~SGPropertyNode ();
537 * Test whether this node contains a primitive leaf value.
539 bool hasValue () const { return (_type != NONE); }
543 * Get the node's simple (XML) name.
545 const string &getName () const { return _name; }
549 * Get the node's integer index.
551 const int getIndex () const { return _index; }
555 * Get a non-const pointer to the node's parent.
557 SGPropertyNode * getParent () { return _parent; }
561 * Get a const pointer to the node's parent.
563 const SGPropertyNode * getParent () const { return _parent; }
572 * Get the number of child nodes.
574 const int nChildren () const { return _children.size(); }
578 * Get a child node by position (*NOT* index).
580 SGPropertyNode * getChild (int position);
584 * Get a const child node by position (*NOT* index).
586 const SGPropertyNode * getChild (int position) const;
590 * Get a child node by name and index.
592 SGPropertyNode * getChild (const string &name, int index = 0,
593 bool create = false);
597 * Get a const child node by name and index.
599 const SGPropertyNode * getChild (const string &name, int index = 0) const;
603 * Get a vector of all children with the specified name.
605 vector<SGPropertyNode *> getChildren (const string &name);
609 * Get a vector all all children (const) with the specified name.
611 vector<const SGPropertyNode *> getChildren (const string &name) const;
620 * Alias this node's leaf value to another's.
622 bool alias (SGPropertyNode * target);
626 * Alias this node's leaf value to another's by relative path.
628 bool alias (const string &path);
632 * Remove any alias for this node.
638 * Test whether the node's leaf value is aliased to another's.
640 bool isAlias () const { return (_type == ALIAS); }
644 * Get a non-const pointer to the current alias target, if any.
646 SGPropertyNode * getAliasTarget ();
650 * Get a const pointer to the current alias target, if any.
652 const SGPropertyNode * getAliasTarget () const;
661 * Get the path to this node from the root.
663 string getPath (bool simplify = false) const;
667 * Get a pointer to the root node.
669 SGPropertyNode * getRootNode ();
673 * Get a const pointer to the root node.
675 const SGPropertyNode * getRootNode () const;
679 * Get a pointer to another node by relative path.
681 SGPropertyNode * getNode (const string &relative_path, bool create = false);
685 * Get a const pointer to another node by relative path.
687 const SGPropertyNode * getNode (const string &relative_path) const;
695 * Check a single mode attribute for the property node.
697 bool getAttribute (Attribute attr) const { return (_attr & attr); }
701 * Set a single mode attribute for the property node.
703 void setAttribute (Attribute attr, bool state) {
704 (state ? _attr |= attr : _attr &= ~attr);
709 * Get all of the mode attributes for the property node.
711 int getAttributes () const { return _attr; }
715 * Set all of the mode attributes for the property node.
717 void setAttributes (int attr) { _attr = attr; }
721 // Leaf Value (primitive).
726 * Get the type of leaf value, if any, for this node.
728 Type getType () const;
732 * Get a bool value for this node.
734 bool getBoolValue () const;
738 * Get an int value for this node.
740 int getIntValue () const;
744 * Get a long int value for this node.
746 long getLongValue () const;
750 * Get a float value for this node.
752 float getFloatValue () const;
756 * Get a double value for this node.
758 double getDoubleValue () const;
762 * Get a string value for this node.
764 string getStringValue () const;
769 * Set a bool value for this node.
771 bool setBoolValue (bool value);
775 * Set an int value for this node.
777 bool setIntValue (int value);
781 * Set a long int value for this node.
783 bool setLongValue (long value);
787 * Set a float value for this node.
789 bool setFloatValue (float value);
793 * Set a double value for this node.
795 bool setDoubleValue (double value);
799 * Set a string value for this node.
801 bool setStringValue (string value);
805 * Set a value of unspecified type for this node.
807 bool setUnspecifiedValue (string value);
816 * Test whether this node is bound to an external data source.
818 bool isTied () const { return _tied; }
822 * Bind this node to an external bool source.
824 bool tie (const SGRawValue<bool> &rawValue, bool useDefault = true);
828 * Bind this node to an external int source.
830 bool tie (const SGRawValue<int> &rawValue, bool useDefault = true);
834 * Bind this node to an external long int source.
836 bool tie (const SGRawValue<long> &rawValue, bool useDefault = true);
840 * Bind this node to an external float source.
842 bool tie (const SGRawValue<float> &rawValue, bool useDefault = true);
846 * Bind this node to an external double source.
848 bool tie (const SGRawValue<double> &rawValue, bool useDefault = true);
852 * Bind this node to an external string source.
854 bool tie (const SGRawValue<string> &rawValue, bool useDefault = true);
858 * Unbind this node from any external data source.
864 // Convenience methods using paths.
865 // TODO: add attribute methods
870 * Get another node's type.
872 Type getType (const string &relative_path) const;
876 * Test whether another node has a leaf value.
878 bool hasValue (const string &relative_path) const;
882 * Get another node's value as a bool.
884 bool getBoolValue (const string &relative_path,
885 bool defaultValue = false) const;
889 * Get another node's value as an int.
891 int getIntValue (const string &relative_path,
892 int defaultValue = 0) const;
896 * Get another node's value as a long int.
898 long getLongValue (const string &relative_path,
899 long defaultValue = 0L) const;
903 * Get another node's value as a float.
905 float getFloatValue (const string &relative_path,
906 float defaultValue = 0.0) const;
910 * Get another node's value as a double.
912 double getDoubleValue (const string &relative_path,
913 double defaultValue = 0.0L) const;
917 * Get another node's value as a string.
919 string getStringValue (const string &relative_path,
920 string defaultValue = "") const;
924 * Set another node's value as a bool.
926 bool setBoolValue (const string &relative_path, bool value);
930 * Set another node's value as an int.
932 bool setIntValue (const string &relative_path, int value);
936 * Set another node's value as a long int.
938 bool setLongValue (const string &relative_path, long value);
942 * Set another node's value as a float.
944 bool setFloatValue (const string &relative_path, float value);
948 * Set another node's value as a double.
950 bool setDoubleValue (const string &relative_path, double value);
954 * Set another node's value as a string.
956 bool setStringValue (const string &relative_path, string value);
960 * Set another node's value with no specified type.
962 bool setUnspecifiedValue (const string &relative_path, string value);
966 * Test whether another node is bound to an external data source.
968 bool isTied (const string &relative_path) const;
972 * Bind another node to an external bool source.
974 bool tie (const string &relative_path, const SGRawValue<bool> &rawValue,
975 bool useDefault = true);
979 * Bind another node to an external int source.
981 bool tie (const string &relative_path, const SGRawValue<int> &rawValue,
982 bool useDefault = true);
986 * Bind another node to an external long int source.
988 bool tie (const string &relative_path, const SGRawValue<long> &rawValue,
989 bool useDefault = true);
993 * Bind another node to an external float source.
995 bool tie (const string &relative_path, const SGRawValue<float> &rawValue,
996 bool useDefault = true);
1000 * Bind another node to an external double source.
1002 bool tie (const string &relative_path, const SGRawValue<double> &rawValue,
1003 bool useDefault = true);
1007 * Bind another node to an external string source.
1009 bool tie (const string &relative_path, const SGRawValue<string> &rawValue,
1010 bool useDefault = true);
1014 * Unbind another node from any external data source.
1016 bool untie (const string &relative_path);
1023 * Protected constructor for making new nodes on demand.
1025 SGPropertyNode (const string &name, int index, SGPropertyNode * parent);
1032 * Clear any existing value and set the type to NONE.
1034 void clear_value ();
1038 SGPropertyNode * _parent;
1039 vector<SGPropertyNode *> _children;
1046 // The right kind of pointer...
1048 SGPropertyNode * alias;
1049 SGRawValue<bool> * bool_val;
1050 SGRawValue<int> * int_val;
1051 SGRawValue<long> * long_val;
1052 SGRawValue<float> * float_val;
1053 SGRawValue<double> * double_val;
1054 SGRawValue<string> * string_val;
1062 ////////////////////////////////////////////////////////////////////////
1064 ////////////////////////////////////////////////////////////////////////
1068 * Read properties from an XML input stream.
1070 void readProperties (istream &input, SGPropertyNode * start_node,
1071 const string &base = "");
1075 * Read properties from an XML file.
1077 void readProperties (const string &file, SGPropertyNode * start_node);
1081 * Write properties to an XML output stream.
1083 void writeProperties (ostream &output, const SGPropertyNode * start_node);
1087 * Write properties to an XML file.
1089 void writeProperties (const string &file, const SGPropertyNode * start_node);
1093 * Copy properties from one node to another.
1095 bool copyProperties (const SGPropertyNode *in, SGPropertyNode *out);
1098 #endif // __PROPS_HXX