diff options
Diffstat (limited to 'doc/ParseArgv.3')
| -rw-r--r-- | doc/ParseArgv.3 | 351 |
1 files changed, 351 insertions, 0 deletions
diff --git a/doc/ParseArgv.3 b/doc/ParseArgv.3 new file mode 100644 index 0000000..8a1e854 --- /dev/null +++ b/doc/ParseArgv.3 @@ -0,0 +1,351 @@ +'\" +'\" 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. +'\" +'\" SCCS: @(#) ParseArgv.3 1.17 97/10/31 12:58:44 +'\" +.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 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 |