src/script/api/script_error.hpp

   1 /*
   2  * This file is part of OpenTTD.
   3  * 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.
   4  * 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.
   5  * 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/>.
   6  */
   7
   8 /** @file script_error.hpp Everything to query errors. */
   9
  10 #ifndef SCRIPT_ERROR_HPP
  11 #define SCRIPT_ERROR_HPP
  12
  13 #include "script_object.hpp"
  14 #include "script_companymode.hpp"
  15
  16 /**
  17  * Helper to write precondition enforcers for the script API in an abbreviated manner.
  18  * @param returnval The value to return on failure.
  19  * @param condition The condition that must be obeyed.
  20  */
  21 #define EnforcePrecondition(returnval, condition)               \
  22         if (!(condition)) {                                           \
  23                 ScriptObject::SetLastError(ScriptError::ERR_PRECONDITION_FAILED);   \
  24                 return returnval;                                           \
  25         }
  26
  27 /**
  28  * Helper to write precondition enforcers for the script API in an abbreviated manner.
  29  * @param returnval The value to return on failure.
  30  * @param condition The condition that must be obeyed.
  31  * @param error_code The error code passed to ScriptObject::SetLastError.
  32  */
  33 #define EnforcePreconditionCustomError(returnval, condition, error_code)   \
  34         if (!(condition)) {                                                      \
  35                 ScriptObject::SetLastError(error_code);                                    \
  36                 return returnval;                                                      \
  37         }
  38
  39 /**
  40  * Helper to write precondition enforcers for the script API in an abbreviated manner for encoded texts.
  41  * @param returnval The value to return on failure.
  42  * @param string The string that is checked.
  43  */
  44 #define EnforcePreconditionEncodedText(returnval, string)   \
  45         if (string.empty()) { \
  46                 ScriptObject::SetLastError(ScriptError::ERR_PRECONDITION_FAILED); \
  47                 return returnval; \
  48         }
  49
  50 /**
  51  * Helper to enforce the precondition that the company mode is valid.
  52  * @param returnval The value to return on failure.
  53  */
  54 #define EnforceCompanyModeValid(returnval) \
  55         EnforcePreconditionCustomError(returnval, ScriptCompanyMode::IsValid(), ScriptError::ERR_PRECONDITION_INVALID_COMPANY)
  56
  57 /**
  58  * Helper to enforce the precondition that the company mode is valid.
  59  */
  60 #define EnforceCompanyModeValid_Void() \
  61         if (!ScriptCompanyMode::IsValid()) { \
  62                 ScriptObject::SetLastError(ScriptError::ERR_PRECONDITION_INVALID_COMPANY); \
  63                 return; \
  64         }
  65
  66 /**
  67  * Helper to enforce the precondition that we are in a deity mode.
  68  * @param returnval The value to return on failure.
  69  */
  70 #define EnforceDeityMode(returnval) \
  71         EnforcePreconditionCustomError(returnval, ScriptCompanyMode::IsDeity(), ScriptError::ERR_PRECONDITION_INVALID_COMPANY)
  72
  73 /**
  74  * Helper to enforce the precondition that the company mode is valid or that we are a deity.
  75  * @param returnval The value to return on failure.
  76  */
  77 #define EnforceDeityOrCompanyModeValid(returnval) \
  78         EnforcePreconditionCustomError(returnval, ScriptCompanyMode::IsDeity() || ScriptCompanyMode::IsValid(), ScriptError::ERR_PRECONDITION_INVALID_COMPANY)
  79
  80 /**
  81  * Helper to enforce the precondition that the company mode is valid or that we are a deity.
  82  */
  83 #define EnforceDeityOrCompanyModeValid_Void() \
  84         if (!(ScriptCompanyMode::IsDeity() || ScriptCompanyMode::IsValid())) { \
  85                 ScriptObject::SetLastError(ScriptError::ERR_PRECONDITION_INVALID_COMPANY); \
  86                 return; \
  87         }
  88
  89
  90 /**
  91  * Class that handles all error related functions.
  92  * @api ai game
  93  */
  94 class ScriptError : public ScriptObject {
  95 public:
  96         /**
  97          * All categories errors can be divided in.
  98          */
  99         enum ErrorCategories {
 100                 ERR_CAT_NONE = 0, ///< Error messages not related to any category.
 101                 ERR_CAT_GENERAL,  ///< Error messages related to general things.
 102                 ERR_CAT_VEHICLE,  ///< Error messages related to building / maintaining vehicles.
 103                 ERR_CAT_STATION,  ///< Error messages related to building / maintaining stations.
 104                 ERR_CAT_BRIDGE,   ///< Error messages related to building / removing bridges.
 105                 ERR_CAT_TUNNEL,   ///< Error messages related to building / removing tunnels.
 106                 ERR_CAT_TILE,     ///< Error messages related to raising / lowering and demolishing tiles.
 107                 ERR_CAT_SIGN,     ///< Error messages related to building / removing signs.
 108                 ERR_CAT_RAIL,     ///< Error messages related to building / maintaining rails.
 109                 ERR_CAT_ROAD,     ///< Error messages related to building / maintaining roads.
 110                 ERR_CAT_ORDER,    ///< Error messages related to managing orders.
 111                 ERR_CAT_MARINE,   ///< Error messages related to building / removing ships, docks and channels.
 112                 ERR_CAT_WAYPOINT, ///< Error messages related to building / maintaining waypoints.
 113
 114                 /**
 115                  * DO NOT USE! The error bitsize determines how many errors can be stored in
 116                  *  a category and what the offsets are of all categories.
 117                  */
 118                 ERR_CAT_BIT_SIZE = 8,
 119         };
 120
 121         /**
 122          * All general related error messages.
 123          *
 124          * @see ScriptErrorType
 125          */
 126         enum ErrorMessages {
 127                 /** Initial error value */
 128                 ERR_NONE = ERR_CAT_NONE << ERR_CAT_BIT_SIZE,  // []
 129                 /** If an error occurred and the error wasn't mapped */
 130                 ERR_UNKNOWN,                                  // []
 131                 /** If a precondition is not met */
 132                 ERR_PRECONDITION_FAILED,                      // []
 133                 /** A string supplied was too long */
 134                 ERR_PRECONDITION_STRING_TOO_LONG,             // []
 135                 /** The company you use is invalid */
 136                 ERR_PRECONDITION_INVALID_COMPANY,             // []
 137                 /** An error returned by a NewGRF. No possibility to get the exact error in an script readable format */
 138                 ERR_NEWGRF_SUPPLIED_ERROR,                    // []
 139
 140                 /** Base for general errors */
 141                 ERR_GENERAL_BASE = ERR_CAT_GENERAL << ERR_CAT_BIT_SIZE,
 142
 143                 /** Not enough cash to perform the previous action */
 144                 ERR_NOT_ENOUGH_CASH,                          // [STR_ERROR_NOT_ENOUGH_CASH_REQUIRES_CURRENCY]
 145
 146                 /** Local authority won't allow the previous action */
 147                 ERR_LOCAL_AUTHORITY_REFUSES,                  // [STR_ERROR_LOCAL_AUTHORITY_REFUSES_TO_ALLOW_THIS, STR_ERROR_LOCAL_AUTHORITY_REFUSES_NOISE]
 148
 149                 /** The piece of infrastructure you tried to build is already in place */
 150                 ERR_ALREADY_BUILT,                            // [STR_ERROR_ALREADY_BUILT, STR_ERROR_MUST_DEMOLISH_BRIDGE_FIRST, STR_ERROR_TREE_ALREADY_HERE]
 151
 152                 /** Area isn't clear, try to demolish the building on it */
 153                 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]
 154
 155                 /** Area / property is owned by another company */
 156                 ERR_OWNED_BY_ANOTHER_COMPANY,                 // [STR_ERROR_AREA_IS_OWNED_BY_ANOTHER, STR_ERROR_OWNED_BY]
 157
 158                 /** The name given is not unique for the object type */
 159                 ERR_NAME_IS_NOT_UNIQUE,                       // [STR_ERROR_NAME_MUST_BE_UNIQUE]
 160
 161                 /** The building you want to build requires flat land */
 162                 ERR_FLAT_LAND_REQUIRED,                       // [STR_ERROR_FLAT_LAND_REQUIRED]
 163
 164                 /** Land is sloped in the wrong direction for this build action */
 165                 ERR_LAND_SLOPED_WRONG,                        // [STR_ERROR_LAND_SLOPED_IN_WRONG_DIRECTION]
 166
 167                 /** A vehicle is in the way */
 168                 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]
 169
 170                 /** Site is unsuitable */
 171                 ERR_SITE_UNSUITABLE,                          // [STR_ERROR_SITE_UNSUITABLE, STR_ERROR_TREE_WRONG_TERRAIN_FOR_TREE_TYPE]
 172
 173                 /** Too close to the edge of the map */
 174                 ERR_TOO_CLOSE_TO_EDGE,                        // [STR_ERROR_TOO_CLOSE_TO_EDGE_OF_MAP]
 175
 176                 /** Station is too spread out */
 177                 ERR_STATION_TOO_SPREAD_OUT,                   // [STR_ERROR_STATION_TOO_SPREAD_OUT]
 178         };
 179
 180         /**
 181          * Check the membership of the last thrown error.
 182          * @return The category the error belongs to.
 183          * @note The last throw error can be acquired by calling GetLastError().
 184          */
 185         static ErrorCategories GetErrorCategory();
 186
 187         /**
 188          * Get the last error.
 189          * @return An ErrorMessages enum value.
 190          */
 191         static ScriptErrorType GetLastError();
 192
 193         /**
 194          * Get the last error in string format (for human readability).
 195          * @return An ErrorMessage enum item, as string.
 196          */
 197         static std::optional<std::string> GetLastErrorString();
 198
 199         /**
 200          * Get the error based on the OpenTTD StringID.
 201          * @api -all
 202          * @param internal_string_id The string to convert.
 203          * @return The script equivalent error message.
 204          */
 205         static ScriptErrorType StringToError(StringID internal_string_id);
 206
 207         /**
 208          * Map an internal OpenTTD error message to its script equivalent.
 209          * @api -all
 210          * @param internal_string_id The OpenTTD StringID used for an error.
 211          * @param ai_error_msg The script equivalent error message.
 212          */
 213         static void RegisterErrorMap(StringID internal_string_id, ScriptErrorType ai_error_msg);
 214
 215         /**
 216          * Map an internal OpenTTD error message to its script equivalent.
 217          * @api -all
 218          * @param ai_error_msg The script error message representation.
 219          * @param message The string representation of this error message, used for debug purposes.
 220          */
 221         static void RegisterErrorMapString(ScriptErrorType ai_error_msg, const char *message);
 222
 223 private:
 224         typedef std::map<StringID, ScriptErrorType> ScriptErrorMap;           ///< The type for mapping between error (internal OpenTTD) StringID to the script error type.
 225         typedef std::map<ScriptErrorType, const char *> ScriptErrorMapString; ///< The type for mapping between error type and textual representation.
 226
 227         static ScriptErrorMap error_map;              ///< The mapping between error (internal OpenTTD) StringID to the script error type.
 228         static ScriptErrorMapString error_map_string; ///< The mapping between error type and textual representation.
 229 };
 230
 231 #endif /* SCRIPT_ERROR_HPP */