Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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  re-
					   main	after the call.

       const char **argv (in/out)	   Command  line  arguments  passed to
					   main	program.  Modified to hold un-
					   processed arguments that remain af-
					   ter 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  or-
       der)  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 does not 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 the result	of interpreter
       interp in the standard Tcl fashion.  In the event of an	error  return,
       *argvPtr	 will  not  have  been modified, but argv could	have been par-
       tially 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 {
		  const	char *key;
		  int type;
		  char *src;
		  char *dst;
		  const	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 val-
       ues 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 ex-
       ists.  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 re-
       turned 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
       argument	in argv	after the matching argument, which is called "the fol-
       lowing  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 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
	      a	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	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 ig-
	      nored.   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 interpreter interp's
	      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	speci-
	      fier 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 re-
	      turned.

       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  does  not  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 are not 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 interpreter interp's
	      result, in the usual Tcl fashion,	and return -1;	when this hap-
	      pens  Tk_ParseArgv  will abort its processing and	return TCL_ER-
	      ROR.

   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 had not 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  re-
	      turn  an error if	it encounters any argument that	does not 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 is not 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, NULL, (char *) &numReps,
		      "Number of repetitions"},
		  {"-of", TK_ARGV_STRING, NULL,	(char *) &fileName,
		      "Name of file for	output"},
		  {"x",	TK_ARGV_REST, NULL, (char *) &exec,
		      "File to exec, followed by any arguments (must be	last argument)."},
		  {NULL, TK_ARGV_END, NULL, NULL,
		      NULL}
	      };

	      main(argc, argv)
		  int argc;
		  char *argv[];
	      {
		  ...

		  if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) {
		      fprintf(stderr, "%s\n", Tcl_GetString(Tcl_GetObjResult(interp)));
		      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 ar-
       guments 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)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | EXAMPLE | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tk_ParseArgv.tk86&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help