diff options
Diffstat (limited to 'doc/ParseArgv.3')
| -rw-r--r-- | doc/ParseArgv.3 | 145 |
1 files changed, 77 insertions, 68 deletions
diff --git a/doc/ParseArgv.3 b/doc/ParseArgv.3 index 07c7551..b7592b7 100644 --- a/doc/ParseArgv.3 +++ b/doc/ParseArgv.3 @@ -26,17 +26,18 @@ no Tk options will be processed. .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 @@ -52,13 +53,13 @@ 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 -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 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 \fIinterp->result\fR in the standard Tcl fashion. In the event of an error return, \fI*argvPtr\fR will not have been @@ -69,14 +70,17 @@ The \fIargTable\fR array specifies the kinds of arguments that are 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; + char *\fIkey\fR; + int \fItype\fR; + char *\fIsrc\fR; + char *\fIdst\fR; + 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 @@ -101,11 +105,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 @@ -120,8 +126,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 @@ -130,7 +139,7 @@ and following arguments are discarded from \fIargv\fR. \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. @@ -142,7 +151,7 @@ argument, and discards the matching and following arguments from \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 @@ -159,7 +168,7 @@ argument is discarded. If \fItkwin\fR is NULL, then argument 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 @@ -178,18 +187,18 @@ specifiers of this type are ignored (as if they did not exist). 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 +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 @@ -206,16 +215,16 @@ The procedure should have the following structure: .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 @@ -232,11 +241,11 @@ form: .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 @@ -251,16 +260,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 -\fBTk_ParseArgv\fR will abort its processing and return TCL_ERROR. +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 @@ -271,17 +279,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 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 @@ -303,32 +310,32 @@ Boolean exec = FALSE; * 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", interp->result); + exit(1); + } - /* - * Remainder of the program. - */ + /* + * Remainder of the program. + */ } .CE .PP @@ -337,13 +344,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 |