1. Types

Types provide a mechanism for validating parameters to Tcl via extern definitions.

A type in Tcl is defined as a list: a string-name optionally followed by parameters. The special type "." is also available to indicate general typeless strings. Following is a list of the builtin types:

int double bool array avar blist choice channel char cmd
code subcode dict dir date datetime dictvar enum eval
expr exprn file float intersect list long match matchi
opts options ns noquote regexp regexpi short string time
tkwin tkfont tkcolor tkcursor tkpixel tkbitmap tkimage
topts uchar uint ulong union ushort uwide var void vopts
wide win _ .

2. Special Types

Four special types opts, topts vopts, and choice are used extensively by Ted for command and argument completion. The opts and topts are exclusively applied to the "args" formal argument. The last, vopts, may start at any argument and is used for a set of options that precede the actal argument. An extern that uses vopts should also use args, even when this doesn't really take variable arguments (if this is the case, the vopts itself should end with a "*").

Here are some examples.

    extern seek {channelId offset {origin start}} {. . {choice start current end}} I
    extern frame {path args} {. win {opts -bg -bd -height -width} I
    extern label {path args} {. win {topts -bd int -height int -width int} I
    extern subst {string args} {. {vopts ?-nobackslashes? ?-nocommands? ?-novariables?}} I

3. Type Arguments

Some types take arguments. eg.

  {choice A B C}
  {match [0-9]*}

Type arguments allows for finer grained type definitions.

4. Strictness

When a type is used with the first letter uppercased, it implies strict typeness. Generally a non-strict type will accept the empty string as a value, but the definition of strictness can vary from type to type.

5. Union and Intersect

The types union and intersect allow multiple types to be checked. eg

  {union double bool}     #  matches 9.9 yes True
  {intersect int bool}    #  matches 1 0

6. Opts

The type opts is used exclusively for name/value options passed in the "args" argument. Here is a typical example:

 extern tk_getOpenFile {args} {. {opts -title -initialfile}} I

7. Topts

The type topts is like opts except it contains a pair list giving the expected type for each option. Here is an example:

 extern text {w args} {. . {topts -width int -height int}} I

8. Vopts

The vopts type describes a set of options that precede a specific argument. Each set is delimited by a pairs of question marks "?...?" and the first element is a constant. Any trailing values give meaningful names to the extra arguments. A double dash "?--?" indicates the end of args.

An extern that uses vopts must have an args. When the command really does take variable arguments, it should end the vopts list with a "*", eg.

  extern exec {arg args} {. {vopts ?-keepnewline? ?--? *}} I
  extern lsort {list args} {. {vopts ?-decreasing?  ?-index index?} .} I

9. Choice

The choice type enumerates a list of literal values. eg.

  extern seek {channelId offset {origin start}} {. . Int {Choice start current end}} I

10. Pattern Types

match - String match (takes 1 arg)
imatch - String match caseless (takes 1 arg)
regexp - Regexp match (takes 1 arg)
iregexp - Regexp match caseless (takes 1 arg)

11. Tcl Code Types

Certain types are used to identify that an argument to a call is contains code. These are used to coerce compilation and checking. These are:

code - Tcl code (eg. catch, eval, etc).
subcode - Like 'code' but ignores expr errors due to % substitutions
expr - An expression
exprn - Expression to eval after replacing %n with value
cmd - A command call (eg. a callback)

12. List of Types

You can dump the list of known types using info types in Wize.

Following is a list of the standard types (with brief description):

    int     - Tcl int
    double  - Tcl double
    bool    - Tcl bool
    array   - An array.
    blist   - A binary list (even number of elements).
    choice  - Select one value from a list of choices
    char    - Tcl char.
    cmd     - Argument is count of args that will be added to Tcl command
    code    - Tcl script that will be evaluate.
    dict    - A dict value.
    date    - A date with no time.
    datetime - A date with time.
    dictvar - A variable containing a dict.
    expr    - A valid Tcl expression is expected.
    file    - A file name.
    float   - Tcl float
    list    - Tcl list.
    long    - Tcl long
    match   - Argument is used in a string match.
    matchi  - Argument is used in a string match.
    opts    - Name/value pairs where name is from a list of choices.
    noquote - N/A
    regexp  - Argument is used in a regexp.
    regexpi - Argument is used in a regexp, case insensitive.
    short   - Tcl short
    string  - A string.  Same as .
    time    - Time with no date.
    topts   - Name/value pairs where name/type is from a list of choices
    uchar   - Tcl unsigned char
    uint    - Tcl unsigned int
    ulong   - Tcl unsigned long
    ushort  - Tcl unsigned short
    uwide   - Tcl unsigned wide
    var     - A Tcl variable.
    void    - A proc returns an empty string
    vopts   - Variable or optional choices preceding an argument.
    wide    - Tcl wide.
    win     - A Tk window path.
    _       - A TOD object.
    .       - A string.

When the array type is used, it means all elements should be predefined before using inside a proc, otherwise -Wall will issue warnings.