NAME

Getopt::Long::Descriptive - Getopt::Long with usage text

VERSION

 0.06

DESCRIPTION

Convenient wrapper for Getopt::Long and program usage output

SYNOPSIS

  use Getopt::Long::Descriptive;
  my ($opts, $usage) = describe_options($format, @opts, \%arg);

FORMAT

  $format = "usage: myprog %o myarg...";

%o will be replaced with a list of the short options, as well as the text "[long options...]" if any have been defined.

%c will be replaced with what Getopt::Long::Descriptive thinks is the program name (see "prog_name"). You can override this guess by calling prog_name($string) yourself.

Because of this, any literal % symbols will need to be written as %%.

OPTIONS

Option specifications are the same as in Getopt::Long. You should pass in an array of arrayrefs whose first elements are option specs and whose second elements are descriptions.

  my @opts = (
    [ "verbose|V" => "be noisy"       ],
    [ "logfile=s" => "file to log to" ],
  );

Option specifications may have a third hashref argument. If present, this configures extra restrictions on the value or presence of that option.

You may cause a blank line to be printed by passing an empty arrayref. Likewise, a plain descriptive line will be printed if you pass an arrayref with a single element:

  @opts = (
    $option,
    [],
    [ 'other options:' ],
    $other_option,
  );

Option Constraints

implies

  implies => 'bar'

  implies => [qw(foo bar)]

  implies => { foo => 1, bar => 2 }

required

  required => 1

hidden

  hidden => 1

This option will not show up in the usage text.

You can achieve this same behavior by using the string hidden for the option's description.

one_of

  one_of => \@option_specs

Useful for a group of options that are related. Each option spec is added to the list for normal parsing and validation.

Your option name will end up with a value of the name of the option that was chosen. For example, given the following spec:

  [ "mode" => hidden => { one_of => [
    [ "get|g"  => "get the value" ],
    [ "set|s"  => "set the value" ],
    [ "delete" => "delete it" ],
  ] } ],

No usage text for 'mode' will be displayed, though get/set/delete will all have descriptions.

If more than one of get/set/delete (or their short versions) are given, an error will be thrown.

If @ARGV is --get, a dump of the resultant option hashref would look like this:

  { get  => 1,
    mode => 'get' }

NOTE: get would not be set if mode defaulted to 'get' and no arguments were passed in.

WARNING: Even though the option sub-specs for one_of are meant to be 'first class' specs, some options don't make sense with them, e.g. required.

As a further shorthand, you may specify one_of options using this form:

  [ mode => \@option_specs, \%constraints ]

Params::Validate

In addition, any constraint understood by Params::Validate may be used.

(Internally, all constraints are translated into Params::Validate options or callbacks.)

EXTRA ARGUMENTS

If the last parameter is a hashref, it contains extra arguments to modify the way describe_options works. Valid arguments are:

  getopt_conf - an arrayref of strings, passed to Getopt::Long::Configure

EXPORTED FUNCTIONS

describe_options

See SYNOPSIS; returns a hashref of option values and an object that represents the usage statement.

The usage statement has several methods:

• $usage->text returns the usage string

• $usage->warn prints usage to STDERR

• $usage->die dies with the usage string

prog_name

A helper function that returns the basename of $0, grabbed at compile-time.

:types

Any of the Params::Validate type constants (SCALAR, etc.) can be imported as well. You can get all of them at once by importing :types.

:all

This gets you everything.

CONFIGURATION

$MungeOptions

When $Getopt::Long::Descriptive::MungeOptions is true, some munging is done to make option names more hash-key friendly:

• All keys are lowercased

• - is changed to _

The default is a true value.

SEE ALSO

Getopt::Long Params::Validate

AUTHOR

Hans Dieter Pearcey, <hdp@cpan.org>

BUGS

Please report any bugs or feature requests to bug-getopt-long-descriptive@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Getopt-Long-Descriptive. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

COPYRIGHT & LICENSE

Copyright 2005 Hans Dieter Pearcey, all rights reserved.

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

cpanm Getopt::Long::Descriptive

perl -MCPAN -e shell
install Getopt::Long::Descriptive