1debug(n) debug narrative debug(n)
2______________________________________________________________________________
6
8 debug - debug narrative - core
9
11 package require Tcl 8.5
12 package require debug ?1.0.6?
14 debug.tag message ?level?
16 debug 2array
18 debug define tag
20 debug header text
22 debug level tag ?level? ?fd?
24 debug names
26 debug off tag
28 debug on tag
30 debug parray arrayvarname
32 debug pdict dict
34 debug hexl data ?prefix?
36 debug nl
38 debug tab
40 debug prefix tag ?text?
42 debug setting (tag level) ... ?fd?
44 debug suffix tag ?text?
46 debug trailer text
48______________________________________________________________________________
50
52 Debugging areas of interest are represented by 'tags' which have inde‐
53 pendently settable levels of interest (an integer, higher is more de‐
54 tailed).
55
57 debug.tag message ?level?
58 For each known tag the package creates a command with this sig‐
59 nature the user can then use to provide the debug narrative of
60 the tag. The narrative message is provided as a Tcl script
61 whose value is substed in the caller's scope if and only if the
62 current level of interest for the tag matches or exceeds the
63 call's level of detail. This is useful, as one can place arbi‐
64 trarily complex narrative in code without unnecessarily evaluat‐
65 ing it.
66 See methods level and setting for querying and manipulating the
68 current level of detail for tags.
69 The actually printed text consists of not only the message, but
71 also global and tag-specific prefix and suffix, should they ex‐
72 ist, with each line in the message having the specified headers
73 and trailers.
74 All these parts are substableTcl scripts, which are substituted
76 once per message before assembly.
77 debug 2array
79 This method returns a dictionary mapping the names of all debug
80 tags currently known to the package to their state and log
81 level. The latter are encoded in a single numeric value, where a
82 negative number indicates an inactive tag at the level given by
83 the absolute value, and a positive number is an active tag at
84 that level.
85 See also method settings below.
87 debug define tag
89 This method registers the named tag with the package. If the
90 tag was not known before it is placed in an inactive state. The
91 state of an already known tag is left untouched.
92 The result of the method is the empty string.
94 debug header text
96 This method defines a global substable Tcl script which provides
97 a text printed before each line of output.
98 Note how this is tag-independent.
100 Further note that the header substitution happens only once per
102 actual printed message, i.e. all lines of the same message will
103 have the same actual heading text.
104 The result of the method is the specified text.
106 debug level tag ?level? ?fd?
108 This method sets the detail-level for the tag, and the channel
109 fd to write the tags narration into. The level is an integer
110 value >= 0 defaulting to 1. The channel defaults to stderr.
111 The result of the method is the new detail-level for the tag.
113 debug names
115 This method returns a list containing the names of all debug
116 tags currently known to the package.
117 debug off tag
119 This method registers the named tag with the package and sets it
120 inactive.
121 The result of the method is the empty string.
123 debug on tag
125 This method registers the named tag with the package, as active.
126 The result of the method is the empty string.
128 debug parray arrayvarname
130 This is a convenience method formatting the named array like the
131 builtin command parray, except it returns the resulting string
132 instead of writing it directly to stdout.
133 This makes it suitable for use in debug messages.
135 debug pdict dict
137 This is a convenience method formatting the dictionary similarly
138 to how the builtin command parray does for array, and returns
139 the resulting string.
140 This makes it suitable for use in debug messages.
142 debug hexl data ?prefix?
144 This is a convenience method formatting arbitrary data into a
145 hex-dump and returns the resulting string.
146 This makes it suitable for use in debug messages.
148 Each line of the dump is prefixed with prefix. This prefix de‐
150 faults to the empty string.
151 debug nl
153 This is a convenience method to insert a linefeed character
154 (ASCII 0x0a) into a debug message.
155 debug tab
157 This is a convenience method to insert a TAB character (ASCII
158 0x09) into a debug message.
159 debug prefix tag ?text?
161 This method is similar to the method header above, in that it
162 defines substable Tcl script which provides more text for debug
163 messages.
164 In contrast to header the generated text is added to the user's
166 message before it is split into lines, making it a per-message
167 extension.
168 Furthermore the script is tag-dependent.
170 In exception to that, a script for tag :: is applied to all mes‐
172 sages.
173 If both global and tag-dependent prefix exist, both are applied,
175 with the global prefix coming before the tag-dependent prefix.
176 Note that the prefix substitution happens only once per actual
178 printed message.
179 The result of the method is the empty string.
181 If the tag was not known at the time of the call it is regis‐
183 tered, and set inactive.
184 debug setting (tag level) ... ?fd?
186 This method is a multi-tag variant of method level above, with
187 the functionality of methods on, and off also folded in.
188 Each named tag is set to the detail-level following it, with a
190 negative level deactivating the tag, and a positive level acti‐
191 vating it.
192 If the last argument is not followed by a level it is not
194 treated as tag name, but as the channel all the named tags
195 should print their messages to.
196 The result of the method is the empty string.
198 debug suffix tag ?text?
200 This method is similar to the method trailer below, in that it
201 defines substable Tcl script which provides more text for debug
202 messages.
203 In contrast to trailer the generated text is added to the user's
205 message before it is split into lines, making it a per-message
206 extension.
207 Furthermore the script is tag-dependent.
209 In exception to that, a script for tag :: is applied to all mes‐
211 sages.
212 If both global and tag-dependent suffix exist, both are applied,
214 with the global suffix coming after the tag-dependent suffix.
215 Note that the suffix substitution happens only once per actual
217 printed message.
218 The result of the method is the empty string.
220 If the tag was not known at the time of the call it is regis‐
222 tered, and set inactive.
223 debug trailer text
225 This method defines a global substable Tcl script which provides
226 a text printed after each line of output (before the EOL how‐
227 ever).
228 Note how this is tag-independent.
230 Further note that the trailer substitution happens only once per
232 actual printed message, i.e. all lines of the same message will
233 have the same actual trailing text.
234 The result of the method is the specified text.
236
238 This document, and the package it describes, will undoubtedly contain
239 bugs and other problems. Please report such in the category debug of
240 the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
241 also report any ideas for enhancements you may have for either package
242 and/or documentation.
243 When proposing code changes, please provide unified diffs, i.e the out‐
245 put of diff -u.
246 Note further that attachments are strongly preferred over inlined
248 patches. Attachments can be made by going to the Edit form of the
249 ticket immediately after its creation, and then using the left-most
250 button in the secondary navigation bar.
251
253 debug, log, narrative, trace
254
256 debugging, tracing, and logging
257
259 Copyright (c) 200?, Colin McCormack, Wub Server Utilities
260 Copyright (c) 2012-2014, Andreas Kupries <andreas_kupries@users.sourceforge.net>
261tcllib 1.0.6 debug(n)