src/Value.hh

   1 /*
   2  * Copyright (C) 2002,2004 Daniel Heck
   3  * Copyright (C) 2007,2008,2009 Ronald Lamprecht
   4  *
   5  * This program is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU General Public License
   7  * as published by the Free Software Foundation; either version 2
   8  * of the License, or (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  *
  19  */
  20 #ifndef VALUE_HH
  21 #define VALUE_HH
  22
  23 /*
  24  * This file contains declarations for facilities used by several
  25  * different parts of the program, like common types and constants,
  26  * and routines for resource management.
  27  */
  28
  29 #include "enigma.hh"
  30
  31 namespace enigma {
  32
  33     class Object;
  34     class Value;
  35
  36     typedef std::list<Object *> ObjectList;
  37     typedef std::list<Value> TokenList;
  38     typedef std::list<Value> PositionList;
  39
  40     /**
  41      * A flexible container for various types of data. This class is one
  42      * of the central Enigma concepts. It is used for Object attributes,
  43      * for passing arguments and return values in messages and for exchanging
  44      * values with LUA code.
  45      *
  46      * Object attributes besides the common floor, item, stone, actor traits
  47      * are usually very specific and only few objects will be aware of
  48      * them. The Value provides a common container, that allows all objects
  49      * and the world to pass these attributes without any further knowledge.
  50      *
  51      * Instances of Value can be passed to and from the type free LUA language.
  52      * Objects can be configured in their attributes and questioned about states
  53      * via attributes.
  54      *
  55      * Value are converted to required types as far as possible and in a
  56      * LUA compatible manner.
  57      *
  58      * Bool Values can not be assigned directly to a bool variable. Use the
  59      * to_bool() method for retrieving proper bool values.
  60      *
  61      * A special Value type called "DEFAULT" exists within the C++ engine. It
  62      * describes a not explicitly set Value. The receiver of this Value should use
  63      * or request the default behaviour. "DEFAULT" Values are the only Values
  64      * that are converted to bool "false". All other Values convert to bool
  65      * "true". Thus a value can be checked for existance by evaluating it as a
  66      * bool. This remains true even for Values that contain bool content! A
  67      * common pattern for handling Values is:
  68      *
  69      * <pre>
  70      * if (Value v = getAttr("key")) {   // proceed only if attribute exists
  71      *     int i = v;                    // assign value to an int
  72      *     std::string s(v);             // create a string out of a value
  73      *     x = (double)v * 2;            // cast v to a desired type
  74      *     double d = getAttr("x", 2);   // get a value with a default of 2.0
  75      * }
  76      * </pre>
  77      */
  78     class Value {
  79     public:
  80         /**
  81          * Specifier for the current type of the value content.
  82          */
  83         enum Type {
  84             DEFAULT,  ///< Pseudotype for a not existing attribute that should
  85                       ///< cause the default behaviour of the object
  86             NIL,      ///< Value that is equivalent to Lua "nil". It represents
  87                       ///< an invalid value
  88             BOOL,     ///< Value that represents bool values "true" and "false".
  89             DOUBLE,   ///< Value is numerical and can take a "double". It is used
  90                       ///< for other numericals values like "int", too.
  91             STRING,   ///< Value is a string. Such a string may encode another
  92                       ///< type that has no native representation in Value
  93             OBJECT,   ///< Value is an object id. The id is a persistent object
  94                       ///< identifier.
  95             GROUP,    ///< Value is a group of objects.
  96             POSITION, ///< Value is a position
  97             GRIDPOS,  ///< Value is a grid position
  98             TOKENS,   ///< Value is a list of token values
  99             NAMEDOBJECT  ///< internal Value type for named objects - public type is OBJECT
 100         };
 101
 102         Value();                       ///< Constructor for NIL value that
 103                                        ///< represents an invalid value
 104         Value(double d);               ///< Constructor for DOUBLE value
 105         Value(const char* str);        ///< Constructor for STRING value. The
 106                                        ///< given string is duplicated
 107         Value(const std::string& str); ///< Constructor for STRING value. The
 108                                        ///< given string is duplicated
 109         Value(int i);                  ///< Constructor for DOUBLE value
 110         Value(bool b);                 ///< Constructor for BOOL value
 111         Value(Object *obj);            ///< Constructor for OBJECT value that properly
 112                                        ///< represents a persistent reference to an object
 113         Value(ObjectList aList);       ///< Constructor for OBJECT value that properly
 114                                        ///< represents a set of objects
 115         Value(TokenList aList);        ///< Constructor for TOKENS value that properly
 116                                        ///< represents a list of tokens
 117         Value(ecl::V2 pos);            ///< Constructor for POSITION value
 118         Value(GridPos gpos);           ///< Constructor for POSITION value
 119         Value(Type t);                 ///< Constructor for a given type. The
 120                                        ///< value defaults to 0.0 or ""
 121         ~Value();
 122
 123         Value(const Value& v);                 ///< Explicit copy constructor that
 124                                                ///< performs a deep copy
 125         Value& operator=(const Value& v);      ///< Explicit copy assignment that
 126                                                ///< performs a deep copy
 127         /**
 128          * Compare values in type and value. This compare is a LUA like
 129          * compare of values. Note that a DOUBLE value of 1.0 does not equal
 130          * a STRING value of "1.0" even though both values are seamless casted
 131          * to the same double and result in the same numerical calculation results.
 132          *
 133          * If you want to compare two values that express numerical data independent
 134          * of their value type use the pattern:
 135          * <pre>
 136          *     (double) value1 == (double) value2
 137          * </pre>
 138          */
 139         bool operator==(const Value& v) const;
 140         bool operator!=(const Value& v) const; ///< Compare values in type and value
 141         bool operator==(int i) const;          ///< Compare value with int without casting.
 142                                                ///< f.e <code>if (v == 2)</code>
 143         bool operator!=(int i) const;          ///< Compare value with int without casting
 144         bool operator<=(int i) const;          ///< Compare value with int without casting
 145         bool operator>=(int i) const;          ///< Compare value with int without casting
 146
 147         /**
 148          * Test of a value for explicit existence besides a default.
 149          * This conversion returns "false" if the value is of type DEFAULT.
 150          * This happens when a "getAttr()" call did not find a concrete value.
 151          * All other value types that represent explicit given values return "true".
 152          * The main usage is the common pattern <code>if (Value v = getAttr("key"))</code>.
 153          *
 154          * Note: this conversion does not return the result of a boolean stored
 155          * in the value. If a concrete value contains a boolean this test
 156          * returns always "true", even if the boolean is "false" and the value
 157          * is of type NIL.
 158          */
 159         operator bool() const;
 160
 161         /**
 162          * Conversion of a value to a double. String values are interpreted as
 163          * a double like it is done by LUA. All other values default to a double
 164          * value of 0.0.
 165          */
 166         operator double() const;
 167
 168         /**
 169          * Conversion of a value to a int. String values are interpreted as
 170          * a int like it is done by LUA. All other values default to a int
 171          * value of 0.
 172          */
 173         operator int() const;
 174
 175         /**
 176          * Conversion of a value to an object reference. All values besides valid
 177          * object values default to a NULL reference.
 178          */
 179         operator Object *() const;
 180
 181         /**
 182          * Conversion of a value to an object set.
 183          */
 184         operator ObjectList() const;
 185
 186         /**
 187          * Conversion of a value to a list of tokens.
 188          */
 189         operator TokenList() const;
 190
 191         /**
 192          * Conversion of a value to a position vector.
 193          */
 194         operator ecl::V2() const;
 195
 196         /**
 197          * Conversion of a value to a grid position.
 198          */
 199         operator GridPos() const;
 200
 201         /**
 202          * Conversion of a value to a <code>char *</code> just for initialization
 203          * of a std::string. Numerical values are converted to a string like it
 204          * id done by LUA. All other values default to an empty string.
 205          *
 206          * Note that the returned pointer may be volatile and
 207          * cannot be used for any further usage besides immediate initialization of
 208          * a string object. For all other purposes use the <code>to_string()</code> method to
 209          * receive a non-volatile copy of the string.
 210          */
 211         operator const char*() const;
 212
 213         void assign(double d);       ///< Reset value to a DOUBLE
 214         void assign(const char* s);  ///< Reset value to a STRING with a copy of
 215                                      ///< the given string
 216
 217         Type    getType() const;               ///< Returns the current value type
 218         double  get_double() const throw();     ///< Returns the current double value without
 219                                                 ///< any conversion if it is a DOUBLE.
 220                                                 ///< On type mismatch a XLevelRuntime is thrown
 221         const char* get_string() const throw(); ///< Returns the current string value without
 222                                                 ///< any conversion if it is a STRING.
 223                                                 ///< On type mismatch a XLevelRuntime is thrown
 224         bool isDefault() const;                 ///< Returns true if type is DEFAULT
 225
 226         /**
 227          * Returns a std::string with convertion of numerical values. All other
 228          * values default to an empty string.
 229          */
 230         std::string to_string() const;
 231
 232         /**
 233          * Returns the LUA compatible boolean representation of the value.
 234          * <code>false</code> is returned for a NIL value and <code>true</code>
 235          * for any other value.
 236          */
 237         bool to_bool() const;
 238
 239         /**
 240          * Returns the value converted to a vector position with a centering of all
 241          * grid position type values. GRIDPOS type values as well as all positions of
 242          * GridObject's will be return as grid centered vector positions, while true
 243          * vector position values and positions of Actor's will be returned as is.
 244          * Other values will return a position of (-1, -1) indicating a false position
 245          */
 246         ecl::V2 centeredPos() const;
 247
 248         /**
 249          *
 250          */
 251         ObjectList getObjectList(Object *reference = NULL) const;
 252         PositionList getPositionList(Object *reference =NULL) const;
 253         bool finalizeNearestObjectReference(Object *reference = NULL);
 254         bool maybeNearestObjectReference() const;
 255     private:
 256         void clear();      ///< Release resources and assign type NIL
 257
 258         // Variables
 259         Type type;
 260         union {
 261             double dval[2];
 262             char* str;
 263         } val;
 264     };
 265
 266
 267     bool        to_bool(const Value &v);        ///< Synonym for v.to_bool()
 268     int         to_int(const Value &v);         ///< Synonym for (int)v
 269     double      to_double(const Value &v);      ///< Synonym for (double)v
 270     std::string to_string(const Value &v);      ///< Synonym for v.to_string()
 271     Direction   to_direction (const Value &v);  ///< Casting of value to Direction
 272
 273 } // namespace enigma
 274
 275 #endif