src/openbabel/oberror.hpp

/**********************************************************************
oberror.h - Handle error messages, warnings, notices, etc.
 
Copyright (C) 2002 by Stefan Kebekus
Some portions Copyright (C) 2003-2005 by Geoffrey R. Hutchison
 
This file is part of the Open Babel project.
For more information, see <http://openbabel.sourceforge.net/>
 
This program 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 version 2 of the License.
 
This program 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.
***********************************************************************/

#ifndef OB_ERROR_H
#define OB_ERROR_H

#include "config.h"

#ifndef EXTERN
#  define EXTERN extern
#endif

#if HAVE_IOSTREAM
#include <iostream>
#elif HAVE_IOSTREAM_H
#include <iostream.h>
#endif
#if HAVE_SSTREAM
        #include <sstream>
#elif
        #include <sstream.h>
#endif
#include <string>
#include <vector>
#include <deque>

namespace OpenBabel
{

//! \brief Levels of error and audit messages to allow filtering
enum obMessageLevel {
   obError,     //!< for critical errors (e.g., cannot read a file)
   obWarning,   //!< for non-critical problems (e.g., molecule appears empty)
   obInfo,      //!< for informative messages (e.g., file is a non-standard format)
   obAuditMsg,  //!< for messages auditing methods which destroy or perceive molecular data (e.g., kekulization, atom typing, etc.)
   obDebug      //!< for messages only useful for debugging purposes
};

//! \brief Customizable error handling and logging -- store a message,
//!        including the method yielding the error, causes, etc.
class OBAPI OBError
{
public:

  //! Constructor for an error message e.g. OBError(__FUNCTION__, " message ")
  OBError( const std::string &method = "",
           const std::string &errorMsg = "",
           const std::string &explanation = "",
           const std::string &possibleCause = "",
           const std::string &suggestedRemedy = "",
           const obMessageLevel = obDebug );

  //! \return a formatted message string, including optional explanations, etc.
  std::string message(void) const;
  
  //! Output a formatted message string
  friend std::ostream& operator<< ( std::ostream &os, const OBError &er )
    { return os << er.message(); };

  std::string    GetMethod()            { return _method;          }
  std::string    GetError()             { return _errorMsg;        }
  std::string    GetExplanation()       { return _explanation;     }
  std::string    GetPossibleCause()     { return _possibleCause;   }
  std::string    GetSuggestedRemedy()   { return _suggestedRemedy; }
  obMessageLevel GetLevel()             { return _level;           }

 protected:

    std::string _method;
    std::string _errorMsg;
    std::string _explanation;
    std::string _possibleCause;
    std::string _suggestedRemedy;

    obMessageLevel _level;
};

 //! \brief Handle error messages, warnings, debugging information and the like
class OBAPI OBMessageHandler
  {
  public:
    OBMessageHandler();
    ~OBMessageHandler();
    
    //! Throw an error with an already-formatted OBError object
    void ThrowError(OBError err);
    //! Throw an error in the specified method with an appropriate level
    void ThrowError(const std::string &method, const std::string &errorMsg, 
                    obMessageLevel level = obDebug);

    //! \return all messages matching a specified level
    std::vector<std::string> GetMessagesOfLevel(const obMessageLevel);

    //! Start logging messages (default)
    void StartLogging() { _logging = true; }
    //! Stop logging messages completely
    void StopLogging()  { _logging = false; }

    //! Set the maximum number of entries (or 0 for no limit)
    void SetMaxLogEntries(unsigned int max) { _maxEntries = max; }
    //! \return the current maximum number of entries (default = 0 for no limit)
    unsigned int GetMaxLogEntries() { return _maxEntries; }

    //! Clear the current message log entirely
    void ClearLog() { _messageList.clear(); }

    //! \brief Set the level of messages to output
    //! (i.e., messages with at least this priority will be output)
    void SetOutputLevel(const obMessageLevel level) { _outputLevel = level; }
    //! \return the current output level
    obMessageLevel GetOutputLevel() { return _outputLevel; }

    void SetOutputStream(std::ostream *os) { _outputStream = os; }
    std::ostream* GetOutputStream() { return _outputStream; }

    //! Start "wrapping" messages to cerr into ThrowError calls
    bool StartErrorWrap();
    //! Turn off "wrapping" messages, restoring normal cerr use (default)
    bool StopErrorWrap();

  protected:
    //! Log of messages for later retrieval via GetMessagesOfLevel()
    std::deque<OBError>    _messageList;

    //! Filtering level for messages and logging (messages of lower priority will be ignored
    obMessageLevel         _outputLevel;

    // self-explanatory
    std::ostream          *_outputStream;

    //! Whether messages will be logged into _messageList
    bool                   _logging;
    //! The maximum size of _messageList log
    unsigned int           _maxEntries;

    //! The default stream buffer for the output stream (saved if wrapping is ued)
    std::streambuf        *_inWrapStreamBuf;
    //! The filtered obLogBuf stream buffer to wrap error messages
    std::streambuf        *_filterStreamBuf;
  }; 

EXTERN OBMessageHandler obErrorLog;

//! \brief A minimal streambuf derivative to wrap calls to cerr into calls to OBMessageHandler as needed
 class OBAPI obLogBuf : public std::stringbuf
  {
    public:
      virtual ~obLogBuf() { sync(); }
    
    protected:
    //! Call OBMessageHandler::ThrowError() and flush the buffer
    int sync()
    {
      obErrorLog.ThrowError("", str(), obInfo);
      str(std::string()); // clear the buffer
                        return 0;
    }
  };

} // end namespace OpenBabel

#endif

//! \file oberror.h
//! \brief Handle error messages, warnings, notices, etc. 
Revision:	2450
Committed:	Thu Nov 17 20:38:45 2005 UTC (18 years, 9 months ago) by gezelter
File size:	6192 byte(s)
Log Message:	Unifying config.h stuff and making sure the OpenBabel codes can find our default (and environment variable) Force Field directories.
#	User	Rev	Content
1	tim	2440	/**********************************************************************
2			oberror.h - Handle error messages, warnings, notices, etc.
3
4			Copyright (C) 2002 by Stefan Kebekus
5			Some portions Copyright (C) 2003-2005 by Geoffrey R. Hutchison
6
7			This file is part of the Open Babel project.
8			For more information, see <http://openbabel.sourceforge.net/>
9
10			This program is free software; you can redistribute it and/or modify
11			it under the terms of the GNU General Public License as published by
12			the Free Software Foundation version 2 of the License.
13
14			This program is distributed in the hope that it will be useful, but
15			WITHOUT ANY WARRANTY; without even the implied warranty of
16			MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17			General Public License for more details.
18			***********************************************************************/
19
20			#ifndef OB_ERROR_H
21			#define OB_ERROR_H
22
23	gezelter	2450	#include "config.h"
24	tim	2440
25			#ifndef EXTERN
26			# define EXTERN extern
27			#endif
28
29			#if HAVE_IOSTREAM
30			#include <iostream>
31			#elif HAVE_IOSTREAM_H
32			#include <iostream.h>
33			#endif
34			#if HAVE_SSTREAM
35			#include <sstream>
36			#elif
37			#include <sstream.h>
38			#endif
39			#include <string>
40			#include <vector>
41			#include <deque>
42
43			namespace OpenBabel
44			{
45
46			//! \brief Levels of error and audit messages to allow filtering
47			enum obMessageLevel {
48			obError, //!< for critical errors (e.g., cannot read a file)
49			obWarning, //!< for non-critical problems (e.g., molecule appears empty)
50			obInfo, //!< for informative messages (e.g., file is a non-standard format)
51			obAuditMsg, //!< for messages auditing methods which destroy or perceive molecular data (e.g., kekulization, atom typing, etc.)
52			obDebug //!< for messages only useful for debugging purposes
53			};
54
55			//! \brief Customizable error handling and logging -- store a message,
56			//! including the method yielding the error, causes, etc.
57			class OBAPI OBError
58			{
59			public:
60
61			//! Constructor for an error message e.g. OBError(__FUNCTION__, " message ")
62			OBError( const std::string &method = "",
63			const std::string &errorMsg = "",
64			const std::string &explanation = "",
65			const std::string &possibleCause = "",
66			const std::string &suggestedRemedy = "",
67			const obMessageLevel = obDebug );
68
69			//! \return a formatted message string, including optional explanations, etc.
70			std::string message(void) const;
71
72			//! Output a formatted message string
73			friend std::ostream& operator<< ( std::ostream &os, const OBError &er )
74			{ return os << er.message(); };
75
76			std::string GetMethod() { return _method; }
77			std::string GetError() { return _errorMsg; }
78			std::string GetExplanation() { return _explanation; }
79			std::string GetPossibleCause() { return _possibleCause; }
80			std::string GetSuggestedRemedy() { return _suggestedRemedy; }
81			obMessageLevel GetLevel() { return _level; }
82
83			protected:
84
85			std::string _method;
86			std::string _errorMsg;
87			std::string _explanation;
88			std::string _possibleCause;
89			std::string _suggestedRemedy;
90
91			obMessageLevel _level;
92			};
93
94			//! \brief Handle error messages, warnings, debugging information and the like
95			class OBAPI OBMessageHandler
96			{
97			public:
98			OBMessageHandler();
99			~OBMessageHandler();
100
101			//! Throw an error with an already-formatted OBError object
102			void ThrowError(OBError err);
103			//! Throw an error in the specified method with an appropriate level
104			void ThrowError(const std::string &method, const std::string &errorMsg,
105			obMessageLevel level = obDebug);
106
107			//! \return all messages matching a specified level
108			std::vector<std::string> GetMessagesOfLevel(const obMessageLevel);
109
110			//! Start logging messages (default)
111			void StartLogging() { _logging = true; }
112			//! Stop logging messages completely
113			void StopLogging() { _logging = false; }
114
115			//! Set the maximum number of entries (or 0 for no limit)
116			void SetMaxLogEntries(unsigned int max) { _maxEntries = max; }
117			//! \return the current maximum number of entries (default = 0 for no limit)
118			unsigned int GetMaxLogEntries() { return _maxEntries; }
119
120			//! Clear the current message log entirely
121			void ClearLog() { _messageList.clear(); }
122
123			//! \brief Set the level of messages to output
124			//! (i.e., messages with at least this priority will be output)
125			void SetOutputLevel(const obMessageLevel level) { _outputLevel = level; }
126			//! \return the current output level
127			obMessageLevel GetOutputLevel() { return _outputLevel; }
128
129			void SetOutputStream(std::ostream *os) { _outputStream = os; }
130			std::ostream* GetOutputStream() { return _outputStream; }
131
132			//! Start "wrapping" messages to cerr into ThrowError calls
133			bool StartErrorWrap();
134			//! Turn off "wrapping" messages, restoring normal cerr use (default)
135			bool StopErrorWrap();
136
137			protected:
138			//! Log of messages for later retrieval via GetMessagesOfLevel()
139			std::deque<OBError> _messageList;
140
141			//! Filtering level for messages and logging (messages of lower priority will be ignored
142			obMessageLevel _outputLevel;
143
144			// self-explanatory
145			std::ostream *_outputStream;
146
147			//! Whether messages will be logged into _messageList
148			bool _logging;
149			//! The maximum size of _messageList log
150			unsigned int _maxEntries;
151
152			//! The default stream buffer for the output stream (saved if wrapping is ued)
153			std::streambuf *_inWrapStreamBuf;
154			//! The filtered obLogBuf stream buffer to wrap error messages
155			std::streambuf *_filterStreamBuf;
156			};
157
158			EXTERN OBMessageHandler obErrorLog;
159
160			//! \brief A minimal streambuf derivative to wrap calls to cerr into calls to OBMessageHandler as needed
161			class OBAPI obLogBuf : public std::stringbuf
162			{
163			public:
164			virtual ~obLogBuf() { sync(); }
165
166			protected:
167			//! Call OBMessageHandler::ThrowError() and flush the buffer
168			int sync()
169			{
170			obErrorLog.ThrowError("", str(), obInfo);
171			str(std::string()); // clear the buffer
172			return 0;
173			}
174			};
175
176			} // end namespace OpenBabel
177
178			#endif
179
180			//! \file oberror.h
181			//! \brief Handle error messages, warnings, notices, etc.