xapian-core/exception_data.pm

   1 # exception_data.pm: details of the exception hierarchy used by Xapian.
   2 package exception_data;
   3 $copyright = <<'EOF';
   4 /* Copyright (C) 2003,2004,2006,2007,2008,2009,2011,2015,2019 Olly Betts
   5  * Copyright (C) 2007 Richard Boulton
   6  *
   7  * This program is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License as
   9  * published by the Free Software Foundation; either version 2 of the
  10  * License, or (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
  20  */
  21 EOF
  22
  23 use Exporter;
  24 @ISA = qw(Exporter);
  25 @EXPORT = qw(
  26     $copyright $generated_warning @baseclasses @classes %subclasses %classcode
  27 );
  28
  29 $generated_warning =
  30 "/* Warning: This file is generated by $0 - do not modify directly! */\n";
  31
  32 @baseclasses = ();
  33 @classes = ();
  34 %subclasses = ();
  35 %classcode = ();
  36
  37 sub errorbaseclass {
  38     push @baseclasses, \@_;
  39     push @{$subclasses{$_[1]}}, $_[0];
  40 }
  41
  42 sub errorclass {
  43     my $typecode = shift;
  44     my ($class, $parent) = @_;
  45     push @classes, \@_;
  46     push @{$subclasses{$parent}}, $class;
  47     $classcode{$class} = $typecode;
  48 }
  49
  50 errorbaseclass('LogicError', 'Error',
  51                'The base class for exceptions indicating errors in the program logic.',
  52                <<'DOC');
  53 A subclass of LogicError will be thrown if Xapian detects a violation
  54 of a class invariant or a logical precondition or postcondition, etc.
  55 DOC
  56
  57 errorclass(0, 'AssertionError', 'LogicError',
  58            'AssertionError is thrown if a logical assertion inside Xapian fails.',
  59            <<'DOC');
  60 In a debug build of Xapian, a failed assertion in the core library code
  61 will cause AssertionError to be thrown.
  62
  63 This represents a bug in Xapian (either an invariant, precondition, etc
  64 has been violated, or the assertion is incorrect!)
  65 DOC
  66
  67 errorclass(1, 'InvalidArgumentError', 'LogicError',
  68            'InvalidArgumentError indicates an invalid parameter value was passed to the API.',
  69            '');
  70
  71 errorclass(2, 'InvalidOperationError', 'LogicError',
  72            'InvalidOperationError indicates the API was used in an invalid way.',
  73            '');
  74
  75 errorclass(3, 'UnimplementedError', 'LogicError',
  76            'UnimplementedError indicates an attempt to use an unimplemented feature.',
  77            '');
  78
  79 # RuntimeError and subclasses:
  80
  81 errorbaseclass('RuntimeError', 'Error',
  82                'The base class for exceptions indicating errors only detectable at runtime.',
  83                <<'DOC');
  84 A subclass of RuntimeError will be thrown if Xapian detects an error
  85 which is exception derived from RuntimeError is thrown when an
  86 error is caused by problems with the data or environment rather
  87 than a programming mistake.
  88 DOC
  89
  90 errorclass(4, 'DatabaseError', 'RuntimeError',
  91            'DatabaseError indicates some sort of database related error.',
  92            '');
  93
  94 errorclass(5, 'DatabaseCorruptError', 'DatabaseError',
  95            'DatabaseCorruptError indicates database corruption was detected.',
  96            '');
  97
  98 errorclass(6, 'DatabaseCreateError', 'DatabaseError',
  99            'DatabaseCreateError indicates a failure to create a database.',
 100            '');
 101
 102 errorclass(7, 'DatabaseLockError', 'DatabaseError',
 103            'DatabaseLockError indicates failure to lock a database.',
 104            '');
 105
 106 errorclass(8, 'DatabaseModifiedError', 'DatabaseError',
 107            'DatabaseModifiedError indicates a database was modified.',
 108            <<'DOC');
 109 To recover after catching this error, you need to call
 110 Xapian::Database::reopen() on the Database and repeat the operation
 111 which failed.
 112 DOC
 113
 114 errorclass(9, 'DatabaseOpeningError', 'DatabaseError',
 115            'DatabaseOpeningError indicates failure to open a database.',
 116            '');
 117
 118 errorclass(10, 'DatabaseVersionError', 'DatabaseOpeningError',
 119            'DatabaseVersionError indicates that a database is in an unsupported format.',
 120            <<'DOC');
 121 From time to time, new versions of Xapian will require the database format
 122 to be changed, to allow new information to be stored or new optimisations
 123 to be performed.  Backwards compatibility will sometimes be maintained, so
 124 that new versions of Xapian can open old databases, but in some cases
 125 Xapian will be unable to open a database because it is in too old (or new)
 126 a format.  This can be resolved either be upgrading or downgrading the
 127 version of Xapian in use, or by rebuilding the database from scratch with
 128 the current version of Xapian.
 129 DOC
 130
 131 errorclass(11, 'DocNotFoundError', 'RuntimeError',
 132            'Indicates an attempt to access a document not present in the database.',
 133            '');
 134
 135 errorclass(12, 'FeatureUnavailableError', 'RuntimeError',
 136            'Indicates an attempt to use a feature which is unavailable.',
 137            <<'DOC');
 138 Typically a feature is unavailable because it wasn't compiled in, or
 139 because it requires other software or facilities which aren't available.
 140 DOC
 141
 142 errorclass(13, 'InternalError', 'RuntimeError',
 143            'InternalError indicates a runtime problem of some sort.',
 144            '');
 145
 146 errorclass(14, 'NetworkError', 'RuntimeError',
 147            'Indicates a problem communicating with a remote database.',
 148            '');
 149
 150 errorclass(15, 'NetworkTimeoutError', 'NetworkError',
 151            'Indicates a timeout expired while communicating with a remote database.',
 152            '');
 153
 154 errorclass(16, 'QueryParserError', 'RuntimeError',
 155            "Indicates a query string can't be parsed.",
 156            '');
 157
 158 errorclass(17, 'SerialisationError', 'RuntimeError',
 159            'Indicates an error in the std::string serialisation of an object.',
 160            '');
 161
 162 errorclass(18, 'RangeError', 'RuntimeError',
 163            'RangeError indicates an attempt to access outside the bounds of a container.',
 164            '');
 165
 166 errorclass(19, 'WildcardError', 'RuntimeError',
 167            'WildcardError indicates an error expanding a wildcarded query.',
 168            '');
 169
 170 errorclass(20, 'DatabaseNotFoundError', 'DatabaseOpeningError',
 171            'Indicates an attempt to access a database not present.',
 172            '');
 173
 174 errorclass(21, 'DatabaseClosedError', 'DatabaseError',
 175            'Indicates an attempt to access a closed database.',
 176            '');
 177
 178 sub for_each_nothrow {
 179     my $func = shift @_;
 180     my $class = '';
 181     foreach my $header ('include/xapian.h', <include/xapian/*.h>) {
 182         local $/ = undef;
 183         open H, '<', $header or die $!;
 184         my $header_text = <H>;
 185         # Strip comments, which might contain text describing XAPIAN_NOTHROW().
 186         $header_text =~ s!/(?:/[^\n]*|\*.*?\*/)! !gs;
 187         for (split /\n/, $header_text) {
 188             if (/^\s*class\s+XAPIAN_VISIBILITY_DEFAULT\s+(\w+)/) {
 189                 $class = "$1::";
 190                 &$func("Xapian::$class~$1");
 191                 next;
 192             }
 193             if (/^[^#]*\bXAPIAN_NOTHROW\(([^~].*)\)/) {
 194                 &$func("Xapian::$class$1");
 195             }
 196         }
 197         close H;
 198     }
 199 }
 200
 201 1;