The Battle for Wesnoth  1.15.12+dev
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 https://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(false)
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(false)
58 
59 #define FAIL(message) \
60  do { \
61  throw_wml_exception(nullptr, __FILE__, __LINE__, __func__, message); \
62  } while(false)
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(false)
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  * @param dev_message Any additional information that might be useful to a developer.
83  */
84 [[noreturn]] void throw_wml_exception(
85  const char* cond
86  , const char* file
87  , int line
88  , const char *function
89  , const std::string& message
90  , const std::string& dev_message = "");
91 
92 /** Helper class, don't construct this directly. */
95 {
96  wml_exception(const std::string& user_msg, const std::string& dev_msg)
97  : user_message(user_msg)
98  , dev_message(dev_msg)
99  {
100  }
101 
102  ~wml_exception() noexcept {}
103 
104  /**
105  * The message for the user explaining what went wrong. This message can
106  * be translated so the user gets a explanation in his/her native tongue.
107  */
108  std::string user_message;
109 
110  /**
111  * The message for developers telling which problem was triggered, this
112  * shouldn't be translated. It's hard for a dev to parse errors in
113  * foreign tongues.
114  */
115  std::string dev_message;
116 
117  /**
118  * Shows the error in a dialog.
119  */
120  void show() const;
121 private:
123 };
124 
125 /**
126  * Returns a standard message for a missing wml key.
127  *
128  * @param section The section is which the key should appear
129  * (this should include the section brackets).
130  * It may contain parent sections to make it
131  * easier to find the wanted sections. They are
132  * listed like [parent][child][section].
133  * @param key The omitted key.
134  * @param primary_key The primary key of the section.
135  * @param primary_value The value of the primary key (mandatory if
136  * primary key isn't empty).
137  *
138  * @returns The error message.
139  */
140 std::string missing_mandatory_wml_key(
141  const std::string& section
142  , const std::string& key
143  , const std::string& primary_key = ""
144  , const std::string& primary_value = "");
145 
146 // TODO: In 1.15 we could rework these two to provide standard detail messages
147 // for the deprecated_message() function.
148 
149 /**
150  * Returns a standard warning message for using a deprecated wml key.
151  *
152  * @param key The deprecated key.
153  * @param removal_version The version in which the key will be removed.
154  *
155  * @returns The warning message.
156  */
157 std::string deprecate_wml_key_warning(
158  const std::string& key
159  , const std::string& removal_version);
160 
161 /**
162  * Returns a standard warning message for using a deprecated renamed wml key.
163  *
164  * @param deprecated_key The deprecated key.
165  * @param key The new key to be used.
166  * @param removal_version The version in which the key will be removed.
167  *
168  * @returns The warning message.
169  */
171  const std::string& deprecated_key
172  , const std::string& key
173  , const std::string& removal_version);
174 
175 /**
176  * Returns a config attribute, using either the old name or the new one.
177  *
178  * The function first tries the find the attribute using @p key and if that
179  * doesn't find the attribute it tries @p deprecated_key. If that test finds
180  * an attribute it will issue a warning and return the result. Else returns
181  * an empty attribute.
182  *
183  * @note This function is not a member of @ref config, since that would add
184  * additional dependencies to the core library.
185  *
186  * @param cfg The config to get the attribute from.
187  * @param deprecated_key The deprecated key.
188  * @param key The new key to be used.
189  * @param removal_version The version in which the key will be
190  * removed key.
191  *
192  * @returns The attribute found as described above.
193  */
195  const config& cfg
196  , const std::string& deprecated_key
197  , const std::string& key
198  , 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:59
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.