1. Opt

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

1.1 Opts

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.

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 Weld 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? ?--?}}