NAME

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

VERSION

version 0.051003

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 parameter to dump raw POD text.

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