TIP #216: HANDLING COMMAND-LINE OPTIONS IN TCLSH AND WISH 
===========================================================
 Version:      $Revision: 1.5 $
 Author:       Arjen Markus <arjen.markus_at_wldelft.nl>
 State:        Draft
 Type:         Project
 Tcl-Version:  8.7
 Vote:         Pending
 Created:      Monday, 23 August 2004
 URL:          https://tip.tcl-lang.org216.html
 Post-History: 

-------------------------------------------------------------------------

 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 [<URL:http://wiki.tcl.tk/6007>] and 
 [<URL: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. 

-------------------------------------------------------------------------

 TIP AutoGenerator - written by Donal K. Fellows