The Battle for Wesnoth  1.17.0-dev
lua_jailbreak_exception.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2011 - 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 #pragma once
17 
18 /**
19  * Base class for exceptions that want to be thrown 'through' lua.
20  *
21  * Classes inheriting from this class need to use the @ref
22  * IMPLEMENT_LUA_JAILBREAK_EXCEPTION macro in the class definition.
23  */
25 {
26 public:
27  virtual ~lua_jailbreak_exception() noexcept {}
28 
29  /** Stores a copy the current exception to be rethrown. */
30  void store() const noexcept;
31 
32  /**
33  * Rethrows the stored exception.
34  *
35  * It is safe to call this function is no exception is stored.
36  */
37  static void rethrow();
38 
39 protected:
40 
41  /** The exception to be rethrown. */
43 
44 private:
45 
46  /** Clears the current exception. */
47  static void clear() noexcept;
48 
49  /**
50  * Creates a copy of the current exception.
51  *
52  * The copy is allocated with @p new and is implemented by the @ref
53  * IMPLEMENT_LUA_JAILBREAK_EXCEPTION macro.
54  *
55  * @note it's implemented by the subclass to avoid slicing.
56  *
57  * @returns A pointer to a copy of the class on the heap.
58  */
59  virtual lua_jailbreak_exception* clone() const = 0;
60 
61  /**
62  * Executes the exception.
63  *
64  * Throws a copy of the stored @ref jailbreak_exception. The caller is
65  * responsible for clearing @ref jailbreak_exception after the throw.
66  * The function is implemented by the @ref
67  * IMPLEMENT_LUA_JAILBREAK_EXCEPTION macro.
68  *
69  * @note it's implemented by the subclass to avoid slicing.
70  *
71  * @pre jailbreak_exception != nullptr
72  */
73  virtual void execute() = 0;
74 };
75 
76 /**
77  * Helper macro for classes deriving from @ref lua_jailbreak_exception.
78  *
79  * @ref lua_jailbreak_exception has several pure virtual functions, this
80  * macro implements them properly. This macro needs to be placed in the
81  * definition of the most derived class, which uses @ref
82  * lua_jailbreak_exception as baseclass.
83  *
84  * @param type The type of the class whc
85  */
86 #define IMPLEMENT_LUA_JAILBREAK_EXCEPTION(type) \
87  \
88  virtual type* clone() const { return new type(*this); } \
89  \
90  virtual void execute() \
91  { \
92  type exception(dynamic_cast<type&>(*jailbreak_exception)); \
93  throw exception; \
94  }
static void clear() noexcept
Clears the current exception.
static lua_jailbreak_exception * jailbreak_exception
The exception to be rethrown.
static void rethrow()
Rethrows the stored exception.
void store() const noexcept
Stores a copy the current exception to be rethrown.
virtual ~lua_jailbreak_exception() noexcept
virtual void execute()=0
Executes the exception.
virtual lua_jailbreak_exception * clone() const =0
Creates a copy of the current exception.
Base class for exceptions that want to be thrown &#39;through&#39; lua.