src/exceptions/base.hpp

   1 /*
   2 Copyright © 2008 Kővágó Zoltán <DirtY.iCE.hu@gmail.com>
   3
   4 This program is free software; you can redistribute it and/or
   5 modify it under the terms of the GNU General Public License
   6 as published by the Free Software Foundation; either version 2
   7 of the License, or (at your option) any later version.
   8
   9 This program is distributed in the hope that it will be useful,
  10 but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  12
  13 See the GNU General Public License for more details.
  14
  15 You should have received a copy of the GNU General Public License
  16 along with this program; if not, write to the Free Software
  17 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  18
  19 */
  20
  21 /**
  22  * @file exceptions/base.hpp
  23  * Base header of DBW exceptions
  24  */
  25
  26 #ifndef EXCEPTIONS__BASE_HPP
  27 #define EXCEPTIONS__BASE_HPP
  28
  29 #include <iostream>
  30 #include <map>
  31 #include <sstream>
  32
  33 /**
  34  * All exception and related stuff should go into this namespace.
  35  */
  36 namespace Exception
  37 {
  38
  39 /**
  40  * Base exception class. All exceptions inside DBW should derived from this class.
  41  */
  42 class Base : public std::exception
  43 {
  44         public:
  45                 /**
  46                  * Default constructor constructing an exception with an empty info map.
  47                  * @param[in] file In what file did the exception occur
  48                  * @param[in] line Inside the file, what line.
  49                  * @param[in] function The name of the function (<dfn>__PRETTY_FUNCTION__</dfn>)
  50                  * @param[in]what A human-readable description of the exception.
  51                  */
  52                 Base(const std::string& file, const unsigned short line, const std::string& function, const std::string& what) throw() : line(line), file(file), function(function), what_(what), info() {};
  53
  54                 /// Odd, but std::exception needs it
  55                 virtual ~Base() throw() {}
  56
  57                 /// @return The value of \ref what field
  58                 std::string GetWhat() const throw() { return what_; };
  59                 /// @return A pretty text about where and what occured, also listing the info
  60                 std::string GetDesc() const throw()
  61                 {
  62                         std::stringstream str;
  63                         str << "Exception @ " << file << ":" << line << std::endl
  64                                 << "In function " << function << " :" << std::endl
  65                                 << what_ << std::endl;
  66
  67                         for (std::map<std::string, std::string>::const_iterator iter = info.begin(); iter != info.end(); iter++)
  68                         {
  69                                 str << std::endl << iter->first << ": " << iter->second;
  70                         }
  71
  72                         return str.str();
  73                 }
  74
  75                 /// Compatibility with std::exception
  76                 inline const char* what() const throw() { return GetDesc().c_str(); }
  77
  78                 /**
  79                  * Adds some info to the map.
  80                  * @param[in] name The name of the key
  81                  * @param[in] value The value of the key (the info)
  82                  */
  83                 void AddInfo(std::string name, std::string value) throw() { info[name] = value; }
  84
  85         protected:
  86
  87                 unsigned short line;   ///< The number of line on the exception occured
  88
  89                 std::string file,      ///< The name of the file in the exception occured
  90                             function,  ///< The name of the function in the exception occured (<dfn>__PRETTY_FUNCTION__</dfn>)
  91                             what_;     ///< The description of the exception
  92
  93                 /// A map storing adittional informations.
  94                 std::map<std::string, std::string> info;
  95 };
  96
  97 /**
  98  * A utility macro to define an exception quickly.
  99  * @param name The name of the exception.
 100  * @param desc The description of the exception (<b>what</b> parameter of Base::Base()
 101  */
 102 #define DEF_EXCEPTION(name, desc)                                                                                                    \
 103         class name : public Base                                                                                                         \
 104         {                                                                                                                                \
 105                 public:                                                                                                                      \
 106                         /**                                                                                                                      \
 107                          * Default constructor constructing an exception with an empty info map.                                                 \
 108                          * @param[in] file In what file did the exception occur                                                                  \
 109                          * @param[in] line Inside the file, what line.                                                                           \
 110                          * @param[in] function The name of the function (<dfn>__PRETTY_FUNCTION__</dfn>)                                         \
 111                          */                                                                                                                      \
 112                 name(const std::string& file, const unsigned short line, const std::string& func) throw() : Base(file, line, func, desc) {}; \
 113         }
 114
 115 /// A shorthand for the three parameters of exception (file, line, function)
 116 #define AT __FILE__ + 7, __LINE__, __PRETTY_FUNCTION__
 117 //#define VAR(var) #var, boost::lexical_cast<std::string>(var)
 118
 119 /**
 120  * An exception throwed when control flows to a section where it shouldn't.
 121  *
 122  * Many apps uses <code>assert(NULL);</code> for this; some, like <a
 123  * href="http://www.openttd.org/">OpenTTD</a> hides it into a
 124  * <dfn>NOT_REACHED()</dfn> macro. But we have a complete class for it ;)
 125  *
 126  * Some example of use: into the <dfn>default:</dfn> part of a switch (when it's
 127  * not the way of the normal running, of course), stub functions, and maybe some
 128  * quick checks, but mostly it's better to use assert() for it..
 129  */
 130 DEF_EXCEPTION(NotReachedException, "Run flow to a section where it shouldn't go.");
 131
 132 /// Throws a NotReachedException without a description
 133 #define NOT_REACHED() throw NotReachedException(AT);
 134 /**
 135  * Throws a NotReachedException with adding a descreption.
 136  * @param[in] desc A description of the exception
 137  */
 138 #define NOT_REACHED_DESC(desc) { NotReachedException e(AT); e.AddInfo("details", desc); throw e; }
 139
 140 /**
 141  * An exception throwed when an assert() command fails.
 142  *
 143  * Assert command fails when it's expression is evaluates to NULL, making it ideal
 144  * for checking pointers, but it's usuable for almost everithing.
 145  */
 146 DEF_EXCEPTION(AssertionFailure, "Assertion failure");
 147
 148 // undefine standard c library's assert..
 149 #undef assert
 150
 151 /**
 152  * Throws an AssertionFailure when the expression evaluates to NULL.
 153  * @param x The expression to check.
 154  */
 155 #define assert(x) DoAssert((x), #x, AT)
 156
 157 /**
 158  * The function that does the real checking. <b>NEVER CALL THIS FUNCTION
 159  * DIRECTLY!</b> Use the assert() macro instead.
 160  * @param assertion The value of the expression
 161  * @param expr A string containing the expression
 162  * @param file Which file
 163  * @param line Which line
 164  * @param function Which function
 165  */
 166 static void inline DoAssert(int assertion, const std::string& expr, const std::string& file, const unsigned short line, const std::string& function) throw(AssertionFailure)
 167 {
 168         if (!assertion)
 169         {
 170                 AssertionFailure fail(file, line, function);
 171                 fail.AddInfo("Expression", expr);
 172                 throw fail;
 173         }
 174 }
 175
 176 /// An exception similar to std::runtime_error
 177 class RuntimeError : public Base
 178 {
 179         public:
 180                 /**
 181                  * Default constructor constructing an exception with an empty info map.
 182                  * @param[in] desc Description of the exception
 183                  * @param[in] file In what file did the exception occur
 184                  * @param[in] line Inside the file, what line.
 185                  * @param[in] function The name of the function (<dfn>__PRETTY_FUNCTION__</dfn>)
 186                  */
 187                 RuntimeError(const std::string& desc, const std::string& file, const unsigned short line, const std::string& func) throw() : Base(file, line, func, desc) {};
 188 };
 189
 190 } //namespace Exception
 191
 192 #endif //EXCEPTIONS__BASE_HPP