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