.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "HTTP::Exception 3pm"
.TH HTTP::Exception 3pm "2018-07-28" "perl v5.26.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
HTTP::Exception \- throw HTTP\-Errors as (Exception::Class\-) Exceptions
.SH "VERSION"
.IX Header "VERSION"
version 0.04007
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
HTTP::Exception lets you throw HTTP-Errors as Exceptions.
.PP
.Vb 1
\&    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
\&    }
.Ve
.PP
You can also throw HTTP::Exception\-subclasses like this.
.PP
.Vb 3
\&    # same 404 Exception
\&    eval { HTTP::Exception::404\->throw(); };
\&    eval { HTTP::Exception::NOT_FOUND\->throw(); };
.Ve
.PP
And catch them accordingly.
.PP
.Vb 2
\&    # same 404 Exception
\&    eval { HTTP::Exception::404\->throw(); };
\&
\&    if (my $e = HTTP::Exception::405\->caught)       { do stuff } # won\*(Aqt 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\*(Aqem all
.Ve
.PP
You can create Exceptions and not throw them, because maybe you want to set some
fields manually. See \*(L"\s-1FIELDS\*(R"\s0 in HTTP::Exception and
\&\*(L"\s-1ACCESSORS\*(R"\s0 in HTTP::Exception for more info.
.PP
.Vb 2
\&    # is not thrown, ie doesn\*(Aqt 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(\*(AqNothing Here\*(Aq)
\&
\&    # fails, because code is only an accessor, see section ACCESSORS below
\&    # $e\->code(403);
\&
\&    # and finally throw our prepared exception
\&    $e\->throw;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Every HTTP::Exception is a Exception::Class \- Class. So the same mechanisms
apply as with Exception::Class\-classes. In fact have a look at
Exception::Class' docs for more general information on exceptions and
Exception::Class::Base for information on what methods a caught exception
also has.
.PP
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.
.PP
Don't bother checking a caught HTTP::Exception::...\-class with \*(L"isa\*(R" as it might
not contain what you would expect. Use the code\- or status_message\-attributes
and the is_ \-methods instead.
.PP
The subclasses are created at compile-time, ie the first time you make
\&\*(L"use HTTP::Exception\*(R". See paragraph below for the naming scheme of those
subclasses.
.PP
Subclassing the subclasses works as expected.
.SH "NAMING SCHEME"
.IX Header "NAMING SCHEME"
.SS "HTTP::Exception::XXX"
.IX Subsection "HTTP::Exception::XXX"
X is a Number and \s-1XXX\s0 is a valid HTTP-Statuscode. All HTTP-Statuscodes are
supported. See chapter \*(L"\s-1COMPLETENESS\*(R"\s0 in HTTP::Exception
.SS "HTTP::Exception::STATUS_MESSAGE"
.IX Subsection "HTTP::Exception::STATUS_MESSAGE"
\&\s-1STATUS_MESSAGE\s0 is the same name as a HTTP::Status Constant \fB\s-1WITHOUT\s0\fR
the \s-1HTTP_\s0 at the beginning. So see \*(L"\s-1CONSTANTS\*(R"\s0 in HTTP::Status for more details.
.SH "IMPORTING SPECIFIC ERROR RANGES"
.IX Header "IMPORTING SPECIFIC ERROR RANGES"
It is possible to load only specific ranges of errors. For example
.PP
.Vb 1
\&    use HTTP::Exception qw(5XX);
\&
\&    HTTP::Exception::500\->throw; # works
\&    HTTP::Exception::400\->throw; # won\*(Aqt work anymore
.Ve
.PP
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.
.PP
You can load multiple ranges
.PP
.Vb 1
\&    use HTTP::Exception qw(3XX 4XX 5XX);
.Ve
.PP
And there are aliases for ranges
.PP
.Vb 1
\&    use HTTP::Exception qw(CLIENT_ERROR)
.Ve
.PP
The following aliases exist and load the specified ranges:
.PP
.Vb 5
\&    REDIRECTION   => 3XX
\&    CLIENT_ERROR  => 4XX
\&    SERVER_ERROR  => 5XX
\&    ERROR         => 4XX 5XX
\&    ALL           => 1XX 2XX 3XX 4XX 5XX
.Ve
.PP
And of course, you can load multiple aliased ranges
.PP
.Vb 1
\&    use HTTP::Exception qw(REDIRECTION ERROR)
.Ve
.PP
\&\s-1ALL\s0 is the same as not specifying any specific range.
.PP
.Vb 3
\&    # the same
\&    use HTTP::Exception qw(ALL);
\&    use HTTP::Exception;
.Ve
.SH "ACCESSORS (READONLY)"
.IX Header "ACCESSORS (READONLY)"
.SS "code"
.IX Subsection "code"
A valid HTTP-Statuscode. See HTTP::Status for information on what codes exist.
.SS "is_info"
.IX Subsection "is_info"
Return \s-1TRUE\s0 if \f(CW\*(C`$self\-\*(C'\fRcode> is an \fIInformational\fR status code (1xx).  This
class of status code indicates a provisional response which can't have
any content.
.SS "is_success"
.IX Subsection "is_success"
Return \s-1TRUE\s0 if \f(CW\*(C`$self\-\*(C'\fRcode> is a \fISuccessful\fR status code (2xx).
.SS "is_redirect"
.IX Subsection "is_redirect"
Return \s-1TRUE\s0 if \f(CW\*(C`$self\-\*(C'\fRcode> is a \fIRedirection\fR 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.
.SS "is_error"
.IX Subsection "is_error"
Return \s-1TRUE\s0 if \f(CW\*(C`$self\-\*(C'\fRcode> is an \fIError\fR status code (4xx or 5xx).  The
function return \s-1TRUE\s0 for both client error or a server error status codes.
.SS "is_client_error"
.IX Subsection "is_client_error"
Return \s-1TRUE\s0 if \f(CW\*(C`$self\-\*(C'\fRcode> is an \fIClient Error\fR status code (4xx). This
class of status code is intended for cases in which the client seems to
have erred.
.SS "is_server_error"
.IX Subsection "is_server_error"
Return \s-1TRUE\s0 if \f(CW\*(C`$self\-\*(C'\fRcode> is an \fIServer Error\fR 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.
.PP
\&\fI\s-1POD\s0 for is_ methods is Copy/Pasted from HTTP::Status, so check back there and
alert me of changes.\fR
.SH "FIELDS"
.IX Header "FIELDS"
Fields are the same as \s-1ACCESSORS\s0 except they can be set. Either you set them
during Exception creation (\->new) or Exception throwing (\->throw).
.PP
.Vb 3
\&    HTTP::Exception\->new(200, status_message => "Everything\*(Aqs fine");
\&    HTTP::Exception::200\->new(status_message => "Everything\*(Aqs fine");
\&    HTTP::Exception::OK\->new(status_message => "Everything\*(Aqs fine");
\&
\&    HTTP::Exception\->throw(200, status_message => "Everything\*(Aqs fine");
\&    HTTP::Exception::200\->throw(status_message => "Everything\*(Aqs fine");
\&    HTTP::Exception::OK\->throw(status_message => "Everything\*(Aqs fine");
.Ve
.PP
Catch them in your Webframework like this
.PP
.Vb 5
\&    eval { ... }
\&    if (my $e = HTTP::Exception\->caught) {
\&        print $e\->code;          # 200
\&        print $e\->status_message # "Everything\*(Aqs fine" instead of the usual ok
\&    }
.Ve
.SS "status_message"
.IX Subsection "status_message"
\&\fB\s-1DEFAULT\s0\fR The HTTP-Statusmessage as provided by HTTP::Status
.PP
A Message, that represents the Execptions' Status for Humans.
.SH "PLACK"
.IX Header "PLACK"
HTTP::Exception can be used with Plack::Middleware::HTTPExceptions. But
HTTP::Exception does not depend on Plack, you can use it anywhere else. It
just plays nicely with Plack.
.SH "COMPLETENESS"
.IX Header "COMPLETENESS"
For the sake of completeness, HTTP::Exception provides exceptions for
non-error-http-statuscodes. This means you can do
.PP
.Vb 1
\&    HTTP::Exception\->throw(200);
.Ve
.PP
which throws an Exception of type \s-1OK.\s0 Maybe useless, but complete.
A more realworld-example would be a redirection
.PP
.Vb 4
\&    # all are exactly the same
\&    HTTP::Exception\->throw(301, location => \*(Aqgoogle.com\*(Aq);
\&    HTTP::Exception::301\->throw(location => \*(Aqgoogle.com\*(Aq);
\&    HTTP::Exception::MOVED_PERMANENTLY\->throw(location => \*(Aqgoogle.com\*(Aq);
.Ve
.SH "CAVEATS"
.IX Header "CAVEATS"
The HTTP::Exception\-Subclass\-Creation relies on HTTP::Status.
It's possible that the Subclasses change, when HTTP::Status'
constants are changed.
.PP
New Subclasses are created automatically, when constants are added to
HTTP::Status. That means in turn, that Subclasses disappear, when constants
are removed from HTTP::Status.
.PP
Some constants were added to 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.
.SH "AUTHOR"
.IX Header "AUTHOR"
Thomas Mueller, \f(CW\*(C`<tmueller at cpan.org>\*(C'\fR
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.SS "Exception::Class, Exception::Class::Base"
.IX Subsection "Exception::Class, 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.
.SS "HTTP::Status"
.IX Subsection "HTTP::Status"
Constants, Statuscodes and Statusmessages
.SS "HTTP::Throwable, built on top of the more modern Throwable framework (the successor to Exception::Class)"
.IX Subsection "HTTP::Throwable, built on top of the more modern Throwable framework (the successor to Exception::Class)"
.SS "Plack, especially Plack::Middleware::HTTPExceptions"
.IX Subsection "Plack, especially 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 Plack::Middleware::HTTPExceptions,
but since it doesn't depend on Plack, you can use it anywhere else, too.
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-http\-exception at rt.cpan.org\*(C'\fR, or through the web interface at
<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.
.SH "SUPPORT"
.IX Header "SUPPORT"
You can find documentation for this module with the perldoc command.
.PP
.Vb 1
\&    perldoc HTTP::Exception
.Ve
.PP
You can also look for information at:
.IP "\(bu" 4
\&\s-1RT: CPAN\s0's request tracker
.Sp
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=HTTP\-Exception>
.IP "\(bu" 4
AnnoCPAN: Annotated \s-1CPAN\s0 documentation
.Sp
<http://annocpan.org/dist/HTTP\-Exception>
.IP "\(bu" 4
\&\s-1CPAN\s0 Ratings
.Sp
<http://cpanratings.perl.org/d/HTTP\-Exception>
.IP "\(bu" 4
Search \s-1CPAN\s0
.Sp
<https://metacpan.org/release/HTTP\-Exception>
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright 2010 Thomas Mueller.
.PP
This program is free software; you can redistribute it and/or modify it
under the terms of either: the \s-1GNU\s0 General Public License as published
by the Free Software Foundation; or the Artistic License.
.PP
See http://dev.perl.org/licenses/ for more information.