1Tk_ParseArgv(3) Tk Library Procedures Tk_ParseArgv(3)
2______________________________________________________________________________
6
8 Tk_ParseArgv - process command-line options
9
11 #include <tk.h>
12 int
14 Tk_ParseArgv(interp, tkwin, argcPtr, argv, argTable, flags)
15
17 Tcl_Interp *interp (in) Interpreter to use for returning
18 error messages.
19 Tk_Window tkwin (in) Window to use when arguments spec‐
21 ify Tk options. If NULL, then no
22 Tk options will be processed.
23 int argcPtr (in/out) Pointer to number of arguments in
25 argv; gets modified to hold number
26 of unprocessed arguments that
27 remain after the call.
28 const char **argv (in/out) Command line arguments passed to
30 main program. Modified to hold
31 unprocessed arguments that remain
32 after the call.
33 Tk_ArgvInfo *argTable (in) Array of argument descriptors, ter‐
35 minated by element with type
36 TK_ARGV_END.
37 int flags (in) If non-zero, then it specifies one
39 or more flags that control the
40 parsing of arguments. Different
41 flags may be OR'ed together. The
42 flags currently defined are
43 TK_ARGV_DONT_SKIP_FIRST_ARG,
44 TK_ARGV_NO_ABBREV, TK_ARGV_NO_LEFT‐
45 OVERS, and TK_ARGV_NO_DEFAULTS.
46______________________________________________________________________________
47
49 Tk_ParseArgv processes an array of command-line arguments according to
50 a table describing the kinds of arguments that are expected. Each of
51 the arguments in argv is processed in turn: if it matches one of the
52 entries in argTable, the argument is processed according to that entry
53 and discarded. The arguments that do not match anything in argTable
54 are copied down to the beginning of argv (retaining their original
55 order) and returned to the caller. At the end of the call Tk_ParseArgv
56 sets *argcPtr to hold the number of arguments that are left in argv,
57 and argv[*argcPtr] will hold the value NULL. Normally, Tk_ParseArgv
58 assumes that argv[0] is a command name, so it is treated like an argu‐
59 ment that does not match argTable and returned to the caller; however,
60 if the TK_ARGV_DONT_SKIP_FIRST_ARG bit is set in flags then argv[0]
61 will be processed just like the other elements of argv.
62 Tk_ParseArgv normally returns the value TCL_OK. If an error occurs
64 while parsing the arguments, then TCL_ERROR is returned and
65 Tk_ParseArgv will leave an error message in the result of interpreter
66 interp in the standard Tcl fashion. In the event of an error return,
67 *argvPtr will not have been modified, but argv could have been par‐
68 tially modified. The possible causes of errors are explained below.
69 The argTable array specifies the kinds of arguments that are expected;
71 each of its entries has the following structure:
72 typedef struct {
73 const char *key;
74 int type;
75 char *src;
76 char *dst;
77 const char *help;
78 } Tk_ArgvInfo;
79 The key field is a string such as “-display” or “-bg” that is compared
80 with the values in argv. Type indicates how to process an argument
81 that matches key (more on this below). Src and dst are additional val‐
82 ues used in processing the argument. Their exact usage depends on
83 type, but typically src indicates a value and dst indicates where to
84 store the value. The char * declarations for src and dst are place‐
85 holders: the actual types may be different. Lastly, help is a string
86 giving a brief description of this option; this string is printed when
87 users ask for help about command-line options.
88 When processing an argument in argv, Tk_ParseArgv compares the argument
90 to each of the key's in argTable. Tk_ParseArgv selects the first spec‐
91 ifier whose key matches the argument exactly, if such a specifier
92 exists. Otherwise Tk_ParseArgv selects a specifier for which the argu‐
93 ment is a unique abbreviation. If the argument is a unique abbrevia‐
94 tion for more than one specifier, then an error is returned. If there
95 is no matching entry in argTable, then the argument is skipped and
96 returned to the caller.
97 Once a matching argument specifier is found, Tk_ParseArgv processes the
99 argument according to the type field of the specifier. The argument
100 that matched key is called “the matching argument” in the descriptions
101 below. As part of the processing, Tk_ParseArgv may also use the next
102 argument in argv after the matching argument, which is called “the fol‐
103 lowing argument”. The legal values for type, and the processing that
104 they cause, are as follows:
105 TK_ARGV_END
107 Marks the end of the table. The last entry in argTable must
108 have this type; all of its other fields are ignored and it will
109 never match any arguments.
110 TK_ARGV_CONSTANT
112 Src is treated as an integer and dst is treated as a pointer to
113 an integer. Src is stored at *dst. The matching argument is
114 discarded.
115 TK_ARGV_INT
117 The following argument must contain an integer string in the
118 format accepted by strtol (e.g. “0” and “0x” prefixes may be
119 used to specify octal or hexadecimal numbers, respectively).
120 Dst is treated as a pointer to an integer; the following argu‐
121 ment is converted to an integer value and stored at *dst. Src
122 is ignored. The matching and following arguments are discarded
123 from argv.
124 TK_ARGV_FLOAT
126 The following argument must contain a floating-point number in
127 the format accepted by strtol. Dst is treated as the address of
128 a double-precision floating point value; the following argument
129 is converted to a double-precision value and stored at *dst.
130 The matching and following arguments are discarded from argv.
131 TK_ARGV_STRING
133 In this form, dst is treated as a pointer to a (char *);
134 Tk_ParseArgv stores at *dst a pointer to the following argument,
135 and discards the matching and following arguments from argv.
136 Src is ignored.
137 TK_ARGV_UID
139 This form is similar to TK_ARGV_STRING, except that the argument
140 is turned into a Tk_Uid by calling Tk_GetUid. Dst is treated as
141 a pointer to a Tk_Uid; Tk_ParseArgv stores at *dst the Tk_Uid
142 corresponding to the following argument, and discards the match‐
143 ing and following arguments from argv. Src is ignored.
144 TK_ARGV_CONST_OPTION
146 This form causes a Tk option to be set (as if the option command
147 had been invoked). The src field is treated as a pointer to a
148 string giving the value of an option, and dst is treated as a
149 pointer to the name of the option. The matching argument is
150 discarded. If tkwin is NULL, then argument specifiers of this
151 type are ignored (as if they did not exist).
152 TK_ARGV_OPTION_VALUE
154 This form is similar to TK_ARGV_CONST_OPTION, except that the
155 value of the option is taken from the following argument instead
156 of from src. Dst is used as the name of the option. Src is
157 ignored. The matching and following arguments are discarded.
158 If tkwin is NULL, then argument specifiers of this type are
159 ignored (as if they did not exist).
160 TK_ARGV_OPTION_NAME_VALUE
162 In this case the following argument is taken as the name of a Tk
163 option and the argument after that is taken as the value for
164 that option. Both src and dst are ignored. All three arguments
165 are discarded from argv. If tkwin is NULL, then argument speci‐
166 fiers of this type are ignored (as if they did not exist).
167 TK_ARGV_HELP
169 When this kind of option is encountered, Tk_ParseArgv uses the
170 help fields of argTable to format a message describing all the
171 valid arguments. The message is placed in interpreter interp's
172 result and Tk_ParseArgv returns TCL_ERROR. When this happens,
173 the caller normally prints the help message and aborts. If the
174 key field of a TK_ARGV_HELP specifier is NULL, then the speci‐
175 fier will never match any arguments; in this case the specifier
176 simply provides extra documentation, which will be included when
177 some other TK_ARGV_HELP entry causes help information to be
178 returned.
179 TK_ARGV_REST
181 This option is used by programs or commands that allow the last
182 several of their options to be the name and/or options for some
183 other program. If a TK_ARGV_REST argument is found, then
184 Tk_ParseArgv does not process any of the remaining arguments;
185 it returns them all at the beginning of argv (along with any
186 other unprocessed arguments). In addition, Tk_ParseArgv treats
187 dst as the address of an integer value, and stores at *dst the
188 index of the first of the TK_ARGV_REST options in the returned
189 argv. This allows the program to distinguish the TK_ARGV_REST
190 options from other unprocessed options that preceded the
191 TK_ARGV_REST.
192 TK_ARGV_FUNC
194 For this kind of argument, src is treated as the address of a
195 procedure, which is invoked to process the following argument.
196 The procedure should have the following structure:
197 int
198 func(dst, key, nextArg)
199 char *dst;
200 char *key;
201 char *nextArg;
202 {
203 }
204 The dst and key parameters will contain the corresponding fields
205 from the argTable entry, and nextArg will point to the following
206 argument from argv (or NULL if there are not any more arguments
207 left in argv). If func uses nextArg (so that Tk_ParseArgv
208 should discard it), then it should return 1. Otherwise it
209 should return 0 and TkParseArgv will process the following argu‐
210 ment in the normal fashion. In either event the matching argu‐
211 ment is discarded.
212 TK_ARGV_GENFUNC
214 This form provides a more general procedural escape. It treats
215 src as the address of a procedure, and passes that procedure all
216 of the remaining arguments. The procedure should have the fol‐
217 lowing form:
218 int
219 genfunc(dst, interp, key, argc, argv)
220 char *dst;
221 Tcl_Interp *interp;
222 char *key;
223 int argc;
224 char **argv;
225 {
226 }
227 The dst and key parameters will contain the corresponding fields
228 from the argTable entry. Interp will be the same as the interp
229 argument to Tcl_ParseArgv. Argc and argv refer to all of the
230 options after the matching one. Genfunc should behave in a
231 fashion similar to Tk_ParseArgv: parse as many of the remaining
232 arguments as it can, then return any that are left by compacting
233 them to the beginning of argv (starting at argv[0]). Genfunc
234 should return a count of how many arguments are left in argv;
235 Tk_ParseArgv will process them. If genfunc encounters an error
236 then it should leave an error message in interpreter interp's
237 result, in the usual Tcl fashion, and return -1; when this hap‐
238 pens Tk_ParseArgv will abort its processing and return
239 TCL_ERROR.
240 FLAGS
242 TK_ARGV_DONT_SKIP_FIRST_ARG
243 Tk_ParseArgv normally treats argv[0] as a program or command
244 name, and returns it to the caller just as if it had not matched
245 argTable. If this flag is given, then argv[0] is not given spe‐
246 cial treatment.
247 TK_ARGV_NO_ABBREV
249 Normally, Tk_ParseArgv accepts unique abbreviations for key val‐
250 ues in argTable. If this flag is given then only exact matches
251 will be acceptable.
252 TK_ARGV_NO_LEFTOVERS
254 Normally, Tk_ParseArgv returns unrecognized arguments to the
255 caller. If this bit is set in flags then Tk_ParseArgv will
256 return an error if it encounters any argument that does not
257 match argTable. The only exception to this rule is argv[0],
258 which will be returned to the caller with no errors as long as
259 TK_ARGV_DONT_SKIP_FIRST_ARG is not specified.
260 TK_ARGV_NO_DEFAULTS
262 Normally, Tk_ParseArgv searches an internal table of standard
263 argument specifiers in addition to argTable. If this bit is set
264 in flags, then Tk_ParseArgv will use only argTable and not its
265 default table.
266
268 Here is an example definition of an argTable and some sample command
269 lines that use the options. Note the effect on argc and argv; argu‐
270 ments processed by Tk_ParseArgv are eliminated from argv, and argc is
271 updated to reflect reduced number of arguments.
272 /*
273 * Define and set default values for globals.
274 */
275 int debugFlag = 0;
276 int numReps = 100;
277 char defaultFileName[] = "out";
278 char *fileName = defaultFileName;
279 Boolean exec = FALSE;
280 /*
282 * Define option descriptions.
283 */
284 Tk_ArgvInfo argTable[] = {
285 {"-X", TK_ARGV_CONSTANT, (char *) 1, (char *) &debugFlag,
286 "Turn on debugging printfs"},
287 {"-N", TK_ARGV_INT, (char *) NULL, (char *) &numReps,
288 "Number of repetitions"},
289 {"-of", TK_ARGV_STRING, (char *) NULL, (char *) &fileName,
290 "Name of file for output"},
291 {"x", TK_ARGV_REST, (char *) NULL, (char *) &exec,
292 "File to exec, followed by any arguments (must be last argument)."},
293 {(char *) NULL, TK_ARGV_END, (char *) NULL, (char *) NULL,
294 (char *) NULL}
295 };
296 main(argc, argv)
298 int argc;
299 char *argv[];
300 {
301 ...
302 if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) {
304 fprintf(stderr, "%s\n", Tcl_GetString(Tcl_GetObjResult(interp)));
305 exit(1);
306 }
307 /*
309 * Remainder of the program.
310 */
311 }
312 Note that default values can be assigned to variables named in
314 argTable: the variables will only be overwritten if the particular
315 arguments are present in argv. Here are some example command lines and
316 their effects.
317 prog -N 200 infile # just sets the numReps variable to 200
318 prog -of out200 infile # sets fileName to reference "out200"
319 prog -XN 10 infile # sets the debug flag, also sets numReps
320 In all of the above examples, argc will be set by Tk_ParseArgv to 2,
321 argv[0] will be “prog”, argv[1] will be “infile”, and argv[2] will be
322 NULL.
323
325 arguments, command line, options
326Tk Tk_ParseArgv(3)