diff options
Diffstat (limited to 'tcl/doc/ParseArgv.3')
| -rw-r--r-- | tcl/doc/ParseArgv.3 | 351 |
1 files changed, 0 insertions, 351 deletions
diff --git a/tcl/doc/ParseArgv.3 b/tcl/doc/ParseArgv.3 deleted file mode 100644 index 4fc886d2fe0..00000000000 --- a/tcl/doc/ParseArgv.3 +++ /dev/null @@ -1,351 +0,0 @@ -'\" -'\" Copyright (c) 1990-1992 The Regents of the University of California. -'\" Copyright (c) 1994-1996 Sun Microsystems, Inc. -'\" -'\" See the file "license.terms" for information on usage and redistribution -'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. -'\" -'\" RCS: @(#) $Id$ -'\" -.so man.macros -.TH Tk_ParseArgv 3 "" Tk "Tk Library Procedures" -.BS -.SH NAME -Tk_ParseArgv \- process command-line options -.SH SYNOPSIS -.nf -\fB#include <tk.h>\fR -.sp -int -\fBTk_ParseArgv\fR(\fIinterp, tkwin, argcPtr, argv, argTable, flags\fR) -.SH ARGUMENTS -.AS Tk_ArgvInfo *argTable -.AP Tcl_Interp *interp in -Interpreter to use for returning error messages. -.AP Tk_Window tkwin in -Window to use when arguments specify Tk options. If NULL, then -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 -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. -.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. -.BE -.SH DESCRIPTION -.PP -\fBTk_ParseArgv\fR processes an array of command-line arguments according -to a table describing the kinds of arguments that are expected. -Each of the arguments in \fIargv\fR is processed in turn: if it matches -one of the entries in \fIargTable\fR, the argument is processed -according to that entry and discarded. The arguments that do not -match anything in \fIargTable\fR are copied down to the beginning -of \fIargv\fR (retaining their original order) and returned to -the caller. At the end of the call -\fBTk_ParseArgv\fR sets \fI*argcPtr\fR to hold the number of -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 -\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 -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. -.PP -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; -} Tk_ArgvInfo; -.CE -The \fIkey\fR field is a string such as ``\-display'' or ``\-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 -values used in processing the argument. Their exact usage -depends on \fItype\fR, but typically \fIsrc\fR indicates -a value and \fIdst\fR indicates where to store the -value. The \fBchar *\fR declarations for \fIsrc\fR and \fIdst\fR -are placeholders: the actual types may be different. Lastly, -\fIhelp\fR is a string giving a brief description -of this option; this string is printed when users ask for help -about command-line options. -.PP -When processing an argument in \fIargv\fR, \fBTk_ParseArgv\fR -compares the argument to each of the \fIkey\fR's in \fIargTable\fR. -\fBTk_ParseArgv\fR selects the first specifier whose \fIkey\fR matches -the argument exactly, if such a specifier exists. Otherwise -\fBTk_ParseArgv\fR selects a specifier for which the argument -is a unique abbreviation. If the argument is a unique abbreviation -for more than one specifier, then an error is returned. If there -is no matching entry in \fIargTable\fR, then the argument is -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, -\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 -that they cause, are as follows: -.TP -\fBTK_ARGV_END\fR -Marks the end of the table. The last entry in \fIargTable\fR -must have this type; all of its other fields are ignored and it -will never match any arguments. -.TP -\fBTK_ARGV_CONSTANT\fR -\fISrc\fR is treated as an integer and \fIdst\fR is treated -as a pointer to an integer. \fISrc\fR is stored at \fI*dst\fR. -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 -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 -and following arguments are discarded from \fIargv\fR. -.TP -\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 -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. -.TP -\fBTK_ARGV_STRING\fR -In this form, \fIdst\fR is treated as a pointer to a (char *); -\fBTk_ParseArgv\fR stores at \fI*dst\fR a pointer to the following -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 -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 -corresponding to the following -argument, and discards the matching and following arguments from -\fIargv\fR. \fISrc\fR is ignored. -.TP -\fBTK_ARGV_CONST_OPTION\fR -This form causes a Tk option to be set (as if the \fBoption\fR -command had been invoked). The \fIsrc\fR field is treated as a -pointer to a string giving the value of an option, and \fIdst\fR -is treated as a pointer to the name of the option. The matching -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 -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 -are discarded. If \fItkwin\fR is NULL, then argument -specifiers of this type are ignored (as if they did not exist). -.TP -\fBTK_ARGV_OPTION_NAME_VALUE\fR -In this case the following argument is taken as the name of a Tk -option and the argument after that is taken as the value for that -option. Both \fIsrc\fR and \fIdst\fR are ignored. All three -arguments are discarded from \fIargv\fR. If \fItkwin\fR is NULL, -then argument -specifiers of this type are ignored (as if they did not exist). -.TP -\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 -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 -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. -.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 -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 -integer value, and stores at \fI*dst\fR the index of the first of the -\fBTK_ARGV_REST\fR options in the returned \fIargv\fR. This allows the -program to distinguish the \fBTK_ARGV_REST\fR options from other -unprocessed options that preceded the \fBTK_ARGV_REST\fR. -.TP -\fBTK_ARGV_FUNC\fR -For this kind of argument, \fIsrc\fR is treated as the address of -a procedure, which is invoked to process the following argument. -The procedure should have the following structure: -.RS -.CS -int -\fIfunc\fR(\fIdst\fR, \fIkey\fR, \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). -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 -argument in the normal fashion. In either event the matching argument -is discarded. -.RE -.TP -\fBTK_ARGV_GENFUNC\fR -This form provides a more general procedural escape. It treats -\fIsrc\fR as the address of a procedure, and passes that procedure -all of the remaining arguments. The procedure should have the following -form: -.RS -.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; -{ -} -.CE -The \fIdst\fR and \fIkey\fR parameters will contain the -corresponding fields from the \fIargTable\fR entry. \fIInterp\fR -will be the same as the \fIinterp\fR argument to \fBTcl_ParseArgv\fR. -\fIArgc\fR and \fIargv\fR refer to all of the options after the -matching one. \fIGenfunc\fR should behave in a fashion similar -to \fBTk_ParseArgv\fR: parse as many of the remaining arguments as it can, -then return any that are left by compacting them to the beginning of -\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. -.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 -\fIargv[0]\fR is not given special treatment. -.TP -\fBTK_ARGV_NO_ABBREV\fR -Normally, \fBTk_ParseArgv\fR accepts unique abbreviations for -\fIkey\fR values in \fIargTable\fR. If this flag is given then -only exact matches will be acceptable. -.TP -\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 -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. -.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 -some sample command lines that use the options. Note the effect -on \fIargc\fR and \fIargv\fR; arguments processed by \fBTk_ParseArgv\fR -are eliminated from \fIargv\fR, and \fIargc\fR -is updated to reflect reduced number of arguments. -.CS -/* - * Define and set default values for globals. - */ -int debugFlag = 0; -int numReps = 100; -char defaultFileName[] = "out"; -char *fileName = defaultFileName; -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} -}; - -main(argc, argv) - int argc; - char *argv[]; -{ - \&... - - if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) { - fprintf(stderr, "%s\en", interp->result); - exit(1); - } - - /* - * Remainder of the program. - */ -} -.CE -.PP -Note that default values can be assigned to variables named in -\fIargTable\fR: the variables will only be overwritten if the -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 -.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'', -and \fIargv\fR[2] will be NULL. - -.SH KEYWORDS -arguments, command line, options |