ABCDEFGHIJKLMNOPQRSTUVWXYZ

Tk_ParseArgv

Tk_ParseArgv(3)              Tk Library Procedures             Tk_ParseArgv(3)



______________________________________________________________________________

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  spec-
                                           ify  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, ter-
                                           minated   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_LEFT-
                                           OVERS, 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
       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  argu-
       ment  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 stan-
       dard 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 com-
       pared with the values in argv.  Type indicates how to process an  argu-
       ment 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  place-
       holders:   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 spec-
       ifier  whose  key  matches  the  argument  exactly, if such a specifier
       exists.  Otherwise Tk_ParseArgv selects a specifier for which the argu-
       ment  is  a unique abbreviation.  If the argument is a unique abbrevia-
       tion 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 argument
       that matched key is called ``the matching argument''  in  the  descrip-
       tions  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 pro-
       cessing 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 argu-
              ment 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  argu-
              ment  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 match-
              ing 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 speci-
              fiers 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;
                     {
                     }
              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 argu-
              ment in the normal fashion.  In either event the matching  argu-
              ment 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 fol-
              lowing 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
              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 spe-
              cial treatment.

       TK_ARGV_NO_ABBREV
              Normally, Tk_ParseArgv accepts unique abbreviations for key val-
              ues  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;  argu-
       ments 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"},
                {"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



Tk                                                             Tk_ParseArgv(3)