head	1.13;
access;
symbols
	core-8-5-9:1.10
	core-8-5-8:1.10
	macosx-cocoa-merge:1.13
	macosx-cocoa-premerge:1.13
	macosx-carbon-freeze:1.13
	core-8-5-7:1.10
	core-8-5-6:1.10
	core-8-6-b1:1.11
	core-8-6-a3:1.11
	core-8-5-5:1.10
	core-8-6-a2:1.11
	core-8-5-4:1.10
	core-8-5-3:1.10
	core-8-6-a1:1.10
	core-8-4-19:1.3
	core-8-5-branch:1.10.0.2
	core-8-5-2:1.10
	core-8-4-18:1.3
	core-8-5-1:1.10
	core-8-4-17:1.3
	core-8-5-0:1.10
	core-8-5-b3:1.9
	core-8-5-b2:1.8
	core-8-4-16:1.3
	core-8-5-b1:1.6
	core-stablilizer-merge:1.6
	core-stabilizer-branch:1.6.0.2
	core-stabilizer-merge:1.10
	core-8-4-15:1.3
	core-8-5-a6:1.6
	core-8-5-a5:1.5
	core-8-4-14:1.3
	core-8-5-a4:1.5
	core-8-4-13:1.3
	core-8-4-12:1.3
	core-8-4-11:1.3
	core-8-5-a3:1.5
	core-8-4-10:1.3
	core-8-4-9-branch:1.3.0.6
	core-8-5-a2:1.5
	core-8-4-9:1.3
	core-8-4-8:1.3
	core-8-4-7:1.3
	core-8-5-a1:1.3
	core-8-4-6:1.3
	core-8-4-5:1.3
	mistachkin-dev-branch:1.3.0.4
	core-8-4-4:1.3
	core-8-4-3:1.3
	core-8-4-branch:1.3.0.2
	core-8-4-2:1.3
	core-8-4-1:1.3
	core-8-3-5:1.2
	core-8-4-0:1.3
	macosx-8-4-merge-2002-08-31-trunk:1.3
	macosx-8-4-premerge-2002-08-31-branch:1.2.24.1
	macosx-8-4-premerge-2002-08-31-trunk:1.3
	macosx-8-4-merge-2002-08-30-branch:1.2.24.1
	macosx-8-4-merge-2002-08-30-trunk:1.3
	macosx-8-4-merge-2002-08-20-branch:1.2.24.1
	macosx-8-4-merge-2002-08-20-trunk:1.3
	core-8-4-b2:1.3
	core-8-4-b1:1.3
	macosx-premerge-6-9-02:1.2.24.1
	core-8-4-a4:1.3
	core-8-3-4:1.2
	macosx-8-4-branch:1.2.0.24
	macosx-8-4-branchpoint:1.2
	core-8-4-a3:1.2
	core-8-3-3:1.2
	dgp-privates-into-namespace:1.2.0.22
	tclpro-1-5-0:1.2
	core-8-4-win-speedup:1.2.0.20
	core-8-4-a2:1.2
	tclpro-1-4-1:1.2
	tclpro-1-4-0:1.2
	core-8-3-2:1.2
	ajuba-ajuba2-2-1-base:1.2
	ajuba-ajuba2-2-0:1.2
	core-8-4-a1:1.2
	core-8-3-1-branch:1.2.0.18
	core-8-3-1:1.2
	scriptics-sc-2-0-b5:1.2
	scriptics-sc-2-0-fixed:1.2
	scriptics-sc-2-0-b2:1.2
	scriptics-sc-2-0-b1:1.2
	core-8-3-0:1.2
	core-8-3-b2:1.2
	core-8-3-b1:1.2
	scriptics-sc-1-1:1.2
	scriptics-sc-1-1-b1:1.2
	core-8-2-3:1.2
	scriptics-sc-1-1-branch:1.2.0.16
	scriptics-sc-1-1-base:1.2
	scriptics-sc-1-0:1.2
	scriptics-sc-1-0-branch:1.2.0.14
	scriptics-sc-1-0-base:1.2
	core-8-2-2:1.2
	core-8-2-1:1.2
	scriptics-bc-1-0-b1:1.2
	core-8-2-1-branch:1.2.0.12
	scriptics-tclpro-1-3-0:1.2
	core-8-2-0:1.2
	core-8-2-b3-branch:1.2.0.10
	core-8-2-b3-base:1.2
	scriptics-tclpro-1-3-b4:1.2
	core-8-2-b2:1.2
	scriptics-tclpro-1-3-b3:1.2
	core-8-2-b1:1.2
	scriptics-tclpro-1-3-b2:1.2
	merge-to-mainline-5/21/99:1.2
	scriptics-tclpro-1-3-b2-branch:1.2.0.8
	core-8-1-1:1.2
	scriptics-tclpro-1-3-b1:1.2
	core-8-1-1-base:1.2
	core-8-1-0:1.2
	merge-to-mainline-4-29-99:1.2
	merge-to-mainline-4-23-99:1.2
	core-8-1-branch-old:1.1.0.4
	core-8-0-6-branch:1.2.0.6
	core-8-0-6-base:1.2
	core-8-0-5:1.2
	core-8-1-b3:1.1.4.1
	core-8-1-b2:1.1.4.1
	dev-8-1-stubs-branch:1.1.4.1.0.2
	dev-stubs-branch:1.2.0.4
	scriptics-tclpro-1-2:1.2
	scriptics-tclpro-1-2-b2:1.2
	core-8-1-merge-2/10/99:1.2
	core-8-0-5-branch:1.2.0.2
	core-8-0-5-base:1.2
	scriptics-tclpro-1-2-b1:1.2
	scriptics-tclpro-1-2-a1:1.2
	core-8-1-b1:1.1.4.1
	core-8-0-4:1.2
	core-8-1-a2:1.1
	core-8-0-2:1.1
	core-8-0-3:1.2;
locks; strict;
comment	@# @;


1.13
date	2009.05.04.09.12.33;	author dkf;	state Exp;
branches;
next	1.12;

1.12
date	2009.01.06.21.58.15;	author nijtmans;	state Exp;
branches;
next	1.11;

1.11
date	2008.06.30.22.57.01;	author dkf;	state Exp;
branches;
next	1.10;

1.10
date	2007.12.13.15.23.43;	author dgp;	state Exp;
branches;
next	1.9;

1.9
date	2007.10.29.16.04.13;	author dkf;	state Exp;
branches;
next	1.8;

1.8
date	2007.10.26.20.13.23;	author dgp;	state Exp;
branches;
next	1.7;

1.7
date	2007.10.24.14.32.57;	author dkf;	state Exp;
branches;
next	1.6;

1.6
date	2007.01.05.00.00.48;	author nijtmans;	state Exp;
branches
	1.6.2.1;
next	1.5;

1.5
date	2004.09.19.16.05.36;	author dkf;	state Exp;
branches;
next	1.4;

1.4
date	2004.08.20.14.15.29;	author dkf;	state Exp;
branches;
next	1.3;

1.3
date	2002.01.25.21.09.36;	author dgp;	state Exp;
branches;
next	1.2;

1.2
date	98.09.14.18.22.53;	author stanton;	state Exp;
branches
	1.2.20.1
	1.2.24.1;
next	1.1;

1.1
date	98.04.01.09.40.10;	author rjohnson;	state Exp;
branches
	1.1.4.1;
next	;

1.1.4.1
date	98.09.30.02.16.05;	author stanton;	state Exp;
branches;
next	;

1.2.20.1
date	2002.04.02.20.57.53;	author hobbs;	state Exp;
branches;
next	;

1.2.24.1
date	2002.02.05.02.25.14;	author wolfsuit;	state Exp;
branches;
next	;

1.6.2.1
date	2007.11.01.16.37.13;	author dgp;	state Exp;
branches;
next	;


desc
@@


1.13
log
@Purge mention of interp->result. [Bug 2431507]
@
text
@'\"
'\" 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.12 2009/01/06 21:58:15 nijtmans 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_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 "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 \fBTK_ARGV_END\fR.
.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 \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR,
\fBTK_ARGV_NO_ABBREV\fR, \fBTK_ARGV_NO_LEFTOVERS\fR, and
\fBTK_ARGV_NO_DEFAULTS\fR.
.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 does not match \fIargTable\fR and returned to the
caller;  however, if the \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR 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 \fBTCL_OK\fR.  If an error
occurs while parsing the arguments, then \fBTCL_ERROR\fR is returned and
\fBTk_ParseArgv\fR will leave an error message in the result of
interpreter \fIinterp\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 {
    const char *\fIkey\fR;
    int \fItype\fR;
    char *\fIsrc\fR;
    char *\fIdst\fR;
    const char *\fIhelp\fR;
} \fBTk_ArgvInfo\fR;
.CE
The \fIkey\fR field is a string such as
.QW \-display
or
.QW \-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
.QW "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
.QW "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.
.QW 0
and
.QW 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 a 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 \fBTK_ARGV_STRING\fR, 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 \fBTK_ARGV_CONST_OPTION\fR, 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 interpreter
\fIinterp\fR's result
and \fBTk_ParseArgv\fR returns \fBTCL_ERROR\fR.  When this happens, the
caller normally prints the help message and aborts.  If the \fIkey\fR
field of a \fBTK_ARGV_HELP\fR 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
\fBTK_ARGV_HELP\fR 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 does not 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 are not 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 interpreter
\fIinterp\fR's result,
in the usual Tcl fashion, and return \-1;  when this happens
\fBTk_ParseArgv\fR will abort its processing and return \fBTCL_ERROR\fR.
.RE
.SS "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
had not 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 does not
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 \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR is not 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", Tcl_GetString(Tcl_GetObjResult(interp)));
        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
.QW prog ,
\fIargv\fR[1] will be
.QW infile ,
and \fIargv\fR[2] will be NULL.
.SH KEYWORDS
arguments, command line, options
@


1.12
log
@A few const -> CONST86 modifications, improving
backwards compatibility. Change Tk_ItemIndexProc
and Tk_ItemInsertProc signature to have a Tcl_Obj parameter
in stead of a string parameter. This is binary
and source compatible with previous API, it just prevents
the need for a type cast in the Tk_ItemType table construction.
Bring doc in line with API.
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ParseArgv.3,v 1.11 2008/06/30 22:57:01 dkf Exp $
d65 2
a66 2
\fBTk_ParseArgv\fR will leave an error message in \fIinterp->result\fR
in the standard Tcl fashion.  In
d191 2
a192 1
all the valid arguments.  The message is placed in \fIinterp->result\fR
d265 2
a266 1
an error then it should leave an error message in \fIinterp->result\fR,
d336 1
a336 1
        fprintf(stderr, "%s\en", interp->result);
@


1.11
log
@Minor doc updates (removing out of date changebars, improving typedef formatting,
 etc.)
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ParseArgv.3,v 1.10 2007/12/13 15:23:43 dgp Exp $
d75 1
a75 1
    char *\fIkey\fR;
d79 1
a79 1
    char *\fIhelp\fR;
@


1.10
log
@merge stable branch onto HEAD
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ParseArgv.3,v 1.6.2.1 2007/11/01 16:37:13 dgp Exp $
d80 1
a80 1
} Tk_ArgvInfo;
d268 1
a268 1
.SH "FLAGS"
@


1.9
log
@Lots more GOOBE stuff. Now works with 'make html'!
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ParseArgv.3,v 1.8 2007/10/26 20:13:23 dgp Exp $
@


1.8
log
@        * doc/*.1:              Revert doc changes that broke
        * doc/*.3:              `make html` so we can get the release
        * doc/*.n:              out the door.
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ParseArgv.3,v 1.6 2007/01/05 00:00:48 nijtmans Exp $
d58 1
a58 1
an argument that doesn't match \fIargTable\fR and returned to the
d82 4
a85 1
The \fIkey\fR field is a string such as ``\-display'' or ``\-bg''
d110 3
a112 2
specifier.  The argument that matched \fIkey\fR is called ``the matching
argument'' in the descriptions below.  As part of the processing,
d114 3
a116 2
after the matching argument, which is called ``the following
argument''.  The legal values for \fItype\fR, and the processing
d131 5
a135 2
integer string in the format accepted by \fBstrtol\fR (e.g. ``0''
and ``0x'' prefixes may be used to specify octal or hexadecimal
d203 1
a203 1
\fBTk_ParseArgv\fR doesn't process any
d229 1
a229 1
(or NULL if there aren't any more arguments left in \fIargv\fR).
d265 1
a265 1
in the usual Tcl fashion, and return -1;  when this happens
a267 1

d273 1
a273 1
hadn't matched \fIargTable\fR.  If this flag is given, then
d284 1
a284 1
will return an error if it encounters any argument that doesn't
d287 1
a287 1
long as \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR isn't specified.
a293 1

d315 1
a315 1
    {"-X", TK_ARGV_CONSTANT, (char *) 1, (char *) &debugFlag,
d317 1
a317 1
    {"-N", TK_ARGV_INT, (char *) NULL, (char *) &numReps,
d319 1
a319 1
    {"-of", TK_ARGV_STRING, (char *) NULL, (char *) &fileName,
d349 3
a351 3
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
d354 4
a357 1
\fIargv\fR[0] will be ``prog'', \fIargv\fR[1] will be ``infile'',
a358 1

@


1.7
log
@Lots of improvements to look and feel of manual pages
@
text
@d82 1
a82 4
The \fIkey\fR field is a string such as
.QW \-display
or
.QW \-bg
d107 2
a108 3
specifier.  The argument that matched \fIkey\fR is called
.QW "the matching argument"
in the descriptions below.  As part of the processing,
d110 2
a111 3
after the matching argument, which is called
.QW "the following argument" .
The legal values for \fItype\fR, and the processing
d126 2
a127 5
integer string in the format accepted by \fBstrtol\fR (e.g.
.QW 0
and
.QW 0x
prefixes may be used to specify octal or hexadecimal
d348 1
a348 4
\fIargv\fR[0] will be
.QW prog ,
\fIargv\fR[1] will be
.QW infile ,
@


1.6
log
@various "const" additions, in line with TIP #27
fix bug #1627732
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ParseArgv.3,v 1.5 2004/09/19 16:05:36 dkf Exp $
d82 4
a85 1
The \fIkey\fR field is a string such as ``\-display'' or ``\-bg''
d110 3
a112 2
specifier.  The argument that matched \fIkey\fR is called ``the matching
argument'' in the descriptions below.  As part of the processing,
d114 3
a116 2
after the matching argument, which is called ``the following
argument''.  The legal values for \fItype\fR, and the processing
d131 5
a135 2
integer string in the format accepted by \fBstrtol\fR (e.g. ``0''
and ``0x'' prefixes may be used to specify octal or hexadecimal
d356 4
a359 1
\fIargv\fR[0] will be ``prog'', \fIargv\fR[1] will be ``infile'',
@


1.6.2.1
log
@merge updates from HEAD
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ParseArgv.3,v 1.6 2007/01/05 00:00:48 nijtmans Exp $
d58 1
a58 1
an argument that does not match \fIargTable\fR and returned to the
d82 1
a82 4
The \fIkey\fR field is a string such as
.QW \-display
or
.QW \-bg
d107 2
a108 3
specifier.  The argument that matched \fIkey\fR is called
.QW "the matching argument"
in the descriptions below.  As part of the processing,
d110 2
a111 3
after the matching argument, which is called
.QW "the following argument" .
The legal values for \fItype\fR, and the processing
d126 2
a127 5
integer string in the format accepted by \fBstrtol\fR (e.g.
.QW 0
and
.QW 0x
prefixes may be used to specify octal or hexadecimal
d195 1
a195 1
\fBTk_ParseArgv\fR does not process any
d221 1
a221 1
(or NULL if there are not any more arguments left in \fIargv\fR).
d257 1
a257 1
in the usual Tcl fashion, and return \-1;  when this happens
d260 1
d266 1
a266 1
had not matched \fIargTable\fR.  If this flag is given, then
d277 1
a277 1
will return an error if it encounters any argument that does not
d280 1
a280 1
long as \fBTK_ARGV_DONT_SKIP_FIRST_ARG\fR is not specified.
d287 1
d309 1
a309 1
    {"\-X", TK_ARGV_CONSTANT, (char *) 1, (char *) &debugFlag,
d311 1
a311 1
    {"\-N", TK_ARGV_INT, (char *) NULL, (char *) &numReps,
d313 1
a313 1
    {"\-of", TK_ARGV_STRING, (char *) NULL, (char *) &fileName,
d343 3
a345 3
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
d348 1
a348 4
\fIargv\fR[0] will be
.QW prog ,
\fIargv\fR[1] will be
.QW infile ,
d350 1
@


1.5
log
@Standardize style of section refs & public symbols. Remove displayed tabs
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ParseArgv.3,v 1.4 2004/08/20 14:15:29 dkf Exp $
d31 1
a31 1
.AP "CONST char" **argv in/out
@


1.4
log
@More doc fixes. [Patch 1012837]
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ParseArgv.3,v 1.3 2002/01/25 21:09:36 dgp Exp $
d36 1
a36 1
type TK_ARGV_END.
d40 3
a42 2
The flags currently defined are TK_ARGV_DONT_SKIP_FIRST_ARG,
TK_ARGV_NO_ABBREV, TK_ARGV_NO_LEFTOVERS, and TK_ARGV_NO_DEFAULTS.
d59 1
a59 1
caller;  however, if the TK_ARGV_DONT_SKIP_FIRST_ARG bit is set in
d63 2
a64 2
\fBTk_ParseArgv\fR normally returns the value TCL_OK.  If an error
occurs while parsing the arguments, then TCL_ERROR is returned and
d75 5
a79 5
	char *\fIkey\fR;
	int \fItype\fR;
	char *\fIsrc\fR;
	char *\fIdst\fR;
	char *\fIhelp\fR;
d148 1
a148 1
This form is similar to TK_ARGV_STRING, except that the argument
d165 1
a165 1
This form is similar to TK_ARGV_CONST_OPTION, except that the
d184 1
a184 1
and \fBTk_ParseArgv\fR returns TCL_ERROR.  When this happens, the
d186 1
a186 1
field of a TK_ARGV_HELP specifier is NULL, then the specifier will
d189 1
a189 1
TK_ARGV_HELP entry causes help information to be returned.
d212 3
a214 3
	char *\fIdst\fR;
	char *\fIkey\fR;
	char *\fInextArg\fR;
d238 5
a242 5
	char *\fIdst\fR;
	Tcl_Interp *\fIinterp\fR;
	char *\fIkey\fR;
	int \fIargc\fR;
	char **\fIargv\fR;
d258 1
a258 1
\fBTk_ParseArgv\fR will abort its processing and return TCL_ERROR.
d280 1
a280 1
long as TK_ARGV_DONT_SKIP_FIRST_ARG isn't specified.
d309 10
a318 10
	{"-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}
d322 2
a323 2
	int argc;
	char *argv[];
d325 1
a325 1
	\&...
d327 4
a330 4
	if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) {
		fprintf(stderr, "%s\en", interp->result);
		exit(1);
	}
d332 3
a334 3
	/*
	 * Remainder of the program.
	 */
d343 3
a345 3
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
@


1.3
log
@	* Updated callers of Tcl_SplitList and Tcl_Merge.
	* Updated callers of Tcl_GetStringResult.
	  Rewrote PrintScrollFractions to ScrollFractions to stop scribbling
	  directly on interp->result.
	* Updated callers of Tcl_GetVar, Tcl_GetVar2
	* Updated callers of Tcl_SplitPath, Tcl_JoinPath, and
	  Tcl_TranslateFileName.
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ParseArgv.3,v 1.2 1998/09/14 18:22:53 stanton Exp $
d135 1
a135 1
\fIDst\fR is treated as the address of an double-precision
@


1.2
log
@Replaced SCCS strings, fixed binary files
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id$
d31 1
a31 1
.AP char **argv in/out
@


1.2.20.1
log
@sync with head
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ParseArgv.3,v 1.3 2002/01/25 21:09:36 dgp Exp $
d31 1
a31 1
.AP "CONST char" **argv in/out
@


1.2.24.1
log
@Merge with current TOT
Added support for the wm stackorder command
Fixed crash when selecting Menu items in the Application menu that we didn't
put there.
Added first bits of the use of CG for low-level drawing.  The line-drawing works,
the rest doesn't yet.  You have to set the file static useCGDrawing to 1 and
rebuild to activate this code.
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ParseArgv.3,v 1.2 1998/09/14 18:22:53 stanton Exp $
d31 1
a31 1
.AP "CONST char" **argv in/out
@


1.1
log
@Initial revision
@
text
@d8 1
a8 1
'\" SCCS: @@(#) ParseArgv.3 1.17 97/10/31 12:58:44
@


1.1.4.1
log
@Merged 8.0.3 changes into 8.1
@
text
@d8 1
a8 1
'\" RCS: @@(#) $Id: ParseArgv.3,v 1.2 1998/09/14 18:22:53 stanton Exp $
@


