Tk_ParseArgv(3) Tk 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
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.
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,
Page 1 (printed 2/26/99)
Tk_ParseArgv(3) Tk Tk_ParseArgv(3)
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 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 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
Page 2 (printed 2/26/99)
Tk_ParseArgv(3) Tk Tk_ParseArgv(3)
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 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.
Page 3 (printed 2/26/99)
Tk_ParseArgv(3) Tk Tk_ParseArgv(3)
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 doesn't process
Page 4 (printed 2/26/99)
Tk_ParseArgv(3) Tk Tk_ParseArgv(3)
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 aren't 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
Page 5 (printed 2/26/99)
Tk_ParseArgv(3) Tk Tk_ParseArgv(3)
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 arguments
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 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;
Page 6 (printed 2/26/99)
Tk_ParseArgv(3) Tk Tk_ParseArgv(3)
/*
* 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
Page 7 (printed 2/26/99)
