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 doesn't 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 com‐
80 pared with the values in argv. Type indicates how to process an argu‐
81 ment that matches key (more on this below). Src and dst are additional
82 values 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 descrip‐
101 tions below. As part of the processing, Tk_ParseArgv may also use the
102 next argument in argv after the matching argument, which is called
103 ``the following argument''. The legal values for type, and the pro‐
104 cessing that 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 an double-precision floating point value; the following argu‐
129 ment is converted to a double-precision value and stored at
130 *dst. The matching and following arguments are discarded from
131 argv.
132 TK_ARGV_STRING
134 In this form, dst is treated as a pointer to a (char *);
135 Tk_ParseArgv stores at *dst a pointer to the following argument,
136 and discards the matching and following arguments from argv.
137 Src is ignored.
138 TK_ARGV_UID
140 This form is similar to TK_ARGV_STRING, except that the argument
141 is turned into a Tk_Uid by calling Tk_GetUid. Dst is treated as
142 a pointer to a Tk_Uid; Tk_ParseArgv stores at *dst the Tk_Uid
143 corresponding to the following argument, and discards the match‐
144 ing and following arguments from argv. Src is ignored.
145 TK_ARGV_CONST_OPTION
147 This form causes a Tk option to be set (as if the option command
148 had been invoked). The src field is treated as a pointer to a
149 string giving the value of an option, and dst is treated as a
150 pointer to the name of the option. The matching argument is
151 discarded. If tkwin is NULL, then argument specifiers of this
152 type are ignored (as if they did not exist).
153 TK_ARGV_OPTION_VALUE
155 This form is similar to TK_ARGV_CONST_OPTION, except that the
156 value of the option is taken from the following argument instead
157 of from src. Dst is used as the name of the option. Src is
158 ignored. The matching and following arguments are discarded.
159 If tkwin is NULL, then argument specifiers of this type are
160 ignored (as if they did not exist).
161 TK_ARGV_OPTION_NAME_VALUE
163 In this case the following argument is taken as the name of a Tk
164 option and the argument after that is taken as the value for
165 that option. Both src and dst are ignored. All three arguments
166 are discarded from argv. If tkwin is NULL, then argument speci‐
167 fiers of this type are ignored (as if they did not exist).
168 TK_ARGV_HELP
170 When this kind of option is encountered, Tk_ParseArgv uses the
171 help fields of argTable to format a message describing all the
172 valid arguments. The message is placed in interp->result and
173 Tk_ParseArgv returns TCL_ERROR. When this happens, the caller
174 normally prints the help message and aborts. If the key field
175 of a TK_ARGV_HELP specifier is NULL, then the specifier will
176 never match any arguments; in this case the specifier simply
177 provides extra documentation, which will be included when some
178 other TK_ARGV_HELP entry causes help information to be 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 doesn't process any of the remaining arguments; it
185 returns them all at the beginning of argv (along with any other
186 unprocessed arguments). In addition, Tk_ParseArgv treats dst as
187 the address of an integer value, and stores at *dst the index of
188 the first of the TK_ARGV_REST options in the returned argv.
189 This allows the program to distinguish the TK_ARGV_REST options
190 from other unprocessed options that preceded the 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 aren't 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
241 TK_ARGV_DONT_SKIP_FIRST_ARG
242 Tk_ParseArgv normally treats argv[0] as a program or command
243 name, and returns it to the caller just as if it hadn't matched
244 argTable. If this flag is given, then argv[0] is not given spe‐
245 cial treatment.
246 TK_ARGV_NO_ABBREV
248 Normally, Tk_ParseArgv accepts unique abbreviations for key val‐
249 ues in argTable. If this flag is given then only exact matches
250 will be acceptable.
251 TK_ARGV_NO_LEFTOVERS
253 Normally, Tk_ParseArgv returns unrecognized arguments to the
254 caller. If this bit is set in flags then Tk_ParseArgv will
255 return an error if it encounters any argument that doesn't match
256 argTable. The only exception to this rule is argv[0], which
257 will be returned to the caller with no errors as long as
258 TK_ARGV_DONT_SKIP_FIRST_ARG isn't specified.
259 TK_ARGV_NO_DEFAULTS
261 Normally, Tk_ParseArgv searches an internal table of standard
262 argument specifiers in addition to argTable. If this bit is set
263 in flags, then Tk_ParseArgv will use only argTable and not its
264 default table.
265
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", interp->result);
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
322 be NULL.
323
326 arguments, command line, options
327Tk Tk_ParseArgv(3)