• NAME
• SYNOPSIS
• DESCRIPTION
• FUNCTIONS
  • HOOKS
• BUGS
  • COPYRIGHT

NAME

SYNOPSIS

    use Opt;
    Opt::getoptions(["-x","Help string for x",\$x],
                    ["-yINT"],
                    ["--zvalue=STRING"], 
                    ["--longvar",\%LocalHashOfOptions]
                   );

and then the values associated with those options will be assigned to variables $x, $OPT{y}, $OPT{zvalue}, and $LocalHashOfOptions{longvar}.

DESCRIPTION

Opt supports simultaneous use of traditional, bundled, and long (aka POSIX) options

-x

turns on the 'x' feature of your code; in this traditional specification, the option specifier 'x' is only permitted to be one character, usually alphabetic of either case, but Opt.pm also permits other characters, such as the digits 0-9, so you can specify '-2' to indicate that you want a two-sided statistical test. Most punctuation would not be permitted.

-x -y

turns on the 'x' and 'y' features

-xy

turns on both 'x' and 'y' features; putting both options together like this is called ``bundling''.

-z 3.14159,

specifies that the number associated with 'z' should have value 3.14159.

-z3.14159

does the same thing, even though there is no space between the 'x' and '3.14159'; that space is optional.

--xflag

turns on the flag associated with ``xflag''; note the two hyphens and that ``xflag'' is not constrained to be a single character.

--zvalue 3.14159, --zvalue=3.14159

are both permitted, but ``--zvalue3.14159'' is not allowed.

@file.opt

specifies that options are read from a file named ``file.opt''.

%file.opt

tells the program to write all the current values of all the options to a file called file.opt. If you want a ``file.opt'' template as a starting point which you might then edit by hand, you can always get one by typing 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?

--help

is a special flag which, if it is the first in a command line, tells the program to write a help message and exit. The message is of a ``standard'' format (standard to 'opt' that is) which can be parsed by other programs, such as 'tkopt' which instantly turns any opt-enabled program to be GUI too.

--menu

pops you into an interactive menu which allows you to see what parameters are available, what they do, and what their current values are. you can then reset those parameters to what you want and run the program.

FUNCTIONS

getoptions(["--var=TYPE","Help string",\$var], ['-x'], ... )

In principle, getoptions is the only function you need to know about in order to use the Opt package. Each argument ``registers'' a single option, which essentially sets up a table that associates each option with attributes specifying what kind of option it is, and which variable in the Perl script it corresponds to. After all the options are registered, the @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.

register("--var=TYPE","Help string",\$var)

This function registers a single option of type TYPE, named ``var'', and associates it with the variable $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.

optreg(\$var,"TYPE",'v',"Help string")

This is another version of the register function. It is arguably not as intuitive as register, but it more closely matches the way that options are registered in the C version of opt. This is not the most convenient way to register a function, but it mimics the C opt version. This form only registers one-character option names. Alternative forms include:

optrega(\$var,"TYPE",'v',"var","Help string")

Provides two names for the variable $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.

optregc(\$var,"TYPE",'v')

only provides a short single-character name ('v') for the variable $var.

Each of these functions also has a form optreg_TYPE(\$var,'v',"Help string"), in which the TYPE is not a string argument but is part of the function name.

@argvnew=opt($0,@argv)

After all the options are registered, the function 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);

HOOKS

Hooks are functions which are written by the Perl application programmer (but not by the Opt developer), which Opt calls at certain points in its processing. Among them are:

optMain(\&MyMain);

specifies that the function &MyMain will be run whenever the ``='' is invoked on the opt menu.

optEnv("ENV_VARIABLE");

specifies that the environment variable can be used to specify default options. eg, if ENV_VARIABLE='-x+ -y-', then the default value for 'x' will be TRUE, and for 'y' will be FALSE.

...

BUGS

• Currently, the %OPT variable is not being exported.

• Do not currently support setting $opt_xxx variables, as is done in the standard GetOpts packages. Well, it sort of does, but it is not exporting the variable names: you have to ask for $Opt::opt_xxx to get your variable.

• Not all of the C-opt functionality is implemented.

• Some extra functionality, not provided in C-opt, is implemented

• Don't be fooled by the Makefile.PL file; it's just a stub until I figure out how to make a real one. Currently, to install you just copy Opt.pm and Option.pm into a directory in your PERLLIB.

COPYRIGHT

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.