286 lines
10 KiB
Groff
286 lines
10 KiB
Groff
'\" Copyright 1991 Regents of the University of California
|
|
'\" Permission to use, copy, modify, and distribute this
|
|
'\" documentation for any purpose and without fee is hereby
|
|
'\" granted, provided that this notice appears in all copies.
|
|
'\" The University of California makes no representations about
|
|
'\" the suitability of this material for any purpose. It is
|
|
'\" provided "as is" without express or implied warranty.
|
|
'\"
|
|
'\" $Header: /home/srilm/CVS/srilm/misc/doc/Opt.man,v 1.4 1991/01/28 17:00:56 kupfer Exp $ SPRITE (Berkeley)
|
|
'/"
|
|
.so \*(]ltmac.sprite
|
|
.HS Opt lib
|
|
.BS
|
|
.SH NAME
|
|
Opt_Parse, Opt_PrintUsage \- Manage command line options
|
|
.SH SYNOPSIS
|
|
\fB#include <option.h>\fR
|
|
.sp
|
|
int
|
|
\fBOpt_Parse\fR(\fIargc, argv, optionArray, numOptions, flags\fR)
|
|
.sp
|
|
void
|
|
\fBOpt_PrintUsage\fR(\fIcommandName, optionArray, numOptions\fR)
|
|
.SH ARGUMENTS
|
|
.AS Option *optionArray
|
|
.AP int argc in
|
|
Number of arguments on command line.
|
|
.AP char **argv in/out
|
|
Command line arguments passed to main program.
|
|
.AP char *commandName in
|
|
Name of the program being run, usually \fIargv\fR[0].
|
|
.AP Option *optionArray in
|
|
An array of option descriptions.
|
|
.AP int numOptions in
|
|
Number of elements in optionArray, usually obtained using the
|
|
\fBOpt_Number\fR macro, e.g. \fBOpt_Number\fR(optionArray).
|
|
.AP int flags in
|
|
If non-zero, then it specifies one or more flags that control the
|
|
parsing of arguments. Different flags may be OR'ed together. The
|
|
only flags currently defined are OPT_ALLOW_CLUSTERING and OPT_OPTIONS_FIRST.
|
|
.BE
|
|
.SH DESCRIPTION
|
|
.PP
|
|
\fBOpt_Parse\fR parses the command line arguments of a program according
|
|
to an array of option descriptions. Starting with \fIargv\fR[1], it parses
|
|
as many options as it can and returns the rest of the options in
|
|
the \fIargv\fR array, compacted to the beginning of the array (starting
|
|
with \fIargv\fR[1]). The return value indicates how many options are
|
|
returned in the \fIargv\fR array (including \fIargv\fR[0]).
|
|
Opt_Parse returns options that don't start with ``-'' unless they
|
|
are arguments for options that it parses. \fBOpt_Parse\fR also returns
|
|
any options following an \fBOPT_REST\fR option (see below for more details).
|
|
.PP
|
|
Each element of the array
|
|
\fIoptionArray\fR has the following structure:
|
|
.DS
|
|
.ta 2c
|
|
\fBtypedef struct\fR Option {
|
|
\fBint\fR \fItype\fR;
|
|
\fBchar\fR *\fIkey\fR;
|
|
\fBchar\fR *\fIvaluePtr\fR;
|
|
\fBchar\fR *\fIdocMsg\fR;
|
|
} Option;
|
|
.DE
|
|
.LP
|
|
The \fIkey\fR field is a string that identifies this option. For
|
|
example, if \fIkey\fR is \fBfoo\fR, then this Option will match
|
|
a \fB\-foo\fR command-line option. If \fIkey\fR is the empty
|
|
string (``'') then it matches a \fB\-\fR command-line option.
|
|
If \fIkey\fR is NULL, the Option
|
|
will not match any command-line options (this feature is only useful
|
|
for OPT_DOC options).
|
|
\fIDocMsg\fR is a documentation string to print out as part of a
|
|
help message.
|
|
The \fItype\fR field determines what to do when this Option is
|
|
matched. It also determines the meaning of the \fIvaluePtr\fR
|
|
field. \fIType\fR should always be specified using one of the
|
|
following macros:
|
|
.TP
|
|
\fBOPT_TRUE\fR
|
|
Treats \fIvaluePtr\fR as the address of an integer, and stores
|
|
the value 1 in that integer.
|
|
.TP
|
|
\fBOPT_FALSE\fR
|
|
Treats \fIvaluePtr\fR as the address of an integer and stores
|
|
the value 0 in that integer.
|
|
.TP
|
|
\fBOPT_CONSTANT\fR(\fIvalue\fR)
|
|
This is a generalized form of OPT_TRUE and OPT_FALSE. Treats
|
|
\fIvaluePtr\fR as the address of an integer and stores \fIvalue\fR
|
|
in that integer. \fIValue\fR must be a positive integer.
|
|
.TP
|
|
\fBOPT_INT\fR
|
|
The next argument after the one matching \fIkey\fR must contain an
|
|
integer string in the format accepted by \fBstrtol\fR (e.g. ``0''
|
|
and ``0x'' prefixes may be used to specify octal or hexadecimal
|
|
numbers, respectively). \fIValuePtr\fR
|
|
will be treated as the address of an integer, and the value given
|
|
by the next argument will be stored there.
|
|
.TP
|
|
\fBOPT_TIME\fR
|
|
The next argument after the one matching \fIkey\fR must contain a
|
|
string that is parsable as a date and time. Currently, only two
|
|
formats are recognized:
|
|
.DS
|
|
\fIseconds\fR
|
|
.DE
|
|
.IP
|
|
and
|
|
.DS
|
|
\fIyy\fB.\fImm\fB.\fIdd\fB.\fIhh\fB.\fImm\fB.\fIss\fR
|
|
.DE
|
|
.IP
|
|
The first form is simply the number of seconds since the start of the
|
|
epoch (1 January 1970, 0 hours GMT). The second form specifies the
|
|
year (e.g., 91 or 1991),
|
|
month (1-12), day of the month, hours (0-23), minutes (0-59), and
|
|
seconds (0-59). All fields must be specified.
|
|
\fIValuePtr\fR
|
|
will be treated as the address of a
|
|
.B time_t
|
|
(defined in
|
|
.BR <time.h> ),
|
|
and the given time will be stored there.
|
|
All times are in terms of the current timezone and daylight savings
|
|
rules.
|
|
.IP
|
|
Note that this flavor can clobber the static buffer used by the
|
|
.B localtime
|
|
library routine.
|
|
.TP
|
|
\fBOPT_FLOAT\fR
|
|
The next argument after the one matching \fIkey\fR must contain a
|
|
floating-point number in the format accepted by \fBstrtol\fR.
|
|
\fIValuePtr\fR will be treated as the address of an double-precision
|
|
floating point value, and the
|
|
value given by the next argument will be stored there.
|
|
.TP
|
|
\fBOPT_STRING\fR
|
|
Treats \fIvaluePtr\fR as the address of a (char *), and stores a pointer
|
|
to the next argument in the location
|
|
pointed to by \fIvaluePtr\fR.
|
|
.TP
|
|
\fBOPT_DOC\fR
|
|
This option is intended primarily as a way of printing extra documentation
|
|
during help message printouts. It isn't normally used as an actual
|
|
option (and normally its \fIkey\fR field is NULL).
|
|
If it is invoked as an option, then the same thing happens as for
|
|
the ``-?'' option: descriptions get printed for all options in
|
|
\fIoptionArray\fR and \fBOpt_Parse\fR calls exit(0) to terminate the process.
|
|
.TP
|
|
\fBOPT_REST\fR
|
|
This option is used by programs that allow the last several of their
|
|
options to be the name and/or options for some other program. If
|
|
an \fBOPT_REST\fR option is found, then \fBOpt_Parse\fR doesn't process any
|
|
of the remaining arguments; it returns them all at the beginning of \fIargv\fR.
|
|
In addition, \fBOpt_Parse\fR treats \fIvaluePtr\fR as the address of an
|
|
integer value, and stores in that value the index of the first of the
|
|
\fBOPT_REST\fR options in the returned \fIargv\fR. This allows the
|
|
program to distinguish the \fBOPT_REST\fR options from other
|
|
unprocessed options that preceeded the \fBOPT_REST\fR.
|
|
.TP
|
|
\fBOPT_FUNC\fR
|
|
When one of these options is encountered, \fIvaluePtr\fR is treated
|
|
as the address of a function which is then called
|
|
with the following calling sequence:
|
|
.DS
|
|
.ta 1c 2c 3c 4c 5c 6c
|
|
\fBint\fI
|
|
func(optString, nextArg)
|
|
\fBchar\fR *\fIoptString\fR;
|
|
\fBchar\fR *\fInextArg\fR;
|
|
{
|
|
}
|
|
.DE
|
|
.IP
|
|
The \fIoptString\fR parameter points to the current option, and
|
|
\fInextArg\fR points to the next option from \fIargv\fR (or NULL
|
|
if there aren't any more options in \fIargv\fR. If \fIfunc\fR
|
|
uses \fInextArg\fR as an argument to the current option (so that
|
|
Opt_Parse should skip it), then it should return 1. Otherwise it
|
|
should return 0.
|
|
.TP
|
|
\fBOPT_GENFUNC\fR
|
|
Treat \fIvaluePtr\fR as the address of a function and pass all of the
|
|
remaining arguments to it in the following way:
|
|
.DS
|
|
.ta 1c 2c 3c 4c 5c 6c
|
|
\fBint\fI
|
|
genfunc(optString, argc, argv)
|
|
\fBchar\fR *\fIoptString\fR;
|
|
\fBint\fR \fIargc\fR;
|
|
\fBchar\fR **\fIargv\fR;
|
|
{
|
|
}
|
|
.DE
|
|
.IP
|
|
\fIArgc\fR and \fIargv\fR refer to all of the options after the
|
|
one that triggered the call, and \fIoptString\fR points to the
|
|
triggering option. \fIGenfunc\fR should behave in a fashion similar
|
|
to \fBOpt_Parse\fR: parse as many of the remaining arguments as it can,
|
|
then return any that are left by compacting them to the beginning of
|
|
\fIargv\fR (starting at \fIargv\fR[0]). \fIGenfunc\fR
|
|
should return a count of how many arguments are left in \fIargv;
|
|
\fBOpt_Parse\fR will process them.
|
|
|
|
.SH "FLAGS"
|
|
.IP \fBOPT_ALLOW_CLUSTERING\fR
|
|
This will
|
|
permit several options to be clustered together with a
|
|
single ``-'', e.g., ``foo -abc'' will be handled the same way as
|
|
``foo -a -b -c''. OPT_ALLOW_CLUSTERING is likely to cause confusing
|
|
behavior unless each option is identified with a single character.
|
|
.IP \fBOPT_OPTIONS_FIRST\fR
|
|
This causes \fBOpt_Parse\fR to stop parsing the command line anytime something
|
|
that is not an option is detected. Thus, a program that takes some options
|
|
followed by a command to execute (along with that command's options) can
|
|
parse its own options using OPT_OPTIONS_FIRST. When the command to execute is
|
|
encountered, assuming it does not begin with a hyphen, \fBOpt_Parse\fR will
|
|
return the command and its arguments starting at \fIargv\fR[1], ignoring
|
|
any arguments with hyphens following the first non-option.
|
|
.SH "USAGE MESSAGE"
|
|
.PP
|
|
\fBOpt_PrintUsage\fR may be invoked to print out all the documentation strings
|
|
(plus option names and default values) for a command's options. If
|
|
\fBOpt_Parse\fR encounters an option ``-?'' or ``-help'', then it will call
|
|
\fBOpt_PrintUsage\fR
|
|
and exit. Note: in some shells the question-mark must be escaped
|
|
(e.g., ``foo -\e?'' in \fIcsh\fR).
|
|
|
|
.SH EXAMPLE
|
|
.PP
|
|
Here is an example definition of a set of option descriptions and
|
|
some sample command lines that use the options. Note the effect
|
|
on argc and argv; command arguments that get interpreted as
|
|
options or option values are eliminated from argv, and argc
|
|
is updated to reflect reduced number of arguments.
|
|
.DS
|
|
/*
|
|
* Define and set default values for globals.
|
|
*/
|
|
Boolean debugFlag = FALSE;
|
|
int numReps = 100;
|
|
char defaultFileName[] = "out";
|
|
char *fileName = defaultFileName;
|
|
Boolean exec = FALSE;
|
|
|
|
/*
|
|
* Define option descriptions.
|
|
*/
|
|
Option optionArray[] = {
|
|
OPT_TRUE, "X", (char *) &debugFlag, "Turn on debugging printfs",
|
|
OPT_INT, "N", (char *) &numReps, "Number of repetitions",
|
|
OPT_STRING, "of", (char *) &fileName, "Output filename",
|
|
OPT_REST, "x", (char *) &exec,
|
|
"File to exec, followed by any arguments (must be last argument).",
|
|
};
|
|
|
|
main(argc, argv)
|
|
int argc;
|
|
char *argv[];
|
|
{
|
|
Opt_Parse(argc, argv, optionArray, Opt_Number(optionArray),
|
|
OPT_ALLOW_CLUSTERING);
|
|
|
|
/*
|
|
* the rest of the program.
|
|
*/
|
|
}
|
|
.DE
|
|
.PP
|
|
Note that default values can be assigned to option variables.
|
|
Also, numOptions gets calculated by the compiler in this example.
|
|
Here are some example command lines and their effects.
|
|
.DS
|
|
prog -N 200 infile # just sets the numReps variable to 200
|
|
prog -of out200 infile # sets fileName to reference "out200"
|
|
prog -XN 10 infile # sets the debug flag, also sets numReps
|
|
.DE
|
|
In all of the above examples, the return value from Opt_Parse will be 2,
|
|
\fIargv\fR[0] will be ``prog'', \fIargv\fR[1] will be ``infile'',
|
|
and \fIargv\fR[2] will be NULL.
|
|
|
|
.SH KEYWORDS
|
|
arguments, command line, options
|