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 #ifndef PROPS_STANDALONE
16 #define PROPS_STANDALONE 0
35 #include <simgear/compiler.h>
36 #include <simgear/debug/logstream.hxx>
42 #if !defined(SG_HAVE_NATIVE_SGI_COMPILERS)
43 SG_USING_STD(istream);
44 SG_USING_STD(ostream);
51 #pragma warn A sloppy coder has defined NONE as a macro!
56 #pragma warn A sloppy coder has defined ALIAS as a macro!
61 #pragma warn A sloppy coder has defined UNSPECIFIED as a macro!
66 #pragma warn A sloppy coder has defined BOOL as a macro!
71 #pragma warn A sloppy coder has defined INT as a macro!
76 #pragma warn A sloppy coder has defined LONG as a macro!
81 #pragma warn A sloppy coder has defined FLOAT as a macro!
86 #pragma warn A sloppy coder has defined DOUBLE as a macro!
91 #pragma warn A sloppy coder has defined STRING as a macro!
97 ////////////////////////////////////////////////////////////////////////
100 // This is the mechanism that information-providing routines can
101 // use to link their own values to the property manager. Any
102 // SGValue can be tied to a raw value and then untied again.
104 // Note: we are forced to use inlined methods here to ensure
105 // that the templates will be instantiated. We're probably taking
106 // a small performance hit for that.
107 ////////////////////////////////////////////////////////////////////////
111 * Abstract base class for a raw value.
113 * <p>The property manager is implemented in two layers. The {@link
114 * SGPropertyNode} is the highest and most abstract layer,
115 * representing an LValue/RValue pair: it records the position of the
116 * property in the property tree and contains facilities for
117 * navigation to other nodes. It is guaranteed to be persistent: the
118 * {@link SGPropertyNode} will not change during a session, even if
119 * the property is bound and unbound multiple times.</p>
121 * <p>When the property value is not managed internally in the
122 * SGPropertyNode, the SGPropertyNode will contain a reference to an
123 * SGRawValue (this class), which provides an abstract way to get,
124 * set, and clone the underlying value. The SGRawValue may change
125 * frequently during a session as a value is retyped or bound and
126 * unbound to various data source, but the abstract SGPropertyNode
127 * layer insulates the application from those changes. The raw value
128 * contains no facilities for data binding or for type conversion: it
129 * is simply the abstraction of a primitive data type (or a compound
130 * data type, in the case of a string).</p>
132 * <p>The SGPropertyNode class always keeps a *copy* of a raw value,
133 * not the original one passed to it; if you override a derived class
134 * but do not replace the {@link #clone} method, strange things will
137 * <p>All derived SGRawValue classes must implement {@link #getValue},
138 * {@link #setValue}, and {@link #clone} for the appropriate type.</p>
140 * @see SGPropertyNode
141 * @see SGRawValuePointer
142 * @see SGRawValueFunctions
143 * @see SGRawValueFunctionsIndexed
144 * @see SGRawValueMethods
145 * @see SGRawValueMethodsIndexed
153 * The default underlying value for this type.
155 * Every raw value has a default; the default is false for a
156 * boolean, 0 for the various numeric values, and "" for a string.
157 * If additional types of raw values are added in the future, they
158 * may need different kinds of default values (such as epoch for a
159 * date type). The default value is used when creating new values.
161 static const T DefaultValue; // Default for this kind of raw value.
167 * Use the default value for this type.
175 virtual ~SGRawValue () {}
179 * Return the underlying value.
181 * @return The actual value for the property.
184 virtual T getValue () const = 0;
188 * Assign a new underlying value.
190 * If the new value cannot be set (because this is a read-only
191 * raw value, or because the new value is not acceptable for
192 * some reason) this method returns false and leaves the original
195 * @param value The actual value for the property.
196 * @return true if the value was set successfully, false otherwise.
199 virtual bool setValue (T value) = 0;
203 * Create a new deep copy of this raw value.
205 * The copy will contain its own version of the underlying value
208 * @return A deep copy of the current object.
210 virtual SGRawValue * clone () const = 0;
215 * A raw value bound to a pointer.
217 * This is the most efficient way to tie an external value, but also
218 * the most dangerous, because there is no way for the supplier to
219 * perform bounds checking and derived calculations except by polling
220 * the variable to see if it has changed. There is no default
221 * constructor, because this class would be meaningless without a
225 class SGRawValuePointer : public SGRawValue<T>
230 * Explicit pointer constructor.
232 * Create a new raw value bound to the value of the variable
233 * referenced by the pointer.
235 * @param ptr The pointer to the variable to which this raw value
238 SGRawValuePointer (T * ptr) : _ptr(ptr) {}
243 virtual ~SGRawValuePointer () {}
246 * Get the underlying value.
248 * This method will dereference the pointer and return the
251 virtual T getValue () const { return *_ptr; }
254 * Set the underlying value.
256 * This method will dereference the pointer and change the
259 virtual bool setValue (T value) { *_ptr = value; return true; }
262 * Create a copy of this raw value.
264 * The copy will use the same external pointer as the original.
266 virtual SGRawValue<T> * clone () const {
267 return new SGRawValuePointer<T>(_ptr);
276 * A value managed through static functions.
278 * A read-only value will not have a setter; a write-only value will
282 class SGRawValueFunctions : public SGRawValue<T>
287 * The template type of a static getter function.
289 typedef T (*getter_t)();
292 * The template type of a static setter function.
294 typedef void (*setter_t)(T);
297 * Explicit constructor.
299 * Create a new raw value bound to the getter and setter supplied.
301 * @param getter A static function for getting a value, or 0
302 * to read-disable the value.
303 * @param setter A static function for setting a value, or 0
304 * to write-disable the value.
306 SGRawValueFunctions (getter_t getter = 0, setter_t setter = 0)
307 : _getter(getter), _setter(setter) {}
312 virtual ~SGRawValueFunctions () {}
315 * Get the underlying value.
317 * This method will invoke the getter function to get a value.
318 * If no getter function was supplied, this method will always
319 * return the default value for the type.
321 virtual T getValue () const {
322 if (_getter) return (*_getter)();
323 else return SGRawValue<T>::DefaultValue;
327 * Set the underlying value.
329 * This method will invoke the setter function to change the
330 * underlying value. If no setter function was supplied, this
331 * method will return false.
333 virtual bool setValue (T value) {
334 if (_setter) { (*_setter)(value); return true; }
339 * Create a copy of this raw value, bound to the same functions.
341 virtual SGRawValue<T> * clone () const {
342 return new SGRawValueFunctions<T>(_getter,_setter);
352 * An indexed value bound to static functions.
354 * A read-only value will not have a setter; a write-only value will
355 * not have a getter. An indexed value is useful for binding one
356 * of a list of possible values (such as multiple engines for a
357 * plane). The index is hard-coded at creation time.
362 class SGRawValueFunctionsIndexed : public SGRawValue<T>
365 typedef T (*getter_t)(int);
366 typedef void (*setter_t)(int,T);
367 SGRawValueFunctionsIndexed (int index, getter_t getter = 0, setter_t setter = 0)
368 : _index(index), _getter(getter), _setter(setter) {}
369 virtual ~SGRawValueFunctionsIndexed () {}
370 virtual T getValue () const {
371 if (_getter) return (*_getter)(_index);
372 else return SGRawValue<T>::DefaultValue;
374 virtual bool setValue (T value) {
375 if (_setter) { (*_setter)(_index, value); return true; }
378 virtual SGRawValue<T> * clone () const {
379 return new SGRawValueFunctionsIndexed<T>(_index, _getter, _setter);
389 * A value managed through an object and access methods.
391 * A read-only value will not have a setter; a write-only value will
394 template <class C, class T>
395 class SGRawValueMethods : public SGRawValue<T>
398 typedef T (C::*getter_t)() const;
399 typedef void (C::*setter_t)(T);
400 SGRawValueMethods (C &obj, getter_t getter = 0, setter_t setter = 0)
401 : _obj(obj), _getter(getter), _setter(setter) {}
402 virtual ~SGRawValueMethods () {}
403 virtual T getValue () const {
404 if (_getter) { return (_obj.*_getter)(); }
405 else { return SGRawValue<T>::DefaultValue; }
407 virtual bool setValue (T value) {
408 if (_setter) { (_obj.*_setter)(value); return true; }
411 virtual SGRawValue<T> * clone () const {
412 return new SGRawValueMethods<C,T>(_obj, _getter, _setter);
422 * An indexed value managed through an object and access methods.
424 * A read-only value will not have a setter; a write-only value will
427 template <class C, class T>
428 class SGRawValueMethodsIndexed : public SGRawValue<T>
431 typedef T (C::*getter_t)(int) const;
432 typedef void (C::*setter_t)(int, T);
433 SGRawValueMethodsIndexed (C &obj, int index,
434 getter_t getter = 0, setter_t setter = 0)
435 : _obj(obj), _index(index), _getter(getter), _setter(setter) {}
436 virtual ~SGRawValueMethodsIndexed () {}
437 virtual T getValue () const {
438 if (_getter) { return (_obj.*_getter)(_index); }
439 else { return SGRawValue<T>::DefaultValue; }
441 virtual bool setValue (T value) {
442 if (_setter) { (_obj.*_setter)(_index, value); return true; }
445 virtual SGRawValue<T> * clone () const {
446 return new SGRawValueMethodsIndexed<C,T>(_obj, _index, _getter, _setter);
458 * A node in a property tree.
468 MAX_STRING_LEN = 1024
472 * Property value types.
488 * Access mode attributes.
490 * <p>The ARCHIVE attribute is strictly advisory, and controls
491 * whether the property should normally be saved and restored.</p>
503 * Default constructor.
511 SGPropertyNode (const SGPropertyNode &node);
517 virtual ~SGPropertyNode ();
526 * Test whether this node contains a primitive leaf value.
528 bool hasValue () const { return (_type != NONE); }
532 * Get the node's simple (XML) name.
534 const char * getName () const { return _name; }
538 * Get the node's integer index.
540 const int getIndex () const { return _index; }
544 * Get a non-const pointer to the node's parent.
546 SGPropertyNode * getParent () { return _parent; }
550 * Get a const pointer to the node's parent.
552 const SGPropertyNode * getParent () const { return _parent; }
561 * Get the number of child nodes.
563 const int nChildren () const { return _children.size(); }
567 * Get a child node by position (*NOT* index).
569 SGPropertyNode * getChild (int position);
573 * Get a const child node by position (*NOT* index).
575 const SGPropertyNode * getChild (int position) const;
579 * Get a child node by name and index.
581 SGPropertyNode * getChild (const char * name, int index = 0,
582 bool create = false);
586 * Get a const child node by name and index.
588 const SGPropertyNode * getChild (const char * name, int index = 0) const;
592 * Get a vector of all children with the specified name.
594 vector<SGPropertyNode *> getChildren (const char * name);
598 * Get a vector all all children (const) with the specified name.
600 vector<const SGPropertyNode *> getChildren (const char * name) const;
609 * Alias this node's leaf value to another's.
611 bool alias (SGPropertyNode * target);
615 * Alias this node's leaf value to another's by relative path.
617 bool alias (const char * path);
621 * Remove any alias for this node.
627 * Test whether the node's leaf value is aliased to another's.
629 bool isAlias () const { return (_type == ALIAS); }
633 * Get a non-const pointer to the current alias target, if any.
635 SGPropertyNode * getAliasTarget ();
639 * Get a const pointer to the current alias target, if any.
641 const SGPropertyNode * getAliasTarget () const;
650 * Get the path to this node from the root.
652 const char * getPath (bool simplify = false) const;
656 * Get a pointer to the root node.
658 SGPropertyNode * getRootNode ();
662 * Get a const pointer to the root node.
664 const SGPropertyNode * getRootNode () const;
668 * Get a pointer to another node by relative path.
670 SGPropertyNode * getNode (const char * relative_path, bool create = false);
674 * Get a pointer to another node by relative path.
676 * This method leaves the index off the last member of the path,
677 * so that the user can specify it separately (and save some
678 * string building). For example, getNode("/bar[1]/foo", 3) is
679 * exactly equivalent to getNode("bar[1]/foo[3]"). The index
680 * provided overrides any given in the path itself for the last
683 SGPropertyNode * getNode (const char * relative_path, int index,
684 bool create = false);
688 * Get a const pointer to another node by relative path.
690 const SGPropertyNode * getNode (const char * relative_path) const;
694 * Get a const pointer to another node by relative path.
696 * This method leaves the index off the last member of the path,
697 * so that the user can specify it separate.
699 const SGPropertyNode * getNode (const char * relative_path,
708 * Check a single mode attribute for the property node.
710 bool getAttribute (Attribute attr) const { return ((_attr & attr) != 0); }
714 * Set a single mode attribute for the property node.
716 void setAttribute (Attribute attr, bool state) {
717 (state ? _attr |= attr : _attr &= ~attr);
722 * Get all of the mode attributes for the property node.
724 int getAttributes () const { return _attr; }
728 * Set all of the mode attributes for the property node.
730 void setAttributes (int attr) { _attr = attr; }
734 // Leaf Value (primitive).
739 * Get the type of leaf value, if any, for this node.
741 Type getType () const;
745 * Get a bool value for this node.
747 bool getBoolValue () const;
751 * Get an int value for this node.
753 int getIntValue () const;
757 * Get a long int value for this node.
759 long getLongValue () const;
763 * Get a float value for this node.
765 float getFloatValue () const;
769 * Get a double value for this node.
771 double getDoubleValue () const;
775 * Get a string value for this node.
777 const char * getStringValue () const;
782 * Set a bool value for this node.
784 bool setBoolValue (bool value);
788 * Set an int value for this node.
790 bool setIntValue (int value);
794 * Set a long int value for this node.
796 bool setLongValue (long value);
800 * Set a float value for this node.
802 bool setFloatValue (float value);
806 * Set a double value for this node.
808 bool setDoubleValue (double value);
812 * Set a string value for this node.
814 bool setStringValue (const char * value);
818 * Set a value of unspecified type for this node.
820 bool setUnspecifiedValue (const char * value);
829 * Test whether this node is bound to an external data source.
831 bool isTied () const { return _tied; }
835 * Bind this node to an external bool source.
837 bool tie (const SGRawValue<bool> &rawValue, bool useDefault = true);
841 * Bind this node to an external int source.
843 bool tie (const SGRawValue<int> &rawValue, bool useDefault = true);
847 * Bind this node to an external long int source.
849 bool tie (const SGRawValue<long> &rawValue, bool useDefault = true);
853 * Bind this node to an external float source.
855 bool tie (const SGRawValue<float> &rawValue, bool useDefault = true);
859 * Bind this node to an external double source.
861 bool tie (const SGRawValue<double> &rawValue, bool useDefault = true);
865 * Bind this node to an external string source.
867 bool tie (const SGRawValue<const char *> &rawValue, bool useDefault = true);
871 * Unbind this node from any external data source.
877 // Convenience methods using paths.
878 // TODO: add attribute methods
883 * Get another node's type.
885 Type getType (const char * relative_path) const;
889 * Test whether another node has a leaf value.
891 bool hasValue (const char * relative_path) const;
895 * Get another node's value as a bool.
897 bool getBoolValue (const char * relative_path,
898 bool defaultValue = false) const;
902 * Get another node's value as an int.
904 int getIntValue (const char * relative_path,
905 int defaultValue = 0) const;
909 * Get another node's value as a long int.
911 long getLongValue (const char * relative_path,
912 long defaultValue = 0L) const;
916 * Get another node's value as a float.
918 float getFloatValue (const char * relative_path,
919 float defaultValue = 0.0) const;
923 * Get another node's value as a double.
925 double getDoubleValue (const char * relative_path,
926 double defaultValue = 0.0L) const;
930 * Get another node's value as a string.
932 const char * getStringValue (const char * relative_path,
933 const char * defaultValue = "") const;
937 * Set another node's value as a bool.
939 bool setBoolValue (const char * relative_path, bool value);
943 * Set another node's value as an int.
945 bool setIntValue (const char * relative_path, int value);
949 * Set another node's value as a long int.
951 bool setLongValue (const char * relative_path, long value);
955 * Set another node's value as a float.
957 bool setFloatValue (const char * relative_path, float value);
961 * Set another node's value as a double.
963 bool setDoubleValue (const char * relative_path, double value);
967 * Set another node's value as a string.
969 bool setStringValue (const char * relative_path, const char * value);
973 * Set another node's value with no specified type.
975 bool setUnspecifiedValue (const char * relative_path, const char * value);
979 * Test whether another node is bound to an external data source.
981 bool isTied (const char * relative_path) const;
985 * Bind another node to an external bool source.
987 bool tie (const char * relative_path, const SGRawValue<bool> &rawValue,
988 bool useDefault = true);
992 * Bind another node to an external int source.
994 bool tie (const char * relative_path, const SGRawValue<int> &rawValue,
995 bool useDefault = true);
999 * Bind another node to an external long int source.
1001 bool tie (const char * relative_path, const SGRawValue<long> &rawValue,
1002 bool useDefault = true);
1006 * Bind another node to an external float source.
1008 bool tie (const char * relative_path, const SGRawValue<float> &rawValue,
1009 bool useDefault = true);
1013 * Bind another node to an external double source.
1015 bool tie (const char * relative_path, const SGRawValue<double> &rawValue,
1016 bool useDefault = true);
1020 * Bind another node to an external string source.
1022 bool tie (const char * relative_path, const SGRawValue<const char *> &rawValue,
1023 bool useDefault = true);
1027 * Unbind another node from any external data source.
1029 bool untie (const char * relative_path);
1036 * Protected constructor for making new nodes on demand.
1038 SGPropertyNode (const char * name, int index, SGPropertyNode * parent);
1043 // Get the raw value
1044 bool get_bool () const;
1045 int get_int () const;
1046 long get_long () const;
1047 float get_float () const;
1048 double get_double () const;
1049 const char * get_string () const;
1051 // Set the raw value
1052 bool set_bool (bool value);
1053 bool set_int (int value);
1054 bool set_long (long value);
1055 bool set_float (float value);
1056 bool set_double (double value);
1057 bool set_string (const char * value);
1061 * Clear any existing value and set the type to NONE.
1063 void clear_value ();
1067 * Get the value as a string.
1069 const char * make_string () const;
1073 * Trace a read access.
1075 void trace_read () const;
1079 * Trace a write access.
1081 void trace_write () const;
1083 mutable char _buffer[MAX_STRING_LEN+1];
1087 SGPropertyNode * _parent;
1088 vector<SGPropertyNode *> _children;
1089 typedef map<const string,SGPropertyNode *> cache_map;
1090 cache_map * _path_cache;
1095 // The right kind of pointer...
1097 SGPropertyNode * alias;
1098 SGRawValue<bool> * bool_val;
1099 SGRawValue<int> * int_val;
1100 SGRawValue<long> * long_val;
1101 SGRawValue<float> * float_val;
1102 SGRawValue<double> * double_val;
1103 SGRawValue<const char *> * string_val;
1112 const char * string_val;
1118 #endif // __PROPS_HXX