Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
App::Sqitch::Plan(3)  User Contributed Perl Documentation App::Sqitch::Plan(3)

Name
       App::Sqitch::Plan - Sqitch Deployment Plan

Synopsis
	 my $plan = App::Sqitch::Plan->new( sqitch => $sqitch );
	 while (my $change = $plan->next) {
	     say "Deploy ", $change->format_name;
	 }

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
   Constants
       "SYNTAX_VERSION"

       Returns the current version of the Sqitch plan syntax. Used for the
       "%sytax-version"	pragma.

   Class Methods
       "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.

   Instance Methods
       "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:

       o   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.

       o   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.

       o   A tag name

	     my	$index = $plan->index_of('@beta1');

	   The name of a tag, including	the leading "@".

       o   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.

Plan File
       A plan file describes the deployment changes to be run against a
       database, and is	typically maintained using the "add" and "rework"
       commands. Its contents must be plain text encoded as UTF-8. Each	line
       of a plan file may be one of four things:

       o   A blank line. May include any amount	of white space,	which will be
	   ignored.

       o   A Pragma

	   Begins with a "%", followed by a pragma name, optionally followed
	   by "=" and a	value. Currently, the only pragma recognized by	Sqitch
	   is "syntax-version".

       o   A change.

	   A named change change as defined in sqitchchanges. A	change may
	   then	also contain a space-delimited list of dependencies, which are
	   the names of	other changes or tags prefixed with a colon (":") for
	   required changes or with an exclamation point ("!") for conflicting
	   changes.

	   Changes with	a leading "-" are slated to be reverted, while changes
	   with	no character or	a leading "+" are to be	deployed.

       o   A tag.

	   A named deployment tag, generally corresponding to a	release	name.
	   Begins with a "@", followed by one or more non-blanks characters,
	   excluding "@", ":", "#", and	blanks.	The first and last characters
	   must	not be punctuation characters.

       o   A note.

	   Begins with a "#" and goes to the end of the	line. Preceding	white
	   space is ignored. May appear	on a line after	a pragma, change, or
	   tag.

       Here's an example of a plan file	with a single deploy change and	tag:

	%syntax-version=1.0.0
	+users_table
	@alpha

       There may, of course, be	any number of tags and changes.	Here's an
       expansion:

	%syntax-version=1.0.0
	+users_table
	+insert_user
	+update_user
	+delete_user
	@root
	@alpha

       Here we have four changes -- "users_table", "insert_user",
       "update_user", and "delete_user"	-- followed by two tags: "@root" and
       "@alpha".

       Most plans will have many changes and tags. Here's a longer example
       with three tagged deployment points, as well as a change	that is
       deployed	and later reverted:

	%syntax-version=1.0.0
	+users_table
	+insert_user
	+update_user
	+delete_user
	+dr_evil
	@root
	@alpha

	+widgets_table
	+list_widgets
	@beta

	-dr_evil
	+ftw
	@gamma

       Using this plan,	to deploy to the "beta"	tag, all of the	changes	up to
       the "@root" and "@alpha"	tags must be deployed, as must changes listed
       before the "@beta" tag. To then deploy to the "@gamma" tag, the
       "dr_evil" change	must be	reverted and the "ftw" change must be
       deployed. If you	then choose to revert to "@alpha", then	the "ftw"
       change will be reverted,	the "dr_evil" change re-deployed, and the
       "@gamma"	tag removed; then "list_widgets" must be reverted and the
       associated "@beta" tag removed, then the	"widgets_table"	change must be
       reverted.

       Changes can only	be repeated if one or more tags	intervene. This	allows
       Sqitch to distinguish between them. An example:

	%syntax-version=1.0.0
	+users_table
	@alpha

	+add_widget
	+widgets_table
	@beta

	+add_user
	@gamma

	+widgets_created_at
	@delta

	+add_widget

       Note that the "add_widget" change is repeated after the "@beta" tag,
       and at the end. Sqitch will notice the repetition when it parses	this
       file, and allow it, because at least one	tag "@beta" appears between
       the instances of	"add_widget". When deploying, Sqitch will fetch	the
       instance	of the deploy script as	of the "@delta"	tag and	apply it as
       the first change, and then, when	it gets	to the last change, retrieve
       the current instance of the deploy script. How does it find such	files?
       The first instances files will either be	named add_widget@delta.sql or
       (soon) findable in the VCS history as of	a VCS "delta" tag.

   Grammar
       Here is the EBNF	Grammar	for the	plan file:

	 plan-file    =	{ <pragma> | <change-line> | <tag-line>	| <note-line> |	<blank-line> }*	;

	 blank-line   =	[ <blanks> ] <eol>;
	 note-line    =	<note> ;
	 change-line  =	<name> [ "[" { <requires> | <conflicts>	} "]" ]	( <eol>	| <note> ) ;
	 tag-line     =	<tag> (	<eol> |	<note> ) ;
	 pragma	      =	"%" [ <blanks> ] <name>	[ <blanks> ] = [ <blanks> ] <value> ( <eol> | <note> ) ;

	 tag	      =	"@" <name> ;
	 requires     =	<name> ;
	 conflicts    =	"!" <name> ;
	 name	      =	<non-punct> [ [	? non-blank and	not "@", ":", or "#" characters	? ] <non-punct>	] ;
	 non-punct    =	? non-punctuation, non-blank character ? ;
	 value	      =	? non-EOL or "#" characters ?

	 note	      =	[ <blanks> ] "#" [ <string> ] <EOL> ;
	 eol	      =	[ <blanks> ] <EOL> ;

	 blanks	      =	? blank	characters ? ;
	 string	      =	? non-EOL characters ? ;

       And written as regular expressions:

	 my $eol	  = qr/[[:blank:]]*$/
	 my $note	  = qr/(?:[[:blank:]]+)?[#].+$/;
	 my $punct	  = q{-!"#$%&'()*+,./:;<=>?@[\\]^`{|}~};
	 my $name	  = qr/[^$punct[:blank:]](?:(?:[^[:space:]:#@]+)?[^$punct[:blank:]])?/;
	 my $tag	  = qr/[@]$name/;
	 my $requires	  = qr/$name/;
	 my conflicts	  = qr/[!]$name/;
	 my $tag_line	  = qr/^$tag(?:$note|$eol)/;
	 my $change_line  = qr/^$name(?:[[](?:$requires|$conflicts)+[]])?(?:$note|$eol)/;
	 my $note_line	  = qr/^$note/;
	 my $pragma	  = qr/^][[:blank:]]*[%][[:blank:]]*$name[[:blank:]]*=[[:blank:]].+?(?:$note|$eol)$/;
	 my $blank_line	  = qr/^$eol/;
	 my $plan	  = qr/(?:$pragma|$change_line|$tag_line|$note_line|$blank_line)+/ms;

See Also
       sqitch
	   The Sqitch command-line client.

Author
       David E.	Wheeler	<david@justatheory.com>

License
       Copyright (c) 2012-2015 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.

perl v5.24.1			  2017-07-03		  App::Sqitch::Plan(3)

Name | Synopsis | Description | Interface | Plan File | See Also | Author | License

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=App::Sqitch::Plan&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help