1Tk_ParseArgv(3)              Tk Library Procedures             Tk_ParseArgv(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tk_ParseArgv - process command-line options
9

SYNOPSIS

11       #include <tk.h>
12
13       int
14       Tk_ParseArgv(interp, tkwin, argcPtr, argv, argTable, flags)
15

ARGUMENTS

17       Tcl_Interp *interp (in)             Interpreter  to  use  for returning
18                                           error messages.
19
20       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
24       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
29       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
34       Tk_ArgvInfo *argTable (in)          Array of argument descriptors, ter‐
35                                           minated   by   element   with  type
36                                           TK_ARGV_END.
37
38       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

DESCRIPTION

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
63       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
70       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
89       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
98       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
106       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
111       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
116       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
125       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
132       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
138       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
145       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
153       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
161       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
168       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
180       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
193       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
213       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
241   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
248       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
253       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
261       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

EXAMPLE

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
281              /*
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, NULL, (char *) &numReps,
288                      "Number of repetitions"},
289                  {"-of", TK_ARGV_STRING, NULL, (char *) &fileName,
290                      "Name of file for output"},
291                  {"x", TK_ARGV_REST, NULL, (char *) &exec,
292                      "File to exec, followed by any arguments (must be last argument)."},
293                  {NULL, TK_ARGV_END, NULL, NULL,
294                      NULL}
295              };
296
297              main(argc, argv)
298                  int argc;
299                  char *argv[];
300              {
301                  ...
302
303                  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
308                  /*
309                   * Remainder of the program.
310                   */
311              }
312
313       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

KEYWORDS

325       arguments, command line, options
326
327
328
329Tk                                                             Tk_ParseArgv(3)
Impressum