NAME

Getopt::LongUsage - Describe the usage of Getopt::Long options in human readable format

SYNOPSIS

Provide the description for Getopt::Long options in order to generate a descriptive usage for the user.

Example code:

use Getopt::Long;
use Getopt::LongUsage;

my ($width,$length,$verbose,$help);
my @getoptconf = (  'width=i'   => \$width,
                    'length=i'  => \$length,
                    'verbose|v' => \$verbose,
                    'help|h'    => \$help
                    );
my $usage = sub {
    my @getopt_long_configuration = @_;
    GetLongUsage (
        'cli_use'       => ($0 ." [options]"),
        'descriptions'  =>
            [   'width'         => "The width",
                'length'        => "The length",
                'verbose'       => "verbose",
                'help'          => "this help message"
                ],
        'Getopt_Long'   => \@getopt_long_configuration,
    );
};
GetOptions( @getoptconf ) || die ($usage->( @getoptconf ),"\n");
...etc...

Example output:

linux$ ./test_it.pl --not-an-option
Unknown option: not-an-option
./test_it.pl [options]
  --width        The width
  --length       The length
  -v, --verbose  verbose
  -h, --help     this help message

DESCRIPTION

This is a pure perl module which generates a user help message for a perl script that implements the Getopt::Long module. Simply describe each option configured for Getopt::Long, and a useful formatted help message is generated.

REQUIREMENTS

The following perl modules are depended on by this module:

Getopt::Long

IMPORTED METHODS

When the calling application invokes this module in a use clause, the following method will be imported into its space.

GetLongUsage

METHODS

new

Create a new object instances of this module. It is not necessary to create an object for this module, as the methods can be called outside of OO style programming.

returns

An object instance of this module.

my $glu = new Getopt::LongUsage();

ParseGetoptLongConfig

Parse option configuration for Getopt::Long. This is also known as the "Spec parser" for <Getopt::Long>.

This method reproduces just enough code as found in Getopt::Long::GetOptionsFromArray(), while also calling functions in that module, so to parse the same exact Getopt::Long configuration input.

Unlike other <Getopt::Long> "Spec parsers", this function parses the argument configuration in the exact same procedure as <Getopt::Long>.

my $configmap = ParseGetoptLongConfig (
                    \%options,
                    'isAvailable',
                    'color=s',
                    'type=s',
                    'cityGrown=s@',
                    'secretAttr=i',
                    'verbose|v',
                    'help|h'
                );

my @getoptconf = (
                  	'isAvailable'  => \$isAvailable,
                    'color=s'      => \$color,
                    'type=s'       => \$type,
                    'cityGrown=s@' => \@cityGrown,
                    'secretAttr:i' => \$secretAttr,
                    'verbose|v'    => \$verbose,
                    'help|h'       => \$help
                    );
my $configmap = ParseGetoptLongConfig ( @getoptconf );

Resulting Config Map documentation, extracted from Getopt::Long

The Getopt::Long::ParseGetoptLongConfig is a function utilizing code copied right out of Getopt::Long to ensure complete compatibility. The author of this Getopt::LongUsage module has communicated with the author of the Getopt::Long module about this action.

The following documentation is assembled based on definitions and code found inside the Getopt::Long source code.

A look at the resulting output from Getopt::LongUsage::ParseGetoptLongConfig

Perl Code

use Getopt::Long;
use Getopt::LongUsage;
use Data::Dumper;
my $configmap = Getopt::LongUsage::ParseGetoptLongConfig (
                    \%options,
                    'inti_opt=i',
                    'stri_opt:s',
                    'flag_opt|f'
                );
print Dumper ( $configmap );

Output

$VAR1 = {
      'inti_opt' => [
                      'i',
                      'inti_opt',
                      undef,
                      0,
                      1,
                      1
                    ],
      'flag_opt' => [
                      '',
                      'flag_opt',
                      undef,
                      0,
                      0,
                      0
                    ],
      'stri_opt' => [
                      's',
                      'stri_opt',
                      undef,
                      0,
                      0,
                      1
                    ],
      'f' => $VAR1->{'flag_opt'}
    };

Description and definition from Getopt::Long, in short form

# Hash_Key => [Config_Vals] # Array_Index - NAME :possible values (or) -definition
'stri_opt' => [
                's',        # 0 - CTL_TYPE    : ''=FLAG,!=NEG,+=INCR,i=INT,I=INTINC,o=XINT,f=FLOAT,s=STRING
                'stri_opt', # 1 - CTL_CNAME   - The name of the option
                undef,      # 2 - CTL_DEFAULT - The default value of the option
                0,          # 3 - CTL_DEST    : 0=SCALAR, 1=ARRAY, 2=HASH, 3=CODE
                1,          # 4 - CTL_AMIN    - Minimum expected values
                1           # 5 - CTL_AMAX    - Maximum allowed values (-1 == unlimited)
              ],

GetLongUsage

Generate a usage message from Getopt::Long options.

header

This is a text string to be used as a header of the usage output. It will appear at the top of the usage output.
footer

This is a text string to be used as a footer of the usage output. It will appear at the bottom of the usage output.
cli_use

This is a string representing the format for executing your application.
descriptions

This is an array reference of options with descriptions. The order of the options provided to the descriptions parameter dictates the presentation order. The format is as follows:
```
my $descriptions = [ 'opt1' => 'desc1', 'opt2' => 'desc2', etc... ]
```
The options should be one that is found in the Getopt::Long configuration passed to the Getopt_Long parameter. If the configuration consists of both long and short options, you should only provide one of them. The description is associated with all related options as configured for Getopt::Long.

So for example, if the following is your Getopt::Long configuration:
```
GetOptions( %options, 'help|h', 'opt1|o')
```
Then the following two descriptions configurations would be valid:
```
$descriptions = [   'h' => "This help message",
                    'o' => "The first option"   ]

$descriptions = [   'help' => "This help message",
                    'opt1' => "The first option"   ]
```
It does not matter if you use either the long or short form of the options, as it is only used in this parameter for the purpose of associating the given description with a relation of options in the Getopt::Long configuration.
format

Formatting options are set in subparameters within this parameter.
- tab
  
  The number of spaces that comprise a tab in the formatted output. The default is 2 spaces for each tab.
- indent
  
  The number of spaces to indent the formatted output. The default is 0 spaces.
- longprefix
  
  The prefix that defines long options. The default is --, as in --help.
- shortprefix
  
  The prefix that defines short options. The default is -, as in -h.
hidden_opts

This is an array reference list of Getopt::Long options that will be hidden from the formatted usage message intended for human reading.
Getopt_Long

The array reference list of a Getopt::Long configuration which is a definition of the expected Getopt::Long::GetOptions() input option.

GetLongUsage (  header          => "This is my header text",
                footer          => "This is my footer text"
                cli_use         => "myprog [options] arg1 arg2",
                descriptions    => \@descriptions,
                format          => \@format_options,
                hidden_opts     => \@hidden_options,
                Getopt_Long     => \@getopt_long_options
                );

EXAMPLES

Actually, the descriptions are not needed either

Example code:

use Getopt::Long;
use Getopt::LongUsage;

my %options;
my @getoptconf = (  \%options,
                    'isAvailable',
                    'color=s',
                    'type=s',
                    'cityGrown=s@',
                    'verbose|v',
                    'help|h'
                    );
my $usage = sub {
    my @getopt_long_configuration = @_;
    GetLongUsage (
        'Getopt_Long'   => \@getopt_long_configuration,
    );
};
GetOptions( @getoptconf ) || die ($usage->( @getoptconf ),"\n");
...etc...

Example output:

linux$ perl test.pl --notanoption
Unknown option: notanoption
  -v, --verbose  
  --isAvailable  
  --color        
  -h, --help     
  --type         
  --cityGrown

Using more formatting options

Example code:

use Getopt::Long;
use Getopt::LongUsage;

my $VERSION = "2.1.5";
my %options;
my @getoptconf = (  \%options,
                    'isAvailable',
                    'color=s',
                    'type=s',
                    'cityGrown=s@',
                    'secretAttr:i',
                    'verbose|v',
                    'help|h'
                    );
my $usage = sub {
    my @getopt_long_configuration = @_;
    GetLongUsage (
        'header'        => ("MyApple Program version ".$VERSION."\n".'Author Smith <author@example.com>'."\n"),
        'cli_use'       => ($0 ."[options] <args>"),
        'descriptions'  =>
            [   'isAvailable'   => "The apple type is available",
                'color'         => "The color of this apple type",
                'type'          => "The type of apple, i.e. \"Gala\"",
                'cityGrown'     => "The city(s) in which this apple is grown",
                'secretAttr'    => "You should not see this option",
                'verbose'       => "verbose",
                'help'          => "help"
                ],
        'hidden_opts    => [qw(secretAttr)]
        'footer'        => undef,
        'format'        =>
            [   'tab'       => 4,
                'indent'    => 0
                ],
        'Getopt_Long'   => \@getopt_long_configuration,
    );
};
GetOptions( @getoptconf ) || die ($usage->( @getoptconf ),"\n");
...etc...

Example output:

MyApple Program version 2.1.5
Author Smith <author@example.com>

script.pl [options] <args>
    --isAvailable    The apple type is available
    --color          The color of this apple type
    --type           The type of apple, i.e. "Gala"
    --cityGrown      The city(s) in which this apple is grown
    -v, --verbose    verbose
    -h, --help       help

Combining Getopt::XML with Getopt::LongUsage

Considering the following XML File '/path/to/xml_file.xml' and content:

<apple>
    <color>red</color>
    <type>red delicious</type>
    <isAvailable/>
    <cityGrown>Macomb</cityGrown>
    <cityGrown>Peoria</cityGrown>
    <cityGrown>Galesburg</cityGrown>
</apple>

Using that XML file as input for default values:

use Getopt::Long;
use Getopt::LongUsage;
use Getopt::XML qw(GetXMLOptionsFromFile);
use Data::Dump qw(pp);
#
# Set the Getopt::Long Configuration
my @GetoptLongConfig = (
                            \%options,
                            'isAvailable',
                            'color=s',
                            'type=s',
                            'cityGrown=s@'
                        );
#
# Read the XML data in as arguments to Getopt::Long
my %options;
GetXMLOptionsFromFile (
        xmlfile     => '/path/to/xml_file.xml',
        xmlpath     => '/apple',
        Getopt_Long => \@GetoptLongConfig
);
print "==My Default Values==\n";
pp(\%options);
#
# Setup the user's help message for Getopt::Long
my $usage = sub {
    my @getopt_long_configuration = @_;
    GetLongUsage (
        'header'        => ("MyApple Program version ".$VERSION."\n".'Author Smith <author@example.com>'."\n"),
        'cli_use'       => ($0 ." [options] <args>"),
        'descriptions'  =>
            [   'isAvailable'   => "The apple type is available",
                'color'         => "The color of this apple type",
                'type'          => "The type of apple, i.e. \"Gala\"",
                'cityGrown'     => "The city(s) in which this apple is grown"
                ],
        'footer'        => "\n",
        'format'        =>
            [   'tab'       => 2,
                'indent'    => 2
                ],
        'Getopt_Long'   => \@getopt_long_configuration,
    );
};
#
# Finally retrieve and absorb the user provided input via Getopt::Long
GetOptions( @GetoptLongConfig ) || die ($usage->( @GetoptLongConfig ));
print "==My Runtime Values==\n";
pp(\%options);

Example output when providing an invalid option

linux$ perl test.pl --notanoption
==My Default Values==
{
  cityGrown => ["Macomb", "Peoria", "Galesburg"],
  color => "red",
  isAvailable => 1,
  type => "red delicious",
}
Unknown option: notanoption
  MyApple Program version 
  Author Smith <author@example.com>
  
  test.pl [options] <args>
    --isAvailable  The apple type is available
    --color        The color of this apple type
    --type         The type of apple, i.e. "Gala"
    --cityGrown    The city(s) in which this apple is grown

Example output when providing a valid option

linux$ perl test.pl --color="blue" --type="blue delicious"
==My Default Values==
{
  cityGrown => ["Macomb", "Peoria", "Galesburg"],
  color => "red",
  isAvailable => 1,
  type => "red delicious",
}
==My Runtime Values==
{
  cityGrown => ["Macomb", "Peoria", "Galesburg"],
  color => "blue",
  isAvailable => 1,
  type => "blue delicious",
}

TODO

1 Support the definition of the column width in the usage message output

By defining a format subparameter called cols in GetLongUsage(), one can define how wide (how many columns) the usage message output should be constrained within. In conforming to a maximum column size, the options sub-column and option description sub-column will be adjusted to fit that width in the following ways:

1. The options sub-column may be formatted such that particularly long rows of this sub-column will be on a line of its own, and its associated description will begin on the next line - though in the description sub-column

2. The option description sub-column may be formatted such that descriptions which span beyond the sub-column width will be wrapped to the next line.

--thisisaverylongoption
                    The descriotion has to start on the next line because the
                    option is too long. Also this description wraps around
                    because it is also too long.
-a, --another, --param2
                    This is also true for options like this one.
-h, --help, -?      This option and description fits.

1 Display the input type for each option in the usage message output

Currently the usage message only displays the options and relation option aliases for each option. The required input format is not provided. So by only looking at the options in the usage message output, a user does not know if the option is a boolean flag, requires a string text as input, or requires a number as input.

The ParseGetopLongConfig() method already returns a map of the option configuration which describes the expected input (as boolean flag, string, or integer). The GetLongUsage() method need only utilize that available data when formatting the usage message.

A flag may be provided to allow the caller to turn this off or on, and maybe even possibly format what it looks like. I am considering something like the following as default, which just mimics the Getopt::Long configuration style:

--booleanflag
--number=i
--yourname=s

1 Support for optionally displaying aliases on their own line

Currently the aliases and their main parameters are displayed on the same line. However, it may be desired to have them on a separated line, and reference the main parameter.

So instead of:

-h, -?, --help        This help message
-v, --verbose, --ver  Turn on verbose messaging

It would be:

-h, -?, --help  This help message
-v, --verbose   Turn on verbose messaging
--ver           Alias for --verbose

AUTHOR

Russell E Glaue, http://russ.glaue.org

COPYRIGHT AND LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

To install Getopt::LongUsage, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Getopt::LongUsage

CPAN shell

perl -MCPAN -e shell
install Getopt::LongUsage

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

REQUIREMENTS

IMPORTED METHODS

METHODS

new

ParseGetoptLongConfig

Resulting Config Map documentation, extracted from Getopt::Long

GetLongUsage

EXAMPLES

Actually, the descriptions are not needed either

Using more formatting options

Combining Getopt::XML with Getopt::LongUsage

TODO

AUTHOR

SEE ALSO

COPYRIGHT AND LICENSE

Module Install Instructions