Name

App::Sqitch::Plan - Sqitch Deployment Plan

Synopsis

  my $plan = App::Sqitch::Plan->new( file => $file );
  while (my $tag = $plan->next) {
      say "Deploy ", join' ', @{ $tag->names };
  }

Description

App::Sqitch::Plan provides the interface for a Sqitch plan. It parses a plan file and provides an iteration interface for working with the plan.

Interface

Constructors

new

  my $plan = App::Sqitch::Plan->new(%params);

Instantiates and returns a App::Sqitch::Plan object.

Accessors

sqitch

  my $sqitch = $cmd->sqitch;

Returns the App::Sqitch object that instantiated the plan.

position

Returns the current position of the iterator. This is an integer that's used as an index into plan. If next() has not been called, or if reset() has been called, the value will be -1, meaning it is outside of the plan. When next returns undef, the value will be the last index in the plan plus 1.

Instance Methods

index_of

  my $index = $plan->index_of($tag_name);

Returns the index of the specified tag name.

seek

  $plan->seek($tag_name);

Move the plan position to the specified tag. Dies if the tag cannot be found in the plan.

reset

   $plan->reset;

Resets iteration. Same as $plan-position(-1)>, but better.

next

  while (my $tag = $plan->next) {
      say "Deploy ", join' ', @{ $tag->names };
  }

Returns the next App::Sqitch::Plan::Tag in the plan. Returns undef if there are no more tags.

last

  my $tag = $plan->last;

Returns the last tag in the plan. Does not change the current position.

current

   my $tag = $plan->current;

Returns the same tag as was last returned by next(). Returns undef if next() has not been called or if the plan has been reset.

peek

   my $tag = $plan->peek;

Returns the next tag in the plan, without incrementing the iterator. Returns undef if there are no more tags beyond the current tag.

all

  my @tags = $plan->all;

Returns all of the tags in the plan. This constitutes the entire plan.

do

  $plan->do(sub { say $_[0]->names->[0]; return $_[0]; });
  $plan->do(sub { say $_->names->[0];    return $_;    });

Pass a code reference to this method to execute it for each tag in the plan. Each item will be set to $_ before executing the code reference, and will also be passed as the sole argument to the code reference. If next() has been called prior to the call to do(), then only the remaining items in the iterator will passed to the code reference. Iteration terminates when the code reference returns false, so be sure to have it return a true value if you want it to iterate over every item.

write_to

  $plan->write_to($file);

Write the plan to the named file. Comments and white space from the original plan are not preserved, so be careful to alert the user when overwriting an exiting plan file.

open_script

  my $file_handle = $plan->open_script(
      step => $step,
      tags => \@tag_names,
      dir  => $sqitch->deploy_dir,
  );

Opens the script corresponding to the named step in the specified directory. The tags option is ignored, but may be used in subclasses to open a script at a particular point in VCS history. Returns a file handle for reading. The script file must be encoded in UTF-8.

parse

Called internally to populate all by parsing the plan file. Not intended to be used directly, though it may be overridden in subclasses.

load

  my $tags = $plan->load;

Loads the plan, including untracked steps (if with_untracked is true). Called internally, not meant to be called directly, as it parses the plan file and searches the file system (if with_untracked) every time it's called. If you want the all of the steps, including untracked, call all() instead.

Subclasses should override this method to load the plan from whatever resources they deem appropriate.

load_untracked

  my $tag = $plan->load_untracked($tags);

Loads untracked steps and returns them in a tag object with the single tag name HEAD+. Pass in an array reference of tracked tags whose steps should be excluded from the returned untracked. Called internally by load() and not meant to be called directly, as it will scan the file system on every call.

Subclasses may override this method to load a tag with untracked steps from whatever resources they deem appropriate.

sort_steps

  @steps = $plan->sort_steps(@steps);
  @steps = $plan->sort_steps(\%seen, @steps);

Sorts the steps passed in in dependency order and returns them. If the first argument is a hash reference, it is assumed to contain a list of previously-seen steps that can be assumed to be satisfied requirements for the succeeding steps.

See Also

sqitch

The Sqitch command-line client.

Author

David E. Wheeler <david@justatheory.com>

License

Copyright (c) 2012 iovation Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

cpanm App::Sqitch

perl -MCPAN -e shell
install App::Sqitch