Contextual::Return 0.1.0

Contextual::Return is a Perl module to create context-senstive return values.

SYNOPSIS

use Contextual::Return;
use Carp;

sub foo {
return
SCALAR { thirty-twelve }
BOOL { 1 }
NUM { 7*6 }
STR { forty-two }

LIST { 1,2,3 }

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

GLOBREF { *STDOUT }
CODEREF { croak "Dont 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->();
}

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