NAME

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

VERSION

version 0.059000

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.

summary =>

Override the default summary for the help command.

usage =>

Override the automatic usage string for the help command.

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 use the parent Term::CLI(3p)'s write_pager() method to pipe the formatted output through a suitable pager.

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.