Section 9.9. Multi-Contextual Return Values

9.9. Multi-Contextual Return Values

When there is no "obvious" scalar context return value, consider Contextual::Return instead.

Sometimes no single scalar return value is appropriate for a list-returning subroutine. Your play-testers simply can't agree: different developers consistently expect different behaviours in different scalar contexts.

For example, suppose you're implementing a get_server_status( ) subroutine that normally returns its information as a heterogeneous list:

      
     # In list context, return all the available information...
     my ($name, $uptime, $load, $users) = get_server_status($server_ID);

You may find that, in scalar contexts, some programmers expected it to return its numeric load value:

      
     # Total load is sum of individual server loads...
     $total_load += get_server_status($server_ID);

Others assumed it would return a boolean value indicating whether the server is up:

      
     # Skip inactive servers...
     next SERVER if ! get_server_status($server_ID);

Still others anticipated a string summarizing the current status:

      
     # Compile report on all servers...
     $servers_summary .= get_server_status($server_ID) . "\n";

While a fourth group hoped for a hash-reference, to give them convenient named access to the particular server information they wanted:

      
     # Total users is sum of users on each server...
     $total_users += get_server_status($server_ID)->{users};

In such cases, implementing any one of these four expectations is going to leave three-quarters of your developers unhappy.

At some point, every subroutine will be called in scalar context, and will have to return something. If that something isn't obvious to the majority of people, then inexperienced developerswho might not even realize their call is in scalar contextwill suffer. And experienced developers will suffer too: ham-strung by the limitations of scalar context return and forced to work with your arbitrary choice of return value.

Perl's subroutines are context-sensitive for a reason: so that they can Do The Right Thing when used in different ways. But often in scalar contexts there is no one Right Thing. So developers give up and just pick the One Thing That Seems Rightest...to them. All too often, a decision like that leads to confusion, frustration, and buggy code.

Surprisingly, the underlying problem here isn't that Perl is context-sensitive. The problem is that Perl isn't context-sensitive enough.

Perl has one kind of list context and one kind of void context, so simple list-context and void-context returns are the perfect tools for those. On the other hand, Perl has at least a dozen distinct scalar subcontexts: boolean, integer, floating-point, string, and the numerous reference types. So, unless one of those return types is the clear and obvious candidate, simple scalar context return is totally inadequate: a sledgehammer when you really need tweezers.

Fortunately, there's a simple way to allow subroutines like get_server_status( ) to cater for two or more different scalar-context expectations simultaneously. The Contextual::Return CPAN module provides a mechanism by which you can specify that a subroutine returns different scalar values in boolean, numeric, string, hash-ref, array-ref, and code-ref contexts. For example, to allow get_server_status( ) to simultaneously support all five return behaviours shown at the start of this guideline, you could simply write:

      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    { @server_data{ qw( name uptime load users ) };                   }             BOOL    { $server_data{uptime} > 0;                                       }             NUM     { $server_data{load};                                             }             STR     { "$server_data{name}: $server_data{uptime}, $server_data{load}"; }             HASHREF { \%server_data;                                                  }         );     }

Now, in a list context, get_server_status( ) uses a hash slice to extract the information in the expected order. In a boolean context, it returns true if the uptime is non-zero. In a numeric context, it returns the server load. In a string context, a string summarizing the server's status is returned. And when the return value is expected to be a hash reference, get_server_status( ) simply returns a reference to the entire %server_data hash.

Note that each of those alternative return values is lazily evaluated. That means, on any given call to get_server_status( ), only one of the five contextual return blocks is actually executed.

Even in cases where you don't need to distinguish between so many alternatives, the Contextual::Return module can still improve the maintainability of your code, compared to using the built-in wantarray. The module allows you to say explicitly what you want to happen in different return context, and to label each of those outcomes with an obvious keyword. For example, suppose you had a subroutine such as:

     sub defined_samples_in {         if (wantarray) {             return grep {defined $_} @_;         }         return first {defined $_} @_;     }

Without changing its behaviour at all, you could make the code considerably more self-documenting, and emphasize the inherent symmetry of the list and scalar cases, by rewriting it with a single contextual return:

      use Contextual::Return;     sub defined_samples_in {         return (             LIST   {  grep {defined $_} @_ }             SCALAR { first {defined $_} @_ }         );     }

Besides producing more explicit and less cluttered code, this approach is more maintainable, too. When you need to extend the return behaviour of the subroutine, to more precisely match the expectations of those who use it, you can just add extra labeled return contexts, anywhere in the return list:

      use Contextual::Return;     sub defined_samples_in {         return (             LIST     {        grep {defined $_} @_   }  
# All defined vals
             SCALAR   {       first {defined $_} @_   }  
# One defined val
             NUM      { scalar grep {defined $_} @_   }  
# How many vals defined?
             ARRAYREF {      [ grep {defined $_} @_ ] }  
# Return vals in an array
         );     }

Regardless of the order in which the alternatives appear, Contextual::Return will automatically select the most appropriate behaviour in each call context.