use Opt qw($OPT);
Opt::getoptions(["-x","Help string for x",\$x],
["-yINT"],
["--zvalue=STRING"],
["--mobile",\%StuckInsideOf]
);
and then the values associated with those options will be assigned to
variables
$x, $OPT{y}, $OPT{zvalue}, and $StuckInsideOf{mobile}.
Opt supports simultaneous use of traditional, bundled, and long (aka POSIX) options
program %file.opt .; using a period ('.') as an argument causes the program to exit
gracefully.
Aside: Hmmm, this could be a problem for a program in which '.' might be a reasonable argument, eg a program that was expecting a directory name. Perhaps, we should instead use something like '---exit' instead?
@ARGV array is parsed, and the variables are all set accordingly. This is the
one-function-does-all invocation; you may prefer to call its individual
components: for instance, the example in the SYNOPSIS is equivalent to:
Opt::register('-x','Help string for x',\$x);
Opt::register('-yINT');
Opt::register('--zvalue=STRING');
Opt::register('--longvar',\%LocalHashOfOptions);
@ARGV=Opt::opt($0,@ARGV);
The longer form is a little closer to what the interface would look like in the C version of opt. You may prefer this form if, say, you want to perform argument processing on an array other than @ARGV.
$var. Invocations of --var=value
on the command line will lead to setting $var='value' in the
Perl script. The help string is optional, as is the $var
reference. If the variable reference is not specified, then a variable $OPT{var} is created, and it is associated with the option. TYPE is one of: NUL, INT, UNSINT, SHORT, LONG,
CHAR, INTLEVEL, FLOAT, DOUBLE, FLAG, NEGFLAG,
ABSFLAG, ABSNEGFLAG, STRING, or UNDELIM.
$var, a long name (``var'') and a short name ('v'). As an implementation issue,
all other registration functions, including the ones below as well as register and even
getoptions, all call optrega to actually register the option.
$var.
optreg_TYPE(\$var,'v',"Help string"), in which the TYPE is not a string argument but is part of the function
name.
opt does the actual parsing of command line as given in the array @argv. Here $0 is the name of the program. Note that opt does ``nondestructive'' argument processing; so the argument @argv is unaltered by the call to opt. The result @argvnew is the list of arguments that are unprocessed by opt. In typical usage, you would write
@ARGV=Opt::opt($0,@ARGV);
line(s) of the usage message. The '\%s'
will be expanded out as the program name. Multiple lines can be providee as
separate arguments. =item useMainFcn(\&MyMain);
specifies that the function &MyMain will be run whenever the ``='' is invoked on the opt menu.
ENVAR='-x+ -y-', then the default value for 'x' will be TRUE, and for 'y' will be FALSE.
%OPTION=();
useHash(\%OPTION);
Opt::register("-x");
will associate the option -x with the variable $OPTION{x}. By default, the package does an equivalent of useHash(\%OPT), unless that is changed by this function or by the useScalarPrefix
function.
$opt_xxx, where xxx is the name of the option.
Option::Base is the base option class; it is an actual working class (not an ``abstract class'' in the sense of C++), and is actually used for string options, but most of the other classes are derived from it.
The derived classes are for different kinds of options; currently these options are:
Option::Base NUL? STRING UNDELIM CSTRING UNDELIMC Option::Numeric FLOAT DOUBLE Option::Int INT SHORT LONG Option::UInt UINT USHORT ULONG Option::IntLevel INTLEVEL Option::Flag FLAG NEGFLAG ABSFLAG ABSNEGFLAG
Each object contains (among other things) a reference to a scalar variable. Getting and setting the value of this variable is the whole point of the Opt package. Since the "variable associated with the given class object" is a cumbersome phrase, I will refer to that variable as the optvar
For many data types, valOf() is an identity function, returning the same value that was provided as an argument. But for some types, it does a little massaging. For example, if the option is a FLAG type, then valOf("+") will return a 1; if the option is a NEGFLAG, then valOf("+") will return a 0.
If the function valOf() is called without an argument, then it sets
optvar as if the option had been invoked without an argument. For example, if you
want -f
to turn on a flag $f, then setvalOf() will toggle the value of the flag variable $f.
setval(valOf(string)); that is, it sets the optvar according to the argument string.
toString(), except that it returns a stringified optvar
that is appropriate for the builtin menu.
x
indicates an implementation of that function for that class, while
... indicates that the function is inherited.
Inheritance Table
-----------------
Function Class: B N I U L F
default x x................
getval x....................
setval x....................
fixval x x x x.... x
valOf x............ x x
setvalOf x....................
requiresArg x............ x....
toString x............ x x
toMenu x............ x x
toMenuLine x....................
toFileLine x....................
The classes (which are columns in this table) are: B=Base, N=Numeric,
I=Integer, U=UnsignedInt, L=IntLevel, and F=Flag. The inheritance hierarchy
is essentially linear, with each class being derived from the class to its
left in the above table. Conceptually, the hierarchy is shown below, except
that there is no S=String class (we just use the B=Base class, and check if $$self{type} =~ /STRING|UNDELIM/ for the few occasions where strings behave differently from the base.
+- S
|
B -+- N --- I --- U --- L --- F
The justification is that by making it look (to a user of the program) just like the C version of opt, a program such as tkopt will be useable on both C and Perl routines. It (this package, Opt) does have a few more bells and whistles, including: support for option files, help strings, and an interactive menu, as well as the ability to read default parameters from an environment variable or a dot file.
The real reason I wrote Opt was to learn about packages and object-oriented programming in Perl.
In particular 'make test' does not yet work. However, you can test it by hand. just do 'perl t/N.t' where N is the name of the test file; it it works it should print 'ok' possibly followed by a number.
This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This library 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. See the GNU Library General Public License for more details.
You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.