This file is indexed.

/usr/share/perl5/ExtUtils/XSpp/Exception.pm is in libextutils-xspp-perl 0.1602-3.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
package ExtUtils::XSpp::Exception;
use strict;
use warnings;

require ExtUtils::XSpp::Exception::unknown;
require ExtUtils::XSpp::Exception::simple;
require ExtUtils::XSpp::Exception::stdmessage;
require ExtUtils::XSpp::Exception::code;
require ExtUtils::XSpp::Exception::perlcode;
#require ExtUtils::XSpp::Exception::message;
require ExtUtils::XSpp::Exception::object;

=head1 NAME

ExtUtils::XSpp::Exception - Map C++ exceptions to Perl exceptions

=head1 DESCRIPTION

This class is both the base class for the different exception handling
mechanisms and the container for the global set of exception
mappings from C++ exceptions (indicated by a C++ data type to catch)
to Perl exceptions. The Perl exceptions are implemented via C<croak()>.

The basic idea is that you can declare the C++ exception types that
you want to handle and how you plan to do so by using the C<%exception>
directive in your XS++ (or better yet, in the XS++ typemap):

  // OutOfBoundsException would have been declared
  // elsewhere as:
  //
  // class OutOfBoundsException : public std::exception {
  // public:
  //   OutOfBoundsException() {}
  //   virtual const char* what() const throw() {
  //     return "You accessed me out of bounds, fool!";
  //   }
  // }
  
  %exception{outOfBounds}{OutOfBoundsException}{stdmessage};

If you know a function or method may throw C<MyOutOfBoundsException>s, you
can annotate the declaration in your XS++ as follows:

  double get_from_array(unsigned int index)
    %catch{outOfBounds};

When C<get_from_array> now throws an C<OutOfBoundsException>, the user
gets a Perl croak with the message
C<"Caught exception of type 'OutOfBoundsException': You accessed me out of bounds, fool!">.
There may be any number of C<%catch> directives per method.

I<Note:> Why do we assign another name (C<outOfBounds>) to the
existing C<OutOfBoundsException>?
Because you may need to catch exceptions of the same C++ type with different
handlers for different methods. You can, in principle, re-use the C++ exception
class name for the exception I<map> name, but that may be confusing to posterity.

Instead of adding C<%catch> to methods, you may also specify exceptions that
you wish to handle for all methods of a class:

  class Foo %catch{SomeException,AnotherException} {
    ...
  };

The C<%catch{Foo,Bar,...}> syntax is shorthand for C<%catch{Foo} %catch{Bar} ...>.
If there are exceptions to be caught both from the class and attached
to a method directly, the exceptions that are attached to the method only will
be handled first. No single type of exceptions will be handled more than once,
therefore it is safe to use this precedence to re-order the class-global
exception handling for a single method.

If there are no C<%catch> decorators on a method, exceptions derived
from C<std::exception> will be caught with a generic C<stdmessage>
handler such as above. Even if there are C<%catch> clauses for the given method,
all otherwise uncaught exceptions will be caught with a generic error message
for safety.

=head1 Exception handlers

There are different cases of Perl exceptions that are implemented
as sub-classes of C<ExtUtils::XSpp::Exception>:

=over 2

=item L<ExtUtils::XSpp::Exception::simple>

implements the most general case of simply throwing a
generic error message that includes the name of the
C++ exception type.

=item L<ExtUtils::XSpp::Exception::stdmessage>

handles C++ exceptions that are derived from C<std::exception> and
which provide a C<char* what()> method that will provide an error message.
The Perl-level error message will include the C++ exception type name
and the exception's C<what()> message.

=item L<ExtUtils::XSpp::Exception::code>

allows the user to supply custom C/C++/XS code that will be included in
the exception handler verbatim. The code has access to the exception
object as the variable C<e>. Your user supplied code
is expected to propagate the exception to Perl by calling croak().

=cut

=begin comment

=item L<ExtUtils::XSpp::Exception::message>

translates C++ exceptions to Perl error messages using a printf-like
mask for the message. Potentially filling in place-holders by calling
methods on the C++ exception object(!). Not yet implemented.
Details to be hammered out.

=end comment

=item L<ExtUtils::XSpp::Exception::object>

maps C++ exceptions to throwing an instance of some Perl exception class.

Syntax:

  %exception{myClassyException}{CppException}{object}{PerlClass};

Currently, this means just calling C<PerlClass-E<gt>new()> and
then die()ing with that object in C<$@>. There is no good way to pass
information from the C++ exception object to the Perl object.
Will change in future.

=item L<ExtUtils::XSpp::Exception::unknown>

is the default exception handler that is added to the list of handlers
automatically during code generation. It simply throws an entirely
unspecific error and catches the type C<...> (meaning I<anything>).

=cut

=begin comment

=item L<ExtUtils::XSpp::Exception::perlcode>

allows the user to supply custom Perl code that will be executed
in the exception handler. The code currently has no access to the
C++ exception object. It is supposed to return a scalar value
that is assigned to C<$@>.
Highly experimental.

=end comment

=back

There is a special exception handler C<nothing> which is always
available:

  int foo() %catch{nothing};

It indicates that the given method (or function) is to handle no
exceptions. It squishes any exception handlers that might otherwise
be inherited from the method's class.

=head1 METHODS

=cut

=head2 new

Creates a new C<ExtUtils::XSpp::Exception>.

Calls the C<$self-E<gt>init(@_)> method after construction.
C<init()> must be overridden in subclasses.

=cut

sub new {
  my $class = shift;
  my $this = bless {}, $class;

  $this->init( @_ );

  return $this;
}

sub init {
  my $self = shift;
  my %args = @_;
  $self->{TYPE} = $args{type};
  $self->{NAME} = $args{name};
}

=head2 handler_code

Unimplemented in this base class, but must be implemented
in all actual exception classes.

Generates the C<catch(){}> block of code for inclusion
in the XS output. First (optional) argument is an integer indicating
the number of spaces to use for the first indentation level.

=cut

sub handler_code {
  Carp::croak("Programmer left 'handler_code' method of his Exception subclass unimplemented");  
}

=head2 indent_code

Given a piece of code and a number of spaces to use for
global indentation, indents the code and returns it.

=cut

sub indent_code {
  my $this = shift;
  my $code = shift;
  my $n = shift;
  my $indent = " " x $n;
  $code =~ s/^/$indent/gm;
  return $code;
}

=head2 cpp_type

Fetches the C++ type of the exception from the C<type> attribute and returns it.

=cut

# TODO: Strip pointers and references
sub cpp_type {
  my $this = shift;
  return $this->type->print;
}

=head1 ACCESSORS

=head2 name

Returns the name of the exception.
This is the C<myException> in C<%exception{myException}{char*}{handler}>.

=cut

sub name { $_[0]->{NAME} }

=head2 type

Returns the L<ExtUtils::XSpp::Node::Type> C++ type that is used for this exception.
This is the C<char*> in C<%exception{myException}{char*}{handler}>.

=cut

sub type { $_[0]->{TYPE} }


=head1 CLASS METHODS

=cut

my %ExceptionsByName;
#my %ExceptionsByType;

=head2 add_exception

Given an C<ExtUtils::XSpp::Exception> object,
adds this object to the global registry, potentially
overwriting an exception map of the same name that was
in effect before.

=cut

sub add_exception {
  my ($class, $exception) = @_;

  $ExceptionsByName{$exception->name} = $exception;
  #push @{$ExceptionsByType{$exception->print} }, $exception;
  return();
}

=head2 get_exception_for_name

Given the XS++ name of the exception map, fetches
the corresponding C<ExtUtils::XSpp::Exception> object
from the global registry and returns it. Croaks on error.

=cut

sub get_exception_for_name {
  my ($class, $name) = @_;

  if (not exists $ExceptionsByName{$name}) {
    Carp::confess( "No Exception with the name $name declared" );
  }
  return $ExceptionsByName{$name};
}


1;