1Contextual::Return(3) User Contributed Perl DocumentationContextual::Return(3)
2
6 Contextual::Return - Create context-sensitive return values
7
9 This document describes Contextual::Return version 0.004014
10
12 use Contextual::Return;
13 use Carp;
14 sub foo {
16 return
17 SCALAR { 'thirty-twelve' }
18 LIST { 1,2,3 }
19 BOOL { 1 }
21 NUM { 7*6 }
22 STR { 'forty-two' }
23 HASHREF { {name => 'foo', value => 99} }
25 ARRAYREF { [3,2,1] }
26 GLOBREF { \*STDOUT }
28 CODEREF { croak "Don't use this result as code!"; }
29 ;
30 }
31 # and later...
33 if (my $foo = foo()) {
35 for my $count (1..$foo) {
36 print "$count: $foo is:\n"
37 . " array: @{$foo}\n"
38 . " hash: $foo->{name} => $foo->{value}\n"
39 ;
40 }
41 print {$foo} $foo->();
42 }
43
45 Usually, when you need to create a subroutine that returns different
46 values in different contexts (list, scalar, or void), you write
47 something like:
48 sub get_server_status {
50 my ($server_ID) = @_;
51 # Acquire server data somehow...
53 my %server_data = _ascertain_server_status($server_ID);
54 # Return different components of that data,
56 # depending on call context...
57 if (wantarray()) {
58 return @server_data{ qw(name uptime load users) };
59 }
60 if (defined wantarray()) {
61 return $server_data{load};
62 }
63 if (!defined wantarray()) {
64 carp 'Useless use of get_server_status() in void context';
65 return;
66 }
67 else {
68 croak q{Bad context! No biscuit!};
69 }
70 }
71 That works okay, but the code could certainly be more readable. In its
73 simplest usage, this module makes that code more readable by providing
74 three subroutines--"LIST()", "SCALAR()", "VOID()"--that are true only
75 when the current subroutine is called in the corresponding context:
76 use Contextual::Return;
78 sub get_server_status {
80 my ($server_ID) = @_;
81 # Acquire server data somehow...
83 my %server_data = _ascertain_server_status($server_ID);
84 # Return different components of that data
86 # depending on call context...
87 if (LIST) { return @server_data{ qw(name uptime load users) } }
88 if (SCALAR) { return $server_data{load} }
89 if (VOID) { print "$server_data{load}\n" }
90 else { croak q{Bad context! No biscuit!} }
91 }
92 Contextual returns
94 Those three subroutines can also be used in another way: as labels on a
95 series of contextual return blocks (collectively known as a contextual
96 return sequence). When a context sequence is returned, it automatically
97 selects the appropriate contextual return block for the calling
98 context. So the previous example could be written even more cleanly
99 as:
100 use Contextual::Return;
102 sub get_server_status {
104 my ($server_ID) = @_;
105 # Acquire server data somehow...
107 my %server_data = _ascertain_server_status($server_ID);
108 # Return different components of that data
110 # depending on call context...
111 return (
112 LIST { return @server_data{ qw(name uptime load users) } }
113 SCALAR { return $server_data{load} }
114 VOID { print "$server_data{load}\n" }
115 DEFAULT { croak q{Bad context! No biscuit!} }
116 );
117 }
118 The context sequence automatically selects the appropriate block for
120 each call context.
121 Lazy contextual return values
123 "LIST" and "VOID" blocks are always executed during the "return"
124 statement. However, scalar return blocks ("SCALAR", "STR", "NUM",
125 "BOOL", etc.) blocks are not. Instead, returning any of scalar block
126 types causes the subroutine to return an object that lazily evaluates
127 that block only when the return value is used.
128 This means that returning a "SCALAR" block is a convenient way to
130 implement a subroutine with a lazy return value. For example:
131 sub digest {
133 return SCALAR {
134 my ($text) = @_;
135 md5($text);
136 }
137 }
138 my $digest = digest($text);
140 print $digest; # md5() called only when $digest used as string
142 To better document this usage, the "SCALAR" block has a synonym:
144 "LAZY".
145 sub digest {
147 return LAZY {
148 my ($text) = @_;
149 md5($text);
150 }
151 }
152 Active contextual return values
154 Once a return value has been lazily evaluated in a given context, the
155 resulting value is cached, and thereafter reused in that same context.
156 However, you can specify that, rather than being cached, the value
158 should be re-evaluated every time the value is used:
159 sub make_counter {
161 my $counter = 0;
162 return ACTIVE
163 SCALAR { ++$counter }
164 ARRAYREF { [1..$counter] }
165 }
166 my $idx = make_counter();
168 print "$idx\n"; # 1
170 print "$idx\n"; # 2
171 print "[@$idx]\n"; # [1 2]
172 print "$idx\n"; # 3
173 print "[@$idx]\n"; # [1 2 3]
174 Semi-lazy contextual return values
176 Sometimes, single or repeated lazy evaluation of a scalar return value
177 in different contexts isn't what you really want. Sometimes what you
178 really want is for the return value to be lazily evaluated once only
179 (the first time it's used in any context), and then for that first
180 value to be reused whenever the return value is subsequently
181 reevaluated in any other context.
182 To get that behaviour, you can use the "FIXED" modifier, which causes
184 the return value to morph itself into the actual value the first time
185 it is used. For example:
186 sub lazy {
188 return
189 SCALAR { 42 }
190 ARRAYREF { [ 1, 2, 3 ] }
191 ;
192 }
193 my $lazy = lazy();
195 print $lazy + 1; # 43
196 print "@{$lazy}"; # 1 2 3
197 sub semilazy {
200 return FIXED
201 SCALAR { 42 }
202 ARRAYREF { [ 1, 2, 3 ] }
203 ;
204 }
205 my $semi = semilazy();
207 print $semi + 1; # 43
208 print "@{$semi}"; # die q{Can't use string ("42") as an ARRAY ref}
209 Finer distinctions of scalar context
211 Because the scalar values returned from a context sequence are lazily
212 evaluated, it becomes possible to be more specific about what kind of
213 scalar value should be returned: a boolean, a number, or a string. To
214 support those distinctions, Contextual::Return provides four extra
215 context blocks: "NUM", "STR", "BOOL", and "PUREBOOL":
216 sub get_server_status {
218 my ($server_ID) = @_;
219 # Acquire server data somehow...
221 my %server_data = _ascertain_server_status($server_ID);
222 # Return different components of that data
224 # depending on call context...
225 return (
226 LIST { @server_data{ qw(name uptime load users) } }
227 PUREBOOL { $_ = $server_data{uptime}; $server_data{uptime} > 0 }
228 BOOL { $server_data{uptime} > 0 }
229 NUM { $server_data{load} }
230 STR { "$server_data{name}: $server_data{uptime}" }
231 VOID { print "$server_data{load}\n" }
232 DEFAULT { croak q{Bad context! No biscuit!} }
233 );
234 }
235 With these in place, the object returned from a scalar-context call to
237 "get_server_status()" now behaves differently, depending on how it's
238 used. For example:
239 if ( my $status = get_server_status() ) { # BOOL: True if uptime > 0
241 $load_distribution[$status]++; # INT: Evaluates to load value
242 print "$status\n"; # STR: Prints "name: uptime"
243 }
244 if (get_server_status()) { # PUREBOOL: also sets $_;
246 print; # ...which is then used here
247 }
248 Boolean vs Pure Boolean contexts
250 There is a special subset of boolean contexts where the return value is
252 being used and immediately thrown away. For example, in the loop:
253 while (get_data()) {
255 ...
256 }
257 the value returned by "get_data()" is tested for truth and then
259 discarded. This is known as "pure boolean context". In contrast, in
260 the loop:
261 while (my $data = get_data()) {
263 ...
264 }
265 the value returned by "get_data()" is first assigned to $data, then
267 tested for truth. Because of the assignment, the return value is not
268 discarded after the boolean test. This is ordinary "boolean context".
269 In Perl, pure boolean context is often associated with a special side-
271 effect, that does not occur in regular boolean contexts. For example:
272 while (<>) {...} # $_ set as side-effect of pure boolean context
274 while ($v = <>) {...} # $_ NOT set in ordinary boolean context
276 Contextual::Return supports this with a special subcase of "BOOL" named
278 <PUREBOOL>. In pure boolean contexts, Contextual::Return will call a
279 "PUREBOOL" handler if one has been defined, or fall back to a "BOOL" or
280 "SCALAR" handler if no "PUREBOOL" handler exists. In ordinary boolean
281 contexts only the "BOOL" or "SCALAR" handlers are tried, even if a
282 "PUREBOOL" handler is also defined.
283 Typically "PUREBOOL" handlers are set up to have some side-effect (most
285 commonly: setting $_ or <$@>), like so:
286 sub get_data {
288 my ($succeeded, @data) = _go_and_get_data();
289 return
291 PUREBOOL { $_ = $data[0]; $succeeded; }
292 BOOL { $succeeded; }
293 SCALAR { $data[0]; }
294 LIST { @data; }
295 }
296 However, there is no requirement that they have side-effects. For
298 example, they can also be used to implement "look-but-don't-retrieve-
299 yet" checking:
300 sub get_data {
302 my $data;
303 return
304 PUREBOOL { _check_for_but_dont_get_data(); }
305 BOOL { defined( $data ||= _go_and_get_data() ); }
306 REF { $data ||= _go_and_get_data(); }
307 }
308 Self-reference within handlers
310 Any handler can refer to the contextual return object it is part of, by
311 calling the "RETOBJ()" function. This is particularly useful for
312 "PUREBOOL" and "LIST" handlers. For example:
313 return
315 PUREBOOL { $_ = RETOBJ; next handler; }
316 BOOL { !$failed; }
317 DEFAULT { $data; };
318 Referential contexts
320 The other major kind of scalar return value is a reference.
321 Contextual::Return provides contextual return blocks that allow you to
322 specify what to (lazily) return when the return value of a subroutine
323 is used as a reference to a scalar ("SCALARREF {...}"), to an array
324 ("ARRAYREF {...}"), to a hash ("HASHREF {...}"), to a subroutine
325 ("CODEREF {...}"), or to a typeglob ("GLOBREF {...}").
326 For example, the server status subroutine shown earlier could be
328 extended to allow it to return a hash reference, thereby supporting
329 "named return values":
330 sub get_server_status {
332 my ($server_ID) = @_;
333 # Acquire server data somehow...
335 my %server_data = _ascertain_server_status($server_ID);
336 # Return different components of that data
338 # depending on call context...
339 return (
340 LIST { @server_data{ qw(name uptime load users) } }
341 BOOL { $server_data{uptime} > 0 }
342 NUM { $server_data{load} }
343 STR { "$server_data{name}: $server_data{uptime}" }
344 VOID { print "$server_data{load}\n" }
345 HASHREF { return \%server_data }
346 DEFAULT { croak q{Bad context! No biscuit!} }
347 );
348 }
349 # and later...
351 my $users = get_server_status->{users};
353 # or, lazily...
356 my $server = get_server_status();
358 print "$server->{name} load = $server->{load}\n";
360 Interpolative referential contexts
362 The "SCALARREF {...}" and "ARRAYREF {...}" context blocks are
363 especially useful when you need to interpolate a subroutine into
364 strings. For example, if you have a subroutine like:
365 sub get_todo_tasks {
367 return (
368 SCALAR { scalar @todo_list } # How many?
369 LIST { @todo_list } # What are they?
370 );
371 }
372 # and later...
374 print "There are ", scalar(get_todo_tasks()), " tasks:\n",
376 get_todo_tasks();
377 then you could make it much easier to interpolate calls to that
379 subroutine by adding:
380 sub get_todo_tasks {
382 return (
383 SCALAR { scalar @todo_list } # How many?
384 LIST { @todo_list } # What are they?
385 SCALARREF { \scalar @todo_list } # Ref to how many
387 ARRAYREF { \@todo_list } # Ref to them
388 );
389 }
390 # and then...
392 print "There are ${get_todo_tasks()} tasks:\n@{get_todo_tasks()}";
394 In fact, this behaviour is so useful that it's the default. If you
396 don't provide an explicit "SCALARREF {...}" block, Contextual::Return
397 automatically provides an implicit one that simply returns a reference
398 to whatever would have been returned in scalar context. Likewise, if
399 no "ARRAYREF {...}" block is specified, the module supplies one that
400 returns the list-context return value wrapped up in an array reference.
401 So you could just write:
403 sub get_todo_tasks {
405 return (
406 SCALAR { scalar @todo_list } # How many?
407 LIST { @todo_list } # What are they?
408 );
409 }
410 # and still do this...
412 print "There are ${get_todo_tasks()} tasks:\n@{get_todo_tasks()}";
414 Fallback contexts
416 As the previous sections imply, the "BOOL {...}", "NUM {...}", "STR
417 {...}", and various "*REF {...}" blocks, are special cases of the
418 general "SCALAR {...}" context block. If a subroutine is called in one
419 of these specialized contexts but does not use the corresponding
420 context block, then the more general "SCALAR {...}" block is used
421 instead (if it has been specified).
422 So, for example:
424 sub read_value_from {
426 my ($fh) = @_;
427 my $value = <$fh>;
429 chomp $value;
430 return (
432 BOOL { defined $value }
433 SCALAR { $value }
434 );
435 }
436 ensures that the "read_value_from()" subroutine returns true in boolean
438 contexts if the read was successful. But, because no specific "NUM
439 {...}" or "STR {...}" return behaviours were specified, the subroutine
440 falls back on using its generic "SCALAR {...}" block in all other
441 scalar contexts.
442 Another way to think about this behaviour is that the various kinds of
444 scalar context blocks form a hierarchy:
445 SCALAR
447 ^
448 |
449 |--< BOOL
450 |
451 |--< NUM
452 |
453 `--< STR
454 Contextual::Return uses this hierarchical relationship to choose the
456 most specific context block available to handle any particular return
457 context, working its way up the tree from the specific type it needs,
458 to the more general type, if that's all that is available.
459 There are two slight complications to this picture. The first is that
461 Perl treats strings and numbers as interconvertable so the diagram (and
462 the Contextual::Return module) also has to allow these interconversions
463 as a fallback strategy:
464 SCALAR
466 ^
467 |
468 |--< BOOL
469 |
470 |--< NUM
471 | : ^
472 | v :
473 `--< STR
474 The dotted lines are meant to indicate that this intraconversion is
476 secondary to the main hierarchical fallback. That is, in a numeric
477 context, a "STR {...}" block will only be used if there is no "NUM
478 {...}" block and no "SCALAR {...}" block. In other words, the generic
479 context type is always used in preference to string<->number
480 conversion.
481 The second slight complication is that the above diagram only shows a
483 small part of the complete hierarchy of contexts supported by
484 Contextual::Return. The full fallback hierarchy (including dotted
485 interconversions) is:
486 DEFAULT
488 ^
489 |
490 |--< VOID
491 |
492 `--< NONVOID
493 ^
494 |
495 |--< VALUE <...............
496 | ^ :
497 | | :
498 | |--< SCALAR <.......:...
499 | | ^ :
500 | | | :
501 | | |--< BOOL :
502 | | | ^ :
503 | | | | :
504 | | | PUREBOOL :
505 | | | :
506 | | |--< NUM <..:.
507 | | | : ^ :
508 | | | v : :
509 | | `--< STR <....:..
510 | | :
511 | | ::
512 | `--< LIST ................: :
513 | : ^ :
514 | : : :
515 `--- REF : : :
516 ^ : : :
517 | v : :
518 |--< ARRAYREF :
519 | :
520 |--< SCALARREF .............:
521 |
522 |--< HASHREF
523 |
524 |--< CODEREF
525 |
526 |--< GLOBREF
527 |
528 `--< OBJREF <....... METHOD
529 ^
530 :........... BLESSED
531 As before, each dashed arrow represents a fallback relationship. That
533 is, if the required context specifier isn't available, the arrows are
534 followed until a more generic one is found. The dotted arrows again
535 represent the interconversion of return values, which is attempted only
536 after the normal hierarchical fallback fails.
537 For example, if a subroutine is called in a context that expects a
539 scalar reference, but no "SCALARREF {...}" block is provided, then
540 Contextual::Return tries the following blocks in order:
541 REF {...}
543 NONVOID {...}
544 DEFAULT {...}
545 STR {...} (automatically taking a reference to the result)
546 NUM {...} (automatically taking a reference to the result)
547 SCALAR {...} (automatically taking a reference to the result)
548 VALUE {...} (automatically taking a reference to the result)
549 Likewise, in a list context, if there is no "LIST {...}" context block,
551 the module tries:
552 VALUE {...}
554 NONVOID {...}
555 DEFAULT {...}
556 ARRAYREF {...} (automatically dereferencing the result)
557 STR {...} (treating it as a list of one element)
558 NUM {...} (treating it as a list of one element)
559 SCALAR {...} (treating it as a list of one element)
560 The more generic context blocks are especially useful for intercepting
562 unexpected and undesirable call contexts. For example, to turn off the
563 automatic scalar-ref and array-ref interpolative behaviour described in
564 "Interpolative referential contexts", you could intercept all
565 referential contexts using a generic "REF {...}" context block:
566 sub get_todo_tasks {
568 return (
569 SCALAR { scalar @todo_list } # How many?
570 LIST { @todo_list } # What are they?
571 REF { croak q{get_todo_task() can't be used as a reference} }
573 );
574 }
575 print 'There are ', get_todo_tasks(), '...'; # Still okay
577 print "There are ${get_todo_tasks()}..."; # Throws an exception
578 Treating return values as objects
580 Normally, when a return value is treated as an object (i.e. has a
581 method called on it), Contextual::Return invokes any "OBJREF" handler
582 that was specified in the contextual return list, and delegates the
583 method call to the object returned by that handler.
584 However, you can also be more specific, by specifying a "METHOD"
586 context handler in the contextual return list. The block of this
587 handler is expected to return one or more method-name/method-handler
588 pairs, like so:
589 return
591 METHOD {
592 get_count => sub { my $n = shift; $data[$n]{count} },
593 get_items => sub { my $n = shift; $data[$n]{items} },
594 clear => sub { @data = (); },
595 reset => sub { @data = (); },
596 }
597 Then, whenever one of the specified methods is called on the return
599 value, the corresponding subroutine will be called to implement it.
600 The method handlers must always be subroutine references, but the
602 method-name specifiers may be strings (as in the previous example) or
603 they may be specified generically, as either regexes or array
604 references. Generic method names are used to call the same handler for
605 two or more distinct method names. For example, the previous example
606 could be simplified to:
607 return
609 METHOD {
610 qr/get_(\w+)/ => sub { my $n = shift; $data[$n]{$1} },
611 ['clear','reset'] => sub { @data = (); },
612 }
613 A method name specified by regex will invoke the corresponding handler
615 for any method call request that the regex matches. A method name
616 specified by array ref will invoke the corresponding handler if the
617 method requested matches any of the elements of the array (which may
618 themselves be strings or regexes).
619 When the method handler is invoked, the name of the method requested is
621 passed to the handler in $_, and the method's argument list is passed
622 (as usual) via @_.
623 Note that any methods not explicitly handled by the "METHOD" handlers
625 will still be delegated to the object returned by the "OBJREF" handler
626 (if it is also specified).
627 Not treating return values as objects
629 The use of "OBJREF" and "METHOD" are slightly complicated by the fact
630 that contextual return values are themselves objects.
631 For example, prior to version 0.4.4 of the module, if you passed a
633 contextual return value to "Scalar::Util::blessed()", it always
634 returned a true value (namely, the string:
635 'Contextual::Return::Value'), even if the return value had not
636 specified handlers for "OBJREF" or "METHOD".
637 In other words, the implementation of contextual return values (as
639 objects) was getting in the way of the use of contextual return values
640 (as non-objects).
641 So the module now also provides a "BLESSED" handler, which allows you
643 to explicitly control how contextual return values interact with
644 "Scalar::Util::blessed()".
645 If $crv is a contextual return value, by default
647 "Scalar::Util::blessed($crv)" will now only return true if that return
648 value has a "OBJREF", "LAZY", "REF", "SCALAR", "VALUE", "NONVOID", or
649 "DEFAULT" handler that in turn returns a blessed object.
650 However if $crv also provides a "BLESSED" handler, "blessed()" will
652 return whatever that handler returns.
653 This means:
655 sub simulate_non_object {
657 return BOOL { 1 }
658 NUM { 42 }
659 }
660 sub simulate_real_object {
662 return OBJREF { bless {}, 'My::Class' }
663 BOOL { 1 }
664 NUM { 42 }
665 }
666 sub simulate_faked_object {
668 return BLESSED { 'Foo' }
669 BOOL { 1 }
670 NUM { 42 }
671 }
672 sub simulate_previous_behaviour {
674 return BLESSED { 'Contextual::Return::Value' }
675 BOOL { 1 }
676 NUM { 42 }
677 }
678 say blessed( simulate_non_object() ); # undef
681 say blessed( simulate_real_object() ); # My::Class
682 say blessed( simulate_faked_object() ); # Foo
683 say blessed( simulate_previous_behaviour() ); # Contextual::Return::Value
684 Typically, you either want no "BLESSED" handler (in which case
686 contextual return values pretend not to be blessed objects), or you
687 want "BLESSED { 'Contextual::Return::Value' }" for backwards
688 compatibility with pre-v0.4.7 behaviour.
689 Preventing fallbacks
691 Sometimes fallbacks can be too helpful. Or sometimes you want to impose
693 strict type checking on a return value.
694 Contextual::Returns allows that via the "STRICT" specifier. If you
696 include "STRICT" anywhere in your return statement, the module disables
697 all fallbacks and will therefore through an exception if the return
698 value is used in any way not explicitly specified in the contextual
699 return sequence.
700 For example, to create a subroutine that returns only a string:
702 sub get_name {
704 return STRICT STR { 'Bruce' }
705 }
706 If the return value of the subroutine is used in any other way than as
708 a string, an exception will be thrown.
709 You can still specify handlers for more than a single kind of context
711 when using "STRICT":
712 sub get_name {
714 return STRICT
715 STR { 'Bruce' }
716 BOOL { 0 }
717 }
718 ...but these will still be the only contexts in which the return value
720 can be used:
721 my $n = get_name() ? 1 : 2; # Okay because BOOL handler specified
723 my $n = 'Dr' . get_name(); # Okay because STR handler specified
725 my $n = 1 + get_name(); # Exception thrown because no NUM handler
727 In other words, "STRICT" allows you to impose strict type checking on
729 your contextual return value.
730 Deferring handlers
732 Because the various handlers form a hierarchy, it's possible to
733 implement more specific handlers by falling back on ("deferring to")
734 more general ones. For example, a "PUREBOOL" handler is almost always
735 identical in its basic behaviour to the corresponding "BOOL" handler,
736 except that it adds some side-effect. For example:
737 return
739 PUREBOOL { $_ = $return_val; defined $return_val && $return_val > 0 }
740 BOOL { defined $return_val && $return_val > 0 }
741 SCALAR { $return_val; }
742 So Contextual::Return allows you to have a handler perform some action
744 and then defer to a more general handler to supply the actual return
745 value. To fall back to a more general case in this way, you simply
746 write:
747 next handler;
749 at the end of the handler in question, after which Contextual::Return
751 will find the next-most-specific handler and execute it as well. So the
752 previous example, could be re-written:
753 return
755 PUREBOOL { $_ = $return_val; next handler; }
756 BOOL { defined $return_val && $return_val > 0 }
757 SCALAR { $return_val; }
758 Note that any specific handler can defer to a more general one in this
760 same way. For example, you could provide consistent and maintainable
761 type-checking for a subroutine that returns references by providing
762 "ARRAYREF", "HASHREF", and "SCALARREF" handlers that all defer to a
763 generic "REF" handler, like so:
764 my $retval = _get_ref();
766 return
768 SCALARREF { croak 'Type mismatch' if ref($retval) ne 'SCALAR';
769 next handler;
770 }
771 ARRAYREF { croak 'Type mismatch' if ref($retval) ne 'ARRAY';
772 next handler;
773 }
774 HASHREF { croak 'Type mismatch' if ref($retval) ne 'HASH';
775 next handler;
776 }
777 REF { $retval }
778 If, at a later time, the process of returning a reference became more
780 complex, only the "REF" handler would have to be updated.
781 Nested handlers
783 Another way of factoring out return behaviour is to nest more specific
784 handlers inside more general ones. For instance, in the final example
785 given in "Boolean vs Pure Boolean contexts":
786 sub get_data {
788 my $data;
789 return
790 PUREBOOL { _check_for_but_dont_get_data(); }
791 BOOL { defined( $data ||= _go_and_get_data() ); }
792 REF { $data ||= _go_and_get_data(); }
793 }
794 you could factor out the repeated calls to "_go_and_get_data()" like
796 so:
797 sub get_data {
799 return
800 PUREBOOL { _check_for_but_dont_get_data(); }
801 DEFAULT {
802 my $data = _go_and_get_data();
803 BOOL { defined $data; }
805 REF { $data; }
806 }
807 }
808 Here, the "DEFAULT" handler deals with every return context except pure
810 boolean. Within that "DEFAULT" handler, the data is first retrieved,
811 and then two "sub-handlers" deal with the ordinary boolean and
812 referential contexts.
813 Typically nested handlers are used in precisely this way: to optimize
815 for inexpensive special cases (such as pure boolean or integer or void
816 return contexts) and only do extra work for those other cases that
817 require it.
818 Failure contexts
820 Two of the most common ways to specify that a subroutine has failed are
821 to return a false value, or to throw an exception. The
822 Contextual::Return module provides a mechanism that allows the
823 subroutine writer to support both of these mechanisms at the same time,
824 by using the "FAIL" specifier.
825 A return statement of the form:
827 return FAIL;
829 causes the surrounding subroutine to return "undef" (i.e. false) in
831 boolean contexts, and to throw an exception in any other context. For
832 example:
833 use Contextual::Return;
835 sub get_next_val {
837 my $next_val = <>;
838 return FAIL if !defined $next_val;
839 chomp $next_val;
840 return $next_val;
841 }
842 If the "return FAIL" statement is executed, it will either return false
844 in a boolean context:
845 if (my $val = get_next_val()) { # returns undef if no next val
847 print "[$val]\n";
848 }
849 or else throw an exception if the return value is used in any other
851 context:
852 print get_next_val(); # throws exception if no next val
854 my $next_val = get_next_val();
856 print "[$next_val]\n"; # throws exception if no next val
857 The exception that is thrown is of the form:
859 Call to main::get_next_val() failed at demo.pl line 42
861 but you can change that message by providing a block to the "FAIL",
863 like so:
864 return FAIL { "No more data" } if !defined $next_val;
866 in which case, the final value of the block becomes the exception
868 message:
869 No more data at demo.pl line 42
871 A failure value can be interrogated for its error message, by calling
873 its "error()" method, like so:
874 my $val = get_next_val();
876 if ($val) {
877 print "[$val]\n";
878 }
879 else {
880 print $val->error, "\n";
881 }
882 Configurable failure contexts
884 The default "FAIL" behaviour--false in boolean context, fatal in all
885 others--works well in most situations, but violates the Platinum Rule
886 ("Do unto others as they would have done unto them").
887 So it may be user-friendlier if the user of a module is allowed decide
889 how the module's subroutines should behave on failure. For example, one
890 user might prefer that failing subs always return undef; another might
891 prefer that they always throw an exception; a third might prefer that
892 they always log the problem and return a special Failure object; whilst
893 a fourth user might want to get back 0 in scalar contexts, an empty
894 list in list contexts, and an exception everywhere else.
895 You could create a module that allows the user to specify all these
897 alternatives, like so:
898 package MyModule;
900 use Contextual::Return;
901 use Log::StdLog;
902 sub import {
904 my ($package, @args) = @_;
905 Contextual::Return::FAIL_WITH {
907 ':false' => sub { return undef },
908 ':fatal' => sub { croak @_ },
909 ':filed' => sub {
910 print STDLOG 'Sub ', (caller 1)[3], ' failed';
911 return Failure->new();
912 },
913 ':fussy' => sub {
914 SCALAR { undef }
915 LIST { () }
916 DEFAULT { croak @_ }
917 },
918 }, @args;
919 }
920 This configures Contextual::Return so that, instead of the usual false-
922 or-fatal semantics, every "return FAIL" within MyModule's namespace is
923 implemented by one of the four subroutines specified in the hash that
924 was passed to "FAIL_WITH".
925 Which of those four subs implements the "FAIL" is determined by the
927 arguments passed after the hash (i.e. by the contents of @args).
928 "FAIL_WITH" walks through that list of arguments and compares them
929 against the keys of the hash. If a key matches an argument, the
930 corresponding value is used as the implementation of "FAIL". Note that,
931 if subsequent arguments also match a key, their subroutine overrides
932 the previously installed implementation, so only the final override has
933 any effect. Contextual::Return generates warnings when multiple
934 overrides are specified.
935 All of which mean that, if a user loaded the MyModule module like this:
937 use MyModule qw( :fatal other args here );
939 then every "FAIL" within MyModule would be reconfigured to throw an
941 exception in all circumstances, since the presence of the ':fatal' in
942 the argument list will cause "FAIL_WITH" to select the hash entry whose
943 key is ':fatal'.
944 On the other hand, if they loaded the module:
946 use MyModule qw( :fussy other args here );
948 then each "FAIL" within MyModule would return undef or empty list or
950 throw an exception, depending on context, since that's what the
951 subroutine whose key is ':fussy' does.
952 Many people prefer module interfaces with a "flag => value" format, and
954 "FAIL_WITH" supports this too. For example, if you wanted your module
955 to take a "-fail" flag, whose associated value could be any of
956 "undefined", "exception", "logged", or "context", then you could
957 implement that simply by specifying the flag as the first argument
958 (i.e. before the hash) like so:
959 sub import {
961 my $package = shift;
962 Contextual::Return::FAIL_WITH -fail => {
964 'undefined' => sub { return undef },
965 'exception' => sub { croak @_ },
966 'logged' => sub {
967 print STDLOG 'Sub ', (caller 1)[3], ' failed';
968 return Failure->new();
969 },
970 'context' => sub {
971 SCALAR { undef }
972 LIST { () }
973 DEFAULT { croak @_ }
974 },
975 }, @_;
976 and then load the module:
978 use MyModule qw( other args here ), -fail=>'undefined';
980 or:
982 use MyModule qw( other args here ), -fail=>'exception';
984 In this case, "FAIL_WITH" scans the argument list for a pair of values:
986 its flag string, followed by some other selector value. Then it looks
987 up the selector value in the hash, and installs the corresponding
988 subroutine as its local "FAIL" handler.
989 If this "flagged" interface is used, the user of the module can also
991 specify their own handler directly, by passing a subroutine reference
992 as the selector value instead of a string:
993 use MyModule qw( other args here ), -fail=>sub{ die 'horribly'};
995 If this last example were used, any call to "FAIL" within MyModule
997 would invoke the specified anonymous subroutine (and hence throw a
998 'horribly' exception).
999 Note that, any overriding of a "FAIL" handler is specific to the
1001 namespace and file from which the subroutine that calls "FAIL_WITH" is
1002 itself called. Since "FAIL_WITH" is designed to be called from within a
1003 module's "import()" subroutine, that generally means that the "FAIL"s
1004 within a given module X are only overridden for the current namespace
1005 within the particular file from module X is loaded. This means that two
1006 separate pieces of code (in separate files or separate namespaces) can
1007 each independently override a module's "FAIL" behaviour, without
1008 interfering with each other.
1009 Lvalue contexts
1011 Recent versions of Perl offer (limited) support for lvalue subroutines:
1012 subroutines that return a modifiable variable, rather than a simple
1013 constant value.
1014 Contextual::Return can make it easier to create such subroutines,
1016 within the limitations imposed by Perl itself. The limitations that
1017 Perl places on lvalue subs are:
1018 1. The subroutine must be declared with an ":lvalue" attribute:
1020 sub foo :lvalue {...}
1022 2. The subroutine must not return via an explicit "return". Instead,
1024 the last statement must evaluate to a variable, or must be a call
1025 to another lvalue subroutine call.
1026 my ($foo, $baz);
1028 sub foo :lvalue {
1030 $foo; # last statement evals to a var
1031 }
1032 sub bar :lvalue {
1034 foo(); # last statement is lvalue sub call
1035 }
1036 sub baz :lvalue {
1038 my ($arg) = @_;
1039 $arg > 0 # last statement evals...
1041 ? $baz # ...to a var
1042 : bar(); # ...or to an lvalue sub call
1043 }
1044 Thereafter, any call to the lvalue subroutine produces a result that
1046 can be assigned to:
1047 baz(0) = 42; # same as: $baz = 42
1049 baz(1) = 84; # same as: bar() = 84
1051 # which is the same as: foo() = 84
1052 # which is the same as: $foo = 84
1053 Ultimately, every lvalue subroutine must return a scalar variable,
1055 which is then used as the lvalue of the assignment (or whatever other
1056 lvalue operation is applied to the subroutine call). Unfortunately,
1057 because the subroutine has to return this variable before the
1058 assignment can take place, there is no way that a normal lvalue
1059 subroutine can get access to the value that will eventually be assigned
1060 to its return value.
1061 This is occasionally annoying, so the Contextual::Return module offers
1063 a solution: in addition to all the context blocks described above, it
1064 provides three special contextual return blocks specifically for use in
1065 lvalue subroutines: "LVALUE", "RVALUE", and "NVALUE".
1066 Using these blocks you can specify what happens when an lvalue
1068 subroutine is used in lvalue and non-lvalue (rvalue) context. For
1069 example:
1070 my $verbosity_level = 1;
1072 # Verbosity values must be between 0 and 5...
1074 sub verbosity :lvalue {
1075 LVALUE { $verbosity_level = max(0, min($_, 5)) }
1076 RVALUE { $verbosity_level }
1077 }
1078 The "LVALUE" block is executed whenever "verbosity" is called as an
1080 lvalue:
1081 verbosity() = 7;
1083 The block has access to the value being assigned, which is passed to it
1085 as $_. So, in the above example, the assigned value of 7 would be
1086 aliased to $_ within the "LVALUE" block, would be reduced to 5 by the
1087 "min-of-max" expression, and then assigned to $verbosity_level.
1088 (If you need to access the caller's $_, it's also still available: as
1090 $CALLER::_.)
1091 When the subroutine isn't used as an lvalue:
1093 print verbosity();
1095 the "RVALUE" block is executed instead and its final value returned.
1097 Within an "RVALUE" block you can use any of the other features of
1098 Contextual::Return. For example:
1099 sub verbosity :lvalue {
1101 LVALUE { $verbosity_level = int max(0, min($_, 5)) }
1102 RVALUE {
1103 NUM { $verbosity_level }
1104 STR { $description[$verbosity_level] }
1105 BOOL { $verbosity_level > 2 }
1106 }
1107 }
1108 but the context sequence must be nested inside an "RVALUE" block.
1110 You can also specify what an lvalue subroutine should do when it is
1112 used neither as an lvalue nor as an rvalue (i.e. in void context), by
1113 using an "NVALUE" block:
1114 sub verbosity :lvalue {
1116 my ($level) = @_;
1117 NVALUE { $verbosity_level = int max(0, min($level, 5)) }
1119 LVALUE { $verbosity_level = int max(0, min($_, 5)) }
1120 RVALUE {
1121 NUM { $verbosity_level }
1122 STR { $description[$verbosity_level] }
1123 BOOL { $verbosity_level > 2 }
1124 }
1125 }
1126 In this example, a call to "verbosity()" in void context sets the
1128 verbosity level to whatever argument is passed to the subroutine:
1129 verbosity(1);
1131 Note that you cannot get the same effect by nesting a "VOID" block
1133 within an "RVALUE" block:
1134 LVALUE { $verbosity_level = int max(0, min($_, 5)) }
1136 RVALUE {
1137 NUM { $verbosity_level }
1138 STR { $description[$verbosity_level] }
1139 BOOL { $verbosity_level > 2 }
1140 VOID { $verbosity_level = $level } # Wrong!
1141 }
1142 That's because, in a void context the return value is never evaluated,
1144 so it is never treated as an rvalue, which means the "RVALUE" block
1145 never executes.
1146 Result blocks
1148 Occasionally, it's convenient to calculate a return value before the
1149 end of a contextual return block. For example, you may need to clean up
1150 external resources involved in the calculation after it's complete.
1151 Typically, this requirement produces a slightly awkward code sequence
1152 like this:
1153 return
1155 VALUE {
1156 $db->start_work();
1157 my $result = $db->retrieve_query($query);
1158 $db->commit();
1159 $result;
1160 }
1161 Such code sequences become considerably more awkward when you want the
1163 return value to be context sensitive, in which case you have to write
1164 either:
1165 return
1167 LIST {
1168 $db->start_work();
1169 my @result = $db->retrieve_query($query);
1170 $db->commit();
1171 @result;
1172 }
1173 SCALAR {
1174 $db->start_work();
1175 my $result = $db->retrieve_query($query);
1176 $db->commit();
1177 $result;
1178 }
1179 or, worse:
1181 return
1183 VALUE {
1184 $db->start_work();
1185 my $result = LIST ? [$db->retrieve_query($query)]
1186 : $db->retrieve_query($query);
1187 $db->commit();
1188 LIST ? @{$result} : $result;
1189 }
1190 To avoid these infelicities, Contextual::Return provides a second way
1192 of setting the result of a context block; a way that doesn't require
1193 that the result be the last statement in the block:
1194 return
1196 LIST {
1197 $db->start_work();
1198 RESULT { $db->retrieve_query($query) };
1199 $db->commit();
1200 }
1201 SCALAR {
1202 $db->start_work();
1203 RESULT { $db->retrieve_query($query) };
1204 $db->commit();
1205 }
1206 The presence of a "RESULT" block inside a contextual return block
1208 causes that block to return the value of the final statement of the
1209 "RESULT" block as the handler's return value, rather than returning the
1210 value of the handler's own final statement. In other words, the
1211 presence of a "RESULT" block overrides the normal return value of a
1212 context handler.
1213 Better still, the "RESULT" block always evaluates its final statement
1215 in the same context as the surrounding "return", so you can just write:
1216 return
1218 VALUE {
1219 $db->start_work();
1220 RESULT { $db->retrieve_query($query) };
1221 $db->commit();
1222 }
1223 and the "retrieve_query()" method will be called in the appropriate
1225 context in all cases.
1226 A "RESULT" block can appear anywhere inside any contextual return
1228 block, but may not be used outside a context block. That is, this is an
1229 error:
1230 if ($db->closed) {
1232 RESULT { undef }; # Error: not in a context block
1233 }
1234 return
1235 VALUE {
1236 $db->start_work();
1237 RESULT { $db->retrieve_query($query) };
1238 $db->commit();
1239 }
1240 Post-handler clean-up
1242 If a subroutine uses an external resource, it's often necessary to
1243 close or clean-up that resource after the subroutine ends...regardless
1244 of whether the subroutine exits normally or via an exception.
1245 Typically, this is done by encapsulating the resource in a lexically
1247 scoped object whose destructor does the clean-up. However, if the
1248 clean-up doesn't involve deallocation of an object (as in the
1249 "$db->commit()" example in the previous section), it can be annoying to
1250 have to create a class and allocate a container object, merely to
1251 mediate the clean-up.
1252 To make it easier to manage such resources, Contextual::Return supplies
1254 a special labelled block: the "RECOVER" block. If a "RECOVER" block is
1255 specified as part of a contextual return sequence, that block is
1256 executed after any context handler, even if the context handler exits
1257 via an exception.
1258 So, for example, you could implement a simple commit-or-revert policy
1260 like so:
1261 return
1263 LIST { $db->retrieve_all($query) }
1264 SCALAR { $db->retrieve_next($query) }
1265 RECOVER {
1266 if ($@) {
1267 $db->revert();
1268 }
1269 else {
1270 $db->commit();
1271 }
1272 }
1273 The presence of a "RECOVER" block also intercepts all exceptions thrown
1275 in any other context block in the same contextual return sequence. Any
1276 such exception is passed into the "RECOVER" block in the usual manner:
1277 via the $@ variable. The exception may be rethrown out of the "RECOVER"
1278 block by calling "die":
1279 return
1281 LIST { $db->retrieve_all($query) }
1282 DEFAULT { croak "Invalid call (not in list context)" }
1283 RECOVER {
1284 die $@ if $@; # Propagate any exception
1285 $db->commit(); # Otherwise commit the changes
1286 }
1287 A "RECOVER" block can also access or replace the returned value, by
1289 invoking a "RESULT" block. For example:
1290 return
1292 LIST { attempt_to_generate_list_for(@_) }
1293 SCALAR { attempt_to_generate_count_for(@_) }
1294 RECOVER {
1295 if ($@) { # On any exception...
1296 warn "Replacing return value. Previously: ", RESULT;
1297 RESULT { undef } # ...return undef
1298 }
1299 }
1300 Post-return clean-up
1302 Occasionally it's necessary to defer the clean-up of resources until
1303 after the return value has been used. Once again, this is usually done
1304 by returning an object with a suitable destructor.
1305 Using Contextual::Return you can get the same effect, by providing a
1307 "CLEANUP" block in the contextual return sequence:
1308 return
1310 LIST { $db->retrieve_all($query) }
1311 SCALAR { $db->retrieve_next($query) }
1312 CLEANUP { $db->commit() }
1313 In this example, the "commit" method call is only performed after the
1315 return value has been used by the caller. Note that this is quite
1316 different from using a "RECOVER" block, which is called as the
1317 subroutine returns its value; a "CLEANUP" is called when the returned
1318 value is garbage collected.
1319 A "CLEANUP" block is useful for controlling resources allocated to
1321 support an "ACTIVE" return value. For example:
1322 my %file;
1324 # Return an active value that is always the next line from a file...
1326 sub readline_from {
1327 my ($file_name) = @_;
1328 # Open the file, if not already open...
1330 if (!$file{$file_name}) {
1331 open $file{$file_name}{handle}, '<', $file_name;
1332 }
1333 # Track how many active return values are using this file...
1335 $file{$file_name}{count}++;
1336 return ACTIVE
1338 # Evaluating the return value returns the next line...
1339 VALUE { readline $file{$file_name}{handle} }
1340 # Once the active value is finished with, clean up the filehandle...
1342 CLEANUP {
1343 delete $file{$file_name}
1344 if --$file{$file_name}{count} == 0;
1345 }
1346 }
1347 Debugging contextual return values
1349 Contextual return values are implemented as opaque objects (using the
1350 "inside-out" technique). This means that passing such values to
1351 Data::Dumper produces an uninformative output like:
1352 $VAR1 = bless( do{\(my $o = undef)}, 'Contextual::Return::Value' );
1354 So the module provides two methods that allow contextual return values
1356 to be correctly reported: either directly, or when dumped by
1357 Data::Dumper.
1358 To dump a contextual return value directly, call the module's "DUMP()"
1360 method explicitly and print the result:
1361 print $crv->Contextual::Return::DUMP();
1363 This produces an output something like:
1365 [
1367 { FROM => 'main::foo' },
1368 { NO_HANDLER => [ 'VOID', 'CODEREF', 'HASHREF', 'GLOBREF' ] },
1369 { FALLBACKS => [ 'VALUE' ] },
1370 { LIST => [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ] },
1371 { STR => '<<<Throws exception: Died at demo.pl line 7.>>>' },
1372 { NUM => 42 },
1373 { BOOL => -1 },
1374 { SCALARREF => '<<<self-reference>>>' },
1375 { ARRAYREF => [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ] },
1376 ];
1377 The "FROM" hash entry names the subroutine that produced the return
1379 value. The "NO_HANDLER" hash entry lists those contexts for which no
1380 handler was defined (and which would therefore normally produce "can't
1381 call" exceptions such as: "Can't call main::foo in VOID context"). The
1382 "FALLBACKS" hash entry lists any "generic" contexts such as "VALUE",
1383 "NONVOID", "REF", "DEFAULT", etc. that the contextual return value can
1384 also handle. After these, all the remaining hash entries are actual
1385 contexts in which the return value could successfully be evaluated, and
1386 the value it would produce in each of those contexts.
1387 The Data::Dumper module also has a mechanism by which you can tell it
1389 how to produce a similar listing automatically whenever a contextual
1390 return value is passed to its "Dumper" method. Data::Dumper allows you
1391 to register a "freezer" method, that is called prior to dumping, and
1392 which can be used to adapt an opaque object to make it dumpable.
1393 Contextual::Return provides just such a method
1394 ("Contextual::Return::FREEZE()") for you to register, like so:
1395 use Data::Dumper 'Dumper';
1397 local $Data::Dumper::Freezer = 'Contextual::Return::FREEZE';
1399 print Dumper $foo;
1401 The output is then precisely the same as "Contextual::Return::DUMP()"
1403 would produce.
1404 Note that, with both of the above dumping mechanisms, it is essential
1406 to use the full name of the method. That is:
1407 print $crv->Contextual::Return::DUMP();
1409 rather than:
1411 print $crv->DUMP();
1413 This is because the shorter version is interpreted as calling the
1415 "DUMP()" method on the object returned by the return value's "OBJREF"
1416 context block (see "Scalar reference contexts")
1417 For the same reason, you must write:
1419 local $Data::Dumper::Freezer = 'Contextual::Return::FREEZE';
1421 not:
1423 local $Data::Dumper::Freezer = 'FREEZE';
1425 Namespace controls
1427 By default the module exports a large number of return context markers:
1428 DEFAULT REF LAZY
1430 VOID SCALARREF FIXED
1431 NONVOID ARRAYREF ACTIVE
1432 LIST CODEREF RESULT
1433 SCALAR HASHREF RECOVER
1434 VALUE GLOBREF CLEANUP
1435 STR OBJREF RVALUE
1436 NUM METHOD LVALUE
1437 BOOL NVALUE
1438 PUREBOOL
1439 These are exported as subroutines, and so can conflict with existing
1441 subroutines in your namespace, or with subroutines imported from other
1442 modules.
1443 Contextual::Return allows you to control which contextual return blocks
1445 are exported into any namespace that uses the module. It also allows
1446 you to rename blocks to avoid namespace conflicts with existing
1447 subroutines.
1448 Both these features are controlled by passing arguments to the "use"
1450 statement that loads the module as follows:
1451 • Any string passed as an argument to "use Contextual::Return",
1453 exports only the block name it specifies;
1454 • Any regex passed as an argument to "use Contextual::Return" exports
1456 every block name it matches;
1457 • Any array ref (recursively) exports each of its elements
1459 • Any string that appears immediately after one of the above three
1461 specifiers, and which is not itself a block name, renames the
1462 handlers exported by that preceding specifier by filtering each
1463 handler name through "sprintf()"
1464 That is, you can specify handlers to be exported by exact name (as a
1466 string), by general pattern (as a regex), or collectively (in an
1467 array). And after any of these export specifications, you can append a
1468 template in which any '%s' will be replaced by the original name of the
1469 handler. For example:
1470 # Selectively export specific sets of handlers...
1472 use Contextual::Return qr/[NLR]VALUE/;
1473 use Contextual::Return qr/.*REF/;
1474 # Selective export specific sets and add a suffix to each...
1476 use Contextual::Return qr/[NLR]VALUE/ => '%s_CONTEXT';
1477 # Selective export specific sets and add a prefix to each...
1479 use Contextual::Return qr/.*REF/ => 'CR_%s';
1480 # Export a list of handlers...
1482 use Contextual::Return 'NUM', 'STR', 'BOOL' ;
1483 use Contextual::Return qw< NUM STR BOOL >;
1484 use Contextual::Return ['NUM', 'STR', 'BOOL'];
1485 # Export a list of handlers, renaming them individually...
1487 use Contextual::Return NUM => 'NUMERIC', STR => 'TEXT', BOOL => 'CR_%s';
1488 # Export a list of handlers, renaming them collectively...
1490 use Contextual::Return ['NUM', 'STR', 'BOOL'] => '%s_CONTEXT';
1491 # Mixed exports and renames...
1493 use Contextual::Return (
1494 STR => 'TEXT',
1495 ['NUM', 'BOOL'] => 'CR_%s',
1496 ['LIST', 'SCALAR', 'VOID', qr/^[NLR]VALUE/] => '%s_CONTEXT',
1497 );
1498
1500 Context tests
1501 "LIST()"
1502 Returns true if the current subroutine was called in list context.
1503 A cleaner way of writing: "wantarray()"
1504 "SCALAR()"
1506 Returns true if the current subroutine was called in scalar
1507 context. A cleaner way of writing: "defined wantarray() && !
1508 wantarray()"
1509 "VOID()"
1511 Returns true if the current subroutine was called in void context.
1512 A cleaner way of writing: "!defined wantarray()"
1513 "NONVOID()"
1515 Returns true if the current subroutine was called in list or scalar
1516 context. A cleaner way of writing: "defined wantarray()"
1517 Standard contexts
1519 "LIST {...}"
1520 The block specifies what the context sequence should evaluate to
1521 when called in list context.
1522 "SCALAR {...}"
1524 The block specifies what the context sequence should evaluate to in
1525 scalar contexts, unless some more-specific specifier scalar context
1526 specifier (see below) also occurs in the same context sequence.
1527 "VOID {...}"
1529 The block specifies what the context sequence should do when called
1530 in void context.
1531 Scalar value contexts
1533 "BOOL {...}"
1534 The block specifies what the context sequence should evaluate to
1535 when treated as a boolean value.
1536 "NUM {...}"
1538 The block specifies what the context sequence should evaluate to
1539 when treated as a numeric value.
1540 "STR {...}"
1542 The block specifies what the context sequence should evaluate to
1543 when treated as a string value.
1544 "LAZY {...}"
1546 Another name for "SCALAR {...}". Usefully self-documenting when the
1547 primary purpose of the contextual return is to defer evaluation of
1548 the return value until it's actually required.
1549 Scalar reference contexts
1551 "SCALARREF {...}"
1552 The block specifies what the context sequence should evaluate to
1553 when treated as a reference to a scalar.
1554 "ARRAYREF {...}"
1556 The block specifies what the context sequence should evaluate to
1557 when treated as a reference to an array.
1558 "HASHREF {...}"
1560 The block specifies what the context sequence should evaluate to
1561 when treated as a reference to a hash.
1562 Note that a common error here is to write:
1564 HASHREF { a=>1, b=>2, c=>3 }
1566 The curly braces there are a block, not a hash constructor, so the
1568 block doesn't return a hash reference and the interpreter throws an
1569 exception. What's needed is:
1570 HASHREF { {a=>1, b=>2, c=>3} }
1572 in which the inner braces are a hash constructor.
1574 "CODEREF {...}"
1576 The block specifies what the context sequence should evaluate to
1577 when treated as a reference to a subroutine.
1578 "GLOBREF {...}"
1580 The block specifies what the context sequence should evaluate to
1581 when treated as a reference to a typeglob.
1582 "OBJREF {...}"
1584 The block specifies what the context sequence should evaluate to
1585 when treated as a reference to an object.
1586 "METHOD {...}"
1588 The block can be used to specify particular handlers for specific
1589 method calls when the return value is treated as an object
1590 reference. It should return a list of methodname/methodbody pairs.
1591 Each method name can be specified as a string, a regex, or an array
1592 of strings or regexes. The method bodies must be specified as
1593 subroutine references (usually anonymous subs). The first method
1594 name that matches the actual method call selects the corresponding
1595 handler, which is then called.
1596 Generic contexts
1598 "VALUE {...}"
1599 The block specifies what the context sequence should evaluate to
1600 when treated as a non-referential value (as a boolean, numeric,
1601 string, scalar, or list). Only used if there is no more-specific
1602 value context specifier in the context sequence.
1603 "REF {...}"
1605 The block specifies what the context sequence should evaluate to
1606 when treated as a reference of any kind. Only used if there is no
1607 more-specific referential context specifier in the context
1608 sequence.
1609 "NONVOID {...}"
1611 The block specifies what the context sequence should evaluate to
1612 when used in a non-void context of any kind. Only used if there is
1613 no more-specific context specifier in the context sequence.
1614 "DEFAULT {...}"
1616 The block specifies what the context sequence should evaluate to
1617 when used in a void or non-void context of any kind. Only used if
1618 there is no more-specific context specifier in the context
1619 sequence.
1620 Failure context
1622 "FAIL"
1623 This block is executed unconditionally and is used to indicate
1624 failure. In a Boolean context it return false. In all other
1625 contexts it throws an exception consisting of the final evaluated
1626 value of the block.
1627 That is, using "FAIL":
1629 return FAIL { "Could not defenestrate the widget" }
1631 is exactly equivalent to writing:
1633 return BOOL { 0 } DEFAULT { croak "Could not defenestrate the
1635 widget" }
1636 except that the reporting of errors is a little smarter under
1638 "FAIL".
1639 If "FAIL" is called without specifying a block:
1641 return FAIL;
1643 it is equivalent to:
1645 return FAIL { croak "Call to <subname> failed" }
1647 (where "<subname>" is replaced with the name of the surrounding
1649 subroutine).
1650 Note that, because "FAIL" implicitly covers every possible return
1652 context, it cannot be chained with other context specifiers.
1653 "Contextual::Return::FAIL_WITH"
1655 This subroutine is not exported, but may be called directly to
1656 reconfigure "FAIL" behaviour in the caller's namespace.
1657 The subroutine is called with an optional string (the flag),
1659 followed by a mandatory hash reference (the configurations hash),
1660 followed by a list of zero-or-more strings (the selector list). The
1661 values of the configurations hash must all be subroutine
1662 references.
1663 If the optional flag is specified, "FAIL_WITH" searches the
1665 selector list looking for that string, then uses the following item
1666 in the selector list as its selector value. If that selector value
1667 is a string, "FAIL_WITH" looks up that key in the hash, and
1668 installs the corresponding subroutine as the namespace's "FAIL"
1669 handler (an exception is thrown if the selector string is not a
1670 valid key of the configurations hash). If the selector value is a
1671 subroutine reference, "FAIL_WITH" installs that subroutine as the
1672 "FAIL" handler.
1673 If the optional flag is not specified, "FAIL_WITH" searches the
1675 entire selector list looking for the last element that matches any
1676 key in the configurations hash. It then looks up that key in the
1677 hash, and installs the corresponding subroutine as the namespace's
1678 "FAIL" handler.
1679 See "Configurable failure contexts" for examples of using this
1681 feature.
1682 Lvalue contexts
1684 "LVALUE"
1685 This block is executed when the result of an ":lvalue" subroutine
1686 is assigned to. The assigned value is passed to the block as $_. To
1687 access the caller's $_ value, use $CALLER::_.
1688 "RVALUE"
1690 This block is executed when the result of an ":lvalue" subroutine
1691 is used as an rvalue. The final value that is evaluated in the
1692 block becomes the rvalue.
1693 "NVALUE"
1695 This block is executed when an ":lvalue" subroutine is evaluated in
1696 void context.
1697 Explicit result blocks
1699 "RESULT"
1700 This block may only appear inside a context handler block. It
1701 causes the surrounding handler to return the final value of the
1702 "RESULT"'s block, rather than the final value of the handler's own
1703 block. This override occurs regardless of the location to the
1704 "RESULT" block within the handler.
1705 If called without a trailing "{...}", it simply returns the current
1707 result value in scalar contexts, or the list of result values in
1708 list context.
1709 Recovery blocks
1711 "RECOVER"
1712 If present in a context return sequence, this block grabs control
1713 after any context handler returns or exits via an exception. If an
1714 exception was thrown it is passed to the "RECOVER" block via the $@
1715 variable.
1716 Clean-up blocks
1718 "CLEANUP"
1719 If present in a context return sequence, this block grabs control
1720 when a return value is garbage collected.
1721 Modifiers
1723 "FIXED"
1724 This specifies that the scalar value will only be evaluated once,
1725 the first time it is used, and that the value will then morph into
1726 that evaluated value.
1727 "ACTIVE"
1729 This specifies that the scalar value's originating block will be
1730 re- evaluated every time the return value is used.
1731 Debugging support
1733 "$crv->Contextual::Return::DUMP()"
1734 Return a dumpable representation of the return value in all viable
1735 contexts.
1736 "local $Data::Dumper::Freezer = 'Contextual::Return::FREEZE';"
1738 "local $Data::Dumper::Freezer = \&Contextual::Return::FREEZE;"
1739 Configure Data::Dumper to correctly dump a representation of the
1740 contextual return value.
1741
1743 "Can't use %s as export specifier"
1744 In your "use Contextual::Return" statement you specified something
1745 (such as a hash or coderef) that can't be used to select what the
1746 module exports. Make sure the list of selectors includes only
1747 strings, regexes, or references to arrays of strings or regexes.
1748 "use Contextual::Return qr{%s} didn't export anything"
1750 In your "use Contextual::Return" statement you specified a regex to
1751 select which handlers to support, but the regex didn't select any
1752 handlers. Check that the regex you're using actually does match at
1753 least one of the names of the modules many handlers.
1754 "Can't export %s: no such handler"
1756 In your "use Contextual::Return" statement you specified a string
1757 as the name of a context handler to be exported, but the module
1758 doesn't export a handler of that name. Check the spelling for the
1759 requested export.
1760 "Can't call %s in a %s context"
1762 "Can't use return value of %s in a %s context"
1763 The subroutine you called uses a contextual return, but doesn't
1764 specify what to return in the particular context in which you
1765 called it. You either need to change the context in which you're
1766 calling the subroutine, or else add a context block corresponding
1767 to the offending context (or perhaps a "DEFAULT {...}" block).
1768 "Can't call bare %s {...} in %s context"
1770 You specified a handler (such as "VOID {...}" or "LIST {...}")
1771 outside any subroutine, and in a context that it can't handle. Did
1772 you mean to place the handler outside of a subroutine? If so, then
1773 you need to put it in a context it can actually handle. Otherwise,
1774 perhaps you need to replace the trailing block with parens (that
1775 is: "VOID()" or "LIST()").
1776 "Call to %s at %s didn't return a %s reference""
1778 You called the subroutine in a context that expected to get back a
1779 reference of some kind but the subroutine didn't specify the
1780 corresponding "SCALARREF", "ARRAYREF", "HASHREF", "CODEREF",
1781 "GLOBREF", or generic "REF", "NONVOID", or "DEFAULT" handlers. You
1782 need to specify the appropriate one of these handlers in the
1783 subroutine.
1784 "Can't call method '%s' on %s value returned by %s""
1786 You called the subroutine and then tried to call a method on the
1787 return value, but the subroutine returned a classname or object
1788 that doesn't have that method. This probably means that the
1789 subroutine didn't return the classname or object you expected. Or
1790 perhaps you need to specify an "OBJREF {...}" context block.
1791 "Can't install two %s handlers"
1793 You attempted to specify two context blocks of the same name in the
1794 same return context, which is ambiguous. For example:
1795 sub foo: lvalue {
1797 LVALUE { $foo = $_ }
1798 RVALUE { $foo }
1799 LVALUE { $foo = substr($_,1,10) }
1800 }
1801 or:
1803 sub bar {
1805 return
1806 BOOL { 0 }
1807 NUM { 1 }
1808 STR { "two" }
1809 BOOL { 1 };
1810 }
1811 Did you cut-and-paste wrongly, or mislabel one of the blocks?
1813 "Expected a %s block after the %s block but found instead: %s"
1815 If you specify any of "LVALUE", "RVALUE", or "NVALUE", then you can
1816 only specify "LVALUE", "RVALUE", or "NVALUE" blocks in the same
1817 return context. If you need to specify other contexts (like
1818 "BOOL", or "STR", or "REF", etc.), put them inside an "RVALUE"
1819 block. See "Lvalue contexts" for an example.
1820 "Call to %s failed at %s"
1822 This is the default exception that a "FAIL" throws in a non-scalar
1823 context. Which means that the subroutine you called has signalled
1824 failure by throwing an exception, and you didn't catch that
1825 exception. You should either put the call in an "eval {...}" block
1826 or else call the subroutine in boolean context instead.
1827 "Call to %s failed at %s. Attempted to use failure value at %s"
1829 This is the default exception that a "FAIL" throws when a failure
1830 value is captured in a scalar variable and later used in a non-
1831 boolean context. That means that the subroutine you called must
1832 have failed, and you didn't check the return value for that
1833 failure, so when you tried to use that invalid value it killed your
1834 program. You should either put the original call in an "eval {...}"
1835 or else test the return value in a boolean context and avoid using
1836 it if it's false.
1837 "Usage: FAIL_WITH $flag_opt, \%selector, @args"
1839 The "FAIL_WITH" subroutine expects an optional flag, followed by a
1840 reference to a configuration hash, followed by a list or selector
1841 arguments. You gave it something else. See "Configurable Failure
1842 Contexts".
1843 "Selector values must be sub refs"
1845 You passed a configuration hash to "FAIL_WITH" that specified non-
1846 subroutines as possible "FAIL" handlers. Since non-subroutines
1847 can't possibly be handlers, maybe you forgot the "sub" keyword
1848 somewhere?
1849 "Invalid option: %s =" %s>
1851 The "FAIL_WITH" subroutine was passed a flag/selector pair, but the
1852 selector was not one of those allowed by the configuration hash.
1853 "FAIL handler for package %s redefined"
1855 A warning that the "FAIL" handler for a particular package was
1856 reconfigured more than once. Typically that's because the module
1857 was loaded in two places with difference configurations specified.
1858 You can't reasonably expect two different sets of behaviours from
1859 the one module within the one namespace.
1860
1862 Contextual::Return requires no configuration files or environment
1863 variables.
1864
1866 Requires version.pm and Want.pm.
1867
1869 "LVALUE", "RVALUE", and "NVALUE" do not work correctly under the Perl
1870 debugger. This seems to be because the debugger injects code to capture
1871 the return values from subroutines, which interferes destructively with
1872 the optional final arguments that allow "LVALUE", "RVALUE", and
1873 "NVALUE" to cascade within a single return.
1874
1876 No bugs have been reported.
1877
1879 Damian Conway "<DCONWAY@cpan.org>"
1880
1882 Copyright (c) 2005-2011, Damian Conway "<DCONWAY@cpan.org>". All rights
1883 reserved.
1884 This module is free software; you can redistribute it and/or modify it
1886 under the same terms as Perl itself.
1887
1889 BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
1890 FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT
1891 WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
1892 PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND,
1893 EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
1894 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
1895 ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
1896 YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
1897 NECESSARY SERVICING, REPAIR, OR CORRECTION.
1898 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
1900 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
1901 REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
1902 TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
1903 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
1904 SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
1905 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
1906 FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
1907 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
1908 DAMAGES.
1909perl v5.36.0 2022-07-22 Contextual::Return(3)