Commit 9531fec9 authored by thomas.forbriger's avatar thomas.forbriger

libdatrwxx [MERGE] new error message format

Merge branch '25-libdatrwxx-miniseed-consistency-checks'

Let libdatrwxx output more user-friendly error messages. These messages can
contain more detailed and comprehensive information regarding the cause of the
error message and can provide hints how to handle the situation.
parents c14e0ed7 5b317b8e
/*! \file aalibdatrwxx.cc
* \brief libdatrwxx version string (implementation)
*
* ----------------------------------------------------------------------------
*
* \author Thomas Forbriger
* \date 05/07/2016
*
* libdatrwxx version string (implementation)
*/
#define DATRW_AALIBDATRWXX_CC_VERSION \
"DATRW_AALIBDATRWXX_CC V1.0"
#include <datrwxx/aalibdatrwxx.h>
namespace datrw {
const char* const libversion="libdatrwxx (version 2016-07-05)";
} // namespace datrw
/* Copyright (c) 2016 by Thomas Forbriger (BFO Schiltach)
*
* ----
* 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; either version 2 of the License, or
* (at your option) any later version.
*
* 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.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
* ----
*
* REVISIONS and CHANGES
* - 05/07/2016 V1.0 Thomas Forbriger
*
* ============================================================================
*/
/* ----- END OF aalibdatrwxx.cc ----- */
/*! \file aalibdatrwxx.h
* \brief libdatrwxx version string (prototypes)
*
* ----------------------------------------------------------------------------
*
* \author Thomas Forbriger
* \date 05/07/2016
*
* libdatrwxx version string (prototypes)
*
* Copyright (c) 2016 by Thomas Forbriger (BFO Schiltach)
*
*
* ----
* 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; either version 2 of the License, or
* (at your option) any later version.
*
* 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.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
* ----
*
* REVISIONS and CHANGES
* - 05/07/2016 V1.0 Thomas Forbriger
*
* ============================================================================
*/
// include guard
#ifndef DATRW_AALIBDATRWXX_H_VERSION
#define DATRW_AALIBDATRWXX_H_VERSION \
"DATRW_AALIBDATRWXX_H V1.0"
namespace datrw {
/*! \brief Version string.
*
* This string can be used in output to identify the library and its version
* Please update this string upon implementation of new features or upon bug
* fixes.
*/
extern const char* const libversion;
} // namespace datrw
#endif // DATRW_AALIBDATRWXX_H_VERSION (includeguard)
/* ----- END OF aalibdatrwxx.h ----- */
......@@ -47,7 +47,7 @@ namespace datrw {
/*! \brief internals of the ascii I/O module
*
* \ingroup ascii
* \ingroup group_ascii
*/
namespace ascii {
......@@ -60,7 +60,7 @@ namespace datrw {
/*! \brief class to read ascii data
*
* \ingroup ascii
* \ingroup group_ascii
*/
class iasciistream: public idatstream {
public:
......@@ -100,7 +100,7 @@ namespace datrw {
/*! \brief class to write ascii data
*
* \ingroup ascii
* \ingroup group_ascii
*/
class oasciistream: public odatstream {
public:
......
......@@ -40,7 +40,7 @@
namespace datrw {
/*! \brief Format properties
* \ingroup ascii
* \ingroup group_ascii
* @{
*/
const bool ascii::isbinary=false;
......@@ -53,7 +53,7 @@ namespace datrw {
/*! \brief I/O module for ASCII data
*
* \defgroup ascii I/O module for ASCII data
* \defgroup group_ascii I/O module for ASCII data
*
* Lines of ASCII data files either start with
* - a single hash \c #: these lines provide header data; see keywords below
......
......@@ -44,7 +44,7 @@ namespace datrw {
namespace ascii {
/*! \brief key for WID2 line header field
* \ingroup ascii
* \ingroup group_ascii
* @{
*/
extern const char* const keydate;
......@@ -61,7 +61,7 @@ namespace datrw {
/**@}*/
/*! \brief key for SRCE line header field
* \ingroup ascii
* \ingroup group_ascii
* @{
*/
extern const char* const keySRCEdate;
......@@ -73,7 +73,7 @@ namespace datrw {
/**@}*/
/*! \brief key for INFO line header field
* \ingroup ascii
* \ingroup group_ascii
* @{
*/
extern const char* const keyRECVX;
......@@ -84,7 +84,7 @@ namespace datrw {
/**@}*/
/*! \brief key for DATA type header field
* \ingroup ascii
* \ingroup group_ascii
* @{
*/
extern const char* const keydata;
......@@ -94,7 +94,7 @@ namespace datrw {
/**@}*/
/*! \brief format modifier key
* \ingroup ascii
* \ingroup group_ascii
* @{
*/
extern const char* const keynonfatal;
......
......@@ -28,15 +28,18 @@
*
*
* REVISIONS and CHANGES
* - 18/10/2011 V1.0 Thomas Forbriger
* - 18/10/2011 V1.0 Thomas Forbriger (thof)
* - 12/06/2012 V1.1 settraceheader must not be called before actual
* number of samples ist set
* correction in skipseries()
* - 08/07/2016 V1.2 thof:
* - make correct use of new DATRW_report_assert
* - make correct use of new DATRW_nonfatal_assert
*
* ============================================================================
*/
#define DATRW_IASCIISTREAM_CC_VERSION \
"DATRW_IASCIISTREAM_CC V1.0 "
"DATRW_IASCIISTREAM_CC V1.2"
#include<iomanip>
#include<vector>
......@@ -255,7 +258,7 @@ namespace datrw {
if (key.length()==0)
{
DATRW_report_assert(key.length()>0,
"keyword is missing in header line",
"keyword is missing in header line\n" <<
"input line: " << Mcurrentline << "\n" <<
"key: " << key);
}
......@@ -268,7 +271,7 @@ namespace datrw {
// was not recognoized
DATRW_nonfatal_assert(Mnonfatal,
false,
"iasciistream: header key not recognized",
"iasciistream: header key not recognized\n"
"input line: " << Mcurrentline << "\n" <<
"key: " << key);
}
......@@ -297,7 +300,7 @@ namespace datrw {
namespace {
/*! read a sequence of samples
* \ingroup ascii
* \ingroup group_ascii
*
* Read a sequence of samples being regarded as a contiguous trace.
*
......@@ -378,7 +381,7 @@ namespace datrw {
DATRW_nonfatal_assert(nonfatal,
(i==n),
"readsamples (ASCII): "
"found less samples than expected",
"found less samples than expected\n"
"expected: " << n << " " <<
"found: " << i);
}
......@@ -388,7 +391,7 @@ namespace datrw {
/*----------------------------------------------------------------------*/
/*! read a sequence of samples
* \ingroup ascii
* \ingroup group_ascii
*
* Read a sequence of samples being regarded as a contiguous trace.
* This function essential performs the correct type conversion after
......@@ -532,7 +535,7 @@ namespace datrw {
namespace {
/*!
* \ingroup ascii
* \ingroup group_ascii
* \todo
* replace with formatmodifiers::ModifierHelp
*/
......@@ -550,7 +553,7 @@ namespace datrw {
/*----------------------------------------------------------------------*/
/*!
* \ingroup ascii
* \ingroup group_ascii
* \todo
* replace with formatmodifiers::ModifierHelp
*/
......
......@@ -48,14 +48,14 @@ namespace datrw {
/*! \brief I/O module for binary data
*
* \defgroup binary I/O module for binary data
* \defgroup group_binary I/O module for binary data
*/
/*----------------------------------------------------------------------*/
/*! \brief internals of the binary I/O module
*
* \ingroup binary
* \ingroup group_binary
*/
namespace binary {
......@@ -63,16 +63,16 @@ namespace datrw {
extern const char* const streamID;
/*! \brief magic number to identify file type and bytesex
* \ingroup binary
* \ingroup group_binary
*/
extern const char* const magic;
/*! \brief a version number for files - just in case
* \ingroup binary
* \ingroup group_binary
*/
extern const short version;
/*! \brief indicate file or trace properties
* \ingroup binary
* \ingroup group_binary
*/
enum Eflags {
Fsrce= (1<<0), //!< trace has SRCE header
......@@ -84,11 +84,11 @@ namespace datrw {
}; // enum Eflags
/*! \brief abort if file flags are inconsistent
* \ingroup binary
* \ingroup group_binary
*/
void checkfileflags(const char& flags);
/*! \brief abort if trace flags are inconsistent
* \ingroup binary
* \ingroup group_binary
*/
void checktraceflags(const char& flags);
......@@ -98,7 +98,7 @@ namespace datrw {
/*! \brief class to read binary data
*
* \ingroup binary
* \ingroup group_binary
*/
class ibinarystream: public idatstream {
public:
......@@ -125,7 +125,7 @@ namespace datrw {
/*! \brief class to write binary
*
* \ingroup binary
* \ingroup group_binary
*/
class obinarystream: public odatstream {
public:
......
......@@ -41,7 +41,7 @@
namespace datrw {
/*! \brief Format properties
* \ingroup binary
* \ingroup group_binary
* @{
*/
const bool binary::isbinary=false;
......
......@@ -51,7 +51,7 @@ namespace datrw {
namespace binary {
/*! \brief stream like class for binary input of basic types and classes
* \ingroup binary
* \ingroup group_binary
*/
class ibinstream {
public:
......@@ -85,7 +85,7 @@ namespace datrw {
/*----------------------------------------------------------------------*/
/*! \brief input operator for basic types and classes
* \ingroup binary
* \ingroup group_binary
*/
template<class C>
ibinstream& operator>>(ibinstream& ibs, C& v)
......
......@@ -51,7 +51,7 @@ namespace datrw {
namespace binary {
/*! \brief binary output for basic types and classes
* \ingroup binary
* \ingroup group_binary
*/
class obinstream {
public:
......@@ -81,7 +81,7 @@ namespace datrw {
/*----------------------------------------------------------------------*/
/*! \brief output operator for basic types and classes
* \ingroup binary
* \ingroup group_binary
*/
template<class C>
obinstream& operator<<(obinstream& obs, const C& v)
......
......@@ -54,7 +54,7 @@ namespace datrw {
/*! \brief input stream to read seismic data provided by K. Bonjer
*
* \ingroup bonjer
* \ingroup group_bonjer
*
* The concept is based on SFF data contents and we will make use of SFF
* structures.
......
......@@ -45,7 +45,7 @@ namespace datrw {
//@{
/*! \brief Format properties
* \ingroup bonjer
* \ingroup group_bonjer
*/
const bool bonjer::isbinary=false;
const char* const bonjer::streamID="bonjer";
......
......@@ -46,12 +46,12 @@ namespace datrw {
/*! \brief all functions, classes, etc. to read K. Bonjers data format
*
* \defgroup bonjer Reading module for: file format defined by K. Bonjer
* \defgroup group_bonjer Reading module for: file format defined by K. Bonjer
*/
/*! \brief all functions, classes, etc. to read K. Bonjers data format
*
* \ingroup bonjer
* \ingroup group_bonjer
*/
namespace bonjer {
......
......@@ -31,11 +31,12 @@
* - 11/04/2006 V1.0 Thomas Forbriger
* - 01/04/2011 V1.1 do not clear Mhassrce upon writing the file header
* - 07/06/2011 V1.2 promise constness of series samples
* - 08/07/2016 V1.3 make correct use of new DATRW_report_assert
*
* ============================================================================
*/
#define DATRW_DATWRITE_CC_VERSION \
"DATRW_DATWRITE_CC V1.2"
"DATRW_DATWRITE_CC V1.3"
#include<fstream>
#include <datrwxx/datwrite.h>
......@@ -103,11 +104,11 @@ namespace datrw {
if (Mheaderflushed)
{
DATRW_report_assert(this->handlestracefree(),
"file format cannot handle trace FREE data",
"file format cannot handle trace FREE data\n" <<
"FREE data will be dropped silently");
} else {
DATRW_report_assert(this->handlesfilefree(),
"file format cannot handle file FREE data",
"file format cannot handle file FREE data\n" <<
"FREE data will be dropped silently");
}
Mfreeset=true;
......@@ -128,7 +129,7 @@ namespace datrw {
void odatstream::setinfo(const sff::INFO& info)
{
DATRW_report_assert(this->handlesinfo(),
"file format cannot handle INFO data",
"file format cannot handle INFO data\n"
"INFO data will be dropped silently");
Minfoset=true;
Minfo=info;
......@@ -139,7 +140,7 @@ namespace datrw {
void odatstream::setsrce(const sff::SRCE& srce)
{
DATRW_report_assert(this->handlessrce(),
"file format cannot handle SRCE data",
"file format cannot handle SRCE data\n"
"SRCE data will be dropped silently");
Msrceset=true;
Msrce=srce;
......
......@@ -62,7 +62,7 @@
*
* The macro can be used in the argument \par M of DATRW_debug
*/
#define DATRW_value(V) #V << ": " << V
#define DATRW_value(V) #V << "=" << V
#endif // DATRW_DEBUG_H_VERSION (includeguard)
......
......@@ -70,6 +70,8 @@ namespace datrw {
- \subpage page_writing_howto
- \subpage page_writing_operation
\subsubsection subsubsec_main_others_programmers For library maintainers and programmers
Upon implementing new features update the version string
datrw::libversion in \ref aalibdatrwxx.cc
- \subpage page_implement_istream
- \subpage page_implement_ostream
- \subpage page_modifiers
......@@ -609,7 +611,7 @@ The operators are provided in namespace ::datrw.
\sa datrw::iseifestream::iseifestream(),
datrw::oseifestream::oseifestream(),
\ref formatmodifiers,
\ref group_formatmodifiers,
libdatrwxxtests.cc
\date 09/2011
......
......@@ -23,29 +23,29 @@
\note
This page is still under construction.
\section sec_util_formatmodifiers
\section sec_util_formatmodifiers Format modifiers
\sa \ref formatmodifiers
\sa \ref group_formatmodifiers
\section sec_util_datatypes
\section sec_util_datatypes Data types
\sa \ref datrw::datatypes
\sa datatypes.h
\section sec_util_properties
\section sec_util_properties Properties
\sa \subpage page_properties
\sa \ref properties
\sa \ref group_properties
\section sec_util_bytesex
\section sec_util_bytesex Bytesex
\sa \ref group_bytesex
\section sec_util_error
\section sec_util_error Error handling
\sa \ref group_error
\section sec_util_reservoir
\section sec_util_reservoir Time series reservoir
\sa reservoir.h
......
......@@ -33,6 +33,15 @@
* - 06/09/2011 V1.3 introduced report_deprecated
* - 22/07/2014 V1.4 thof: report comments prior to throwing exception
* provide warning macro
* - 05/07/2016 V1.5 thof: operate with string containers rather than
* with pointer to character arrays
* - 07/07/2016 V1.6 thof: move class exception to separate header
* - 08/07/2016 V1.7 thof:
* - move report functions to separate compilation unit
* - create multiline messages
* - remove specific multiline macros
* - 11/07/2016 V1.8 thof:
* - support multi-line abort message
*
* ============================================================================
*/
......@@ -41,102 +50,15 @@
#ifndef DATRW_ERROR_H_VERSION
#define DATRW_ERROR_H_VERSION \
"DATRW_ERROR_H V1.4"
"DATRW_ERROR_H V1.8"
#include <iostream>
#include <sstream>
#include <datrwxx/report.h>
#include <datrwxx/exception.h>
namespace datrw {
/*! \defgroup group_error Error handling module
*/
/*! \brief Base class for exceptions
*
* This is an exception base class. It holds some information about the
* reason for throwing the exception. The information is printed to cerr
* through function report(). This function may be overloaded by a derived
* type. But its functionality is still accessible through base_report().
*
* The standard behaviour is to print out the message during object
* initialization. If you don't like this, call dont_report_on_construct().
*
* \ingroup group_error
* \sa DATRW_Xassert
* \sa DATRW_assert
* \sa DATRW_abort
*/
class Exception
{
public:
//! Creates exception with no explaning comments
Exception();
//! Creates an exception with an explanation message
Exception(const char* message);
//! Creates an exception with message and failed assertion
Exception(const char* message,
const char* condition);
//! Create with message, failed assertion, and code position
Exception(const char* message,
const char* file,
const int& line,
const char* condition);
//! Create with message and code position
Exception(const char* message,
const char* file,
const int& line);
//! provide explicit virtual destructor
virtual ~Exception() { }
//! Screen report
virtual void report() const;
//! Issue a screen report on construction of exception
static void report_on_construct();
//! Issue NO screen report on construction of exception
static void dont_report_on_construct();
//! set report on construct flag
static void report_on_construct_flag(const bool& flag)
{ Mreport_on_construct=flag; }
//! return report on construct flag
static bool report_on_construct_flag() { return(Mreport_on_construct); }
protected:
//! Screen report
void base_report() const;
private:
//! Shall we print to cerr at construction time?
static bool Mreport_on_construct;
//! pointer to message string
const char* Mmessage;
//! pointer to file name string
const char* Mfile;
//! pointer to line number in source file
const int& Mline;
//! pointer to assertion condition text string
const char* Mcondition;
}; // class Exception
/*! \brief report violation of condition
*
* \ingroup group_error