'\" 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.3 2002/01/25 21:09:36 dgp Exp $
-'\"
-'\" The definitions below are for supplemental macros used in Tcl/Tk
-'\" manual entries.
-'\"
-'\" .AP type name in/out ?indent?
-'\" Start paragraph describing an argument to a library procedure.
-'\" type is type of argument (int, etc.), in/out is either "in", "out",
-'\" or "in/out" to describe whether procedure reads or modifies arg,
-'\" and indent is equivalent to second arg of .IP (shouldn't ever be
-'\" needed; use .AS below instead)
-'\"
-'\" .AS ?type? ?name?
-'\" Give maximum sizes of arguments for setting tab stops. Type and
-'\" name are examples of largest possible arguments that will be passed
-'\" to .AP later. If args are omitted, default tab stops are used.
-'\"
-'\" .BS
-'\" Start box enclosure. From here until next .BE, everything will be
-'\" enclosed in one large box.
-'\"
-'\" .BE
-'\" End of box enclosure.
-'\"
-'\" .CS
-'\" Begin code excerpt.
-'\"
-'\" .CE
-'\" End code excerpt.
-'\"
-'\" .VS ?version? ?br?
-'\" Begin vertical sidebar, for use in marking newly-changed parts
-'\" of man pages. The first argument is ignored and used for recording
-'\" the version when the .VS was added, so that the sidebars can be
-'\" found and removed when they reach a certain age. If another argument
-'\" is present, then a line break is forced before starting the sidebar.
-'\"
-'\" .VE
-'\" End of vertical sidebar.
-'\"
-'\" .DS
-'\" Begin an indented unfilled display.
-'\"
-'\" .DE
-'\" End of indented unfilled display.
-'\"
-'\" .SO
-'\" Start of list of standard options for a Tk widget. The
-'\" options follow on successive lines, in four columns separated
-'\" by tabs.
-'\"
-'\" .SE
-'\" End of list of standard options for a Tk widget.
-'\"
-'\" .OP cmdName dbName dbClass
-'\" Start of description of a specific option. cmdName gives the
-'\" option's name as specified in the class command, dbName gives
-'\" the option's name in the option database, and dbClass gives
-'\" the option's class in the option database.
-'\"
-'\" .UL arg1 arg2
-'\" Print arg1 underlined, then print arg2 normally.
-'\"
-'\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
-'\"
-'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
+.TH Tk_ParseArgv 3 "" Tk "Tk Library Procedures"
+.\" The -*- nroff -*- definitions below are for supplemental macros used
+.\" in Tcl/Tk manual entries.
+.\"
+.\" .AP type name in/out ?indent?
+.\" Start paragraph describing an argument to a library procedure.
+.\" type is type of argument (int, etc.), in/out is either "in", "out",
+.\" or "in/out" to describe whether procedure reads or modifies arg,
+.\" and indent is equivalent to second arg of .IP (shouldn't ever be
+.\" needed; use .AS below instead)
+.\"
+.\" .AS ?type? ?name?
+.\" Give maximum sizes of arguments for setting tab stops. Type and
+.\" name are examples of largest possible arguments that will be passed
+.\" to .AP later. If args are omitted, default tab stops are used.
+.\"
+.\" .BS
+.\" Start box enclosure. From here until next .BE, everything will be
+.\" enclosed in one large box.
+.\"
+.\" .BE
+.\" End of box enclosure.
+.\"
+.\" .CS
+.\" Begin code excerpt.
+.\"
+.\" .CE
+.\" End code excerpt.
+.\"
+.\" .VS ?version? ?br?
+.\" Begin vertical sidebar, for use in marking newly-changed parts
+.\" of man pages. The first argument is ignored and used for recording
+.\" the version when the .VS was added, so that the sidebars can be
+.\" found and removed when they reach a certain age. If another argument
+.\" is present, then a line break is forced before starting the sidebar.
+.\"
+.\" .VE
+.\" End of vertical sidebar.
+.\"
+.\" .DS
+.\" Begin an indented unfilled display.
+.\"
+.\" .DE
+.\" End of indented unfilled display.
+.\"
+.\" .SO ?manpage?
+.\" Start of list of standard options for a Tk widget. The manpage
+.\" argument defines where to look up the standard options; if
+.\" omitted, defaults to "options". The options follow on successive
+.\" lines, in three columns separated by tabs.
+.\"
+.\" .SE
+.\" End of list of standard options for a Tk widget.
+.\"
+.\" .OP cmdName dbName dbClass
+.\" Start of description of a specific option. cmdName gives the
+.\" option's name as specified in the class command, dbName gives
+.\" the option's name in the option database, and dbClass gives
+.\" the option's class in the option database.
+.\"
+.\" .UL arg1 arg2
+.\" Print arg1 underlined, then print arg2 normally.
+.\"
+.\" .QW arg1 ?arg2?
+.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
+.\"
+.\" .PQ arg1 ?arg2?
+.\" Print an open parenthesis, arg1 in quotes, then arg2 normally
+.\" (for trailing punctuation) and then a closing parenthesis.
+.\"
+.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
-'\" # Start an argument description
+.\" # Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
-\&\\$1 \\fI\\$2\\fP (\\$3)
+\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.\}
.\}
..
-'\" # define tabbing values for .AP
+.\" # define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
-'\" # BS - start boxed text
-'\" # ^y = starting y location
-'\" # ^b = 1
+.\" # BS - start boxed text
+.\" # ^y = starting y location
+.\" # ^b = 1
.de BS
.br
.mk ^y
.if n \l'\\n(.lu\(ul'
.if n .fi
..
-'\" # BE - end boxed text (draw box now)
+.\" # BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.br
.nr ^b 0
..
-'\" # VS - start vertical sidebar
-'\" # ^Y = starting y location
-'\" # ^v = 1 (for troff; for nroff this doesn't matter)
+.\" # VS - start vertical sidebar
+.\" # ^Y = starting y location
+.\" # ^v = 1 (for troff; for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
-'\" # VE - end of vertical sidebar
+.\" # VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.\}
.nr ^v 0
..
-'\" # Special macro to handle page bottom: finish off current
-'\" # box/sidebar if in box/sidebar mode, then invoked standard
-'\" # page bottom macro.
+.\" # Special macro to handle page bottom: finish off current
+.\" # box/sidebar if in box/sidebar mode, then invoked standard
+.\" # page bottom macro.
.de ^B
.ev 2
'ti 0
.mk ^Y
.\}
..
-'\" # DS - begin display
+.\" # DS - begin display
.de DS
.RS
.nf
.sp
..
-'\" # DE - end display
+.\" # DE - end display
.de DE
.fi
.RE
.sp
..
-'\" # SO - start of list of standard options
+.\" # SO - start of list of standard options
.de SO
+'ie '\\$1'' .ds So \\fBoptions\\fR
+'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
-'\" # SE - end of list of standard options
+.\" # SE - end of list of standard options
.de SE
.fi
.ft R
.LP
-See the \\fBoptions\\fR manual entry for details on the standard options.
+See the \\*(So manual entry for details on the standard options.
..
-'\" # OP - start of full description for a single option
+.\" # OP - start of full description for a single option
.de OP
.LP
.nf
.fi
.IP
..
-'\" # CS - begin code excerpt
+.\" # CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
-'\" # CE - end code excerpt
+.\" # CE - end code excerpt
.de CE
.fi
.RE
..
+.\" # UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..
-.TH Tk_ParseArgv 3 "" Tk "Tk Library Procedures"
+.\" # QW - apply quotation marks to word
+.de QW
+.ie '\\*(lq'"' ``\\$1''\\$2
+.\"" fix emacs highlighting
+.el \\*(lq\\$1\\*(rq\\$2
+..
+.\" # PQ - apply parens and quotation marks to word
+.de PQ
+.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
+.\"" fix emacs highlighting
+.el (\\*(lq\\$1\\*(rq\\$2)\\$3
+..
+.\" # QR - quoted range
+.de QR
+.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
+.\"" fix emacs highlighting
+.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
+..
+.\" # MT - "empty" string
+.de MT
+.QW ""
+..
.BS
.SH NAME
Tk_ParseArgv \- process command-line options
.AP int argcPtr in/out
Pointer to number of arguments in argv; gets modified to hold
number of unprocessed arguments that remain after the call.
-.AP "CONST char" **argv in/out
+.AP "const char" **argv in/out
Command line arguments passed to main program. Modified to
hold unprocessed arguments that remain after the call.
.AP Tk_ArgvInfo *argTable in
Array of argument descriptors, terminated by element with
-type TK_ARGV_END.
+type \fBTK_ARGV_END\fR.
.AP int flags in
If non-zero, then it specifies one or more flags that control the
parsing of arguments. Different flags may be OR'ed together.
-The flags currently defined are TK_ARGV_DONT_SKIP_FIRST_ARG,
-TK_ARGV_NO_ABBREV, TK_ARGV_NO_LEFTOVERS, and TK_ARGV_NO_DEFAULTS.
+The flags currently defined are \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR,
+\fBTK_ARGV_NO_ABBREV\fR, \fBTK_ARGV_NO_LEFTOVERS\fR, and
+\fBTK_ARGV_NO_DEFAULTS\fR.
.BE
.SH DESCRIPTION
.PP
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
-caller; however, if the TK_ARGV_DONT_SKIP_FIRST_ARG bit is set in
+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.
.PP
-\fBTk_ParseArgv\fR normally returns the value TCL_OK. If an error
-occurs while parsing the arguments, then TCL_ERROR is returned and
-\fBTk_ParseArgv\fR will leave an error message in \fIinterp->result\fR
-in the standard Tcl fashion. In
+\fBTk_ParseArgv\fR normally returns the value \fBTCL_OK\fR. If an error
+occurs while parsing the arguments, then \fBTCL_ERROR\fR is returned and
+\fBTk_ParseArgv\fR will leave an error message in the result of
+interpreter \fIinterp\fR in the standard Tcl fashion. In
the event of an error return, \fI*argvPtr\fR will not have been
modified, but \fIargv\fR could have been partially modified. The
possible causes of errors are explained below.
expected; each of its entries has the following structure:
.CS
typedef struct {
- char *\fIkey\fR;
- int \fItype\fR;
- char *\fIsrc\fR;
- char *\fIdst\fR;
- char *\fIhelp\fR;
-} Tk_ArgvInfo;
+ const char *\fIkey\fR;
+ int \fItype\fR;
+ char *\fIsrc\fR;
+ char *\fIdst\fR;
+ const char *\fIhelp\fR;
+} \fBTk_ArgvInfo\fR;
.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
.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
.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
\fBTK_ARGV_FLOAT\fR
The following argument must contain a floating-point number in
the format accepted by \fBstrtol\fR.
-\fIDst\fR is treated as the address of an double-precision
+\fIDst\fR is treated as the address of a double-precision
floating point value; the following argument is converted to a
double-precision value and stored at \fI*dst\fR. The matching
and following arguments are discarded from \fIargv\fR.
\fIargv\fR. \fISrc\fR is ignored.
.TP
\fBTK_ARGV_UID\fR
-This form is similar to TK_ARGV_STRING, except that the argument
+This form is similar to \fBTK_ARGV_STRING\fR, except that the argument
is turned into a Tk_Uid by calling \fBTk_GetUid\fR.
\fIDst\fR is treated as a pointer to a
Tk_Uid; \fBTk_ParseArgv\fR stores at \fI*dst\fR the Tk_Uid
specifiers of this type are ignored (as if they did not exist).
.TP
\fBTK_ARGV_OPTION_VALUE\fR
-This form is similar to TK_ARGV_CONST_OPTION, except that the
+This form is similar to \fBTK_ARGV_CONST_OPTION\fR, except that the
value of the option is taken from the following argument instead
of from \fIsrc\fR. \fIDst\fR is used as the name of the option.
\fISrc\fR is ignored. The matching and following arguments
\fBTK_ARGV_HELP\fR
When this kind of option is encountered, \fBTk_ParseArgv\fR uses the
\fIhelp\fR fields of \fIargTable\fR to format a message describing
-all the valid arguments. The message is placed in \fIinterp->result\fR
-and \fBTk_ParseArgv\fR returns TCL_ERROR. When this happens, the
+all the valid arguments. The message is placed in interpreter
+\fIinterp\fR's result
+and \fBTk_ParseArgv\fR returns \fBTCL_ERROR\fR. When this happens, the
caller normally prints the help message and aborts. If the \fIkey\fR
-field of a TK_ARGV_HELP specifier is NULL, then the specifier will
+field of a \fBTK_ARGV_HELP\fR specifier is NULL, then the specifier will
never match any arguments; in this case the specifier simply provides
extra documentation, which will be included when some other
-TK_ARGV_HELP entry causes help information to be returned.
+\fBTK_ARGV_HELP\fR entry causes help information to be returned.
.TP
\fBTK_ARGV_REST\fR
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
.CS
int
\fIfunc\fR(\fIdst\fR, \fIkey\fR, \fInextArg\fR)
- char *\fIdst\fR;
- char *\fIkey\fR;
- char *\fInextArg\fR;
+ char *\fIdst\fR;
+ char *\fIkey\fR;
+ char *\fInextArg\fR;
{
}
.CE
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
.CS
int
\fIgenfunc\fR(dst, interp, key, argc, argv)
- char *\fIdst\fR;
- Tcl_Interp *\fIinterp\fR;
- char *\fIkey\fR;
- int \fIargc\fR;
- char **\fIargv\fR;
+ char *\fIdst\fR;
+ Tcl_Interp *\fIinterp\fR;
+ char *\fIkey\fR;
+ int \fIargc\fR;
+ char **\fIargv\fR;
{
}
.CE
\fIargv\fR (starting at \fIargv\fR[0]). \fIGenfunc\fR
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
-\fBTk_ParseArgv\fR will abort its processing and return TCL_ERROR.
+an error then it should leave an error message in interpreter
+\fIinterp\fR's result,
+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"
+.SS "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
\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 TK_ARGV_DONT_SKIP_FIRST_ARG 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
* Define option descriptions.
*/
Tk_ArgvInfo argTable[] = {
- {"-X", TK_ARGV_CONSTANT, (char *) 1, (char *) &debugFlag,
- "Turn on debugging printfs"},
- {"-N", TK_ARGV_INT, (char *) NULL, (char *) &numReps,
- "Number of repetitions"},
- {"-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)."},
- {(char *) NULL, TK_ARGV_END, (char *) NULL, (char *) NULL,
- (char *) NULL}
+ {"\-X", TK_ARGV_CONSTANT, (char *) 1, (char *) &debugFlag,
+ "Turn on debugging printfs"},
+ {"\-N", TK_ARGV_INT, (char *) NULL, (char *) &numReps,
+ "Number of repetitions"},
+ {"\-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)."},
+ {(char *) NULL, TK_ARGV_END, (char *) NULL, (char *) NULL,
+ (char *) NULL}
};
main(argc, argv)
- int argc;
- char *argv[];
+ int argc;
+ char *argv[];
{
- \&...
+ \&...
- if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) {
- fprintf(stderr, "%s\en", interp->result);
- exit(1);
- }
+ if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) {
+ fprintf(stderr, "%s\en", Tcl_GetString(Tcl_GetObjResult(interp)));
+ exit(1);
+ }
- /*
- * Remainder of the program.
- */
+ /*
+ * Remainder of the program.
+ */
}
.CE
.PP
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
OSDN Git Service
