NAME

Script::Resume - State keeper for scripts that might abort in the middle of execution but need to pick up where they left off in later invocations.

SYNOPSIS

use Script::Resume;

my $state = {Robin => "Jason Todd"};
my $rez = new Script::Resume(SCRIPT_STATE => \$state, STAGES => ["do_this", "then_that", "finally_this"]);
$rez->addStage("oh_and_this_too", FUNC => \&this_too, ALWAYS=>1);

$rez->runAllStages();

print "Result: Robin = $state->{Robin}\n";

sub do_this      { print "I'm doing this\n";}
sub then_that    { print "I'm doing that\n"; $state->{Robin} = "Dick Grayson"; }
sub finally_this { print "I'm finally doing this\n"; $state->{Robin} = "Tim Drake"; }
sub this_too     { print "I'm doing this too\n";}

Here's a script that runs it with more explicit control

use Script::Resume;

my $robin;
my $now = time();
my $rez = new Script::Resume();
$rez->addStage("my_first_stage",  FUNC => \&stage_one);
$rez->addStage("my_second_stage", FUNC => \&stage_two);
$rez->addStage("my_third_stage",  FUNC => \&stage_three);

$robin = $rez->runStage("my_first_stage", "Jason Todd");
print "Result: Robin 1 = $robin\n";

$robin = $rez->runStage("my_second_stage", "Dick Grayson");
print "Result: Robin 2 = $robin\n";

$robin = $rez->runStage("my_third_stage", "Tim Drake");
print "Result: Robin3 = $robin\n";

sub stage_one { return shift;}
sub stage_two { return shift;}
sub stage_three { return shift;}

DESCRIPTION

Script::Resume Allows you to automatically break your script into stages with state such that if the script bails out in the middle somewhere, you can fix the problem, rerun the script and it'll pick up where it left off, with the previous state and all. This is useful for tasks where you can't start from the beginning again and/or you wouldn't want to, such as scripts involved in copying massive files around.

State is maintained in a plain Data::Dumper format file in $ENV{TEMP}/$0.state or /tmp/$0.state (or wherever you designate) so you can tweak it before re-running. It will store the SCRIPT_STATE you pass into the constructor along with all return values from all the stages. If the stage has already been run in a previous invocation of your script, the return value will be returned without actually re-running the stage.

METHODS

my $rez = Script::Resume->new(%config)

Construct a new object. Optional parameters include:

$rez = new Script::Resume(DEBUG        => 1,            # Print out debug info. (Default = 0)
                          RETAIN_STATE => 1,            # Keep the state around even after the script finishes 
                                                        # (You'll want to delete this by hand before running the script again)
                                                        # For debugging only. (Default = 0)
                          RESUME       => 0,            # Continue where left off (Default = 1)
                          SCRIPT_STATE => \$my_state,   # Script specific state (reference to a reference to an 
                                                        # object or hash or array or scalar). (Default = undef)
                          STATE_FILE   => "/tmp/X",     # Filename of state file where state is to be stored
                                                        # (Default = "$ENV{TEMP}/$0.state" or "/tmp/$0.state")
                          STAGES       => ["s1", "s2"], # Reference to an array of stage names. (Default = undef)
                          STOP_AFTER   => "s2");        # Stop after state "s2" is run. For debugging only. (Default = undef)

$rez->addStage($stage_name, %config)

addStage() is where you specify the stage name and optionally map it to a function reference. If no function reference is given, it'll try to use the name as a function reference in the calling package.

$rez->addStage("stage_name",
               FUNC    => \&my_func_ref,               # Function reference to call for this stage
               ALWAYS  => 1);                          # Always run this stage. (Default = 0)

$rez->addStages(@stage_names)

This is a convenience function that in turn calls addStage(). You can only call this if all of your stage_names map to function names.

$rez->setStageAttributes($stage_name, %config)

Sets a stage's attributes, such as:

$rez->setStageAttribute("MyThirdStage", ALWAYS => 1, FUNC => \&my_func);

$rez->runStage($stage_name, @stage_parameters)

Runs the stage matching the name $stage_name passing in @stage_parameters and returning the result of running that stage. If the stage has already been run in a previous invocation, it will return that saved data.

$rez->runAllStages($stage_name, @stage_parameters)

Runs all stages in order, passing in @stage_parameters.

$rez->doneEarly()

Call this when you don't want to run the rest of the stages. Calling this function tells Script::Resume that there is no further work to be done and the state can be deleted.

LEGALESE

Copyright 2006 by Robert Powers, all rights reserved. This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

2006, Robert Powers <batman@cpan.org>