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  mes­
                                           sages.

       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  pro­
                                           gram.    Modified   to
                                           hold unprocessed argu­
                                           ments   that    remain
                                           after the call.

       Tk_ArgvInfo   *argTable   (in)      Array    of   argument
                                           descriptors,    termi­
                                           nated  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


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  pro­
       cessed  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 any­
       thing 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 mod­
       ified,  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 pro­
       cessing 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 differ­
       ent.  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.
       wise Tk_ParseArgv selects a specifier for which the  argu­
       ment  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 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 argu­
       ment 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.

              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 cor­
              responding 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 speci­
              fiers 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 argu­
              ments.  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 speci­
              fier 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
              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  addi­
              tion,  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 corre­
              sponding fields from the argTable entry,  and  nex­
              tArg 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.   Oth­
              erwise it should return 0 and TkParseArgv will pro­
              cess 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 proce­
              dure, and passes that procedure all of the  remain­
              ing  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  corre­
              sponding  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
              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 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 argu­
              ments 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 sam­
       ple  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;
              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