App::Sqitch::Command - Sqitch Command support
my $cmd = App::Sqitch::Command->load( deploy => \%params ); $cmd->run;
App::Sqitch::Command is the base class for all Sqitch commands.
options
my @spec = App::Sqitch::Command->options;
Returns a list of Getopt::Long options specifications. When load loads the class, any options passed to the command will be parsed using these values. The keys in the resulting hash will be the first part of each option. This hash will be passed to configure along with a App::Sqitch::Config object for munging into parameters to be passed to the constructor.
load
configure
Here's an example excerpted from the config command:
config
sub options { return qw( get unset list global system config-file=s ); }
This will result in hash keys with the same names as each option except for config-file=s, which will be named config_file.
config-file=s
config_file
my $params = App::Sqitch::Command->configure($config, $options);
Takes two arguments, an App::Sqitch::Config object and the hash of command-line options as specified by options. The returned hash should be the result of munging these two objects into a hash reference of parameters to be passed to the command subclass constructor.
By default, this method converts dashes to underscores in command-line options keys, and then merges the configuration values with the options, with the command-line options taking priority. You may wish to override this method to do something different.
my $cmd = App::Sqitch::Command->load( \%params );
A factory method for instantiating Sqitch commands. It loads the subclass for the specified command, uses the options returned by options to parse command-line options, calls configure to merge configuration with the options, and finally calls new with the resulting hash. Supported parameters are:
new
sqitch
The App::Sqitch object driving the whole thing.
An App::Sqitch::Config representing the current application configuration state.
command
The name of the command to be executed.
args
An array reference of command-line arguments passed to the command.
my $cmd = App::Sqitch::Command->new(%params);
Instantiates and returns a App::Sqitch::Command object. This method is not designed to be overridden by subclasses; they should implement BUILDARGS or BUILD, instead.
BUILDARGS
BUILD
my $sqitch = $cmd->sqitch;
Returns the App::Sqitch object that instantiated the command. Commands may access its properties in order to manage global state.
These methods should be overridden by all subclasses.
execute
$cmd->execute;
Executes the command. This is the method that does the work of the command. Must be overridden in all subclasses. Dies if the method is not overridden for the object on which it is called, or if it is called against a base App::Sqitch::Command object.
my $command = $cmd->command;
The name of the command. Defaults to the last part of the package name, so as a rule you should not need to override it, since it is that string that Sqitch uses to find the command class.
These methods are mainly provided as utilities for the command subclasses to use.
do_system
if !($cmd->do_system('echo hello')) { $cmd->fail('Ooops'); }
Executes a system command and waits for it to finish. Returns true if the command returned without error, and false if it did not.
verbosity
my $verbosity = $cmd->verbosity;
Returns the verbosity level.
trace
$cmd->trace('About to fuzzle the wuzzle.');
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.
STDOUT
TRACE:
debug
$cmd->debug('Found snuggle in the crib.');
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:
info
$cmd->info('Nothing to deploy (up-to-date)');
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.
comment
$cmd->comment('On database flipr_test');
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.
#
emit
$cmd->emit('core.editor=emacs');
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.
sqitch config --get core.editor
warn
$cmd->warn('Could not find nerble; using nobble instead.');
Send a warning messages to STDERR. Use if something unexpected happened but you can recover from it.
STDERR
unfound
$cmd->unfound;
Exit the program with status code 1. Best for use for non-fatal errors, such as when something requested was not found.
fail
$cmd->fail('File or directory "foo" not found.');
Send a failure message to STDERR and exit with status code 2. Use if something unexpected happened and you cannot recover from it.
usage
$cmd->usage('Missing "value" argument');
Sends the specified message to STDERR, followed by the usage sections of the command's documentation. Those sections may be named "Name", "Synopsis", or "Options". Any or all of those will be shown.
help
$cmd->help('"foo" is not a valid command.');
Sends messages to STDERR and exists with an additional message to "See sqitch --help". Use if the user has misused the app.
bail
$cmd->bail(3, 'The config file is invalid');
Exits with the specified error code, sending any specified messages to STDOUT if the exit code is 0, and to STDERR if it is not 0.
The Sqitch command-line client.
David E. Wheeler <david@justatheory.com>
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.
To install App::Sqitch, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::Sqitch
CPAN shell
perl -MCPAN -e shell install App::Sqitch
For more information on module installation, please visit the detailed CPAN module installation guide.