/ 
Getopt-Helpful-0.04
River stage one • 2 direct dependents • 2 total dependents
/ Getopt::Helpful

NAME

Getopt::Helpful - Integrated option hash / help messages.

STATE

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.

SYNOPSIS

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...

AUTHOR

Eric L. Wilhelm <ewilhelm at cpan dot org>

http://scratchcomputing.com

COPYRIGHT

This module is copyright (C) 2004-2006 by Eric L. Wilhelm.

LICENSE

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)

Modifications

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.

SEE ALSO

Getopt::Long

Constructor

The helper object's values should be completely filled upon creation. The new() function accepts the following three types of arguments:

new

The constructor is (currently) the only interface to add contents to the $helper object.

Array references

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'],

Key => Value arguments

The key => value arguments let you specify values which control specific features.

usage

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]'

Builtins

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.)

Example

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
  );

DWIM

Do What I Mean methods.

Get

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);

Get_from

Equivalent to Get(@extra), but treats @args as a localized @ARGV.

$hopt->Get_from(\@args, @extra);

ordered

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');

Methods

opts

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";

help_table

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();

help_string

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');

Internal Methods

builtins

Returns a hash of builtin options.

%builtins = $helper->builtins();

usage

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.

CALLER

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>"
Specific Help

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.

juggle_list

Juggles an argument list to put help at the front (all arguments before -h or --help are removed.)

@list = $self->juggle_list(\@list, \%opts);

Functions

spec_parse

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);