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

FreeBSD Manual Pages

  
 
  

home | help
Contextual::Return(3) User Contributed Perl DocumentationContextual::Return(3)

NAME
       Contextual::Return - Create context-sensitive return values

VERSION
       This document describes Contextual::Return version 0.004014

SYNOPSIS
	   use Contextual::Return;
	   use Carp;

	   sub foo {
	       return
		   SCALAR { 'thirty-twelve' }
		   LIST	  { 1,2,3 }

		   BOOL	{ 1 }
		   NUM	{ 7*6 }
		   STR	{ 'forty-two' }

		   HASHREF  { {name => 'foo', value => 99} }
		   ARRAYREF { [3,2,1] }

		   GLOBREF  { \*STDOUT }
		   CODEREF  { croak "Don't use this result as code!"; }
	       ;
	   }

	   # and later...

	   if (my $foo = foo())	{
	       for my $count (1..$foo) {
		   print "$count: $foo is:\n"
		       . "  array: @{$foo}\n"
		       . "  hash:  $foo->{name}	=> $foo->{value}\n"
		       ;
	       }
	       print {$foo} $foo->();
	   }

DESCRIPTION
       Usually,	when you need to create	a subroutine that returns different
       values in different contexts (list, scalar, or void), you write
       something like:

	   sub get_server_status {
	       my ($server_ID) = @_;

	       # Acquire server	data somehow...
	       my %server_data = _ascertain_server_status($server_ID);

	       # Return	different components of	that data,
	       # depending on call context...
	       if (wantarray())	{
		   return @server_data{	qw(name	uptime load users) };
	       }
	       if (defined wantarray())	{
		   return $server_data{load};
	       }
	       if (!defined wantarray()) {
		   carp	'Useless use of	get_server_status() in void context';
		   return;
	       }
	       else {
		   croak q{Bad context!	No biscuit!};
	       }
	   }

       That works okay,	but the	code could certainly be	more readable. In its
       simplest	usage, this module makes that code more	readable by providing
       three subroutines--"LIST()", "SCALAR()",	"VOID()"--that are true	only
       when the	current	subroutine is called in	the corresponding context:

	   use Contextual::Return;

	   sub get_server_status {
	       my ($server_ID) = @_;

	       # Acquire server	data somehow...
	       my %server_data = _ascertain_server_status($server_ID);

	       # Return	different components of	that data
	       # depending on call context...
	       if (LIST)   { return @server_data{ qw(name uptime load users) } }
	       if (SCALAR) { return $server_data{load}			       }
	       if (VOID)   { print "$server_data{load}\n"		       }
	       else	   { croak q{Bad context! No biscuit!}		       }
	   }

   Contextual returns
       Those three subroutines can also	be used	in another way:	as labels on a
       series of contextual return blocks (collectively	known as a contextual
       return sequence). When a	context	sequence is returned, it automatically
       selects the appropriate contextual return block for the calling
       context.	 So the	previous example could be written even more cleanly
       as:

	   use Contextual::Return;

	   sub get_server_status {
	       my ($server_ID) = @_;

	       # Acquire server	data somehow...
	       my %server_data = _ascertain_server_status($server_ID);

	       # Return	different components of	that data
	       # depending on call context...
	       return (
		   LIST	   { return @server_data{ qw(name uptime load users) } }
		   SCALAR  { return $server_data{load}			       }
		   VOID	   { print "$server_data{load}\n"		       }
		   DEFAULT { croak q{Bad context! No biscuit!}		       }
	       );
	   }

       The context sequence automatically selects the appropriate block	for
       each call context.

   Lazy	contextual return values
       "LIST" and "VOID" blocks	are always executed during the "return"
       statement. However, scalar return blocks	("SCALAR", "STR", "NUM",
       "BOOL", etc.) blocks are	not. Instead, returning	any of scalar block
       types causes the	subroutine to return an	object that lazily evaluates
       that block only when the	return value is	used.

       This means that returning a "SCALAR" block is a convenient way to
       implement a subroutine with a lazy return value.	For example:

	   sub digest {
	       return SCALAR {
		   my ($text) =	@_;
		   md5($text);
	       }
	   }

	   my $digest =	digest($text);

	   print $digest;   # md5() called only	when $digest used as string

       To better document this usage, the "SCALAR" block has a synonym:
       "LAZY".

	   sub digest {
	       return LAZY {
		   my ($text) =	@_;
		   md5($text);
	       }
	   }

   Active contextual return values
       Once a return value has been lazily evaluated in	a given	context, the
       resulting value is cached, and thereafter reused	in that	same context.

       However,	you can	specify	that, rather than being	cached,	the value
       should be re-evaluated every time the value is used:

	    sub	make_counter {
	       my $counter = 0;
	       return ACTIVE
		   SCALAR   { ++$counter }
		   ARRAYREF { [1..$counter] }
	   }

	   my $idx = make_counter();

	   print "$idx\n";	# 1
	   print "$idx\n";	# 2
	   print "[@$idx]\n";	# [1 2]
	   print "$idx\n";	# 3
	   print "[@$idx]\n";	# [1 2 3]

   Semi-lazy contextual	return values
       Sometimes, single or repeated lazy evaluation of	a scalar return	value
       in different contexts isn't what	you really want. Sometimes what	you
       really want is for the return value to be lazily	evaluated once only
       (the first time it's used in any	context), and then for that first
       value to	be reused whenever the return value is subsequently
       reevaluated in any other	context.

       To get that behaviour, you can use the "FIXED" modifier,	which causes
       the return value	to morph itself	into the actual	value the first	time
       it is used. For example:

	   sub lazy {
	       return
		   SCALAR { 42 }
		   ARRAYREF { [	1, 2, 3	] }
	       ;
	   }

	   my $lazy = lazy();
	   print $lazy + 1;	       # 43
	   print "@{$lazy}";	       # 1 2 3

	   sub semilazy	{
	       return FIXED
		   SCALAR { 42 }
		   ARRAYREF { [	1, 2, 3	] }
	       ;
	   }

	   my $semi = semilazy();
	   print $semi + 1;	       # 43
	   print "@{$semi}";	       # die q{Can't use string	("42") as an ARRAY ref}

   Finer distinctions of scalar	context
       Because the scalar values returned from a context sequence are lazily
       evaluated, it becomes possible to be more specific about	what kind of
       scalar value should be returned:	a boolean, a number, or	a string. To
       support those distinctions, Contextual::Return provides four extra
       context blocks: "NUM", "STR", "BOOL", and "PUREBOOL":

	   sub get_server_status {
	       my ($server_ID) = @_;

	       # Acquire server	data somehow...
	       my %server_data = _ascertain_server_status($server_ID);

	       # Return	different components of	that data
	       # depending on call context...
	       return (
		      LIST { @server_data{ qw(name uptime load users) }		 }
		  PUREBOOL { $_	= $server_data{uptime};	$server_data{uptime} > 0 }
		      BOOL { $server_data{uptime} > 0				 }
		      NUM  { $server_data{load}					 }
		      STR  { "$server_data{name}: $server_data{uptime}"		 }
		      VOID { print "$server_data{load}\n"			 }
		   DEFAULT { croak q{Bad context! No biscuit!}			 }
	       );
	   }

       With these in place, the	object returned	from a scalar-context call to
       "get_server_status()" now behaves differently, depending	on how it's
       used. For example:

	   if (	my $status = get_server_status() ) {  #	BOOL: True if uptime > 0
	       $load_distribution[$status]++;	      #	INT:  Evaluates	to load	value
	       print "$status\n";		      #	STR:  Prints "name: uptime"
	   }

	   if (get_server_status()) {		      #	PUREBOOL: also sets $_;
	       print;				      #	...which is then used here
	   }

       Boolean vs Pure Boolean contexts

       There is	a special subset of boolean contexts where the return value is
       being used and immediately thrown away. For example, in the loop:

	   while (get_data()) {
	       ...
	   }

       the value returned by "get_data()" is tested for	truth and then
       discarded.  This	is known as "pure boolean context". In contrast, in
       the loop:

	   while (my $data = get_data()) {
	       ...
	   }

       the value returned by "get_data()" is first assigned to $data, then
       tested for truth. Because of the	assignment, the	return value is	not
       discarded after the boolean test. This is ordinary "boolean context".

       In Perl,	pure boolean context is	often associated with a	special	side-
       effect, that does not occur in regular boolean contexts.	For example:

	   while (<>) {...}	    # $_ set as	side-effect of pure boolean context

	   while ($v = <>) {...}    # $_ NOT set in ordinary boolean context

       Contextual::Return supports this	with a special subcase of "BOOL" named
       <PUREBOOL>. In pure boolean contexts, Contextual::Return	will call a
       "PUREBOOL" handler if one has been defined, or fall back	to a "BOOL" or
       "SCALAR"	handler	if no "PUREBOOL" handler exists. In ordinary boolean
       contexts	only the "BOOL"	or "SCALAR" handlers are tried,	even if	a
       "PUREBOOL" handler is also defined.

       Typically "PUREBOOL" handlers are set up	to have	some side-effect (most
       commonly: setting $_ or <$@>), like so:

	   sub get_data	{
	       my ($succeeded, @data) =	_go_and_get_data();

	       return
		   PUREBOOL { $_ = $data[0]; $succeeded; }
		       BOOL {		     $succeeded; }
		     SCALAR {		     $data[0];	 }
		       LIST {		     @data;	 }
	   }

       However,	there is no requirement	that they have side-effects. For
       example,	they can also be used to implement "look-but-don't-retrieve-
       yet" checking:

	   sub get_data	{
	       my $data;
	       return
		   PUREBOOL {	     _check_for_but_dont_get_data();   }
		       BOOL { defined( $data ||= _go_and_get_data() ); }
			REF {	       $data ||= _go_and_get_data();   }
	   }

   Self-reference within handlers
       Any handler can refer to	the contextual return object it	is part	of, by
       calling the "RETOBJ()" function.	This is	particularly useful for
       "PUREBOOL" and "LIST" handlers. For example:

	   return
	       PUREBOOL	{ $_ = RETOBJ; next handler; }
		   BOOL	{ !$failed;		     }
		DEFAULT	{ $data;		     };

   Referential contexts
       The other major kind of scalar return value is a	reference.
       Contextual::Return provides contextual return blocks that allow you to
       specify what to (lazily)	return when the	return value of	a subroutine
       is used as a reference to a scalar ("SCALARREF {...}"), to an array
       ("ARRAYREF {...}"), to a	hash ("HASHREF {...}"),	to a subroutine
       ("CODEREF {...}"), or to	a typeglob ("GLOBREF {...}").

       For example, the	server status subroutine shown earlier could be
       extended	to allow it to return a	hash reference,	thereby	supporting
       "named return values":

	   sub get_server_status {
	       my ($server_ID) = @_;

	       # Acquire server	data somehow...
	       my %server_data = _ascertain_server_status($server_ID);

	       # Return	different components of	that data
	       # depending on call context...
	       return (
		      LIST { @server_data{ qw(name uptime load users) }	 }
		      BOOL { $server_data{uptime} > 0			 }
		       NUM { $server_data{load}				 }
		       STR { "$server_data{name}: $server_data{uptime}"	 }
		      VOID { print "$server_data{load}\n"		 }
		   HASHREF { return \%server_data			 }
		   DEFAULT { croak q{Bad context! No biscuit!}		 }
	       );
	   }

	   # and later...

	   my $users = get_server_status->{users};

	   # or, lazily...

	   my $server =	get_server_status();

	   print "$server->{name} load = $server->{load}\n";

   Interpolative referential contexts
       The "SCALARREF {...}" and "ARRAYREF {...}" context blocks are
       especially useful when you need to interpolate a	subroutine into
       strings.	For example, if	you have a subroutine like:

	   sub get_todo_tasks {
	       return (
		   SCALAR { scalar @todo_list }	     # How many?
		   LIST	  { @todo_list	      }	     # What are	they?
	       );
	   }

	   # and later...

	   print "There	are ", scalar(get_todo_tasks()), " tasks:\n",
		   get_todo_tasks();

       then you	could make it much easier to interpolate calls to that
       subroutine by adding:

	   sub get_todo_tasks {
	       return (
		   SCALAR { scalar @todo_list }	     # How many?
		   LIST	  { @todo_list	      }	     # What are	they?

		   SCALARREF { \scalar @todo_list }  # Ref to how many
		   ARRAYREF  { \@todo_list	  }  # Ref to them
	       );
	   }

	   # and then...

	   print "There	are ${get_todo_tasks()}	tasks:\n@{get_todo_tasks()}";

       In fact,	this behaviour is so useful that it's the default. If you
       don't provide an	explicit "SCALARREF {...}" block, Contextual::Return
       automatically provides an implicit one that simply returns a reference
       to whatever would have been returned in scalar context.	Likewise, if
       no "ARRAYREF {...}" block is specified, the module supplies one that
       returns the list-context	return value wrapped up	in an array reference.

       So you could just write:

	   sub get_todo_tasks {
	       return (
		   SCALAR { scalar @todo_list }	     # How many?
		   LIST	  { @todo_list	      }	     # What are	they?
	       );
	   }

	   # and still do this...

	   print "There	are ${get_todo_tasks()}	tasks:\n@{get_todo_tasks()}";

   Fallback contexts
       As the previous sections	imply, the "BOOL {...}", "NUM {...}", "STR
       {...}", and various "*REF {...}"	blocks,	are special cases of the
       general "SCALAR {...}" context block. If	a subroutine is	called in one
       of these	specialized contexts but does not use the corresponding
       context block, then the more general "SCALAR {...}" block is used
       instead (if it has been specified).

       So, for example:

	   sub read_value_from {
	       my ($fh)	= @_;

	       my $value = <$fh>;
	       chomp $value;

	       return (
		   BOOL	  { defined $value }
		   SCALAR { $value	   }
	       );
	   }

       ensures that the	"read_value_from()" subroutine returns true in boolean
       contexts	if the read was	successful. But, because no specific "NUM
       {...}" or "STR {...}" return behaviours were specified, the subroutine
       falls back on using its generic "SCALAR {...}" block in all other
       scalar contexts.

       Another way to think about this behaviour is that the various kinds of
       scalar context blocks form a hierarchy:

	   SCALAR
		^
		|
		|--< BOOL
		|
		|--< NUM
		|
		`--< STR

       Contextual::Return uses this hierarchical relationship to choose	the
       most specific context block available to	handle any particular return
       context,	working	its way	up the tree from the specific type it needs,
       to the more general type, if that's all that is available.

       There are two slight complications to this picture. The first is	that
       Perl treats strings and numbers as interconvertable so the diagram (and
       the Contextual::Return module) also has to allow	these interconversions
       as a fallback strategy:

	   SCALAR
		^
		|
		|--< BOOL
		|
		|--< NUM
		|    : ^
		|    v :
		`--< STR

       The dotted lines	are meant to indicate that this	intraconversion	is
       secondary to the	main hierarchical fallback. That is, in	a numeric
       context,	a "STR {...}" block will only be used if there is no "NUM
       {...}" block and	no "SCALAR {...}" block. In other words, the generic
       context type is always used in preference to string<->number
       conversion.

       The second slight complication is that the above	diagram	only shows a
       small part of the complete hierarchy of contexts	supported by
       Contextual::Return. The full fallback hierarchy (including dotted
       interconversions) is:

	     DEFAULT
		^
		|
		|--< VOID
		|
		`--< NONVOID
			^
			|
			|--< VALUE <...............
			|      ^		   :
			|      |		   :
			|      |--< SCALAR <.......:...
			|      |	   ^	       :
			|      |	   |	       :
			|      |	   |--<	BOOL   :
			|      |	   |	 ^     :
			|      |	   |	 |     :
			|      |	   |  PUREBOOL :
			|      |	   |	       :
			|      |	   |--<	NUM <..:.
			|      |	   |	: ^	 :
			|      |	   |	v :	 :
			|      |	   `--<	STR <....:..
			|      |			   :
			|      |			  ::
			|      `--< LIST ................: :
			|	     : ^		   :
			|	     : :		   :
			`--- REF     : :		   :
			      ^	     : :		   :
			      |	     v :		   :
			      |--< ARRAYREF		   :
			      |				   :
			      |--< SCALARREF .............:
			      |
			      |--< HASHREF
			      |
			      |--< CODEREF
			      |
			      |--< GLOBREF
			      |
			      `--< OBJREF <....... METHOD
				      ^
				      :........... BLESSED

       As before, each dashed arrow represents a fallback relationship.	That
       is, if the required context specifier isn't available, the arrows are
       followed	until a	more generic one is found. The dotted arrows again
       represent the interconversion of	return values, which is	attempted only
       after the normal	hierarchical fallback fails.

       For example, if a subroutine is called in a context that	expects	a
       scalar reference, but no	"SCALARREF {...}" block	is provided, then
       Contextual::Return tries	the following blocks in	order:

	       REF {...}
	   NONVOID {...}
	   DEFAULT {...}
	       STR {...} (automatically	taking a reference to the result)
	       NUM {...} (automatically	taking a reference to the result)
	    SCALAR {...} (automatically	taking a reference to the result)
	     VALUE {...} (automatically	taking a reference to the result)

       Likewise, in a list context, if there is	no "LIST {...}"	context	block,
       the module tries:

	      VALUE {...}
	    NONVOID {...}
	    DEFAULT {...}
	   ARRAYREF {...} (automatically dereferencing the result)
		STR {...} (treating it as a list of one	element)
		NUM {...} (treating it as a list of one	element)
	     SCALAR {...} (treating it as a list of one	element)

       The more	generic	context	blocks are especially useful for intercepting
       unexpected and undesirable call contexts. For example, to turn off the
       automatic scalar-ref and	array-ref interpolative	behaviour described in
       "Interpolative referential contexts", you could intercept all
       referential contexts using a generic "REF {...}"	context	block:

	   sub get_todo_tasks {
	       return (
		   SCALAR { scalar @todo_list }	     # How many?
		   LIST	  { @todo_list	      }	     # What are	they?

		   REF { croak q{get_todo_task() can't be used as a reference} }
	       );
	   }

	   print 'There	are ', get_todo_tasks(), '...';	   # Still okay
	   print "There	are ${get_todo_tasks()}...";	   # Throws an exception

   Treating return values as objects
       Normally, when a	return value is	treated	as an object (i.e. has a
       method called on	it), Contextual::Return	invokes	any "OBJREF" handler
       that was	specified in the contextual return list, and delegates the
       method call to the object returned by that handler.

       However,	you can	also be	more specific, by specifying a "METHOD"
       context handler in the contextual return	list. The block	of this
       handler is expected to return one or more method-name/method-handler
       pairs, like so:

	   return
	       METHOD {
		   get_count =>	sub { my $n = shift; $data[$n]{count} },
		   get_items =>	sub { my $n = shift; $data[$n]{items} },
		   clear     =>	sub { @data = (); },
		   reset     =>	sub { @data = (); },
	       }

       Then, whenever one of the specified methods is called on	the return
       value, the corresponding	subroutine will	be called to implement it.

       The method handlers must	always be subroutine references, but the
       method-name specifiers may be strings (as in the	previous example) or
       they may	be specified generically, as either regexes or array
       references. Generic method names	are used to call the same handler for
       two or more distinct method names.  For example,	the previous example
       could be	simplified to:

	   return
	       METHOD {
		   qr/get_(\w+)/     =>	sub { my $n = shift; $data[$n]{$1} },
		   ['clear','reset'] =>	sub { @data = (); },
	       }

       A method	name specified by regex	will invoke the	corresponding handler
       for any method call request that	the regex matches. A method name
       specified by array ref will invoke the corresponding handler if the
       method requested	matches	any of the elements of the array (which	may
       themselves be strings or	regexes).

       When the	method handler is invoked, the name of the method requested is
       passed to the handler in	$_, and	the method's argument list is passed
       (as usual) via @_.

       Note that any methods not explicitly handled by the "METHOD" handlers
       will still be delegated to the object returned by the "OBJREF" handler
       (if it is also specified).

   Not treating	return values as objects
       The use of "OBJREF" and "METHOD"	are slightly complicated by the	fact
       that contextual return values are themselves objects.

       For example, prior to version 0.4.4 of the module, if you passed	a
       contextual return value to "Scalar::Util::blessed()", it	always
       returned	a true value (namely, the string:
       'Contextual::Return::Value'), even if the return	value had not
       specified handlers for "OBJREF" or "METHOD".

       In other	words, the implementation of contextual	return values (as
       objects)	was getting in the way of the use of contextual	return values
       (as non-objects).

       So the module now also provides a "BLESSED" handler, which allows you
       to explicitly control how contextual return values interact with
       "Scalar::Util::blessed()".

       If $crv is a contextual return value, by	default
       "Scalar::Util::blessed($crv)" will now only return true if that return
       value has a "OBJREF", "LAZY", "REF", "SCALAR", "VALUE", "NONVOID", or
       "DEFAULT" handler that in turn returns a	blessed	object.

       However if $crv also provides a "BLESSED" handler, "blessed()" will
       return whatever that handler returns.

       This means:

	   sub simulate_non_object {
	       return BOOL { 1 }
		       NUM { 42	}
	   }

	   sub simulate_real_object {
	       return OBJREF { bless {}, 'My::Class' }
			BOOL { 1 }
			 NUM { 42 }
	   }

	   sub simulate_faked_object {
	       return BLESSED {	'Foo' }
			 BOOL {	1 }
			  NUM {	42 }
	   }

	   sub simulate_previous_behaviour {
	       return BLESSED {	'Contextual::Return::Value' }
			 BOOL {	1 }
			  NUM {	42 }
	   }

	   say blessed(	simulate_non_object()	      );   # undef
	   say blessed(	simulate_real_object()	      );   # My::Class
	   say blessed(	simulate_faked_object()	      );   # Foo
	   say blessed(	simulate_previous_behaviour() );   # Contextual::Return::Value

       Typically, you either want no "BLESSED" handler (in which case
       contextual return values	pretend	not to be blessed objects), or you
       want "BLESSED { 'Contextual::Return::Value' }" for backwards
       compatibility with pre-v0.4.7 behaviour.

       Preventing fallbacks

       Sometimes fallbacks can be too helpful. Or sometimes you	want to	impose
       strict type checking on a return	value.

       Contextual::Returns allows that via the "STRICT"	specifier. If you
       include "STRICT"	anywhere in your return	statement, the module disables
       all fallbacks and will therefore	through	an exception if	the return
       value is	used in	any way	not explicitly specified in the	contextual
       return sequence.

       For example, to create a	subroutine that	returns	only a string:

	   sub get_name	{
	       return STRICT STR { 'Bruce' }
	   }

       If the return value of the subroutine is	used in	any other way than as
       a string, an exception will be thrown.

       You can still specify handlers for more than a single kind of context
       when using "STRICT":

	   sub get_name	{
	       return STRICT
		   STR	{ 'Bruce' }
		   BOOL	{ 0 }
	   }

       ...but these will still be the only contexts in which the return	value
       can be used:

	   my $n = get_name() ?	1 : 2;	# Okay because BOOL handler specified

	   my $n = 'Dr'	. get_name();	# Okay because STR handler specified

	   my $n = 1 + get_name();	# Exception thrown because no NUM handler

       In other	words, "STRICT"	allows you to impose strict type checking on
       your contextual return value.

   Deferring handlers
       Because the various handlers form a hierarchy, it's possible to
       implement more specific handlers	by falling back	on ("deferring to")
       more general ones. For example, a "PUREBOOL" handler is almost always
       identical in its	basic behaviour	to the corresponding "BOOL" handler,
       except that it adds some	side-effect.  For example:

	   return
	       PUREBOOL	{ $_ = $return_val; defined $return_val	&& $return_val > 0 }
		   BOOL	{		    defined $return_val	&& $return_val > 0 }
		 SCALAR	{		    $return_val;			   }

       So Contextual::Return allows you	to have	a handler perform some action
       and then	defer to a more	general	handler	to supply the actual return
       value. To fall back to a	more general case in this way, you simply
       write:

	   next	handler;

       at the end of the handler in question, after which Contextual::Return
       will find the next-most-specific	handler	and execute it as well.	So the
       previous	example, could be re-written:

	   return
	       PUREBOOL	{ $_ = $return_val; next handler;	 }
		   BOOL	{ defined $return_val && $return_val > 0 }
		 SCALAR	{ $return_val;				 }

       Note that any specific handler can defer	to a more general one in this
       same way. For example, you could	provide	consistent and maintainable
       type-checking for a subroutine that returns references by providing
       "ARRAYREF", "HASHREF", and "SCALARREF" handlers that all	defer to a
       generic "REF" handler, like so:

	   my $retval =	_get_ref();

	   return
	      SCALARREF	{ croak	'Type mismatch'	if ref($retval)	ne 'SCALAR';
			  next handler;
			}
	       ARRAYREF	{ croak	'Type mismatch'	if ref($retval)	ne 'ARRAY';
			  next handler;
			}
		HASHREF	{ croak	'Type mismatch'	if ref($retval)	ne 'HASH';
			  next handler;
			}
		    REF	{ $retval }

       If, at a	later time, the	process	of returning a reference became	more
       complex,	only the "REF" handler would have to be	updated.

   Nested handlers
       Another way of factoring	out return behaviour is	to nest	more specific
       handlers	inside more general ones. For instance,	in the final example
       given in	"Boolean vs Pure Boolean contexts":

	   sub get_data	{
	       my $data;
	       return
		   PUREBOOL {	     _check_for_but_dont_get_data();   }
		       BOOL { defined( $data ||= _go_and_get_data() ); }
			REF {	       $data ||= _go_and_get_data();   }
	   }

       you could factor	out the	repeated calls to "_go_and_get_data()" like
       so:

	   sub get_data	{
	       return
		   PUREBOOL { _check_for_but_dont_get_data(); }
		    DEFAULT {
		       my $data	= _go_and_get_data();

		       BOOL { defined $data; }
			REF {	      $data; }
		    }
	   }

       Here, the "DEFAULT" handler deals with every return context except pure
       boolean.	Within that "DEFAULT" handler, the data	is first retrieved,
       and then	two "sub-handlers" deal	with the ordinary boolean and
       referential contexts.

       Typically nested	handlers are used in precisely this way: to optimize
       for inexpensive special cases (such as pure boolean or integer or void
       return contexts)	and only do extra work for those other cases that
       require it.

   Failure contexts
       Two of the most common ways to specify that a subroutine	has failed are
       to return a false value,	or to throw an exception. The
       Contextual::Return module provides a mechanism that allows the
       subroutine writer to support both of these mechanisms at	the same time,
       by using	the "FAIL" specifier.

       A return	statement of the form:

	   return FAIL;

       causes the surrounding subroutine to return "undef" (i.e. false)	in
       boolean contexts, and to	throw an exception in any other	context. For
       example:

	   use Contextual::Return;

	   sub get_next_val {
	       my $next_val = <>;
	       return FAIL if !defined $next_val;
	       chomp $next_val;
	       return $next_val;
	   }

       If the "return FAIL" statement is executed, it will either return false
       in a boolean context:

	   if (my $val = get_next_val()) {	# returns undef	if no next val
	       print "[$val]\n";
	   }

       or else throw an	exception if the return	value is used in any other
       context:

	   print get_next_val();       # throws	exception if no	next val

	   my $next_val	= get_next_val();
	   print "[$next_val]\n";      # throws	exception if no	next val

       The exception that is thrown is of the form:

	   Call	to main::get_next_val()	failed at demo.pl line 42

       but you can change that message by providing a block to the "FAIL",
       like so:

	   return FAIL { "No more data"	} if !defined $next_val;

       in which	case, the final	value of the block becomes the exception
       message:

	   No more data	at demo.pl line	42

       A failure value can be interrogated for its error message, by calling
       its "error()" method, like so:

	   my $val = get_next_val();
	   if ($val) {
	       print "[$val]\n";
	   }
	   else	{
	       print $val->error, "\n";
	   }

   Configurable	failure	contexts
       The default "FAIL" behaviour--false in boolean context, fatal in	all
       others--works well in most situations, but violates the Platinum	Rule
       ("Do unto others	as they	would have done	unto them").

       So it may be user-friendlier if the user	of a module is allowed decide
       how the module's	subroutines should behave on failure. For example, one
       user might prefer that failing subs always return undef;	another	might
       prefer that they	always throw an	exception; a third might prefer	that
       they always log the problem and return a	special	Failure	object;	whilst
       a fourth	user might want	to get back 0 in scalar	contexts, an empty
       list in list contexts, and an exception everywhere else.

       You could create	a module that allows the user to specify all these
       alternatives, like so:

	   package MyModule;
	   use Contextual::Return;
	   use Log::StdLog;

	   sub import {
	       my ($package, @args) = @_;

	       Contextual::Return::FAIL_WITH {
		   ':false' => sub { return undef },
		   ':fatal' => sub { croak @_	    },
		   ':filed' => sub {
				   print STDLOG	'Sub ',	(caller	1)[3], ' failed';
				   return Failure->new();
			       },
		   ':fussy' => sub {
				   SCALAR  { undef	}
				   LIST	   { ()		}
				   DEFAULT { croak @_ }
			       },
	       }, @args;
	   }

       This configures Contextual::Return so that, instead of the usual	false-
       or-fatal	semantics, every "return FAIL" within MyModule's namespace is
       implemented by one of the four subroutines specified in the hash	that
       was passed to "FAIL_WITH".

       Which of	those four subs	implements the "FAIL" is determined by the
       arguments passed	after the hash (i.e. by	the contents of	@args).
       "FAIL_WITH" walks through that list of arguments	and compares them
       against the keys	of the hash. If	a key matches an argument, the
       corresponding value is used as the implementation of "FAIL". Note that,
       if subsequent arguments also match a key, their subroutine overrides
       the previously installed	implementation,	so only	the final override has
       any effect. Contextual::Return generates	warnings when multiple
       overrides are specified.

       All of which mean that, if a user loaded	the MyModule module like this:

	   use MyModule	qw( :fatal other args here );

       then every "FAIL" within	MyModule would be reconfigured to throw	an
       exception in all	circumstances, since the presence of the ':fatal' in
       the argument list will cause "FAIL_WITH"	to select the hash entry whose
       key is ':fatal'.

       On the other hand, if they loaded the module:

	   use MyModule	qw( :fussy other args here );

       then each "FAIL"	within MyModule	would return undef or empty list or
       throw an	exception, depending on	context, since that's what the
       subroutine whose	key is ':fussy'	does.

       Many people prefer module interfaces with a "flag =_ value" format, and
       "FAIL_WITH" supports this too. For example, if you wanted your module
       to take a "-fail" flag, whose associated	value could be any of
       "undefined", "exception", "logged", or "context", then you could
       implement that simply by	specifying the flag as the first argument
       (i.e. before the	hash) like so:

	   sub import {
	       my $package = shift;

	       Contextual::Return::FAIL_WITH -fail => {
		   'undefined' => sub {	return undef },
		   'exception' => sub {	croak @_ },
		   'logged'    => sub {
				   print STDLOG	'Sub ',	(caller	1)[3], ' failed';
				   return Failure->new();
			       },
		   'context' =>	sub {
				   SCALAR  { undef	}
				   LIST	   { ()		}
				   DEFAULT { croak @_ }
			       },
	       }, @_;

       and then	load the module:

	   use MyModule	qw( other args here ), -fail=>'undefined';

       or:

	   use MyModule	qw( other args here ), -fail=>'exception';

       In this case, "FAIL_WITH" scans the argument list for a pair of values:
       its flag	string,	followed by some other selector	value. Then it looks
       up the selector value in	the hash, and installs the corresponding
       subroutine as its local "FAIL" handler.

       If this "flagged" interface is used, the	user of	the module can also
       specify their own handler directly, by passing a	subroutine reference
       as the selector value instead of	a string:

	   use MyModule	qw( other args here ), -fail=>sub{ die 'horribly'};

       If this last example were used, any call	to "FAIL" within MyModule
       would invoke the	specified anonymous subroutine (and hence throw	a
       'horribly' exception).

       Note that, any overriding of a "FAIL" handler is	specific to the
       namespace and file from which the subroutine that calls "FAIL_WITH" is
       itself called. Since "FAIL_WITH"	is designed to be called from within a
       module's	"import()" subroutine, that generally means that the "FAIL"s
       within a	given module X are only	overridden for the current namespace
       within the particular file from module X	is loaded. This	means that two
       separate	pieces of code (in separate files or separate namespaces) can
       each independently override a module's "FAIL" behaviour,	without
       interfering with	each other.

   Lvalue contexts
       Recent versions of Perl offer (limited) support for lvalue subroutines:
       subroutines that	return a modifiable variable, rather than a simple
       constant	value.

       Contextual::Return can make it easier to	create such subroutines,
       within the limitations imposed by Perl itself. The limitations that
       Perl places on lvalue subs are:

       1.  The subroutine must be declared with	an ":lvalue" attribute:

	       sub foo :lvalue {...}

       2.  The subroutine must not return via an explicit "return". Instead,
	   the last statement must evaluate to a variable, or must be a	call
	   to another lvalue subroutine	call.

	       my ($foo, $baz);

	       sub foo :lvalue {
		   $foo;	       # last statement	evals to a var
	       }

	       sub bar :lvalue {
		   foo();	       # last statement	is lvalue sub call
	       }

	       sub baz :lvalue {
		   my ($arg) = @_;

		   $arg	> 0	       # last statement	evals...
		       ? $baz	       # ...to a var
		       : bar();	       # ...or to an lvalue sub	call
	       }

       Thereafter, any call to the lvalue subroutine produces a	result that
       can be assigned to:

	   baz(0) = 42;		   # same as: $baz = 42

	   baz(1) = 84;		   # same as:		       bar() = 84
				   #  which is the same	as:    foo() = 84
				   #   which is	the same as:   $foo  = 84

       Ultimately, every lvalue	subroutine must	return a scalar	variable,
       which is	then used as the lvalue	of the assignment (or whatever other
       lvalue operation	is applied to the subroutine call). Unfortunately,
       because the subroutine has to return this variable before the
       assignment can take place, there	is no way that a normal	lvalue
       subroutine can get access to the	value that will	eventually be assigned
       to its return value.

       This is occasionally annoying, so the Contextual::Return	module offers
       a solution: in addition to all the context blocks described above, it
       provides	three special contextual return	blocks specifically for	use in
       lvalue subroutines: "LVALUE", "RVALUE", and "NVALUE".

       Using these blocks you can specify what happens when an lvalue
       subroutine is used in lvalue and	non-lvalue (rvalue) context. For
       example:

	   my $verbosity_level = 1;

	   # Verbosity values must be between 0	and 5...
	   sub verbosity :lvalue {
	       LVALUE {	$verbosity_level = max(0, min($_, 5)) }
	       RVALUE {	$verbosity_level		      }
	   }

       The "LVALUE" block is executed whenever "verbosity" is called as	an
       lvalue:

	   verbosity() = 7;

       The block has access to the value being assigned, which is passed to it
       as $_. So, in the above example,	the assigned value of 7	would be
       aliased to $_ within the	"LVALUE" block,	would be reduced to 5 by the
       "min-of-max" expression,	and then assigned to $verbosity_level.

       (If you need to access the caller's $_, it's also still available: as
       $CALLER::_.)

       When the	subroutine isn't used as an lvalue:

	   print verbosity();

       the "RVALUE" block is executed instead and its final value returned.
       Within an "RVALUE" block	you can	use any	of the other features of
       Contextual::Return. For example:

	   sub verbosity :lvalue {
	       LVALUE {	$verbosity_level = int max(0, min($_, 5)) }
	       RVALUE {
		   NUM	{ $verbosity_level		 }
		   STR	{ $description[$verbosity_level] }
		   BOOL	{ $verbosity_level > 2		 }
	       }
	   }

       but the context sequence	must be	nested inside an "RVALUE" block.

       You can also specify what an lvalue subroutine should do	when it	is
       used neither as an lvalue nor as	an rvalue (i.e.	in void	context), by
       using an	"NVALUE" block:

	   sub verbosity :lvalue {
	       my ($level) = @_;

	       NVALUE {	$verbosity_level = int max(0, min($level, 5)) }
	       LVALUE {	$verbosity_level = int max(0, min($_,	  5)) }
	       RVALUE {
		   NUM	{ $verbosity_level		 }
		   STR	{ $description[$verbosity_level] }
		   BOOL	{ $verbosity_level > 2		 }
	       }
	   }

       In this example,	a call to "verbosity()"	in void	context	sets the
       verbosity level to whatever argument is passed to the subroutine:

	   verbosity(1);

       Note that you cannot get	the same effect	by nesting a "VOID" block
       within an "RVALUE" block:

	       LVALUE {	$verbosity_level = int max(0, min($_, 5)) }
	       RVALUE {
		   NUM	{ $verbosity_level		 }
		   STR	{ $description[$verbosity_level] }
		   BOOL	{ $verbosity_level > 2		 }
		   VOID	{ $verbosity_level = $level	 }  # Wrong!
	       }

       That's because, in a void context the return value is never evaluated,
       so it is	never treated as an rvalue, which means	the "RVALUE" block
       never executes.

   Result blocks
       Occasionally, it's convenient to	calculate a return value before	the
       end of a	contextual return block. For example, you may need to clean up
       external	resources involved in the calculation after it's complete.
       Typically, this requirement produces a slightly awkward code sequence
       like this:

	   return
	       VALUE {
		   $db->start_work();
		   my $result =	$db->retrieve_query($query);
		   $db->commit();
		   $result;
	       }

       Such code sequences become considerably more awkward when you want the
       return value to be context sensitive, in	which case you have to write
       either:

	   return
	       LIST {
		   $db->start_work();
		   my @result =	$db->retrieve_query($query);
		   $db->commit();
		   @result;
	       }
	       SCALAR {
		   $db->start_work();
		   my $result =	$db->retrieve_query($query);
		   $db->commit();
		   $result;
	       }

       or, worse:

	   return
	       VALUE {
		   $db->start_work();
		   my $result =	LIST ? [$db->retrieve_query($query)]
				     :	$db->retrieve_query($query);
		   $db->commit();
		   LIST	? @{$result} : $result;
	       }

       To avoid	these infelicities, Contextual::Return provides	a second way
       of setting the result of	a context block; a way that doesn't require
       that the	result be the last statement in	the block:

	   return
	       LIST {
		   $db->start_work();
		   RESULT { $db->retrieve_query($query)	};
		   $db->commit();
	       }
	       SCALAR {
		   $db->start_work();
		   RESULT { $db->retrieve_query($query)	};
		   $db->commit();
	       }

       The presence of a "RESULT" block	inside a contextual return block
       causes that block to return the value of	the final statement of the
       "RESULT"	block as the handler's return value, rather than returning the
       value of	the handler's own final	statement. In other words, the
       presence	of a "RESULT" block overrides the normal return	value of a
       context handler.

       Better still, the "RESULT" block	always evaluates its final statement
       in the same context as the surrounding "return",	so you can just	write:

	   return
	       VALUE {
		   $db->start_work();
		   RESULT { $db->retrieve_query($query)	};
		   $db->commit();
	       }

       and the "retrieve_query()" method will be called	in the appropriate
       context in all cases.

       A "RESULT" block	can appear anywhere inside any contextual return
       block, but may not be used outside a context block. That	is, this is an
       error:

	   if ($db->closed) {
	       RESULT {	undef }; # Error: not in a context block
	   }
	   return
	       VALUE {
		   $db->start_work();
		   RESULT { $db->retrieve_query($query)	};
		   $db->commit();
	       }

   Post-handler	clean-up
       If a subroutine uses an external	resource, it's often necessary to
       close or	clean-up that resource after the subroutine ends...regardless
       of whether the subroutine exits normally	or via an exception.

       Typically, this is done by encapsulating	the resource in	a lexically
       scoped object whose destructor does the clean-up. However, if the
       clean-up	doesn't	involve	deallocation of	an object (as in the
       "$db->commit()" example in the previous section), it can	be annoying to
       have to create a	class and allocate a container object, merely to
       mediate the clean-up.

       To make it easier to manage such	resources, Contextual::Return supplies
       a special labelled block: the "RECOVER" block. If a "RECOVER" block is
       specified as part of a contextual return	sequence, that block is
       executed	after any context handler, even	if the context handler exits
       via an exception.

       So, for example,	you could implement a simple commit-or-revert policy
       like so:

	   return
	       LIST    { $db->retrieve_all($query)  }
	       SCALAR  { $db->retrieve_next($query) }
	       RECOVER {
		   if ($@) {
		       $db->revert();
		   }
		   else	{
		       $db->commit();
		   }
	       }

       The presence of a "RECOVER" block also intercepts all exceptions	thrown
       in any other context block in the same contextual return	sequence. Any
       such exception is passed	into the "RECOVER" block in the	usual manner:
       via the $@ variable. The	exception may be rethrown out of the "RECOVER"
       block by	calling	"die":

	   return
	       LIST    { $db->retrieve_all($query) }
	       DEFAULT { croak "Invalid	call (not in list context)" }
	       RECOVER {
		   die $@ if $@;    # Propagate	any exception
		   $db->commit();   # Otherwise	commit the changes
	       }

       A "RECOVER" block can also access or replace the	returned value,	by
       invoking	a "RESULT" block. For example:

	   return
	       LIST    { attempt_to_generate_list_for(@_)  }
	       SCALAR  { attempt_to_generate_count_for(@_) }
	       RECOVER {
		   if ($@) {		    # On any exception...
		       warn "Replacing return value. Previously: ", RESULT;
		       RESULT {	undef }	    # ...return	undef
		   }
	       }

   Post-return clean-up
       Occasionally it's necessary to defer the	clean-up of resources until
       after the return	value has been used. Once again, this is usually done
       by returning an object with a suitable destructor.

       Using Contextual::Return	you can	get the	same effect, by	providing a
       "CLEANUP" block in the contextual return	sequence:

	   return
	       LIST    { $db->retrieve_all($query)  }
	       SCALAR  { $db->retrieve_next($query) }
	       CLEANUP { $db->commit()		    }

       In this example,	the "commit" method call is only performed after the
       return value has	been used by the caller. Note that this	is quite
       different from using a "RECOVER"	block, which is	called as the
       subroutine returns its value; a "CLEANUP" is called when	the returned
       value is	garbage	collected.

       A "CLEANUP" block is useful for controlling resources allocated to
       support an "ACTIVE" return value. For example:

	   my %file;

	   # Return an active value that is always the next line from a	file...
	   sub readline_from {
	       my ($file_name) = @_;

	       # Open the file,	if not already open...
	       if (!$file{$file_name}) {
		   open	$file{$file_name}{handle}, '<',	$file_name;
	       }

	       # Track how many	active return values are using this file...
	       $file{$file_name}{count}++;

	       return ACTIVE
		   # Evaluating	the return value returns the next line...
		   VALUE   { readline $file{$file_name}{handle}	}

		   # Once the active value is finished with, clean up the filehandle...
		   CLEANUP {
		       delete $file{$file_name}
			   if --$file{$file_name}{count} == 0;
		   }
	   }

   Debugging contextual	return values
       Contextual return values	are implemented	as opaque objects (using the
       "inside-out" technique).	This means that	passing	such values to
       Data::Dumper produces an	uninformative output like:

	   $VAR1 = bless( do{\(my $o = undef)},	'Contextual::Return::Value' );

       So the module provides two methods that allow contextual	return values
       to be correctly reported: either	directly, or when dumped by
       Data::Dumper.

       To dump a contextual return value directly, call	the module's "DUMP()"
       method explicitly and print the result:

	   print $crv->Contextual::Return::DUMP();

       This produces an	output something like:

	   [
	    { FROM	 => 'main::foo'					      },
	    { NO_HANDLER => [ 'VOID', 'CODEREF', 'HASHREF', 'GLOBREF' ]	      },
	    { FALLBACKS	 => [ 'VALUE' ]					      },
	    { LIST	 => [ 1, 2, 3, 4, 5, 6,	7, 8, 9, 10 ]		      },
	    { STR	 => '<<<Throws exception: Died at demo.pl line 7.>>>' },
	    { NUM	 => 42						      },
	    { BOOL	 => -1						      },
	    { SCALARREF	 => '<<<self-reference>>>'			      },
	    { ARRAYREF	 => [ 1, 2, 3, 4, 5, 6,	7, 8, 9, 10 ]		      },
	   ];

       The "FROM" hash entry names the subroutine that produced	the return
       value. The "NO_HANDLER" hash entry lists	those contexts for which no
       handler was defined (and	which would therefore normally produce "can't
       call" exceptions	such as: "Can't	call main::foo in VOID context").  The
       "FALLBACKS" hash	entry lists any	"generic" contexts such	as "VALUE",
       "NONVOID", "REF", "DEFAULT", etc. that the contextual return value can
       also handle. After these, all the remaining hash	entries	are actual
       contexts	in which the return value could	successfully be	evaluated, and
       the value it would produce in each of those contexts.

       The Data::Dumper	module also has	a mechanism by which you can tell it
       how to produce a	similar	listing	automatically whenever a contextual
       return value is passed to its "Dumper" method. Data::Dumper allows you
       to register a "freezer" method, that is called prior to dumping,	and
       which can be used to adapt an opaque object to make it dumpable.
       Contextual::Return provides just	such a method
       ("Contextual::Return::FREEZE()")	for you	to register, like so:

	   use Data::Dumper 'Dumper';

	   local $Data::Dumper::Freezer	= 'Contextual::Return::FREEZE';

	   print Dumper	$foo;

       The output is then precisely the	same as	"Contextual::Return::DUMP()"
       would produce.

       Note that, with both of the above dumping mechanisms, it	is essential
       to use the full name of the method. That	is:

	   print $crv->Contextual::Return::DUMP();

       rather than:

	   print $crv->DUMP();

       This is because the shorter version is interpreted as calling the
       "DUMP()"	method on the object returned by the return value's "OBJREF"
       context block (see "Scalar reference contexts")

       For the same reason, you	must write:

	   local $Data::Dumper::Freezer	= 'Contextual::Return::FREEZE';

       not:

	   local $Data::Dumper::Freezer	= 'FREEZE';

   Namespace controls
       By default the module exports a large number of return context markers:

	   DEFAULT    REF	   LAZY
	   VOID	      SCALARREF	   FIXED
	   NONVOID    ARRAYREF	   ACTIVE
	   LIST	      CODEREF	   RESULT
	   SCALAR     HASHREF	   RECOVER
	   VALUE      GLOBREF	   CLEANUP
	   STR	      OBJREF	   RVALUE
	   NUM	      METHOD	   LVALUE
	   BOOL			   NVALUE
	   PUREBOOL

       These are exported as subroutines, and so can conflict with existing
       subroutines in your namespace, or with subroutines imported from	other
       modules.

       Contextual::Return allows you to	control	which contextual return	blocks
       are exported into any namespace that uses the module. It	also allows
       you to rename blocks to avoid namespace conflicts with existing
       subroutines.

       Both these features are controlled by passing arguments to the "use"
       statement that loads the	module as follows:

       o   Any string passed as	an argument to "use Contextual::Return",
	   exports only	the block name it specifies;

       o   Any regex passed as an argument to "use Contextual::Return" exports
	   every block name it matches;

       o   Any array ref (recursively) exports each of its elements

       o   Any string that appears immediately after one of the	above three
	   specifiers, and which is not	itself a block name, renames the
	   handlers exported by	that preceding specifier by filtering each
	   handler name	through	"sprintf()"

       That is,	you can	specify	handlers to be exported	by exact name (as a
       string),	by general pattern (as a regex), or collectively (in an
       array). And after any of	these export specifications, you can append a
       template	in which any '%s' will be replaced by the original name	of the
       handler.	For example:

	   # Selectively export	specific sets of handlers...
	   use Contextual::Return  qr/[NLR]VALUE/;
	   use Contextual::Return  qr/.*REF/;

	   # Selective export specific sets and	add a suffix to	each...
	   use Contextual::Return  qr/[NLR]VALUE/ => '%s_CONTEXT';

	   # Selective export specific sets and	add a prefix to	each...
	   use Contextual::Return  qr/.*REF/ =>	'CR_%s';

	   # Export a list of handlers...
	   use Contextual::Return    'NUM', 'STR', 'BOOL' ;
	   use Contextual::Return qw< NUM    STR    BOOL >;
	   use Contextual::Return   ['NUM', 'STR', 'BOOL'];

	   # Export a list of handlers,	renaming them individually...
	   use Contextual::Return  NUM => 'NUMERIC', STR => 'TEXT', BOOL => 'CR_%s';

	   # Export a list of handlers,	renaming them collectively...
	   use Contextual::Return  ['NUM', 'STR', 'BOOL'] => '%s_CONTEXT';

	   # Mixed exports and renames...
	   use Contextual::Return (
	       STR => 'TEXT',
	       ['NUM', 'BOOL'] => 'CR_%s',
	       ['LIST',	'SCALAR', 'VOID', qr/^[NLR]VALUE/] => '%s_CONTEXT',
	   );

INTERFACE
   Context tests
       "LIST()"
	   Returns true	if the current subroutine was called in	list context.
	   A cleaner way of writing: "wantarray()"

       "SCALAR()"
	   Returns true	if the current subroutine was called in	scalar
	   context.  A cleaner way of writing: "defined	wantarray() && !
	   wantarray()"

       "VOID()"
	   Returns true	if the current subroutine was called in	void context.
	   A cleaner way of writing: "!defined wantarray()"

       "NONVOID()"
	   Returns true	if the current subroutine was called in	list or	scalar
	   context.  A cleaner way of writing: "defined	wantarray()"

   Standard contexts
       "LIST {...}"
	   The block specifies what the	context	sequence should	evaluate to
	   when	called in list context.

       "SCALAR {...}"
	   The block specifies what the	context	sequence should	evaluate to in
	   scalar contexts, unless some	more-specific specifier	scalar context
	   specifier (see below) also occurs in	the same context sequence.

       "VOID {...}"
	   The block specifies what the	context	sequence should	do when	called
	   in void context.

   Scalar value	contexts
       "BOOL {...}"
	   The block specifies what the	context	sequence should	evaluate to
	   when	treated	as a boolean value.

       "NUM {...}"
	   The block specifies what the	context	sequence should	evaluate to
	   when	treated	as a numeric value.

       "STR {...}"
	   The block specifies what the	context	sequence should	evaluate to
	   when	treated	as a string value.

       "LAZY {...}"
	   Another name	for "SCALAR {...}". Usefully self-documenting when the
	   primary purpose of the contextual return is to defer	evaluation of
	   the return value until it's actually	required.

   Scalar reference contexts
       "SCALARREF {...}"
	   The block specifies what the	context	sequence should	evaluate to
	   when	treated	as a reference to a scalar.

       "ARRAYREF {...}"
	   The block specifies what the	context	sequence should	evaluate to
	   when	treated	as a reference to an array.

       "HASHREF	{...}"
	   The block specifies what the	context	sequence should	evaluate to
	   when	treated	as a reference to a hash.

	   Note	that a common error here is to write:

	   HASHREF { a=>1, b=>2, c=>3 }

	   The curly braces there are a	block, not a hash constructor, so the
	   block doesn't return	a hash reference and the interpreter throws an
	   exception.  What's needed is:

	   HASHREF { {a=>1, b=>2, c=>3}	}

	   in which the	inner braces are a hash	constructor.

       "CODEREF	{...}"
	   The block specifies what the	context	sequence should	evaluate to
	   when	treated	as a reference to a subroutine.

       "GLOBREF	{...}"
	   The block specifies what the	context	sequence should	evaluate to
	   when	treated	as a reference to a typeglob.

       "OBJREF {...}"
	   The block specifies what the	context	sequence should	evaluate to
	   when	treated	as a reference to an object.

       "METHOD {...}"
	   The block can be used to specify particular handlers	for specific
	   method calls	when the return	value is treated as an object
	   reference.  It should return	a list of methodname/methodbody	pairs.
	   Each	method name can	be specified as	a string, a regex, or an array
	   of strings or regexes. The method bodies must be specified as
	   subroutine references (usually anonymous subs). The first method
	   name	that matches the actual	method call selects the	corresponding
	   handler, which is then called.

   Generic contexts
       "VALUE {...}"
	   The block specifies what the	context	sequence should	evaluate to
	   when	treated	as a non-referential value (as a boolean, numeric,
	   string, scalar, or list). Only used if there	is no more-specific
	   value context specifier in the context sequence.

       "REF {...}"
	   The block specifies what the	context	sequence should	evaluate to
	   when	treated	as a reference of any kind. Only used if there is no
	   more-specific referential context specifier in the context
	   sequence.

       "NONVOID	{...}"
	   The block specifies what the	context	sequence should	evaluate to
	   when	used in	a non-void context of any kind.	Only used if there is
	   no more-specific context specifier in the context sequence.

       "DEFAULT	{...}"
	   The block specifies what the	context	sequence should	evaluate to
	   when	used in	a void or non-void context of any kind.	Only used if
	   there is no more-specific context specifier in the context
	   sequence.

   Failure context
       "FAIL"
	   This	block is executed unconditionally and is used to indicate
	   failure. In a Boolean context it return false. In all other
	   contexts it throws an exception consisting of the final evaluated
	   value of the	block.

	   That	is, using "FAIL":

	   return FAIL { "Could	not defenestrate the widget" }

	   is exactly equivalent to writing:

	   return BOOL { 0 } DEFAULT { croak "Could not	defenestrate the
	   widget" }

	   except that the reporting of	errors is a little smarter under
	   "FAIL".

	   If "FAIL" is	called without specifying a block:

	   return FAIL;

	   it is equivalent to:

	   return FAIL { croak "Call to	<subname> failed" }

	   (where "<subname>" is replaced with the name	of the surrounding
	   subroutine).

	   Note	that, because "FAIL" implicitly	covers every possible return
	   context, it cannot be chained with other context specifiers.

       "Contextual::Return::FAIL_WITH"
	   This	subroutine is not exported, but	may be called directly to
	   reconfigure "FAIL" behaviour	in the caller's	namespace.

	   The subroutine is called with an optional string (the flag),
	   followed by a mandatory hash	reference (the configurations hash),
	   followed by a list of zero-or-more strings (the selector list). The
	   values of the configurations	hash must all be subroutine
	   references.

	   If the optional flag	is specified, "FAIL_WITH" searches the
	   selector list looking for that string, then uses the	following item
	   in the selector list	as its selector	value. If that selector	value
	   is a	string,	"FAIL_WITH" looks up that key in the hash, and
	   installs the	corresponding subroutine as the	namespace's "FAIL"
	   handler (an exception is thrown if the selector string is not a
	   valid key of	the configurations hash). If the selector value	is a
	   subroutine reference, "FAIL_WITH" installs that subroutine as the
	   "FAIL" handler.

	   If the optional flag	is not specified, "FAIL_WITH" searches the
	   entire selector list	looking	for the	last element that matches any
	   key in the configurations hash. It then looks up that key in	the
	   hash, and installs the corresponding	subroutine as the namespace's
	   "FAIL" handler.

	   See "Configurable failure contexts" for examples of using this
	   feature.

   Lvalue contexts
       "LVALUE"
	   This	block is executed when the result of an	":lvalue" subroutine
	   is assigned to. The assigned	value is passed	to the block as	$_. To
	   access the caller's $_ value, use $CALLER::_.

       "RVALUE"
	   This	block is executed when the result of an	":lvalue" subroutine
	   is used as an rvalue. The final value that is evaluated in the
	   block becomes the rvalue.

       "NVALUE"
	   This	block is executed when an ":lvalue" subroutine is evaluated in
	   void	context.

   Explicit result blocks
       "RESULT"
	   This	block may only appear inside a context handler block. It
	   causes the surrounding handler to return the	final value of the
	   "RESULT"'s block, rather than the final value of the	handler's own
	   block. This override	occurs regardless of the location to the
	   "RESULT" block within the handler.

	   If called without a trailing	"{...}", it simply returns the current
	   result value	in scalar contexts, or the list	of result values in
	   list	context.

   Recovery blocks
       "RECOVER"
	   If present in a context return sequence, this block grabs control
	   after any context handler returns or	exits via an exception.	If an
	   exception was thrown	it is passed to	the "RECOVER" block via	the $@
	   variable.

   Clean-up blocks
       "CLEANUP"
	   If present in a context return sequence, this block grabs control
	   when	a return value is garbage collected.

   Modifiers
       "FIXED"
	   This	specifies that the scalar value	will only be evaluated once,
	   the first time it is	used, and that the value will then morph into
	   that	evaluated value.

       "ACTIVE"
	   This	specifies that the scalar value's originating block will be
	   re- evaluated every time the	return value is	used.

   Debugging support
       "$crv->Contextual::Return::DUMP()"
	   Return a dumpable representation of the return value	in all viable
	   contexts.

       "local $Data::Dumper::Freezer = 'Contextual::Return::FREEZE';"
       "local $Data::Dumper::Freezer = \&Contextual::Return::FREEZE;"
	   Configure Data::Dumper to correctly dump a representation of	the
	   contextual return value.

DIAGNOSTICS
       "Can't use %s as	export specifier"
	   In your "use	Contextual::Return" statement you specified something
	   (such as a hash or coderef) that can't be used to select what the
	   module exports. Make	sure the list of selectors includes only
	   strings, regexes, or	references to arrays of	strings	or regexes.

       "use Contextual::Return qr{%s} didn't export anything"
	   In your "use	Contextual::Return" statement you specified a regex to
	   select which	handlers to support, but the regex didn't select any
	   handlers. Check that	the regex you're using actually	does match at
	   least one of	the names of the modules many handlers.

       "Can't export %s: no such handler"
	   In your "use	Contextual::Return" statement you specified a string
	   as the name of a context handler to be exported, but	the module
	   doesn't export a handler of that name. Check	the spelling for the
	   requested export.

       "Can't call %s in a %s context"
       "Can't use return value of %s in	a %s context"
	   The subroutine you called uses a contextual return, but doesn't
	   specify what	to return in the particular context in which you
	   called it. You either need to change	the context in which you're
	   calling the subroutine, or else add a context block corresponding
	   to the offending context (or	perhaps	a "DEFAULT {...}" block).

       "Can't call bare	%s {...} in %s context"
	   You specified a handler (such as "VOID {...}" or "LIST {...}")
	   outside any subroutine, and in a context that it can't handle. Did
	   you mean to place the handler outside of a subroutine?  If so, then
	   you need to put it in a context it can actually handle.  Otherwise,
	   perhaps you need to replace the trailing block with parens (that
	   is: "VOID()"	or "LIST()").

       "Call to	%s at %s didn't	return a %s reference""
	   You called the subroutine in	a context that expected	to get back a
	   reference of	some kind but the subroutine didn't specify the
	   corresponding "SCALARREF", "ARRAYREF", "HASHREF", "CODEREF",
	   "GLOBREF", or generic "REF",	"NONVOID", or "DEFAULT"	handlers.  You
	   need	to specify the appropriate one of these	handlers in the
	   subroutine.

       "Can't call method '%s' on %s value returned by %s""
	   You called the subroutine and then tried to call a method on	the
	   return value, but the subroutine returned a classname or object
	   that	doesn't	have that method. This probably	means that the
	   subroutine didn't return the	classname or object you	expected. Or
	   perhaps you need to specify an "OBJREF {...}" context block.

       "Can't install two %s handlers"
	   You attempted to specify two	context	blocks of the same name	in the
	   same	return context,	which is ambiguous. For	example:

	       sub foo:	lvalue {
		   LVALUE { $foo = $_ }
		   RVALUE { $foo }
		   LVALUE { $foo = substr($_,1,10) }
	       }

	   or:

	       sub bar {
		   return
		       BOOL { 0	}
		       NUM  { 1	}
		       STR  { "two" }
		       BOOL { 1	};
	       }

	   Did you cut-and-paste wrongly, or mislabel one of the blocks?

       "Expected a %s block after the %s block but found instead: %s"
	   If you specify any of "LVALUE", "RVALUE", or	"NVALUE", then you can
	   only	specify	"LVALUE", "RVALUE", or "NVALUE"	blocks in the same
	   return context.  If you need	to specify other contexts (like
	   "BOOL", or "STR", or	"REF", etc.), put them inside an "RVALUE"
	   block. See "Lvalue contexts"	for an example.

       "Call to	%s failed at %s"
	   This	is the default exception that a	"FAIL" throws in a non-scalar
	   context. Which means	that the subroutine you	called has signalled
	   failure by throwing an exception, and you didn't catch that
	   exception.  You should either put the call in an "eval {...}" block
	   or else call	the subroutine in boolean context instead.

       "Call to	%s failed at %s. Attempted to use failure value	at %s"
	   This	is the default exception that a	"FAIL" throws when a failure
	   value is captured in	a scalar variable and later used in a non-
	   boolean context. That means that the	subroutine you called must
	   have	failed,	and you	didn't check the return	value for that
	   failure, so when you	tried to use that invalid value	it killed your
	   program. You	should either put the original call in an "eval	{...}"
	   or else test	the return value in a boolean context and avoid	using
	   it if it's false.

       "Usage: FAIL_WITH $flag_opt, \%selector,	@args"
	   The "FAIL_WITH" subroutine expects an optional flag,	followed by a
	   reference to	a configuration	hash, followed by a list or selector
	   arguments. You gave it something else. See "Configurable Failure
	   Contexts".

       "Selector values	must be	sub refs"
	   You passed a	configuration hash to "FAIL_WITH" that specified non-
	   subroutines as possible "FAIL" handlers. Since non-subroutines
	   can't possibly be handlers, maybe you forgot	the "sub" keyword
	   somewhere?

       "Invalid	option:	%s =" %s>
	   The "FAIL_WITH" subroutine was passed a flag/selector pair, but the
	   selector was	not one	of those allowed by the	configuration hash.

       "FAIL handler for package %s redefined"
	   A warning that the "FAIL" handler for a particular package was
	   reconfigured	more than once.	Typically that's because the module
	   was loaded in two places with difference configurations specified.
	   You can't reasonably	expect two different sets of behaviours	from
	   the one module within the one namespace.

CONFIGURATION AND ENVIRONMENT
       Contextual::Return requires no configuration files or environment
       variables.

DEPENDENCIES
       Requires	version.pm and Want.pm.

INCOMPATIBILITIES
       "LVALUE", "RVALUE", and "NVALUE"	do not work correctly under the	Perl
       debugger. This seems to be because the debugger injects code to capture
       the return values from subroutines, which interferes destructively with
       the optional final arguments that allow "LVALUE", "RVALUE", and
       "NVALUE"	to cascade within a single return.

BUGS AND LIMITATIONS
       No bugs have been reported.

AUTHOR
       Damian Conway  "<DCONWAY@cpan.org>"

LICENCE	AND COPYRIGHT
       Copyright (c) 2005-2011,	Damian Conway "<DCONWAY@cpan.org>". All	rights
       reserved.

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

DISCLAIMER OF WARRANTY
       BECAUSE THIS SOFTWARE IS	LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
       FOR THE SOFTWARE, TO THE	EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
       WHEN OTHERWISE STATED IN	WRITING	THE COPYRIGHT HOLDERS AND/OR OTHER
       PARTIES PROVIDE THE SOFTWARE "AS	IS" WITHOUT WARRANTY OF	ANY KIND,
       EITHER EXPRESSED	OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
       WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
       ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF	THE SOFTWARE IS	WITH
       YOU. SHOULD THE SOFTWARE	PROVE DEFECTIVE, YOU ASSUME THE	COST OF	ALL
       NECESSARY SERVICING, REPAIR, OR CORRECTION.

       IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR	AGREED TO IN WRITING
       WILL ANY	COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
       REDISTRIBUTE THE	SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
       TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
       CONSEQUENTIAL DAMAGES ARISING OUT OF THE	USE OR INABILITY TO USE	THE
       SOFTWARE	(INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
       RENDERED	INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
       FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
       SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
       DAMAGES.

perl v5.24.1			  2017-04-14		 Contextual::Return(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | INTERFACE | DIAGNOSTICS | CONFIGURATION AND ENVIRONMENT | DEPENDENCIES | INCOMPATIBILITIES | BUGS AND LIMITATIONS | AUTHOR | LICENCE AND COPYRIGHT | DISCLAIMER OF WARRANTY

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

home | help