/usr/share/perl5/HTTP/Exception.pm is in libhttp-exception-perl 0.04004-2.
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 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 | package HTTP::Exception;
{
$HTTP::Exception::VERSION = '0.04004';
}
use strict;
use HTTP::Status;
use Scalar::Util qw(blessed);
################################################################################
sub import {
my ($class) = shift;
require HTTP::Exception::Loader;
HTTP::Exception::Loader->import(@_);
}
# act as a kind of factory here
sub new {
my $class = shift;
my $error_code = shift;
die ('HTTP::Exception->throw needs a HTTP-Statuscode to throw') unless ($error_code);
die ("Unknown HTTP-Statuscode: $error_code") unless (HTTP::Status::status_message ($error_code));
"HTTP::Exception::$error_code"->new(@_);
}
# makes HTTP::Exception->caught possible instead of HTTP::Exception::Base->caught
sub caught {
my $self = shift;
my $e = $@;
return $e if (blessed $e && $e->isa('HTTP::Exception::Base'));
$self->SUPER::caught(@_);
}
1;
=head1 NAME
HTTP::Exception - throw HTTP-Errors as (Exception::Class-) Exceptions
=head1 VERSION
version 0.04004
=begin readme
=head1 INSTALLATION
To install this module, run the following commands:
perl Build.PL
./Build
./Build test
./Build install
=end readme
=head1 SYNOPSIS
HTTP::Exception lets you throw HTTP-Errors as Exceptions.
use HTTP::Exception;
# throw a 404 Exception
HTTP::Exception->throw(404);
# later in your framework
eval { ... };
if (my $e = HTTP::Exception->caught) {
# do some errorhandling stuff
print $e->code; # 404
print $e->status_message; # Not Found
}
You can also throw HTTP::Exception-subclasses like this.
# same 404 Exception
eval { HTTP::Exception::404->throw(); };
eval { HTTP::Exception::NOT_FOUND->throw(); };
And catch them accordingly.
# same 404 Exception
eval { HTTP::Exception::404->throw(); };
if (my $e = HTTP::Exception::405->caught) { do stuff } # won't catch
if (my $e = HTTP::Exception::404->caught) { do stuff } # will catch
if (my $e = HTTP::Exception::NOT_FOUND->caught) { do stuff } # will catch
if (my $e = HTTP::Exception::4XX->caught) { do stuff } # will catch all 4XX Exceptions
if (my $e = HTTP::Exception->caught) { do stuff } # will catch every HTTP::Exception
if (my $e = Exception::Class->caught) { do stuff } # catch'em all
You can create Exceptions and not throw them, because maybe you want to set some
fields manually. See L<HTTP::Exception/"FIELDS"> and
L<HTTP::Exception/"ACCESSORS"> for more info.
# is not thrown, ie doesn't die, only created
my $e = HTTP::Exception->new(404);
# usual stuff works
$e->code; # 404
$e->status_message # Not Found
# set status_message to something else
$e->status_message('Nothing Here')
# fails, because code is only an accessor, see section ACCESSORS below
# $e->code(403);
# and finally throw our prepared exception
$e->throw;
=head1 DESCRIPTION
Every HTTP::Exception is a L<Exception::Class> - Class. So the same mechanisms
apply as with L<Exception::Class>-classes. In fact have a look at
L<Exception::Class>' docs for more general information on exceptions and
L<Exception::Class::Base> for information on what methods a caught exception
also has.
HTTP::Exception is only a factory for HTTP::Exception::XXX (where X is a number)
subclasses. That means that HTTP::Exception->new(404) returns a
HTTP::Exception::404 object, which in turn is a HTTP::Exception::Base - Object.
Don't bother checking a caught HTTP::Exception::...-class with "isa" as it might
not contain what you would expect. Use the code- or status_message-attributes
and the is_ -methods instead.
The subclasses are created at compile-time, ie the first time you make
"use HTTP::Exception". See paragraph below for the naming scheme of those
subclasses.
Subclassing the subclasses works as expected.
=head1 NAMING SCHEME
=head2 HTTP::Exception::XXX
X is a Number and XXX is a valid HTTP-Statuscode. All HTTP-Statuscodes are
supported. See chapter L<HTTP::Exception/"COMPLETENESS">
=head2 HTTP::Exception::STATUS_MESSAGE
STATUS_MESSAGE is the same name as a L<HTTP::Status> Constant B<WITHOUT>
the HTTP_ at the beginning. So see L<HTTP::Status/"CONSTANTS"> for more details.
=head1 IMPORTING SPECIFIC ERROR RANGES
It is possible to load only specific ranges of errors. For example
use HTTP::Exception qw(5XX);
HTTP::Exception::500->throw; # works
HTTP::Exception::400->throw; # won't work anymore
will only create HTTP::Exception::500 till HTTP::Exception::510. In theory this
should save some memory, but I don't have any numbers, that back up this claim.
You can load multiple ranges
use HTTP::Exception qw(3XX 4XX 5XX);
And there are aliases for ranges
use HTTP::Exception qw(CLIENT_ERROR)
The following aliases exist and load the specified ranges:
REDIRECTION => 3XX
CLIENT_ERROR => 4XX
SERVER_ERROR => 5XX
ERROR => 4XX 5XX
ALL => 1XX 2XX 3XX 4XX 5XX
And of course, you can load multiple aliased ranges
use HTTP::Exception qw(REDIRECTION ERROR)
ALL is the same as not specifying any specific range.
# the same
use HTTP::Exception qw(ALL);
use HTTP::Exception;
=head1 ACCESSORS (READONLY)
=head2 code
A valid HTTP-Statuscode. See L<HTTP::Status> for information on what codes exist.
=head2 is_info
Return TRUE if C<$self->code> is an I<Informational> status code (1xx). This
class of status code indicates a provisional response which can't have
any content.
=head2 is_success
Return TRUE if C<$self->code> is a I<Successful> status code (2xx).
=head2 is_redirect
Return TRUE if C<$self->code> is a I<Redirection> status code (3xx). This class
if status code indicates that further action needs to be taken by the
user agent in order to fulfill the request.
=head2 is_error
Return TRUE if C<$self->code> is an I<Error> status code (4xx or 5xx). The
function return TRUE for both client error or a server error status codes.
=head2 is_client_error
Return TRUE if C<$self->code> is an I<Client Error> status code (4xx). This
class of status code is intended for cases in which the client seems to
have erred.
=head2 is_server_error
Return TRUE if C<$self->code> is an I<Server Error> status code (5xx). This
class of status codes is intended for cases in which the server is aware
that it has erred or is incapable of performing the request.
I<POD for is_ methods is Copy/Pasted from L<HTTP::Status>, so check back there and
alert me of changes.>
=head1 FIELDS
Fields are the same as ACCESSORS except they can be set. Either you set them
during Exception creation (->new) or Exception throwing (->throw).
HTTP::Exception->new(200, status_message => "Everything's fine");
HTTP::Exception::200->new(status_message => "Everything's fine");
HTTP::Exception::OK->new(status_message => "Everything's fine");
HTTP::Exception->throw(200, status_message => "Everything's fine");
HTTP::Exception::200->throw(status_message => "Everything's fine");
HTTP::Exception::OK->throw(status_message => "Everything's fine");
Catch them in your Webframework like this
eval { ... }
if (my $e = HTTP::Exception->caught) {
print $e->code; # 200
print $e->status_message # "Everything's fine" instead of the usual ok
}
=head2 status_message
B<DEFAULT> The HTTP-Statusmessage as provided by L<HTTP::Status>
A Message, that represents the Execptions' Status for Humans.
=head1 PLACK
HTTP::Exception can be used with L<Plack::Middleware::HTTPExceptions>. But
HTTP::Exception does not depend on L<Plack>, you can use it anywhere else. It
just plays nicely with L<Plack>.
=head1 COMPLETENESS
For the sake of completeness, HTTP::Exception provides exceptions for
non-error-http-statuscodes. This means you can do
HTTP::Exception->throw(200);
which throws an Exception of type OK. Maybe useless, but complete.
A more realworld-example would be a redirection
# all are exactly the same
HTTP::Exception->throw(301, location => 'google.com');
HTTP::Exception::301->throw(location => 'google.com');
HTTP::Exception::MOVED_PERMANENTLY->throw(location => 'google.com');
=head1 CAVEATS
The HTTP::Exception-Subclass-Creation relies on L<HTTP::Status>.
It's possible that the Subclasses change, when HTTP::Status'
constants are changed.
New Subclasses are created automatically, when constants are added to
HTTP::Status. That means in turn, that Subclasses disappear, when constants
are removed from L<HTTP::Status>.
Some constants were added to L<HTTP::Status>' in February 2012. As a result
HTTP::Exception broke. But that was the result of uncareful coding on my side.
I think, that breaking changes are now quite unlikely.
=head1 AUTHOR
Thomas Mueller, C<< <tmueller at cpan.org> >>
=head1 SEE ALSO
=head2 L<Exception::Class>, L<Exception::Class::Base>
Consult Exception::Class' documentation for the Exception-Mechanism and
Exception::Class::Base' docs for a list of methods our caught Exception is also
capable of.
=head2 L<HTTP::Status>
Constants, Statuscodes and Statusmessages
=head2 L<Plack>, especially L<Plack::Middleware::HTTPExceptions>
Have a look at Plack, because it rules in general. In the first place, this
Module was written as the companion for L<Plack::Middleware::HTTPExceptions>,
but since it doesn't depend on Plack, you can use it anywhere else, too.
=head1 BUGS
Please report any bugs or feature requests to
C<bug-http-exception at rt.cpan.org>, or through the web interface at
L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=HTTP-Exception>.
I will be notified, and then you'll automatically be notified of progress on
your bug as I make changes.
=head1 SUPPORT
You can find documentation for this module with the perldoc command.
perldoc HTTP::Exception
You can also look for information at:
=over 4
=item * RT: CPAN's request tracker
L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=HTTP-Exception>
=item * AnnoCPAN: Annotated CPAN documentation
L<http://annocpan.org/dist/HTTP-Exception>
=item * CPAN Ratings
L<http://cpanratings.perl.org/d/HTTP-Exception>
=item * Search CPAN
L<https://metacpan.org/release/HTTP-Exception>
=back
=head1 LICENSE AND COPYRIGHT
Copyright 2010 Thomas Mueller.
This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.
=cut
|