NAME

Term::CLI::Role::HelpText - Role for generating help text in Term::CLI

VERSION

version 0.04006

SYNOPSIS

 package Term::CLI::Command {

    use Moo;

    with('Term::CLI::Role::HelpText');

    ...
 };

 my $cmd = Term::CLI::Command->new(
    name => 'file',
    options => ['verbose|v'],
    arguments => [
        Term::CLI::Argument::Filename->new(name => 'path'),
    ],
    commands => [
        Term::CLI::Command->new(name => 'info'),
        Term::CLI::Command->new(name => 'delete'),
        Term::CLI::Command->new(name => 'show'),
    ],
 );

 say $cmd->usage_text();
 # -> file [--verbose] [-v] path {info|delete|show}

 say $cmd->usage_text( with_options => 'long' );
 # -> file [--verbose] path {info|delete|show}

 say $cmd->usage_text( with_options => 'none');
 # -> file path {info|delete|show}

 say $cmd->usage_text( with_arguments => 0);
 # -> file [--verbose] [-v] {info|delete|show}

 say $cmd->usage_text( with_subcommands => 0);
 # -> file [--verbose] [-v] path

DESCRIPTION

Role for Term::CLI::Command(3p) elements that need to have help text.

This role is consumed by Term::CLI::Command(3p).

The functionality of this role is primarily used by Term::CLI::Command::Help(3p).

ATTRIBUTES

This role defines three additional attributes:

description => Str

Fragment of POD text that describes the command in some detail. It is typically shown when help is requested for specifically this command.

Default is undef, which typically means that the summary attribute is used in its place.

summary => Str

Short summary of the command (e.g. what you typically find in the NAME section of a manual page), that is typically displayed in a command summary.

Default is an empty string.

usage => Str

Optional attribute that should contain a single line of POD documentation to describe the syntax of the command.

Default is undef, which causes usage_text to automatically generate a usage line.

NOTE: if this is specified, the usage_text method will always return this value.

ACCESSORS

description ( [ Str ] )

Get or set the description help text.

summary ( [ Str ] )

Get or set the summary help text.

usage ( [ Str ] )

Get or set the static usage text.

METHODS

get_options_summary ( [ with_options => VAL )

Return a line of POD text for the command line options for this command, depending on the value of the with_options parameter.

This function is called by usage_text. You'll probably never need to call it directly.

usage_text ( OPT => VAL, ... )

Return a line of POD text with a usage summary for the command.

If the usage attribute has been set, then this value is always returned. Otherwise, the method will construct a POD fragment from the command's name, options, arguments, and sub-commands.

The following parameters are recognised:

with_options => {long|short|both|none}

Specify which command options to include in the usage text. Options are long to only include long options (e.g. [--verbose]), short to only include short options (e.g. [-v]), both for both short and long options (e.g. [--verbose] [-v]), or none for none.

Default is both.

with_arguments => {0|1}

Specify whether or not to include placeholders for command line arguments in the usage line.

Default is 1.

with_subcommands => {0|1}

Specify whether or not to include the list of sub-commands in the usage line.

Default is 1.

SEE ALSO

Term::CLI(3p), Term::CLI::Command::Help(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.