tclGetOpts - typedopts

For latest version, documentation, and information, visit
http://www.waxandwane.com/toolbox/tclGetOpts/

NAME
	typedopts - parse typed command-line options in TCL
 

SYNOPSIS
	typedopts arglist optlist optret argret rest [ options ]


OPTIONS
	-noinit
		Don't initialize optret and argret.


DESCRIPTION
	typedopts is a command line option parser. It reads arglist
	and finds all the options that are described in optlist. If
	no errors are found, then typedopts will set rest to the
	command line arguments that weren't parsed, optret and argret
	as described below, and return 1. optret and argret will be
	set to arrays, indexed by the names of the options in optlist.
	optret will contain boolean values indicating which options
	were found in arglist, and argret will contain the arguments
	to the options found.

	optlist is a TCL list that describes all of the options that
	the program accepts. It consists of type-name pairs:
	{ type name type name ... }
	type describes what type of argument the option may take; the
	types are described below. Some of the types require
	additional parameters; for these types, type must be a TCL
	list with the type name followed by the parameters.

	name is the name of the option; if the program accepts more
	than one option of type type, then name may be a TCL list of
	all the options of that type. The option may be abbreviated
	on the command line, as long as the abbreviation uniquely
	identifies one option.

	The types for type are listed here. The type name in type may
	be a unique abbreviation of the type name listed.


	boolean
		A simple flag; no argument is accepted for the option.

	string
		A string -- no type checking is done.

	float
		A floating point number. All of the TCL floating point
		formats should be accepted for this.

	integer
		An integer.

	number
		A floating point number or an integer.

	one-of value...
		One of a specific set of values. The values may be
		abbreviated when used on the command line.

	list-of type
		A list of values of type type. The list ends when one of
		the following is found: A valid command line option, the
		string --, or the end of arglist.

	multiple type
		This option takes one argument of type type, but may
		appear more than once on the command line. If an option
		is not specified as being of type multiple then it may
		appear on the command line only once.


	If an option is of type list-of or multiple, then the value
	found for that option in argret will be a TCL list of all the
	values found for the option, in the order in which they
	appeared on the command line.

	If typedopts finds an option that is not described in optlist,
	or if it finds an option argument of the wrong type, it will
	set argret(_ERROR_) to an error message, set rest to the rest
	of the options and arguments, and return 0.

	If the -noinit option is given to typedopts, then the optret
	and argret arrays will not be initialized. This allows the
	program to call typedopts several times with different
	arglists without losing the information from previous calls.

	If typedopts can't parse its options for any reason, it will
	print an error message to stderr and return a -1 without
	modifying any other variables.


EXAMPLE
	The command line parser for a simple text formatter is given
	below. The formatter accepts the options -top, -bottom, -left,
	-right, and -paragraph to set the margins, -header to set the
	header string, -pagenum to set the page number, and -position
	to position the page number in the footer (the position can be
	left, right, or center).  It first parses arguments from the
	environment variable TFORMAT, then from the command line. The
	command line can have options and filenames intermixed; the
	options affect all files found after the option.

     proc parseOpts { } {

     # global variables needed:  env = environ variables array,
     #                           argv == command line args
       global env argv

     # The options list: (they have to be declared multiple, because we
     # aren't re-initializing the option arrays each time.
       set optlist {
         { multiple integer } { left right top bottom paragraph pagenum }
         { multiple string } header
         { multiple one-of left right center } position
       }

     # check if we have a $TFORMAT environment variable to parse
       if { [ lsearch -exact [ array names $env ] "TFORMAT" ] > -1 } then {

     # initialize the options arrays found() and values() with the values
     # from TFORMAT
         set list $env(TFORMAT)
         while { ! [ typedopts $list $opts found values list ] } {

     # error returned from typedopts:  print the error message and
     # continue parsing
           puts stderr "Parsing \$TFORMAT: $values(_ERROR_)"
         }

     # check if there are any arguments left; if so, give a warning.
       if { [ llength $list ] } then {
         puts stderr "Warning:  \$TFORMAT has non-option arguments!"
       }

       } else {

     # initialize options arrays found() and values() from an empty list
         typedopts { } $opts found values
       }

     # start parsing the command line.  As long as its not empty, we first
     # pass pass it through the option parser, then call the formatter on
     # the files.
       while { [ llength $argv ] } {
         while { ! [ typedopts $argv $opts found values argv -noinit ] } {
           puts stderr "$values(_ERROR_)"
         }
         format [ lindex $argv 0 ]
         set argv [ lrange $argv 1 end ]
       }
     }


SEE ALSO
	getopt(3C), getopt
	http://www.waxandwane.com/toolbox/tclGetOpts/


AUTHOR
	Ross Mohn, RPMohn@panix.com
	Johnson Earls


BUGS
	If an option has both multiple and list-of in its type, the
	multiple part will only be effective if it comes first,
	e.g.
	{ multiple list-of string }
	but not
	{ list-of multiple string }

	Setting an option to type
	{ multiple boolean }
	will cause an infinite loop if the option occurs before
	non-option arguments.
	
