1. Opts

Opt is a Tcl package for parsing options for procs, modules and the command line. Opt provides Opts, which parses name/value pairs passed to the args parameter at the end of a proc's arglist. A second (and lesser) command, Vopts, handls options that appear before or in between other arguments, ie. the form used by many of Tcl's builtin commands.

1.1 Opts

Opts is used for setting options into an array variable. The signature for Opts is:

  proc Opts {avar params {opts {}} args}

On entry, avar must be an empty or non-existant array.

Opts arguments are very simple. They always appear after all other arguments in a proc, and they are always are in name/value pair form. The Opts command usually takes 3 arguments, namely: the name of an array, the arguments and an option list describing the options.

Here is an example.

   proc foo {x args} {
      Opts p $args {
        { -name     {}     "Name of value" }
        { -debug    0      "Debugging level" }
        { -quiet    True   "Verbosity flag" -type Bool }
        { -- }
      }
      return $p(-debug)
    }

    foo 0 -name "Funny"
    foo 1 -name "Fast" -debug 1
    foo 2 -name "Extra" -- a b c

The options list is a list of list elements. The format of each element in the options list is defined as a sublist of the form: { NAME DEFAULT DESCRIPTION ...}. Of these, only the first (NAME) is required, and values beyond the third are name/value options such as -type, -label, etc.

Here are the options that Opts args accepts:

Name	Default	Description
-check		Override default checking level for this option
-cmd		On warning call given cmd instead of tclLog.
-force	False	Typecheck and force default if fails
-implicit	True	Imply type from default (if check>=20)
-init	True	Initialize array with all option default values
-prefix		Message prefix for warn/error messages.
-subst	False	Perform subst on opts in callers stack.
-unset	True	Unset avar array prior to assigning (required for arg checking).

Note, the option -icfg has a special meaning.

1.2 Vopts

Vopts is used to parses the optional parameters that may appear at a certain specific argument in a proc/command arglist. Moreover, unlike Opts these parameters do not appear in pairs, but can take 0, 1 or multiple values. These values (if any) are included in the argument name string of the description list.

Vopts initializes avar from lst of options then assigns the passed values. The special arg (which should be last) is used to indicate the end of 'args' AND that the proc really does accept extra args. When Vopts returns, avar(--) contains the real trailing args. Moreover, all of the parameters (including args) are updated in place.

Vopts emulates Tcl command option parsing which, yes, is somewhat pathological. One difference is that the C vopts can choose not to use the option while still taking args, where Vopts uses as a flag that extra args are accepted, which is flagged in 'extern's by using a '*' at the end of vopts.

        # Test for Vopts.  TODO: move to test file.
        proc myfunc {exp string args} {
            # Options can appear before arg 1 (string).
            Vopts p 1 {
                { -about        0       "Return info about" }
                { -all              0       "Do all patterns" }
                {"-start index" 0       "Offset to start at"}
                {"-range b e"   {0 -1}  "Range of values" }
                { --            {}      "Marks end of switch" }
            }
            if {$p(-all)} {
            }
            set i 0
            if {$p(-start)} {
            }
            puts "<<: [info level 0]"
            puts ">>: p='[array get p]', exp='$exp', string=$string"
            return 1
        }

        myfunc d.* -about -all dog
        myfunc d.* -about -all -- dog
        myfunc d.* dog
        myfunc d.* -about -- -all
        myfunc d.* a
        myfunc d.* -range 0 1 -about a

1.3 Options and Externs

An secondary but nevertheless important function of Opts and Vopts is for generation of Extern definitions which are used by Wize for Tcl validation and by Ted for command completion. Ted uses the Mod component Interface to automatically generate extern for a file.

For example, given the above the generated interface would look something like:

        extern foo {x args} {. . {opts -name {-debug bool} -quiet -- } 
        extern myfunc {exp string args} {. . . {vopts ?-about? \
            ?-all? ?-start index? ?-range b e? ?--?}}