App::Sqitch::Command(3)

Name
App::Sqitch::Command - Sqitch Command support

Synopsis
  my $cmd = App::Sqitch::Command->load( deploy => \%params );
  $cmd->run;

Description
App::Sqitch::Command is the base class for all Sqitch commands.

Interface

  Class Methods
"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, with dashes converted to underscores. This hash will be passed to "configure" along with a App::Sqitch::Config object for munging into parameters to be passed to the constructor.

Here's an example excerpted from the "config" command:

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

"configure"

  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.

  Constructors
"load"

  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:

"sqitch"
    The App::Sqitch object driving the whole thing.

"config"
    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.

"new"

  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.

  Accessors
"sqitch"

  my $sqitch = $cmd->sqitch;

Returns the App::Sqitch object that instantiated the command. Commands may access its properties in order to manage global state.

  Overridable Instance Methods
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.

"command"

  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.

  Utility Instance Methods
These methods are mainly provided as utilities for the command subclasses to use.

"default_target"

  my $target = $cmd->default_target;

This method returns the default target. It should only be used by commands that don't use a "parse_args()" to find and load a target.

This method should always return a target option, never "undef". If the "--engine" option or "core.engine" configuration option has been set, then the target will support that engine. In the latter case, if "engine.$engine.target" is set, that value will be used. Otherwise, the returned target will have a URI of "db:" and no associated engine; the "engine" method will throw an exception. This behavior should be fine for commands that don't need to load the engine.

"parse_args"

  my %parsed_args = $cmd->parse_args(target => $target_name, args => \@args);

Examines each argument to determine whether it's a known change spec or target. Returns a list of two-value array references, one for each argument passed. For each array reference, the first item is the argument type, either "change", "target", or "unknown", and the second item is the original value. Useful for commands that take a number of parameters where the order may be mixed.

If a target parameter is passed, it will always be instantiated and returned under the "target" key, and arguments recognized as changes in the plan associated with that target will be returned as changes.

If a target name is specified in the arguments, it will be instantiated and returned under the "target" key and any subsequent changes must be recognized from its plan.

If no target is passed or appears in the arguments, a default target will be instantiated based on the command-line options and configuration. Unlike the target returned by "default_target", however, it must have an associated engine specified by the "--engine" option or configuration. This is on the assumption that it will be used by commands that require an engine to do their work. Of course, any changes must be recognized from the plan associated with this target.

"run"

  $cmd->run('echo hello');

Runs a system command and waits for it to finish. Throws an exception on error.

"capture"

  my @files = $cmd->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 = $cmd->capture(qw(git --version));

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

"verbosity"

  my $verbosity = $cmd->verbosity;

Returns the verbosity level.

"trace"

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.

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

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

"vent"

  $cmd->vent('That was a misage.');

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.

"page"

  $sqitch->page('Search results:');

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". 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->() ) {
      $cmd->page(join ' - ', @{ $change }{ qw(change_id event change) });
  }

"warn"

  $cmd->warn('Could not find nerble; using nobble instead.');

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.

"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 these will be shown. The doc used to display them will be the first found of:

"sqitch-$command-usage"
"sqitch-$command"
"sqitch"
"App::Sqitch::Command::$command"
"App::Sqitch::Command"

For an ideal usage messages, "sqitch-$command-usage.pod" should be created by all command subclasses.

See Also

sqitch
    The Sqitch command-line client.

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

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