Subversion Repositories or1k_old

'\"

'\" 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.1.1.1 2002-01-16 10:25:48 markom 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 \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