OVERVIEW
========

A tcl package for parsing command line options(support short options bundling).


SYNOPSIS
========

package require getopt

getopt::parse CALLBACK_CMD ARGV_VARNAME
getopt::split STRING


FEATURES
========

* short option and long option support
* short option bundling support
* options mixed with non-option arguments
* support of "--" to indicate an options end


DESCRIPTION
===========

getopt::parse proc is used to parse a list of arguments with options and
possible option arguments. It accept 2 arguments. The first is a callback
command - a list with command name and arguments (if needed). And the
second argument is a var name of a list variable with arguments.

This callback will be called on every option-value pair found in a list. It
is called with 2 additional arguments added to the list supplied to
getopt::parse - option name and possible option value. getopt::parse
doesn't know is this option require a value or not; so, it parses argv as
if every option require a value. And callback must tell through it return
code if this option require a value. The callback must return 0 if option
doesn't have an value and return 1 for option with a value. If callback
returns 0, then a string interpreted as an option value is not removed from
argv and parsed as usual in the next iteration. If callback returns 1, then
option value is removed from argv.

Every found option(with its value if return code is 1) is removed from argv
specified in second argument to getopt::parse. Thus, after
getopt::parse finish, a list with command line arguments contains only non
option words.

If getopt::parse get "--" as a next command line argument, then it finish
options parsing and stay intact the next arguments.

Example:

  set argv {-abc arg -d val -l name}
  getopt::parse {opts_parse priv} argv

will do the next calls in order (assume that opts_parse return 1 only for
b and d):

- opts_parse priv -a bc
- opts_parse priv -b c
- opts_parse priv -d val
- opts_parse priv -l name

argv is {arg name}.

A short option is a letter with dash in front of it. Like "-a". Many
short options can be bundled together like this: -abDv. This is equal to
"-a -b -D -v". Short option can have a value specified right after the
name or separated with space. Like "-a123" or "-a 123", where "123" is the
value of "a" option.

A long option is a word with two dashes in front of it. Like "--db". Long
option can have a value specified separated with equal sign or space. Like
"--db=name" or "--db name", where "name" is the value of "db" option.

getopt::split is used to split a string with arguments into a list of
arguments. It try to conform to shell style of argument splitting. E.g.
the string - a bc"d\\e \"fg"hi jkl mno - is splitted to
{a {bcd\e "fghi} jkl mno} list.


RETURN VALUE
============

getopt::parse callback should return 0 if option is not consume the
specified option argument; or 1 if option is consume it.

getopt::split returns a list with arguments according to shell splitting
rules.


ERRORS
======

On error getopt::split is throw an error with first item of errorCode
list equal to 'GETOPT'.


EXAMPLES
========

proc opts_parse {_priv oname oval} {
	upvar 2 $_priv priv

	switch $oname {
	-b -
	-d {
		lappend priv [list $oname $oval]
		return 1
	}
	default {
		lappend priv $oname
	}
	}

	return 0
}

set argv {-abc arg -d val -l name}
set priv {}
getopt::parse {opts_parse priv} argv
puts "opts: $priv"
puts "argv now is: $argv"


See ex1.tcl.