Consider a program that has a lot of constants—say, a graphical program [Hack #16] with screen size, color depth, difficulty level, and so on. If you’re debugging such a problem, it can be difficult to track variables when you’re passing around magic variables. It gets worse when you have to deal with flags that you AND and OR together. How do you know when a number is really an important number or just the coincidental result of a calculation that merely looks like an important number?

Instead of having to look up the symbolic names (easy for programmers to remember) for values (easy for a computer to handle) every time you debug something, consider using dualvars:

use Scalar::Util 'dualvar';

my $width   = dualvar( 800, 'Screen width'       );
my $height  = dualvar( 600, 'Screen height'      );
my $colors  = dualvar(  16, 'Screen color depth' );

# some code
sub debug_variable
{
    my $constant = shift;
    printf STDERR "%s is %d\n", $constant, $constant;
}

Now whenever you encounter a variable you want to inspect for debugging, pass it to debug_variable( ), which will helpfully print something like:

Screen width is 800
Screen height is 600
Screen color depth is 16

Every Perl scalar has several slots for several different types of data. The dualvar( ) function from the ever-useful Scalar::Util package takes two: a numeric and a string value. It stores the numeric value in the numeric (NV) slot of the scalar and sets a flag that it’s okay to look in that slot in numeric contexts. It does the same for the string value (PV slot, string contexts).

Whenever you access a scalar in a certain type of context, Perl first checks the appropriate flag for that context. If it’s okay to use the value in the appropriate slot, Perl does so. Otherwise, it converts an existing value from another slot to the appropriate type, puts the calculated value in the appropriate slot, and sets the flag it checked.

The dualvar nature affects the value stored in the variable, not the variable itself, so it’s safe to pass back and forth in and out of functions.

You can also use this trick with the constant pragma if you prefer that for your constants:

use constant AUTHOR => dualvar( 006, 'chromatic the superspy author' );

If that’s not paranoid enough for you, the Readonly module also works with this technique:

use Readonly;
Readonly::Scalar my $colors => dualvar(  16, 'Screen color depth' );

Use a hash, as the FAQ suggests, stuffed full of references to the variables you need to update. You can build this very concisely, with only a little bit of duplication, with a sadly underused piece of Perl syntax—the list reference constructor. When given a list of scalars, the reference constructor (\) returns a list of references to those scalars. That’s perfect for the list of values to a hash slice!

sub create_report
{
    my %totals;
    @totals{ qw( books movies candy certificates total )} =
    \( $books_total, $movies_total, $candy_total,
       $certificates_total, $total
     );

    while (my ($category, $value)  = get_row( ))
    {
        ${ $totals{ $category } } += $value;
        ${ $totals{total}       } += $value;
    }
}

That’s better. When your data feed changes next week and gives you a list of product names, not categories, change the list slice assignment to %totals to store multiple references to the same category total scalars under different keys. You still have an ugly mapping of strings to lexical variables, but until you can refactor out the yuck of the rest of the application, you’ve at least localized the problem in only one spot you need to touch.

Besides, as far as the author knows, the original application is likely still running.

Validation is still a problem here; how do you prevent a typo in the data from an external source from causing a run-time error? With the hash, you can check for a valid key with exists (though storing total in the hash as well is a potential bug waiting to happen). This may be an appropriate place to use a locked hash [Hack #87].

If you find that you have to tack a newline onto the end of most (or even just many) of your print statements, factor out that tiny annoyance:

sub say { print @_, "\n" }

# and ever after...

say "Showing first ", @results / 2, " of ", scalar @results;

for (@results[ 0 .. @results / 2 - 1 ])
{
    if (m/($IDENT): \s* (.*?) \s* $/x)
    {
        say "$1 -> ", normalize($2);
    }
    else
    {
        say "Strange result: ", substr( $2, 0, 10 );
    }
}

Likewise, if you’re forever opening a file and reading in the contents:

open my $fh, '<', $filename or die "Couldn't open 'filename'";
my $contents = do { local $/; <$fh> };

you could automate that:

sub slurp
{
    my ($file) = @_;
    open my $fh, '<', $file or croak "Couldn't open '$file'";
    local $/;
    return <$fh>;
}

# and thereafter:

my $contents = slurp $filename;

The key here is to find the repetitive, low-level, mechanical things you do and hoist them out of your code into shorter, cleaner, higher-level abbreviations. Factoring out these common “micropatterns” makes the resulting code more readable and less prone to typos and other mishaps. It also frees you to concentrate on solving your actual problem.

There are already good implementations on CPAN for many of these micropatterns. For example, see Perl6::Say, File::Slurp, List::UtilTerm::ReadKey, or Sort::Maker. Subroutines like say( ) and slurp( ) are also prime candidates for adding to your standard toolkit [Hack #34].

Suppose you’re working on code that needs to sling around several hashes and your coworkers keep mistyping key names.^[3] Though things all look correct, it’s difficult to catch and debug and it causes you plenty of problems.

Rather than searching the entire program’s source code (and vetting the contents of all possible variables and configuration files and every place you could get a new hash key), lock the hash’s keys:

use Test::More tests => 2;
use Hash::Util 'lock_keys';

my %locked   = ( foo => 1, bar => 2 );
my %unlocked = ( foo => 1, bar => 2 );
lock_keys( %locked );

eval {   $locked{fool} = 1 };
eval { $unlocked{fool} = 1 };

is( keys %locked,  2, 'hash with locked keys should disallow unknown key' );
is( keys %unlocked, 3, '... but unlocked hash should not' );

Anyone can add any keys and values to %unlocked, but trying to read from or write to a key not in the hash (in this case, fool) when you call lock_keys( ) will fail with the error:

Attempt to access disallowed key 'fool' in a restricted hash...

Run your test suite and check the line number of the error message to find the culprit. Fix. Repeat.

Note that you can still call exists without triggering the exception. Also, if your co-workers are particularly evil or at least actively malicious, they can call unlock_keys( ) before doing bad things. If this is the case, you have bigger problems than misspellings—such as not having a comprehensive test suite.

Imagine that you have to write a program that processes and analyzes records from a database. The processing isn’t idempotent, so you need to keep track of the most recent record processed. You can assume that the record ids increase monotonically. However, admins can interrupt the program as necessary, as the task has a low priority. You want to make sure that, no matter what happens, you always record the id of the most-recently processed item.

Use Scope::Guard and a closure to schedule an end-of-scope operation:

use Scope::Guard;

sub process_records
{
    my $records  = fetch_records( );
    my $last_rec = 0;
    my $cleanup  = sub { cleanup( $last_rec ) if $last_rec };
    my $guard    = Scope::Guard->new( $cleanup );

    for my $record ( @$records )
    {
        process_record( $record );
        $last_rec = $record;
    }
}

sub cleanup
{
    my $record = shift;

    # mark record as last record successfully completed
}

process_records( ) declares a lexical variable, $last_rec, to hold the last record successfully processed. It then builds a closure in $cleanup which calls the cleanup( ) subroutine, passing $last_rec. Then it creates a new Scope::Guard object with the closure.

In the normal flow of operation, the subroutine will process all of the records. Then it exits the subroutine. At this point, Perl garbage collects $guard and calls the closure, which itself calls the cleanup( ) subroutine and marks the last successfully processed record.

It’s possible that process_record( ) may throw an exception if it cannot process a record appropriately. It’s also possible that an admin or resource limit will kill the process, or something else could stop the program before it finishes processing all of the records. Even so, $guard still goes out of scope and calls cleanup( ).

Scope::Guard isn’t just good for cleanup. You can perform all sorts of interesting operations when you leave a scope. For example, what if you need to chdir to various directories to run external processes that expect very specific current working directories? You could write a chdir replacement that takes a directory and return a Scope::Guard object that returns to the current working directory:

use Cwd;

sub change_directory
{
    my $newdir = shift;
    my $curdir = cwd( );
    chdir( $newdir );
    return Scope::Guard->new( sub { chdir $curdir } );
}

Of course, you could also use David Golden’s File::pushd module from the CPAN.

There are far stranger ways to invoke a function. All of these ways are usually too weird for normal use, but useful only on occasion. That’s another way^[4] to say that they are the perfect hack.

sub foo
{
    ...a bunch of code....
}

sub foo;   # predefine 'foo'

sub foo ( )
{
    ...a bunch of code...
}

sub foo ( );

my $x = time;
my $x = time( );

sub time_days ( )
{
    return time( ) / (24 * 60 * 60);
}

my $xd = time_days;

use Data::Format 'time2str';

  sub ymd_now ()
  {
      time2str( '%Y-%m-%d', time )
  }

  print "It is now ", ymd_now, "!!\n";

{
    package TimeVar_YMDhms;

    use Tie::Scalar ( );
    use base 'Tie::StdScalar';
    use Date::Format 'time2str';

    sub FETCH { time2str('%Y-%m-%dT%H:%M:%S', time) }
}

tie my $TIME, TimeVar_YMDhms;

print "It is now $TIME\n";
sleep 3;
print "It is now $TIME\n";

It is now 2006-02-03T16:04:17
It is now 2006-02-03T16:04:20

{
    package Tie::ScalarFnParams;
    sub TIESCALAR
    {
        my($class, $fn, @params) = @_;
        return bless sub { $fn->(@params) }, $class;
    }

    sub FETCH { return shift( )->( ) }
    sub STORE { return } # called for $var = somevalue;
}

use Date::Format 'time2str';

tie my $TIME, Tie::ScalarFnParams,
 # And now any function and optional parameter(s):
   sub { time2str(shift, time) }, '%Y-%m-%dT%H:%M:%S';

print "It is now $TIME\n";
sleep 3;
print "It is now $TIME\n";

use Lingua::EN::Numbers::Ordinate 'ordinate';
print ordinate(4), "!\n";

{
    package Tie::Ordinalize;

    use Lingua::EN::Numbers::Ordinate 'ordinate';
    use base 'Tie::Array';

    sub TIEARRAY  { return bless { }, shift } # dummy obj
    sub FETCH     { return ordinate( $_[1] ) }
    sub FETCHSIZE { return 0 }
}

tie my @TH, Tie::Ordinalize;
print $TH[4], "!\n";

{
    package Tie::TimeFormatty;
    use Tie::Hash ( );
    use base 'Tie::StdHash';
    use Date::Format 'time2str';
    sub FETCH { time2str($_[1], time) }
}

tie my %NowAs, Tie::TimeFormatty;

print "It is now $NowAs{'%Y-%m-%dT%H:%M:%S'}\n";
sleep 3;
print "It is now $NowAs{'%c'}\n";

It is now 2006-02-03T18:28:06
It is now 02/03/06 18:28:09

use Date::Format 'time2str';
use Interpolation NowAs => sub { time2str($_[0],time) };

print "It is now $NowAs{'%Y-%m-%dT%H:%M:%S'}\n";
sleep 3;
print "It is now $NowAs{'%c'}\n";

open $fh, '>:somelayer:someotherlayer:yetmore', 'file.dat'

open( $out, '>:utf8', 'resume.utf' ) or die "Cannot read resume: $!\n";
print {$out} "\x{2605} My R\xE9sum\xE9 \x{2605}\n";
close( $out );  # ^^-- a star character

package Function_IO_Layer;

# A dumb base class for simple PerlIO::via::* layers.
# See PerlIO::via::dynamic for a smarter version of this.

sub PUSHED { bless { }, $_[0] } # our dumb ctor

# when reading
sub FILL
{
    my($this, $fh) = @_;
    defined(my $line = readline($fh)) or return undef;
    return $this->change($line);
}

sub WRITE
{
    my($this,$buf,$fh) = @_;
    print {$fh} $this->change($buf)  or return -1;
    return length($buf);
}

sub change { my($this,$str) = @_;  $str; } #override!

# Puts everything in allcaps.
package PerlIO::via::Scream;

use base 'Function_IO_Layer';

sub change
{
    my($this, $str) = @_;
    return uc($str);
}

# Changes "I" to "me".
package PerlIO::via::Cookiemonster;

use base 'Function_IO_Layer';

sub change
{
    my($this, $str) = @_;
    $str =~ s<\bI\b><me>g;
    return $str;
}

open my $fh, '>:via(Scream):via(Cookiemonster)',
   'author_bio.txt' or die $!;

print {$fh} "I eat cookies without cease or restraint.\n",
   "I like cookies.\n";

close($fh);

ME EAT COOKIES WITHOUT CEASE OR RESTRAINT.
ME LIKE COOKIES.

open my $ls, '-|:via(Scream)', 'ls -C /usr' or die $!;
print <$ls>;

BIN  GAMES    KERBEROS  LIBEXEC  SBIN   SRC  X11R6
ETC  INCLUDE  LIB       LOCAL    SHARE  TMP

bin  games    kerberos  libexec  sbin   src  X11R6
etc  include  lib       local    share  tmp

The angle brackets in Perl have two distinct purposes: as a shorthand for calling readline, and as a shorthand for calling glob:

my $input = <$fh>;      # shorthand for: readline($fh)

my @files = <*.pl>;     # shorthand for: glob("*.pl")

Assuming you’re not interested in that second rather specialized usage (and you can always use the standard File::Glob module, if you are), you can hijack non-readline angles for something much tastier: list comprehensions.

@prime_countdown = grep { is_prime($_) } map { 100-$_ } 0..99;

@prime_countdown = <100..1 : is_prime(X)>;

By replacing the CORE::GLOBAL::glob( ) subroutine, you replace both the builtin glob( ) function and the angle-bracketed operator version. By rewriting CORE::GLOBAL::glob( ), you can retarget the <...> syntax to do whatever you like, for example, to build sophisticated lists.

Do so with:

package Glob::Lists;

use Carp;

# Regexes to parse the extended list specifications...
my $NUM    = qr{\s* [+-]? \d+ (?:\.\d*)? \s* }xms;
my $TO     = qr{\s* \.\. \s*}xms;
my $FILTER = qr{ (?: : (.*) )? }xms;
my $ABtoZ  = qr{\A ($NUM) (,) ($NUM) ,? $TO ($NUM) $FILTER \Z}xms;
my $AZxN   = qr{\A ($NUM) $TO ($NUM) (?:x ($NUM))? $FILTER \Z}xms;

# Install a new glob( ) function...
no warnings 'redefine';
*CORE::GLOBAL::glob = sub
{
    my ($listspec) = @_;

    # Does the spec match any of the acceptable forms?
    croak "Bad list specification: <$listspec>"
        if $listspec !~ $ABtoZ && $listspec !~ $AZxN;

    # Extract the range of values and any filter...
    my ($from, $to, $incr, $filter) =  $2 eq ',' ? ($1, $4, $3-$1, $5)
                                    :              ($1, $2, $3,    $4);

    # Work out the implicit increment, if no explicit one...
    $incr = $from > $to ? -1 : 1 unless defined $incr;

    # Check for nonsensical increments (zero or the wrong sign)...
    my $delta = $to - $from;
    croak sprintf "Sequence <%s, %s, %s...> will never reach %s",
        $from, $from+$incr, $from+2*$incr, $to
            if $incr = = 0 || $delta * $incr < 0;

    # Generate list of values (and return it, if not filter)...
    my @vals = map { $from + $incr * $_ } 0..($delta/$incr);
    return @vals unless defined $filter;

    # Apply the filter before returning the values...
    $filter =~ s/\b[A-Z]\b/\$_/g;
    return eval "grep {package ".caller."; $filter } \@vals";
};

The $ABtoZ and $AZxN regexes match two kinds of sequence specifiers:

<from, then,..to>

and:

<from..to x increment>

and both also allow you to specify a filtering expression after a colon:

<from, then,..to : filter>
<from..to x incr : filter>

The regexes capture and extract the relevant start and end values, the increment amount, and the filter. The subroutine then computes the increment in the cases where it is implicit, and checks to see that the sequence makes sense (that is, it isn’t something like <1..10 x -1> or <1,2,..-10>).

The code then genereates the sequence using a map, and immediately returns it if there is no filter. If there is a filter, the code evals it into a grep and returns the filtered list instead.

Then you can write:

use Glob::Lists;

for ( <1..100 x 7> ) {...}           # 1, 8, 15, 22,...85, 92, 99

my @even_countdown  = <10,8..0>;     # 10, 8, 6, 4, 2, 0

my @fract_countdown = <10,9.5,..0>;  # 10, 9.5, 9,...1, 0.5, 0

my @some_primes = <1..100 x 3 : /7/ && is_prime(N)>;
                                     # 7, 37, 67, 73, 79, 97

One of the neater hacks based on this idea is the CPAN module Tie::FTP, which diverts file operations to functions that actually perform those operations on files on remote FTP servers. Another notable module is Tie::STDERR, which provides handy options for diverting STDERR output to email to root, an errorlog file, or an arbitrary function. For Zen-like transcendence of the very concept of “hack” or “purpose”, the CPAN module IO::Null can tie to functions that do, and return, nothing at all!

One of the most failure-prone points of programming is IO programming, whether working with files or other computers across a network. File paths may be wrong, file permissions may change, disks can mysteriously fill up, and transitory networking problems may make remote computers temporarily invisible. If you work much with files, using Fatal can reduce the amount of code you need to write.

The Fatal module takes a list of function names to override to raise exceptions on failures. open and close are good candidates. Pass their names to the use line to avoid writing the or die( ) idiom:

use Fatal qw( open close );

open( my $fh, '>', '/invalid_directory/invalid_file' );
print {$fh} "Hello\n";
close $fh;

If you run this (and don’t have a directory named /invalid_directory), you’ll receive an error message:

Can't open(GLOB(0x10159d74), >, /nodirectory/nofile.txt): No such file or
  directory at (eval 1) line 3
  main::__ANON__('GLOB(0x10159d74)', '>', '/nodirectory/nofile.txt') called
      at fatal_io.pl line 8

If it’s appropriate for your program to exit with an error if this happens, this is all you need to do. To handle the error with more grace, wrap the code in an eval block and do what you need to do:

use Fatal qw( open close );
eval {
    open( my $fh, '>', '/invalid_directory/invalid_file' );
    print {$fh} "Hello\n";
    close $fh;
};

die "File error: $!" if $@;

Fatal can also make your own code strict. Use it within your own modules just as you would normally:

package MyCode;

sub succeed { 1 }
sub fail    { 0 }

use Fatal qw( :void succeed fail );

succeed( );
fail( );

1;

Because fail( ) returns false, Fatal throws an exception. This code has one trick, in that the subroutine declarations come before the Fatal call. If you use the module before Perl parses the subroutine declarations, Fatal will not be able to find them and will throw an error.

This can be useful for your own code, but it’s even more useful when you export these functions to other code. The order of the use lines doesn’t matter here, though:^[6]

package MyCode;
use base 'Exporter';
               our @EXPORT = qw( succeed fail );

sub succeed { 1 }
sub fail    { 0 }

use Fatal qw( :void succeed fail );

1;

This technique even works with classes and objects; you don’t have to export your methods for Fatal to work.

The module also allows you to be more specific about what to return in different kinds of scalar context.

For example, you might want a stopwatch( ) subroutine that returns the elapsed time in seconds in numeric contexts, but an HH:MM:SS representation in string contexts. You might also want it to return a true or false value depending on whether the stopwatch is currently running. You can do all of that with:

use Time::HiRes 'time';
use Contextual::Return;

my $elapsed       = 0;
my $started_at    = 0;
my $is_running    = 0;

# Convert elapsed seconds to HH::MM::SS string...
sub _HMS
{
    my ($elapsed) = @_;
    my $hours     = int($elapsed / 3600);
    my $mins      = int($elapsed / 60 % 60);
    my $secs      = int($elapsed) % 60;
    return sprintf "%02d:%02d:%02d", $hours, $mins, $secs;
}

sub stopwatch
{
    my ($run)     = @_;

    # Update elapsed time...
    my $now       =  time( );
    $elapsed     +=  $now - $started_at if $is_running;
    $started_at   =  $now;

    # Defined arg turns stopwatch on/off, undef arg resets it...
    $is_running   =  $run if @_;
    $elapsed      =  0 if @_ && !defined $run;

    # Handle different scalar contexts...
    return
         NUM { $elapsed         }
         STR { _HMS( $elapsed ) }
        BOOL { $is_running      }
}

With that arrangement, you can write code like:

print "The clock's already ticking\n"
    if stopwatch( );                              # treat as a boolean
stopwatch(1);                                    # start
do_stuff( );
stopwatch(0);                                    # stop
print "Did stuff in ", stopwatch( ), "\n";        # report as string

stopwatch(undef);                                # reset
stopwatch(1);                                    # start
do_more_stuff( );
print "Did more stuff in ", stopwatch(0), "\n";  # stop and report

print "Sorry for the delay\n"
    if stopwatch( ) > 5;                          # treat as number

The stopwatch example works well, but it still doesn’t explore the full range of possibilities for a scalar return value. For example, the single piece of numeric information you want back might not be the elapsed time, but rather when the stopwatch started. You might also want to return a boolean indicating whether the stopwatch is currently running without always having to cast your call into boolean context:

$stopwatch_running = !!stopwatch( );      # !! --> boolean context

It would be handy if, in addition to all the other return options, stopwatch( ) would also return a hash reference, so you could write:

$stopwatch_running = stopwatch->{running};

print "Stopwatch started at ", stopwatch->{started}, "\n";

Returning a hash reference allows you to send back all the information you have available, from which the caller can then pick out (by name) the interesting bits. Using names to select what you want back also helps the code document what it’s doing.

Contextual::Return makes it easy to add this kind of behavior to stopwatch( ). Just add a specific return value for the HASHREF context:

# Handle different scalar contexts...
return
        NUM { $elapsed         }
        STR { _HMS( $elapsed ) }
       BOOL { $is_running      }
    HASHREF { { elapsed 
               => $elapsed,
                               started   => $now - $elapsed,
                               running   => $is_running,
                             }
                           }
            

Contextual::Return can handle other types of reference returns as well. One of the most useful is SCALARREF {...}. This block specifies what to return when the calling code uses the return value as a reference to a scalar. That is, what to return if you write:

${ stopwatch( ) }    # Call stopwatch( ) and treat result as scalar ref

The reason this particular construct is so interesting is that you can interpolate it directly into a double quoted string. For example, add a SCALARREF return block to stopwatch( ):

# Handle different scalar contexts...
return
        NUM { $elapsed         }
        STR { _HMS($elapsed)   }
  SCALARREF  { \ _HMS($elapsed)   }
       BOOL { $is_running      }
    HASHREF { {   elapsed => $elapsed,
                  started => $now - $elapsed,
                  running => $is_running,
              }
            }

Then, whenever it’s called in a scalar-ref context, the subroutine returns a reference to the HH:MM:SS elapsed string, which the scalar ref context then automatically dereferences. Instead of having to write:

print "Did stuff in ", stopwatch( ), "\n";

you can interpolate the call right into the string itself:

print "Did stuff in ${stopwatch( )}\n";

This turns out to be so amazingly useful that it’s Contextual::Return’s default behaviour. That is, any subroutine that specifies one or more of STR {...}, NUM {...}, or BOOL {...} automatically gets a SCALARREF {...} as well: one that returns a reference to the appropriate string, number, or boolean.

For example, you can create a subroutine that returns a value that automatically tracks the elapsed time between events:

use Contextual::Return;
use Time::HiRes qw( sleep time );      # Allow subsecond timing

# Subroutine returns an active timer value...
sub timer
{
    my $start = time;                  # Set initial start time

    return VALUE                       # Return an active value that...
    {                     
        my $elapsed = time - $start;   #    1. computes elapsed time
        $start      = time;            #    2. resets start time
        return $elapsed;               #    3. returns elapsed time
    }
}

# Create an active value...
my $process_timer = timer( );

# Use active value...
while (1)
{
    do_some_long_process( );
    print "Process took $process_timer seconds\n";
}

Because the timer( ) subroutine returns a contextual value that is computed within the VALUE block itself, that returned value becomes active. Each time the value of $process_timer is reevaluated (in the print statement), the value’s VALUE block executes, recomputing and resetting the value stored in $process_timer.

Of course, the real advantage here is that you can have the subroutine create two or more timers for you:

my $task_timer    = timer( );
my $subtask_timer = timer( );

for my $task (@tasks)
{
    print "Performing $task...\n";
    for my $subtask ($task->get_subtasks( ))
    {
        $subtask->perform( );
        print "\t$subtask took $subtask_timer seconds\n";
    }
    print "Finished $task in $task_timer seconds\n\n";
}

to produce something like:

$ perl do_tasks.pl

Performing set-up...
    Finding files took 0.775737047195435 seconds
    Reading files took 0.985733032226562 seconds
    Verifying data took 0.137604951858521 seconds
Finished set-up in 1.98483791351318 seconds

Performing initialization...
    Creating data structures took 0.627048969268799 seconds
    Cross-correlating took 2.756386041641235 seconds
Finished initialization in 3.45225400924683 seconds

etc.

Active values can use all the other features of the Contextual::Return module. In particular, they can still be context-sensitive. For example, you could create a safer version of the built-in open function, where “safer” means that this version will return a filehandle that explodes catastrophically if you ever try to use the handle without first verifying that it was opened correctly.

Implement it like this:

use Contextual::Return;

sub safe_open
{
    my ($mode, $filename) = @_;
    my $user_has_tested   = 0;

    # Open a filehandle and remember where it was opened...
    open my($filehandle), $mode, $filename;
    my $where = sprintf("'%s' line %s", (caller)[1,2]);

    # Return an active value that's only usable after it's been tested...
    return (
        BOOL
        {
            $user_has_tested = 1;
            return defined $filehandle;
        }
        DEFAULT
        {
            croak "Used untested filehandle (opened at $where)"
                unless $user_has_tested;
            return $filehandle;
        }
    )
}

The safe_open subroutine expects two arguments: the opening mode and the name of the file to open:

my $fh = safe_open '<', $some_file;

The returned value acts like a filehandle in all contexts, but only after you have tested the value in a boolean context. Accessing the returned value in a boolean context invokes the value’s BOOL block, which actively sets the $user_has_tested flag true. If you try to use the filehandle before you’ve tested it:

my $fh    = safe_open '<', $some_file;

my $input = <$fh>;          # Use of untested return value
                            # invokes DEFAULT block

the BOOL block will not have run, so the internal flag will still be false, and the value’s DEFAULT block will throw an exception:

$ perl demo.pl

Used untested filehandle (opened at 'demo.pl' line 12) at demo.pl line 14

If however, the filehandle has been tested in any boolean context:

my $fh = safe_open '<', $some_file
    or croak "Couldn't open $some_file";   # the 'or' evaluates $fh in a
                                           # boolean context so it invokes
                                           # returned value's BOOL block

my $input = <$fh>;          # Invokes returned value's DEFAULT block

then the value’s BOOL block will have set the $user_has_tested flag. Once the flag is set, the DEFAULT block will thereafter return the filehandle without detonating.

Of course, this is incompatible with the use of Fatal as shown in “Write Less Error-Checking Code” [Hack #91].

Although Perl may not be perfect, it is perfectable. For example, recent versions of Perl provide a way to grab your program’s source code before it even reaches the compiler, change it in some useful manner, and then send it on to be compiled and executed. The easiest way to do that is to write a module that uses the standard (in version 5.8.0 and later) Filter::Simple module:

package My::Filter;
use Filter::Simple;

FILTER_ONLY code => sub
{
    # The code from any program that uses this module
    # is passed into this subroutine in $_.
    # Whatever is in $_ at the end of this subroutine
    # becomes the source code that the compiler eventually sees.
};

1;

Because the Perl compiler only sees the end result of these source filters, only that end result has to be valid Perl code. The original source code that the filter intercepts can be anything you like, as long as the filter can transform that anything into valid Perl.

For example, you could augment the Perl subroutine declaration syntax by creating a source filter that looks for subs with parameter lists and converts them to normal subs:

package Sub::With::Params;
use Filter::Simple;

# Regex that matches a valid Perl identifier (e.g. a sub name)...
my $IDENT = qr/[^\W\d]\w*/;

# Apply this filter to the code of any program
# that uses Sub::With::Params...
FILTER_ONLY code => sub
{
    s{ ( sub \s* $IDENT \s* )   # Match any named sub declaration
       (   \( .*? \)        )   # ...followed by a parameter list
       (   \s* \{           )   # ...followed by a sub body
    }
    {$1$3 my $2 = \@_;}gxs;     # Then move the param list inside the
                                # sub, converting it to a list of
                                # lexical variables initialized from @_
};

1;

By setting up this filter module so that it expects subs with parameter lists and transforms them into regular subs that unpack @_ into lexicals, now you can write:

use Sub::With::Params;

sub convert_to_base($base, $number)
{
    my $converted  = '';
    while ($number > 0)
    {
        $converted = $NUMERAL_FOR[$number % $base] . $converted;
        $number    = int( $number / $base);
    }
    return $converted;
}

and have it work as you expect. Sub::With::Params will now intercept your source code on its way to the compiler and convert it to:

sub convert_to_base { my ($base, $number) = @_;
    my $converted  = '';
    while ($number > 0)
    {
        $converted = $NUMERAL_FOR[$number % $base] . $converted;
        $number    = int( $number / $base);
    }
    return $converted;
}

Suppose that you could use the starting column of a heredoc’s terminator to indicate the left margin of each line of the preceding heredoc content. In other words, what if you could indent every line in the heredoc by the same amount as the final terminator marker? If that were the case, then the previous example would work as expected, printing:

$ ksv -z filename

Usage: ksv [options] <infile> <outfile>

Options:
 -z       Zero tolerance on formatting errors
 -o       Output overview only
 -d       Debugging mode

with the start of each line hard against the left margin.

To make that happen in real life, you need a source filter that recognizes indented heredocs and rewrites them as unindented heredocs before they reach the compiler. Here’s a module that provides just that:

package Heredoc::Indenting;

use Filter::Simple;

FILTER
{
    # Find all instances of...
    1 while
        s{ <<                     #     Heredoc marker
           ( ['"]             )   # $1: Quote for terminator
           ( (?:\\\1|[^\n])*? )   # $2: Terminator specification
             \1                   #     Matching closing quote
           ( [^\n]*  \n       )   # $3: The rest of the statement line
           ( .*? \n           )   # $4: The heredoc contents
           ( [^\S\n]*         )   # $5: Any whitespace indent before...
             \2 \n                #     ...the terminator itself
        }

        # ... and replace it with the same heredoc, with its terminator
        # outdented and the heredoc contents passed through a subroutine
        # that removes the indent from each line...
        {Try::outdent(q{$1$2$1}, '$5',<< $1$2$1)\n$4$2\n$3}xms;
};

use Carp;

# Remove indentations from a string...
sub outdent
{
    my ($name, $indentation, $string) = @_;

    # Complain if any line doesn't have the specified indentation...
    if ($string =~ m/^((?:.*\n)*?)(?!$indentation)(.*\S.*)\n/m)
    {
        my ($good_lines, $bad_line) = ($1, $2);
        my $bad_line_pos = 1 + ($good_lines =~ tr/\n/\n/);
        croak "Negative indentation on line $bad_line_pos ",
              "of <<$name heredoc specified";
    }

    # Otherwise remove the indentations from each line...
    $string =~ s/^$indentation//gm;
    return $string;
}

1;

The FILTER {...} block tells Filter::Simple how to filter any code that uses the Heredoc::Indenting module. The code comes in in the $_ variable and the block then uses a repeated regex substitution to replace each outdented heredoc with a regular left-justified heredoc.

The regex is complex because it has to break a heredoc up into: introducer, quoted terminator specification, remainder of statement, heredoc contents, terminator indent, and terminator. The replacement is complex too, as it reorders those components as: outdenter function, introducer, quoted terminator specification, heredoc contents, terminator, and remainder of statement.

This reordering also explains why the FILTER block uses 1 while s/.../.../ instead of s/.../.../g. Using the /g flag doesn’t allow for overlapping matches, which would cause the substitution to skip over the rewritten remainder of statement component. The remainder of the statement might contain another indented heredoc however, which would then process incorrectly. In contrast, the 1 while... form rematches the partially rewritten source code from the start, so it correctly handles multiple heredocs on the same line.

There’s a cunning layout trick used here. Because each heredoc is rewritten as a (modified) heredoc, on the second iteration of the 1 while, the first heredoc it will find is the one it just rewrote, so the substitution is in danger of reprocessing and re-reprocessing and re-re-reprocessing that very first heredoc ad infinitum. To avoid that, the module requires that indented heredocs have no space between their << introducer and their terminator specification, like so:

print <<"END_USAGE";

Then it carefully rewrites each heredoc so that it does have a space between those two components:

{Try::outdent(q{$1$2$1}, '$5',<< $1$2$1)\n$4$2\n$3}xms;
#                               ^
#                               |
            

That way, the next time the iterated substitution matches against the source code, it will ignore any already-rewritten heredocs and move on to the first unrewritten one instead.

Each heredoc is rewritten to pass through the Try::outdent( ) subroutine at runtime. This subroutine removes the specified indentation (passed as its second argument) from the heredoc text, checking for invalid indentations as it does so.

As an alternative, the FILTER block itself could run the heredoc contents through outdent( ) as it rewrites them. To do that, the second half of the substitution would look instead like:

{"<< $1$2$1\n" . Try::outdent($1.$2.$1, $5, $4) . "$2\n$3"}exms;

with the /e flag allowing you to specify the replacement as an expression to be evaluated, rather than as a simple string.

The advantage of this second version of the filter is that the outdenting of each heredoc now occurs only once, at compile time during the original source filtering, rather than every time perl encounters the heredoc at run-time. The disadvantage is that Perl will report any errors during the outdenting as occurring at the use Heredoc::Indenting line, rather than in the correct position of the heredoc in the source code. Although that’s entirely accurate—they are occurring during the loading of the filtering module—it’s not very useful to users of the module, who really want to know where their heredocs are broken, not where your module detected the breakage.

Consider how Perl passes arguments to functions: in @_, on a stack. As far as the calling conventions work, any function that takes a string, an array reference, and a hash reference looks the same for the purposes of calling the function.

Consider how C passes arguments to functions: much the same way. Any function that takes two integers and returns a double looks the same, again as far as the calling conventions go.

Similarly, any XS code that converts between a Perl function that passes two integers (well, scalars containing integers) to a C function and expects a double (well, a scalar containing a numeric value) is the same. The only difference is the name of the function as Perl sees it and the actual C function it calls. Those are actually very easy to vary.

The P5NCI module builds up its own library of thunk functions (the glue between Perl and C) and allows you to bind thunks to functions in shared libraries.

Suppose you want to use a good, fast library for determining the cube root of any given number. The libm shared library in the C standard library provides a nice function cbrt that takes a double and returns a double and does it fairly quickly—at least more quickly than you could do it in Perl (and certainly more easily than you could write XS code to do it).

Loading the library and creating the wrapper around cbrt is easy, once you know the name of the shared library and the function signature:

use P5NCI::Library;

my $lib = P5NCI::Library->new( library => 'm' );
$lib->install_function( 'cbrt', 'dd' );

print cbrt( 27 ), "\n";
print cbrt( 31 ), "\n";

Note that, if you have P5NCI installed, you don’t need a compiler to do this, nor do you even need math.h installed for this to work! Just create a new P5NCI::Library object, passing the name of the library without any platform-specific prefix or suffix.^[7] Then, call install_function( ) on that object, passing the name of the function within the shared library to wrap as well as the signature, where the first letter is the type of the returned variable and the remaining letters are the types of the arguments to the function. You probably need to read the header or at least the documentation for the shared library to find out the signature, but you don’t have to have the development package or tools installed when you deploy your code.

Then call the function as if it were a normal Perl function—as far as the code cares, it is.

See the module’s documentation for other call signatures.

One drawback of the NCI approach as described here is that it requires a shared library containing the thunking layer between Perl’s and C’s calling conventions. Even with a few possible data types and signatures no longer than four characters, there are still many, many possible necessary thunking functions. If your project only needs a few types of signatures, building your own thunking library can be useful. If you want to distribute this thunking layer, you must compile it for the destination machines. Fortunately, you only have to compile it once.

For general use, wrapping a library such as libffi may be a better approach—it can generate the thunks on its own as needed, requiring only that you have the FFI library installed. Look for updates to P5NCI on the CPAN that do this.

It’s possible to handle pointers to structures passed to and from the shared library as well. Marcus Holland-Moritz’s Convert::Binary::C is a likely candidate for giving access to struct members.

You need some kind of proxy, or rather, reverse-proxy sitting on port 443 at home.example.com that can tell the difference between a SSL connection and a SSH connection.

Using a tool such as Ethereal, it’s quite easy to notice the differences between the two protocols by looking at the first few packets of data exchanged. The SSH server packets look something like:

SSH-2.0-OpenSSH_3.9p1

while the client resembles:

SSH-2.0-OpenSSH_4.2p1 Debian-5

Then they both negotiate the cyphering protocol and everything else. HTTP over SSL looks different. A common session might be:

Client: ....s...o......$.@]w#.U!..F.(.h..^.#y....D....[/.x.=...."..w.4..
Server: ....J...F..C.B.....y..cY.}s......h\.qo.......9..8.i.|..7..

Here it’s unreadable garbage from the beginning—but did you notice the difference?

When using a protocol like SSH, the server always speaks first, and sends a banner to the client. When using HTTP over SSL, it’s the client that speaks first.

Now you have a way to discriminate between the two services: once a client has connected to the reverse-proxy’s port 443, if it immediately sends data then it’s an SSL client; if it does nothing and waits for data to be sent by the server, then it’s a SSH client. The reverse proxy can wait for a short timeout before deciding which of the two services to contact. With the connection established, it can start its proxy work and send data back and forth between client and server.

In 2003, Philippe “BooK” Bruhat wrote a 160-line script that did just that. Nowadays, all the necessary logic to write a network proxy is in a module aptly named Net::Proxy. Creating a reverse proxy to serve both HTTPS and SSH on port 443 of your home machine is now a handful of lines of code away:

#!/usr/bin/perl

use strict;
use warnings;

use Net::Proxy;

# show some information on STDERR
Net::Proxy->set_verbosity(1);

# run this on the server that should listen on port 443
my $proxy = Net::Proxy->new(
    {   in =>
        {
            type         => 'dual',
            host         => '0.0.0.0',
            port         => 443,
            client_first =>
            {
                type => 'tcp',
                port => 444,     # move the https server to another port
            },
            server_first =>
            {
                type => 'tcp',
                port => 22,      # good old SSH
            },

            # wait during a 2 second timeout
            timeout      => 2,
        },
        out => { type => 'dummy' },
    }
);

$proxy->register( );

Net::Proxy->mainloop( );

Depending on your operating system, you may need to run the program with some administrative privileges to listen on a port below 1024.

Run the program on your server. From your workstation, connect as usual. The only limitation of dual is that you have to find a pair of services with these special characteristics. HTTP and HTTPS are protocols where the client speaks first. The server speaks first with SSH, POP3, and SMTP.

Net::Proxy is how BooK hacked the sslh hack (the 160-line Perl script). This module introduces the concept of connectors: in connectors accept incoming (client) connections and forward them toward servers via out connectors.

There is a tcp connector that handles standard TCP inbound and outbound connections, a connect connector that implements the CONNECT trick mentioned earlier, and a dummy connector that does nothing. BooK plans to add new connectors over time.

The dual connector used in this example uses the timeout trick to decide which connector (server_first or client_first) will contact the remote service. So the usual out parameter is just a dummy connector.

You can also use Net::Proxy to proxy an outgoing SSH connection through the corporate proxy:

#!/usr/bin/perl

use strict;
use warnings;

use Net::Proxy;

# show some information on STDERR
Net::Proxy->set_verbosity(1);

# run this on your workstation
my $proxy = Net::Proxy->new(
    {   in =>
        {
            # local port for local SSH client
            port => 2222,
            type => 'tcp',
        },
        out =>
        {
            host        => 'home.example.com',
            port        => 443,
            proxy_host  => 'proxy.company.com',
            proxy_port  => 8080,
            proxy_user  => 'id23494',
            proxy_pass  => 's3kr3t',
            proxy_agent => 'Mozilla/4.0 (compatible; MSIE 6.0; Windows XP)',
        },
    }
);

$proxy->register( );

Net::Proxy->mainloop( );

To reach the https server, use your browser as usual—you’ve already configured it to use the corporate proxy!

Two scripts included in the Net::Proxy distribution support both of these uses. sslh lets you run two services on a single port on the server side and connect-tunnel helps you get through the corporate proxy on the client side.

The idea is to gather all the different keys of the dispatch table and assemble them into a single regular expression. Given such an expression, you can then apply it to a target string and see what matches.

Even better, specifying a tracked pattern lets you find out after the match which pattern from the dispatch triggered the match. Once you have this, use it as a key into the dispatch table and call the corresponding code block. The more keys there are, the better the situation becomes, because instead of running down a long chain of regular expression matches in an if/elsif/elsif chain sequentially, you need only one match to try them all at once.

At the simplest, assemble the keys in the above dispatch table into a single tracked regular expression with:

my $re = Regexp::Assemble->new->track->add(keys %dispatch);

You can then use this to process a file with a loop as simple as:

while (<>)
{
    $re->match($_) and print $dispatch{$re->matched}->( );
}

As an example, consider an IRC bot. You may wish to program a bot to react to many different messages observed on a channel. Ordinarily, you might do this with a mini-parser running through a list of regular expressions. Regexp::Assemble allows you to use a dispatch table instead.

All that you need is a hash whose keys are regular expressions (or to be precise, scalars usable as regexps), and whose values are code references.

First assemble the hash keys, and then match the resulting expression against incoming messages on an IRC channel. When a match occurs, recover the original regexp and use it to look up the code reference in the dispatch table and call that, passing in the captured variables that the pattern specified.

Here’s a bare-bones IRC bot that has just enough smarts to keep track of karma (foo++, bar--) and factoids (for instance, the association that TPF is The Perl Foundation, so when someone asks “TPF?”, the bot responds with the definition).

The instantiating code is very short, thanks to Bot::BasicBot:

use DispatchBot;

my $bot = DispatchBot->new(
    server   => "irc.perl.org",
    port     => "6667",
    channels => ["#bottest"],
    nick     => 'rebot',
);
$bot->run( );

The package DispatchBot is where everything all happens:

package DispatchBot;

use strict;
use Regexp::Assemble;
use Bot::BasicBot;
use YAML qw(LoadFile DumpFile);

use vars qw( $VERSION @ISA );
$VERSION    = '0.03';
@ISA        = 'Bot::BasicBot';

my $factoid = _load( 'factoid.dat' ); # "foo" is "bar" factoids
my $karma   = _load( 'karma.dat' );   # keep track of foo++ and foo--

sub _load
{
    my $file = shift;
    return -e $file ? LoadFile($file) : { };
}

sub _save
{
    my ($dictionary, $file) = @_;
    DumpFile( $file, $dictionary );
}

sub _flush
{
    _save( $factoid, 'factoid.dat' );
    _save( $karma,   'karma.dat' );
}

END { _flush }

my %dispatch =
(
    # define a factoid
    '(\\S+) is (.*)$' => sub { $factoid->{$_[0]} = $_[1]; _flush; return },

    # query a factoid
    '(\\S+)\s*\\?$' => sub
    {
        exists $factoid->{$_[0]}
            and return "I believe that $_[0] is $factoid->{$_[0]}"
    },

    # drop a factoid
    'forget (\\S+)$'=> sub
    {
        if (exists $factoid->{$_[0]})
        {
            my $message = "I forgot $_[0]";
            delete $factoid->{$_[0]};
            _flush;
            return $message;
        }
    },

    # karma shifts
    '(\\S+)\\+\\+' => sub { $karma->{$_[0]}++; _flush; return },
    '(\\S+)--'     => sub { $karma->{$_[0]}--; _flush; return },

    # karma query
    '^karma (\\S+)$' => sub
    {
        return exists $karma->{$_[0]}
            ? "$_[0] has karma of $karma->{$_[0]}"
            : "$_[0] has neutral karma"
    },

    # time... to die
    '^!quit$' => sub { exit },
);

my $re = Regexp::Assemble->new->track->add(keys %dispatch);

sub said
{
    my ($self, $arg) = @_;
    $re->match($arg->{body})
        and return $dispatch{$re->matched}->($re->capture);
    return;
               
               
}

Interval arithmetic is a simple technique for tracking the accuracy of numeric computations. Instead of representing each value as a single number, encode it as a range: minimum possible value to maximum possible value.

For example, most platforms can’t represent the number 1.2345678901234567890 exactly. Interval arithmetic would encode it as the range [1.23456789012345, 1.23456789012346], assuming those two values are the closest lower and upper bounds that your machine can represent. On the other hand, if your machine could represent the number 1.23456, then it would encode it as [1.23456, 1.23456], with identical lower and upper bounds as there is no uncertainty about the actual value.

Once every number is properly encoded, any unary operations on the number are applied to both the minimal and maximal values, producing a new range that encodes the result. For example, the operation:

sqrt( [1.2, 1.3] )

yields:

[1.095445, 1.140175]

being the square roots of the minimal and maximal values. Logically, the true square root of the true value must lie somewhere in that new range.

Binary operations are more complex. They have to be performed on every possible combination of the minimal and maximal values of each operand. Then the minimal and maximal outcomes are used as the encoding of the result. For example, the multiplication:

[1.2, 1.3] * [-1, 0.9]

produces the result:

[-1.3, 1.17]

because:

1.2 *  -1 → -1.2
1.3 *  -1 → -1.3   (minimal value)
1.2 * 0.9 →  1.08
1.3 * 0.9 →  1.17  (maximal value)

The advantage of interval arithmetic is that, provided you’re careful about rounding errors, the exact result is always guaranteed to lie somewhere in the interval you produce. Intervals also make it easy to estimate how accurate your computation is: the smaller the interval, the more precise the answer.

You can also think of intervals as: average value( half-interval). So you could also write the operation:

[1.2, 1.3] * [-1, 0.9]  →  [-1.3, 1.17]

as:

1.25(0.05) * -0.05(0.95)  →  -0.065(1.235)

This representation gives a clear indication of how the accuracy of the approximation changes under different operations, and how the uncertainty in the result grows over time.

To make Perl track the accuracy of your floating-point calculations, you first have to convince it to represent every floating point number as an interval:

package Number::Intervals;

# Compute maximal error in the representation of a given number...
sub _eps_for
{
    my ($num, $epsilon) = (shift) x 2;              # copy arg to both vars
    $epsilon /= 2 while $num + $epsilon/2 != $num;  # whittle epsilon down
    return $epsilon;
}

# Create an interval object, allowing for representation errors...
sub _interval
{
    use List::Util qw( min max );
    my ($min, $max) = ( min(@_), max(@_) );
    return bless [$min - _eps_for($min), $max + _eps_for($max)], __PACKAGE__;
}

# Convert all floating-point constants to interval objects...
sub import
{
    use overload;

    overload::constant(
        float => sub
        {
            my ($raw, $cooked) = @_;
            return _interval($cooked);
        },
    );
}

When your code uses Number::Intervals, its import( ) will call the constant( ) subroutine from the standard overload module. That subroutine does exactly what its name suggests: it overloads the standard handling of constants with new behaviors. In this case, you’re overloading the handling of floating-point constants by providing a subroutine that will be called every time a literal floating-point value appears in your program.

That handler subroutine receives two arguments: a string containing the raw source code that defined the constant ($raw), and a numeric value that is how Perl would normally interpret that source code definition ($cooked). The subroutine should return an object to use instead of the constant value.

In this instance, the handler just returns the corresponding interval object for the cooked value, as provided by _interval($cooked). That function determines the minimal and maximal values it receives and uses them as the lower and upper bounds of the resulting range. Note that it also subtracts the smallest possible amount (_eps_for($min)) from the lower bound and adds the smallest possible amount (_eps_for($max)) to the upper bound.

Adding and subtracting these epsilon values doesn’t produce the smallest possible interval representing the original value, but the interval it does produce has three essential advantages: it’s trivial to compute, it’s guaranteed to correctly bound any number passed to _interval( ) (regardless of the rounding scheme your floating-point implementation uses), and it still produces the second-smallest possible interval representing the original number.

Of course, this isn’t the end of the story. Depending on how you use Number::Intervals objects, you may get the wrong results. You can fix that too, though, in “Overload Your Operators” [Hack #100].

The trick, of course, is to overload the arithmetic operators that will apply to Number::Intervals objects by using the overload pragma:

# Overload operators for Number::Intervals objects...
use overload
(
    # Add two intervals by independently adding minima and maxima...
    q{+} => sub
    {
        my ($x, $y) = _check_args(@_);
        return _interval($x->[0] + $y->[0], $x->[1] + $y->[1]);
    },

    # Subtract intervals by subtracting maxima from minima and vice versa...
    q{-} => sub
    {
        my ($x, $y) = _check_args(@_);
        return _interval($x->[0] - $y->[1], $x->[1] - $y->[0]);
    },

    # Multiply intervals by taking least and greatest products...
    q{*} => sub
    {
        my ($x, $y) = _check_args(@_);
        return _interval($x->[0] * $y->[0], $x->[1] * $y->[0],
                         $x->[1] * $y->[1], $x->[0] * $y->[1],
                        );
    },

    # Divide intervals by taking least and greatest quotients...
    q{/} => sub
    {
        my ($x, $y) = _check_args(@_);
        return _interval($x->[0] / $y->[0], $x->[1] / $y->[0],
                         $x->[1] / $y->[1], $x->[0] / $y->[1],
                        );
    },

    # Exponentiate intervals by taking least and greatest powers...
    q{**} => sub
    {
        my ($x, $y) = _check_args(@_);
        return _interval($x->[0] ** $y->[0], $x->[1] ** $y->[0],
                         $x->[1] ** $y->[1], $x->[0] ** $y->[1],
                        );
    },

    # Integer value of an interval is integer value of bounds...
    q{int} => sub
    {
        my ($x) = @_;
        return _interval(int $x->[0], int $x->[1]);
    },

    # Square root of interval is square roots of bounds...
    q{sqrt} => sub
    {
        my ($x) = @_;
        return _interval(sqrt $x->[0], sqrt $x->[1]);
    },

    # Unary minus: negate bounds and swap upper/lower:
    q{neg} => sub
    {
        my ($x) = @_;
        return _interval(-$x->[1], -$x->[0]);
    },

    # etc. etc. for the other arithmetic operators...
);

The overload module expects a list of key/value pairs, where each key is the name of an operator and each value is a subroutine that implements that operator. Once they’re installed, each of the implementation subroutines will be called whenever an object of the class is an argument to the corresponding operator.

Unary operators (including int, neg, and sqrt) receive the operand object as their only argument; binary operators (like +, *, and **) receive three arguments: their two operands and an extra flag indicating whether the operands appear in reversed order (because the first operand wasn’t an object). Binary operators therefore need to check, and sometimes unreverse, their arguments, which the _check_args( ) subroutine does for them:

# Flip args if necessary, converting to an interval if not already...
sub _check_args
{
    my ($x, $y, $reversed) = @_;

    return $reversed              ?  ( _interval($y), $x            )
         : ref $y ne __PACKAGE__  ?  ( $x,            _interval($y) )
         :                           ( $x,            $y            );
}

Note that this utility subroutine also converts any non-interval arguments (integers, for example) to interval ranges. This means that, after calling _check_args( ), all of the binary handlers can be certain that their operands are in the correct order and that both operands are proper interval objects. This greatly simplifies the implementation of the overloaded operators. In particular, they don’t need to implement three separate sets of logic for handling interval/number, number/interval, and interval/interval interactions.

$ perl count_atoms_v2.pl

Number of atoms = Number::Intervals=ARRAY(0x182f89c)

use overload
(
    # Stringify intervals as: VALUE (UNCERTAINTY)...
    q{""} => sub
    {
        my ($self) = @_;

        my $uncert = ($self->[1] - $self->[0]) / 2;

        use charnames qw( :full );
        return $self->[0]+$uncert . " (\N{PLUS-MINUS SIGN}$uncert)";
    },

    # Numerify intervals by averaging their bounds (with warning)...
    q{0+} => sub
    {
        my ($self) = @_;
        carp "Approximating interval by a single (averaged) number";
        return ($self->[0] + $self->[1]) /2;
    },
);

$ perl count_atoms_v3.pl

Number of atoms = 1.07832864612244e+24 (805306368)