Author:		Arjen Markus <arjen.markus@wldelft.nl>
State:		Draft
Type:		Project
Vote:		Pending
Created:	23-Aug-2004
Post-History:	
Tcl-Version:	8.7
Keywords:	Tcl, debugging, argument, shell

Abstract

Currently there is no means to add new command-line options to the standard Tcl shells, tclsh and wish, that can be handled at the script level. This hampers the development of, for instance, a scripted debugger or tracing tool, because the shell must be called with an awkward command line (stating the location of the script file implementing the facility). This TIP proposes a simple mechanism so that a command line like "tclsh -debug myprog.tcl" is possible. The new mechanism relies on the existing package mechanism and a few conventions. It can be implemented for the most part in Tcl.

Rationale

With Tcl 8.4 it is quite easy to create a scripted debugger - see for instance http://wiki.tcl.tk/6007 and http://wiki.tcl.tk.12251 - since this version introduced execution traces. However, it is less simple to turn that into an "out-of-the-box" resource: suppose its implementation file is "debug.tcl", residing in a directory "~/my-tcl-utils" (or "d:\my-tcl-utils" under Windows), then the following command-line is necessary:

 tclsh ~/my-tcl-utils/debug.tcl myapp.tcl

or under Windows:

 tclsh d:\my-tcl-utils\debug.tcl myapp.tcl

instead of the more elegant:

 tclsh -debug myapp.tcl

where some mechanism links the option "-debug" to the implementation file "debug.tcl".

An alternative method could be to make the file "debug.tcl" a loadable package but this requires the user to change the application: it should then load the debug package whenever the user wants to interactively debug it.

Proposed Changes

The only thing that needs to be changed in tclsh and wish (TclMain.c and TkMain.c respectively) or any other shell to benefit from this new feature is that just before sourcing the file given on the command-line or going into an interactive loop, is that a new procedure is called, "HandleCmdLine" (and some proper processing of its results).

This procedure, which will reside in init.tcl, does the following (at least in the proposed, default, implementation):

• it loops over the command-line arguments (in the global variable argv): if the argument starts with "-", it is considered an option (and it is removed from argv).

• the option is translated into the name of a package that gets loaded.

• if the initialisation code of the package recognises other arguments, it must remove them from the list contained in argv.

• this continues until an argument is found that does not qualify as an option.

A simple implementation of this procedure is:

 proc HandleCmdLine {} {
    while { [string index [lindex $::argv 0]] == "-" } {
       set pkg [string range [lindex $::argv 0] 1 end]
       package require $pkg

       set ::argv [lrange $::argv 1 end]
    }

    if { [llength $::argv] > 0 } {
       set ::argv0 [lindex $::argv 0]
       set ::argv [lrange $::argv 1 end]
    }
 }

(Details like proper error handling are left out for simplicity.)

After the call to this procedure in the C code, variable argv0 must be examined to determine if the shell is to be run interactively or not.

With the proposed mechanism, tclsh or wish can be invoked with:

 tclsh -debug myapp.tcl

or:

 tclsh -trace -out "report.out" myapp.tcl

(assuming that the package trace recognises the option -out)

or:

 wish -tkcon myapp.tcl

(assuming Tkcon has been turned into a package)

Reference Implementation

None yet.

Copyright

This document is placed in the public domain.