NAME
TkParseArgv - process command-line options
SYNOPSIS
##iinncclluuddee <
int TTkkPPaarrsseeAArrggvv(interp, tkwin, argcPtr, argv, argTable, flags) AARRGGUUMMEENNTTSS TclInterp *interp (in) Interpreter to use for returning error messages.> TkWindow tkwin (in) Window to use when arguments spec-
ify 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.TkArgvInfo *argTable (in) Array of argument descriptors, ter-
minated by element with type TKARGVEND.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 TKARGVDONTSKIPFIRSTARG,TKARGVNOABBREV, TKARGVNOLEFT-
OVERS, and TKARGVNODEFAULTS.DESCRIPTION
TTkkPPaarrsseeAArrggvv 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 TTkkPPaarrsseeAArrggvv sets *argcPtr to hold the number of arguments that are left in argv, and argv[*argcPtr] will hold the value NULL. Normally, TTkkPPaarrsseeAArrggvvassumes that argv[0] is a command name, so it is treated like an argu-
ment that doesn't match argTable and returned to the caller; however, if the TKARGVDONTSKIPFIRSTARG bit is set in flags then argv[0] will be processed just like the other elements of argv. TTkkPPaarrsseeAArrggvv normally returns the value TCLOK. If an error occurswhile parsing the arguments, then TCLERROR is returned and
TTkkPPaarrsseeAArrggvv will leave an error message in interp->result in the stan-
dard 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; } TkArgvInfo;The key field is a string such as ``-display'' or ``-bg'' that is com-
pared with the values in argv. Type indicates how to process an argu-
ment 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 tostore the value. The cchhaarr ** declarations for src and dst are place-
holders: the actual types may be different. Lastly, help is a string giving a brief description of this option; this string is printed whenusers ask for help about command-line options.
When processing an argument in argv, TTkkPPaarrsseeAArrggvv compares the argumentto each of the key's in argTable. TTkkPPaarrsseeAArrggvv selects the first spec-
ifier whose key matches the argument exactly, if such a specifierexists. Otherwise TTkkPPaarrsseeAArrggvv selects a specifier for which the argu-
ment is a unique abbreviation. If the argument is a unique abbrevia-
tion 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, TTkkPPaarrsseeAArrggvv processes the argument according to the type field of the specifier. The argumentthat matched key is called ``the matching argument'' in the descrip-
tions below. As part of the processing, TTkkPPaarrsseeAArrggvv 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 pro-
cessing that they cause, are as follows: TTKKAARRGGVVEENNDD 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. TTKKAARRGGVVCCOONNSSTTAANNTT 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. TTKKAARRGGVVIINNTT The following argument must contain an integer string in the format accepted by ssttrrttooll (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 argu-
ment is converted to an integer value and stored at *dst. Src is ignored. The matching and following arguments are discarded from argv. TTKKAARRGGVVFFLLOOAATTThe following argument must contain a floating-point number in
the format accepted by ssttrrttooll. Dst is treated as the address ofan double-precision floating point value; the following argu-
ment is converted to a double-precision value and stored at
*dst. The matching and following arguments are discarded from argv. TTKKAARRGGVVSSTTRRIINNGG In this form, dst is treated as a pointer to a (char *); TTkkPPaarrsseeAArrggvv stores at *dst a pointer to the following argument, and discards the matching and following arguments from argv. Src is ignored. TTKKAARRGGVVUUIIDD This form is similar to TKARGVSTRING, except that the argument is turned into a TkUid by calling TTkkGGeettUUiidd. Dst is treated as a pointer to a TkUid; TTkkPPaarrsseeAArrggvv stores at *dst the TkUidcorresponding to the following argument, and discards the match-
ing and following arguments from argv. Src is ignored. TTKKAARRGGVVCCOONNSSTTOOPPTTIIOONN This form causes a Tk option to be set (as if the ooppttiioonn 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). TTKKAARRGGVVOOPPTTIIOONNVVAALLUUEEThis form is similar to TKARGVCONSTOPTION, 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).TKARGVOPTIONNAMEVALUE
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 argumentsare discarded from argv. If tkwin is NULL, then argument speci-
fiers of this type are ignored (as if they did not exist). TTKKAARRGGVVHHEELLPP When this kind of option is encountered, TTkkPPaarrsseeAArrggvv uses the help fields of argTable to format a message describing all thevalid arguments. The message is placed in interp->result and
TTkkPPaarrsseeAArrggvv returns TCLERROR. When this happens, the caller
normally prints the help message and aborts. If the key field of a TKARGVHELP 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 TKARGVHELP entry causes help information to be returned. TTKKAARRGGVVRREESSTT 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 TTKKAARRGGVVRREESSTT argument is found, then TTkkPPaarrsseeAArrggvv doesn't process any of the remaining arguments; it returns them all at the beginning of argv (along with any other unprocessed arguments). In addition, TTkkPPaarrsseeAArrggvv treats dst as the address of an integer value, and stores at *dst the index of the first of the TTKKAARRGGVVRREESSTT options in the returned argv. This allows the program to distinguish the TTKKAARRGGVVRREESSTT options from other unprocessed options that preceded the TTKKAARRGGVVRREESSTT. TTKKAARRGGVVFFUUNNCC 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 TTkkPPaarrsseeAArrggvv should discard it), then it should return 1. Otherwise itshould return 0 and TTkkPPaarrsseeAArrggvv will process the following argu-
ment in the normal fashion. In either event the matching argu-
ment is discarded. TTKKAARRGGVVGGEENNFFUUNNCC This form provides a more general procedural escape. It treats src as the address of a procedure, and passes that procedure allof the remaining arguments. The procedure should have the fol-
lowing form: int genfunc(dst, interp, key, argc, argv) char *dst; TclInterp *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 TTccllPPaarrsseeAArrggvv. Argc and argv refer to all of the options after the matching one. Genfunc should behave in a fashion similar to TTkkPPaarrsseeAArrggvv: 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; TTkkPPaarrsseeAArrggvv will process them. If genfunc encounters an errorthen it should leave an error message in interp->result, in the
usual Tcl fashion, and return -1; when this happens
TTkkPPaarrsseeAArrggvv will abort its processing and return TCLERROR.
FFLLAAGGSS TTKKAARRGGVVDDOONNTTSSKKIIPPFFIIRRSSTTAARRGG TTkkPPaarrsseeAArrggvv normally treats argv[0] as a program or command name, and returns it to the caller just as if it hadn't matchedargTable. If this flag is given, then argv[0] is not given spe-
cial treatment. TTKKAARRGGVVNNOOAABBBBRREEVVNormally, TTkkPPaarrsseeAArrggvv accepts unique abbreviations for key val-
ues in argTable. If this flag is given then only exact matches will be acceptable. TTKKAARRGGVVNNOOLLEEFFTTOOVVEERRSS Normally, TTkkPPaarrsseeAArrggvv returns unrecognized arguments to the caller. If this bit is set in flags then TTkkPPaarrsseeAArrggvv 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 TKARGVDONTSKIPFIRSTARG isn't specified. TTKKAARRGGVVNNOODDEEFFAAUULLTTSS Normally, TTkkPPaarrsseeAArrggvv searches an internal table of standard argument specifiers in addition to argTable. If this bit is set in flags, then TTkkPPaarrsseeAArrggvv will use only argTable and not its default table. EEXXAAMMPPLLEE Here is an example definition of an argTable and some sample commandlines that use the options. Note the effect on argc and argv; argu-
ments processed by TTkkPPaarrsseeAArrggvv 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. */ TkArgvInfo argTable[] = {{"-X", TKARGVCONSTANT, (char *) 1, (char *) &debugFlag,
"Turn on debugging printfs"},{"-N", TKARGVINT, (char *) NULL, (char *) &numReps,
"Number of repetitions"},{"-of", TKARGVSTRING, (char *) NULL, (char *) &fileName,
"Name of file for output"}, {"x", TKARGVREST, (char *) NULL, (char *) &exec, "File to exec, followed by any arguments (must be last argument)."}, {(char *) NULL, TKARGVEND, (char *) NULL, (char *) NULL, (char *) NULL} }; main(argc, argv) int argc; char *argv[]; { ... if (TkParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCLOK) {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 TTkkPPaarrsseeAArrggvv to 2, argv[0] will be ``prog'', argv[1] will be ``infile'', and argv[2] will be NULL. KKEEYYWWOORRDDSS arguments, command line, options Tk TkParseArgv(3)