src/script/api/script_error.hpp

   1 /* $Id$ */
   2
   3 /*
   4  * This file is part of OpenTTD.
   5  * OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
   6  * OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   7  * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
   8  */
   9
  10 /** @file script_error.hpp Everything to query errors. */
  11
  12 #ifndef SCRIPT_ERROR_HPP
  13 #define SCRIPT_ERROR_HPP
  14
  15 #include "script_object.hpp"
  16 #include <map>
  17
  18 /**
  19  * Helper to write precondition enforcers for the script API in an abbreviated manner.
  20  * @param returnval The value to return on failure.
  21  * @param condition The condition that must be obeyed.
  22  */
  23 #define EnforcePrecondition(returnval, condition)               \
  24         if (!(condition)) {                                           \
  25                 ScriptObject::SetLastError(ScriptError::ERR_PRECONDITION_FAILED);   \
  26                 return returnval;                                           \
  27         }
  28
  29 /**
  30  * Helper to write precondition enforcers for the script API in an abbreviated manner.
  31  * @param returnval The value to return on failure.
  32  * @param condition The condition that must be obeyed.
  33  * @param error_code The error code passed to ScriptObject::SetLastError.
  34  */
  35 #define EnforcePreconditionCustomError(returnval, condition, error_code)   \
  36         if (!(condition)) {                                                      \
  37                 ScriptObject::SetLastError(error_code);                                    \
  38                 return returnval;                                                      \
  39         }
  40
  41 /**
  42  * Helper to write precondition enforcers for the script API in an abbreviated manner for encoded texts.
  43  * @param returnval The value to return on failure.
  44  * @param string The string that is checked.
  45  */
  46 #define EnforcePreconditionEncodedText(returnval, string)   \
  47         if ((string) == NULL) { \
  48                 ScriptObject::SetLastError(ScriptError::ERR_PRECONDITION_TOO_MANY_PARAMETERS); \
  49                 return returnval; \
  50         } \
  51         if (StrEmpty(string)) { \
  52                 ScriptObject::SetLastError(ScriptError::ERR_PRECONDITION_FAILED); \
  53                 return returnval; \
  54         }
  55
  56 /**
  57  * Class that handles all error related functions.
  58  * @api ai game
  59  */
  60 class ScriptError : public ScriptObject {
  61 public:
  62         /**
  63          * All categories errors can be divided in.
  64          */
  65         enum ErrorCategories {
  66                 ERR_CAT_NONE = 0, ///< Error messages not related to any category.
  67                 ERR_CAT_GENERAL,  ///< Error messages related to general things.
  68                 ERR_CAT_VEHICLE,  ///< Error messages related to building / maintaining vehicles.
  69                 ERR_CAT_STATION,  ///< Error messages related to building / maintaining stations.
  70                 ERR_CAT_BRIDGE,   ///< Error messages related to building / removing bridges.
  71                 ERR_CAT_TUNNEL,   ///< Error messages related to building / removing tunnels.
  72                 ERR_CAT_TILE,     ///< Error messages related to raising / lowering and demolishing tiles.
  73                 ERR_CAT_SIGN,     ///< Error messages related to building / removing signs.
  74                 ERR_CAT_RAIL,     ///< Error messages related to building / maintaining rails.
  75                 ERR_CAT_ROAD,     ///< Error messages related to building / maintaining roads.
  76                 ERR_CAT_ORDER,    ///< Error messages related to managing orders.
  77                 ERR_CAT_MARINE,   ///< Error messages related to building / removing ships, docks and channels.
  78                 ERR_CAT_WAYPOINT, ///< Error messages related to building / maintaining waypoints.
  79
  80                 /**
  81                  * DO NOT USE! The error bitsize determines how many errors can be stored in
  82                  *  a category and what the offsets are of all categories.
  83                  */
  84                 ERR_CAT_BIT_SIZE = 8,
  85         };
  86
  87         /**
  88          * All general related error messages.
  89          */
  90         enum ErrorMessages {
  91                 /** Initial error value */
  92                 ERR_NONE = ERR_CAT_NONE << ERR_CAT_BIT_SIZE,  // []
  93                 /** If an error occurred and the error wasn't mapped */
  94                 ERR_UNKNOWN,                                  // []
  95                 /** If a precondition is not met */
  96                 ERR_PRECONDITION_FAILED,                      // []
  97                 /** A string supplied was too long */
  98                 ERR_PRECONDITION_STRING_TOO_LONG,             // []
  99                 /** A string had too many parameters */
 100                 ERR_PRECONDITION_TOO_MANY_PARAMETERS,         // []
 101                 /** The company you use is invalid */
 102                 ERR_PRECONDITION_INVALID_COMPANY,             // []
 103                 /** An error returned by a NewGRF. No possibility to get the exact error in an script readable format */
 104                 ERR_NEWGRF_SUPPLIED_ERROR,                    // []
 105
 106                 /** Base for general errors */
 107                 ERR_GENERAL_BASE = ERR_CAT_GENERAL << ERR_CAT_BIT_SIZE,
 108
 109                 /** Not enough cash to perform the previous action */
 110                 ERR_NOT_ENOUGH_CASH,                          // [STR_ERROR_NOT_ENOUGH_CASH_REQUIRES_CURRENCY]
 111
 112                 /** Local authority won't allow the previous action */
 113                 ERR_LOCAL_AUTHORITY_REFUSES,                  // [STR_ERROR_LOCAL_AUTHORITY_REFUSES_TO_ALLOW_THIS]
 114
 115                 /** The piece of infrastructure you tried to build is already in place */
 116                 ERR_ALREADY_BUILT,                            // [STR_ERROR_ALREADY_BUILT, STR_ERROR_MUST_DEMOLISH_BRIDGE_FIRST]
 117
 118                 /** Area isn't clear, try to demolish the building on it */
 119                 ERR_AREA_NOT_CLEAR,                           // [STR_ERROR_BUILDING_MUST_BE_DEMOLISHED, STR_ERROR_MUST_DEMOLISH_BRIDGE_FIRST, STR_ERROR_MUST_DEMOLISH_RAILROAD, STR_ERROR_MUST_DEMOLISH_AIRPORT_FIRST, STR_ERROR_MUST_DEMOLISH_CARGO_TRAM_STATION_FIRST, STR_ERROR_MUST_DEMOLISH_TRUCK_STATION_FIRST, STR_ERROR_MUST_DEMOLISH_PASSENGER_TRAM_STATION_FIRST, STR_ERROR_MUST_DEMOLISH_BUS_STATION_FIRST, STR_ERROR_BUOY_IN_THE_WAY, STR_ERROR_MUST_DEMOLISH_DOCK_FIRST, STR_ERROR_GENERIC_OBJECT_IN_THE_WAY, STR_ERROR_COMPANY_HEADQUARTERS_IN, STR_ERROR_OBJECT_IN_THE_WAY, STR_ERROR_MUST_REMOVE_ROAD_FIRST, STR_ERROR_MUST_REMOVE_RAILROAD_TRACK, STR_ERROR_MUST_DEMOLISH_BRIDGE_FIRST, STR_ERROR_MUST_DEMOLISH_TUNNEL_FIRST, STR_ERROR_EXCAVATION_WOULD_DAMAGE]
 120
 121                 /** Area / property is owned by another company */
 122                 ERR_OWNED_BY_ANOTHER_COMPANY,                 // [STR_ERROR_AREA_IS_OWNED_BY_ANOTHER, STR_ERROR_OWNED_BY]
 123
 124                 /** The name given is not unique for the object type */
 125                 ERR_NAME_IS_NOT_UNIQUE,                       // [STR_ERROR_NAME_MUST_BE_UNIQUE]
 126
 127                 /** The building you want to build requires flat land */
 128                 ERR_FLAT_LAND_REQUIRED,                       // [STR_ERROR_FLAT_LAND_REQUIRED]
 129
 130                 /** Land is sloped in the wrong direction for this build action */
 131                 ERR_LAND_SLOPED_WRONG,                        // [STR_ERROR_LAND_SLOPED_IN_WRONG_DIRECTION]
 132
 133                 /** A vehicle is in the way */
 134                 ERR_VEHICLE_IN_THE_WAY,                       // [STR_ERROR_TRAIN_IN_THE_WAY, STR_ERROR_ROAD_VEHICLE_IN_THE_WAY, STR_ERROR_SHIP_IN_THE_WAY, STR_ERROR_AIRCRAFT_IN_THE_WAY]
 135
 136                 /** Site is unsuitable */
 137                 ERR_SITE_UNSUITABLE,                          // [STR_ERROR_SITE_UNSUITABLE]
 138
 139                 /** Too close to the edge of the map */
 140                 ERR_TOO_CLOSE_TO_EDGE,                        // [STR_ERROR_TOO_CLOSE_TO_EDGE_OF_MAP]
 141
 142                 /** Station is too spread out */
 143                 ERR_STATION_TOO_SPREAD_OUT,                   // [STR_ERROR_STATION_TOO_SPREAD_OUT]
 144         };
 145
 146         /**
 147          * Check the membership of the last thrown error.
 148          * @return The category the error belongs to.
 149          * @note The last throw error can be acquired by calling GetLastError().
 150          */
 151         static ErrorCategories GetErrorCategory();
 152
 153         /**
 154          * Get the last error.
 155          * @return An ErrorMessages enum value.
 156          */
 157         static ScriptErrorType GetLastError();
 158
 159         /**
 160          * Get the last error in string format (for human readability).
 161          * @return An ErrorMessage enum item, as string.
 162          */
 163         static char *GetLastErrorString();
 164
 165         /**
 166          * Get the error based on the OpenTTD StringID.
 167          * @api -all
 168          * @param internal_string_id The string to convert.
 169          * @return The script equivalent error message.
 170          */
 171         static ScriptErrorType StringToError(StringID internal_string_id);
 172
 173         /**
 174          * Map an internal OpenTTD error message to its script equivalent.
 175          * @api -all
 176          * @param internal_string_id The OpenTTD StringID used for an error.
 177          * @param ai_error_msg The script equivalent error message.
 178          */
 179         static void RegisterErrorMap(StringID internal_string_id, ScriptErrorType ai_error_msg);
 180
 181         /**
 182          * Map an internal OpenTTD error message to its script equivalent.
 183          * @api -all
 184          * @param ai_error_msg The script error message representation.
 185          * @param message The string representation of this error message, used for debug purposes.
 186          */
 187         static void RegisterErrorMapString(ScriptErrorType ai_error_msg, const char *message);
 188
 189 private:
 190         typedef std::map<StringID, ScriptErrorType> ScriptErrorMap;           ///< The type for mapping between error (internal OpenTTD) StringID to the script error type.
 191         typedef std::map<ScriptErrorType, const char *> ScriptErrorMapString; ///< The type for mapping between error type and textual representation.
 192
 193         static ScriptErrorMap error_map;              ///< The mapping between error (internal OpenTTD) StringID to the script error type.
 194         static ScriptErrorMapString error_map_string; ///< The mapping between error type and textual representation.
 195 };
 196
 197 #endif /* SCRIPT_ERROR_HPP */