mxError.hpp

Go to the documentation of this file.

/** \file mxError.hpp
  * \author Jared R. Males (jaredmales@gmail.com)
  * \brief Declares and defines the mxlib error reporting system.
  * \ingroup error_handling_files
  * 
*/
 
//***********************************************************************//
// Copyright 2015, 2016, 2017 Jared R. Males (jaredmales@gmail.com)
//
// This file is part of mxlib.
//
// mxlib is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// mxlib 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.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with mxlib.  If not, see <http://www.gnu.org/licenses/>.
//***********************************************************************//
 
#ifndef __mxError__
#define __mxError__
 
#include <cerrno>
#include <cstring>
#include <sstream>
 
/** \addtogroup error_macros 
  * 
  * mxlib components use these macros to report errors to the user, which by default are wrappers for mx::error_report and mx::errno_report.
  * This behavior can be changed with preprocessor defines.
  * 
  * To completely suppress all mxlib error reporting, include the following before includng any mxlib headers
  * \code
  * #define MX_NO_ERROR_REPORTS
  * \endcode
  */
 
  /** \ingroup error_handling
  * @{
  */
 
/** \def MX_NO_ERROR_REPORTS
  * \brief If this is defined, then no errors are reported.
  * \ingroup error_macros
  */
#ifdef MX_NO_ERROR_REPORTS
 
//Just defining these as empty macros, though this is currently untested.
/** \todo test MX_NO_ERROR_REPORTS */
 
#define mxError(esrc,ecode,expl) 
#define mxPError(esrc,ecode,expl)
 
#else
 
 
#ifndef mxError
 
#include <iostream>
 
/** \def mxError
  * \brief This reports an mxlib specific error
  * 
  * Can be predefined to change the error reporting of mxlib.
  *
  * \param[in] esrc is intended to identify the component (i.e. the class name)
  * \param[in] ecode is an errno erro code
  * \param[in] expl [optional] if more information can be provided, use this to inform the user.
  * 
  * \ingroup error_macros
 */
#define mxError(esrc,ecode,expl) std::cerr << "\n" << mx::error_report(esrc, ecode, __FILE__, __LINE__, expl) << "\n";
 
#endif //mxError
 
#ifndef mxPError
 
/** \def mxPError
  * \brief This reports a standard library error, taking after perror.
  * 
  * Can be pre-defined to change the error reporting of mxlib.
  * 
  * \param[in] esrc is intended to identify the component (i.e. the class name)
  * \param[in] ecode is an errno erro code
  * \param[in] expl [optional] if more information can be provided, use this to inform the user.
  * 
  * \addtogroup error_macros
  */
#define mxPError(esrc,ecode,expl) std::cerr << "\n" << mx::errno_report(esrc, ecode, __FILE__, __LINE__, expl) << "\n";
 
 
#endif //mxPError
 
#endif //MX_NO_ERROR_REPORTS
 
/// @}
 
 
namespace mx
{
/** \defgroup mxe_errors mxlib Error Codes
  * \ingroup error_handling
  */  
 
/** \def MXE_INVALIDARG
  * \brief An argument was invalid.
  * \ingroup mxe_errors
  */   
#define MXE_INVALIDARG 25
#define MXE_INVALIDARG_NAME "MXE_INVALIDARG"
#define MXE_INVALIDARG_MSG "An argument was invalid."
 
/** \def MXE_INVALIDCONFIG
  * \brief A config setting was invalid.
  * \ingroup mxe_errors
  */   
#define MXE_INVALIDCONFIG 27
#define MXE_INVALIDCONFIG_NAME "MXE_INVALIDCONFIG"
#define MXE_INVALIDCONFIG_MSG "A config setting was invalid."
 
/** \def MXE_NOTIMPL
  * \brief A component or technique is not implemented.
  * \ingroup mxe_errors
  */   
#define MXE_NOTIMPL 30
#define MXE_NOTIMPL_NAME "MXE_NOTIMPL"
#define MXE_NOTIMPL_MSG "A component or technique is not implemented."
 
/** \def MXE_PARAMNOTSET
  * \brief A parameter was not set
  * \ingroup mxe_errors
  */   
#define MXE_PARAMNOTSET 35
#define MXE_PARAMNOTSET_NAME "MXE_PARAMNOTSET"
#define MXE_PARAMNOTSET_MSG "A parameter was not set."
 
/** \def MXE_ENVNOTSET
  * \brief An environment variable is not set
  * \ingroup mxe_errors
  */   
#define MXE_ENVNOTSET 36
#define MXE_ENVNOTSET_NAME "MXE_ENVNOTSET"
#define MXE_ENVNOTSET_MSG "An environment variable is not set."
 
/** \def MXE_NOTFOUND
  * \brief An item was not found
  * \ingroup mxe_errors
  */   
#define MXE_NOTFOUND 40
#define MXE_NOTFOUND_NAME "MXE_NOTFOUND"
#define MXE_NOTFOUND_MSG "An item was not found."
 
/** \def MXE_SIZEERR
  * \brief A size was invalid or calculated incorrectly
  * \ingroup mxe_errors
  */   
#define MXE_SIZEERR 55
#define MXE_SIZEERR_NAME "MXE_SIZEERR"
#define MXE_SIZEERR_MSG "A size was invalid or calculated incorrectly."
 
/** \def MXE_ALLOCERR
  * \brief An error occurred during memory allocation.
  * \ingroup mxe_errors
  */   
#define MXE_ALLOCERR 60
#define MXE_ALLOCERR_NAME "MXE_ALLOCERR"
#define MXE_ALLOCERR_MSG "An error occurred during memory allocation."
 
/** \def MXE_FREEERR
  * \brief An error occurred during memory de-allocation.
  * \ingroup mxe_errors
  */   
#define MXE_FREEERR 65
#define MXE_FREEERR_NAME "MXE_FREEERR"
#define MXE_FREEERR_MSG "An error occurred during memory de-allocation."
 
 
/** \def MXE_PARSEERR
  * \brief A parsing error occurred.
  * \ingroup mxe_errors
  */   
#define MXE_PARSEERR 75
#define MXE_PARSEERR_NAME "MXE_PARSEERR"
#define MXE_PARSEERR_MSG "A parsing error occurred."
 
 
/** \def MXE_FILEOERR
  * \brief An error occurred while opening a file.
  * \ingroup mxe_errors
  */   
#define MXE_FILEOERR 1034
#define MXE_FILEOERR_NAME "MXE_FILEOERR"
#define MXE_FILEOERR_MSG "An error occurred while opening a file."
 
/** \def MXE_FILEWERR
  * \brief An error occurred while writing to a file.
  * \ingroup mxe_errors
  */   
#define MXE_FILEWERR 1044
#define MXE_FILEWERR_NAME "MXE_FILEWERR"
#define MXE_FILEWERR_MSG "An error occurred while writing to a file."
 
/** \def MXE_FILERERR
  * \brief An error occurred while reading from a file.
  * \ingroup mxe_errors
  */   
#define MXE_FILERERR 1049
#define MXE_FILERERR_NAME "MXE_FILERERR"
#define MXE_FILERERR_MSG "An error occurred while reading from a file."
 
/** \def MXE_FILECERR
  * \brief An error occurred while closing a file.
  * \ingroup mxe_errors
  */   
#define MXE_FILECERR 1054
#define MXE_FILECERR_NAME "MXE_FILECERR"
#define MXE_FILECERR_MSG "An error occurred while closing a file."
 
/** \def MXE_FILENOTFOUND
  * \brief The file was not found.
  * \ingroup mxe_errors
  */   
#define MXE_FILENOTFOUND 1059
#define MXE_FILENOTFOUND_NAME "MXE_FILENOTFOUND"
#define MXE_FILENOTFOUND_MSG "The file was not found."
 
/** \def MXE_PROCERR
  * \brief An error occrred while starting a process.
  * \ingroup mxe_errors
  */   
#define MXE_PROCERR 2001
#define MXE_PROCERR_NAME "MXE_PROCERR"
#define MXE_PROCERR_MSG "An error occured while starting a process."
 
/** \def MXE_TIMEOUT
  * \brief A timeout occurred.
  * \ingroup mxe_errors
  */   
#define MXE_TIMEOUT 2322
#define MXE_TIMEOUT_NAME "MXE_TIMEOUT"
#define MXE_TIMEOUT_MSG "A timeout occurred."
 
/** \def MXE_LIBERR
  * \brief An error was returned by a library.
  * \ingroup mxe_errors
  */   
#define MXE_LIBERR 4000
#define MXE_LIBERR_NAME "MXE_LIBERR"
#define MXE_LIBERR_MSG "An error was returned by a library."
 
 
/** \def MXE_GNUPLOTERR
  * \brief An error was returned by gnuplot.
  * \ingroup mxe_errors
  */   
#define MXE_GNUPLOTERR 4567
#define MXE_GNUPLOTERR_NAME "MXE_GNUPLOTERR"
#define MXE_GNUPLOTERR_MSG "An error was returned by gnuplot."
 
/** \def MXE_LAPACKERR
  * \brief An error was returned by Lapack.
  * \ingroup mxe_errors
  */   
#define MXE_LAPACKERR 6890
#define MXE_LAPACKERR_NAME "MXE_LAPACKERR"
#define MXE_LAPACKERR_MSG "An error was returned by Lapack."
 
 
///Return the name for an mxlib error code
/**
  * 
  * \returns the name of the macro corresponding to the error code.
  * 
  * \ingroup error_handling
  */
std::string MXE_CodeToName( int ec /**< [in] the error code */ );
 
///Return the description for an mxlib error code
/**
  * 
  * \returns the description for and error code.
  * 
  * \ingroup error_handling
  */
std::string MXE_CodeToDescription( int ec /**< [in] the error code */ );
 
///Return the macro name and a message for a standard errno code
/**
  * 
  * \returns the name of the macro corresponding to the code.
  * 
  * \ingroup error_handling
  */
std::string errno_CodeToName( int ec /**< [in] the error code */ );
 
///Construct a rich error report given an mxlib error code
/**
  * 
  * \return the formatted error report.
  * 
  * \ingroup error_handling
  */ 
std::string error_report( const std::string & source,   ///< [in] is intended to identify the mxlib component (i.e. the class name)
                          const int & code,             ///< [in] is an MXE_* error code
                          const std::string & file,     ///< [in] should be passed the __FILE__ macro
                          const int & line,             ///< [in] should be passed the __LINE__ macro
                          const std::string & expl = "" ///< [in] [optional] if more information can be provided, use this to inform the user.
                        );
 
 
///Construct a rich error report given a standard errno error code
/**
  * \return the formatted error report.
  * 
  * \ingroup error_handling
  */ 
std::string errno_report( const std::string & source,   ///< [in] intended to identify the component (i.e. the class name)
                          int ec,                       ///< [in] an errno erro code
                          const std::string & file,     ///< [in] file should be passed the __FILE__ macro
                          const int & line,             ///< [in] line should be passed the __LINE__ macro
                          const std::string & expl = "" ///< [in] [optional] if more information can be provided, use this to inform the user.
                        );
 
 
 
 
 
 
} //namespace mx
 
#endif //__mxError__