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 interp->result in the stan‐
66 dard Tcl fashion. In the event of an error return, *argvPtr will not
67 have been modified, but argv could have been partially modified. The
68 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 char *key;
74 int type;
75 char *src;
76 char *dst;
77 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 interp->result and
172 Tk_ParseArgv returns TCL_ERROR. When this happens, the caller
173 normally prints the help message and aborts. If the key field
174 of a TK_ARGV_HELP specifier is NULL, then the specifier will
175 never match any arguments; in this case the specifier simply
176 provides extra documentation, which will be included when some
177 other TK_ARGV_HELP entry causes help information to be returned.
178 TK_ARGV_REST
180 This option is used by programs or commands that allow the last
181 several of their options to be the name and/or options for some
182 other program. If a TK_ARGV_REST argument is found, then
183 Tk_ParseArgv does not process any of the remaining arguments;
184 it returns them all at the beginning of argv (along with any
185 other unprocessed arguments). In addition, Tk_ParseArgv treats
186 dst as the address of an integer value, and stores at *dst the
187 index of the first of the TK_ARGV_REST options in the returned
188 argv. This allows the program to distinguish the TK_ARGV_REST
189 options from other unprocessed options that preceded the
190 TK_ARGV_REST.
191 TK_ARGV_FUNC
193 For this kind of argument, src is treated as the address of a
194 procedure, which is invoked to process the following argument.
195 The procedure should have the following structure:
196 int
197 func(dst, key, nextArg)
198 char *dst;
199 char *key;
200 char *nextArg;
201 {
202 }
203 The dst and key parameters will contain the corresponding fields
204 from the argTable entry, and nextArg will point to the following
205 argument from argv (or NULL if there are not any more arguments
206 left in argv). If func uses nextArg (so that Tk_ParseArgv
207 should discard it), then it should return 1. Otherwise it
208 should return 0 and TkParseArgv will process the following argu‐
209 ment in the normal fashion. In either event the matching argu‐
210 ment is discarded.
211 TK_ARGV_GENFUNC
213 This form provides a more general procedural escape. It treats
214 src as the address of a procedure, and passes that procedure all
215 of the remaining arguments. The procedure should have the fol‐
216 lowing form:
217 int
218 genfunc(dst, interp, key, argc, argv)
219 char *dst;
220 Tcl_Interp *interp;
221 char *key;
222 int argc;
223 char **argv;
224 {
225 }
226 The dst and key parameters will contain the corresponding fields
227 from the argTable entry. Interp will be the same as the interp
228 argument to Tcl_ParseArgv. Argc and argv refer to all of the
229 options after the matching one. Genfunc should behave in a
230 fashion similar to Tk_ParseArgv: parse as many of the remaining
231 arguments as it can, then return any that are left by compacting
232 them to the beginning of argv (starting at argv[0]). Genfunc
233 should return a count of how many arguments are left in argv;
234 Tk_ParseArgv will process them. If genfunc encounters an error
235 then it should leave an error message in interp->result, in the
236 usual Tcl fashion, and return -1; when this happens
237 Tk_ParseArgv will abort its processing and return TCL_ERROR.
238
240 TK_ARGV_DONT_SKIP_FIRST_ARG
241 Tk_ParseArgv normally treats argv[0] as a program or command
242 name, and returns it to the caller just as if it had not matched
243 argTable. If this flag is given, then argv[0] is not given spe‐
244 cial treatment.
245 TK_ARGV_NO_ABBREV
247 Normally, Tk_ParseArgv accepts unique abbreviations for key val‐
248 ues in argTable. If this flag is given then only exact matches
249 will be acceptable.
250 TK_ARGV_NO_LEFTOVERS
252 Normally, Tk_ParseArgv returns unrecognized arguments to the
253 caller. If this bit is set in flags then Tk_ParseArgv will
254 return an error if it encounters any argument that does not
255 match argTable. The only exception to this rule is argv[0],
256 which will be returned to the caller with no errors as long as
257 TK_ARGV_DONT_SKIP_FIRST_ARG is not specified.
258 TK_ARGV_NO_DEFAULTS
260 Normally, Tk_ParseArgv searches an internal table of standard
261 argument specifiers in addition to argTable. If this bit is set
262 in flags, then Tk_ParseArgv will use only argTable and not its
263 default table.
264
266 Here is an example definition of an argTable and some sample command
267 lines that use the options. Note the effect on argc and argv; argu‐
268 ments processed by Tk_ParseArgv are eliminated from argv, and argc is
269 updated to reflect reduced number of arguments.
270 /*
271 * Define and set default values for globals.
272 */
273 int debugFlag = 0;
274 int numReps = 100;
275 char defaultFileName[] = "out";
276 char *fileName = defaultFileName;
277 Boolean exec = FALSE;
278 /*
280 * Define option descriptions.
281 */
282 Tk_ArgvInfo argTable[] = {
283 {"-X", TK_ARGV_CONSTANT, (char *) 1, (char *) &debugFlag,
284 "Turn on debugging printfs"},
285 {"-N", TK_ARGV_INT, (char *) NULL, (char *) &numReps,
286 "Number of repetitions"},
287 {"-of", TK_ARGV_STRING, (char *) NULL, (char *) &fileName,
288 "Name of file for output"},
289 {"x", TK_ARGV_REST, (char *) NULL, (char *) &exec,
290 "File to exec, followed by any arguments (must be last argument)."},
291 {(char *) NULL, TK_ARGV_END, (char *) NULL, (char *) NULL,
292 (char *) NULL}
293 };
294 main(argc, argv)
296 int argc;
297 char *argv[];
298 {
299 ...
300 if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) {
302 fprintf(stderr, "%s\n", interp->result);
303 exit(1);
304 }
305 /*
307 * Remainder of the program.
308 */
309 }
310 Note that default values can be assigned to variables named in
312 argTable: the variables will only be overwritten if the particular
313 arguments are present in argv. Here are some example command lines and
314 their effects.
315 prog -N 200 infile # just sets the numReps variable to 200
316 prog -of out200 infile # sets fileName to reference "out200"
317 prog -XN 10 infile # sets the debug flag, also sets numReps
318 In all of the above examples, argc will be set by Tk_ParseArgv to 2,
319 argv[0] will be “prog”, argv[1] will be “infile”, and argv[2] will be
320 NULL.
321
323 arguments, command line, options
324Tk Tk_ParseArgv(3)