tclGetOpts - typedopts

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 ]
      }
    }

AUTHOR

Ross Palmer Mohn (rpmohn at waxandwane dot org), Johnson Earls (darkfox at springhaven dot org)

BUGS

If an option has both multiple and list-of in its type, the muiltiple 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.

menu