Loading...
Searching...
No Matches
LogIO.h
Go to the documentation of this file.
//# LogIO.h: ostream-like interface to creating log messages.
//# Copyright (C) 1997,1999,2000,2001,2003
//# Associated Universities, Inc. Washington DC, USA.
//#
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//#
//# 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. See the GNU Library General Public
//# License for more details.
//#
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//#
//# Correspondence concerning AIPS++ should be addressed as follows:
//# Internet email: casa-feedback@nrao.edu.
//# Postal address: AIPS++ Project Office
//# National Radio Astronomy Observatory
//# 520 Edgemont Road
//# Charlottesville, VA 22903-2475 USA
#ifndef CASA_LOGIO_H
#define CASA_LOGIO_H
//# Includes
#include <casacore/casa/aips.h>
#include <casacore/casa/Logging/LogMessage.h>
#include <casacore/casa/Logging/LogSink.h>
#include <casacore/casa/BasicSL/Complex.h>
#include <casacore/casa/iosstrfwd.h>
namespace casacore { //# NAMESPACE CASACORE - BEGIN
//# Forward Declarations
class LogSink;
class LogOrigin;
// <summary>
// ostream-like interface to creating log messages.
// </summary>
// <use visibility=export>
// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tLogIO.cc" demos="dLogging.cc">
// </reviewed>
// <prerequisite>
// <li> <linkto class=LogSink>LogSink</linkto> class
// <li> <linkto class=LogMessage>LogMessage</linkto> class
// <li> <linkto class=LogMessage>LogOrigin</linkto> class
// </prerequisite>
//
// <etymology>
// <src>Log</src> message, <src>I</src>nput/<src>O</src>utput.
// </etymology>
//
// <synopsis>
// LogIO is intended to be used in a way similar to the ostream class.
// However, rather than sending it's output to a file or stdout, it bundles
// its output up into <linkto class=LogMessage>LogMessage</linkto> objects
// and posts them to a <linkto class=LogSink>LogSink</linkto>.
//
// When you use the "<<" operator on a LogIO, you are building up a log message
// inside the LogIO object. The message is posted when:
// <ol>
// <li> <src>LogIO::POST()</src> is called
// <li> You send the <src>LogIO::POST</src> or <src>LogIO::EXCEPTION</src>
// commands to the LogIO with the shift (<src> << </src>) command.
// <li> The LogIO object is destructed.
// </ol>
// Note that log messages may span multiple lines, so sending the LogIO a
// newline (via "\n" or endl) does not force the message to be emitted.
// </synopsis>
//
// <example>
// A LogIO may be created in the following ways:
// <srcblock>
// LogIO os;
// </srcblock>
// Here, <src>os</src> is attached to the global log sink, and no origin
// information is set.
//
// <srcblock>
// TableLogSink tab(...);
// LogIO os(tab);
// </srcblock>
// Here, <src>os</src> is attached to <src>tab</src> (and also to the global
// log sink since every sink's <src>post</src> also calls the global sink's
// <src>post</src>).
//
//
// <srcblock>
// LogIO os(LogOrigin("class", "func(args)", WHERE));
// </srcblock>
// Here, <src>os</src> is attached to the global sink and the origin
// information is set to <src>class::func(args)</src> and the line number and
// source file information is set (with <src>WHERE</src>).
//
// <srcblock>
// TableLogSink tab(...);
// LogIO os(LogOrigin("class", "func(args)", WHERE), tab);
// </srcblock>
// Here all the above information is set.
//
// Once you have a <src>LogIO</src>, using it is pretty simple:
// <srcblock>
// os << "Every good boy deserves" << 5 << " pieces of fudge!";
// </srcblock>
//
// This accumulates the message but does not send it. If you want to force it
// to be sent you can do so with either of the following methods:
// <srcblock>
// os << LogIO::POST; // From the Commands enum
// os.post(); // Member function
// </srcblock>
// Note that after a post the priority is reset to NORMAL.
//
// If you want to change the level of the message you can also do so with the
// shift operator:
// <srcblock>
// os << LogIO::DEBUGGING << "Boring message" <<
// LogIO::SEVERE << "Error!" << LogIO::POST;
// </srcblock>
// Note that changing the priority changes the priority of the entire
// message. The message does not get posted until the POST is done.
// So in the above example the DEBUGGING priority does not do anything
// because the priority is overwritten by the SEVERE one.
//
// You can also change the origin information with the << operator:
// <srcblock>
// os << LogOrigin("class", "func(args)");
// os << WHERE;
// </srcblock>
//
// A class which has an operator<< to std::ostream but not LogIO can be handled
// as follows:
// <srcblock>
// os << LogIO::SEVERE << " at ";
// os.output() << MEpoch::Convert(time_p, MEpoch::Ref(MEpoch::UTC))();
// os << LogIO::POST;
// </srcblock>
// </example>
//
// <motivation>
// The earlier method of creating log messages solely through LogSink and
// LogMessage required the programmer to type in more lines of code than
// this solution. Also, this interface makes it easy to drop log messages
// into existing code that uses ostreams.
// </motivation>
//
// <todo asof="1997/01/29">
// <li> Add << operators for all classes that have ostream<< defined.
// (We could probably do it with a template, but might result
// in ambiguity).
// <li> Have a function for changing the LogSink only? (You can get
// much the same effect with operator=).
// them?
// </todo>
class LogIO
{
public:
// Special commands to the LogIO object
enum Command {
// Post the accumulated message. Equivalent to calling LogIO::post().
POST,
// Post the accumulated message then throw an exception.
// Always posts the message at SEVERE priority. Equivalent to calling
// LogIO::postThenThrow().
EXCEPTION,
// Change the message priority to SEVERE.
SEVERE,
// Change the message priority to WARN.
WARN,
// Change the message priority to NORMAL.
NORMAL,
NORMAL1,
NORMAL2,
NORMAL3,
NORMAL4,
NORMAL5,
// Change the message priority to DEBUGGING.
DEBUG1,
DEBUG2,
DEBUGGING};
// Attach this LogIO object to the global sink with no origin information.
LogIO();
// Attach this LogIO object to the supplied sink. A referencing copy of
// the sink is made inside the LogIO object, so you do not need to worry
// about memory management.
LogIO(LogSink &sink);
// Attach this LogIO object to the supplied origin and global sink.
LogIO(const LogOrigin &OR);
// Attach this LogIO object to the supplied origin and sink.
LogIO(const LogOrigin &OR, LogSink &sink);
// Copying uses reference semantics, i.e. the same sink will be shared
// by both copies.
// <group>
LogIO(const LogIO &other);
LogIO &operator=(const LogIO &other);
// </group>
// The destructor will post any accumulated message that has not already
// been posted.
~LogIO();
// Post the accumulated message. If you wish, you can post the messages
// only locally to the sink.
// After the post the priority is reset to NORMAL.
void post();
void post(LogMessage &amess);
// Post the accumulated message locally.
// After the post the priority is reset to NORMAL.
void postLocally();
// Post the accumulated message at SEVERE priority and then throw an
// exception.
// After the post the priority is reset to NORMAL.
template<typename EXC> void postThenThrow (const EXC& exc)
{ preparePostThenThrow(exc); sink_p.postThenThrow (msg_p, exc); }
// Change the priority of the message. It does NOT post the accumulated
// message at the old priority first.
void priority(LogMessage::Priority which);
LogMessage::Priority priority();
// Change the location in the origin. Almost always this is called with the
// macro WHERE as its argument.
void sourceLocation(const SourceLocation *where);
// Change the origin of the accumulated message.
void origin(const LogOrigin &origin);
// Acumulate output in this ostream.
ostream& output();
// Occasionally it is useful to interrogate the local log sink.
LogSinkInterface &localSink();
const LogSinkInterface &localSink() const;
private:
// Prepare message stream for postThenThrow function.
void preparePostThenThrow (const AipsError& x);
LogSink sink_p;
LogMessage msg_p;
ostringstream *text_p;
};
// <summary>
// Functions to send commands to a LogIO object.
// </summary>
// The following commands don't change the accumulated message, rather they
// send commands to the LogIO object, either to:
// <ol>
// <li>post the current message: <src>os << "message" << LogIO::POST;</src>
// <li>post the current message and then throw an exception:
// <src>os << "error" << LogIO::EXCEPTION;</src>
// <li> Change the priority of the current message:
// <src>os << LogIO::DEBUGGING;</src>
// <li> Change the origin of the message:
// <srcblock>
// os << LogOrigin(...);
// os << WHERE; // Changes only source file/line number
// </srcblock>
// </ol>
// <group name=command>
LogIO &operator<<(LogIO &os, LogIO::Command item);
LogIO &operator<<(LogIO &os, const SourceLocation &item);
LogIO &operator<<(LogIO &os, const LogOrigin &OR);
// </group>
// <summary>
// Functions to accumulate text in the output message.
// </summary>
// Accumulate text in the output message. The last entry is for things like
// <src>endl</src>.
// <group name=output>
LogIO &operator<<(LogIO &os, const String &item);
LogIO &operator<<(LogIO &os, const char *item);
LogIO &operator<<(LogIO &os, Double item);
LogIO &operator<<(LogIO &os, Complex item);
LogIO &operator<<(LogIO &os, DComplex item);
LogIO &operator<<(LogIO &os, Int item);
LogIO &operator<<(LogIO &os, uInt item);
LogIO &operator<<(LogIO &os, Int64 item);
LogIO &operator<<(LogIO &os, uInt64 item);
LogIO &operator<<(LogIO &os, uLong item);
LogIO &operator<<(LogIO &os, Long item);
LogIO &operator<<(LogIO &os, Bool item);
LogIO &operator<<(LogIO &os, ostream &(*item)(ostream &));
// </group>
inline LogSinkInterface &LogIO::localSink()
{
return sink_p.localSink();
}
inline const LogSinkInterface &LogIO::localSink() const
{
return sink_p.localSink();
}
} //# NAMESPACE CASACORE - END
#endif
casacore::AipsError
Definition Error.h:133
casacore::LogIO
Definition LogIO.h:165
casacore::LogIO::LogIO
LogIO()
Attach this LogIO object to the global sink with no origin information.
casacore::LogIO::LogIO
LogIO(const LogIO &other)
Copying uses reference semantics, i.e.
casacore::LogIO::Command
Command
Special commands to the LogIO object.
Definition LogIO.h:168
casacore::LogIO::DEBUG1
@ DEBUG1
Change the message priority to DEBUGGING.
Definition LogIO.h:187
casacore::LogIO::SEVERE
@ SEVERE
Change the message priority to SEVERE.
Definition LogIO.h:176
casacore::LogIO::NORMAL5
@ NORMAL5
Definition LogIO.h:185
casacore::LogIO::EXCEPTION
@ EXCEPTION
Post the accumulated message then throw an exception.
Definition LogIO.h:174
casacore::LogIO::DEBUG2
@ DEBUG2
Definition LogIO.h:188
casacore::LogIO::NORMAL
@ NORMAL
Change the message priority to NORMAL.
Definition LogIO.h:180
casacore::LogIO::NORMAL3
@ NORMAL3
Definition LogIO.h:183
casacore::LogIO::NORMAL2
@ NORMAL2
Definition LogIO.h:182
casacore::LogIO::DEBUGGING
@ DEBUGGING
Definition LogIO.h:189
casacore::LogIO::POST
@ POST
Post the accumulated message.
Definition LogIO.h:170
casacore::LogIO::NORMAL1
@ NORMAL1
Definition LogIO.h:181
casacore::LogIO::NORMAL4
@ NORMAL4
Definition LogIO.h:184
casacore::LogIO::WARN
@ WARN
Change the message priority to WARN.
Definition LogIO.h:178
casacore::LogIO::text_p
ostringstream * text_p
Definition LogIO.h:252
casacore::LogIO::LogIO
LogIO(const LogOrigin &OR)
Attach this LogIO object to the supplied origin and global sink.
casacore::LogIO::output
ostream & output()
Acumulate output in this ostream.
casacore::LogIO::postThenThrow
void postThenThrow(const EXC &exc)
Post the accumulated message at SEVERE priority and then throw an exception.
Definition LogIO.h:226
casacore::LogIO::post
void post()
Post the accumulated message.
casacore::LogIO::msg_p
LogMessage msg_p
Definition LogIO.h:251
casacore::LogIO::preparePostThenThrow
void preparePostThenThrow(const AipsError &x)
Prepare message stream for postThenThrow function.
casacore::LogIO::~LogIO
~LogIO()
The destructor will post any accumulated message that has not already been posted.
casacore::LogIO::localSink
LogSinkInterface & localSink()
Occasionally it is useful to interrogate the local log sink.
Definition LogIO.h:300
casacore::LogIO::priority
void priority(LogMessage::Priority which)
Change the priority of the message.
casacore::LogIO::priority
LogMessage::Priority priority()
casacore::LogIO::sink_p
LogSink sink_p
Definition LogIO.h:250
casacore::LogIO::sourceLocation
void sourceLocation(const SourceLocation *where)
Change the location in the origin.
casacore::LogIO::LogIO
LogIO(LogSink &sink)
Attach this LogIO object to the supplied sink.
casacore::LogIO::operator=
LogIO & operator=(const LogIO &other)
casacore::LogIO::LogIO
LogIO(const LogOrigin &OR, LogSink &sink)
Attach this LogIO object to the supplied origin and sink.
casacore::LogIO::post
void post(LogMessage &amess)
casacore::LogIO::postLocally
void postLocally()
Post the accumulated message locally.
casacore::LogIO::origin
void origin(const LogOrigin &origin)
Change the origin of the accumulated message.
casacore::LogMessage
Definition LogMessage.h:98
casacore::LogMessage::Priority
Priority
An "importance" which is assigned to each LogMessage.
Definition LogMessage.h:102
casacore::LogOrigin
Definition LogOrigin.h:92
casacore::LogSinkInterface
Definition LogSinkInterface.h:97
casacore::LogSink
Definition LogSink.h:138
casacore::String
String: the storage and methods of handling collections of characters.
Definition String.h:223
casacore
this file contains all the compiler specific defines
Definition mainpage.dox:28
casacore::operator<<
ostream & operator<<(ostream &os, const IComplex &)
Show on ostream.
casacore::uLong
unsigned long uLong
Definition aipstype.h:51
casacore::Long
long Long
Definition aipstype.h:50
casacore::uInt
unsigned int uInt
Definition aipstype.h:49
casacore::Int64
long long Int64
Define the extra non-standard types used by Casacore (like proposed uSize, Size).
Definition aipsxtype.h:36
casacore::Int
int Int
Definition aipstype.h:48
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:40
casacore::Double
double Double
Definition aipstype.h:53
casacore::uInt64
unsigned long long uInt64
Definition aipsxtype.h:37
casacore::LogIO_global_functions_command
Functions to send commands to a LogIO object.
Definition LogIO.h:274
casacore::LogIO_global_functions_command::operator<<
LogIO & operator<<(LogIO &os, const LogOrigin &OR)
casacore::LogIO_global_functions_command::operator<<
LogIO & operator<<(LogIO &os, LogIO::Command item)
casacore::LogIO_global_functions_command::operator<<
LogIO & operator<<(LogIO &os, const SourceLocation &item)
casacore::LogIO_global_functions_output
Functions to accumulate text in the output message.
Definition LogIO.h:285
casacore::LogIO_global_functions_output::operator<<
LogIO & operator<<(LogIO &os, uInt64 item)
casacore::LogIO_global_functions_output::operator<<
LogIO & operator<<(LogIO &os, const char *item)
casacore::LogIO_global_functions_output::operator<<
LogIO & operator<<(LogIO &os, uInt item)
casacore::LogIO_global_functions_output::operator<<
LogIO & operator<<(LogIO &os, Double item)
casacore::LogIO_global_functions_output::operator<<
LogIO & operator<<(LogIO &os, Long item)
casacore::LogIO_global_functions_output::operator<<
LogIO & operator<<(LogIO &os, Int item)
casacore::LogIO_global_functions_output::operator<<
LogIO & operator<<(LogIO &os, DComplex item)
casacore::LogIO_global_functions_output::operator<<
LogIO & operator<<(LogIO &os, ostream &(*item)(ostream &))
casacore::LogIO_global_functions_output::operator<<
LogIO & operator<<(LogIO &os, Complex item)
casacore::LogIO_global_functions_output::operator<<
LogIO & operator<<(LogIO &os, uLong item)
casacore::LogIO_global_functions_output::operator<<
LogIO & operator<<(LogIO &os, Bool item)
casacore::LogIO_global_functions_output::operator<<
LogIO & operator<<(LogIO &os, Int64 item)
casacore::LogIO_global_functions_output::operator<<
LogIO & operator<<(LogIO &os, const String &item)