debug(3tcl)

💖 debug — debug narrative — core 💖

okay bestie, welcome to debug(3tcl), from the tcllib manual collection 🦋 this is the page for the debug narrative package, and ngl it's kind of a whole vibe once you get it.

---

✨ SYNOPSIS ✨

package require Tcl 8.5 9

package require debug ?1.0.7?

debug.tag message ?level?

debug 2array

debug define tag

debug header text

debug level tag ?level? ?fd?

debug names

debug off tag

debug on tag

debug parray arrayvarname

debug pdict dict

debug hexl data ?prefix?

debug nl

debug tab

debug prefix tag ?text?

debug setting (tag level) ... ?fd?

debug suffix tag ?text?

debug trailer text

---

🌸 DESCRIPTION 🌸

so basically, the areas you wanna debug are represented by tags 💅 and each tag has its own independently settable level of interest. that level is an integer, and higher = more detailed. periodt.

---

👑 API 👑

debug.tag message ?level?

for every tag the package knows about, it creates a command with this exact signature, and you (the user) can use it to feed in the debug narrative for that tag 💖

the narrative message is a Tcl script, and its value gets substed in the caller's scope — but only if the current level of interest for the tag matches or exceeds the level of detail of the call. and this is genuinely so useful bestie, because it means you can drop arbitrarily complex narrative into your code without paying to evaluate it when you don't need it. no cap. ✨

peep the methods level and setting for querying and manipulating the current level of detail for tags.

and the text that actually gets printed? it's not just the message — it's also the global and tag-specific prefix and suffix, if those exist, and every line in the message gets the specified headers and trailers 🎀

all of these parts are substable Tcl scripts, and they get substituted once per message before assembly. iconic behaviour fr fr.

debug 2array

this method returns a dictionary mapping the names of all the debug tags currently known to the package to their state and log level 👑

the state and level are encoded into one single numeric value, where:

• a negative number means the tag is inactive, at the level given by the absolute value
• a positive number means the tag is active, at that level

see also the method settings below 👀

debug define tag

this method registers the named tag with the package ✨

if the tag wasn't known before, it lands in an inactive state. if the tag was already known, its state is left completely untouched. respect.

the result of the method is the empty string.

debug header text

this method defines a global substable Tcl script that provides text printed before each line of output 💅

note how this is tag-independent. it does not care about your tags, bestie.

and further note: the header substitution happens only once per actual printed message, meaning all the lines of the same message will share the same actual heading text. consistency slay.

the result of the method is the specified text.

debug level tag ?level? ?fd?

this method sets the detail-level for tag, and also the channel fd to write that tag's narration into 🎀

• level is an integer value >= 0, and it defaults to 1
• the channel defaults to stderr

the result of the method is the new detail-level for the tag.

debug names

this method returns a list containing the names of all the debug tags currently known to the package 💖

debug off tag

this method registers the named tag with the package and sets it inactive.

the result of the method is the empty string.

debug on tag

this method registers the named tag with the package, as active ✅

the result of the method is the empty string.

debug parray arrayvarname

this is a convenience method that formats the named array exactly like the builtin command parray does — except it returns the resulting string instead of writing it straight to stdout 🌸

which is exactly what makes it suitable for use inside debug messages.

debug pdict dict

this is a convenience method that formats the dictionary similarly to how the builtin command parray does it for an array, and returns the resulting string 💜

which makes it suitable for use inside debug messages.

debug hexl data ?prefix?

this is a convenience method that formats arbitrary data into a hex-dump and returns the resulting string 🌈

which makes it suitable for use inside debug messages.

each line of the dump is prefixed with prefix, and that prefix defaults to the empty string.

debug nl

this is a convenience method to insert a linefeed character (ASCII 0x0a) into a debug message 🦋

debug tab

this is a convenience method to insert a TAB character (ASCII 0x09) into a debug message 🦋

debug prefix tag ?text?

this method is similar to the method header up there, in that it defines a substable Tcl script providing more text for debug messages 💅

but in contrast to header, the generated text is added to the user's message before it is split into lines, which makes it a per-message extension.

also, the script is tag-dependent 🔥

and in exception to all that: a script for tag :: is applied to all messages. she's the main character, she applies everywhere.

if both a global and a tag-dependent prefix exist, both are applied, with the global prefix coming before the tag-dependent prefix.

note that the prefix substitution happens only once per actual printed message.

the result of the method is the empty string.

if the tag wasn't known at the time of the call, it gets registered, and set inactive.

debug setting (tag level) ... ?fd?

this method is the multi-tag variant of the method level above, with the functionality of the methods on and off also folded in 👑

each named tag gets set to the detail-level that follows it:

• a negative level deactivates the tag
• a positive level activates it

and if the last argument isn't followed by a level, it isn't treated as a tag name — it's treated as the channel that all the named tags should print their messages to 💖

the result of the method is the empty string.

debug suffix tag ?text?

this method is similar to the method trailer below, in that it defines a substable Tcl script providing more text for debug messages 💅

but in contrast to trailer, the generated text is added to the user's message before it is split into lines, making it a per-message extension.

also, the script is tag-dependent 🔥

and in exception to that: a script for tag :: is applied to all messages.

if both a global and a tag-dependent suffix exist, both are applied, with the global suffix coming after the tag-dependent suffix.

note that the suffix substitution happens only once per actual printed message.

the result of the method is the empty string.

if the tag wasn't known at the time of the call, it gets registered, and set inactive.

debug trailer text

this method defines a global substable Tcl script providing text printed after each line of output — but before the EOL, however 💅

note how this is tag-independent.

further note that the trailer substitution happens only once per actual printed message, i.e. all the lines of the same message will have the same actual trailing text.

the result of the method is the specified text.

---

🫶 BUGS, IDEAS, FEEDBACK 🫶

bestie, this document — and the package it describes — will undoubtedly contain bugs and other problems 😭 it's giving "we know". please report those in the category debug of the Tcllib Trackers: http://core.tcl.tk/tcllib/reportlist. and please also report any ideas you have for enhancements, whether for the package and/or the documentation. we want them. we love them. 💖

when proposing code changes, please provide unified diffs, i.e. the output of diff -u 🎀

and note further that attachments are strongly preferred over inlined patches. you can attach stuff by going to the Edit form of the ticket immediately after creating it, and then using the left-most button in the secondary navigation bar. iykyk 👑

---

⭐ KEYWORDS ⭐

debug, log, narrative, trace

---

🌈 CATEGORY 🌈

debugging, tracing, and logging

---

💜 COPYRIGHT 💜

Copyright (c) 200?, Colin McCormack, Wub Server Utilities
Copyright (c) 2012-2014, Andreas Kupries <andreas_kupries@users.sourceforge.net>

---

okay that's the whole page, you ate it 🎀 this was debug(3tcl) — manual page debug, section 3tcl — shipped with tcllib version 1.0.7, dated in the footer as you'd expect. go forth and narrate your debug output, queen 👑✨💅