Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

CentOS 7.0 - man page for tk_parseargv (centos section 3)

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 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.

       const char **argv (in/out)	   Command line arguments passed to main program.   Modi-
					   fied  to  hold unprocessed arguments that remain after
					   the call.

       Tk_ArgvInfo *argTable (in)	   Array of argument descriptors, terminated  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 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  argument
       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	standard  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 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 placeholders:  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 specifier whose key matches the argu-
       ment exactly, if such a specifier exists.  Otherwise Tk_ParseArgv 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
       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 argument 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  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
	      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 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 dis-
	      carded.  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 specifiers 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  argu-
	      ments;   it  returns them all at the beginning of argv (along with any other unpro-
	      cessed arguments).  In addition, Tk_ParseArgv treats dst as the address of an inte-
	      ger 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 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 procedure, and passes that procedure all of the remaining arguments.  The pro-
	      cedure should have the following 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 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 arguments to the caller.  If	this  bit
	      is  set  in flags then Tk_ParseArgv will return an error if it encounters any argu-
	      ment 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;  arguments processed by Tk_ParseArgv are elim-
       inated 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)


All times are GMT -4. The time now is 03:45 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password