通讯编程

开发平台：
Visual C++

ParseArgv.3：源码内容
							'"
'" 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: ParseArgv.3,v 1.3 2002/01/25 21:09:36 dgp Exp $
'" 
.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_ParseArgvfR(fIinterp, tkwin, argcPtr, argv, argTable, flagsfR)
.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_ParseArgvfR processes an array of command-line arguments according
to a table describing the kinds of arguments that are expected.
Each of the arguments in fIargvfR is processed in turn:  if it matches
one of the entries in fIargTablefR, the argument is processed
according to that entry and discarded.  The arguments that do not
match anything in fIargTablefR are copied down to the beginning
of fIargvfR (retaining their original order) and returned to
the caller.  At the end of the call
fBTk_ParseArgvfR sets fI*argcPtrfR to hold the number of
arguments that are left in fIargvfR, and fIargv[*argcPtr]fR
will hold the value NULL.  Normally, fBTk_ParseArgvfR
assumes that fIargv[0]fR is a command name, so it is treated like
an argument that doesn't match fIargTablefR and returned to the
caller;  however, if the TK_ARGV_DONT_SKIP_FIRST_ARG bit is set in
fIflagsfR then fIargv[0]fR will be processed just like the other
elements of fIargvfR.
.PP
fBTk_ParseArgvfR normally returns the value TCL_OK.  If an error
occurs while parsing the arguments, then TCL_ERROR is returned and
fBTk_ParseArgvfR will leave an error message in fIinterp->resultfR
in the standard Tcl fashion.  In
the event of an error return, fI*argvPtrfR will not have been
modified, but fIargvfR could have been partially modified.  The
possible causes of errors are explained below.
.PP
The fIargTablefR array specifies the kinds of arguments that are
expected;  each of its entries has the following structure:
.CS
typedef struct {
	char *fIkeyfR;
	int fItypefR;
	char *fIsrcfR;
	char *fIdstfR;
	char *fIhelpfR;
} Tk_ArgvInfo;
.CE
The fIkeyfR field is a string such as ``-display'' or ``-bg''
that is compared with the values in fIargvfR.  fITypefR
indicates how to process an argument that matches fIkeyfR
(more on this below).  fISrcfR and fIdstfR are additional
values used in processing the argument.  Their exact usage
depends on fItypefR, but typically fIsrcfR indicates
a value and fIdstfR indicates where to store the
value.  The fBchar *fR declarations for fIsrcfR and fIdstfR
are placeholders:  the actual types may be different.  Lastly,
fIhelpfR 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 fIargvfR, fBTk_ParseArgvfR
compares the argument to each of the fIkeyfR's in fIargTablefR.
fBTk_ParseArgvfR selects the first specifier whose fIkeyfR matches
the argument exactly, if such a specifier exists.  Otherwise
fBTk_ParseArgvfR 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 fIargTablefR, then the argument is
skipped and returned to the caller.
.PP
Once a matching argument specifier is found, fBTk_ParseArgvfR
processes the argument according to the fItypefR field of the
specifier.  The argument that matched fIkeyfR is called ``the matching
argument'' in the descriptions below.  As part of the processing,
fBTk_ParseArgvfR may also use the next argument in fIargvfR
after the matching argument, which is called ``the following
argument''.  The legal values for fItypefR, and the processing
that they cause, are as follows:
.TP
fBTK_ARGV_ENDfR
Marks the end of the table.  The last entry in fIargTablefR
must have this type;  all of its other fields are ignored and it
will never match any arguments.
.TP
fBTK_ARGV_CONSTANTfR
fISrcfR is treated as an integer and fIdstfR is treated
as a pointer to an integer.  fISrcfR is stored at fI*dstfR.
The matching argument is discarded.
.TP
fBTK_ARGV_INTfR
The following argument must contain an
integer string in the format accepted by fBstrtolfR (e.g. ``0''
and ``0x'' prefixes may be used to specify octal or hexadecimal
numbers, respectively).  fIDstfR is treated as a pointer to an
integer;  the following argument is converted to an integer value
and stored at fI*dstfR.  fISrcfR is ignored.  The matching
and following arguments are discarded from fIargvfR.
.TP
fBTK_ARGV_FLOATfR
The following argument must contain a floating-point number in
the format accepted by fBstrtolfR.
fIDstfR 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*dstfR.  The matching
and following arguments are discarded from fIargvfR.
.TP
fBTK_ARGV_STRINGfR
In this form, fIdstfR is treated as a pointer to a (char *);
fBTk_ParseArgvfR stores at fI*dstfR a pointer to the following
argument, and discards the matching and following arguments from
fIargvfR.  fISrcfR is ignored.
.TP
fBTK_ARGV_UIDfR
This form is similar to TK_ARGV_STRING, except that the argument
is turned into a Tk_Uid by calling fBTk_GetUidfR.
fIDstfR is treated as a pointer to a
Tk_Uid; fBTk_ParseArgvfR stores at fI*dstfR the Tk_Uid
corresponding to the following
argument, and discards the matching and following arguments from
fIargvfR.  fISrcfR is ignored.
.TP
fBTK_ARGV_CONST_OPTIONfR
This form causes a Tk option to be set (as if the fBoptionfR
command had been invoked).  The fIsrcfR field is treated as a
pointer to a string giving the value of an option, and fIdstfR
is treated as a pointer to the name of the option.  The matching
argument is discarded.  If fItkwinfR is NULL, then argument
specifiers of this type are ignored (as if they did not exist).
.TP
fBTK_ARGV_OPTION_VALUEfR
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 fIsrcfR.  fIDstfR is used as the name of the option.
fISrcfR is ignored.  The matching and following arguments
are discarded.  If fItkwinfR is NULL, then argument
specifiers of this type are ignored (as if they did not exist).
.TP
fBTK_ARGV_OPTION_NAME_VALUEfR
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 fIsrcfR and fIdstfR are ignored.  All three
arguments are discarded from fIargvfR.  If fItkwinfR is NULL,
then argument
specifiers of this type are ignored (as if they did not exist).
.TP
fBTK_ARGV_HELPfR
When this kind of option is encountered, fBTk_ParseArgvfR uses the
fIhelpfR fields of fIargTablefR to format a message describing
all the valid arguments.  The message is placed in fIinterp->resultfR
and fBTk_ParseArgvfR returns TCL_ERROR.  When this happens, the
caller normally prints the help message and aborts.  If the fIkeyfR
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_RESTfR
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_RESTfR argument is found, then
fBTk_ParseArgvfR doesn't process any
of the remaining arguments;  it returns them all at
the beginning of fIargvfR (along with any other unprocessed arguments).
In addition, fBTk_ParseArgvfR treats fIdstfR as the address of an
integer value, and stores at fI*dstfR the index of the first of the
fBTK_ARGV_RESTfR options in the returned fIargvfR.  This allows the
program to distinguish the fBTK_ARGV_RESTfR options from other
unprocessed options that preceded the fBTK_ARGV_RESTfR.
.TP
fBTK_ARGV_FUNCfR
For this kind of argument, fIsrcfR 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
fIfuncfR(fIdstfR, fIkeyfR, fInextArgfR)
	char *fIdstfR;
	char *fIkeyfR;
	char *fInextArgfR;
{
}
.CE
The fIdstfR and fIkeyfR parameters will contain the
corresponding fields from the fIargTablefR entry, and
fInextArgfR will point to the following argument from fIargvfR
(or NULL if there aren't any more arguments left in fIargvfR).
If fIfuncfR uses fInextArgfR (so that
fBTk_ParseArgvfR should discard it), then it should return 1.  Otherwise it
should return 0 and fBTkParseArgvfR will process the following
argument in the normal fashion.  In either event the matching argument
is discarded.
.RE
.TP
fBTK_ARGV_GENFUNCfR
This form provides a more general procedural escape.  It treats
fIsrcfR 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
fIgenfuncfR(dst, interp, key, argc, argv)
	char *fIdstfR;
	Tcl_Interp *fIinterpfR;
	char *fIkeyfR;
	int fIargcfR;
	char **fIargvfR;
{
}
.CE
The fIdstfR and fIkeyfR parameters will contain the
corresponding fields from the fIargTablefR entry.  fIInterpfR
will be the same as the fIinterpfR argument to fBTcl_ParseArgvfR.
fIArgcfR and fIargvfR refer to all of the options after the
matching one.  fIGenfuncfR should behave in a fashion similar
to fBTk_ParseArgvfR:  parse as many of the remaining arguments as it can,
then return any that are left by compacting them to the beginning of
fIargvfR (starting at fIargvfR[0]).  fIGenfuncfR
should return a count of how many arguments are left in fIargvfR;
fBTk_ParseArgvfR will process them.  If fIgenfuncfR encounters
an error then it should leave an error message in fIinterp->resultfR,
in the usual Tcl fashion, and return -1;  when this happens
fBTk_ParseArgvfR will abort its processing and return TCL_ERROR.
.RE
.SH "FLAGS"
.TP
fBTK_ARGV_DONT_SKIP_FIRST_ARGfR
fBTk_ParseArgvfR normally treats fIargv[0]fR as a program
or command name, and returns it to the caller just as if it
hadn't matched fIargTablefR.  If this flag is given, then
fIargv[0]fR is not given special treatment.
.TP
fBTK_ARGV_NO_ABBREVfR
Normally, fBTk_ParseArgvfR accepts unique abbreviations for
fIkeyfR values in fIargTablefR.  If this flag is given then
only exact matches will be acceptable.
.TP
fBTK_ARGV_NO_LEFTOVERSfR
Normally, fBTk_ParseArgvfR returns unrecognized arguments to the
caller.  If this bit is set in fIflagsfR then fBTk_ParseArgvfR
will return an error if it encounters any argument that doesn't
match fIargTablefR.  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_DEFAULTSfR
Normally, fBTk_ParseArgvfR searches an internal table of
standard argument specifiers in addition to fIargTablefR.  If
this bit is set in fIflagsfR, then fBTk_ParseArgvfR will
use only fIargTablefR and not its default table.
.SH EXAMPLE
.PP
Here is an example definition of an fIargTablefR and
some sample command lines that use the options.  Note the effect
on fIargcfR and fIargvfR;  arguments processed by fBTk_ParseArgvfR
are eliminated from fIargvfR, and fIargcfR
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, "%sen", interp->result);
		exit(1);
	}
	/*
	 * Remainder of the program.
	 */
}
.CE
.PP
Note that default values can be assigned to variables named in
fIargTablefR:  the variables will only be overwritten if the
particular arguments are present in fIargvfR.
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, fIargcfR will be set by fBTk_ParseArgvfR to 2,
fIargvfR[0] will be ``prog'', fIargvfR[1] will be ``infile'',
and fIargvfR[2] will be NULL.
.SH KEYWORDS
arguments, command line, options

						