1. Development

The devel macro commands are used to simplify debugging when warnings are enabled. If warnings are disabled, these all return the empty string and do nothing.

Moreover, the commands can become Tcl noops by calling Mod ndebug: A noop has zero runtime overhead.

Here's an example:

  proc Foo {n m} {
     .Trace
     .Assert {$n>0 && $n<1000} 1
     if {[.Debug] != {}} {
        CheckRange $m $n
     }
     .Debug {
        if {$n < $m} { .Break BadN1 }
     }
     .Warn "Begin processing"
     return $n.0
  }

Note that all commands start with period + capital letter.

Below are the supported commands.

1.1 .Assert expr ?warnonly?

Evaluate the expression expr. The expression should use curley braces to avoid a double eval. If warnonly==1 then calls .Warn instead of causing an error. If warnonly>1 the output contains detailed stack info (ie. to help debugging).

  .Assert {$n>0}
  .Assert {$n>1} 1
  .Assert {$n<-1} 2

1.2 .Break ?str?

Invoke Tcl inspect, eg.

  .Break stop1

1.3 .Debug ?script?

If called with no argument it returns the current debug level. Otherwise evaluate the script and issue a warning only if an error occurs.

Usage:

  if {[.Debug]!=""} {
     if {$m==$n} { error "equal error" }
  }
  .Debug {
     if {$n<$m} { error "range error" }
  }

WARNING: Do not do the following as it can result in a runtime error:

if {[.Debug]} { #... }

1.4 .Error str ?subst?

Kick an error. If subst is true, evaluate str first.

The following are roughly equivalent:

  .Error {bad call: $n} 1
  if {[.Debug] != {}} { error "bad call: $n" }

1.5 .Trace ?-num cnt? ?-fmt bool? ?-prefix str?

Dump the call-stack info from the current proc. The default is to dump only the current proc, with no formatting or prefix. Using a cnt of -1 will dump the whole call-stack.

If -fmt is true, show a in name=value form

  proc Foo {n} {
     .Trace -num -1 -fmt 1
  }

1.6 .Warn str ?subst?

Log a warning message using tclLog. If subst is true, evaluate str first.

  .Warn "Something bad happened"
  .Warn {Range error: $m>$n} 1