summaryrefslogtreecommitdiffstats
path: root/doc/ParseArgv.3
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ParseArgv.3')
-rw-r--r--doc/ParseArgv.358
1 files changed, 33 insertions, 25 deletions
diff --git a/doc/ParseArgv.3 b/doc/ParseArgv.3
index 7a881a8..89438dc 100644
--- a/doc/ParseArgv.3
+++ b/doc/ParseArgv.3
@@ -5,7 +5,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: ParseArgv.3,v 1.8 2007/10/26 20:13:23 dgp Exp $
+'\" RCS: @(#) $Id: ParseArgv.3,v 1.9 2007/10/29 16:04:13 dkf Exp $
'\"
.so man.macros
.TH Tk_ParseArgv 3 "" Tk "Tk Library Procedures"
@@ -55,7 +55,7 @@ the caller. At the end of the call
arguments that are left in \fIargv\fR, and \fIargv[*argcPtr]\fR
will hold the value NULL. Normally, \fBTk_ParseArgv\fR
assumes that \fIargv[0]\fR is a command name, so it is treated like
-an argument that doesn't match \fIargTable\fR and returned to the
+an argument that does not match \fIargTable\fR and returned to the
caller; however, if the \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR bit is set in
\fIflags\fR then \fIargv[0]\fR will be processed just like the other
elements of \fIargv\fR.
@@ -79,7 +79,10 @@ typedef struct {
char *\fIhelp\fR;
} Tk_ArgvInfo;
.CE
-The \fIkey\fR field is a string such as ``\-display'' or ``\-bg''
+The \fIkey\fR field is a string such as
+.QW \-display
+or
+.QW \-bg
that is compared with the values in \fIargv\fR. \fIType\fR
indicates how to process an argument that matches \fIkey\fR
(more on this below). \fISrc\fR and \fIdst\fR are additional
@@ -104,11 +107,13 @@ skipped and returned to the caller.
.PP
Once a matching argument specifier is found, \fBTk_ParseArgv\fR
processes the argument according to the \fItype\fR field of the
-specifier. The argument that matched \fIkey\fR is called ``the matching
-argument'' in the descriptions below. As part of the processing,
+specifier. The argument that matched \fIkey\fR is called
+.QW "the matching argument"
+in the descriptions below. As part of the processing,
\fBTk_ParseArgv\fR may also use the next argument in \fIargv\fR
-after the matching argument, which is called ``the following
-argument''. The legal values for \fItype\fR, and the processing
+after the matching argument, which is called
+.QW "the following argument" .
+The legal values for \fItype\fR, and the processing
that they cause, are as follows:
.TP
\fBTK_ARGV_END\fR
@@ -123,8 +128,11 @@ The matching argument is discarded.
.TP
\fBTK_ARGV_INT\fR
The following argument must contain an
-integer string in the format accepted by \fBstrtol\fR (e.g. ``0''
-and ``0x'' prefixes may be used to specify octal or hexadecimal
+integer string in the format accepted by \fBstrtol\fR (e.g.
+.QW 0
+and
+.QW 0x
+prefixes may be used to specify octal or hexadecimal
numbers, respectively). \fIDst\fR is treated as a pointer to an
integer; the following argument is converted to an integer value
and stored at \fI*dst\fR. \fISrc\fR is ignored. The matching
@@ -192,7 +200,7 @@ extra documentation, which will be included when some other
This option is used by programs or commands that allow the last
several of their options to be the name and/or options for some
other program. If a \fBTK_ARGV_REST\fR argument is found, then
-\fBTk_ParseArgv\fR doesn't process any
+\fBTk_ParseArgv\fR does not process any
of the remaining arguments; it returns them all at
the beginning of \fIargv\fR (along with any other unprocessed arguments).
In addition, \fBTk_ParseArgv\fR treats \fIdst\fR as the address of an
@@ -218,7 +226,7 @@ int
The \fIdst\fR and \fIkey\fR parameters will contain the
corresponding fields from the \fIargTable\fR entry, and
\fInextArg\fR will point to the following argument from \fIargv\fR
-(or NULL if there aren't any more arguments left in \fIargv\fR).
+(or NULL if there are not any more arguments left in \fIargv\fR).
If \fIfunc\fR uses \fInextArg\fR (so that
\fBTk_ParseArgv\fR should discard it), then it should return 1. Otherwise it
should return 0 and \fBTkParseArgv\fR will process the following
@@ -254,16 +262,15 @@ then return any that are left by compacting them to the beginning of
should return a count of how many arguments are left in \fIargv\fR;
\fBTk_ParseArgv\fR will process them. If \fIgenfunc\fR encounters
an error then it should leave an error message in \fIinterp->result\fR,
-in the usual Tcl fashion, and return -1; when this happens
+in the usual Tcl fashion, and return \-1; when this happens
\fBTk_ParseArgv\fR will abort its processing and return \fBTCL_ERROR\fR.
.RE
-
.SH "FLAGS"
.TP
\fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR
\fBTk_ParseArgv\fR normally treats \fIargv[0]\fR as a program
or command name, and returns it to the caller just as if it
-hadn't matched \fIargTable\fR. If this flag is given, then
+had not matched \fIargTable\fR. If this flag is given, then
\fIargv[0]\fR is not given special treatment.
.TP
\fBTK_ARGV_NO_ABBREV\fR
@@ -274,17 +281,16 @@ only exact matches will be acceptable.
\fBTK_ARGV_NO_LEFTOVERS\fR
Normally, \fBTk_ParseArgv\fR returns unrecognized arguments to the
caller. If this bit is set in \fIflags\fR then \fBTk_ParseArgv\fR
-will return an error if it encounters any argument that doesn't
+will return an error if it encounters any argument that does not
match \fIargTable\fR. The only exception to this rule is \fIargv[0]\fR,
which will be returned to the caller with no errors as
-long as \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR isn't specified.
+long as \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR is not specified.
.TP
\fBTK_ARGV_NO_DEFAULTS\fR
Normally, \fBTk_ParseArgv\fR searches an internal table of
standard argument specifiers in addition to \fIargTable\fR. If
this bit is set in \fIflags\fR, then \fBTk_ParseArgv\fR will
use only \fIargTable\fR and not its default table.
-
.SH EXAMPLE
.PP
Here is an example definition of an \fIargTable\fR and
@@ -306,11 +312,11 @@ Boolean exec = FALSE;
* Define option descriptions.
*/
Tk_ArgvInfo argTable[] = {
- {"-X", TK_ARGV_CONSTANT, (char *) 1, (char *) &debugFlag,
+ {"\-X", TK_ARGV_CONSTANT, (char *) 1, (char *) &debugFlag,
"Turn on debugging printfs"},
- {"-N", TK_ARGV_INT, (char *) NULL, (char *) &numReps,
+ {"\-N", TK_ARGV_INT, (char *) NULL, (char *) &numReps,
"Number of repetitions"},
- {"-of", TK_ARGV_STRING, (char *) NULL, (char *) &fileName,
+ {"\-of", TK_ARGV_STRING, (char *) NULL, (char *) &fileName,
"Name of file for output"},
{"x", TK_ARGV_REST, (char *) NULL, (char *) &exec,
"File to exec, followed by any arguments (must be last argument)."},
@@ -340,13 +346,15 @@ Note that default values can be assigned to variables named in
particular arguments are present in \fIargv\fR.
Here are some example command lines and their effects.
.CS
-prog -N 200 infile # just sets the numReps variable to 200
-prog -of out200 infile # sets fileName to reference "out200"
-prog -XN 10 infile # sets the debug flag, also sets numReps
+prog \-N 200 infile # just sets the numReps variable to 200
+prog \-of out200 infile # sets fileName to reference "out200"
+prog \-XN 10 infile # sets the debug flag, also sets numReps
.CE
In all of the above examples, \fIargc\fR will be set by \fBTk_ParseArgv\fR to 2,
-\fIargv\fR[0] will be ``prog'', \fIargv\fR[1] will be ``infile'',
+\fIargv\fR[0] will be
+.QW prog ,
+\fIargv\fR[1] will be
+.QW infile ,
and \fIargv\fR[2] will be NULL.
-
.SH KEYWORDS
arguments, command line, options