.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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 turned on, 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
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "HTTP::Throwable::Factory 3pm"
.TH HTTP::Throwable::Factory 3pm "2013-11-20" "perl v5.18.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::Throwable::Factory \- a factory that throws HTTP::Throwables for you
.SH "VERSION"
.IX Header "VERSION"
version 0.018
.SH "OVERVIEW"
.IX Header "OVERVIEW"
HTTP::Throwable is a role that makes it easy to build exceptions that, once
thrown, can be turned into \s-1PSGI\s0\-style \s-1HTTP\s0 responses.  Because
HTTP::Throwable and all its related roles are, well, roles, they can't be
instantiated or thrown directly.  Instead, they must be built into classes
first.  HTTP::Throwable::Factory takes care of this job, building classes out
of the roles you need for the exception you want to throw.
.PP
You can use the factory to either \fIbuild\fR or \fIthrow\fR an exception of either a
\&\fIgeneric\fR or \fIspecific\fR type.  Building and throwing are very similar \*(-- the
only difference is whether or not the newly built object is thrown or returned.
To throw an exception, use the \f(CW\*(C`throw\*(C'\fR method on the factory.  To return it,
use the \f(CW\*(C`new_exception\*(C'\fR method.  In the examples below, we'll just use
\&\f(CW\*(C`throw\*(C'\fR.
.PP
To throw a generic exception \*(-- one where you must specify the status code and
reason, and any other headers \*(-- you pass \f(CW\*(C`throw\*(C'\fR a hashref of arguments that
will be passed to the exception class's constructor.
.PP
.Vb 7
\&  HTTP::Throwable::Factory\->throw({
\&      status_code => 301,
\&      reason      => \*(AqMoved Permanently\*(Aq,
\&      additional_headers => [
\&        Location => \*(Aq/new\*(Aq,
\&      ],
\&  });
.Ve
.PP
To throw a specific type of exception, include an exception type identifier,
like this:
.PP
.Vb 1
\&  HTTP::Throwable::Factory\->throw(MovedPermanently => { location => \*(Aq/new\*(Aq });
.Ve
.PP
The type identifier is (by default) the end of a role name in the form
\&\f(CW\*(C`HTTP::Throwable::Role::Status::IDENTIFIER\*(C'\fR.  The full list of such included
roles is given in the HTTP::Throwable docs.
.SS "Exports"
.IX Subsection "Exports"
You can import routines called \f(CW\*(C`http_throw\*(C'\fR and \f(CW\*(C`http_exception\*(C'\fR that work
like the \f(CW\*(C`throw\*(C'\fR and \f(CW\*(C`new_exception\*(C'\fR methods, respectively, but are not
called as methods.  For example:
.PP
.Vb 1
\&  use HTTP::Throwable::Factory \*(Aqhttp_exception\*(Aq;
\&
\&  builder {
\&      mount \*(Aq/old\*(Aq => http_exception(\*(AqGone\*(Aq),
\&  };
.Ve
.SH "SUBCLASSING"
.IX Header "SUBCLASSING"
One of the big benefits of using HTTP::Throwable::Factory is that you can
subclass it to change the kind of exceptions it provides.
.PP
If you subclass it, you can change its behavior by overriding the following
methods \*(-- provided in the order of likelihood that you'd want to override
them, most likely first.
.SS "extra_roles"
.IX Subsection "extra_roles"
This method returns a list of role names that will be included in any class
built by the factory.  By default, it includes only
HTTP::Throwable::Role::TextBody to satisfy HTTP::Throwable's requirements
for methods needed to build a body.
.PP
This is the method you're most likely to override in a subclass.
.SS "roles_for_ident"
.IX Subsection "roles_for_ident"
.SS "roles_for_no_ident"
.IX Subsection "roles_for_no_ident"
This methods convert the exception type identifier to a role to apply.  For
example, if you call:
.PP
.Vb 1
\&  Factory\->throw(NotFound => { ... })
.Ve
.PP
\&...then \f(CW\*(C`roles_for_ident\*(C'\fR is called with \*(L"NotFound\*(R" as its argument.
.PP
If \f(CW\*(C`throw\*(C'\fR is called \fIwithout\fR a type identifier, \f(CW\*(C`roles_for_no_ident\*(C'\fR is
called.
.PP
By default, \f(CW\*(C`roles_for_ident\*(C'\fR returns \f(CW\*(C`HTTP::Throwable::Role::Status::$ident\*(C'\fR
and \f(CW\*(C`roles_for_no_ident\*(C'\fR returns HTTP::Throwable::Role::Generic and
HTTP::Throwable::Role::BoringText.
.SS "base_class"
.IX Subsection "base_class"
This is the base class that will be subclassed and into which all the roles
will be composed.  By default, it is Moose::Object, the universal base Moose
class.
.SS "core_roles"
.IX Subsection "core_roles"
This method returns the roles that are expected to be applied to every
HTTP::Throwable exception.  This method's results might change over time, and
you are encouraged \fI\f(BInot\fI\fR to alter it.
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
Stevan Little <stevan.little@iinteractive.com>
.IP "\(bu" 4
Ricardo Signes <rjbs@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2011 by Infinity Interactive, Inc..
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.