NAME¶

SYNOPSIS¶

#include <tk.h>
 
int
Tk_ParseArgv(interp, tkwin, argcPtr, argv, argTable, flags)

ARGUMENTS¶

Tcl_Interp *interp (in)

Interpreter to use for returning error messages.

Tk_Window tkwin (in)

Window to use when arguments specify Tk options. If NULL, then no Tk options will be processed.

int argcPtr (in/out)

Pointer to number of arguments in argv; gets modified to hold number of unprocessed arguments that remain after the call.

CONST char **argv (in/out)

Command line arguments passed to main program. Modified to hold unprocessed arguments that remain after the call.

Tk_ArgvInfo *argTable (in)

Array of argument descriptors, terminated by element with type TK_ARGV_END.

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.

 

DESCRIPTION¶

typedef struct {
	char * key;
	int  type;
	char * src;
	char * dst;
	char * help;
} Tk_ArgvInfo;

TK_ARGV_END

Marks the end of the table. The last entry in argTable must have this type; all of its other fields are ignored and it will never match any arguments.

TK_ARGV_CONSTANT

Src is treated as an integer and dst is treated as a pointer to an integer. Src is stored at *dst. The matching argument is discarded.

TK_ARGV_INT

The following argument must contain an integer string in the format accepted by strtol (e.g. ``0'' and ``0x'' prefixes may be used to specify octal or hexadecimal numbers, respectively). Dst is treated as a pointer to an integer; the following argument is converted to an integer value and stored at *dst. Src is ignored. The matching and following arguments are discarded from argv.

TK_ARGV_FLOAT

The following argument must contain a floating-point number in the format accepted by strtol. Dst 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 *dst. The matching and following arguments are discarded from argv.

TK_ARGV_STRING

In this form, dst is treated as a pointer to a (char *); Tk_ParseArgv stores at *dst a pointer to the following argument, and discards the matching and following arguments from argv. Src is ignored.

TK_ARGV_UID

This form is similar to TK_ARGV_STRING, except that the argument is turned into a Tk_Uid by calling Tk_GetUid. Dst is treated as a pointer to a Tk_Uid; Tk_ParseArgv stores at *dst the Tk_Uid corresponding to the following argument, and discards the matching and following arguments from argv. Src is ignored.

TK_ARGV_CONST_OPTION

This form causes a Tk option to be set (as if the option command had been invoked). The src field is treated as a pointer to a string giving the value of an option, and dst is treated as a pointer to the name of the option. The matching argument is discarded. If tkwin is NULL, then argument specifiers of this type are ignored (as if they did not exist).

TK_ARGV_OPTION_VALUE

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 src. Dst is used as the name of the option. Src is ignored. The matching and following arguments are discarded. If tkwin is NULL, then argument specifiers of this type are ignored (as if they did not exist).

TK_ARGV_OPTION_NAME_VALUE

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 src and dst are ignored. All three arguments are discarded from argv. If tkwin is NULL, then argument specifiers of this type are ignored (as if they did not exist).

TK_ARGV_HELP

When this kind of option is encountered, Tk_ParseArgv uses the help fields of argTable to format a message describing all the valid arguments. The message is placed in interp->result and Tk_ParseArgv returns TCL_ERROR. When this happens, the caller normally prints the help message and aborts. If the key 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.

TK_ARGV_REST

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 TK_ARGV_REST argument is found, then Tk_ParseArgv doesn't process any of the remaining arguments; it returns them all at the beginning of argv (along with any other unprocessed arguments). In addition, Tk_ParseArgv treats dst as the address of an integer value, and stores at *dst the index of the first of the TK_ARGV_REST options in the returned argv. This allows the program to distinguish the TK_ARGV_REST options from other unprocessed options that preceded the TK_ARGV_REST.

TK_ARGV_FUNC

For this kind of argument, src is treated as the address of a procedure, which is invoked to process the following argument. The procedure should have the following structure:

int
func(dst, key, nextArg)
	char * dst;
	char * key;
	char * nextArg;
{
}

TK_ARGV_GENFUNC

This form provides a more general procedural escape. It treats src as the address of a procedure, and passes that procedure all of the remaining arguments. The procedure should have the following form:

int
genfunc(dst, interp, key, argc, argv)
	char * dst;
	Tcl_Interp * interp;
	char * key;
	int  argc;
	char ** argv;
{
}

FLAGS¶

TK_ARGV_DONT_SKIP_FIRST_ARG

Tk_ParseArgv normally treats argv[0] as a program or command name, and returns it to the caller just as if it hadn't matched argTable. If this flag is given, then argv[0] is not given special treatment.

TK_ARGV_NO_ABBREV

Normally, Tk_ParseArgv accepts unique abbreviations for key values in argTable. If this flag is given then only exact matches will be acceptable.

TK_ARGV_NO_LEFTOVERS

Normally, Tk_ParseArgv returns unrecognized arguments to the caller. If this bit is set in flags then Tk_ParseArgv will return an error if it encounters any argument that doesn't match argTable. The only exception to this rule is argv[0], which will be returned to the caller with no errors as long as TK_ARGV_DONT_SKIP_FIRST_ARG isn't specified.

TK_ARGV_NO_DEFAULTS

Normally, Tk_ParseArgv searches an internal table of standard argument specifiers in addition to argTable. If this bit is set in flags, then Tk_ParseArgv will use only argTable and not its default table.

 

EXAMPLE¶

/*
 * 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\n", interp->result);
		exit(1);
	}

	/*
	 * Remainder of the program.
	 */
}

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

KEYWORDS¶