HPUX ParseArgv[3]
ParseArgv in anderen Kapiteln des hpux Handbuch:
Tk_ParseArgv(3) Tk Tk_ParseArgv(3)
Tk Library Procedures Tk Library Procedures
___________________________________________________________________________
NAME
Tk_ParseArgv - process command-line options
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.
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
Tk_ParseArgv processes an array of command-line arguments according to
a table describing the kinds of arguments that are expected. Each of
the arguments in argv is processed in turn: if it matches one of the
entries in argTable, the argument is processed according to that entry
- 1 - Formatted: August 11, 1996
Tk_ParseArgv(3) Tk Tk_ParseArgv(3)
Tk Library Procedures Tk Library Procedures
and discarded. The arguments that do not match anything in argTable
are copied down to the beginning of argv (retaining their original
order) and returned to the caller. At the end of the call
Tk_ParseArgv sets *argcPtr to hold the number of arguments that are
left in argv, and argv[*argcPtr] will hold the value NULL. Normally,
Tk_ParseArgv assumes that argv[0] is a command name, so it is treated
like an argument that doesn't match argTable and returned to the
caller; however, if the TK_ARGV_DONT_SKIP_FIRST_ARG bit is set in
flags then argv[0] will be processed just like the other elements of
argv.
Tk_ParseArgv normally returns the value TCL_OK. If an error occurs
while parsing the arguments, then TCL_ERROR is returned and
Tk_ParseArgv will leave an error message in interp->result in the
standard Tcl fashion. In the event of an error return, *argvPtr will
not have been modified, but argv could have been partially modified.
The possible causes of errors are explained below.
The argTable array specifies the kinds of arguments that are expected;
each of its entries has the following structure:
typedef struct {
char*key;
int type;
char*src;
char*dst;
char*help;
} Tk_ArgvInfo;
The key field is a string such as ``-display'' or ``-bg'' that is
compared with the values in argv. Type indicates how to process an
argument that matches key (more on this below). Src and dst are
additional values used in processing the argument. Their exact usage
depends on type, but typically src indicates a value and dst indicates
where to store the value. The char * declarations for src and dst are
placeholders: the actual types may be different. Lastly, help is a
string giving a brief description of this option; this string is
printed when users ask for help about command-line options.
When processing an argument in argv, Tk_ParseArgv compares the
argument to each of the key's in argTable. Tk_ParseArgv selects the
first specifier whose key matches the argument exactly, if such a
specifier exists. Otherwise Tk_ParseArgv 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 argTable, then the
argument is skipped and returned to the caller.
Once a matching argument specifier is found, Tk_ParseArgv processes
the argument according to the type field of the specifier. The
- 2 - Formatted: August 11, 1996
Tk_ParseArgv(3) Tk Tk_ParseArgv(3)
Tk Library Procedures Tk Library Procedures
argument that matched key is called ``the matching argument'' in the
descriptions below. As part of the processing, Tk_ParseArgv may also
use the next argument in argv after the matching argument, which is
called ``the following argument''. The legal values for type, and the
processing that they cause, are as follows:
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
- 3 - Formatted: August 11, 1996
Tk_ParseArgv(3) Tk Tk_ParseArgv(3)
Tk Library Procedures Tk Library Procedures
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 preceeded 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)
- 4 - Formatted: August 11, 1996
Tk_ParseArgv(3) Tk Tk_ParseArgv(3)
Tk Library Procedures Tk Library Procedures
char *dst;
char *key;
char *nextArg;
{
}
The dst and key parameters will contain the corresponding fields
from the argTable entry, and nextArg will point to the following
argument from argv (or NULL if there aren't any more arguments
left in argv). If func uses nextArg (so that Tk_ParseArgv should
discard it), then it should return 1. Otherwise it should return
0 and TkParseArgv will process the following argument in the
normal fashion. In either event the matching argument is
discarded.
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;
{
}
The dst and key parameters will contain the corresponding fields
from the argTable entry. Interp will be the same as the interp
argument to Tcl_ParseArgv. Argc and argv refer to all of the
options after the matching one. Genfunc should behave in a
fashion similar to Tk_ParseArgv: parse as many of the remaining
arguments as it can, then return any that are left by compacting
them to the beginning of argv (starting at argv[0]). Genfunc
should return a count of how many arguments are left in argv;
Tk_ParseArgv will process them. If genfunc encounters an error
then it should leave an error message in interp->result, in the
usual Tcl fashion, and return -1; when this happens Tk_ParseArgv
will abort its processing and return TCL_ERROR.
FLAGS
TK_ARGV_DONT_SKIP_FIRST_ARG
Tk_ParseArgv normally treats argv[0] as a program or command
- 5 - Formatted: August 11, 1996
Tk_ParseArgv(3) Tk Tk_ParseArgv(3)
Tk Library Procedures Tk Library Procedures
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
Here is an example definition of an argTable and some sample command
lines that use the options. Note the effect on argc and argv;
arguments processed by Tk_ParseArgv are eliminated from argv, and argc
is updated to reflect reduced number of arguments.
/*
* 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"},
- 6 - Formatted: August 11, 1996
Tk_ParseArgv(3) Tk Tk_ParseArgv(3)
Tk Library Procedures Tk Library Procedures
{"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.
*/
}
Note that default values can be assigned to variables named in
argTable: the variables will only be overwritten if the particular
arguments are present in argv. Here are some example command lines
and their effects.
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
In all of the above examples, argc will be set by Tk_ParseArgv to 2,
argv[0] will be ``prog'', argv[1] will be ``infile'', and argv[2] will
be NULL.
KEYWORDS
arguments, command line, options
- 7 - Formatted: August 11, 1996