xapian-core/generate-exceptions

   1 # generate-exceptions: generate C++ files for Xapian's exception hierarchy.
   2 #
   3 # Copyright (C) 2003,2004,2006,2007,2008,2009,2011,2012,2013,2014,2015 Olly Betts
   4 # Copyright (C) 2007 Richard Boulton
   5 #
   6 # This program is free software; you can redistribute it and/or
   7 # modify it under the terms of the GNU General Public License as
   8 # published by the Free Software Foundation; either version 2 of the
   9 # License, or (at your option) any later version.
  10 #
  11 # This program is distributed in the hope that it will be useful,
  12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 # GNU General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU General Public License
  17 # along with this program; if not, write to the Free Software
  18 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
  19
  20 use strict;
  21 use exception_data qw(
  22     $copyright $generated_warning @baseclasses @classes %classcode
  23 );
  24
  25 open HDR, ">include/xapian/error.h" or die $!;
  26 open DISPATCH, ">include/xapian/errordispatch.h" or die $!;
  27
  28 print HDR <<'EOF';
  29 /** @file error.h
  30  *  @brief Hierarchy of classes which Xapian can throw as exceptions.
  31  */
  32 EOF
  33
  34 print HDR $generated_warning;
  35 print DISPATCH $generated_warning;
  36
  37 print HDR $copyright;
  38 print DISPATCH $copyright;
  39
  40 print HDR <<'EOF';
  41
  42 #ifndef XAPIAN_INCLUDED_ERROR_H
  43 #define XAPIAN_INCLUDED_ERROR_H
  44
  45 #if !defined XAPIAN_IN_XAPIAN_H && !defined XAPIAN_LIB_BUILD
  46 # error "Never use <xapian/error.h> directly; include <xapian.h> instead."
  47 #endif
  48
  49 #include <string>
  50 #include <xapian/attributes.h>
  51 #include <xapian/visibility.h>
  52
  53 namespace Xapian {
  54
  55 class ErrorHandler;
  56
  57 /** All exceptions thrown by Xapian are subclasses of Xapian::Error.
  58  *
  59  *  This class can not be instantiated directly - instead a subclass should
  60  *  be used.
  61  */
  62 class XAPIAN_VISIBILITY_DEFAULT Error {
  63     // ErrorHandler needs to be able to access Error::already_handled.
  64     friend class ErrorHandler;
  65
  66     /// Message giving details of the error, intended for human consumption.
  67     std::string msg;
  68
  69     /** Optional context information.
  70      *
  71      *  This context is intended for use by Xapian::ErrorHandler (for example
  72      *  so it can know which remote server is unreliable and report the problem
  73      *  and remove that server from those being searched).  But it's typically
  74      *  a plain-text string, and so also fit for human consumption.
  75      */
  76     std::string context;
  77
  78     /** The error string derived from my_errno.
  79      *
  80      *  This string is generated from my_errno lazily.
  81      */
  82     mutable std::string error_string;
  83
  84     /// The type of this error (e.g. DocNotFoundError.)
  85     const char * type;
  86
  87     /** Optional value of 'errno' associated with this error.
  88      *
  89      *  If no value is associated, this member variable will be 0.
  90      *
  91      *  On UNIX, if this value is < 0, it's an error code returned from
  92      *  getaddrinfo() (negated if such error codes are positive).
  93      *
  94      *  On Windows, if this value is < 0, it's a negated Windows error code
  95      *  (as given by GetLastError()), while if it is >= WSABASEERR then it is a
  96      *  WinSock error code (as given by WSAGetLastError()).  Prior to Xapian
  97      *  1.2.20 and 1.3.3, WSAGetLastError() codes were also negated.
  98      *
  99      *  NB We don't just call this member "errno" to avoid problems on
 100      *  platforms where errno is a preprocessor macro.
 101      */
 102     int my_errno;
 103
 104     /// True if this error has already been passed to an ErrorHandler.
 105     bool already_handled;
 106
 107     /// Don't allow assignment of the base class.
 108     void operator=(const Error &o);
 109
 110   protected:
 111     /** @private @internal
 112      *  @brief Constructor for use by constructors of derived classes.
 113      */
 114     Error(const std::string &msg_, const std::string &context_,
 115           const char * type_, const char * error_string_);
 116
 117     /** @private @internal
 118      *  @brief Constructor for use by constructors of derived classes.
 119      */
 120     Error(const std::string &msg_, const std::string &context_,
 121           const char * type_, int errno_)
 122         : msg(msg_), context(context_), error_string(), type(type_),
 123           my_errno(errno_), already_handled(false) { }
 124
 125   public:
 126     /// The type of this error (e.g. "DocNotFoundError".)
 127     const char * XAPIAN_NOTHROW(get_type() const) {
 128         return type + 1;
 129     }
 130
 131     /// Message giving details of the error, intended for human consumption.
 132     const std::string & XAPIAN_NOTHROW(get_msg() const) {
 133         return msg;
 134     }
 135
 136     /** Optional context information.
 137      *
 138      *  This context is intended for use by Xapian::ErrorHandler (for example
 139      *  so it can know which remote server is unreliable and report the problem
 140      *  and remove that server from those being searched).  But it's typically
 141      *  a plain-text string, and so also fit for human consumption.
 142      */
 143     const std::string & XAPIAN_NOTHROW(get_context() const) {
 144         return context;
 145     }
 146
 147     /** Returns any system error string associated with this exception.
 148      *
 149      *  The system error string may come from errno, h_errno (on UNIX), or
 150      *  GetLastError() (on MS Windows).  If there is no associated system
 151      *  error string, NULL is returned.
 152      */
 153     const char * get_error_string() const;
 154
 155     /// Return a string describing this object.
 156     std::string get_description() const;
 157 };
 158 EOF
 159
 160 print DISPATCH <<'EOF';
 161
 162 /* Note that this file isn't an external header - it's located in
 163  * include/xapian in the source tree because it's generated so this
 164  * is the simplest way to make inclusion work in a VPATH build.
 165  */
 166
 167 // DOXYGEN gets confused by this header-with-code.
 168 #ifndef DOXYGEN
 169 EOF
 170
 171 for (@baseclasses) {
 172     chomp;
 173     my ($class, $parent, $comment) = split /\t/, $_, 3;
 174     print HDR <<EOF;
 175
 176 $comment
 177 class XAPIAN_VISIBILITY_DEFAULT $class : public $parent {
 178   protected:
 179     /** \@private \@internal
 180      *  \@brief Constructor for use by constructors of derived classes.
 181      */
 182     $class(const std::string \&msg_, const std::string \&context_, const char * type_, const char * error_string_)
 183         : $parent(msg_, context_, type_, error_string_) {}
 184
 185     /** \@private \@internal
 186      *  \@brief Constructor for use by constructors of derived classes.
 187      */
 188     $class(const std::string \&msg_, const std::string \&context_, const char * type_, int errno_)
 189         : $parent(msg_, context_, type_, errno_) {}
 190 };
 191 EOF
 192 }
 193
 194 for (@classes) {
 195     chomp;
 196     my ($class, $parent, $comment) = split /\t/, $_, 3;
 197     my $code = sprintf('\%03o', $classcode{$class});
 198
 199     print DISPATCH "case '$code': throw Xapian::$class(msg, context, error_string);\n";
 200
 201     print HDR <<EOF;
 202
 203 $comment
 204 class XAPIAN_VISIBILITY_DEFAULT $class : public $parent {
 205   public:
 206     /** \@private \@internal
 207      *  \@brief Private constructor for use by remote backend.
 208      *
 209      *  \@param error_string_   Optional string describing error.  May be NULL.
 210      */
 211     $class(const std::string \&msg_, const std::string \&context_, const char * error_string_)
 212         : $parent(msg_, context_, "$code$class", error_string_) {}
 213     /** General purpose constructor.
 214      *
 215      *  \@param msg_            Message giving details of the error, intended
 216      *                          for human consumption.
 217      *  \@param context_        Optional context information for this error.
 218      *  \@param errno_          Optional errno value associated with this error.
 219      */
 220     explicit $class(const std::string \&msg_, const std::string \&context_ = std::string(), int errno_ = 0)
 221         : $parent(msg_, context_, "$code$class", errno_) {}
 222     /** Construct from message and errno value.
 223      *
 224      *  \@param msg_            Message giving details of the error, intended
 225      *                          for human consumption.
 226      *  \@param errno_          Optional errno value associated with this error.
 227      */
 228     $class(const std::string \&msg_, int errno_)
 229         : $parent(msg_, std::string(), "$code$class", errno_) {}
 230   protected:
 231     /** \@private \@internal
 232      *  \@brief Constructor for use by constructors of derived classes.
 233      */
 234     $class(const std::string \&msg_, const std::string \&context_, const char * type_, const char * error_string_)
 235         : $parent(msg_, context_, type_, error_string_) {}
 236
 237     /** \@private \@internal
 238      *  \@brief Constructor for use by constructors of derived classes.
 239      */
 240     $class(const std::string \&msg_, const std::string \&context_, const char * type_, int errno_)
 241         : $parent(msg_, context_, type_, errno_) {}
 242 };
 243 EOF
 244 }
 245
 246 print HDR <<'EOF';
 247
 248 }
 249
 250 #endif /* XAPIAN_INCLUDED_ERROR_H */
 251 EOF
 252
 253 print DISPATCH <<'EOF';
 254 #endif /* DOXYGEN */
 255 EOF
 256
 257 close HDR or die $!;
 258 close DISPATCH or die $!;
 259
 260 # vim: set syntax=perl: