Getopt::Helpful - Integrated option hash / help messages.
This module is still under development, but is being publish on CPAN to satisfy some code which depends on it. The interface may change in a future version and some of the functionality is not yet complete.
This module provides methods which integrate help messages into a Getopt::Long option spec. This gathers documentation and declaration into one place and allows you to utilize perl code to state the default values of options in your online help messages (helping you utilize the single-point-of-truth principle.)
Additionally, it provides DWIM methods (Get) which allow you to cut some standard error-checking code from your scripts. There is even a handy usage() method which eliminates that silly block of code from the beginning.
#!/usr/bin/perl use warnings; use strict; use Getopt::Helpful; my $var1 = "default"; my $req_arg; # declare this as 'our' or $main::verbose our $verbose = 0; # every option must be passed into the constructor... my $hopt = Getopt::Helpful->new( usage => 'CALLER <argument> [options]', [ 'var=s', \$default, '<setting>', "setting for \$var1 (default: '$var1')" ], [ 'a|arg', \$req_arg, '<argument>', 'required argument' ], '+verbose', '+help', ); # call GetOptions() behind the scenes (with error-checking) $hopt->Get(); $req_arg or ($req_arg = shift); # usage() called with a message results in non-zero exit code $req_arg or $hopt->usage('missing required argument'); $verbose and warn "doing stuff now\n"; # now do stuff...
Eric L. Wilhelm <ewilhelm at cpan dot org>
http://scratchcomputing.com
This module is copyright (C) 2004-2006 by Eric L. Wilhelm.
This module is distributed under the same terms as Perl. See the Perl source package for details.
You may use this software under one of the following licenses:
(1) GNU General Public License (found at http://www.gnu.org/copyleft/gpl.html) (2) Artistic License (found at http://www.perl.com/pub/language/misc/Artistic.html)
The source code of this module is made freely available and distributable under the GPL or Artistic License. Modifications to and use of this software must adhere to one of these licenses. Changes to the code should be noted as such and this notification (as well as the above copyright information) must remain intact on all copies of the code.
Additionally, while the author is actively developing this code, notification of any intended changes or extensions would be most helpful in avoiding repeated work for all parties involved. Please contact the author with any such development plans.
Getopt::Long
The helper object's values should be completely filled upon creation. The new() function accepts the following three types of arguments:
The constructor is (currently) the only interface to add contents to the $helper object.
This is the most generic form of option specification. The first two columns should be exactly the same as the hash that you would usually use to feed Getopt::Long. The second two columns are for printing helpful information.
# spec , ref , example , message [ 'a|argname=s', \$arg, '<argument>', 'a value for argument'],
The key => value arguments let you specify values which control specific features.
The 'usage' key will be used to create a customized usage message for the usage() function. The value may contain the string 'CALLER' which will be replaced with the value of $0. This is very helpful when you have a program that behaves differently under different names (such as when called through a symlink.) If you specify a usage message, you still need to request the '+help' builtin or include another option which will trigger the $helper->usage() call.
usage => 'CALLER inputfile outputfile [options]'
The following builtin options are available by using a '+<builtin>' string instead of an array reference in the constructor:
'+help' -> 'h|help' - calls main::usage() (also see usage()) '+verbose' -> 'v|verbose' - increments $main::verbose '+debug' -> 'd|debug' - increments $main::debug
If you are using strict, you will want to declare these variables as 'our $verbose' and 'our $debug' (or initialize them as $main::verbose, etc.)
our $debug = 0; my $helper = Getopt::Helpful->new( usage => 'CALLER <filename> [options]', ['choice=s', \$choice, '<choice>', 'your choice (default $choice)'], '+debug', # let's user toggle $main::debug '+help', # use a builtin );
Do What I Mean methods.
Calls GetOptions() with the options builtin to $helper (and optionally a list of other helpers or a hash of plain-old options.)
If GetOptions() returns false, we die (hinting at how to get help if '+help' was one of the options given to the constructor.)
$helper->Get(); # multiple helper objects: $helper->Get(@other_helpers); # mixed method (hash ref must come first) $helper->Get(\%opts, @other_helpers);
Equivalent to Get(@extra), but treats @args as a localized @ARGV.
$hopt->Get_from(\@args, @extra);
Not finished yet. The idea is to have one or more arguments that may be just an ordered list on the command line so that your program could be called as:
program infile outfile --option "these are options"
or
program -o outfile -i infile --option "these are options"
Still working on what this should look like, whether it should die if these things are unset, where it should set them (in the references?), how to set default values, etc...
$helper->ordered('first_option+r7qe', 'second_option');
Makes a hash of the first two columns of the table. Better to use Get() instead.
GetOptions( $helper->opts() ) or die "invalid arguments (-h for help)\n";
Returns a list of array refs of the first, third, and fourth columns of the table (e.g. you don't need the variable refs for this.)
my @table = $helper->help_table();
Returns join()ed string of the help table, with columnation and other fancy stuff (though it could stand to be a bit fancier.)
$helper->help_string();
If any arguments are passed, help will only be printed for the options which match those arguments.
$helper->help_string('foo', 'bar');
Returns a hash of builtin options.
%builtins = $helper->builtins();
If main::usage() is not declared, this method will be called instead (when the -h or --help flag is used.)
This is (currently) only able to leverage the values of one $helper (the one where '+help' was declared.)
# print to stdout and exit with 0 status: $helper->usage(); # print $message and minimal usage on stderr and exit with non-zero $helper->usage($message);
The usage message can be controlled by the usage => $string option of the new() constructor. If the usage string is empty, a default of "CALLER" is used. The following strings have special meaning in the usage string.
If the optional usage string contains the (case-sensitive) string "CALLER", this will be replaced by the calling program's ($0) basename (this is useful when you may want to change the name of a program or alias to it with symlinks.)
usage => "CALLER <filename>"
If there is anything in @main::ARGV which matches one of the options (less the leading dashes (or it would have already been stripped by GetOptions)), only the help for those options will be returned. What this does is allow your users to say something like:
program --help option-name
And get a compact help message for only that option.
Juggles an argument list to put help at the front (all arguments before -h or --help are removed.)
@list = $self->juggle_list(\@list, \%opts);
Parses the specification according to a minimalistic usage of Getopt::Long, returning an array of the variations and a type character (if the =s, =f, or =i items were found.)
($type, @variations) = spec_parse($spec);
To install Getopt::Helpful, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Getopt::Helpful
CPAN shell
perl -MCPAN -e shell install Getopt::Helpful
For more information on module installation, please visit the detailed CPAN module installation guide.