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

FreeBSD Manual Pages

  
 
  

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

Name
       App::Sqitch - Sane database change management

Synopsis
	 use App::Sqitch;
	 exit App::Sqitch->go;

Description
       This module provides the	implementation for sqitch. You probably	want
       to read its documentation, or the tutorial. Unless you want to hack on
       Sqitch itself, or provide support for a new engine or command. In which
       case, you will find this	API documentation useful.

Interface
   Class Methods
       "go"

	 App::Sqitch->go;

       Called from "sqitch", this class	method parses command-line options and
       arguments in @ARGV, parses the configuration file, constructs an
       App::Sqitch object, constructs a	command	object,	and runs it.

   Constructor
       "new"

	 my $sqitch = App::Sqitch->new(\%params);

       Constructs and returns a	new Sqitch object. The supported parameters
       include:

       "options"
       "user_name"
       "user_email"
       "editor"
       "verbosity"

   Accessors
       "user_name"

       "user_email"

       "editor"

       "options"

	 my $options = $sqitch->options;

       Returns a hashref of the	core command-line options.

       "config"

	 my $config = $sqitch->config;

       Returns the full	configuration, combined	from the project, user,	and
       system configuration files.

       "verbosity"

   Instance Methods
       "run"

	 $sqitch->run('echo', '-n', 'hello');

       Runs a system command and waits for it to finish. Throws	an exception
       on error. Does not use the shell, so arguments must be passed as	a
       list. Use "shell" to run	a command and its arguments as a single
       string.

       "engine"

	 my $engine = $sqitch->engine(@params);

       Creates and returns an engine of	the appropriate	subclass. Pass in
       additional parameters to	be passed through to the engine	constructor.

   "config_for_target"
	 my $config = $sqitch->config_for_target($target);

       Returns a hash reference	representing the configuration for the
       specified target	name or	URI. The supported keys	in the hash reference
       are:

       "target"
	   The name of the target, as passed.

       "uri"
	   A database URI object, to be	used to	connect	to the target
	   database.

       "registry"
	   The name of the Sqitch registry in the target database.

       If the $target argument looks like a database URI, it will simply
       returned	in the hash reference. If the $target argument corresponds to
       a target	configuration key, the target configuration will be returned,
       with the	"uri" value a upgraded to a URI	object.	Otherwise returns
       "undef".

   "engine_key"
	 my $key = $sqitch->engine_key;
	 my $key = $sqitch->engine_key($uri);

       Returns the key name of the engine. If "--engine" was specified,	its
       value will be used. If the $uri argument	is passed and is a URI::db
       object, the key will be derived from its	database driver. Otherwise,
       the value specified for the "core.engine" variable will be used.

   "config_for_target_strict"
	 my $config = $sqitch->config_for_target_strict($target);

       Like "config_for_target", but throws an exception if $target is not a
       URL, does not correspond	to a target configuration section, or does not
       include a "uri" key. Otherwise returns the target configuration.

       "engine_for_target"

	 my $engine = $sqitch->engine_for($target);

       Like "config_for_target_strict",	but returns an App::Sqitch::Engine
       object. If $target is not defined or is empty, an engine	will be
       returned	for the	default	target.

       "shell"

	 $sqitch->shell('echo -n hello');

       Shells out a system command and waits for it to finish. Throws an
       exception on error. Always uses the shell, so a single string must be
       passed encapsulating the	entire command and its arguments. Use
       "quote_shell" to	assemble strings into a	single shell command. Use
       "run" to	execute	a list without a shell.

       "quote_shell"

	 my $cmd = $sqitch->quote_shell('echo',	'-n', 'hello');

       Assemble	a list into a single string quoted for execution by "shell".
       Useful for combining a specified	command, such as "editor()", which
       might include the options in the	string,	for example:

	 $sqitch->shell( $sqitch->editor, $sqitch->quote_shell($file) );

       "capture"

	 my @files = $sqitch->capture(qw(ls -lah));

       Runs a system command and captures its output to	"STDOUT". Returns the
       output lines in list context and	the concatenation of the lines in
       scalar context.	Throws an exception on error.

       "probe"

	 my $git_version = $sqitch->capture(qw(git --version));

       Like "capture", but returns just	the "chomp"ed first line of output.

       "spool"

	 $sqitch->spool($sql_file_handle, 'sqlite3', 'my.db');
	 $sqitch->spool(\@file_handles,	'sqlite3', 'my.db');

       Like run, but spools the	contents of one	or ore file handle to the
       standard	input the system command. Returns true on success and throws
       an exception on failure.

       "trace"

       "trace_literal"

	 $sqitch->trace_literal('About to fuzzle the wuzzle.');
	 $sqitch->trace('Done.');

       Send trace information to "STDOUT" if the verbosity level is 3 or
       higher.	Trace messages will have "trace: " prefixed to every line. If
       it's lower than 3, nothing will be output. "trace" appends a newline to
       the end of the message while "trace_literal" does not.

       "debug"

       "debug_literal"

	 $sqitch->debug('Found snuggle in the crib.');
	 $sqitch->debug_literal('ITYM "snuggie".');

       Send debug information to "STDOUT" if the verbosity level is 2 or
       higher.	Debug messages will have "debug: " prefixed to every line. If
       it's lower than 2, nothing will be output. "debug" appends a newline to
       the end of the message while "debug_literal" does not.

       "info"

       "info_literal"

	 $sqitch->info('Nothing	to deploy (up-to-date)');
	 $sqitch->info_literal('Going to frobble the shiznet.');

       Send informational message to "STDOUT" if the verbosity level is	1 or
       higher, which, by default, it is. Should	be used	for normal messages
       the user	would normally want to see. If verbosity is lower than 1,
       nothing will be output.	"info" appends a newline to the	end of the
       message while "info_literal" does not.

       "comment"

       "comment_literal"

	 $sqitch->comment('On database flipr_test');
	 $sqitch->comment_literal('Uh-oh...');

       Send comments to	"STDOUT" if the	verbosity level	is 1 or	higher,	which,
       by default, it is. Comments have	"# " prefixed to every line. If
       verbosity is lower than 1, nothing will be output. "comment" appends a
       newline to the end of the message while "comment_literal" does not.

       "emit"

       "emit_literal"

	 $sqitch->emit('core.editor=emacs');
	 $sqitch->emit_literal('Getting	ready...');

       Send a message to "STDOUT", without regard to the verbosity. Should be
       used only if the	user explicitly	asks for output, such as for "sqitch
       config --get core.editor". "emit" appends a newline to the end of the
       message while "emit_literal" does not.

       "vent"

       "vent_literal"

	 $sqitch->vent('That was a misage.');
	 $sqitch->vent_literal('This is	going to be bad...');

       Send a message to "STDERR", without regard to the verbosity. Should be
       used only for error messages to be printed before exiting with an
       error, such as when reverting failed changes. "vent" appends a newline
       to the end of the message while "vent_literal" does not.

       "page"

       "page_literal"

	 $sqitch->page('Search results:');
	 $sqitch->page("Here we	go\n");

       Like "emit()", but sends	the output to a	pager handle rather than
       "STDOUT".  Unless there is no TTY (such as when output is being piped
       elsewhere), in which case it is sent to "STDOUT". "page"	appends	a
       newline to the end of the message while "page_literal" does not.	Meant
       to be used to send a lot	of data	to the user at once, such as when
       display the results of searching	the event log:

	 $iter = $sqitch->engine->search_events;
	 while ( my $change = $iter->()	) {
	     $sqitch->page(join	' - ', @{ $change }{ qw(change_id event	change)	});
	 }

       "warn"

       "warn_literal"

	 $sqitch->warn('Could not find nerble; using nobble instead.');
	 $sqitch->warn_literal("Cannot read file: $!\n");

       Send a warning messages to "STDERR". Warnings will have "warning: "
       prefixed	to every line. Use if something	unexpected happened but	you
       can recover from	it. "warn" appends a newline to	the end	of the message
       while "warn_literal" does not.

       "prompt"

	 my $ans = $sqitch->('Why would	you want to do this?', 'because');

       Prompts the user	for input and returns that input. Pass in an optional
       default value for the user to accept or to be used if Sqitch is running
       unattended. An exception	will be	thrown if there	is no prompt message
       or if Sqitch is unattended and there is no default value.

       "ask_y_n"

	 if ( $sqitch->ask_y_no('Are you sure?', 'y') )	{ # do it! }

       Prompts the user	with a "yes" or	"no" question. Returns true for	"yes"
       and false for "no". Any answer that begins with case-insensitive	"y" or
       "n" will	be accepted as valid. If the user inputs an invalid value
       three times, an exception will be thrown. An exception will also	be
       thrown if there is no message or	if the optional	default	value does not
       begin with "y" or "n". As with "prompt()" an exception will be thrown
       if Sqitch is running unattended and there is no default.

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(3)

Name | Synopsis | Description | Interface | Author | License

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

home | help