Linux Certif

Toute la documentation sur la certification Linux LPI

Getopt::Long::Descriptive.3pm

NAME

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

VERSION

Version 0.084

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