cmdline(n)						 command line / option processing						cmdline(n)

NAME

       cmdline - Procedures to process command lines and options.

SYNOPSIS

       package require Tcl 8.2

       package require cmdline ?1.2?

       ::cmdline::getopt argvVar optstring optVar valVar

       ::cmdline::getKnownOpt argvVar optstring optVar valVar

       ::cmdline::getoptions arglistVar optlist ?usage?

       ::cmdline::getKnownOptions arglistVar optlist ?usage?

       ::cmdline::usage optlist ?usage?

       ::cmdline::getfiles patterns quiet

       ::cmdline::getArgv0

DESCRIPTION

       This package provides commands to parse command lines and options.

       ::cmdline::getopt argvVar optstring optVar valVar
	      This command works in a fashion like the standard C based getopt function.  Given an option string and a pointer to an array or args
	      this command will process the first argument and return info on how to procede. The command returns 1 if an option was found,  0	if
	      no more options were found, and -1 if an error occurred.

	      argvVar contains the name of the argv list to process. If options are found the arg list is modified and the processed arguments are
	      removed from the start of the list.

	      optstring contains a list of command options that the application will accept.  If the option ends in ".arg" the	command  will  use
	      the next argument as an argument to the option.  Otherwise the option is a boolean that is set to 1 if present.

	      optVar refers to the variable the command will store the found option into (without the leading '-' and without the .arg extension).

	      valVar  refers  to the variable to store either the value for the specified option into upon success or an error message in the case
	      of failure. The stored value comes from the command line for .arg options, otherwise the value is 1.

       ::cmdline::getKnownOpt argvVar optstring optVar valVar
	      Like ::cmdline::getopt, but ignores any unknown options in the input.

       ::cmdline::getoptions arglistVar optlist ?usage?
	      Processes the set of command line options found in the list variable named by arglistVar and fills in defaults for those not  speci-
	      fied.  This also generates an error message that lists the allowed flags if an incorrect flag is specified. The optional usage-argu-
	      ment contains a string to include in front of the generated message. If not present it defaults to "options:".

	      optlist contains a list of lists where each element specifies an option in the form: flag default comment.

	      If flag ends in ".arg" then the value is taken from the command line. Otherwise it is a boolean and appears in the result if present
	      on the command line. If flag ends in ".secret", it will not be displayed in the usage.

       ::cmdline::getKnownOptions arglistVar optlist ?usage?
	      Like ::cmdline::getoptions, but ignores any unknown options in the input.

       ::cmdline::usage optlist ?usage?
	      Generates  and  returns an error message that lists the allowed flags. optlist is defined as for ::cmdline::getoptions. The optional
	      usage-argument contains a string to include in front of the generated message. If not present it defaults to "options:".

       ::cmdline::getfiles patterns quiet
	      Given a list of file patterns this command computes the set of valid files.  On windows, file globbing is performed  on  each  argu-
	      ment.   On  Unix, only file existence is tested.	If a file argument produces no valid files, a warning is optionally generated (set
	      quiet to true).

	      This code also uses the full path for each file.	If not given it prepends the current  working  directory  to  the  filename.  This
	      ensures that these files will never conflict with files in a wrapped zip file. The last sentence refers to the pro-tools.

       ::cmdline::getArgv0
	      This  command  returns  the "sanitized" version of argv0.  It will strip off the leading path and removes the ".bin" extensions that
	      the pro-apps use because they must be wrapped by a shell script.

KEYWORDS

       cmdline processing

cmdline 								1.2								cmdline(n)