TIP #216: Handling Command-Line Options in Tclsh and Wish
_____________________________________________________________________________
TIP:	216
Title:	Handling Command-Line Options in Tclsh and Wish
Version:	$Revision: 1.5 $
Authors:	Arjen Markus <arjen.markus@wldelft.nl>
State:	Draft
Type:	Project
Tcl-Version:	8.7
Vote:	Pending
Created:	Mon Aug 23 00:00:00 UTC 2004
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:-tcl-utils" under Windows), then the following command-line is necessary:
 tclsh ~/my-tcl-utils/debug.tcl myapp.tcl
or under Windows:
 tclsh d:-tcl-utils.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.
_____________________________________________________________________________
Colophon
TIP AutoGenerator - written by Donal K. Fellows