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>
27 #if !defined(SG_HAVE_NATIVE_SGI_COMPILERS)
28 SG_USING_STD(istream);
29 SG_USING_STD(ostream);
33 #pragma warn A sloppy coder has defined NONE as a macro!
38 #pragma warn A sloppy coder has defined ALIAS as a macro!
43 #pragma warn A sloppy coder has defined UNSPECIFIED as a macro!
48 #pragma warn A sloppy coder has defined BOOL as a macro!
53 #pragma warn A sloppy coder has defined INT as a macro!
58 #pragma warn A sloppy coder has defined LONG as a macro!
63 #pragma warn A sloppy coder has defined FLOAT as a macro!
68 #pragma warn A sloppy coder has defined DOUBLE as a macro!
73 #pragma warn A sloppy coder has defined STRING as a macro!
79 ////////////////////////////////////////////////////////////////////////
82 // This is the mechanism that information-providing routines can
83 // use to link their own values to the property manager. Any
84 // SGValue can be tied to a raw value and then untied again.
85 ////////////////////////////////////////////////////////////////////////
89 * Abstract base class for a raw value.
91 * The property manager is implemented in three layers. The {@link
92 * SGPropertyNode} is the highest and most abstract layer,
93 * representing * an LValue/RValue pair: it * records the position
94 * of the property in the property tree and * contains facilities
95 * for navigation to other nodes. Each node * may contain an {@link
96 * SGValue}, which is guaranteed persistent: the * {@link SGValue}
97 * will not change during a session, even if the * property is bound
98 * and unbound multiple times. The SGValue is the * abstraction of
99 * an RValue: it allows for conversion among all of the different
100 * types, and can be bound to external pointers, functions, methods,
101 * or other data sources. Every SGValue contains an SGRawValue of
102 * a specific type. The SGRawValue (this class) may change frequently
103 * during a session as a value is retyped or bound and unbound to
104 * various data source, but the abstract SGValue layer insulates
105 * the application from those changes. The raw value contains no
106 * facilities for data binding or for type conversion: it is simply
107 * the abstraction of a primitive data type (or a compound data
108 * type, in the case of a string).
110 * The SGValue class always keeps a *copy* of a raw value, not the
111 * original one passed to it; if you override a derived class but do
112 * not replace the {@link #clone} method, strange things will happen.
114 * All raw values must implement {@link #getValue}, {@link #setValue},
115 * and {@link #clone} for the appropriate type.
118 * @see SGPropertyNode */
125 * The default underlying value for this type.
127 * Every raw value has a default; the default is false for a
128 * boolean, 0 for the various numeric values, and "" for a string.
129 * If additional types of raw values are added in the future, they
130 * may need different kinds of default values (such as epoch for a
131 * date type). The default value is used when creating new values.
133 static const T DefaultValue; // Default for this kind of raw value.
139 * Use the default value for this type.
147 virtual ~SGRawValue () {}
151 * Return the underlying value.
153 * @return The actual value for the property.
156 virtual T getValue () const = 0;
160 * Assign a new underlying value.
162 * If the new value cannot be set (because this is a read-only
163 * raw value, or because the new value is not acceptable for
164 * some reason) this method returns false and leaves the original
167 * @param value The actual value for the property.
168 * @return true if the value was set successfully, false otherwise.
171 virtual bool setValue (T value) = 0;
175 * Create a new deep copy of this raw value.
177 * The copy will contain its own version of the underlying value
180 * @return A deep copy of the current object.
182 virtual SGRawValue * clone () const = 0;
187 * An unbound raw value, stored internally.
189 * Instances of this class are created automatically, by default,
190 * by the SGValue class; ordinarily the application should not
194 class SGRawValueInternal : public SGRawValue<T>
199 * Default constructor.
201 * Initialize with the default value for this type.
203 SGRawValueInternal () {}
206 * Explicit value constructor.
208 * Initialize with the underlying value provided.
210 * @param value The initial value for this property.
212 SGRawValueInternal (T value) : _value(value) {}
217 virtual ~SGRawValueInternal () {}
220 * Get the underlying value.
222 virtual T getValue () const { return _value; }
225 * Set the underlying value.
227 virtual bool setValue (T value) { _value = value; return true; }
230 * Create a deep copy of this raw value.
232 virtual SGRawValue<T> * clone () const {
233 return new SGRawValueInternal<T>(_value);
242 * A raw value bound to a pointer.
244 * This is the most efficient way to tie an external value, but also
245 * the most dangerous, because there is no way for the supplier to
246 * perform bounds checking and derived calculations except by polling
247 * the variable to see if it has changed. There is no default
248 * constructor, because this class would be meaningless without a
252 class SGRawValuePointer : public SGRawValue<T>
257 * Explicit pointer constructor.
259 * Create a new raw value bound to the value of the variable
260 * referenced by the pointer.
262 * @param ptr The pointer to the variable to which this raw value
265 SGRawValuePointer (T * ptr) : _ptr(ptr) {}
270 virtual ~SGRawValuePointer () {}
273 * Get the underlying value.
275 * This method will dereference the pointer and return the
278 virtual T getValue () const { return *_ptr; }
281 * Set the underlying value.
283 * This method will dereference the pointer and change the
286 virtual bool setValue (T value) { *_ptr = value; return true; }
289 * Create a copy of this raw value.
291 * The copy will use the same external pointer as the original.
293 virtual SGRawValue<T> * clone () const {
294 return new SGRawValuePointer<T>(_ptr);
303 * A value managed through static functions.
305 * A read-only value will not have a setter; a write-only value will
309 class SGRawValueFunctions : public SGRawValue<T>
314 * The template type of a static getter function.
316 typedef T (*getter_t)();
319 * The template type of a static setter function.
321 typedef void (*setter_t)(T);
324 * Explicit constructor.
326 * Create a new raw value bound to the getter and setter supplied.
328 * @param getter A static function for getting a value, or 0
329 * to read-disable the value.
330 * @param setter A static function for setting a value, or 0
331 * to write-disable the value.
333 SGRawValueFunctions (getter_t getter = 0, setter_t setter = 0)
334 : _getter(getter), _setter(setter) {}
339 virtual ~SGRawValueFunctions () {}
342 * Get the underlying value.
344 * This method will invoke the getter function to get a value.
345 * If no getter function was supplied, this method will always
346 * return the default value for the type.
348 virtual T getValue () const {
349 if (_getter) return (*_getter)();
350 else return SGRawValue<T>::DefaultValue;
354 * Set the underlying value.
356 * This method will invoke the setter function to change the
357 * underlying value. If no setter function was supplied, this
358 * method will return false.
360 virtual bool setValue (T value) {
361 if (_setter) { (*_setter)(value); return true; }
366 * Create a copy of this raw value, bound to the same functions.
368 virtual SGRawValue<T> * clone () const {
369 return new SGRawValueFunctions<T>(_getter,_setter);
379 * An indexed value bound to static functions.
381 * A read-only value will not have a setter; a write-only value will
382 * not have a getter. An indexed value is useful for binding one
383 * of a list of possible values (such as multiple engines for a
384 * plane). The index is hard-coded at creation time.
387 class SGRawValueFunctionsIndexed : public SGRawValue<T>
390 typedef T (*getter_t)(int);
391 typedef void (*setter_t)(int,T);
392 SGRawValueFunctionsIndexed (int index, getter_t getter = 0, setter_t setter = 0)
393 : _index(index), _getter(getter), _setter(setter) {}
394 virtual ~SGRawValueFunctionsIndexed () {}
395 virtual T getValue () const {
396 if (_getter) return (*_getter)(_index);
397 else return SGRawValue<T>::DefaultValue;
399 virtual bool setValue (T value) {
400 if (_setter) { (*_setter)(_index, value); return true; }
403 virtual SGRawValue<T> * clone () const {
404 return new SGRawValueFunctionsIndexed<T>(_index, _getter, _setter);
414 * A value managed through an object and access methods.
416 * A read-only value will not have a setter; a write-only value will
419 template <class C, class T>
420 class SGRawValueMethods : public SGRawValue<T>
423 typedef T (C::*getter_t)() const;
424 typedef void (C::*setter_t)(T);
425 SGRawValueMethods (C &obj, getter_t getter = 0, setter_t setter = 0)
426 : _obj(obj), _getter(getter), _setter(setter) {}
427 virtual ~SGRawValueMethods () {}
428 virtual T getValue () const {
429 if (_getter) { return (_obj.*_getter)(); }
430 else { return SGRawValue<T>::DefaultValue; }
432 virtual bool setValue (T value) {
433 if (_setter) { (_obj.*_setter)(value); return true; }
436 virtual SGRawValue<T> * clone () const {
437 return new SGRawValueMethods<C,T>(_obj, _getter, _setter);
447 * An indexed value managed through an object and access methods.
449 * A read-only value will not have a setter; a write-only value will
452 template <class C, class T>
453 class SGRawValueMethodsIndexed : public SGRawValue<T>
456 typedef T (C::*getter_t)(int) const;
457 typedef void (C::*setter_t)(int, T);
458 SGRawValueMethodsIndexed (C &obj, int index,
459 getter_t getter = 0, setter_t setter = 0)
460 : _obj(obj), _index(index), _getter(getter), _setter(setter) {}
461 virtual ~SGRawValueMethodsIndexed () {}
462 virtual T getValue () const {
463 if (_getter) { return (_obj.*_getter)(_index); }
464 else { return SGRawValue<T>::DefaultValue; }
466 virtual bool setValue (T value) {
467 if (_setter) { (_obj.*_setter)(_index, value); return true; }
470 virtual SGRawValue<T> * clone () const {
471 return new SGRawValueMethodsIndexed<C,T>(_obj, _index, _getter, _setter);
483 * A node in a property tree.
492 * Property value types.
508 * Access mode attributes.
510 * <p>The ARCHIVE attribute is strictly advisory, and controls
511 * whether the property should normally be saved and restored.</p>
523 * Default constructor.
531 SGPropertyNode (const SGPropertyNode &node);
537 virtual ~SGPropertyNode ();
546 * Test whether this node contains a primitive leaf value.
548 bool hasValue () const { return (_type != NONE); }
552 * Get the node's simple (XML) name.
554 const string &getName () const { return _name; }
558 * Get the node's integer index.
560 const int getIndex () const { return _index; }
564 * Get a non-const pointer to the node's parent.
566 SGPropertyNode * getParent () { return _parent; }
570 * Get a const pointer to the node's parent.
572 const SGPropertyNode * getParent () const { return _parent; }
581 * Get the number of child nodes.
583 const int nChildren () const { return _children.size(); }
587 * Get a child node by position (*NOT* index).
589 SGPropertyNode * getChild (int position);
593 * Get a const child node by position (*NOT* index).
595 const SGPropertyNode * getChild (int position) const;
599 * Get a child node by name and index.
601 SGPropertyNode * getChild (const string &name, int index = 0,
602 bool create = false);
606 * Get a const child node by name and index.
608 const SGPropertyNode * getChild (const string &name, int index = 0) const;
612 * Get a vector of all children with the specified name.
614 vector<SGPropertyNode *> getChildren (const string &name);
618 * Get a vector all all children (const) with the specified name.
620 vector<const SGPropertyNode *> getChildren (const string &name) const;
629 * Alias this node's leaf value to another's.
631 bool alias (SGPropertyNode * target);
635 * Alias this node's leaf value to another's by relative path.
637 bool alias (const string &path);
641 * Remove any alias for this node.
647 * Test whether the node's leaf value is aliased to another's.
649 bool isAlias () const { return (_type == ALIAS); }
653 * Get a non-const pointer to the current alias target, if any.
655 SGPropertyNode * getAliasTarget ();
659 * Get a const pointer to the current alias target, if any.
661 const SGPropertyNode * getAliasTarget () const;
670 * Get the path to this node from the root.
672 string getPath (bool simplify = false) const;
676 * Get a pointer to the root node.
678 SGPropertyNode * getRootNode ();
682 * Get a const pointer to the root node.
684 const SGPropertyNode * getRootNode () const;
688 * Get a pointer to another node by relative path.
690 SGPropertyNode * getNode (const string &relative_path, bool create = false);
694 * Get a 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 separately (and save some
698 * string building). For example, getNode("/bar[1]/foo", 3) is
699 * exactly equivalent to getNode("bar[1]/foo[3]"). The index
700 * provided overrides any given in the path itself for the last
703 SGPropertyNode * getNode (const string &relative_path, int index,
704 bool create = false);
708 * Get a const pointer to another node by relative path.
710 const SGPropertyNode * getNode (const string &relative_path) const;
714 * Get a const pointer to another node by relative path.
716 * This method leaves the index off the last member of the path,
717 * so that the user can specify it separate.
719 const SGPropertyNode * getNode (const string &relative_path,
728 * Check a single mode attribute for the property node.
730 bool getAttribute (Attribute attr) const { return ((_attr & attr) != 0); }
734 * Set a single mode attribute for the property node.
736 void setAttribute (Attribute attr, bool state) {
737 (state ? _attr |= attr : _attr &= ~attr);
742 * Get all of the mode attributes for the property node.
744 int getAttributes () const { return _attr; }
748 * Set all of the mode attributes for the property node.
750 void setAttributes (int attr) { _attr = attr; }
754 // Leaf Value (primitive).
759 * Get the type of leaf value, if any, for this node.
761 Type getType () const;
765 * Get a bool value for this node.
767 bool getBoolValue () const;
771 * Get an int value for this node.
773 int getIntValue () const;
777 * Get a long int value for this node.
779 long getLongValue () const;
783 * Get a float value for this node.
785 float getFloatValue () const;
789 * Get a double value for this node.
791 double getDoubleValue () const;
795 * Get a string value for this node.
797 string getStringValue () const;
802 * Set a bool value for this node.
804 bool setBoolValue (bool value);
808 * Set an int value for this node.
810 bool setIntValue (int value);
814 * Set a long int value for this node.
816 bool setLongValue (long value);
820 * Set a float value for this node.
822 bool setFloatValue (float value);
826 * Set a double value for this node.
828 bool setDoubleValue (double value);
832 * Set a string value for this node.
834 bool setStringValue (string value);
838 * Set a value of unspecified type for this node.
840 bool setUnspecifiedValue (string value);
849 * Test whether this node is bound to an external data source.
851 bool isTied () const { return _tied; }
855 * Bind this node to an external bool source.
857 bool tie (const SGRawValue<bool> &rawValue, bool useDefault = true);
861 * Bind this node to an external int source.
863 bool tie (const SGRawValue<int> &rawValue, bool useDefault = true);
867 * Bind this node to an external long int source.
869 bool tie (const SGRawValue<long> &rawValue, bool useDefault = true);
873 * Bind this node to an external float source.
875 bool tie (const SGRawValue<float> &rawValue, bool useDefault = true);
879 * Bind this node to an external double source.
881 bool tie (const SGRawValue<double> &rawValue, bool useDefault = true);
885 * Bind this node to an external string source.
887 bool tie (const SGRawValue<string> &rawValue, bool useDefault = true);
891 * Unbind this node from any external data source.
897 // Convenience methods using paths.
898 // TODO: add attribute methods
903 * Get another node's type.
905 Type getType (const string &relative_path) const;
909 * Test whether another node has a leaf value.
911 bool hasValue (const string &relative_path) const;
915 * Get another node's value as a bool.
917 bool getBoolValue (const string &relative_path,
918 bool defaultValue = false) const;
922 * Get another node's value as an int.
924 int getIntValue (const string &relative_path,
925 int defaultValue = 0) const;
929 * Get another node's value as a long int.
931 long getLongValue (const string &relative_path,
932 long defaultValue = 0L) const;
936 * Get another node's value as a float.
938 float getFloatValue (const string &relative_path,
939 float defaultValue = 0.0) const;
943 * Get another node's value as a double.
945 double getDoubleValue (const string &relative_path,
946 double defaultValue = 0.0L) const;
950 * Get another node's value as a string.
952 string getStringValue (const string &relative_path,
953 string defaultValue = "") const;
957 * Set another node's value as a bool.
959 bool setBoolValue (const string &relative_path, bool value);
963 * Set another node's value as an int.
965 bool setIntValue (const string &relative_path, int value);
969 * Set another node's value as a long int.
971 bool setLongValue (const string &relative_path, long value);
975 * Set another node's value as a float.
977 bool setFloatValue (const string &relative_path, float value);
981 * Set another node's value as a double.
983 bool setDoubleValue (const string &relative_path, double value);
987 * Set another node's value as a string.
989 bool setStringValue (const string &relative_path, string value);
993 * Set another node's value with no specified type.
995 bool setUnspecifiedValue (const string &relative_path, string value);
999 * Test whether another node is bound to an external data source.
1001 bool isTied (const string &relative_path) const;
1005 * Bind another node to an external bool source.
1007 bool tie (const string &relative_path, const SGRawValue<bool> &rawValue,
1008 bool useDefault = true);
1012 * Bind another node to an external int source.
1014 bool tie (const string &relative_path, const SGRawValue<int> &rawValue,
1015 bool useDefault = true);
1019 * Bind another node to an external long int source.
1021 bool tie (const string &relative_path, const SGRawValue<long> &rawValue,
1022 bool useDefault = true);
1026 * Bind another node to an external float source.
1028 bool tie (const string &relative_path, const SGRawValue<float> &rawValue,
1029 bool useDefault = true);
1033 * Bind another node to an external double source.
1035 bool tie (const string &relative_path, const SGRawValue<double> &rawValue,
1036 bool useDefault = true);
1040 * Bind another node to an external string source.
1042 bool tie (const string &relative_path, const SGRawValue<string> &rawValue,
1043 bool useDefault = true);
1047 * Unbind another node from any external data source.
1049 bool untie (const string &relative_path);
1056 * Protected constructor for making new nodes on demand.
1058 SGPropertyNode (const string &name, int index, SGPropertyNode * parent);
1065 * Clear any existing value and set the type to NONE.
1067 void clear_value ();
1071 * Get the value as a string.
1073 string get_string () const;
1077 * Trace a read access.
1079 void trace_read (Type accessType) const;
1083 * Trace a write access.
1085 void trace_write (Type accessType) const;
1089 SGPropertyNode * _parent;
1090 vector<SGPropertyNode *> _children;
1091 typedef map<const string,SGPropertyNode *> cache_map;
1092 cache_map * _path_cache;
1097 // The right kind of pointer...
1099 SGPropertyNode * alias;
1100 SGRawValue<bool> * bool_val;
1101 SGRawValue<int> * int_val;
1102 SGRawValue<long> * long_val;
1103 SGRawValue<float> * float_val;
1104 SGRawValue<double> * double_val;
1105 SGRawValue<string> * string_val;
1113 ////////////////////////////////////////////////////////////////////////
1115 ////////////////////////////////////////////////////////////////////////
1119 * Read properties from an XML input stream.
1121 void readProperties (istream &input, SGPropertyNode * start_node,
1122 const string &base = "");
1126 * Read properties from an XML file.
1128 void readProperties (const string &file, SGPropertyNode * start_node);
1132 * Write properties to an XML output stream.
1134 void writeProperties (ostream &output, const SGPropertyNode * start_node);
1138 * Write properties to an XML file.
1140 void writeProperties (const string &file, const SGPropertyNode * start_node);
1144 * Copy properties from one node to another.
1146 bool copyProperties (const SGPropertyNode *in, SGPropertyNode *out);
1149 #endif // __PROPS_HXX