ParseArgv man page on BSDi

Man page or keyword search:  
man Server   6284 pages
apropos Keyword Search (all sections)
Output format
BSDi logo
[printable version]



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

Tk								1

Tk_ParseArgv(3)	      Tk Library Procedures	  Tk_ParseArgv(3)

_________________________________________________________________

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.
       Tk_ParseArgv selects the first specifier whose key matches

Tk								2

Tk_ParseArgv(3)	      Tk Library Procedures	  Tk_ParseArgv(3)

       the  argument exactly, if such a specifier exists.  Other-
       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.

Tk								3

Tk_ParseArgv(3)	      Tk Library Procedures	  Tk_ParseArgv(3)

       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 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
	      allow  the  last several of their options to be the

Tk								4

Tk_ParseArgv(3)	      Tk Library Procedures	  Tk_ParseArgv(3)

	      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  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
	      options after the	 matching  one.	  Genfunc  should

Tk								5

Tk_ParseArgv(3)	      Tk Library Procedures	  Tk_ParseArgv(3)

	      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 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;
	      int numReps = 100;

Tk								6

Tk_ParseArgv(3)	      Tk Library Procedures	  Tk_ParseArgv(3)

	      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								7

[top]

List of man pages available for BSDi

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net