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