NAME

       HTTP::Throwable::Factory - a factory that throws HTTP::Throwables for you

VERSION

       version 0.026

OVERVIEW

       HTTP::Throwable is a role that makes it easy to build exceptions that, once thrown, can be
       turned into PSGI-style HTTP 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.

       You can use the factory to either build or throw an exception of either a generic or
       specific 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
       "throw" method on the factory.  To return it, use the "new_exception" method.  In the
       examples below, we'll just use "throw".

       To throw a generic exception -- one where you must specify the status code and reason, and
       any other headers -- you pass "throw" a hashref of arguments that will be passed to the
       exception class's constructor.

         HTTP::Throwable::Factory->throw({
             status_code => 301,
             reason      => 'Moved Permanently',
             additional_headers => [
               Location => '/new',
             ],
         });

       To throw a specific type of exception, include an exception type identifier, like this:

         HTTP::Throwable::Factory->throw(MovedPermanently => { location => '/new' });

       The type identifier is (by default) the end of a role name in the form
       "HTTP::Throwable::Role::Status::IDENTIFIER".  The full list of such included roles is
       given in the HTTP::Throwable docs.

   Exports
       You can import routines called "http_throw" and "http_exception" that work like the
       "throw" and "new_exception" methods, respectively, but are not called as methods.  For
       example:

         use HTTP::Throwable::Factory 'http_exception';

         builder {
             mount '/old' => http_exception('Gone'),
         };

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.

       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.

   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.

       This is the method you're most likely to override in a subclass.

   roles_for_ident
   roles_for_status_code
   roles_for_no_ident
       This methods convert the exception type identifier to a role to apply.  For example, if
       you call:

         Factory->throw(NotFound => { ... })

       ...then "roles_for_ident" is called with "NotFound" as its argument.
       "roles_for_status_code" is used if the string is three ASCII digits.

       If "throw" is called without a type identifier, "roles_for_no_ident" is called.

       By default, "roles_for_ident" returns "HTTP::Throwable::Role::Status::$ident" and
       "roles_for_no_ident" returns HTTP::Throwable::Role::Generic and
       HTTP::Throwable::Role::BoringText.

   base_class
       This is the base class that will be subclassed and into which all the roles will be
       composed.  By default, it is Moo::Object, the universal base Moo class.

   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 not to
       alter it.

AUTHORS

       •   Stevan Little <stevan.little@iinteractive.com>

       •   Ricardo Signes <rjbs@cpan.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2011 by Infinity Interactive, Inc..

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.