There are times when I am confused by the context of Perl. I wrote a tool to reduce this confusion.

Usage

If you plug in the contextual_diag subroutine where you want to know Perl context, it will alert you to the context.

The following code explores the context when evaluating the value of a hash reference:

use Contextual::Diag;

# Here...
my $a = { key => 'value' };

# Do this...
my $a = { key => contextual_diag 'value' };

# Then this happens!
# => wanted LIST context

Inside Contextual::Diag

In Contextual::Diag, the first step is to use wantarray to separate contexts into SCALAR, LIST, and VOID. Then, in the case of SCALAR context, the return value is wrapped in an object, and overload is used to hook into string evaluation, numeric evaluation, and array dereferencing. Only in the case of object reference, overload is not enough to hook, so AUTOLOAD is used. I got this idea from Professor Damian's Contextual::Return.

List of diagnoses

Contextual::Diag has a total of 11 different diagnoses:

1. SCALAR context
   - CASE: Scalar value
      - BOOL e.g. `if ($value)`
      - NUM e.g. `$value + 1`
      - STR e.g. `$value . "hello"`
   - CASE:  Scalar reference
      - SCALARREF e.g. `$$value`
      - ARRAYREF e.g. `$value->[0]`
      - HASHREF e.g. `$value->{key}`
      - CODEREF e.g. `$value->()`
      - GLOBREF e.g. `*{$value}->{CODE}`
      - OBJREF e.g. `$value->hello()`
2. LIST context
3. VOID context

Conclusion

I wrote Contextual::Diag to make it easier to understand Perl context.

You can use it if you like!