Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
HTTP::Throwable::FactoUser)Contributed Perl DocumenHTTP::Throwable::Factory(3)

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

VERSION
       version 0.027

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
       o   Stevan Little <stevan.little@iinteractive.com>

       o   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.

perl v5.32.1			  2020-01-26	   HTTP::Throwable::Factory(3)

NAME | VERSION | OVERVIEW | SUBCLASSING | AUTHORS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=HTTP::Throwable::Factory&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help