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>
16 #include <simgear/debug/logstream.hxx>
28 #if !defined(SG_HAVE_NATIVE_SGI_COMPILERS)
29 SG_USING_STD(istream);
30 SG_USING_STD(ostream);
34 #pragma warn A sloppy coder has defined NONE as a macro!
39 #pragma warn A sloppy coder has defined ALIAS as a macro!
44 #pragma warn A sloppy coder has defined UNSPECIFIED as a macro!
49 #pragma warn A sloppy coder has defined BOOL as a macro!
54 #pragma warn A sloppy coder has defined INT as a macro!
59 #pragma warn A sloppy coder has defined LONG as a macro!
64 #pragma warn A sloppy coder has defined FLOAT as a macro!
69 #pragma warn A sloppy coder has defined DOUBLE as a macro!
74 #pragma warn A sloppy coder has defined STRING as a macro!
80 ////////////////////////////////////////////////////////////////////////
83 // This is the mechanism that information-providing routines can
84 // use to link their own values to the property manager. Any
85 // SGValue can be tied to a raw value and then untied again.
87 // Note: we are forced to use inlined methods here to ensure
88 // that the templates will be instantiated. We're probably taking
89 // a small performance hit for that.
90 ////////////////////////////////////////////////////////////////////////
94 * Abstract base class for a raw value.
96 * <p>The property manager is implemented in two layers. The {@link
97 * SGPropertyNode} is the highest and most abstract layer,
98 * representing an LValue/RValue pair: it records the position of the
99 * property in the property tree and contains facilities for
100 * navigation to other nodes. It is guaranteed to be persistent: the
101 * {@link SGPropertyNode} will not change during a session, even if
102 * the property is bound and unbound multiple times.</p>
104 * <p>When the property value is not managed internally in the
105 * SGPropertyNode, the SGPropertyNode will contain a reference to an
106 * SGRawValue (this class), which provides an abstract way to get,
107 * set, and clone the underlying value. The SGRawValue may change
108 * frequently during a session as a value is retyped or bound and
109 * unbound to various data source, but the abstract SGPropertyNode
110 * layer insulates the application from those changes. The raw value
111 * contains no facilities for data binding or for type conversion: it
112 * is simply the abstraction of a primitive data type (or a compound
113 * data type, in the case of a string).</p>
115 * <p>The SGPropertyNode class always keeps a *copy* of a raw value,
116 * not the original one passed to it; if you override a derived class
117 * but do not replace the {@link #clone} method, strange things will
120 * <p>All derived SGRawValue classes must implement {@link #getValue},
121 * {@link #setValue}, and {@link #clone} for the appropriate type.</p>
123 * @see SGPropertyNode
124 * @see SGRawValuePointer
125 * @see SGRawValueFunctions
126 * @see SGRawValueFunctionsIndexed
127 * @see SGRawValueMethods
128 * @see SGRawValueMethodsIndexed
136 * The default underlying value for this type.
138 * Every raw value has a default; the default is false for a
139 * boolean, 0 for the various numeric values, and "" for a string.
140 * If additional types of raw values are added in the future, they
141 * may need different kinds of default values (such as epoch for a
142 * date type). The default value is used when creating new values.
144 static const T DefaultValue; // Default for this kind of raw value.
150 * Use the default value for this type.
158 virtual ~SGRawValue () {}
162 * Return the underlying value.
164 * @return The actual value for the property.
167 virtual T getValue () const = 0;
171 * Assign a new underlying value.
173 * If the new value cannot be set (because this is a read-only
174 * raw value, or because the new value is not acceptable for
175 * some reason) this method returns false and leaves the original
178 * @param value The actual value for the property.
179 * @return true if the value was set successfully, false otherwise.
182 virtual bool setValue (T value) = 0;
186 * Create a new deep copy of this raw value.
188 * The copy will contain its own version of the underlying value
191 * @return A deep copy of the current object.
193 virtual SGRawValue * clone () const = 0;
198 * A raw value bound to a pointer.
200 * This is the most efficient way to tie an external value, but also
201 * the most dangerous, because there is no way for the supplier to
202 * perform bounds checking and derived calculations except by polling
203 * the variable to see if it has changed. There is no default
204 * constructor, because this class would be meaningless without a
208 class SGRawValuePointer : public SGRawValue<T>
213 * Explicit pointer constructor.
215 * Create a new raw value bound to the value of the variable
216 * referenced by the pointer.
218 * @param ptr The pointer to the variable to which this raw value
221 SGRawValuePointer (T * ptr) : _ptr(ptr) {}
226 virtual ~SGRawValuePointer () {}
229 * Get the underlying value.
231 * This method will dereference the pointer and return the
234 virtual T getValue () const { return *_ptr; }
237 * Set the underlying value.
239 * This method will dereference the pointer and change the
242 virtual bool setValue (T value) { *_ptr = value; return true; }
245 * Create a copy of this raw value.
247 * The copy will use the same external pointer as the original.
249 virtual SGRawValue<T> * clone () const {
250 return new SGRawValuePointer<T>(_ptr);
259 * A value managed through static functions.
261 * A read-only value will not have a setter; a write-only value will
265 class SGRawValueFunctions : public SGRawValue<T>
270 * The template type of a static getter function.
272 typedef T (*getter_t)();
275 * The template type of a static setter function.
277 typedef void (*setter_t)(T);
280 * Explicit constructor.
282 * Create a new raw value bound to the getter and setter supplied.
284 * @param getter A static function for getting a value, or 0
285 * to read-disable the value.
286 * @param setter A static function for setting a value, or 0
287 * to write-disable the value.
289 SGRawValueFunctions (getter_t getter = 0, setter_t setter = 0)
290 : _getter(getter), _setter(setter) {}
295 virtual ~SGRawValueFunctions () {}
298 * Get the underlying value.
300 * This method will invoke the getter function to get a value.
301 * If no getter function was supplied, this method will always
302 * return the default value for the type.
304 virtual T getValue () const {
305 if (_getter) return (*_getter)();
306 else return SGRawValue<T>::DefaultValue;
310 * Set the underlying value.
312 * This method will invoke the setter function to change the
313 * underlying value. If no setter function was supplied, this
314 * method will return false.
316 virtual bool setValue (T value) {
317 if (_setter) { (*_setter)(value); return true; }
322 * Create a copy of this raw value, bound to the same functions.
324 virtual SGRawValue<T> * clone () const {
325 return new SGRawValueFunctions<T>(_getter,_setter);
335 * An indexed value bound to static functions.
337 * A read-only value will not have a setter; a write-only value will
338 * not have a getter. An indexed value is useful for binding one
339 * of a list of possible values (such as multiple engines for a
340 * plane). The index is hard-coded at creation time.
345 class SGRawValueFunctionsIndexed : public SGRawValue<T>
348 typedef T (*getter_t)(int);
349 typedef void (*setter_t)(int,T);
350 SGRawValueFunctionsIndexed (int index, getter_t getter = 0, setter_t setter = 0)
351 : _index(index), _getter(getter), _setter(setter) {}
352 virtual ~SGRawValueFunctionsIndexed () {}
353 virtual T getValue () const {
354 if (_getter) return (*_getter)(_index);
355 else return SGRawValue<T>::DefaultValue;
357 virtual bool setValue (T value) {
358 if (_setter) { (*_setter)(_index, value); return true; }
361 virtual SGRawValue<T> * clone () const {
362 return new SGRawValueFunctionsIndexed<T>(_index, _getter, _setter);
372 * A value managed through an object and access methods.
374 * A read-only value will not have a setter; a write-only value will
377 template <class C, class T>
378 class SGRawValueMethods : public SGRawValue<T>
381 typedef T (C::*getter_t)() const;
382 typedef void (C::*setter_t)(T);
383 SGRawValueMethods (C &obj, getter_t getter = 0, setter_t setter = 0)
384 : _obj(obj), _getter(getter), _setter(setter) {}
385 virtual ~SGRawValueMethods () {}
386 virtual T getValue () const {
387 if (_getter) { return (_obj.*_getter)(); }
388 else { return SGRawValue<T>::DefaultValue; }
390 virtual bool setValue (T value) {
391 if (_setter) { (_obj.*_setter)(value); return true; }
394 virtual SGRawValue<T> * clone () const {
395 return new SGRawValueMethods<C,T>(_obj, _getter, _setter);
405 * An indexed value managed through an object and access methods.
407 * A read-only value will not have a setter; a write-only value will
410 template <class C, class T>
411 class SGRawValueMethodsIndexed : public SGRawValue<T>
414 typedef T (C::*getter_t)(int) const;
415 typedef void (C::*setter_t)(int, T);
416 SGRawValueMethodsIndexed (C &obj, int index,
417 getter_t getter = 0, setter_t setter = 0)
418 : _obj(obj), _index(index), _getter(getter), _setter(setter) {}
419 virtual ~SGRawValueMethodsIndexed () {}
420 virtual T getValue () const {
421 if (_getter) { return (_obj.*_getter)(_index); }
422 else { return SGRawValue<T>::DefaultValue; }
424 virtual bool setValue (T value) {
425 if (_setter) { (_obj.*_setter)(_index, value); return true; }
428 virtual SGRawValue<T> * clone () const {
429 return new SGRawValueMethodsIndexed<C,T>(_obj, _index, _getter, _setter);
441 * A node in a property tree.
448 * Property value types.
464 * Access mode attributes.
466 * <p>The ARCHIVE attribute is strictly advisory, and controls
467 * whether the property should normally be saved and restored.</p>
479 * Default constructor.
487 SGPropertyNode (const SGPropertyNode &node);
493 virtual ~SGPropertyNode ();
502 * Test whether this node contains a primitive leaf value.
504 bool hasValue () const { return (_type != NONE); }
508 * Get the node's simple (XML) name.
510 const string &getName () const { return _name; }
514 * Get the node's integer index.
516 const int getIndex () const { return _index; }
520 * Get a non-const pointer to the node's parent.
522 SGPropertyNode * getParent () { return _parent; }
526 * Get a const pointer to the node's parent.
528 const SGPropertyNode * getParent () const { return _parent; }
537 * Get the number of child nodes.
539 const int nChildren () const { return _children.size(); }
543 * Get a child node by position (*NOT* index).
545 SGPropertyNode * getChild (int position);
549 * Get a const child node by position (*NOT* index).
551 const SGPropertyNode * getChild (int position) const;
555 * Get a child node by name and index.
557 SGPropertyNode * getChild (const string &name, int index = 0,
558 bool create = false);
562 * Get a const child node by name and index.
564 const SGPropertyNode * getChild (const string &name, int index = 0) const;
568 * Get a vector of all children with the specified name.
570 vector<SGPropertyNode *> getChildren (const string &name);
574 * Get a vector all all children (const) with the specified name.
576 vector<const SGPropertyNode *> getChildren (const string &name) const;
585 * Alias this node's leaf value to another's.
587 bool alias (SGPropertyNode * target);
591 * Alias this node's leaf value to another's by relative path.
593 bool alias (const string &path);
597 * Remove any alias for this node.
603 * Test whether the node's leaf value is aliased to another's.
605 bool isAlias () const { return (_type == ALIAS); }
609 * Get a non-const pointer to the current alias target, if any.
611 SGPropertyNode * getAliasTarget ();
615 * Get a const pointer to the current alias target, if any.
617 const SGPropertyNode * getAliasTarget () const;
626 * Get the path to this node from the root.
628 string getPath (bool simplify = false) const;
632 * Get a pointer to the root node.
634 SGPropertyNode * getRootNode ();
638 * Get a const pointer to the root node.
640 const SGPropertyNode * getRootNode () const;
644 * Get a pointer to another node by relative path.
646 SGPropertyNode * getNode (const string &relative_path, bool create = false);
650 * Get a pointer to another node by relative path.
652 * This method leaves the index off the last member of the path,
653 * so that the user can specify it separately (and save some
654 * string building). For example, getNode("/bar[1]/foo", 3) is
655 * exactly equivalent to getNode("bar[1]/foo[3]"). The index
656 * provided overrides any given in the path itself for the last
659 SGPropertyNode * getNode (const string &relative_path, int index,
660 bool create = false);
664 * Get a const pointer to another node by relative path.
666 const SGPropertyNode * getNode (const string &relative_path) const;
670 * Get a const pointer to another node by relative path.
672 * This method leaves the index off the last member of the path,
673 * so that the user can specify it separate.
675 const SGPropertyNode * getNode (const string &relative_path,
684 * Check a single mode attribute for the property node.
686 bool getAttribute (Attribute attr) const { return ((_attr & attr) != 0); }
690 * Set a single mode attribute for the property node.
692 void setAttribute (Attribute attr, bool state) {
693 (state ? _attr |= attr : _attr &= ~attr);
698 * Get all of the mode attributes for the property node.
700 int getAttributes () const { return _attr; }
704 * Set all of the mode attributes for the property node.
706 void setAttributes (int attr) { _attr = attr; }
710 // Leaf Value (primitive).
715 * Get the type of leaf value, if any, for this node.
717 Type getType () const;
721 * Get a bool value for this node.
723 bool getBoolValue () const;
727 * Get an int value for this node.
729 int getIntValue () const;
733 * Get a long int value for this node.
735 long getLongValue () const;
739 * Get a float value for this node.
741 float getFloatValue () const;
745 * Get a double value for this node.
747 double getDoubleValue () const;
751 * Get a string value for this node.
753 string getStringValue () const;
758 * Set a bool value for this node.
760 bool setBoolValue (bool value);
764 * Set an int value for this node.
766 bool setIntValue (int value);
770 * Set a long int value for this node.
772 bool setLongValue (long value);
776 * Set a float value for this node.
778 bool setFloatValue (float value);
782 * Set a double value for this node.
784 bool setDoubleValue (double value);
788 * Set a string value for this node.
790 bool setStringValue (string value);
794 * Set a value of unspecified type for this node.
796 bool setUnspecifiedValue (string value);
805 * Test whether this node is bound to an external data source.
807 bool isTied () const { return _tied; }
811 * Bind this node to an external bool source.
813 bool tie (const SGRawValue<bool> &rawValue, bool useDefault = true);
817 * Bind this node to an external int source.
819 bool tie (const SGRawValue<int> &rawValue, bool useDefault = true);
823 * Bind this node to an external long int source.
825 bool tie (const SGRawValue<long> &rawValue, bool useDefault = true);
829 * Bind this node to an external float source.
831 bool tie (const SGRawValue<float> &rawValue, bool useDefault = true);
835 * Bind this node to an external double source.
837 bool tie (const SGRawValue<double> &rawValue, bool useDefault = true);
841 * Bind this node to an external string source.
843 bool tie (const SGRawValue<string> &rawValue, bool useDefault = true);
847 * Unbind this node from any external data source.
853 // Convenience methods using paths.
854 // TODO: add attribute methods
859 * Get another node's type.
861 Type getType (const string &relative_path) const;
865 * Test whether another node has a leaf value.
867 bool hasValue (const string &relative_path) const;
871 * Get another node's value as a bool.
873 bool getBoolValue (const string &relative_path,
874 bool defaultValue = false) const;
878 * Get another node's value as an int.
880 int getIntValue (const string &relative_path,
881 int defaultValue = 0) const;
885 * Get another node's value as a long int.
887 long getLongValue (const string &relative_path,
888 long defaultValue = 0L) const;
892 * Get another node's value as a float.
894 float getFloatValue (const string &relative_path,
895 float defaultValue = 0.0) const;
899 * Get another node's value as a double.
901 double getDoubleValue (const string &relative_path,
902 double defaultValue = 0.0L) const;
906 * Get another node's value as a string.
908 string getStringValue (const string &relative_path,
909 string defaultValue = "") const;
913 * Set another node's value as a bool.
915 bool setBoolValue (const string &relative_path, bool value);
919 * Set another node's value as an int.
921 bool setIntValue (const string &relative_path, int value);
925 * Set another node's value as a long int.
927 bool setLongValue (const string &relative_path, long value);
931 * Set another node's value as a float.
933 bool setFloatValue (const string &relative_path, float value);
937 * Set another node's value as a double.
939 bool setDoubleValue (const string &relative_path, double value);
943 * Set another node's value as a string.
945 bool setStringValue (const string &relative_path, string value);
949 * Set another node's value with no specified type.
951 bool setUnspecifiedValue (const string &relative_path, string value);
955 * Test whether another node is bound to an external data source.
957 bool isTied (const string &relative_path) const;
961 * Bind another node to an external bool source.
963 bool tie (const string &relative_path, const SGRawValue<bool> &rawValue,
964 bool useDefault = true);
968 * Bind another node to an external int source.
970 bool tie (const string &relative_path, const SGRawValue<int> &rawValue,
971 bool useDefault = true);
975 * Bind another node to an external long int source.
977 bool tie (const string &relative_path, const SGRawValue<long> &rawValue,
978 bool useDefault = true);
982 * Bind another node to an external float source.
984 bool tie (const string &relative_path, const SGRawValue<float> &rawValue,
985 bool useDefault = true);
989 * Bind another node to an external double source.
991 bool tie (const string &relative_path, const SGRawValue<double> &rawValue,
992 bool useDefault = true);
996 * Bind another node to an external string source.
998 bool tie (const string &relative_path, const SGRawValue<string> &rawValue,
999 bool useDefault = true);
1003 * Unbind another node from any external data source.
1005 bool untie (const string &relative_path);
1012 * Protected constructor for making new nodes on demand.
1014 SGPropertyNode (const string &name, int index, SGPropertyNode * parent);
1019 // Get the raw value
1020 bool get_bool () const;
1021 int get_int () const;
1022 long get_long () const;
1023 float get_float () const;
1024 double get_double () const;
1025 const string get_string () const;
1027 // Set the raw value
1028 bool set_bool (bool value);
1029 bool set_int (int value);
1030 bool set_long (long value);
1031 bool set_float (float value);
1032 bool set_double (double value);
1033 bool set_string (const string &value);
1037 * Clear any existing value and set the type to NONE.
1039 void clear_value ();
1043 * Get the value as a string.
1045 string make_string () const;
1049 * Trace a read access.
1051 void trace_read () const;
1055 * Trace a write access.
1057 void trace_write () const;
1061 SGPropertyNode * _parent;
1062 vector<SGPropertyNode *> _children;
1063 typedef map<const string,SGPropertyNode *> cache_map;
1064 cache_map * _path_cache;
1069 // The right kind of pointer...
1071 SGPropertyNode * alias;
1072 SGRawValue<bool> * bool_val;
1073 SGRawValue<int> * int_val;
1074 SGRawValue<long> * long_val;
1075 SGRawValue<float> * float_val;
1076 SGRawValue<double> * double_val;
1077 SGRawValue<string> * string_val;
1086 string * string_val;
1092 #endif // __PROPS_HXX