/ 
Getopt-Long-Descriptive-0.082
River stage four • 86 direct dependents • 1719 total dependents
/ Getopt::Long::Descriptive

NAME

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

VERSION

Version 0.082

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. You should always import this routine, and not call it directly. The ability to call Getopt::Long::Descriptive::describe_options may go away in the future.

The usage object has several methods:

  • $usage->text returns the usage string

  • $usage->warn prints usage to STDERR

  • $usage->die dies with the usage string

For more information on the usage object, look at Getopt::Long::Descriptive::Usage.

prog_name

This routine 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

CUSTOMIZING

Getopt::Long::Descriptive uses Sub::Exporter to build and export the describe_options routine. By writing a new class that extends Getopt::Long::Descriptive, the behavior of the constructed describe_options routine can be changed.

The following methods can be overridden:

usage_class

my $class = Getopt::Long::Descriptive->usage_class;

This returns the class to be used for constructing a Usage object, and defaults to Getopt::Long::Descriptive::Usage.

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.