include/EDoc/exceptions.h

Go to the documentation of this file.

/*******************************************************************************

   Copyright (C) 2007 by Brendon Costa

   This library is free software; you can redistribute it and/or modify 
   it under the terms of the "LGPL Like" License defined in the file COPYING 
   that should have been distributed along with this source.

   This library is distributed in the hope that it will be useful, 
   but WITHOUT ANY WARRANTY; without even the implied warranty of 
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  

   You should have received a copy of the "LGPL Like" License 
   along with this library; see the file COPYING. if not, it can be 
   obtained from the EDoc++ website: 
   http://edoc.sourceforge.net/license.html

*******************************************************************************/
#ifndef EDOC_EXCEPTIONS_H
#define EDOC_EXCEPTIONS_H

/** \file EDoc/exceptions.h This file contains definitions for all exception 
 * objects that may be thrown by objects in the EDoc namespace.
 */


#include <string>
#include <sstream>
#include <exception>

#include "EDoc/Logger.h"

//==============================================================================
/** \brief Gathers the current file name and line number to give to an exception
 * object upon construction.
 */
#define EDOC_THROW_DATA __FILE__, __LINE__


//==============================================================================
/** \brief Use this macro to simplify throwing of all exceptions.
 *
 * This will gather source information like file name and line number, along
 * with allowing the user to specify additional debug information to a string
 * stream when throwing an exception.
 *
 * It is used like:
 * \code
 *    ...
 *    EDOC_THROW_EXCEPTION(MergeException, strerror(errno), 
 *       "More detailed developer message. Data: " << data);
 * \endcode
 */
#define EDOC_THROW_EXCEPTION(ExceptionType, UserMessage, DevMessage) \
{ \
   std::ostringstream stream_kjhgbvk791; \
   std::ostringstream stream_kjhgbvk792; \
   stream_kjhgbvk791 << UserMessage; \
   stream_kjhgbvk792 << DevMessage; \
   throw ExceptionType (EDOC_THROW_DATA, stream_kjhgbvk791.str(), \
      stream_kjhgbvk792.str()); \
}

//==============================================================================
/** \brief An assertion statement that will throw an exception of type
 * BugException if the assertion fails.
 *
 * The BugException is not supposed to be caught except in the main() function.
 */
#define EDOC_ASSERT(Condition, Message) \
{ \
   if (!(Condition)) \
   { \
      EDOC_Fatal("Assertion failure. \"" << #Condition << "\"" \
         << " : " << Message); \
      EDOC_THROW_EXCEPTION(::EDoc::BugException, "Assertion failure.", \
         #Condition << " : " << Message); \
   } \
   else \
   { \
      EDOC_Finest("Assertion success. \"" << #Condition << "\""); \
   } \
}


//==============================================================================
/** \brief Macro defined to simply create a new exception type.
 *
 * This can be used for creating simple exception types that have the standard
 * functionality of the EDoc::Throwable type. 
 *
 * \param NewExceptionType The name of the new exception type to create.
 *
 * \param BaseExceptionType The name of the exception type that the new one will
 * derive from.
 */
#define EDOC_NEW_EXCEPTION(NewExceptionType, BaseExceptionType) \
   class NewExceptionType : public BaseExceptionType \
   { \
   public: \
      NewExceptionType(const char* type_name_in,\
            const char* file_in, \
            int line_in,  \
            std::string user_message_in = "", \
            std::string dev_message_in = "") : \
         \
         BaseExceptionType(type_name_in, file_in, line_in, user_message_in, \
            dev_message_in) \
      { \
      } \
      \
      NewExceptionType(const char* file_in, \
            int line_in,  \
            std::string user_message_in = "", \
            std::string dev_message_in = "") : \
         \
         BaseExceptionType(#NewExceptionType, file_in, line_in, \
            user_message_in, dev_message_in) \
      { \
      } \
   };   

namespace EDoc
{
   //===========================================================================
   /** \brief Base class from which all EDoc exception types will derive.
    *
    * This provides some simple functionality for useful exception objects.
    */
   class Throwable : public std::exception
   {
   public:

      //------------------------------------------------------------------------
      /** \brief Expected to be created in a throw statement.
       *
       * This provides a good representation of an error that provides enough
       * information that can be used to help debug problems and also to provide
       * succint useful information to a user when an error occurs.
       *
       * \param type_name_in This is the name of the exception type being
       * thrown.
       *
       * \param file_in The name of the source file from where the exception is
       * being thrown.
       *
       * \param line_in The line of the source file from where the exception is
       * being thrown.
       *
       * \param user_message_in A string that should be displayed to a user
       * describing succintly the error that occured.
       *
       * \param dev_message_in A more detailed message describing a bit of the
       * state information that may have caused the error to occur.
       */
      Throwable(const char* type_name_in,
            const char* file_in, 
            int line_in, 
            std::string user_message_in = "",
            std::string dev_message_in = "");

      //------------------------------------------------------------------------
      /** \brief Destructor.
       */
      virtual ~Throwable() throw() {}

      //------------------------------------------------------------------------
      /** \brief Return a string of information so that this can be used as a 
       * std::exception instance.
       */
      virtual const char* what() const throw();

      //------------------------------------------------------------------------
      /** \brief Returns the name of the type of exception that was thrown.
       */
      std::string GetType() const;
      
      //------------------------------------------------------------------------
      /** \brief Returns the name of the source file from where the exception
       * was thrown.
       */
      std::string GetFile() const;

      //------------------------------------------------------------------------
      /** \brief Returns the line number of the source file from where the
       * exception was thrown.
       */
      int GetLine() const;

      //------------------------------------------------------------------------
      /** \brief Returns the succinct message describing the error for the user.
       */
      std::string GetUserMessage() const;

      //------------------------------------------------------------------------
      /** \brief Returns the more detailed message describing the error for a
       * developer.
       */
      std::string GetDevMessage() const;

      //------------------------------------------------------------------------

   private:

      //------------------------------------------------------------------------
      /** \brief See GetType()
       */
      std::string type_name;

      //------------------------------------------------------------------------
      /** \brief See GetFile()
       */
      std::string file;

      //------------------------------------------------------------------------
      /** \brief See GetLine()
       */
      int line;

      //------------------------------------------------------------------------
      /** \brief See GetUserMessage()
       */
      std::string user_message;

      //------------------------------------------------------------------------
      /** \brief See GetDevMessage()
       */
      std::string dev_message;

      //------------------------------------------------------------------------
      /** \brief A string that contains all the information for this exception
       * in a single string. This is used by the what() function.
       *
       * NOTE: It is not a good format to display to the user.
       */
      std::string detailed_message;

      //------------------------------------------------------------------------
   };
   //===========================================================================


//==============================================================================
// Define a number of Exception types for use in EDoc.
//==============================================================================
EDOC_NEW_EXCEPTION(BugException, Throwable)
EDOC_NEW_EXCEPTION(BaseException, Throwable)
EDOC_NEW_EXCEPTION(MergeException, BaseException)
EDOC_NEW_EXCEPTION(PythonException, BaseException)
EDOC_NEW_EXCEPTION(FileIOException, BaseException)
EDOC_NEW_EXCEPTION(EOFException, FileIOException)
EDOC_NEW_EXCEPTION(UnknownFileTypeException, FileIOException)

}

#endif // EDOC_EXCEPTIONS_H

---