Constants"SYNTAX_VERSION"
Returns the current version of the Sqitch plan syntax. Used for the "%sytax-version" pragma.
ClassMethods"name_regex"
die "$this has no name" unless $this =~ App::Sqitch::Plan->name_regex;
Returns a regular expression that matches names. Note that it is not anchored, so if you need to make
sure that a string is a valid name and nothing else, you will need to anchor it yourself, like so:
my $name_re = App::Sqitch::Plan->name_regex;
die "$this is not a valid name" if $this !~ /\A$name_re\z/;
Constructors"new"
my $plan = App::Sqitch::Plan->new( sqitch => $sqitch );
Instantiates and returns a App::Sqitch::Plan object. Takes a single parameter: an App::Sqitch object.
Accessors"sqitch"
my $sqitch = $plan->sqitch;
Returns the App::Sqitch object that instantiated the plan.
"target"
my $target = $plan->target
Returns the App::Sqitch::Target passed to the constructor.
"file"
my $file = $plan->file;
The file name from which to read 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.
"project"
my $project = $plan->project;
Returns the name of the project as set via the %project pragma in the plan file.
"uri"
my $uri = $plan->uri;
Returns the URI for the project as set via the %uri pragma, which is optional. If it is not present,
"undef" will be returned.
"syntax_version"
my $syntax_version = $plan->syntax_version;
Returns the plan syntax version, which is always the latest version.
InstanceMethods"index_of"
my $index = $plan->index_of('6c2f28d125aff1deea615f8de774599acf39a7a1');
my $foo_index = $plan->index_of('@foo');
my $bar_index = $plan->index_of('bar');
my $bar1_index = $plan->index_of('bar@alpha')
my $bar2_index = $plan->index_of('bar@HEAD');
Returns the index of the specified change. Returns "undef" if no such change exists. The argument may be
any one of:
• An ID
my $index = $plan->index_of('6c2f28d125aff1deea615f8de774599acf39a7a1');
This is the SHA1 hash of a change or tag. Currently, the full 40-character hexed hash string must be
specified.
• A change name
my $index = $plan->index_of('users_table');
The name of a change. Will throw an exception if the named change appears more than once in the list.
• A tag name
my $index = $plan->index_of('@beta1');
The name of a tag, including the leading "@".
• A tag-qualified change name
my $index = $plan->index_of('users_table@beta1');
The named change as it was last seen in the list before the specified tag.
"contains"
say 'Yes!' if $plan->contains('6c2f28d125aff1deea615f8de774599acf39a7a1');
Like index_of(), but never throws an exception, and returns true if the plan contains the specified
change, and false if it does not.
"get"
my $change = $plan->get('6c2f28d125aff1deea615f8de774599acf39a7a1');
my $foo = $plan->get('@foo');
my $bar = $plan->get('bar');
my $bar1 = $plan->get('bar@alpha')
my $bar2 = $plan->get('bar@HEAD');
Returns the change corresponding to the specified ID or name. The argument may be in any of the formats
described for index_of().
"find"
my $change = $plan->find('6c2f28d125aff1deea615f8de774599acf39a7a1');
my $foo = $plan->find('@foo');
my $bar = $plan->find('bar');
my $bar1 = $plan->find('bar@alpha')
my $bar2 = $plan->find('bar@HEAD');
Finds the change corresponding to the specified ID or name. The argument may be in any of the formats
described for index_of(). Unlike get(), find() will not throw an error if more than one change exists
with the specified name, but will return the first instance.
"first_index_of"
my $index = $plan->first_index_of($change_name);
my $index = $plan->first_index_of($change_name, $change_or_tag_name);
Returns the index of the first instance of the named change in the plan. If a second argument is passed,
the index of the first instance of the change after the index of the second argument will be returned.
This is useful for getting the index of a change as it was deployed after a particular tag, for example,
to get the first index of the foo change since the @beta tag, do this:
my $index = $plan->first_index_of('foo', '@beta');
You can also specify the first instance of a change after another change, including such a change at the
point of a tag:
my $index = $plan->first_index_of('foo', 'users_table@beta1');
The second argument must unambiguously refer to a single change in the plan. As such, it should usually
be a tag name or tag-qualified change name. Returns "undef" if the change does not appear in the plan, or
if it does not appear after the specified second argument change name.
"last_tagged_change"
my $change = $plan->last_tagged_change;
Returns the last tagged change object. Returns "undef" if no changes have been tagged.
"change_at"
my $change = $plan->change_at($index);
Returns the change at the specified index.
"seek"
$plan->seek('@foo');
$plan->seek('bar');
Move the plan position to the specified change. Dies if the change cannot be found in the plan.
"reset"
$plan->reset;
Resets iteration. Same as "$plan->position(-1)", but better.
"next"
while (my $change = $plan->next) {
say "Deploy ", $change->format_name;
}
Returns the next change in the plan. Returns "undef" if there are no more changes.
"last"
my $change = $plan->last;
Returns the last change in the plan. Does not change the current position.
"current"
my $change = $plan->current;
Returns the same change as was last returned by next(). Returns "undef" if next() has not been called or
if the plan has been reset.
"peek"
my $change = $plan->peek;
Returns the next change in the plan without incrementing the iterator. Returns "undef" if there are no
more changes beyond the current change.
"changes"
my @changes = $plan->changes;
Returns all of the changes in the plan. This constitutes the entire plan.
"tags"
my @tags = $plan->tags;
Returns all of the tags in the plan.
"count"
my $count = $plan->count;
Returns the number of changes in the plan.
"lines"
my @lines = $plan->lines;
Returns all of the lines in the plan. This includes all the changes, tags, pragmas, and blank lines.
"do"
$plan->do(sub { say $_[0]->name; return $_[0]; });
$plan->do(sub { say $_->name; return $_; });
Pass a code reference to this method to execute it for each change in the plan. Each change will be
stored in $_ before executing the code reference, and will also be passed as the sole argument. If next()
has been called prior to the call to do(), then only the remaining changes 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 change.
"search_changes"
my $iter = $engine->search_changes( %params );
while (my $change = $iter->()) {
say '* $change->{event}ed $change->{change}";
}
Searches the changes in the plan returns an iterator code reference with the results. If no parameters
are provided, a list of all changes will be returned from the iterator in plan order. The supported
parameters are:
"event"
An array of the type of event to search for. Allowed values are "deploy" and
"revert".
"name"
Limit the results to changes with names matching the specified regular expression.
"planner"
Limit the changes to those added by planners matching the specified regular expression.
"limit"
Limit the number of changes to the specified number.
"offset"
Skip the specified number of events.
"direction"
Return the results in the specified order, which must be a value matching "/^(:?a|de)sc/i" for
"ascending" or "descending".
"write_to"
$plan->write_to($file);
$plan->write_to($file, $from, $to);
Write the plan to the named file, including notes and white space from the original plan file. If "from"
and/or $to are provided, the plan will be written only with the pragmas headers and the lines between
those specified changes.
"open_script"
my $file_handle = $plan->open_script( $change->deploy_file );
Opens the script file passed to it and returns a file handle for reading. The script file must be encoded
in UTF-8.
"load"
my $plan_data = $plan->load;
Loads the plan data. Called internally, not meant to be called directly, as it parses the plan file and
deploy scripts every time it's called. If you want the all of the changes, call changes() instead. And if
you want to load an alternate plan, use parse().
"parse"
$plan->parse($plan_data);
Load an alternate plan by passing the complete text of the plan. The text should be UTF-8 encoded. Useful
for loading a plan from a different VCS branch, for example.
"check_changes"
@changes = $plan->check_changes( $project, @changes );
@changes = $plan->check_changes( $project, { '@foo' => 1 }, @changes );
Checks a list of changes to validate their dependencies and returns them. If the second argument is a
hash reference, its keys should be previously-seen change and tag names that can be assumed to be
satisfied requirements for the succeeding changes.
"tag"
$plan->tag( name => 'whee' );
Tags a change in the plan. Exits with a fatal error if the tag already exists in the plan or if a change
cannot be found to tag. The supported parameters are:
"name"
The tag name to use. Required.
"change"
The change to be tagged, specified as a supported change specification as described in sqitchchanges.
Defaults to the last change in the plan.
"note"
A brief note about the tag.
"planner_name"
The name of the user adding the tag to the plan. Defaults to the value of the "user.name"
configuration variable.
"planner_email"
The email address of the user adding the tag to the plan. Defaults to the value of the "user.email"
configuration variable.
"add"
$plan->add( name => 'whatevs' );
$plan->add(
name => 'widgets',
requires => [qw(foo bar)],
conflicts => [qw(dr_evil)],
);
Adds a change to the plan. The supported parameters are the same as those passed to the
App::Sqitch::Plan::Change constructor. Exits with a fatal error if the change already exists, or if the
any of the dependencies are unknown.
"rework"
$plan->rework( 'whatevs' );
$plan->rework( 'widgets', [qw(foo bar)], [qw(dr_evil)] );
Reworks an existing change. Said change must already exist in the plan and be tagged or have a tag
following it or an exception will be thrown. The previous occurrence of the change will have the suffix
of the most recent tag added to it, and a new tag instance will be added to the list.
Install Now
PNG Icons
SVG Icons