Tk_ParseArgv(3)
_________________________________________________________________
NAME
Tk_ParseArgv - process command-line options
SYNOPSIS
#include <<tk.h>>
int
Tk_ParseArgv(interp, tkwin, argcPtr, argv, argTable, flags)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter to use for
returning error mes-
sages.
Tk_Window tkwin (in) Window to use when
arguments specify Tk
options. If NULL,
then no Tk options
will be processed.
int argcPtr (in/out) Pointer to number of
arguments in argv;
gets modified to hold
number of unprocessed
arguments that remain
after the call.
char **argv (in/out) Command line arguments
passed to main pro-
gram. Modified to
hold unprocessed argu-
ments that remain
after the call.
Tk_ArgvInfo *argTable (in) Array of argument
descriptors, termi-
nated by element with
type TK_ARGV_END.
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.
_________________________________________________________________
DESCRIPTION
Tk_ParseArgv processes an array of command-line arguments
according to a table describing the kinds of arguments
that are expected. Each of the arguments in argv is pro-
cessed in turn: if it matches one of the entries in
argTable, the argument is processed according to that
entry and discarded. The arguments that do not match any-
thing in argTable are copied down to the beginning of argv
(retaining their original order) and returned to the
caller. At the end of the call Tk_ParseArgv sets *argcPtr
to hold the number of arguments that are left in argv, and
argv[*argcPtr] will hold the value NULL. Normally,
Tk_ParseArgv assumes that argv[0] is a command name, so it
is treated like an argument that doesn't match argTable
and returned to the caller; however, if the
TK_ARGV_DONT_SKIP_FIRST_ARG bit is set in flags then
argv[0] will be processed just like the other elements of
argv.
Tk_ParseArgv normally returns the value TCL_OK. If an
error occurs while parsing the arguments, then TCL_ERROR
is returned and Tk_ParseArgv will leave an error message
in interp->result in the standard Tcl fashion. In the
event of an error return, *argvPtr will not have been mod-
ified, but argv could have been partially modified. The
possible causes of errors are explained below.
The argTable array specifies the kinds of arguments that
are expected; each of its entries has the following
structure:
typedef struct {
char *key;
int type;
char *src;
char *dst;
char *help;
} Tk_ArgvInfo;
The key field is a string such as ``-display'' or ``-bg''
that is compared with the values in argv. Type indicates
how to process an argument that matches key (more on this
below). Src and dst are additional values used in pro-
cessing the argument. Their exact usage depends on type,
but typically src indicates a value and dst indicates
where to store the value. The char * declarations for src
and dst are placeholders: the actual types may be differ-
ent. Lastly, help is a string giving a brief description
of this option; this string is printed when users ask for
help about command-line options.
When processing an argument in argv, Tk_ParseArgv compares
the argument to each of the key's in argTable.
Tk_ParseArgv selects the first specifier whose key matches
the argument exactly, if such a specifier exists. Other-
wise Tk_ParseArgv selects a specifier for which the argu-
ment 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
argTable, then the argument is skipped and returned to the
caller.
Once a matching argument specifier is found, Tk_ParseArgv
processes the argument according to the type field of the
specifier. The argument that matched key is called ``the
matching argument'' in the descriptions below. As part of
the processing, Tk_ParseArgv may also use the next argu-
ment in argv after the matching argument, which is called
``the following argument''. The legal values for type,
and the processing that they cause, are as follows:
TK_ARGV_END
Marks the end of the table. The last entry in
argTable must have this type; all of its other
fields are ignored and it will never match any
arguments.
TK_ARGV_CONSTANT
Src is treated as an integer and dst is treated as
a pointer to an integer. Src is stored at *dst.
The matching argument is discarded.
TK_ARGV_INT
The following argument must contain an integer
string in the format accepted by strtol (e.g. ``0''
and ``0x'' prefixes may be used to specify octal or
hexadecimal numbers, respectively). Dst is treated
as a pointer to an integer; the following argument
is converted to an integer value and stored at
*dst. Src is ignored. The matching and following
arguments are discarded from argv.
TK_ARGV_FLOAT
The following argument must contain a floating-
point number in the format accepted by strtol. Dst
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
*dst. The matching and following arguments are
discarded from argv.
TK_ARGV_STRING
In this form, dst is treated as a pointer to a
(char *); Tk_ParseArgv stores at *dst a pointer to
the following argument, and discards the matching
and following arguments from argv. Src is ignored.
TK_ARGV_UID
This form is similar to TK_ARGV_STRING, except that
the argument is turned into a Tk_Uid by calling
Tk_GetUid. Dst is treated as a pointer to a
Tk_Uid; Tk_ParseArgv stores at *dst the Tk_Uid cor-
responding to the following argument, and discards
the matching and following arguments from argv.
Src is ignored.
TK_ARGV_CONST_OPTION
This form causes a Tk option to be set (as if the
option command had been invoked). The src field is
treated as a pointer to a string giving the value
of an option, and dst is treated as a pointer to
the name of the option. The matching argument is
discarded. If tkwin is NULL, then argument speci-
fiers of this type are ignored (as if they did not
exist).
TK_ARGV_OPTION_VALUE
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 src. Dst is
used as the name of the option. Src is ignored.
The matching and following arguments are discarded.
If tkwin is NULL, then argument specifiers of this
type are ignored (as if they did not exist).
TK_ARGV_OPTION_NAME_VALUE
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 src and
dst are ignored. All three arguments are discarded
from argv. If tkwin is NULL, then argument speci-
fiers of this type are ignored (as if they did not
exist).
TK_ARGV_HELP
When this kind of option is encountered,
Tk_ParseArgv uses the help fields of argTable to
format a message describing all the valid argu-
ments. The message is placed in interp->result and
Tk_ParseArgv returns TCL_ERROR. When this happens,
the caller normally prints the help message and
aborts. If the key field of a TK_ARGV_HELP speci-
fier 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.
TK_ARGV_REST
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
TK_ARGV_REST argument is found, then Tk_ParseArgv
doesn't process any of the remaining arguments; it
returns them all at the beginning of argv (along
with any other unprocessed arguments). In addi-
tion, Tk_ParseArgv treats dst as the address of an
integer value, and stores at *dst the index of the
first of the TK_ARGV_REST options in the returned
argv. This allows the program to distinguish the
TK_ARGV_REST options from other unprocessed options
that preceded the TK_ARGV_REST.
TK_ARGV_FUNC
For this kind of argument, src is treated as the
address of a procedure, which is invoked to process
the following argument. The procedure should have
the following structure:
int
func(dst, key, nextArg)
char *dst;
char *key;
char *nextArg;
{
}
The dst and key parameters will contain the corre-
sponding fields from the argTable entry, and nex-
tArg will point to the following argument from argv
(or NULL if there aren't any more arguments left in
argv). If func uses nextArg (so that Tk_ParseArgv
should discard it), then it should return 1. Oth-
erwise it should return 0 and TkParseArgv will pro-
cess the following argument in the normal fashion.
In either event the matching argument is discarded.
TK_ARGV_GENFUNC
This form provides a more general procedural
escape. It treats src as the address of a proce-
dure, and passes that procedure all of the remain-
ing arguments. The procedure should have the fol-
lowing form:
int
genfunc(dst, interp, key, argc, argv)
char *dst;
Tcl_Interp *interp;
char *key;
int argc;
char **argv;
{
}
The dst and key parameters will contain the corre-
sponding fields from the argTable entry. Interp
will be the same as the interp argument to
Tcl_ParseArgv. Argc and argv refer to all of the
options after the matching one. Genfunc should
behave in a fashion similar to Tk_ParseArgv: parse
as many of the remaining arguments as it can, then
return any that are left by compacting them to the
beginning of argv (starting at argv[0]). Genfunc
should return a count of how many arguments are
left in argv; Tk_ParseArgv will process them. If
genfunc encounters an error then it should leave an
error message in interp->result, in the usual Tcl
fashion, and return -1; when this happens
Tk_ParseArgv will abort its processing and return
TCL_ERROR.
FLAGS
TK_ARGV_DONT_SKIP_FIRST_ARG
Tk_ParseArgv normally treats argv[0] as a program
or command name, and returns it to the caller just
as if it hadn't matched argTable. If this flag is
given, then argv[0] is not given special treatment.
TK_ARGV_NO_ABBREV
Normally, Tk_ParseArgv accepts unique abbreviations
for key values in argTable. If this flag is given
then only exact matches will be acceptable.
TK_ARGV_NO_LEFTOVERS
Normally, Tk_ParseArgv returns unrecognized argu-
ments to the caller. If this bit is set in flags
then Tk_ParseArgv will return an error if it
encounters any argument that doesn't match
argTable. The only exception to this rule is
argv[0], which will be returned to the caller with
no errors as long as TK_ARGV_DONT_SKIP_FIRST_ARG
isn't specified.
TK_ARGV_NO_DEFAULTS
Normally, Tk_ParseArgv searches an internal table
of standard argument specifiers in addition to
argTable. If this bit is set in flags, then
Tk_ParseArgv will use only argTable and not its
default table.
EXAMPLE
Here is an example definition of an argTable and some sam-
ple command lines that use the options. Note the effect
on argc and argv; arguments processed by Tk_ParseArgv are
eliminated from argv, and argc is updated to reflect
reduced number of arguments.
/*
* 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\n", interp->result);
exit(1);
}
/*
* Remainder of the program.
*/
}
Note that default values can be assigned to variables
named in argTable: the variables will only be overwritten
if the particular arguments are present in argv. Here are
some example command lines and their effects.
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
In all of the above examples, argc will be set by
Tk_ParseArgv to 2, argv[0] will be ``prog'', argv[1] will
be ``infile'', and argv[2] will be NULL.
KEYWORDS
arguments, command line, options