NAME
Getopt::OO - Perl object oriented version of Getopt that uses a perl hash as template to describe command line options and handles most common command line parsing.
SYNOPSIS
use Getopt::OO qw(Debug Verbose);
my ($handle) = Getopt::OO->new(\@ARGV,
'-d' => {
help => 'turn on debug output',
callback => sub {Debug(1); 0},
},
'-o' => {
help => 'another option.',
},
'-f' => {
help => 'option that expects one more value.',
n_values => 1,
},
'--long' {
help => 'long option'
},
);
if ($handle->Values()) {
Debug("You will get output if -d was on command line");
if (my $f = handle->Values(-f)) {
print "Got $f with the -f value.\n";
}
}
else {
print "No options found on command line.\n";
}DESCRIPTION
Getopt::OO is an object oriented tool for parsing command line arguments. It expects a reference to the input arguments and uses a perl hash to describe how the command line arguments should be parsed. Note that by parsed, we mean what options expect values, etc. We check to make sure values exist on the command line as necessary -- nothing else. The caller is responsible for making sure that a value that he knows should be a file exists, is writable, or whatever.
Command line arguments can be broken into two distinct types: options and values that are associated with these options. In windows, options often start with a '/' but sometimes with a '-', but in unix they almost universally start with a '-'. For this module options start with a '-'. We support two types of options: the short single dashed options and the long double dashed arguments. The difference between these two is that with this module the short options can be combined into a single option, but the long options can not. For example, most of us will be familiar with the tar '-xvf file' command which can also be expressed as '-x -v -f file'. Long options can not be combined this way, so '--help' for example must always stand by itself.
The input template expects the option names as its keys. For instance if you were expecting "-xv --hello" as possible command line arguments, the keys for your template hash would be '-x', '-v', and '--hello'.
Valid values for each dashed argument are:
help
A help string associated with the argument.
n_values
Number of arguments the value expects. Any value greater than or equal to 0 is valid with 0 being the default.
multiple
If this exists, it means the argument may be encountered multiple times. For example --
'-a' => {
n_values => 3,
multiple => 1,
},says that if '-a' is encountered on the command line, the next three arguments on the command line are associated with it and that it may be encountered multiple times.
callback
This must be a code reference. If the template entry looked like:
'-a' => {
n_values => 1,
multiple => 1,
callback => \&xyz,
},then we would call the function xyz with the a Getopt::OO handle and the option found and the argument reference. For instance if the function looked like:
sub Callback {
my ($handle, $option) = @_
...the caller could get help with $handle->Help() or its values with $handle->Values($option). He could also manipulate the argument list.
Note that the only option information available at this point is what has been found on the command line up to this point. For example, if the callback were associated with the -f option and the command line looked like '-xvfz 1 2 3', and the v and f options both expected one additional value, the argument list would have only the '3' left and $handle->Values($option) would return 2.
If the callback returns a non-0 defined value, it failed. We execute 'die $string' where $string is the returned value.
Template non-dashed arguments
Only four non-dashed keys are allowed: 'required' and 'usage' and 'mutual_exclusive'.
usage
This is a string. Typically it wil be the first part of a help statement and combined with the 'help' arguments for the various dashed arguments in the template, creates the complete usage message. By default, we will create a usage string that is the base name of the executable ($0) and just the string '[options]'.
required
This is an array reference to required arguments. It is an error if none of these are found on the command line.
mutual_exclusive
This is an list reference. It says "it is an error to receive these arguments at the same time." For example, "tar cx" would not make sense because you can't both create and extract at the same time. Give a reference for each set of mutually exclusive arguments. In the trivial case where you only have one set, the argument can be just a reference to a list, but in the more complicated case where you have sets of mutually exclusive arguments, this will be a refrence to an list of list references. The template to express this might look like:
mutual_exclusive => [ qw( -x -c ) ],
-x => {
help => 'Extract a tar file',
},
-c => {
help => 'Create a tar file',
}As stated above, this would also be correct.
mutual_exclusive => [
[qw( -x -c )],
],
-x => {
help => 'Extract a tar file',
},
-c => {
help => 'Create a tar file',
}Methods associated with the OO module:
my $handle = Getopt::OO->new(\@ARGV, %Template)
Creator function. Expects a reference to the argument list and a template that explanes how to parse the input arguments. Returns an object reference. If you want to catch any possible errors, do
my $handle = eval {Getopt::OO>new(\@ARGV, %template)};
if ($@) {...$@ will contain your error string if one exists and be empty otherwise.
$handle->Values(argument);
Values() returns the number of command line options that were matched.
Values($option) depends on the 'n_values' and the 'multiple' for the option in the template. If the option had no n_values element or n_values was 0, Values(option) will return 0 if the option was not found on the command line and 1 if it was found. If n_values was set to 1 and multiple was not set or was set to 0, we return nothing if the argument was not found and the value of the argument if one was found. If n_values > 1 and multiple was not set or if n_values is 1 and multiple was set, we return a list containing the values if the values were found and nothing otherwise. If the of n_values is greater than 1 and multiple is set, we retrun a list of list references -- each contining n_values elements, or nothing if no matches were found.
The example below shows a template and accesing the values returned by the parser. The template is ordered from the simplest use to the most complex.
Given the command line arguments:
-abcde b c0 d0 d1 e0 e1 -c c1 -e e2 esand the following to create our GetOpt handle:
use Getopt::OO qw(Debug);
my @argv = qw (-abcde b c0 d0 d1 e0 e1 -c c1 -e e2 es);
my $h = Getopt::OO->new(\@argv,
'-a' => {},
'-b' => { n_values => 1, },
'-c' => { n_values => 1, multiple => 1, },
'-d' => { n_values => 2, },
'-e' => { n_values => 2, multiple => 1, },
);
my $n_options = $h->Values();
my $a = $h->Values('-a');
my $b = $h->Values('-b');
my @c = $h->Values('-c');
my @d = $h->Values('-d');
my @e = $h->Values('-e');
Example 1. ValuesDemo.plmy $help_string = $handle->Help();
Get the string string we built for this template. Note that this can be used to check the template to make sure it is doing what you expect. It will contain optional arguments separated from non optional, indicates required and mutually exclusive options and indicates which options expect values and how many values.
my $client_data = $handle->ClientData($option);
The ClientData method is supplied to allow data to be associated with an option. The data must be scalar or a reference. All calls to this method return what ever the data was replied to, but it is only set if data is passed in.
To set the data:
$h->ClientData($option, $x);To get the data:
$x = $h->ClientData($option);Debug and Verbose Functions
We also supply two functions the user can export. These are the Debug and the Verbose functions. If the functions are exported and we find --debug or --verbose in the command line arguments, the associated function is enabled. These two functions behave in multiplt ways: If called with just a '0' or '1', the function is disabled or disabled. If called with no arguments, we return the state of the function: 0 if disabled and 1 if enabled. If called with a list and the first element of the list looks like a printf format statement, we behave like printf, and otherwise we behave like a simple print statement. If the function is called with a single argument that is a reference to an IO::File object, we will attempt to send all further output to this handle. Note that the object must be enabled before any output will occur though.
EXPORT
None by default.
Example
AUTHOR
Steven Smith, <sjs@chaos-tools.com<gt>
COPYRIGHT AND LICENSE
Copyright (C) 2004 by Steven Smith
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.3 or, at your option, any later version of Perl 5 you may have available.