debug(n)

okay bestie, welcome to debug(n) — the debug narrative core manual. It's giving Tcl debugging, it's giving tags, it's giving levels, and I'm obsessed. 🎀

---

💖 NAME 💖

debug - debug narrative - core

---

📜 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 like, every debugging area you care about is a tag. Each tag has its own level of interest — that's an integer, and the higher it is, the more detailed the tea gets. No cap. 🫖

---

🛠️ API 🛠️

Now the main character methods. Periodt.

• debug.tag message ?level? — For every tag the package knows, it creates a command with this exact signature, and you use it to drop the debug narrative for that tag. The narrative message is a Tcl script, and its value gets substed in the caller's scope only if the tag's current level of interest matches or exceeds the level of detail you asked for. That's iconic because you can put super complex narrative in your code without it getting evaluated when you don't need it. 💅

Wanna query or mess with a tag's current detail level? See methods level and setting.

The text that actually prints isn't just your message — it can also include global and tag-specific prefix and suffix, if those exist. And every line in the message gets the specified headers and trailers. The whole ensemble, okay?

All these parts are substableTcl scripts, and they get substituted once per message before assembly. Slay.

• debug 2array — This one returns a dictionary that maps every debug tag name currently known to the package over to its state and log level. Those two are packed into one numeric value: a negative number means the tag is inactive, and the level is the absolute value; a positive number means the tag is active at that level. See also method settings below.
• debug define tag — Registers the named tag with the package. If the tag was unknown before, it goes into an inactive state. If the tag was already known, its state is left completely untouched. The result is the empty string.
• debug header text — Defines a global substable Tcl script that gives you text printed before each line of output. Note that this is tag-independent, bestie. Also note that the header substitution only happens once per actual printed message, so every line in the same message gets the same actual heading text. The result is the specified text.
• debug level tag ?level? ?fd? — Sets the detail-level for the tag, and sets the channel fd where that tag's narration gets written. The level is an integer >= 0 and defaults to 1. The channel defaults to stderr. The result is the new detail-level for the tag.
• debug names — Returns a list of all the debug tag names the package currently knows. Cute.
• debug off tag — Registers the named tag with the package and sets it inactive. The result is the empty string.
• debug on tag — Registers the named tag with the package and sets it active. The result is the empty string.
• debug parray arrayvarname — A convenience method that formats the named array like the builtin parray command does — except this one returns the resulting string instead of writing it straight to stdout. That makes it suitable for use in debug messages. Obsessed.
• debug pdict dict — Another convenience method, this time formatting the dictionary similarly to how builtin parray handles arrays. It returns the resulting string, so it's also suitable for use in debug messages.
• debug hexl data ?prefix? — Convenience method that formats arbitrary data into a hex-dump and returns the resulting string. Perfect for debug messages. Each line of the dump gets prefixed with prefix, and that prefix defaults to the empty string.
• debug nl — Convenience method to insert a linefeed character (ASCII 0x0a) into a debug message.
• debug tab — Convenience method to insert a TAB character (ASCII 0x09) into a debug message.
• debug prefix tag ?text? — This one is like the header method above, because it defines a substable Tcl script that provides more text for debug messages. But here's the contrast: the generated text gets added to your message before it's split into lines, so it's a per-message extension. Also, the script is tag-dependent. Exception: a script for tag :: gets applied to all messages. If both a global and a tag-dependent prefix exist, both get applied, with the global prefix coming before the tag-dependent prefix. Note that prefix substitution happens only once per actual printed message. The result is the empty string. And if the tag wasn't known when you called this, it gets registered and set inactive.
• debug setting (tag level) ... ?fd? — This is the multi-tag variant of the level method above, and it also folds in the functionality of on and off. Each named tag gets set to the detail-level that follows it: a negative level deactivates the tag, and a positive level activates it. If the last argument isn't followed by a level, it's not treated as a tag name — it's treated as the channel that all the named tags should print their messages to. The result is the empty string.
• debug suffix tag ?text? — Similar to the trailer method below, because it defines a substable Tcl script that provides more text for debug messages. But in contrast to trailer, the generated text gets added to your message before it's split into lines, making it a per-message extension. The script is tag-dependent. Exception: a script for tag :: is applied to all messages. If both a global and a tag-dependent suffix exist, both get applied, with the global suffix coming after the tag-dependent suffix. Note that suffix substitution happens only once per actual printed message. The result is the empty string. If the tag wasn't known at call time, it gets registered and set inactive.
• debug trailer text — Defines a global substable Tcl script that provides text printed after each line of output (but before the EOL, bestie). This is tag-independent. Also, the trailer substitution happens only once per actual printed message, so all lines of the same message get the same actual trailing text. The result is the specified text.

---

🐛 BUGS, IDEAS, FEEDBACK 🐛

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report those in the category debug of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also report any ideas for enhancements you may have for either the package and/or the documentation.

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

Also note: attachments are strongly preferred over inlined patches. You can make attachments by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar.

---

🔑 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>

---

And that's the whole vibe. This page came from tcllib, version 1.0.7, and it's the debug(n) manual. Stay debuggy, bestie. 💅✨