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 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 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 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 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 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 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, (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 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 | FLAGS | EXAMPLE | KEYWORDS

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

home | help