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,2017 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 /** All exceptions thrown by Xapian are subclasses of Xapian::Error.
  56  *
  57  *  This class can not be instantiated directly - instead a subclass should
  58  *  be used.
  59  */
  60 class XAPIAN_VISIBILITY_DEFAULT Error {
  61     /// Message giving details of the error, intended for human consumption.
  62     std::string msg;
  63
  64     /** Optional context information.
  65      *
  66      *  This context is intended for machine use (for example to know which
  67      *  remote server an error came from), but it is typically a
  68      *  plain-text string, and so also fit for human consumption.
  69      */
  70     std::string context;
  71
  72     /** The error string derived from my_errno.
  73      *
  74      *  This string is generated from my_errno lazily.
  75      */
  76     mutable std::string error_string;
  77
  78     /// The type of this error (e.g. DocNotFoundError.)
  79     const char * type;
  80
  81     /** Optional value of 'errno' associated with this error.
  82      *
  83      *  If no value is associated, this member variable will be 0.
  84      *
  85      *  On UNIX, if this value is < 0, it's an error code returned from
  86      *  getaddrinfo() (negated if such error codes are positive).
  87      *
  88      *  On Windows, if this value is < 0, it's a negated Windows error code
  89      *  (as given by GetLastError()), while if it is >= WSABASEERR then it is a
  90      *  WinSock error code (as given by WSAGetLastError()).  Prior to Xapian
  91      *  1.2.20 and 1.3.3, WSAGetLastError() codes were also negated.
  92      *
  93      *  NB We don't just call this member "errno" to avoid problems on
  94      *  platforms where errno is a preprocessor macro.
  95      */
  96     int my_errno;
  97
  98     /// Don't allow assignment of the base class.
  99     void operator=(const Error &o);
 100
 101   protected:
 102     /** @private @internal
 103      *  @brief Constructor for use by constructors of derived classes.
 104      */
 105     Error(const std::string &msg_, const std::string &context_,
 106           const char * type_, const char * error_string_);
 107
 108     /** @private @internal
 109      *  @brief Constructor for use by constructors of derived classes.
 110      */
 111     Error(const std::string &msg_, const std::string &context_,
 112           const char * type_, int errno_)
 113         : msg(msg_), context(context_), error_string(), type(type_),
 114           my_errno(errno_) { }
 115
 116   public:
 117     /// The type of this error (e.g. "DocNotFoundError".)
 118     const char * XAPIAN_NOTHROW(get_type() const) {
 119         return type + 1;
 120     }
 121
 122     /// Message giving details of the error, intended for human consumption.
 123     const std::string & XAPIAN_NOTHROW(get_msg() const) {
 124         return msg;
 125     }
 126
 127     /** Optional context information.
 128      *
 129      *  This context is intended for machine use (for example to know which
 130      *  remote server an error came from), but it is typically a
 131      *  plain-text string, and so also fit for human consumption.
 132      */
 133     const std::string & XAPIAN_NOTHROW(get_context() const) {
 134         return context;
 135     }
 136
 137     /** Returns any system error string associated with this exception.
 138      *
 139      *  The system error string may come from errno, h_errno (on UNIX), or
 140      *  GetLastError() (on MS Windows).  If there is no associated system
 141      *  error string, NULL is returned.
 142      */
 143     const char * get_error_string() const;
 144
 145     /// Return a string describing this object.
 146     std::string get_description() const;
 147 };
 148 EOF
 149
 150 print DISPATCH <<'EOF';
 151
 152 /* Note that this file isn't an external header - it's located in
 153  * include/xapian in the source tree because it's generated so this
 154  * is the simplest way to make inclusion work in a VPATH build.
 155  */
 156
 157 // DOXYGEN gets confused by this header-with-code.
 158 #ifndef DOXYGEN
 159 EOF
 160
 161 for (@baseclasses) {
 162     chomp;
 163     my ($class, $parent, $comment) = split /\t/, $_, 3;
 164     print HDR <<EOF;
 165
 166 $comment
 167 class XAPIAN_VISIBILITY_DEFAULT $class : public $parent {
 168   protected:
 169     /** \@private \@internal
 170      *  \@brief Constructor for use by constructors of derived classes.
 171      */
 172     $class(const std::string \&msg_, const std::string \&context_, const char * type_, const char * error_string_)
 173         : $parent(msg_, context_, type_, error_string_) {}
 174
 175     /** \@private \@internal
 176      *  \@brief Constructor for use by constructors of derived classes.
 177      */
 178     $class(const std::string \&msg_, const std::string \&context_, const char * type_, int errno_)
 179         : $parent(msg_, context_, type_, errno_) {}
 180 };
 181 EOF
 182 }
 183
 184 for (@classes) {
 185     chomp;
 186     my ($class, $parent, $comment) = split /\t/, $_, 3;
 187     my $code = sprintf('\%03o', $classcode{$class});
 188
 189     print DISPATCH "case '$code': throw Xapian::$class(msg, context, error_string);\n";
 190
 191     print HDR <<EOF;
 192
 193 $comment
 194 class XAPIAN_VISIBILITY_DEFAULT $class : public $parent {
 195   public:
 196     /** \@private \@internal
 197      *  \@brief Private constructor for use by remote backend.
 198      *
 199      *  \@param error_string_   Optional string describing error.  May be NULL.
 200      */
 201     $class(const std::string \&msg_, const std::string \&context_, const char * error_string_)
 202         : $parent(msg_, context_, "$code$class", error_string_) {}
 203     /** General purpose constructor.
 204      *
 205      *  \@param msg_            Message giving details of the error, intended
 206      *                          for human consumption.
 207      *  \@param context_        Optional context information for this error.
 208      *  \@param errno_          Optional errno value associated with this error.
 209      */
 210     explicit $class(const std::string \&msg_, const std::string \&context_ = std::string(), int errno_ = 0)
 211         : $parent(msg_, context_, "$code$class", errno_) {}
 212     /** Construct from message and errno value.
 213      *
 214      *  \@param msg_            Message giving details of the error, intended
 215      *                          for human consumption.
 216      *  \@param errno_          Optional errno value associated with this error.
 217      */
 218     $class(const std::string \&msg_, int errno_)
 219         : $parent(msg_, std::string(), "$code$class", errno_) {}
 220   protected:
 221     /** \@private \@internal
 222      *  \@brief Constructor for use by constructors of derived classes.
 223      */
 224     $class(const std::string \&msg_, const std::string \&context_, const char * type_, const char * error_string_)
 225         : $parent(msg_, context_, type_, error_string_) {}
 226
 227     /** \@private \@internal
 228      *  \@brief Constructor for use by constructors of derived classes.
 229      */
 230     $class(const std::string \&msg_, const std::string \&context_, const char * type_, int errno_)
 231         : $parent(msg_, context_, type_, errno_) {}
 232 };
 233 EOF
 234 }
 235
 236 print HDR <<'EOF';
 237
 238 }
 239
 240 #endif /* XAPIAN_INCLUDED_ERROR_H */
 241 EOF
 242
 243 print DISPATCH <<'EOF';
 244 #endif /* DOXYGEN */
 245 EOF
 246
 247 close HDR or die $!;
 248 close DISPATCH or die $!;
 249
 250 # vim: set syntax=perl: