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:	751
Committed:	Thu Nov 17 20:38:45 2005 UTC (19 years, 11 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.
#	Content
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 "config.h"
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.