| Getopt::constant -- set constants from command line options |
Getopt::constant -- set constants from command line options
# Assuming @ARGV is: ('-foo=9,8,7', '-bar', 'wakawaka.txt')
use Getopt::constant (
':prefix' => 'C_',
'foo' => [3,5],
'bar' => 0,
':usage' =>
"Usage:
thingamabob
-foo=one,two,three : fooey on these items
-bar : enable barriness
",
);
# @ARGV is now 'wakawaka.txt', and you've now got
# a constant C_foo with value (9,8,7)
# and a constant C_bar with value 1
Other command-line options processing modules (like Getopt::Std) parse command-line arguments (from @ARGV) and set either variables or hash entries based on them. This module, however, parses command-line arguments into constants which are put into the current package.
You provide default values for each constant in the list that you pass in the ``use Getopt::constant (...);'' statement. Values can be a scalar (in which case you will get a scalar constant) or an arrayref (in which case you will get a list constant).
Default is empty-string, "". A common useful value you
should consider is "C_".
You should not use a value, like ``*'' or ``-'' or ``1'' that can't begin a legal Perl symbol name.
use Getopt::constant (...) didn't mention a
'foo' => some_value,
then when Getopt::constant gets to parsing ``-foo=1'', it would exit with a message to STDERR, as determined by the value of the ``:usage'' parameter.
However, if the ``:permissive'' parameter is set to a true value, then unknown items are simply ignored.
The default value is 0.
What happens in the case of a fatal error is controlled by the ``:usage'' parameter's value:
If it's a string, then on STDERR we print ``Unknown options: '', and the list of the unknown options, and a newline and then the string value of the ``:usage'' parameter (which should presumably be something explaining what the valid parameters are, and what they mean); and then the program exits.
If it's undef (which is the default value), then on STDERR we print ``Unknown options: '', and the list of the unknown options and a newline, and then on the next line, the list of all permitted options; and then the program exits.
If it's a code ref, then the code ref is called with three options: a
reference to the array of unknown options found, a reference to the
array of options allowed, and a reference to the hash consisting of
the elements passed in the 'use Getopt::constant (...);' statement.
For example, if you said:
use Getopt::constant (
':prefix' => 'C_',
'foo' => [3,5],
'bar' => 0,
':usage' => sub {...},
);
and there's a ``-baz'' in @ARGV, then the specified sub will be called as
$thatsub->(
['baz'],
['foo','bar'],
{ ':prefix' => 'C_',
'foo' => [3,5],
'bar' => 0,
':usage' => sub {...},
}
);
and then once that sub returns, the program exits.
Default is 0 -- to remove parsed items from @ARGV.
If you want to parse the options in @ARGV first with Getopt::constant and then with something like Getopt::Std, you should consider:
":retain" => 1, ":retain" => 1,
(Although note that this is only a partial solution: consider an
argument list of qw(-foo 13 -bar) which you want to be parsed by
Getopt::constant and then by Getopt::Long. Getopt::Long will parse it
as you expect, but Getopt::constant has a more restricted view of
switch parsing and will stop parsing at ``13''.)
As Getopt::constant parses thru the items in @ARGV, it expects @ARGV to start with some number of switches; it stops parsing when it hits the first non-switch item.
A switch consists of one of the following syntaxes:
split(",", VALUE, -1)
Note that VALUE may be empty-string. I.e., ``-foo='', is a legal switch which sets foo to empty-string, or empty-list if foo is to be a list constant.
Note that switches of the form:
% progname.pl -foo VALUE
are not recognized; you need to express that as one of:
% progname.pl -foo=VALUE
% progname.pl --foo=VALUE
the constant manpage, the Getopt::Long manpage, the Getopt::Std manpage
Consider this:
use Getopt::constant ('DEBUG' => 0);
...
print "Starting doing things...\n" if DEBUG;
...
foreach $thing (@many_things) {
print " About to do things with $thing\n" if DEBUG > 1;
...
}
...
DEBUG and printf "Done doing things at %s after %s sec.\n",
scalar(localtime), time - $^T;
What's the point of doing this, as opposed to using Getopt::Std to set
a $DEBUG that we'd use everywhere where we have a DEBUG above?
Well, every time an expression consisting of a variable, or involving
a variable (like ``$DEBUG > 1'') is encountered, it has to be
evaluated. That means that in every iteration of the loop, the
expression ``$DEBUG > 1'' would have to be evaluated anew, since
Perl has no assurance that $DEBUG's value can't have changed since
the last iteration. But, with constants, or expressions involving
constants, Perl evaluates them only once, at compile time. So if Perl
knows that the constant DEBUG has the value 2, then the expression
print " About to do things with $thing\n" if DEBUG > 1;
turns into:
print " About to do things with $thing\n";
as Perl compiles it.
But more importantly, if Perl knows DEBUG is 0 (or anything such that ``DEBUG > 1'' is false) then the above statement is actually removed from the in-memory compiled version of the program, before it is actually run.
Incidentally, you can, with some doing, use any other Getopt library to make constants, using something like:
#...Assuming an @ARGV of qw( -D4 -x9 stuff )...
use strict;
my %opts;
BEGIN { # constants need to be made at compile time!
%opts = ( 'D' => 0, 'y' => 'nope', 'x' => 3 ); # default values
use Getopt::Std ();
Getopt::Std::getopt('Dxy', \%opts);
require constant;
# Now make constants from whatever we want:
constant->import('D', $opts{'D'});
constant->import('C_y', $opts{'y'});
}
print "ARGV is @ARGV\n";
printf "D is %s, C_y is %s, and opts-x is %s\n", D, C_y, $opts{'x'};
That prints:
ARGV is stuff D is 4, C_y is nope, opts-x is 9
That's obviously a bit circuitous, but it's quite doable.
Copyright (c) 2001 Sean M. Burke. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.
Sean M. Burke, sburke@cpan.org
| Getopt::constant -- set constants from command line options |