PracTcl Programming Tips

On occasion, I write Tcl programs that don't work right the first time, and thus need to be “debugged”. The easiest way to debug a Tcl program is with the puts command.

puts stderr "Some useful information to print"

A few carefully placed puts statements can be used to ferret out most bugs. Unfortunately, it often seems the bugs have a habit of returning as soon as the puts statements are removed.

The solution to the recurring bug problem is to wrap puts in a procedure, called dputs, so we can turn debug printing on or off without changing the code:

proc dputs {args} {
  global Debug
  if {[info exists Debug]} {
     puts stderr $args
  }
}

This first version of dputs checks to see if the global variable Debug is set (to anything) before printing the arguments passed to dputs. As a side benefit, dputs lets us specify what to print as multiple arguments. The args parameter, which is special in Tcl, automatically gathers all of the arguments of dputs into a single string.

Although dputs is an improvement over puts, it doesn't take too long to discover the limitation of this version. You have the choice of either too little output or too much. What we would like to do is turn debug printing on or off selectively, in different sections of the program.

We can use the introspective capabilities of Tcl to determine which procedure each dputs is being called from, and turn debug printing on or off for each procedure. We'll use the info level command to look into the current procedure stack and figure out the name of the procedure that dputs is being called from. We can set Debug to a glob-style pattern that will cause only those dputs statements in procedures that match that pattern to print. As a bonus, we'll print the calling procedure name as part of our output, so it doesn't have to be included as an argument to dputs.

proc dputs {args} {
  global Debug
  if {![info exists Debug]} return
  set current [expr [info level] - 1]
  set caller toplevel
  catch {
    set caller [lindex [info level $current] 0]
  }
  if {[string match $Debug $caller]} {
    puts stderr "$caller: $args"
  }
}

In this version of dputs, as before, if Debug is not set, no debugging output is produced. The info level command returns the current nesting level of the procedure call stack, the dputs procedure. Subtracting one from $current is the stack level of dputs's caller. The info level $current command returns a list of information about the procedure stack at level $current, whose first element is the name of the procedure. If dputs is called at the global scope, the call to info level will fail (current will be -1), thus the catch around info level, which will leave $caller with the pre-initialized value of toplevel.

Now that we have the name of the procedure that dputs was called from, it is a simple matter for string match to compare the procedure name in $caller with the pattern in Debug, and only emit debugging output for the desired procedures. The pattern in Debug can be changed interactively at the command prompt, or automatically under program control.

Although this version of dputs is better, it requires the programmer know in advance what information to pass as arguments to dputs in order for the debug output to help locate the bug. Typically, half the battle of debugging is determining what information needs to be printed to find the bug, and what dputs prints is probably not right.

We can easily overcome this limitation by remembering that Tcl is an interpreted language. Instead of simply printing canned values that are passed as arguments to dputs, we can stop the program at any dputs call and allow the programmer to enter arbitrary Tcl commands to elicit information about the current execution state of the program.

The next procedure, breakpoint, may be inserted anywhere in a Tcl program to cause it to stop and allow interactive execution of commands. For example, the Tcl moral equivalent of the C assert command is implemented by calling breakpoint any time an invalid condition is detected. Alternately, breakpoint can be inserted into dputs so breakpoints can be turned on or off selectively using the Debug variable.

The breakpoint procedure implements four build-in commands: +, -, ? and C. The + and - commands allow the user to move up and down the call stack. The ? commands prints out useful information about the current stack frame, and C returns from breakpoint, resuming execution of the program. Any other command is passed to uplevel to be evaluated at the appropriate stack level.

proc breakpoint {} {
  set max [expr [info level] - 2]
  set current $max
  show $current
  while {1} {
    puts -nonewline stderr "#$current: "
    gets stdin line
    while {![info complete $line]} {
      puts -nonewline stderr "? "
      append line \n[gets stdin]
    }
    switch -- $line {
      + {if {$current < $max} {show [incr current]}}
      - {if {$current > 0} {show [incr current -1]}}
      C {puts stderr "Resuming execution";return}
      ? {show $current}
      default {
        catch { uplevel #$current $line } result
        puts stderr $result
      }
    }
  }
}

The procedure breakpoint demonstrates the use of the Tcl commands info level and uplevel to examine the state of a running Tcl program, and the info complete command to read and evaluate Tcl commands entered interactively.

First, info level computes the depth of the procedure call stack (in $max). We need to subtract two from info level, one for the breakpoint procedure, and one for dputs. We then loop (while {1}) getting Tcl commands and running them. The variable $current contains the current stack level, which we'll print as part of the prompt to the user.

Getting a Tcl command from the console is a little tricky, as a single command might span multiple input lines. We'll use info complete, and append commands in the inner while loop to gather up enough lines of input to form a complete Tcl command. Once we have the entire command, the switch statement selects either one of the built-in commands, or it calls uplevel to run the command at the current stack level, which may have been modified previously by + or - commands. The catch around uplevel insures that an errant command typed by the user doesn't terminate the program with an error. We then print the result of the command (or the error message if it failed), and loop back to get the next command from the user.

The built-in commands + and - are used to change the stack level that the commands we enter will be evaluated in. They simply change the value of $current. The ? command calls show, and C returns, resuming execution of the program. The procedure show, which we'll write next, displays useful information about the current stack level.

proc show {current} {
  if {$current > 0} {
    set info [info level $current]
    set proc [lindex $info 0]
    puts stderr "$current: Procedure $proc \
                {[info args $proc]}"
    set index 0
    foreach arg [info args $proc] {
      puts stderr \
           "\t$arg = [lindex $info [incr index]]"
    }
  } else {
    puts stderr "Top level"
  }
}

The procedure show is a shortcut for printing application-specific information while debugging, since the user could type in the Tcl commands to achieve the same result. This version of show, which gets passed the stack level $current as an argument, prints the procedure name, its arguments, and their values at the time the procedure was called. In dputs we used the first element of info level $current as the name of the procedure in stack frame $current. The remaining elements contain the values of the arguments passed to the procedure. The call to info args returns the names of the arguments, which we pair with their values in info level $current, using the variable index to step though the list of argument values. Here is some sample output from show, taken from a debugging session of HMtag_img, part of a Tcl HTML library package.

4: Procedure HMtag_img {win param text}
        win = .clone1.text
        param = src=green_ball.gif
        text = text
#4: info vars
var text param win
#4: set var(font)
font:courier:14:medium:r
#4: -
3: Procedure HMrender {win tag not param text}
        win = .clone1.text
        tag = img
        not =
        param = src=green_ball.gif
        text =  This is a good point
#3: C
Resuming Execution

In conclusion, we started with a simple puts for program debugging, and in less than 50 lines of Tcl code, created a powerful debugging environment that can be easily tailored to meet the debugging needs of most Tcl applications.