Commands::Guarded 0.01

Commands::Guarded Perl package provides better scripts through guarded commands.

SYNOPSIS

use Commands::Guarded;

my $var = 0;

step something =>
ensure { $var == 1 }
using { $var = 1 }
; # $var is now 1

step nothing =>
ensure { $var == 1 }
using { $var = 2 } # bug!
; # $var is still 1 (good thing too)

my $brokeUnless5 =
step brokenUnless5 =>
ensure { $var == 5 }
using { $var = shift }
; # nothing happens yet

print "var: $varn"; # prints 1

$brokeUnless5->do(5);

print "now var: $varn"; # prints 5

step fail =>
ensure { $var == 3 }
using { $var = 2 }
; # Exception thrown here

This module implements a deterministic, rectifying variant on Dijkstras guarded commands. Each named step is passed two blocks: an ensure block that defines a test for a necessary and sufficient condition of the step, and a using block that will cause that condition to obtain.

If step is called in void context (i.e., is not assigned to anything or used as a value), the step is run immediately, as in this pseudocode:

unless (ENSURE) {
USING;
die unless ENSURE;
}

If step is called in scalar or array context, execution is deferred and instead a Commands::Guarded object is returned, which can be executed as above using the do method. If do is given arguments, they will be passed to the ensure block and (if necessary) the using block.

The interface to Commands::Guarded is thus a hybrid of exported subroutines (see SUBROUTINES below) and non-exported methods (see METHODS).
For a detailed discussion of the reason for this modules existence, see RATIONALE below.