Debug is a Wub utility to produce debug narrative. It is useful because a deselected debugging narrative stream is implemented as a very efficient noop, so it encourages the user to create narratives as complex as necessary for understanding.

Usage

First declare a narrative stream thus:

   Debug on FOO 100

Where FOO is the narrative stream's name, and 100 is the level of interest we have in it. By convention, higher numbers are more detailed.

Then, scatter narrative through your code thus:

   Debug.FOO {this is an arbitrary expression containing $vars [and exprs]} 10

If the level of interest of the narrative line is less than the currently assigned level of interest, the narrative is substed and the output sent to the stream's open file descriptor.

Because the narrative string is substed in the caller's scope, one can perform arbitrarily complex computations which narrate the state of the computation, but because it's only conditionally substed according to level of interest in each narrative stream, the user can feel free to pepper their code with Debug narrative at fairly low cost when the Debugging's not needed. In my opinion, this freedom makes for a more literate programming style, more readable code, and easier debugging.

Latest version may be sourced here [1] and perused here [2]

---

Lars H, 2008-08-26: Some remarks…

1. If the message length is between 4097 and 8193 characters in length, the above "truncating" actually amounts to repeating the central part of it!
2. Don't do uplevel 1 ::subst -nobackslashes [list $message], do uplevel 1 [list ::subst -nobackslashes $message] — avoids some shimmering.
3. You probably need to clarify what is meant by "an arbitrary expression containing $vars [and exprs]" in the docs; subst was not an association I got from that.
4. string map {\n \\n} $result is a rather inconsistent (and IMHO ugly) way of quoting newlines. string range [list $result\{] 0 end-2 is an alternative.
5. To be "no-op if disabled" is a feature also of the tcllib logger package, but that doesn't do substitution on the message, so dynamic messages would still be formed.
6. Why -nobackslashes in the subst?

CMcC Thanks Lars! I took the view that backslash interpretation is a bad thing for code (usually) destined for a log file. I don't understand what that string range in 4 does. Everything else is (I hope) fixed.

Lars H: The idea in 4 is to make list quote all newlines, by giving it an unbalanced string (the extra left brace at the end); this prevents wrapping the string up in a brace and thus forces backslashing all special characters instead, in particular newline which becomes \n, whereas any existing \n becomes \\n. The string range then removes the extra final \{ from the string rep of the list. The downside of this technique is that it also backslashes all spaces, which can be annoying in text but works fairly well for raw data.

An alternative I thought of later at night is string map {\n \u240A} $result — \u240A (␊)is "symbol for line feed". That is probably more practical.

---