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

FreeBSD Manual Pages

  
 
  

home | help
App::Sqitch::X(3)     User Contributed Perl Documentation    App::Sqitch::X(3)

Name
       App::Sqitch::X -	Sqitch Exception class

Synopsis
	 use Locale::TextDomain;
	 use App::Sqitch::X qw(hurl);
	 open my $fh, '>', 'foo.txt' or	hurl {
	     ident   =>	'io',
	     message =>	__x 'Cannot open {file}: {err}", file => 'foo.txt', err	=> $!,
	 };

       Developer:

	 hurl 'Odd number of arguments passed to burf()' if @_ % 2;

Description
       This module provides implements Sqitch exceptions. Exceptions may be
       thrown by any part of the code, and, as long as a command is running,
       they will be handled, showing the error message to the user.

Interface
   Function
       "hurl"

       Throws an exception. Pass the parameters	as a hash reference, like so:

	 use App::Sqitch::X qw(hurl);
	 open my $fh, '>', 'foo.txt' or	hurl {
	     ident   =>	'io',
	     message =>	__x 'Cannot open {file}: {err}", file => 'foo.txt', err	=> $!,
	 };

       More simply, if all you need to pass are	the "ident" and	"message"
       parameters, you can pass	them as	the only arguments to "hurl()":

	 open my $fh, '>', 'foo.txt'
	   or hurl io => __x 'Cannot open {file}: {err}", file => 'foo.txt', err => $!

       For errors that should only happen during development (e.g., an invalid
       parameter passed	by some	other library that should know better),	you
       can omit	the "ident":

	 hurl 'Odd number of arguments passed to burf()' if @_ % 2;

       In this case, the "ident" will be "DEV",	which you should not otherwise
       use.  Sqitch will emit a	more detailed error message, including a stack
       trace, when it sees "DEV" exceptions.

       The supported parameters	are:

       "ident"
	   A non-localized string identifying the type of exception.

       "message"
	   The exception message. Use Locale::TextDomain to craft localized
	   messages.

       "exitval"
	   Suggested exit value	to use.	Defaults to 2. This will be used if
	   Sqitch handles an exception while a command is running.

   Methods
       "as_string"

	 my $errstr = $x->as_string;

       Returns the stringified representation of the exception.	This value is
       also used for string overloading	of the exception object, which means
       it is the output	shown for uncaught exceptions. Its contents are	the
       concatenation of	the exception message, the previous exception (if
       any), and the stack trace.

Handling Exceptions
       use Try::Tiny to	do exception handling, like so:

	 use Try::Tiny;
	 try {
	     # ...
	 } catch {
	     die $_ unless eval	{ $_->isa('App::Sqitch::X') };
	     $sqitch->vent($x_->message);
	     if	($_->ident eq 'DEV') {
		 $sqitch->vent($_->stack_trace->as_string);
	     } else {
		 $sqitch->debug($_->stack_trace->as_string);
	     }
	     exit $_->exitval;
	 };

       Use the "ident" attribute to determine what category of exception it
       is, and take changes as appropriate.

Author
       David E.	Wheeler	<david@justatheory.com>

License
       Copyright (c) 2012-2015 iovation	Inc.

       Permission is hereby granted, free of charge, to	any person obtaining a
       copy of this software and associated documentation files	(the
       "Software"), to deal in the Software without restriction, including
       without limitation the rights to	use, copy, modify, merge, publish,
       distribute, sublicense, and/or sell copies of the Software, and to
       permit persons to whom the Software is furnished	to do so, subject to
       the following conditions:

       The above copyright notice and this permission notice shall be included
       in all copies or	substantial portions of	the Software.

       THE SOFTWARE IS PROVIDED	"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
       OR IMPLIED, INCLUDING BUT NOT LIMITED TO	THE WARRANTIES OF
       MERCHANTABILITY,	FITNESS	FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
       IN NO EVENT SHALL THE AUTHORS OR	COPYRIGHT HOLDERS BE LIABLE FOR	ANY
       CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN	ACTION OF CONTRACT,
       TORT OR OTHERWISE, ARISING FROM,	OUT OF OR IN CONNECTION	WITH THE
       SOFTWARE	OR THE USE OR OTHER DEALINGS IN	THE SOFTWARE.

perl v5.24.1			  2017-07-03		     App::Sqitch::X(3)

Name | Synopsis | Description | Interface | Handling Exceptions | Author | License

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

home | help