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

FreeBSD Manual Pages

  
 
  

home | help
Exception::Class::TryCUser(Contributed Perl DocumException::Class::TryCatch(3)

NAME
       Exception::Class::TryCatch - Syntactic try/catch	sugar for use with
       Exception::Class

VERSION
       version 1.13

SYNOPSIS
	    use	Exception::Class::TryCatch;

	    # simple usage of catch()

	    eval { Exception::Class::Base->throw('error') };
	    catch my $err and warn $err->error;

	    # catching only certain types or else rethrowing

	    eval { Exception::Class::Base::SubClass->throw('error') };
	    catch( my $err, ['Exception::Class::Base', 'Other::Exception'] )
		and warn $err->error;

	    # catching and handling different types of errors

	    eval { Exception::Class::Base->throw('error') };
	    if ( catch my $err ) {
		$err->isa('this') and do { handle_this($err) };
		$err->isa('that') and do { handle_that($err) };
	    }

	    # use "try eval" to	push exceptions	onto a stack to	catch later

	    try	eval {
		Exception::Class::Base->throw('error')
	    };
	    do {
		# cleanup that might use "try/catch" again
	    };
	    catch my $err; # catches a matching	"try"

DESCRIPTION
       Exception::Class::TryCatch provides syntactic sugar for use with
       Exception::Class	using the familiar keywords "try" and "catch".	Its
       primary objective is to allow users to avoid dealing directly with $@
       by ensuring that	any exceptions caught in an "eval" are captured	as
       Exception::Class	objects, whether they were thrown objects to begin
       with or whether the error resulted from "die".  This means that users
       may immediately use "isa" and various Exception::Class methods to
       process the exception.

       In addition, this module	provides for a method to push errors onto a
       hidden error stack immediately after an "eval" so that cleanup code or
       other error handling may	also call "eval" without the original error in
       $@ being	lost.

       Inspiration for this module is due in part to Dave Rolsky's article
       "Exception Handling in Perl With	Exception::Class" in The Perl Journal
       (Rolsky 2004).

       The "try/catch" syntax used in this module does not use code reference
       prototypes the way the Error.pm module does, but	simply provides	some
       helpful functionality when used in combination with "eval".  As a
       result, it avoids the complexity	and dangers involving nested closures
       and memory leaks	inherent in Error.pm (Perrin 2003).

       Rolsky (2004) notes that	these memory leaks may not occur in recent
       versions	of Perl, but the approach used in Exception::Class::TryCatch
       should be safe for all versions of Perl as it leaves all	code execution
       to the "eval" in	the current scope, avoiding closures altogether.

USAGE
   "catch"
	    # zero argument form
	    my $err = catch;

	    # one argument forms
	    catch my $err;
	    my $err = catch( [ 'Exception::Type', 'Exception::Other::Type' ] );

	    # two argument form
	    catch my $err, [ 'Exception::Type',	'Exception::Other::Type' ];

       Returns an "Exception::Class::Base" object (or an object	which is a
       subclass	of it) if an exception has been	caught by "eval".  If no
       exception was thrown, it	returns	"undef"	in scalar context and an empty
       list in list context.   The exception is	either popped from a hidden
       error stack (see	"try") or, if the stack	is empty, taken	from the
       current value of	$@.

       If the exception	is not an "Exception::Class::Base" object (or subclass
       object),	an "Exception::Class::Base" object will	be created using the
       string contents of the exception.  This means that calls	to "die" will
       be wrapped and may be treated as	exception objects.  Other objects
       caught will be stringified and wrapped likewise.	 Such wrapping will
       likely result in	confusing stack	traces and the like, so	any methods
       other than "error" used on "Exception::Class::Base" objects caught
       should be used with caution.

       "catch" is prototyped to	take up	to two optional	scalar arguments.  The
       single argument form has	two variations.

       o   If the argument is a	reference to an	array, any exception caught
	   that	is not of the same type	(or a subtype) of one of the classes
	   listed in the array will be rethrown.

       o   If the argument is not a reference to an array, "catch" will	set
	   the argument	to the same value that is returned.  This allows for
	   the "catch my $err" idiom without parentheses.

       In the two-argument form, the first argument is set to the same value
       as is returned.	The second argument must be an array reference and is
       handled the same	as as for the single argument version with an array
       reference, as given above.

   "caught" (DEPRECATED)
       "caught"	is a synonym for "catch" for syntactic convenience.

       NOTE: Exception::Class version 1.21 added a "caught" method of its own.
       It provides somewhat similar functionality to this subroutine, but with
       very different semantics.  As this class	is intended to work closely
       with Exception::Class, the existence of a subroutine and	a method with
       the same	name is	liable to cause	confusion and this method is
       deprecated and may be removed in	future releases	of
       Exception::Class::TryCatch.

       This method is no longer	exported by default.

   "try"
	    # void context
	    try	eval {
	      #	dangerous code
	    };
	    do {
	      #	cleanup	code can use try/catch
	    };
	    catch my $err;

	    # scalar context
	    $rv	= try eval { return $scalar };

	    # list context
	    @rv	= try [	eval { return @array } ];

       Pushes the current error	($@) onto a hidden error stack for later use
       by "catch".  "try" uses a prototype that	expects	a single scalar	so
       that it can be used with	eval without parentheses.  As "eval { BLOCK }"
       is an argument to try, it will be evaluated just	prior to "try",
       ensuring	that "try" captures the	correct	error status.  "try" does not
       itself handle any errors	-- it merely records the results of "eval".
       "try { BLOCK }" will be interpreted as passing a	hash reference and
       will (probably) not compile. (And if it does, it	will result in very
       unexpected behavior.)

       Since "try" requires a single argument, "eval" will normally be called
       in scalar context.  To use "eval" in list context with "try", put the
       call to "eval" in an anonymous array:

	  @rv =	try [ eval {return @array} ];

       When "try" is called in list context, if	the argument to	"try" is an
       array reference,	"try" will dereference the array and return the
       resulting list.

       In scalar context, "try"	passes through the scalar value	returned by
       "eval" without modifications -- even if that is an array	reference.

	  $rv =	try eval { return $scalar };
	  $rv =	try eval { return [ qw(	anonymous array	) ] };

       Of course, if the eval throws an	exception, "eval" and thus "try" will
       return undef.

       "try" must always be properly bracketed with a matching "catch" or
       unexpected behavior may result when "catch" pops	the error off of the
       stack.  "try" executes right after its "eval", so inconsistent usage of
       "try" like the following	will work as expected:

	    try	eval {
		eval { die "inner" };
		catch my $inner_err
		die "outer" if $inner_err;
	    };
	    catch my $outer_err;
	    # handle $outer_err;

       However,	the following code is a	problem:

	    # BAD EXAMPLE
	    try	eval {
		try eval { die "inner" };
		die $@ if $@;
	    };
	    catch my $outer_err;
	    # handle $outer_err;

       This code will appear to	run correctly, but "catch" gets	the exception
       from the	inner "try", not the outer one,	and there will still be	an
       exception on the	error stack which will be caught by the	next "catch"
       in the program, causing unexpected (and likely hard to track) behavior.

       In short, if you	use "try", you must have a matching "catch".  The
       problem code above should be rewritten as:

	    try	eval {
		try eval { die "inner" };
		catch my $inner_err;
		$inner_err->rethrow if $inner_err;
	    };
	    catch my $outer_err;
	    # handle $outer_err;

REFERENCES
       1.  perrin. (2003), "Re:	Re2: Learning how to use the Error module by
	   example", (perlmonks.org), Available:
	   http://www.perlmonks.org/index.pl?node_id=278900 (Accessed
	   September 8,	2004).

       2.  Rolsky, D. (2004), "Exception Handling in Perl with
	   Exception::Class", The Perl Journal,	vol. 8,	no. 7, pp. 9-13

SEE ALSO
       o   Exception::Class

       o   Error -- but	see (Perrin 2003) before using

SUPPORT
   Bugs	/ Feature Requests
       Please report any bugs or feature requests through the issue tracker at
       <https://github.com/dagolden/Exception-Class-TryCatch/issues>.  You
       will be notified	automatically of any progress on your issue.

   Source Code
       This is open source software.  The code repository is available for
       public review and contribution under the	terms of the license.

       <https://github.com/dagolden/Exception-Class-TryCatch>

	 git clone https://github.com/dagolden/Exception-Class-TryCatch.git

AUTHOR
       David Golden <dagolden@cpan.org>

COPYRIGHT AND LICENSE
       This software is	Copyright (c) 2014 by David Golden.

       This is free software, licensed under:

	 The Apache License, Version 2.0, January 2004

perl v5.24.1			  2014-02-27	 Exception::Class::TryCatch(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | USAGE | REFERENCES | SEE ALSO | SUPPORT | AUTHOR | COPYRIGHT AND LICENSE

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

home | help