The Battle for Wesnoth  1.13.11+dev
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
wml_exception.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2007 - 2018 by Mark de Wever <koraq@xs4all.nl>
3  Part of the Battle for Wesnoth Project http://www.wesnoth.org/
4 
5  This program is free software; you can redistribute it and/or modify
6  it under the terms of the GNU General Public License as published by
7  the Free Software Foundation; either version 2 of the License, or
8  (at your option) any later version.
9  This program is distributed in the hope that it will be useful,
10  but WITHOUT ANY WARRANTY.
11 
12  See the COPYING file for more details.
13 */
14 
15 /**
16  * @file
17  * Add a special kind of assert to validate whether the input from WML
18  * doesn't contain any problems that might crash the game.
19  */
20 
21 #pragma once
22 
23 #include "config.hpp"
25 
26 #include <string>
27 
28 /**
29  * The macro to use for the validation of WML
30  *
31  * @param cond The condition to test, if false and exception is generated.
32  * @param message The translatable message to show at the user.
33  */
34 #ifndef __func__
35  #ifdef __FUNCTION__
36  #define __func__ __FUNCTION__
37  #endif
38 #endif
39 
40 #define VALIDATE(cond, message) \
41  do { \
42  if(!(cond)) { \
43  throw_wml_exception(#cond, __FILE__, __LINE__, __func__, message); \
44  } \
45  } while(0)
46 
47 #define VALIDATE_WITH_DEV_MESSAGE(cond, message, dev_message) \
48  do { \
49  if(!(cond)) { \
50  throw_wml_exception(#cond \
51  , __FILE__ \
52  , __LINE__ \
53  , __func__ \
54  , message \
55  , dev_message); \
56  } \
57  } while(0)
58 
59 #define FAIL(message) \
60  do { \
61  throw_wml_exception(nullptr, __FILE__, __LINE__, __func__, message); \
62  } while(0)
63 
64 #define FAIL_WITH_DEV_MESSAGE(message, dev_message) \
65  do { \
66  throw_wml_exception(nullptr \
67  , __FILE__ \
68  , __LINE__ \
69  , __func__ \
70  , message \
71  , dev_message); \
72  } while(0)
73 
74 /**
75  * Helper function, don't call this directly.
76  *
77  * @param cond The textual presentation of the test that failed.
78  * @param file The file in which the test failed.
79  * @param line The line at which the test failed.
80  * @param function The function in which the test failed.
81  * @param message The translated message to show the user.
82  */
83 NORETURN void throw_wml_exception(
84  const char* cond
85  , const char* file
86  , int line
87  , const char *function
88  , const std::string& message
89  , const std::string& dev_message = "");
90 
91 /** Helper class, don't construct this directly. */
94 {
95  wml_exception(const std::string& user_msg, const std::string& dev_msg)
96  : user_message(user_msg)
97  , dev_message(dev_msg)
98  {
99  }
100 
101  ~wml_exception() NOEXCEPT {}
102 
103  /**
104  * The message for the user explaining what went wrong. This message can
105  * be translated so the user gets a explanation in his/her native tongue.
106  */
108 
109  /**
110  * The message for developers telling which problem was triggered, this
111  * shouldn't be translated. It's hard for a dev to parse errors in
112  * foreign tongues.
113  */
115 
116  /**
117  * Shows the error in a dialog.
118  */
119  void show();
120 private:
122 };
123 
124 /**
125  * Returns a standard message for a missing wml key.
126  *
127  * @param section The section is which the key should appear
128  * (this should include the section brackets).
129  * It may contain parent sections to make it
130  * easier to find the wanted sections. They are
131  * listed like [parent][child][section].
132  * @param key The omitted key.
133  * @param primary_key The primary key of the section.
134  * @param primary_value The value of the primary key (mandatory if
135  * primary key isn't empty).
136  *
137  * @returns The error message.
138  */
140  const std::string& section
141  , const std::string& key
142  , const std::string& primary_key = ""
143  , const std::string& primary_value = "");
144 /**
145  * Returns a standard warning message for using a deprecated wml key.
146  *
147  * @param key The deprecated key.
148  * @param removal_version The version in which the key will be
149  * removed key.
150  *
151  * @returns The warning message.
152  */
154  const std::string& key
155  , const std::string& removal_version);
156 
157 /**
158  * Returns a standard warning message for using a deprecated renamed wml key.
159  *
160  * @param deprecated_key The deprecated key.
161  * @param key The new key to be used.
162  * @param removal_version The version in which the key will be
163  * removed key.
164  *
165  * @returns The warning message.
166  */
168  const std::string& deprecated_key
169  , const std::string& key
170  , const std::string& removal_version);
171 
172 /**
173  * Returns a config attribute, using either the old name or the new one.
174  *
175  * The function first tries the find the attribute using @p key and if that
176  * doesn't find the attribute it tries @p deprecated_key. If that test finds
177  * an attribute it will issue a warning and return the result. Else returns
178  * an empty attribute.
179  *
180  * @note This function is not a member of @ref config, since that would add
181  * additional dependencies to the core library.
182  *
183  * @param cfg The config to get the attribute from.
184  * @param deprecated_key The deprecated key.
185  * @param key The new key to be used.
186  * @param removal_version The version in which the key will be
187  * removed key.
188  *
189  * @returns The attribute found as described above.
190  */
192  const config& cfg
193  , const std::string& deprecated_key
194  , const std::string& key
195  , const std::string& removal_version);
std::vector< char_t > string
#define IMPLEMENT_LUA_JAILBREAK_EXCEPTION(type)
Helper macro for classes deriving from lua_jailbreak_exception.
Variant for storing WML attributes.
~wml_exception() NOEXCEPT
std::string deprecate_wml_key_warning(const std::string &key, const std::string &removal_version)
Returns a standard warning message for using a deprecated wml key.
std::string user_message
The message for the user explaining what went wrong.
Definitions for the interface to Wesnoth Markup Language (WML).
const config::attribute_value & get_renamed_config_attribute(const config &cfg, const std::string &deprecated_key, const std::string &key, const std::string &removal_version)
Returns a config attribute, using either the old name or the new one.
std::string deprecated_renamed_wml_key_warning(const std::string &deprecated_key, const std::string &key, const std::string &removal_version)
Returns a standard warning message for using a deprecated renamed wml key.
wml_exception(const std::string &user_msg, const std::string &dev_msg)
void show()
Shows the error in a dialog.
Helper class, don't construct this directly.
std::string dev_message
The message for developers telling which problem was triggered, this shouldn't be translated...
NORETURN void throw_wml_exception(const char *cond, const char *file, int line, const char *function, const std::string &message, const std::string &dev_message="")
Helper function, don't call this directly.
static int cond(LexState *ls)
Definition: lparser.cpp:1177
A config object defines a single node in a WML file, with access to child nodes.
Definition: config.hpp:93
std::string missing_mandatory_wml_key(const std::string &section, const std::string &key, const std::string &primary_key="", const std::string &primary_value="")
Returns a standard message for a missing wml key.
Base class for exceptions that want to be thrown 'through' lua.