352 lines
14 KiB
Groff
352 lines
14 KiB
Groff
'\"
|
|
'\" Copyright (c) 1990-1992 The Regents of the University of California.
|
|
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
|
'\"
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
|
'\"
|
|
'\" SCCS: @(#) ParseArgv.3 1.16 96/03/18 14:25:51
|
|
'\"
|
|
.so man.macros
|
|
.TH Tk_ParseArgv 3 "" Tk "Tk Library Procedures"
|
|
.BS
|
|
.SH NAME
|
|
Tk_ParseArgv \- process command-line options
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fB#include <tk.h>\fR
|
|
.sp
|
|
int
|
|
\fBTk_ParseArgv\fR(\fIinterp, tkwin, argcPtr, argv, argTable, flags\fR)
|
|
.SH ARGUMENTS
|
|
.AS Tk_ArgvInfo *argTable
|
|
.AP Tcl_Interp *interp in
|
|
Interpreter to use for returning error messages.
|
|
.AP Tk_Window tkwin in
|
|
Window to use when arguments specify Tk options. If NULL, then
|
|
no Tk options will be processed.
|
|
.AP int argcPtr in/out
|
|
Pointer to number of arguments in argv; gets modified to hold
|
|
number of unprocessed arguments that remain after the call.
|
|
.AP char **argv in/out
|
|
Command line arguments passed to main program. Modified to
|
|
hold unprocessed arguments that remain after the call.
|
|
.AP Tk_ArgvInfo *argTable in
|
|
Array of argument descriptors, terminated by element with
|
|
type TK_ARGV_END.
|
|
.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 flags currently defined are TK_ARGV_DONT_SKIP_FIRST_ARG,
|
|
TK_ARGV_NO_ABBREV, TK_ARGV_NO_LEFTOVERS, and TK_ARGV_NO_DEFAULTS.
|
|
.BE
|
|
.SH DESCRIPTION
|
|
.PP
|
|
\fBTk_ParseArgv\fR processes an array of command-line arguments according
|
|
to a table describing the kinds of arguments that are expected.
|
|
Each of the arguments in \fIargv\fR is processed in turn: if it matches
|
|
one of the entries in \fIargTable\fR, the argument is processed
|
|
according to that entry and discarded. The arguments that do not
|
|
match anything in \fIargTable\fR are copied down to the beginning
|
|
of \fIargv\fR (retaining their original order) and returned to
|
|
the caller. At the end of the call
|
|
\fBTk_ParseArgv\fR sets \fI*argcPtr\fR to hold the number of
|
|
arguments that are left in \fIargv\fR, and \fIargv[*argcPtr]\fR
|
|
will hold the value NULL. Normally, \fBTk_ParseArgv\fR
|
|
assumes that \fIargv[0]\fR is a command name, so it is treated like
|
|
an argument that doesn't match \fIargTable\fR and returned to the
|
|
caller; however, if the TK_ARGV_DONT_SKIP_FIRST_ARG bit is set in
|
|
\fIflags\fR then \fIargv[0]\fR will be processed just like the other
|
|
elements of \fIargv\fR.
|
|
.PP
|
|
\fBTk_ParseArgv\fR normally returns the value TCL_OK. If an error
|
|
occurs while parsing the arguments, then TCL_ERROR is returned and
|
|
\fBTk_ParseArgv\fR will leave an error message in \fIinterp->result\fR
|
|
in the standard Tcl fashion. In
|
|
the event of an error return, \fI*argvPtr\fR will not have been
|
|
modified, but \fIargv\fR could have been partially modified. The
|
|
possible causes of errors are explained below.
|
|
.PP
|
|
The \fIargTable\fR array specifies the kinds of arguments that are
|
|
expected; each of its entries has the following structure:
|
|
.CS
|
|
typedef struct {
|
|
char *\fIkey\fR;
|
|
int \fItype\fR;
|
|
char *\fIsrc\fR;
|
|
char *\fIdst\fR;
|
|
char *\fIhelp\fR;
|
|
} Tk_ArgvInfo;
|
|
.CE
|
|
The \fIkey\fR field is a string such as ``\-display'' or ``\-bg''
|
|
that is compared with the values in \fIargv\fR. \fIType\fR
|
|
indicates how to process an argument that matches \fIkey\fR
|
|
(more on this below). \fISrc\fR and \fIdst\fR are additional
|
|
values used in processing the argument. Their exact usage
|
|
depends on \fItype\fR, but typically \fIsrc\fR indicates
|
|
a value and \fIdst\fR indicates where to store the
|
|
value. The \fBchar *\fR declarations for \fIsrc\fR and \fIdst\fR
|
|
are placeholders: the actual types may be different. Lastly,
|
|
\fIhelp\fR is a string giving a brief description
|
|
of this option; this string is printed when users ask for help
|
|
about command-line options.
|
|
.PP
|
|
When processing an argument in \fIargv\fR, \fBTk_ParseArgv\fR
|
|
compares the argument to each of the \fIkey\fR's in \fIargTable\fR.
|
|
\fBTk_ParseArgv\fR selects the first specifier whose \fIkey\fR matches
|
|
the argument exactly, if such a specifier exists. Otherwise
|
|
\fBTk_ParseArgv\fR selects a specifier for which the argument
|
|
is a unique abbreviation. If the argument is a unique abbreviation
|
|
for more than one specifier, then an error is returned. If there
|
|
is no matching entry in \fIargTable\fR, then the argument is
|
|
skipped and returned to the caller.
|
|
.PP
|
|
Once a matching argument specifier is found, \fBTk_ParseArgv\fR
|
|
processes the argument according to the \fItype\fR field of the
|
|
specifier. The argument that matched \fIkey\fR is called ``the matching
|
|
argument'' in the descriptions below. As part of the processing,
|
|
\fBTk_ParseArgv\fR may also use the next argument in \fIargv\fR
|
|
after the matching argument, which is called ``the following
|
|
argument''. The legal values for \fItype\fR, and the processing
|
|
that they cause, are as follows:
|
|
.TP
|
|
\fBTK_ARGV_END\fR
|
|
Marks the end of the table. The last entry in \fIargTable\fR
|
|
must have this type; all of its other fields are ignored and it
|
|
will never match any arguments.
|
|
.TP
|
|
\fBTK_ARGV_CONSTANT\fR
|
|
\fISrc\fR is treated as an integer and \fIdst\fR is treated
|
|
as a pointer to an integer. \fISrc\fR is stored at \fI*dst\fR.
|
|
The matching argument is discarded.
|
|
.TP
|
|
\fBTK_ARGV_INT\fR
|
|
The following argument 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). \fIDst\fR is treated as a pointer to an
|
|
integer; the following argument is converted to an integer value
|
|
and stored at \fI*dst\fR. \fISrc\fR is ignored. The matching
|
|
and following arguments are discarded from \fIargv\fR.
|
|
.TP
|
|
\fBTK_ARGV_FLOAT\fR
|
|
The following argument must contain a floating-point number in
|
|
the format accepted by \fBstrtol\fR.
|
|
\fIDst\fR is treated as the address of an double-precision
|
|
floating point value; the following argument is converted to a
|
|
double-precision value and stored at \fI*dst\fR. The matching
|
|
and following arguments are discarded from \fIargv\fR.
|
|
.TP
|
|
\fBTK_ARGV_STRING\fR
|
|
In this form, \fIdst\fR is treated as a pointer to a (char *);
|
|
\fBTk_ParseArgv\fR stores at \fI*dst\fR a pointer to the following
|
|
argument, and discards the matching and following arguments from
|
|
\fIargv\fR. \fISrc\fR is ignored.
|
|
.TP
|
|
\fBTK_ARGV_UID\fR
|
|
This form is similar to TK_ARGV_STRING, except that the argument
|
|
is turned into a Tk_Uid by calling \fBTk_GetUid\fR.
|
|
\fIDst\fR is treated as a pointer to a
|
|
Tk_Uid; \fBTk_ParseArgv\fR stores at \fI*dst\fR the Tk_Uid
|
|
corresponding to the following
|
|
argument, and discards the matching and following arguments from
|
|
\fIargv\fR. \fISrc\fR is ignored.
|
|
.TP
|
|
\fBTK_ARGV_CONST_OPTION\fR
|
|
This form causes a Tk option to be set (as if the \fBoption\fR
|
|
command had been invoked). The \fIsrc\fR field is treated as a
|
|
pointer to a string giving the value of an option, and \fIdst\fR
|
|
is treated as a pointer to the name of the option. The matching
|
|
argument is discarded. If \fItkwin\fR is NULL, then argument
|
|
specifiers of this type are ignored (as if they did not exist).
|
|
.TP
|
|
\fBTK_ARGV_OPTION_VALUE\fR
|
|
This form is similar to TK_ARGV_CONST_OPTION, except that the
|
|
value of the option is taken from the following argument instead
|
|
of from \fIsrc\fR. \fIDst\fR is used as the name of the option.
|
|
\fISrc\fR is ignored. The matching and following arguments
|
|
are discarded. If \fItkwin\fR is NULL, then argument
|
|
specifiers of this type are ignored (as if they did not exist).
|
|
.TP
|
|
\fBTK_ARGV_OPTION_NAME_VALUE\fR
|
|
In this case the following argument is taken as the name of a Tk
|
|
option and the argument after that is taken as the value for that
|
|
option. Both \fIsrc\fR and \fIdst\fR are ignored. All three
|
|
arguments are discarded from \fIargv\fR. If \fItkwin\fR is NULL,
|
|
then argument
|
|
specifiers of this type are ignored (as if they did not exist).
|
|
.TP
|
|
\fBTK_ARGV_HELP\fR
|
|
When this kind of option is encountered, \fBTk_ParseArgv\fR uses the
|
|
\fIhelp\fR fields of \fIargTable\fR to format a message describing
|
|
all the valid arguments. The message is placed in \fIinterp->result\fR
|
|
and \fBTk_ParseArgv\fR returns TCL_ERROR. When this happens, the
|
|
caller normally prints the help message and aborts. If the \fIkey\fR
|
|
field of a TK_ARGV_HELP specifier is NULL, then the specifier will
|
|
never match any arguments; in this case the specifier simply provides
|
|
extra documentation, which will be included when some other
|
|
TK_ARGV_HELP entry causes help information to be returned.
|
|
.TP
|
|
\fBTK_ARGV_REST\fR
|
|
This option is used by programs or commands that allow the last
|
|
several of their options to be the name and/or options for some
|
|
other program. If a \fBTK_ARGV_REST\fR argument is found, then
|
|
\fBTk_ParseArgv\fR doesn't process any
|
|
of the remaining arguments; it returns them all at
|
|
the beginning of \fIargv\fR (along with any other unprocessed arguments).
|
|
In addition, \fBTk_ParseArgv\fR treats \fIdst\fR as the address of an
|
|
integer value, and stores at \fI*dst\fR the index of the first of the
|
|
\fBTK_ARGV_REST\fR options in the returned \fIargv\fR. This allows the
|
|
program to distinguish the \fBTK_ARGV_REST\fR options from other
|
|
unprocessed options that preceded the \fBTK_ARGV_REST\fR.
|
|
.TP
|
|
\fBTK_ARGV_FUNC\fR
|
|
For this kind of argument, \fIsrc\fR is treated as the address of
|
|
a procedure, which is invoked to process the following argument.
|
|
The procedure should have the following structure:
|
|
.RS
|
|
.CS
|
|
int
|
|
\fIfunc(dst, key, nextArg)
|
|
char *\fIdst\fR;
|
|
char *\fIkey\fR;
|
|
char *\fInextArg\fR;
|
|
{
|
|
}
|
|
.CE
|
|
The \fIdst\fR and \fIkey\fR parameters will contain the
|
|
corresponding fields from the \fIargTable\fR entry, and
|
|
\fInextArg\fR will point to the following argument from \fIargv\fR
|
|
(or NULL if there aren't any more arguments left in \fIargv\fR).
|
|
If \fIfunc\fR uses \fInextArg\fR (so that
|
|
\fBTk_ParseArgv\fR should discard it), then it should return 1. Otherwise it
|
|
should return 0 and \fBTkParseArgv\fR will process the following
|
|
argument in the normal fashion. In either event the matching argument
|
|
is discarded.
|
|
.RE
|
|
.TP
|
|
\fBTK_ARGV_GENFUNC\fR
|
|
This form provides a more general procedural escape. It treats
|
|
\fIsrc\fR as the address of a procedure, and passes that procedure
|
|
all of the remaining arguments. The procedure should have the following
|
|
form:
|
|
.RS
|
|
.CS
|
|
int
|
|
\fIgenfunc\fR(dst, interp, key, argc, argv)
|
|
char *\fIdst\fR;
|
|
Tcl_Interp *\fIinterp\fR;
|
|
char *\fIkey\fR;
|
|
int \fIargc\fR;
|
|
char **\fIargv\fR;
|
|
{
|
|
}
|
|
.CE
|
|
The \fIdst\fR and \fIkey\fR parameters will contain the
|
|
corresponding fields from the \fIargTable\fR entry. \fIInterp\fR
|
|
will be the same as the \fIinterp\fR argument to \fBTcl_ParseArgv\fR.
|
|
\fIArgc\fR and \fIargv\fR refer to all of the options after the
|
|
matching one. \fIGenfunc\fR should behave in a fashion similar
|
|
to \fBTk_ParseArgv\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\fR;
|
|
\fBTk_ParseArgv\fR will process them. If \fIgenfunc\fR encounters
|
|
an error then it should leave an error message in \fIinterp->result\fR,
|
|
in the usual Tcl fashion, and return -1; when this happens
|
|
\fBTk_ParseArgv\fR will abort its processing and return TCL_ERROR.
|
|
.RE
|
|
|
|
.SH "FLAGS"
|
|
.TP
|
|
\fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR
|
|
\fBTk_ParseArgv\fR normally treats \fIargv[0]\fR as a program
|
|
or command name, and returns it to the caller just as if it
|
|
hadn't matched \fIargTable\fR. If this flag is given, then
|
|
\fIargv[0]\fR is not given special treatment.
|
|
.TP
|
|
\fBTK_ARGV_NO_ABBREV\fR
|
|
Normally, \fBTk_ParseArgv\fR accepts unique abbreviations for
|
|
\fIkey\fR values in \fIargTable\fR. If this flag is given then
|
|
only exact matches will be acceptable.
|
|
.TP
|
|
\fBTK_ARGV_NO_LEFTOVERS\fR
|
|
Normally, \fBTk_ParseArgv\fR returns unrecognized arguments to the
|
|
caller. If this bit is set in \fIflags\fR then \fBTk_ParseArgv\fR
|
|
will return an error if it encounters any argument that doesn't
|
|
match \fIargTable\fR. The only exception to this rule is \fIargv[0]\fR,
|
|
which will be returned to the caller with no errors as
|
|
long as TK_ARGV_DONT_SKIP_FIRST_ARG isn't specified.
|
|
.TP
|
|
\fBTK_ARGV_NO_DEFAULTS\fR
|
|
Normally, \fBTk_ParseArgv\fR searches an internal table of
|
|
standard argument specifiers in addition to \fIargTable\fR. If
|
|
this bit is set in \fIflags\fR, then \fBTk_ParseArgv\fR will
|
|
use only \fIargTable\fR and not its default table.
|
|
|
|
.SH EXAMPLE
|
|
.PP
|
|
Here is an example definition of an \fIargTable\fR and
|
|
some sample command lines that use the options. Note the effect
|
|
on \fIargc\fR and \fIargv\fR; arguments processed by \fBTk_ParseArgv\fR
|
|
are eliminated from \fIargv\fR, and \fIargc\fR
|
|
is updated to reflect reduced number of arguments.
|
|
.CS
|
|
/*
|
|
* Define and set default values for globals.
|
|
*/
|
|
int debugFlag = 0;
|
|
int numReps = 100;
|
|
char defaultFileName[] = "out";
|
|
char *fileName = defaultFileName;
|
|
Boolean exec = FALSE;
|
|
|
|
/*
|
|
* Define option descriptions.
|
|
*/
|
|
Tk_ArgvInfo argTable[] = {
|
|
{"-X", TK_ARGV_CONSTANT, (char *) 1, (char *) &debugFlag,
|
|
"Turn on debugging printfs"},
|
|
{"-N", TK_ARGV_INT, (char *) NULL, (char *) &numReps,
|
|
"Number of repetitions"},
|
|
{"-of", TK_ARGV_STRING, (char *) NULL, (char *) &fileName,
|
|
"Name of file for output"},
|
|
{"x", TK_ARGV_REST, (char *) NULL, (char *) &exec,
|
|
"File to exec, followed by any arguments (must be last argument)."},
|
|
{(char *) NULL, TK_ARGV_END, (char *) NULL, (char *) NULL,
|
|
(char *) NULL}
|
|
};
|
|
|
|
main(argc, argv)
|
|
int argc;
|
|
char *argv[];
|
|
{
|
|
\&...
|
|
|
|
if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) {
|
|
fprintf(stderr, "%s\en", interp->result);
|
|
exit(1);
|
|
}
|
|
|
|
/*
|
|
* Remainder of the program.
|
|
*/
|
|
}
|
|
.CE
|
|
.PP
|
|
Note that default values can be assigned to variables named in
|
|
\fIargTable\fR: the variables will only be overwritten if the
|
|
particular arguments are present in \fIargv\fR.
|
|
Here are some example command lines and their effects.
|
|
.CS
|
|
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
|
|
.CE
|
|
In all of the above examples, \fIargc\fR will be set by \fBTk_ParseArgv\fR to 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
|