NAME

Term::CLI::Command::Help - A generic 'help' command for Term::CLI

VERSION

version 0.055001

SYNOPSIS

use Term::CLI;

my $cli = Term::CLI->new(
   name => 'myapp',
   prompt => 'myapp> ',
   commands => [
       Term::CLI::Command::Help->new(),
       Term::CLI::Command->new( name => 'copy', ... ),
       Term::CLI::Command->new( name => 'move', ... ),
   ],
);

$cli->execute('help');
# -> command summary

say "\n----\n";

$cli->execute('help copy');
# -> detailed help on 'copy'.

(See EXAMPLE for a working example.)

DESCRIPTION

The Term::CLI::Command::Help class is derived from Term::CLI::Command(3p) and implements a generic "help" command for Term::CLI(3p) applications.

The help command accepts arguments that it will try to match against the commands of its Term::CLI(3p) parent.

It supports completion, as well as a --pod option to dump raw POD text, and a --all option to show a command summary followed by extended help on each commands.

CONSTRUCTORS

new

Create a new Term::CLI::Command::Help object and return a reference to it.

The object provides appropriate default values for all attributes, so there is no need to provide any.

If you want, you can override the default attributes; in that case, see the Term::CLI::Command(3p) documentation. Attributes that are "safe" to override are:

description => Str

Override the default description for the help command.

name => Str

Override the name for the help command. Default is help.

pager => ArrayRef[Str]

Override the default pager for help display. See OUTPUT PAGING. The value should be a command line split on words, e.g.:

OBJ->pager( [ 'cat', '-n', '-e' ] );

If an empty list is provided, no external pager will be used, and output is printed to STDOUT directly.

See also the pager method.

summary =>

Override the default summary for the help command.

usage =>

Override the automatic usage string for the help command.

METHODS

pager ( [ ArrayRef[Str]> ] )

Get or set the pager command. If an empty list is provided, no external pager will be used, and output is printed to STDOUT directly.

Example:

$help_cmd->pager([]); # Print directly to STDOUT.
$help_cmd->pager([ 'cat', '-n' ]); # Number output lines.

OUTPUT FORMATTING

Help text is assumed to be in POD format, and will be formatted for the terminal using Pod::Text::Termcap(3p).

OUTPUT PAGING

The help command will try to pipe the formatted output through a suitable pager.

At startup, the pager is selected from the following list, in order of preference: less, more, pg, STDOUT.

This can be overridden by supplying a value to the object's pager attribute.

EXAMPLE

Using the following code:

use Term::CLI;

my $cli = Term::CLI->new(
    name => 'myapp',
    prompt => 'myapp> ',
    commands => [
        Term::CLI::Command::Help->new(),

        Term::CLI::Command->new(
            name => 'copy',
            options => [ 'verbose!' ],
            summary => 'copy I<src> to I<dst>',
            description =>
                qq{Copy I<src> to I<dst>.\n}
                .qq{Show progress if C<--verbose> is given.},
            arguments => [
                Term::CLI::Argument::Filename->new(name => 'src'),
                Term::CLI::Argument::Filename->new(name => 'dst'),
            ],
        ),
        Term::CLI::Command->new(
            name => 'move',
            options => [ 'verbose!' ],
            summary => 'move I<src> to I<dst>',
            description =>
                qq{Move I<src> to I<dst>.\n}
                .qq{Move progress if C<--verbose> is given.},
            arguments => [
                Term::CLI::Argument::Filename->new(name => 'src'),
                Term::CLI::Argument::Filename->new(name => 'dst'),
            ],
        )
    ],
);

say "\n----\n";

$cli->execute('help');
# -> command summary

say "\n----\n";

$cli->execute('help copy');
# -> detailed help on 'copy'.

The output would look something like this:

----

  Commands:
    help [cmd ...]                      Show help.
    copy src dst                        copy src to dst
    move src dst                        move src to dst

----

  Usage:
    copy [--verbose] src dst

  Description:
    Copy src to dst. Show progress if "--verbose" is given.

----

SEE ALSO

cat(1), less(1), more(1), perlpod(1), pg(1), Pod::Text::Termcap(3p). Term::CLI(3p), Term::CLI::Command(3p).

AUTHOR

Steven Bakker <sbakker@cpan.org>, 2018.

COPYRIGHT AND LICENSE

Copyright (c) 2018 Steven Bakker

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See "perldoc perlartistic."

This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

cpanm Term::CLI

perl -MCPAN -e shell
install Term::CLI