home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / man.3 / ParseArgv.3 < prev    next >
Encoding:
Text File  |  1995-07-21  |  18.9 KB  |  546 lines
  1. '\"
  2. '\" Copyright (c) 1990-1992 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/wish/man/RCS/ParseArgv.3,v 1.8 93/08/27 17:11:49 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .\" The definitions below are for supplemental macros used in Tcl/Tk
  24. .\" manual entries.
  25. .\"
  26. .\" .HS name section [date [version]]
  27. .\"    Replacement for .TH in other man pages.  See below for valid
  28. .\"    section names.
  29. .\"
  30. .\" .AP type name in/out [indent]
  31. .\"    Start paragraph describing an argument to a library procedure.
  32. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  33. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  34. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  35. .\"    needed;  use .AS below instead)
  36. .\"
  37. .\" .AS [type [name]]
  38. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  39. .\"    name are examples of largest possible arguments that will be passed
  40. .\"    to .AP later.  If args are omitted, default tab stops are used.
  41. .\"
  42. .\" .BS
  43. .\"    Start box enclosure.  From here until next .BE, everything will be
  44. .\"    enclosed in one large box.
  45. .\"
  46. .\" .BE
  47. .\"    End of box enclosure.
  48. .\"
  49. .\" .VS
  50. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  51. .\"    of man pages.
  52. .\"
  53. .\" .VE
  54. .\"    End of vertical sidebar.
  55. .\"
  56. .\" .DS
  57. .\"    Begin an indented unfilled display.
  58. .\"
  59. .\" .DE
  60. .\"    End of indented unfilled display.
  61. .\"
  62. '\"    # Heading for Tcl/Tk man pages
  63. .de HS
  64. .ds ^3 \\0
  65. .if !"\\$3"" .ds ^3 \\$3
  66. .if '\\$2'cmds'       .TH \\$1 1 \\*(^3 \\$4
  67. .if '\\$2'lib'        .TH \\$1 3 \\*(^3 \\$4
  68. .if '\\$2'tcl'        .TH \\$1 n \\*(^3 Tcl "Tcl Built-In Commands"
  69. .if '\\$2'tk'         .TH \\$1 n \\*(^3 Tk "Tk Commands"
  70. .if '\\$2'tclc'        .TH \\$1 3 \\*(^3 Tcl "Tcl Library Procedures"
  71. .if '\\$2'tkc'         .TH \\$1 3 \\*(^3 Tk "Tk Library Procedures"
  72. .if '\\$2'tclcmds'         .TH \\$1 1 \\*(^3 Tk "Tcl Applications"
  73. .if '\\$2'tkcmds'         .TH \\$1 1 \\*(^3 Tk "Tk Applications"
  74. .if t .wh -1.3i ^B
  75. .nr ^l \\n(.l
  76. .ad b
  77. ..
  78. '\"    # Start an argument description
  79. .de AP
  80. .ie !"\\$4"" .TP \\$4
  81. .el \{\
  82. .   ie !"\\$2"" .TP \\n()Cu
  83. .   el          .TP 15
  84. .\}
  85. .ie !"\\$3"" \{\
  86. .ta \\n()Au \\n()Bu
  87. \&\\$1    \\fI\\$2\\fP    (\\$3)
  88. .\".b
  89. .\}
  90. .el \{\
  91. .br
  92. .ie !"\\$2"" \{\
  93. \&\\$1    \\fI\\$2\\fP
  94. .\}
  95. .el \{\
  96. \&\\fI\\$1\\fP
  97. .\}
  98. .\}
  99. ..
  100. '\"    # define tabbing values for .AP
  101. .de AS
  102. .nr )A 10n
  103. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  104. .nr )B \\n()Au+15n
  105. .\"
  106. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  107. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  108. ..
  109. '\"    # BS - start boxed text
  110. '\"    # ^y = starting y location
  111. '\"    # ^b = 1
  112. .de BS
  113. .br
  114. .mk ^y
  115. .nr ^b 1u
  116. .if n .nf
  117. .if n .ti 0
  118. .if n \l'\\n(.lu\(ul'
  119. .if n .fi
  120. ..
  121. '\"    # BE - end boxed text (draw box now)
  122. .de BE
  123. .nf
  124. .ti 0
  125. .mk ^t
  126. .ie n \l'\\n(^lu\(ul'
  127. .el \{\
  128. .\"    Draw four-sided box normally, but don't draw top of
  129. .\"    box if the box started on an earlier page.
  130. .ie !\\n(^b-1 \{\
  131. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  132. .\}
  133. .el \}\
  134. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  135. .\}
  136. .\}
  137. .fi
  138. .br
  139. .nr ^b 0
  140. ..
  141. '\"    # VS - start vertical sidebar
  142. '\"    # ^Y = starting y location
  143. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  144. .de VS
  145. .mk ^Y
  146. .ie n 'mc \s12\(br\s0
  147. .el .nr ^v 1u
  148. ..
  149. '\"    # VE - end of vertical sidebar
  150. .de VE
  151. .ie n 'mc
  152. .el \{\
  153. .ev 2
  154. .nf
  155. .ti 0
  156. .mk ^t
  157. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  158. .sp -1
  159. .fi
  160. .ev
  161. .\}
  162. .nr ^v 0
  163. ..
  164. '\"    # Special macro to handle page bottom:  finish off current
  165. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  166. '\"    # page bottom macro.
  167. .de ^B
  168. .ev 2
  169. 'ti 0
  170. 'nf
  171. .mk ^t
  172. .if \\n(^b \{\
  173. .\"    Draw three-sided box if this is the box's first page,
  174. .\"    draw two sides but no top otherwise.
  175. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  176. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  177. .\}
  178. .if \\n(^v \{\
  179. .nr ^x \\n(^tu+1v-\\n(^Yu
  180. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  181. .\}
  182. .bp
  183. 'fi
  184. .ev
  185. .if \\n(^b \{\
  186. .mk ^y
  187. .nr ^b 2
  188. .\}
  189. .if \\n(^v \{\
  190. .mk ^Y
  191. .\}
  192. ..
  193. '\"    # DS - begin display
  194. .de DS
  195. .RS
  196. .nf
  197. .sp
  198. ..
  199. '\"    # DE - end display
  200. .de DE
  201. .fi
  202. .RE
  203. .sp .5
  204. ..
  205. .HS Tk_ParseArgv tkc
  206. .BS
  207. .SH NAME
  208. Tk_ParseArgv \- process command-line options
  209. .SH SYNOPSIS
  210. \fB#include <tk.h>\fR
  211. .sp
  212. int
  213. .br
  214. \fBTk_ParseArgv\fR(\fIinterp, tkwin, argcPtr, argv, argTable, flags\fR)
  215. .SH ARGUMENTS
  216. .AS Tk_ArgvInfo *argTable
  217. .AP Tcl_Interp *interp in
  218. Interpreter to use for returning error messages.
  219. .AP Tk_Window tkwin in
  220. Window to use when arguments specify Tk options.  If NULL, then
  221. no Tk options will be processed.
  222. .AP int argcPtr in/out
  223. Pointer to number of arguments in argv;  gets modified to hold
  224. number of unprocessed arguments that remain after the call.
  225. .AP char **argv in/out
  226. Command line arguments passed to main program.  Modified to
  227. hold unprocessed arguments that remain after the call.
  228. .AP Tk_ArgvInfo *argTable in
  229. Array of argument descriptors, terminated by element with
  230. type TK_ARGV_END.
  231. .AP int flags in
  232. If non-zero, then it specifies one or more flags that control the
  233. parsing of arguments.  Different flags may be OR'ed together.
  234. .na
  235. The flags currently defined are TK_ARGV_DONT_SKIP_FIRST_ARG,
  236. TK_ARGV_NO_ABBREV, TK_ARGV_NO_LEFTOVERS, and TK_ARGV_NO_DEFAULTS.
  237. .ad
  238. .BE
  239. .SH DESCRIPTION
  240. .PP
  241. \fBTk_ParseArgv\fR processes an array of command-line arguments according
  242. to a table describing the kinds of arguments that are expected.
  243. Each of the arguments in \fIargv\fR is processed in turn:  if it matches
  244. one of the entries in \fIargTable\fR, the argument is processed
  245. according to that entry and discarded.  The arguments that do not
  246. match anything in \fIargTable\fR are copied down to the beginning
  247. of \fIargv\fR (retaining their original order) and returned to
  248. the caller.  At the end of the call
  249. \fBTk_ParseArgv\fR sets \fI*argcPtr\fR to hold the number of
  250. arguments that are left in \fIargv\fR, and \fIargv[*argcPtr]\fR
  251. will hold the value NULL.  Normally, \fBTk_ParseArgv\fR
  252. assumes that \fIargv[0]\fR is a command name, so it is treated like
  253. an argument that doesn't match \fIargTable\fR and returned to the
  254. caller;  however, if the TK_ARGV_DONT_SKIP_FIRST_ARG bit is set in
  255. \fIflags\fR then \fIargv[0]\fR will be processed just like the other
  256. elements of \fIargv\fR.
  257. .PP
  258. \fBTk_ParseArgv\fR normally returns the value TCL_OK.  If an error
  259. occurs while parsing the arguments, then TCL_ERROR is returned and
  260. \fBTk_ParseArgv\fR will leave an error message in \fIinterp->result\fR
  261. in the standard Tcl fashion.  In
  262. the event of an error return, \fI*argvPtr\fR will not have been
  263. modified, but \fIargv\fR could have been partially modified.  The
  264. possible causes of errors are explained below.
  265. .PP
  266. The \fIargTable\fR array specifies the kinds of arguments that are
  267. expected;  each of its entries has the following structure:
  268. .DS
  269. .ta 2c
  270. \fBtypedef struct\fR {
  271.     \fBchar\fR    *\fIkey\fR;
  272.     \fBint\fR    \fItype\fR;
  273.     \fBchar\fR    *\fIsrc\fR;
  274.     \fBchar\fR    *\fIdst\fR;
  275.     \fBchar\fR    *\fIhelp\fR;
  276. \fB} Tk_ArgvInfo;\fR
  277. .DE
  278. .LP
  279. The \fIkey\fR field is a string such as ``\-display'' or ``\-bg''
  280. that is compared with the values in \fIargv\fR.  \fIType\fR
  281. indicates how to process an argument that matches \fIkey\fR
  282. (more on this below).  \fISrc\fR and \fIdst\fR are additional
  283. values used in processing the argument.  Their exact usage
  284. depends on \fItype\fR, but typically \fIsrc\fR indicates
  285. a value and \fIdst\fR indicates where to store the
  286. value.  The \fBchar *\fR declarations for \fIsrc\fR and \fIdst\fR
  287. are placeholders:  the actual types may be different.  Lastly,
  288. \fIhelp\fR is a string giving a brief description
  289. of this option;  this string is printed when users ask for help
  290. about command-line options.
  291. .PP
  292. When processing an argument in \fIargv\fR, \fBTk_ParseArgv\fR
  293. compares the argument to each of the \fIkey\fR's in \fIargTable\fR.
  294. \fBTk_ParseArgv\fR selects the first specifier whose \fIkey\fR matches
  295. the argument exactly, if such a specifier exists.  Otherwise
  296. \fBTk_ParseArgv\fR selects a specifier for which the argument
  297. is a unique abbreviation.  If the argument is a unique abbreviation
  298. for more than one specifier, then an error is returned.  If there
  299. is no matching entry in \fIargTable\fR, then the argument is
  300. skipped and returned to the caller.
  301. .PP
  302. Once a matching argument specifier is found, \fBTk_ParseArgv\fR
  303. processes the argument according to the \fItype\fR field of the
  304. specifier.  The argument that matched \fIkey\fR is called ``the matching
  305. argument'' in the descriptions below.  As part of the processing,
  306. \fBTk_ParseArgv\fR may also use the next argument in \fIargv\fR
  307. after the matching argument, which is called ``the following
  308. argument''.  The legal values for \fItype\fR, and the processing
  309. that they cause, are as follows:
  310. .TP
  311. \fBTK_ARGV_END\fR
  312. Marks the end of the table.  The last entry in \fIargTable\fR
  313. must have this type;  all of its other fields are ignored and it
  314. will never match any arguments.
  315. .TP
  316. \fBTK_ARGV_CONSTANT\fR
  317. \fISrc\fR is treated as an integer and \fIdst\fR is treated
  318. as a pointer to an integer.  \fISrc\fR is stored at \fI*dst\fR.
  319. The matching argument is discarded.
  320. .TP
  321. \fBTK_ARGV_INT\fR
  322. The following argument must contain an
  323. integer string in the format accepted by \fBstrtol\fR (e.g. ``0''
  324. and ``0x'' prefixes may be used to specify octal or hexadecimal
  325. numbers, respectively).  \fIDst\fR is treated as a pointer to an
  326. integer;  the following argument is converted to an integer value
  327. and stored at \fI*dst\fR.  \fISrc\fR is ignored.  The matching
  328. and following arguments are discarded from \fIargv\fR.
  329. .TP
  330. \fBTK_ARGV_FLOAT\fR
  331. The following argument must contain a floating-point number in
  332. the format accepted by \fBstrtol\fR.
  333. \fIDst\fR is treated as the address of an double-precision
  334. floating point value;  the following argument is converted to a
  335. double-precision value and stored at \fI*dst\fR.  The matching
  336. and following arguments are discarded from \fIargv\fR.
  337. .TP
  338. \fBTK_ARGV_STRING\fR
  339. In this form, \fIdst\fR is treated as a pointer to a (char *);
  340. \fBTk_ParseArgv\fR stores at \fI*dst\fR a pointer to the following
  341. argument, and discards the matching and following arguments from
  342. \fIargv\fR.  \fISrc\fR is ignored.
  343. .TP
  344. \fBTK_ARGV_UID\fR
  345. This form is similar to TK_ARGV_STRING, except that the argument
  346. is turned into a Tk_Uid by calling \fBTk_GetUid\fR.
  347. \fIDst\fR is treated as a pointer to a
  348. Tk_Uid; \fBTk_ParseArgv\fR stores at \fI*dst\fR the Tk_Uid
  349. corresponding to the following
  350. argument, and discards the matching and following arguments from
  351. \fIargv\fR.  \fISrc\fR is ignored.
  352. .TP
  353. \fBTK_ARGV_CONST_OPTION\fR
  354. This form causes a Tk option to be set (as if the \fBoption\fR
  355. command had been invoked).  The \fIsrc\fR field is treated as a
  356. pointer to a string giving the value of an option, and \fIdst\fR
  357. is treated as a pointer to the name of the option.  The matching
  358. argument is discarded.  If \fItkwin\fR is NULL, then argument
  359. specifiers of this type are ignored (as if they did not exist).
  360. .TP
  361. \fBTK_ARGV_OPTION_VALUE\fR
  362. This form is similar to TK_ARGV_CONST_OPTION, except that the
  363. value of the option is taken from the following argument instead
  364. of from \fIsrc\fR.  \fIDst\fR is used as the name of the option.
  365. \fISrc\fR is ignored.  The matching and following arguments
  366. are discarded.  If \fItkwin\fR is NULL, then argument
  367. specifiers of this type are ignored (as if they did not exist).
  368. .TP
  369. \fBTK_ARGV_OPTION_NAME_VALUE\fR
  370. In this case the following argument is taken as the name of a Tk
  371. option and the argument after that is taken as the value for that
  372. option.  Both \fIsrc\fR and \fIdst\fR are ignored.  All three
  373. arguments are discarded from \fIargv\fR.  If \fItkwin\fR is NULL,
  374. then argument
  375. specifiers of this type are ignored (as if they did not exist).
  376. .TP
  377. \fBTK_ARGV_HELP\fR
  378. When this kind of option is encountered, \fBTk_ParseArgv\fR uses the
  379. \fIhelp\fR fields of \fIargTable\fR to format a message describing
  380. all the valid arguments.  The message is placed in \fIinterp->result\fR
  381. and \fBTk_ParseArgv\fR returns TCL_ERROR.  When this happens, the
  382. caller normally prints the help message and aborts.  If the \fIkey\fR
  383. field of a TK_ARGV_HELP specifier is NULL, then the specifier will
  384. never match any arguments;  in this case the specifier simply provides
  385. extra documentation, which will be included when some other
  386. TK_ARGV_HELP entry causes help information to be returned.
  387. .TP
  388. \fBTK_ARGV_REST\fR
  389. This option is used by programs or commands that allow the last
  390. several of their options to be the name and/or options for some
  391. other program.  If a \fBTK_ARGV_REST\fR argument is found, then
  392. \fBTk_ParseArgv\fR doesn't process any
  393. of the remaining arguments;  it returns them all at
  394. the beginning of \fIargv\fR (along with any other unprocessed arguments).
  395. In addition, \fBTk_ParseArgv\fR treats \fIdst\fR as the address of an
  396. integer value, and stores at \fI*dst\fR the index of the first of the
  397. \fBTK_ARGV_REST\fR options in the returned \fIargv\fR.  This allows the
  398. program to distinguish the \fBTK_ARGV_REST\fR options from other
  399. unprocessed options that preceeded the \fBTK_ARGV_REST\fR.
  400. .TP
  401. \fBTK_ARGV_FUNC\fR
  402. For this kind of argument, \fIsrc\fR is treated as the address of
  403. a procedure, which is invoked to process the following argument.
  404. The procedure should have the following structure:
  405. .DS
  406. .ta 1c 2c 3c 4c 5c 6c
  407. \fBint\fI
  408. func(dst, key, nextArg)
  409.     \fBchar\fR    *\fIdst\fR;
  410.     \fBchar\fR    *\fIkey\fR;
  411.     \fBchar\fR    *\fInextArg\fR;
  412. {
  413. }
  414. .DE
  415. .IP
  416. The \fIdst\fR and \fIkey\fR parameters will contain the
  417. corresponding fields from the \fIargTable\fR entry, and
  418. \fInextArg\fR will point to the following argument from \fIargv\fR
  419. (or NULL if there aren't any more arguments left in \fIargv\fR).
  420. If \fIfunc\fR uses \fInextArg\fR (so that
  421. \fBTk_ParseArgv\fR should discard it), then it should return 1.  Otherwise it
  422. should return 0 and \fBTkParseArgv\fR will process the following
  423. argument in the normal fashion.  In either event the matching argument
  424. is discarded.
  425. .TP
  426. \fBTK_ARGV_GENFUNC\fR
  427. This form provides a more general procedural escape.  It treats
  428. \fIsrc\fR as the address of a procedure, and passes that procedure
  429. all of the remaining arguments.  The procedure should have the following
  430. form:
  431. .DS
  432. .ta 1c 2c 3c 4c 5c 6c
  433. \fBint\fI
  434. genfunc(dst, interp, key, argc, argv)
  435.     \fBchar\fR    *\fIdst\fR;
  436.     \fBTcl_Interp\fR    *\fIinterp\fR;
  437.     \fBchar\fR    *\fIkey\fR;
  438.     \fBint\fR    \fIargc\fR;
  439.     \fBchar\fR    **\fIargv\fR;
  440. {
  441. }
  442. .DE
  443. .IP
  444. The \fIdst\fR and \fIkey\fR parameters will contain the
  445. corresponding fields from the \fIargTable\fR entry.  \fIInterp\fR
  446. will be the same as the \fIinterp\fR argument to \fBTcl_ParseArgv\fR.
  447. \fIArgc\fR and \fIargv\fR refer to all of the options after the
  448. matching one.  \fIGenfunc\fR should behave in a fashion similar
  449. to \fBTk_ParseArgv\fR:  parse as many of the remaining arguments as it can,
  450. then return any that are left by compacting them to the beginning of
  451. \fIargv\fR (starting at \fIargv\fR[0]).  \fIGenfunc\fR
  452. should return a count of how many arguments are left in \fIargv\fR;
  453. \fBTk_ParseArgv\fR will process them.  If \fIgenfunc\fR encounters
  454. an error then it should leave an error message in \fIinterp->result\fR,
  455. in the usual Tcl fashion, and return -1;  when this happens
  456. \fBTk_ParseArgv\fR will abort its processing and return TCL_ERROR.
  457.  
  458. .SH "FLAGS"
  459. .IP \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR
  460. \fBTk_ParseArgv\fR normally treats \fIargv[0]\fR as a program
  461. or command name, and returns it to the caller just as if it
  462. hadn't matched \fIargTable\fR.  If this flag is given, then
  463. \fIargv[0]\fR is not given special treatment.
  464. .IP \fBTK_ARGV_NO_ABBREV\fR
  465. Normally, \fBTk_ParseArgv\fR accepts unique abbreviations for
  466. \fIkey\fR values in \fIargTable\fR.  If this flag is given then
  467. only exact matches will be acceptable.
  468. .IP \fBTK_ARGV_NO_LEFTOVERS\fR
  469. Normally, \fBTk_ParseArgv\fR returns unrecognized arguments to the
  470. caller.  If this bit is set in \fIflags\fR then \fBTk_ParseArgv\fR
  471. will return an error if it encounters any argument that doesn't
  472. match \fIargTable\fR.  The only exception to this rule is \fIargv[0]\fR,
  473. which will be returned to the caller with no errors as
  474. long as TK_ARGV_DONT_SKIP_FIRST_ARG isn't specified.
  475. .IP \fBTK_ARGV_NO_DEFAULTS\fR
  476. Normally, \fBTk_ParseArgv\fR searches an internal table of
  477. standard argument specifiers in addition to \fIargTable\fR.  If
  478. this bit is set in \fIflags\fR, then \fBTk_ParseArgv\fR will
  479. use only \fIargTable\fR and not its default table.
  480.  
  481. .SH EXAMPLE
  482. .PP
  483. Here is an example definition of an \fIargTable\fR and
  484. some sample command lines that use the options.  Note the effect
  485. on \fIargc\fR and \fIargv\fR;  arguments processed by \fBTk_ParseArgv\fR
  486. are eliminated from \fIargv\fR, and \fIargc\fR
  487. is updated to reflect reduced number of arguments.
  488. .DS L
  489. \fC/*
  490.  * Define and set default values for globals.
  491.  */
  492. int debugFlag = 0;
  493. int numReps = 100;
  494. char defaultFileName[] = "out";
  495. char *fileName = defaultFileName;
  496. Boolean exec = FALSE;
  497.  
  498. /*
  499.  * Define option descriptions.
  500.  */
  501. Tk_ArgvInfo argTable[] = {
  502.     {"-X", TK_ARGV_CONSTANT, (char *) 1, (char *) &debugFlag,
  503.         "Turn on debugging printfs"},
  504.     {"-N", TK_ARGV_INT, (char *) NULL, (char *) &numReps,
  505.         "Number of repetitions"},
  506.     {"-of", TK_ARGV_STRING, (char *) NULL, (char *) &fileName,
  507.         "Name of file for output"},
  508.     {"x", TK_ARGV_REST, (char *) NULL, (char *) &exec,
  509.         "File to exec, followed by any arguments (must be last argument)."},
  510.     {(char *) NULL, TK_ARGV_END, (char *) NULL, (char *) NULL,
  511.         (char *) NULL}
  512. };
  513.  
  514. main(argc, argv)
  515.     int argc;
  516.     char *argv[];
  517. {
  518.     \&...
  519.  
  520.     if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) {
  521.         fprintf(stderr, "%s\en", interp->result);
  522.         exit(1);
  523.     }
  524.  
  525.     /*
  526.      * Remainder of the program.
  527.      */
  528. }\fR
  529. .DE
  530. .PP
  531. Note that default values can be assigned to variables named in
  532. \fIargTable\fR:  the variables will only be overwritten if the
  533. particular arguments are present in \fIargv\fR.
  534. Here are some example command lines and their effects.
  535. .DS
  536. \fCprog -N 200 infile        # just sets the numReps variable to 200
  537. prog -of out200 infile     # sets fileName to reference "out200"
  538. prog -XN 10 infile        # sets the debug flag, also sets numReps\fR
  539. .DE
  540. In all of the above examples, \fIargc\fR will be set by \fBTk_ParseArgv\fR to 2,
  541. \fIargv\fR[0] will be ``prog'', \fIargv\fR[1] will be ``infile'',
  542. and \fIargv\fR[2] will be NULL.
  543.  
  544. .SH KEYWORDS
  545. arguments, command line, options
  546.