Provided by: tk8.5-doc_8.5.15-2ubuntu3_all 
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 messages.
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.
const char **argv (in/out) Command line arguments passed to main program.
Modified to hold unprocessed arguments that remain
after the call.
Tk_ArgvInfo *argTable (in) Array of argument descriptors, terminated 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 processed 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 anything 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 does not 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 modified, 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 processing 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
different. 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. Otherwise Tk_ParseArgv 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
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 argument 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 a 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 corresponding 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 specifiers 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 specifiers 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 arguments. 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 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.
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 does not process any of the remaining
arguments; it returns them all at the beginning of argv (along with any other
unprocessed arguments). In addition, 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 corresponding fields from the argTable
entry, and nextArg will point to the following argument from argv (or NULL if there
are not any more arguments left in argv). If func uses nextArg (so that
Tk_ParseArgv should discard it), then it should return 1. Otherwise it should
return 0 and TkParseArgv will process 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 procedure, and passes that procedure all of the remaining arguments. The
procedure should have the following 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 corresponding 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 had not 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 arguments to the caller. If this bit
is set in flags then Tk_ParseArgv will return an error if it encounters any
argument that does not 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 is not 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 sample 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