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 NONE as a macro!
36 #pragma warn A sloppy coder has defined ALIAS as a macro!
41 #pragma warn A sloppy coder has defined UNSPECIFIED as a macro!
46 #pragma warn A sloppy coder has defined BOOL as a macro!
51 #pragma warn A sloppy coder has defined INT as a macro!
56 #pragma warn A sloppy coder has defined LONG as a macro!
61 #pragma warn A sloppy coder has defined FLOAT as a macro!
66 #pragma warn A sloppy coder has defined DOUBLE as a macro!
71 #pragma warn A sloppy coder has defined STRING as a macro!
77 ////////////////////////////////////////////////////////////////////////
80 // This is the mechanism that information-providing routines can
81 // use to link their own values to the property manager. Any
82 // SGValue can be tied to a raw value and then untied again.
83 ////////////////////////////////////////////////////////////////////////
87 * Abstract base class for a raw value.
89 * The property manager is implemented in three layers. The {@link
90 * SGPropertyNode} is the highest and most abstract layer,
91 * representing * an LValue/RValue pair: it * records the position
92 * of the property in the property tree and * contains facilities
93 * for navigation to other nodes. Each node * may contain an {@link
94 * SGValue}, which is guaranteed persistent: the * {@link SGValue}
95 * will not change during a session, even if the * property is bound
96 * and unbound multiple times. The SGValue is the * abstraction of
97 * an RValue: it allows for conversion among all of the different
98 * types, and can be bound to external pointers, functions, methods,
99 * or other data sources. Every SGValue contains an SGRawValue of
100 * a specific type. The SGRawValue (this class) may change frequently
101 * during a session as a value is retyped or bound and unbound to
102 * various data source, but the abstract SGValue layer insulates
103 * the application from those changes. The raw value contains no
104 * facilities for data binding or for type conversion: it is simply
105 * the abstraction of a primitive data type (or a compound data
106 * type, in the case of a string).
108 * The SGValue class always keeps a *copy* of a raw value, not the
109 * original one passed to it; if you override a derived class but do
110 * not replace the {@link #clone} method, strange things will happen.
112 * All raw values must implement {@link #getValue}, {@link #setValue},
113 * and {@link #clone} for the appropriate type.
116 * @see SGPropertyNode */
123 * The default underlying value for this type.
125 * Every raw value has a default; the default is false for a
126 * boolean, 0 for the various numeric values, and "" for a string.
127 * If additional types of raw values are added in the future, they
128 * may need different kinds of default values (such as epoch for a
129 * date type). The default value is used when creating new values.
131 static const T DefaultValue; // Default for this kind of raw value.
137 * Use the default value for this type.
145 virtual ~SGRawValue () {}
149 * Return the underlying value.
151 * @return The actual value for the property.
154 virtual T getValue () const = 0;
158 * Assign a new underlying value.
160 * If the new value cannot be set (because this is a read-only
161 * raw value, or because the new value is not acceptable for
162 * some reason) this method returns false and leaves the original
165 * @param value The actual value for the property.
166 * @return true if the value was set successfully, false otherwise.
169 virtual bool setValue (T value) = 0;
173 * Create a new deep copy of this raw value.
175 * The copy will contain its own version of the underlying value
178 * @return A deep copy of the current object.
180 virtual SGRawValue * clone () const = 0;
185 * An unbound raw value, stored internally.
187 * Instances of this class are created automatically, by default,
188 * by the SGValue class; ordinarily the application should not
192 class SGRawValueInternal : public SGRawValue<T>
197 * Default constructor.
199 * Initialize with the default value for this type.
201 SGRawValueInternal () {}
204 * Explicit value constructor.
206 * Initialize with the underlying value provided.
208 * @param value The initial value for this property.
210 SGRawValueInternal (T value) : _value(value) {}
215 virtual ~SGRawValueInternal () {}
218 * Get the underlying value.
220 virtual T getValue () const { return _value; }
223 * Set the underlying value.
225 virtual bool setValue (T value) { _value = value; return true; }
228 * Create a deep copy of this raw value.
230 virtual SGRawValue<T> * clone () const {
231 return new SGRawValueInternal<T>(_value);
240 * A raw value bound to a pointer.
242 * This is the most efficient way to tie an external value, but also
243 * the most dangerous, because there is no way for the supplier to
244 * perform bounds checking and derived calculations except by polling
245 * the variable to see if it has changed. There is no default
246 * constructor, because this class would be meaningless without a
250 class SGRawValuePointer : public SGRawValue<T>
255 * Explicit pointer constructor.
257 * Create a new raw value bound to the value of the variable
258 * referenced by the pointer.
260 * @param ptr The pointer to the variable to which this raw value
263 SGRawValuePointer (T * ptr) : _ptr(ptr) {}
268 virtual ~SGRawValuePointer () {}
271 * Get the underlying value.
273 * This method will dereference the pointer and return the
276 virtual T getValue () const { return *_ptr; }
279 * Set the underlying value.
281 * This method will dereference the pointer and change the
284 virtual bool setValue (T value) { *_ptr = value; return true; }
287 * Create a copy of this raw value.
289 * The copy will use the same external pointer as the original.
291 virtual SGRawValue<T> * clone () const {
292 return new SGRawValuePointer<T>(_ptr);
301 * A value managed through static functions.
303 * A read-only value will not have a setter; a write-only value will
307 class SGRawValueFunctions : public SGRawValue<T>
312 * The template type of a static getter function.
314 typedef T (*getter_t)();
317 * The template type of a static setter function.
319 typedef void (*setter_t)(T);
322 * Explicit constructor.
324 * Create a new raw value bound to the getter and setter supplied.
326 * @param getter A static function for getting a value, or 0
327 * to read-disable the value.
328 * @param setter A static function for setting a value, or 0
329 * to write-disable the value.
331 SGRawValueFunctions (getter_t getter = 0, setter_t setter = 0)
332 : _getter(getter), _setter(setter) {}
337 virtual ~SGRawValueFunctions () {}
340 * Get the underlying value.
342 * This method will invoke the getter function to get a value.
343 * If no getter function was supplied, this method will always
344 * return the default value for the type.
346 virtual T getValue () const {
347 if (_getter) return (*_getter)();
348 else return SGRawValue<T>::DefaultValue;
352 * Set the underlying value.
354 * This method will invoke the setter function to change the
355 * underlying value. If no setter function was supplied, this
356 * method will return false.
358 virtual bool setValue (T value) {
359 if (_setter) { (*_setter)(value); return true; }
364 * Create a copy of this raw value, bound to the same functions.
366 virtual SGRawValue<T> * clone () const {
367 return new SGRawValueFunctions<T>(_getter,_setter);
377 * An indexed value bound to static functions.
379 * A read-only value will not have a setter; a write-only value will
380 * not have a getter. An indexed value is useful for binding one
381 * of a list of possible values (such as multiple engines for a
382 * plane). The index is hard-coded at creation time.
385 class SGRawValueFunctionsIndexed : public SGRawValue<T>
388 typedef T (*getter_t)(int);
389 typedef void (*setter_t)(int,T);
390 SGRawValueFunctionsIndexed (int index, getter_t getter = 0, setter_t setter = 0)
391 : _index(index), _getter(getter), _setter(setter) {}
392 virtual ~SGRawValueFunctionsIndexed () {}
393 virtual T getValue () const {
394 if (_getter) return (*_getter)(_index);
395 else return SGRawValue<T>::DefaultValue;
397 virtual bool setValue (T value) {
398 if (_setter) { (*_setter)(_index, value); return true; }
401 virtual SGRawValue<T> * clone () const {
402 return new SGRawValueFunctionsIndexed<T>(_index, _getter, _setter);
412 * A value managed through an object and access methods.
414 * A read-only value will not have a setter; a write-only value will
417 template <class C, class T>
418 class SGRawValueMethods : public SGRawValue<T>
421 typedef T (C::*getter_t)() const;
422 typedef void (C::*setter_t)(T);
423 SGRawValueMethods (C &obj, getter_t getter = 0, setter_t setter = 0)
424 : _obj(obj), _getter(getter), _setter(setter) {}
425 virtual ~SGRawValueMethods () {}
426 virtual T getValue () const {
427 if (_getter) { return (_obj.*_getter)(); }
428 else { return SGRawValue<T>::DefaultValue; }
430 virtual bool setValue (T value) {
431 if (_setter) { (_obj.*_setter)(value); return true; }
434 virtual SGRawValue<T> * clone () const {
435 return new SGRawValueMethods<C,T>(_obj, _getter, _setter);
445 * An indexed value managed through an object and access methods.
447 * A read-only value will not have a setter; a write-only value will
450 template <class C, class T>
451 class SGRawValueMethodsIndexed : public SGRawValue<T>
454 typedef T (C::*getter_t)(int) const;
455 typedef void (C::*setter_t)(int, T);
456 SGRawValueMethodsIndexed (C &obj, int index,
457 getter_t getter = 0, setter_t setter = 0)
458 : _obj(obj), _index(index), _getter(getter), _setter(setter) {}
459 virtual ~SGRawValueMethodsIndexed () {}
460 virtual T getValue () const {
461 if (_getter) { return (_obj.*_getter)(_index); }
462 else { return SGRawValue<T>::DefaultValue; }
464 virtual bool setValue (T value) {
465 if (_setter) { (_obj.*_setter)(_index, value); return true; }
468 virtual SGRawValue<T> * clone () const {
469 return new SGRawValueMethodsIndexed<C,T>(_obj, _index, _getter, _setter);
481 * A node in a property tree.
490 * Property value types.
506 * Access mode attributes.
508 * <p>The ARCHIVE attribute is strictly advisory, and controls
509 * whether the property should normally be saved and restored.</p>
521 * Default constructor.
529 SGPropertyNode (const SGPropertyNode &node);
535 virtual ~SGPropertyNode ();
544 * Test whether this node contains a primitive leaf value.
546 bool hasValue () const { return (_type != NONE); }
550 * Get the node's simple (XML) name.
552 const string &getName () const { return _name; }
556 * Get the node's integer index.
558 const int getIndex () const { return _index; }
562 * Get a non-const pointer to the node's parent.
564 SGPropertyNode * getParent () { return _parent; }
568 * Get a const pointer to the node's parent.
570 const SGPropertyNode * getParent () const { return _parent; }
579 * Get the number of child nodes.
581 const int nChildren () const { return _children.size(); }
585 * Get a child node by position (*NOT* index).
587 SGPropertyNode * getChild (int position);
591 * Get a const child node by position (*NOT* index).
593 const SGPropertyNode * getChild (int position) const;
597 * Get a child node by name and index.
599 SGPropertyNode * getChild (const string &name, int index = 0,
600 bool create = false);
604 * Get a const child node by name and index.
606 const SGPropertyNode * getChild (const string &name, int index = 0) const;
610 * Get a vector of all children with the specified name.
612 vector<SGPropertyNode *> getChildren (const string &name);
616 * Get a vector all all children (const) with the specified name.
618 vector<const SGPropertyNode *> getChildren (const string &name) const;
627 * Alias this node's leaf value to another's.
629 bool alias (SGPropertyNode * target);
633 * Alias this node's leaf value to another's by relative path.
635 bool alias (const string &path);
639 * Remove any alias for this node.
645 * Test whether the node's leaf value is aliased to another's.
647 bool isAlias () const { return (_type == ALIAS); }
651 * Get a non-const pointer to the current alias target, if any.
653 SGPropertyNode * getAliasTarget ();
657 * Get a const pointer to the current alias target, if any.
659 const SGPropertyNode * getAliasTarget () const;
668 * Get the path to this node from the root.
670 string getPath (bool simplify = false) const;
674 * Get a pointer to the root node.
676 SGPropertyNode * getRootNode ();
680 * Get a const pointer to the root node.
682 const SGPropertyNode * getRootNode () const;
686 * Get a pointer to another node by relative path.
688 SGPropertyNode * getNode (const string &relative_path, bool create = false);
692 * Get a const pointer to another node by relative path.
694 const SGPropertyNode * getNode (const string &relative_path) const;
702 * Check a single mode attribute for the property node.
704 bool getAttribute (Attribute attr) const { return ((_attr & attr) != 0); }
708 * Set a single mode attribute for the property node.
710 void setAttribute (Attribute attr, bool state) {
711 (state ? _attr |= attr : _attr &= ~attr);
716 * Get all of the mode attributes for the property node.
718 int getAttributes () const { return _attr; }
722 * Set all of the mode attributes for the property node.
724 void setAttributes (int attr) { _attr = attr; }
728 // Leaf Value (primitive).
733 * Get the type of leaf value, if any, for this node.
735 Type getType () const;
739 * Get a bool value for this node.
741 bool getBoolValue () const;
745 * Get an int value for this node.
747 int getIntValue () const;
751 * Get a long int value for this node.
753 long getLongValue () const;
757 * Get a float value for this node.
759 float getFloatValue () const;
763 * Get a double value for this node.
765 double getDoubleValue () const;
769 * Get a string value for this node.
771 string getStringValue () const;
776 * Set a bool value for this node.
778 bool setBoolValue (bool value);
782 * Set an int value for this node.
784 bool setIntValue (int value);
788 * Set a long int value for this node.
790 bool setLongValue (long value);
794 * Set a float value for this node.
796 bool setFloatValue (float value);
800 * Set a double value for this node.
802 bool setDoubleValue (double value);
806 * Set a string value for this node.
808 bool setStringValue (string value);
812 * Set a value of unspecified type for this node.
814 bool setUnspecifiedValue (string value);
823 * Test whether this node is bound to an external data source.
825 bool isTied () const { return _tied; }
829 * Bind this node to an external bool source.
831 bool tie (const SGRawValue<bool> &rawValue, bool useDefault = true);
835 * Bind this node to an external int source.
837 bool tie (const SGRawValue<int> &rawValue, bool useDefault = true);
841 * Bind this node to an external long int source.
843 bool tie (const SGRawValue<long> &rawValue, bool useDefault = true);
847 * Bind this node to an external float source.
849 bool tie (const SGRawValue<float> &rawValue, bool useDefault = true);
853 * Bind this node to an external double source.
855 bool tie (const SGRawValue<double> &rawValue, bool useDefault = true);
859 * Bind this node to an external string source.
861 bool tie (const SGRawValue<string> &rawValue, bool useDefault = true);
865 * Unbind this node from any external data source.
871 // Convenience methods using paths.
872 // TODO: add attribute methods
877 * Get another node's type.
879 Type getType (const string &relative_path) const;
883 * Test whether another node has a leaf value.
885 bool hasValue (const string &relative_path) const;
889 * Get another node's value as a bool.
891 bool getBoolValue (const string &relative_path,
892 bool defaultValue = false) const;
896 * Get another node's value as an int.
898 int getIntValue (const string &relative_path,
899 int defaultValue = 0) const;
903 * Get another node's value as a long int.
905 long getLongValue (const string &relative_path,
906 long defaultValue = 0L) const;
910 * Get another node's value as a float.
912 float getFloatValue (const string &relative_path,
913 float defaultValue = 0.0) const;
917 * Get another node's value as a double.
919 double getDoubleValue (const string &relative_path,
920 double defaultValue = 0.0L) const;
924 * Get another node's value as a string.
926 string getStringValue (const string &relative_path,
927 string defaultValue = "") const;
931 * Set another node's value as a bool.
933 bool setBoolValue (const string &relative_path, bool value);
937 * Set another node's value as an int.
939 bool setIntValue (const string &relative_path, int value);
943 * Set another node's value as a long int.
945 bool setLongValue (const string &relative_path, long value);
949 * Set another node's value as a float.
951 bool setFloatValue (const string &relative_path, float value);
955 * Set another node's value as a double.
957 bool setDoubleValue (const string &relative_path, double value);
961 * Set another node's value as a string.
963 bool setStringValue (const string &relative_path, string value);
967 * Set another node's value with no specified type.
969 bool setUnspecifiedValue (const string &relative_path, string value);
973 * Test whether another node is bound to an external data source.
975 bool isTied (const string &relative_path) const;
979 * Bind another node to an external bool source.
981 bool tie (const string &relative_path, const SGRawValue<bool> &rawValue,
982 bool useDefault = true);
986 * Bind another node to an external int source.
988 bool tie (const string &relative_path, const SGRawValue<int> &rawValue,
989 bool useDefault = true);
993 * Bind another node to an external long int source.
995 bool tie (const string &relative_path, const SGRawValue<long> &rawValue,
996 bool useDefault = true);
1000 * Bind another node to an external float source.
1002 bool tie (const string &relative_path, const SGRawValue<float> &rawValue,
1003 bool useDefault = true);
1007 * Bind another node to an external double source.
1009 bool tie (const string &relative_path, const SGRawValue<double> &rawValue,
1010 bool useDefault = true);
1014 * Bind another node to an external string source.
1016 bool tie (const string &relative_path, const SGRawValue<string> &rawValue,
1017 bool useDefault = true);
1021 * Unbind another node from any external data source.
1023 bool untie (const string &relative_path);
1030 * Protected constructor for making new nodes on demand.
1032 SGPropertyNode (const string &name, int index, SGPropertyNode * parent);
1039 * Clear any existing value and set the type to NONE.
1041 void clear_value ();
1045 * Get the value as a string.
1047 string get_string () const;
1051 * Trace a read access.
1053 void trace_read (Type accessType) const;
1057 * Trace a write access.
1059 void trace_write (Type accessType) const;
1063 SGPropertyNode * _parent;
1064 vector<SGPropertyNode *> _children;
1071 // The right kind of pointer...
1073 SGPropertyNode * alias;
1074 SGRawValue<bool> * bool_val;
1075 SGRawValue<int> * int_val;
1076 SGRawValue<long> * long_val;
1077 SGRawValue<float> * float_val;
1078 SGRawValue<double> * double_val;
1079 SGRawValue<string> * string_val;
1087 ////////////////////////////////////////////////////////////////////////
1089 ////////////////////////////////////////////////////////////////////////
1093 * Read properties from an XML input stream.
1095 void readProperties (istream &input, SGPropertyNode * start_node,
1096 const string &base = "");
1100 * Read properties from an XML file.
1102 void readProperties (const string &file, SGPropertyNode * start_node);
1106 * Write properties to an XML output stream.
1108 void writeProperties (ostream &output, const SGPropertyNode * start_node);
1112 * Write properties to an XML file.
1114 void writeProperties (const string &file, const SGPropertyNode * start_node);
1118 * Copy properties from one node to another.
1120 bool copyProperties (const SGPropertyNode *in, SGPropertyNode *out);
1123 #endif // __PROPS_HXX