NAME

Stepford::Planner - Takes a set of steps and figures out what order to run them in

VERSION

version 0.001002

SYNOPSIS

use Stepford::Planner;

Stepford::Planner->new(
    step_namespaces => 'My::Step',
    final_step      => 'My::Step::MakeSomething',
)->run();

DESCRIPTION

This class takes a set of objects which do the Stepford::Role::Step role and determines what order they should be run so as to get to a final step.

Steps which are up to date are skipped during the run, so no unnecessary work is done.

METHODS

This class provides the following methods:

Stepford::Planner->new(...)

This method returns a new planner object. It accepts the following arguments:

• step_namespaces

  This argument is required.

  This can either be a string or an array reference of strings. Each string should contain a namespace which contains step classes.

  For example, if your steps are named My::Step::CreateFoo, My::Step::MergeFooAndBar, and My::Step::DeployMergedFooAndBar, the namespace you'd provide is 'My::Step'.

  The order of the step namespaces is relevant. If more than one step has a production of the same name, then the first step "wins". Stepford sorts step class names based on the order of the namespaces provided to the constructor, and then the full name of the class. You can take advantage of this feature to provide different steps in a different environments (for example, for testing).

  The constructor checks for circular dependencies among the steps and will throw a Stepford::Error exception if it finds one.

• final_step

  This argument is required.

  This is the final step that the planner should run when the $planner->run() method is called. This should be a valid (loaded) class that does the Stepford::Role::Step role.

• logger

  This argument is optional.

  This should be an object that provides debug(), info(), notice(), warning(), and error() methods.

  This object will receive log messages from the planner and (possibly your steps).

  If this is not provided, Stepford will create a Log::Dispatch object with a single Log::Dispatch::Null output (which silently eats all the logging messages).

  Note that if you do provide a logger object of your own, Stepford will not load Log::Dispatch into memory.

$planner->run()

When this method is called, the planner comes up with a plan of the steps needed to get to the final step given to the constructor and runs them in order.

For each step, the planner checks if it is up to date compared to its dependencies (as determined by the $step->last_run_time() method. If the step is up to date, it is skipped, otherwise the planner calls $step->run() on the step.

Note that the step objects are always constructed, so you should avoid doing a lot of work in your constructor. Save that for the run() method.

$planner->step_namespaces()

This method returns the step namespaces passed to the constructor as a list (not an arrayref).

$planner->final_step()

This method returns the final_step argument passed to the constructor.

$planner->logger()

This method returns the logger used by the planner, either what you passed to the constructor or a default.

AUTHOR

Dave Rolsky <drolsky@maxmind.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by MaxMind, Inc..

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.