File Coverage

blib/lib/App/Cmd/Command/help.pm

Criterion	Covered	Total	%
statement	22	25	88.0
branch	3	4	75.0
condition			n/a
subroutine	7	7	100.0
pod	3	3	100.0
total	35	39	89.7

use strict;
use warnings;

package App::Cmd::Command::help 0.336;

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

# ABSTRACT: display a command's help screen

#pod =head1 DESCRIPTION
#pod
#pod This command will either list all of the application commands and their
#pod abstracts, or display the usage screen for a subcommand with its
#pod description.
#pod
#pod =head1 USAGE
#pod
#pod The help text is generated from three sources:
#pod
#pod =for :list
#pod * The C method
#pod * The C method
#pod * The C data structure
#pod
#pod The C method provides the opening usage line, following the
#pod specification described in L.  In some cases,
#pod the default C in L may be sufficient and
#pod you will only need to override it to provide additional command line
#pod usage information.
#pod
#pod The C data structure is used with L
#pod to generate the description of the options.
#pod
#pod Subcommand classes should override the C method to provide
#pod additional information that is prepended before the option descriptions.
#pod
#pod For example, consider the following subcommand module:
#pod
#pod   package YourApp::Command::initialize;
#pod
#pod   # This is the default from App::Cmd::Command
#pod   sub usage_desc {
#pod     my ($self) = @_;
#pod     my $desc = $self->SUPER::usage_desc; # "%c COMMAND %o"
#pod     return "$desc [DIRECTORY]";
#pod   }
#pod
#pod   sub description {
#pod     return "The initialize command prepares the application...";
#pod   }
#pod
#pod   sub opt_spec {
#pod     return (
#pod       [ "skip-refs|R",  "skip reference checks during init", ],
#pod       [ "values|v=s@",  "starting values", { default => [ 0, 1, 3 ] } ],
#pod     );
#pod   }
#pod
#pod   ...
#pod
#pod That module would generate help output like this:
#pod
#pod   $ yourapp help initialize
#pod   yourapp initialize [-Rv] [long options...] [DIRECTORY]
#pod
#pod   The initialize command prepares the application...
#pod
#pod         --help            This usage screen
#pod         -R --skip-refs    skip reference checks during init
#pod         -v --values       starting values
#pod
#pod =cut

sub usage_desc { '%c help [subcommand]' }

sub command_names { qw/help --help -h -?/ }

sub execute {
  my ($self, $opts, $args) = @_;

  if (!@$args) {
    print $self->app->usage->text . "\n";

    print "Available commands:\n\n";

    $self->app->execute_command( $self->app->_prepare_command("commands") );
  } else {
    my ($cmd, $opt, $args) = $self->app->prepare_command(@$args);

    local $@;
    my $desc = $cmd->description;
    $desc = "\n$desc" if length $desc;

    my $ut = join "\n",
      eval { $cmd->usage->leader_text },
      $desc,
      eval { $cmd->usage->option_text };

    print "$ut\n";
  }
}

1;

__END__