view release on metacpan or  search on metacpan

lib/App/Cmd/Command.pm  view on Meta::CPAN

use strict;
use warnings;

package App::Cmd::Command 0.336;

use App::Cmd::ArgProcessor;
BEGIN { our @ISA = 'App::Cmd::ArgProcessor' };

# ABSTRACT: a base class for App::Cmd commands

use Carp ();

#pod =method prepare
#pod
#pod   my ($cmd, $opt, $args) = $class->prepare($app, @args);
#pod
#pod This method is the primary way in which App::Cmd::Command objects are built.
#pod Given the remaining command line arguments meant for the command, it returns
#pod the Command object, parsed options (as a hashref), and remaining arguments (as
#pod an arrayref).
#pod
#pod In the usage above, C<$app> is the App::Cmd object that is invoking the
#pod command.
#pod
#pod =cut

sub prepare {
  my ($class, $app, @args) = @_;

  my ($opt, $args, %fields)
    = $class->_process_args(\@args, $class->_option_processing_params($app));

  return (
    $class->new({ app => $app, %fields }),
    $opt,
    @$args,
  );
}

sub _option_processing_params {
  my ($class, @args) = @_;

  return (
    $class->usage_desc(@args),
    $class->opt_spec(@args),
  );
}

#pod =method new
#pod
#pod This returns a new instance of the command plugin.  Probably only C<prepare>
#pod should use this.
#pod
#pod =cut

sub new {
  my ($class, $arg) = @_;
  bless $arg => $class;
}

#pod =method execute
#pod
#pod   $command_plugin->execute(\%opt, \@args);
#pod
#pod This method does whatever it is the command should do!  It is passed a hash
#pod reference of the parsed command-line options and an array reference of left
#pod over arguments.
#pod
#pod If no C<execute> method is defined, it will try to call C<run> -- but it will
#pod warn about this behavior during testing, to remind you to fix the method name!
#pod
#pod =cut

sub execute {
  my $class = shift;

  if (my $run = $class->can('run')) {
    warn "App::Cmd::Command subclasses should implement ->execute not ->run"
      if $ENV{HARNESS_ACTIVE};

    return $class->$run(@_);
  }

  Carp::croak ref($class) . " does not implement mandatory method 'execute'\n";
}

#pod =method app
#pod
#pod This method returns the App::Cmd object into which this command is plugged.
#pod
#pod =cut

sub app { $_[0]->{app}; }

#pod =method usage
#pod
#pod This method returns the usage object for this command.  (See
#pod L<Getopt::Long::Descriptive>).
#pod
#pod =cut

sub usage { $_[0]->{usage}; }

#pod =method command_names
#pod
#pod This method returns a list of command names handled by this plugin. The
#pod first item returned is the 'canonical' name of the command.
#pod
#pod If this method is not overridden by an App::Cmd::Command subclass, it will
#pod return the last part of the plugin's package name, converted to lowercase.
#pod For example, YourApp::Cmd::Command::Init will, by default, handle the command
#pod "init".
#pod
#pod Subclasses should generally get the superclass value of C<command_names>
#pod and then append aliases.
#pod
#pod =cut