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 [subst]ed and the output sent to the stream's open file descriptor.

Because the narrative string is [subst]ed in the caller's scope, one can perform arbitrarily complex computations which narrate the state of the computation, but because it's only conditionally [subst]ed 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 [http://wub.googlecode.com/svn/trunk/Utilities/Debug.tcl] and perused here [http://code.google.com/p/wub/source/browse/trunk/Utilities/Debug.tcl]
----
[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.

----
!!!!!!
%| [Category Debugging] |%
!!!!!!