Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: code/trunk/src/libraries/util/Exception.h @ 9737

Last change on this file since 9737 was 8858, checked in by landauf, 13 years ago

merged output branch back to trunk.

Changes:

  • you have to include util/Output.h instead of util/Debug.h
  • COUT(x) is now called orxout(level)
  • output levels are now defined by an enum instead of numbers. see util/Output.h for the definition
  • it's possible to use output contexts with orxout(level, context). see util/Output.h for some common contexts. you can define more contexts
  • you must use 'endl' at the end of an output message, '\n' does not flush the message

Output levels:

  • instead of COUT(0) use orxout()
  • instead of COUT(1) use orxout(user_error) or orxout(internal_error)
  • instead of COUT(2) use orxout(user_warning) or orxout(internal_warning)
  • instead of COUT(3) use orxout(user_status/user_info) or orxout(internal_status/internal_info)
  • instead of COUT(4) use orxout(verbose)
  • instead of COUT(5) use orxout(verbose_more)
  • instead of COUT(6) use orxout(verbose_ultra)

Guidelines:

  • user_* levels are for the user, visible in the console and the log-file
  • internal_* levels are for developers, visible in the log-file
  • verbose_* levels are for debugging, only visible if the context of the output is activated

Usage in C++:

  • orxout() << "message" << endl;
  • orxout(level) << "message" << endl;
  • orxout(level, context) << "message" << endl;

Usage in Lua:

  • orxout("message")
  • orxout(orxonox.level.levelname, "message")
  • orxout(orxonox.level.levelname, "context", "message")

Usage in Tcl (and in the in-game-console):

  • orxout levelname message
  • orxout_context levelname context message
  • shortcuts: log message, error message, warning message, status message, info message, debug message
  • Property svn:eol-style set to native
File size: 8.4 KB
Line 
1/*
2 *   ORXONOX - the hottest 3D action shooter ever to exist
3 *                    > www.orxonox.net <
4 *
5 *
6 *   License notice:
7 *
8 *   This program is free software; you can redistribute it and/or
9 *   modify it under the terms of the GNU General Public License
10 *   as published by the Free Software Foundation; either version 2
11 *   of the License, or (at your option) any later version.
12 *
13 *   This program is distributed in the hope that it will be useful,
14 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
15 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16 *   GNU General Public License for more details.
17 *
18 *   You should have received a copy of the GNU General Public License
19 *   along with this program; if not, write to the Free Software
20 *   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
21 *
22 *   Author:
23 *      Reto Grieder
24 *   Co-authors:
25 *      ...
26 *
27 */
28
29/**
30    @defgroup ExceptionAssertion Exceptions and assertions
31    @ingroup Util
32*/
33
34/**
35@file
36@ingroup ExceptionAssertion
37@brief
38    Declaration of facilities to handle exceptions.
39@details
40    Any exception thrown should inherit from orxonox::Exception. There is a macro
41    \ref CREATE_ORXONOX_EXCEPTION to create a new exception (you can find a list of
42    available exceptions in the docs of this file). <br>
43    Throwing exception is also very simple:
44    @code
45        ThrowException(General, "Something went wrong");
46    @endcode
47    (\c General is a type of exception, see docs of this file) <br>
48    The exception will automatically contain information about file, line number
49    and function name it occurred in. <br><br>
50    There is also some magic you can do for numbers, etc.:
51    @code
52        ThrowException(General, "Error code: " << myInt << ". more info...");
53    @endcode
54    It works with an std::ostringstream, so you can feed it all sorts of values.
55*/
56
57#ifndef _Exception_H__
58#define _Exception_H__
59
60#include "UtilPrereqs.h"
61
62#include <exception>
63#include <sstream>
64#include <string>
65#include "Output.h"
66
67namespace orxonox
68{
69    /** Base class for all exceptions (derived from std::exception).
70    @details
71        This class provides support for information about the file, the line
72        and the function the error occurred.
73    @see Exception.h
74    */
75    class _UtilExport Exception : public std::exception
76    {
77    public:
78        /**
79        @brief
80            Creates the exception but doesn't yet compose the full descrption (because of the virtual functions)
81        @param description
82            Exception description as string. This message is supposed to help developers!
83        @param lineNumber
84            The number of the code-line in which the exception occurred
85        @param filename
86            The file in which the exception occurred
87        @param functionName
88            The function in which the exception occurred
89        */
90        Exception(const std::string& description, unsigned int lineNumber,
91                  const char* filename, const char* functionName);
92        //! Simplified constructor with just a description. If you need more, use the other one.
93        Exception(const std::string& description);
94
95        //! Needed for compatibility with std::exception
96        virtual ~Exception() throw() { }
97        //! Returns the error description
98        const char* what() const throw();
99
100        /** Returns a full description with type, line, file and function
101        @remarks
102            The composed full description gets stored to fullDescription_. But for compliance
103            with std::exception, this method has to be const. Hence fullDescription_ is declared
104            as mutable.
105        */
106        virtual const std::string& getFullDescription() const;
107        //! Returns the string name of the exception type
108        virtual std::string        getTypeName()        const = 0;
109        //! Returns the short developer written exception
110        virtual const std::string& getDescription()     const { return this->description_; }
111        //! Returns the line number on which the exception occurred.
112        virtual unsigned int getLineNumber()            const { return this->lineNumber_; }
113        //! Returns the function in which the exception occurred.
114        virtual const std::string& getFunctionName()    const { return this->functionName_; }
115        //! Returns the filename in which the exception occurred.
116        virtual const std::string& getFilename()        const { return this->filename_; }
117
118        /**
119        @brief
120            Retrieves information from an exception caught with "..."
121            Works for std::exception and CEGUI::Exception
122        @remarks
123            Never ever call this function without an exception in the stack!
124        */
125        static std::string handleMessage();
126
127    protected:
128        std::string description_;             //!< User typed text about why the exception occurred
129        unsigned int lineNumber_;             //!< Line on which the exception occurred
130        std::string functionName_;            //!< Function (including namespace and class) where the exception occurred
131        std::string filename_;                //!< File where the exception occurred
132        // mutable because "what()" is a const method
133        mutable std::string fullDescription_; //!< Full description with line, file and function
134    };
135
136//! Creates a new type of exception that inherits from orxonox::Exception
137#define CREATE_ORXONOX_EXCEPTION(ExceptionName)                                     \
138    class ExceptionName##Exception : public Exception                               \
139    {                                                                               \
140    public:                                                                         \
141        ExceptionName##Exception(const std::string& description,                    \
142                unsigned int lineNumber, const char* filename,                      \
143                const char* functionName)                                           \
144            : Exception(description, lineNumber, filename, functionName)            \
145        { }                                                                         \
146                                                                                    \
147        ExceptionName##Exception(const std::string& description)                    \
148            : Exception(description)                                                \
149        { }                                                                         \
150                                                                                    \
151        ~ExceptionName##Exception() throw() { }                                     \
152                                                                                    \
153        std::string getTypeName() const { return #ExceptionName; }                  \
154    }
155
156    // Creates all possible exception types.
157    // If you want to add a new type, simply copy and adjust a new line here.
158    CREATE_ORXONOX_EXCEPTION(General);
159    CREATE_ORXONOX_EXCEPTION(FileNotFound);
160    CREATE_ORXONOX_EXCEPTION(Argument);
161    CREATE_ORXONOX_EXCEPTION(PhysicsViolation);
162    CREATE_ORXONOX_EXCEPTION(ParseError);
163    CREATE_ORXONOX_EXCEPTION(PluginsNotFound);
164    CREATE_ORXONOX_EXCEPTION(InitialisationFailed);
165    CREATE_ORXONOX_EXCEPTION(InitialisationAborted);
166    CREATE_ORXONOX_EXCEPTION(NotImplemented);
167    CREATE_ORXONOX_EXCEPTION(GameState);
168    CREATE_ORXONOX_EXCEPTION(NoGraphics);
169    CREATE_ORXONOX_EXCEPTION(AbortLoading);
170
171    /** Helper function that forwards an exception and displays the message.
172    @details
173        This is necessary because only when using 'throw' the objects storage is managed.
174    */
175    template <class T>
176    inline const T& exceptionThrowerHelper(const T& exception)
177    {
178        // let the catcher decide whether to display the message also to the user
179        orxout(internal_error) << exception.getFullDescription() << endl;
180        return exception;
181    }
182
183/** Throws an exception and logs a message beforehand.
184@param type
185    Type of the exception as literal (General, Initialisation, etc.)
186@param description
187    Exception description as string
188@see Exception.h
189*/
190#define ThrowException(type, description) \
191    throw orxonox::exceptionThrowerHelper(type##Exception(static_cast<std::ostringstream&>(std::ostringstream().flush() << description).str(), __LINE__, __FILE__, __FUNCTIONNAME__))
192
193} /* namespace orxonox */
194
195#endif /* _Exception_H__ */
Note: See TracBrowser for help on using the repository browser.