1debug(n)                        debug narrative                       debug(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       debug - debug narrative - core
9

SYNOPSIS

11       package require Tcl  8.5
12
13       package require debug  ?1.0.6?
14
15       debug.tag message ?level?
16
17       debug 2array
18
19       debug define tag
20
21       debug header text
22
23       debug level tag ?level? ?fd?
24
25       debug names
26
27       debug off tag
28
29       debug on tag
30
31       debug parray arrayvarname
32
33       debug pdict dict
34
35       debug hexl data ?prefix?
36
37       debug nl
38
39       debug tab
40
41       debug prefix tag ?text?
42
43       debug setting (tag level) ... ?fd?
44
45       debug suffix tag ?text?
46
47       debug trailer text
48
49______________________________________________________________________________
50

DESCRIPTION

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

API

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
67              See methods level and setting for querying and manipulating  the
68              current level of detail for tags.
69
70              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
75              All these parts are substableTcl scripts, which are  substituted
76              once per message before assembly.
77
78       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
86              See also method settings below.
87
88       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
93              The result of the method is the empty string.
94
95       debug header text
96              This method defines a global substable Tcl script which provides
97              a text printed before each line of output.
98
99              Note how this is tag-independent.
100
101              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
105              The result of the method is the specified text.
106
107       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
112              The result of the method is the new detail-level for the tag.
113
114       debug names
115              This  method  returns  a  list containing the names of all debug
116              tags currently known to the package.
117
118       debug off tag
119              This method registers the named tag with the package and sets it
120              inactive.
121
122              The result of the method is the empty string.
123
124       debug on tag
125              This method registers the named tag with the package, as active.
126
127              The result of the method is the empty string.
128
129       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
134              This makes it suitable for use in debug messages.
135
136       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
141              This makes it suitable for use in debug messages.
142
143       debug hexl data ?prefix?
144              This  is  a  convenience method formatting arbitrary data into a
145              hex-dump and returns the resulting string.
146
147              This makes it suitable for use in debug messages.
148
149              Each line of the dump is prefixed with prefix. This  prefix  de‐
150              faults to the empty string.
151
152       debug nl
153              This  is  a  convenience  method  to insert a linefeed character
154              (ASCII 0x0a) into a debug message.
155
156       debug tab
157              This is a convenience method to insert a  TAB  character  (ASCII
158              0x09) into a debug message.
159
160       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
165              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
169              Furthermore the script is tag-dependent.
170
171              In exception to that, a script for tag :: is applied to all mes‐
172              sages.
173
174              If both global and tag-dependent prefix exist, both are applied,
175              with the global prefix coming before the tag-dependent prefix.
176
177              Note  that  the prefix substitution happens only once per actual
178              printed message.
179
180              The result of the method is the empty string.
181
182              If the tag was not known at the time of the call  it  is  regis‐
183              tered, and set inactive.
184
185       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
189              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
193              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
197              The result of the method is the empty string.
198
199       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
204              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
208              Furthermore the script is tag-dependent.
209
210              In exception to that, a script for tag :: is applied to all mes‐
211              sages.
212
213              If both global and tag-dependent suffix exist, both are applied,
214              with the global suffix coming after the tag-dependent suffix.
215
216              Note that the suffix substitution happens only once  per  actual
217              printed message.
218
219              The result of the method is the empty string.
220
221              If  the  tag  was not known at the time of the call it is regis‐
222              tered, and set inactive.
223
224       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
229              Note how this is tag-independent.
230
231              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
235              The result of the method is the specified text.
236

BUGS, IDEAS, FEEDBACK

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
244       When proposing code changes, please provide unified diffs, i.e the out‐
245       put of diff -u.
246
247       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

KEYWORDS

253       debug, log, narrative, trace
254

CATEGORY

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>
261
262
263
264
265tcllib                               1.0.6                            debug(n)
Impressum