1 |
/********************************************************************** |
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 |
#include "babelconfig.hpp" |
24 |
|
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. |