1.  Backtrace

Decoding a Tcl error traceback can be very tedious. This is particularly true in larger applications involving hundreds of lines of backtrace and dozens of stack levels. Therefore Mod provides a facility that automatically decodes stack tracebacks, presenting them in one-level-per-line format. Th can also optionally stop the program right at an error, before the stack unwinds in a traceback. (note: this facility is for handling runtime errors, and presumes program files have already sourced without error.)

Mod handles background errors by unwinding the stack backtrace into a one per line listing which can then be used to navigate through source code involved in an error. Here a couple of screenshots. The first is a real-error screenshot and the other the install demo-error screenshot. Clicking on any given level, a Mini-EDitor (Med) will popup displaying the file/line of error. Med provides only rudimentary capabilities, however, it does support save and so allows immediate editing and fixing of problems.

One issue with debugging Tcl is that it normally does not collect file or line information associated with procs. Mod allows forcing this collection by adding the following to the top of your program (or setting it from command-line).

 set ::env(TCL_WARN) all

When not using TCL_WARN or Wize -Wall, Mod instead falls back to show just the proc definition.

The backtrace window should look like:

Clicking on any line should open a Mini-Editor window (see below).

2.  Pausing A Program

It is sometimes desirable to pause a running program right inside a proc, to allow inspection of the runtime variables. This can be achieved using the .Break directive while running a program while running with -Wall.

Here is an example:.

    proc Invoke-Stop {_} {
        # Demo of pausing a program for inspection.
        set j 1
        .Break first
        incr j
        .Break second
    }

If run with checking on, this should open a window something like:

As shown, Tcl commands can be executed in the command input at bottom. Closing the window will resume execution, pausing again at the next .Break.

3.  Trap

Trap deals with uncaught errors by stopping the program right at the error to enable the user to inspect variables.

To enable it run the program like so:

  wize -Wlevel=all,trap=1 script.tcl

or put the following at the top of the main script

   set ::env(TCL_WARN) "level=all,trap=1"
   package require Mod

Trap stops a program-event right at the point of error, to allow introspection of the running program. Commands can then be run within a procs error context, prior to the unwinding of the stack.

Another way to use trap is selecting the trap option from Teds Run-Tcl.

WARNING: Do not always use the trap option as it exercises obscure areas of Tcl and can intermittently crash.

© 2008 Peter MacDonald