Commit | Line | Data |
---|---|---|
6a1aa64f DV |
1 | <?xml version="1.0" encoding="utf-8" ?> |
2 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> | |
3 | ||
4 | <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> | |
5 | <head> | |
6 | <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> | |
7 | <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" /> | |
8 | <title>MochiKit.Logging - we're all tired of alert()</title> | |
9 | ||
10 | <link rel="stylesheet" href="../../../include/css/documentation.css" type="text/css" /> | |
11 | <script type="text/javascript" src="../../../packed/MochiKit/MochiKit.js"></script> | |
12 | <script type="text/javascript" src="../../js/toc.js"></script> | |
13 | </head> | |
14 | <body> | |
15 | <div class="document"> | |
16 | <div class="section"> | |
17 | <h1><a id="name" name="name">Name</a></h1> | |
18 | <p>MochiKit.Logging - we're all tired of alert()</p> | |
19 | </div> | |
20 | <div class="section"> | |
21 | <h1><a id="synopsis" name="synopsis">Synopsis</a></h1> | |
22 | <pre class="literal-block"> | |
23 | log("INFO messages are so boring"); | |
24 | logDebug("DEBUG messages are even worse"); | |
25 | log("good thing I can pass", objects, "conveniently"); | |
26 | </pre> | |
27 | </div> | |
28 | <div class="section"> | |
29 | <h1><a id="description" name="description">Description</a></h1> | |
30 | <p>MochiKit.Logging steals some ideas from Python's logging module <a class="footnote-reference" href="#id6" id="id1" name="id1">[1]</a>, | |
31 | but completely forgot about the Java <a class="footnote-reference" href="#id7" id="id2" name="id2">[2]</a> inspiration. This is a KISS | |
32 | module for logging that provides enough flexibility to do just about | |
33 | anything via listeners, but without all the cruft.</p> | |
34 | </div> | |
35 | <div class="section"> | |
36 | <h1><a id="dependencies" name="dependencies">Dependencies</a></h1> | |
37 | <ul class="simple"> | |
38 | <li><a class="mochiref reference" href="Base.html">MochiKit.Base</a></li> | |
39 | </ul> | |
40 | </div> | |
41 | <div class="section"> | |
42 | <h1><a id="overview" name="overview">Overview</a></h1> | |
43 | <div class="section"> | |
44 | <h2><a id="native-console-logging" name="native-console-logging">Native Console Logging</a></h2> | |
45 | <p>As of MochiKit 1.3, the default logger will log all messages to your | |
46 | browser's native console. This is currently supported in Safari, Opera | |
47 | 9, and Firefox when the <a class="reference" href="http://www.joehewitt.com/software/firebug/">FireBug</a> extension is installed. MochiKit | |
48 | 1.4 adds support for the relevant APIs for Internet Explorer (the | |
49 | Debugger and the Atlas framework, see <a class="reference" href="http://www.nikhilk.net/Entry.aspx?id=93">here</a>).</p> | |
50 | <p>To disable this behavior:</p> | |
51 | <pre class="literal-block"> | |
52 | MochiKit.Logging.logger.useNativeConsole = false; | |
53 | </pre> | |
54 | </div> | |
55 | <div class="section"> | |
56 | <h2><a id="bookmarklet-based-debugging" name="bookmarklet-based-debugging">Bookmarklet Based Debugging</a></h2> | |
57 | <p>JavaScript is at a serious disadvantage without a standard console for | |
58 | "print" statements. Everything else has one. The closest thing that | |
59 | you get in a browser environment is the <tt class="docutils literal"><span class="pre">alert</span></tt> function, which is | |
60 | absolutely evil.</p> | |
61 | <p>This leaves you with one reasonable solution: do your logging in the | |
62 | page somehow. The problem here is that you don't want to clutter the | |
63 | page with debugging tools. The solution to that problem is what we | |
64 | call BBD, or Bookmarklet Based Debugging <a class="footnote-reference" href="#id8" id="id4" name="id4">[3]</a>.</p> | |
65 | <p>Simply create a bookmarklet for | |
66 | <a class="reference" href="javascript:MochiKit.Logging.logger.debuggingBookmarklet()">javascript:MochiKit.Logging.logger.debuggingBookmarklet()</a>, and | |
67 | whack it whenever you want to see what's in the logger. Of course, | |
68 | this means you must drink the MochiKit.Logging kool-aid. It's tangy | |
69 | and sweet, don't worry.</p> | |
70 | <p>Currently this is an ugly <tt class="docutils literal"><span class="pre">alert</span></tt>, but we'll have something spiffy | |
71 | Real Soon Now, and when we do, you only have to upgrade | |
72 | MochiKit.Logging, not your bookmarklet!</p> | |
73 | </div> | |
74 | </div> | |
75 | <div class="section"> | |
76 | <h1><a id="api-reference" name="api-reference">API Reference</a></h1> | |
77 | <div class="section"> | |
78 | <h2><a id="constructors" name="constructors">Constructors</a></h2> | |
79 | <p> | |
80 | <a name="fn-logmessage"></a> | |
81 | <a class="mochidef reference" href="#fn-logmessage">LogMessage(num, level, info)</a>:</p> | |
82 | <blockquote> | |
83 | <p>Properties:</p> | |
84 | <blockquote> | |
85 | <dl class="docutils"> | |
86 | <dt><tt class="docutils literal"><span class="pre">num</span></tt>:</dt> | |
87 | <dd>Identifier for the log message</dd> | |
88 | <dt><tt class="docutils literal"><span class="pre">level</span></tt>:</dt> | |
89 | <dd>Level of the log message (<tt class="docutils literal"><span class="pre">"INFO"</span></tt>, <tt class="docutils literal"><span class="pre">"WARN"</span></tt>, | |
90 | <tt class="docutils literal"><span class="pre">"DEBUG"</span></tt>, etc.)</dd> | |
91 | <dt><tt class="docutils literal"><span class="pre">info</span></tt>:</dt> | |
92 | <dd>All other arguments passed to log function as an <tt class="docutils literal"><span class="pre">Array</span></tt></dd> | |
93 | <dt><tt class="docutils literal"><span class="pre">timestamp</span></tt>:</dt> | |
94 | <dd><tt class="docutils literal"><span class="pre">Date</span></tt> object timestamping the log message</dd> | |
95 | </dl> | |
96 | </blockquote> | |
97 | <dl class="docutils"> | |
98 | <dt><em>Availability</em>:</dt> | |
99 | <dd>Available in MochiKit 1.3.1+</dd> | |
100 | </dl> | |
101 | </blockquote> | |
102 | <p> | |
103 | <a name="fn-logger"></a> | |
104 | <a class="mochidef reference" href="#fn-logger">Logger([maxSize])</a>:</p> | |
105 | <blockquote> | |
106 | <p>A basic logger object that has a buffer of recent messages plus a | |
107 | listener dispatch mechanism for "real-time" logging of important | |
108 | messages.</p> | |
109 | <p><tt class="docutils literal"><span class="pre">maxSize</span></tt> is the maximum number of entries in the log. If | |
110 | <tt class="docutils literal"><span class="pre">maxSize</span> <span class="pre">>=</span> <span class="pre">0</span></tt>, then the log will not buffer more than that many | |
111 | messages. So if you don't like logging at all, be sure to pass | |
112 | <tt class="docutils literal"><span class="pre">0</span></tt>.</p> | |
113 | <p>There is a default logger available named "logger", and several of | |
114 | its methods are also global functions:</p> | |
115 | <blockquote> | |
116 | <tt class="docutils literal"><span class="pre">logger.log</span></tt> -> <tt class="docutils literal"><span class="pre">log</span></tt> | |
117 | <tt class="docutils literal"><span class="pre">logger.debug</span></tt> -> <tt class="docutils literal"><span class="pre">logDebug</span></tt> | |
118 | <tt class="docutils literal"><span class="pre">logger.warning</span></tt> -> <tt class="docutils literal"><span class="pre">logWarning</span></tt> | |
119 | <tt class="docutils literal"><span class="pre">logger.error</span></tt> -> <tt class="docutils literal"><span class="pre">logError</span></tt> | |
120 | <tt class="docutils literal"><span class="pre">logger.fatal</span></tt> -> <tt class="docutils literal"><span class="pre">logFatal</span></tt></blockquote> | |
121 | <dl class="docutils"> | |
122 | <dt><em>Availability</em>:</dt> | |
123 | <dd>Available in MochiKit 1.3.1+</dd> | |
124 | </dl> | |
125 | </blockquote> | |
126 | <p> | |
127 | <a name="fn-logger.prototype.addlistener"></a> | |
128 | <a class="mochidef reference" href="#fn-logger.prototype.addlistener">Logger.prototype.addListener(ident, filter, listener)</a>:</p> | |
129 | <blockquote> | |
130 | <p>Add a listener for log messages.</p> | |
131 | <p><tt class="docutils literal"><span class="pre">ident</span></tt> is a unique identifier that may be used to remove the | |
132 | listener later on.</p> | |
133 | <p><tt class="docutils literal"><span class="pre">filter</span></tt> can be one of the following:</p> | |
134 | <blockquote> | |
135 | <dl class="docutils"> | |
136 | <dt><tt class="docutils literal"><span class="pre">null</span></tt>:</dt> | |
137 | <dd><tt class="docutils literal"><span class="pre">listener(msg)</span></tt> will be called for every log message | |
138 | received.</dd> | |
139 | <dt><tt class="docutils literal"><span class="pre">string</span></tt>:</dt> | |
140 | <dd><a class="mochiref reference" href="#fn-loglevelatleast">logLevelAtLeast(filter)</a> will be used as the | |
141 | function (see below).</dd> | |
142 | <dt><tt class="docutils literal"><span class="pre">function</span></tt>:</dt> | |
143 | <dd><tt class="docutils literal"><span class="pre">filter(msg)</span></tt> will be called for every msg, if it | |
144 | returns true then <tt class="docutils literal"><span class="pre">listener(msg)</span></tt> will be called.</dd> | |
145 | </dl> | |
146 | </blockquote> | |
147 | <p><tt class="docutils literal"><span class="pre">listener</span></tt> is a function that takes one argument, a log | |
148 | message. A log message is an object (<a class="mochiref reference" href="#fn-logmessage">LogMessage</a> | |
149 | instance) that has at least these properties:</p> | |
150 | <blockquote> | |
151 | <dl class="docutils"> | |
152 | <dt><tt class="docutils literal"><span class="pre">num</span></tt>:</dt> | |
153 | <dd>A counter that uniquely identifies a log message | |
154 | (per-logger)</dd> | |
155 | <dt><tt class="docutils literal"><span class="pre">level</span></tt>:</dt> | |
156 | <dd>A string or number representing the log level. If string, | |
157 | you may want to use <tt class="docutils literal"><span class="pre">LogLevel[level]</span></tt> for comparison.</dd> | |
158 | <dt><tt class="docutils literal"><span class="pre">info</span></tt>:</dt> | |
159 | <dd>An Array of objects passed as additional arguments to the | |
160 | <tt class="docutils literal"><span class="pre">log</span></tt> function.</dd> | |
161 | </dl> | |
162 | </blockquote> | |
163 | <dl class="docutils"> | |
164 | <dt><em>Availability</em>:</dt> | |
165 | <dd>Available in MochiKit 1.3.1+</dd> | |
166 | </dl> | |
167 | </blockquote> | |
168 | <p> | |
169 | <a name="fn-logger.prototype.baselog"></a> | |
170 | <a class="mochidef reference" href="#fn-logger.prototype.baselog">Logger.prototype.baseLog(level, message[, ...])</a>:</p> | |
171 | <blockquote> | |
172 | <p>The base functionality behind all of the log functions. The first | |
173 | argument is the log level as a string or number, and all other | |
174 | arguments are used as the info list.</p> | |
175 | <p>This function is available partially applied as:</p> | |
176 | <blockquote> | |
177 | <table border="1" class="docutils"> | |
178 | <colgroup> | |
179 | <col width="61%" /> | |
180 | <col width="39%" /> | |
181 | </colgroup> | |
182 | <tbody valign="top"> | |
183 | <tr><td>Logger.debug</td> | |
184 | <td>'DEBUG'</td> | |
185 | </tr> | |
186 | <tr><td>Logger.log</td> | |
187 | <td>'INFO'</td> | |
188 | </tr> | |
189 | <tr><td>Logger.error</td> | |
190 | <td>'ERROR'</td> | |
191 | </tr> | |
192 | <tr><td>Logger.fatal</td> | |
193 | <td>'FATAL'</td> | |
194 | </tr> | |
195 | <tr><td>Logger.warning</td> | |
196 | <td>'WARNING'</td> | |
197 | </tr> | |
198 | </tbody> | |
199 | </table> | |
200 | </blockquote> | |
201 | <p>For the default logger, these are also available as global | |
202 | functions, see the <a class="mochiref reference" href="#fn-logger">Logger</a> constructor documentation | |
203 | for more info.</p> | |
204 | <dl class="docutils"> | |
205 | <dt><em>Availability</em>:</dt> | |
206 | <dd>Available in MochiKit 1.3.1+</dd> | |
207 | </dl> | |
208 | </blockquote> | |
209 | <p> | |
210 | <a name="fn-logger.prototype.clear"></a> | |
211 | <a class="mochidef reference" href="#fn-logger.prototype.clear">Logger.prototype.clear()</a>:</p> | |
212 | <blockquote> | |
213 | <p>Clear all messages from the message buffer.</p> | |
214 | <dl class="docutils"> | |
215 | <dt><em>Availability</em>:</dt> | |
216 | <dd>Available in MochiKit 1.3.1+</dd> | |
217 | </dl> | |
218 | </blockquote> | |
219 | <p> | |
220 | <a name="fn-logger.prototype.debuggingbookmarklet"></a> | |
221 | <a class="mochidef reference" href="#fn-logger.prototype.debuggingbookmarklet">Logger.prototype.debuggingBookmarklet()</a>:</p> | |
222 | <blockquote> | |
223 | <p>Display the contents of the logger in a useful way for browsers.</p> | |
224 | <p>Currently, if <a class="mochiref reference" href="LoggingPane.html">MochiKit.LoggingPane</a> is loaded, then a | |
225 | pop-up <a class="mochiref reference" href="LoggingPane.html#fn-loggingpane">MochiKit.LoggingPane.LoggingPane</a> will be | |
226 | used. Otherwise, it will be an alert with | |
227 | <a class="mochiref reference" href="#fn-logger.prototype.getmessagetext">Logger.prototype.getMessageText()</a>.</p> | |
228 | <dl class="docutils"> | |
229 | <dt><em>Availability</em>:</dt> | |
230 | <dd>Available in MochiKit 1.3.1+</dd> | |
231 | </dl> | |
232 | </blockquote> | |
233 | <p> | |
234 | <a name="fn-logger.prototype.dispatchlisteners"></a> | |
235 | <a class="mochidef reference" href="#fn-logger.prototype.dispatchlisteners">Logger.prototype.dispatchListeners(msg)</a>:</p> | |
236 | <blockquote> | |
237 | <p>Dispatch a log message to all listeners.</p> | |
238 | <dl class="docutils"> | |
239 | <dt><em>Availability</em>:</dt> | |
240 | <dd>Available in MochiKit 1.3.1+</dd> | |
241 | </dl> | |
242 | </blockquote> | |
243 | <p> | |
244 | <a name="fn-logger.prototype.getmessages"></a> | |
245 | <a class="mochidef reference" href="#fn-logger.prototype.getmessages">Logger.prototype.getMessages(howMany)</a>:</p> | |
246 | <blockquote> | |
247 | <p>Return a list of up to <tt class="docutils literal"><span class="pre">howMany</span></tt> messages from the message | |
248 | buffer.</p> | |
249 | <dl class="docutils"> | |
250 | <dt><em>Availability</em>:</dt> | |
251 | <dd>Available in MochiKit 1.3.1+</dd> | |
252 | </dl> | |
253 | </blockquote> | |
254 | <p> | |
255 | <a name="fn-logger.prototype.getmessagetext"></a> | |
256 | <a class="mochidef reference" href="#fn-logger.prototype.getmessagetext">Logger.prototype.getMessageText(howMany)</a>:</p> | |
257 | <blockquote> | |
258 | <p>Get a string representing up to the last <tt class="docutils literal"><span class="pre">howMany</span></tt> messages in | |
259 | the message buffer. The default is <tt class="docutils literal"><span class="pre">30</span></tt>.</p> | |
260 | <p>The message looks like this:</p> | |
261 | <pre class="literal-block"> | |
262 | LAST {messages.length} MESSAGES: | |
263 | [{msg.num}] {msg.level}: {m.info.join(' ')} | |
264 | [{msg.num}] {msg.level}: {m.info.join(' ')} | |
265 | ... | |
266 | </pre> | |
267 | <p>If you want some other format, use | |
268 | <a class="mochiref reference" href="#fn-logger.prototype.getmessages">Logger.prototype.getMessages</a> and do it yourself.</p> | |
269 | <dl class="docutils"> | |
270 | <dt><em>Availability</em>:</dt> | |
271 | <dd>Available in MochiKit 1.3.1+</dd> | |
272 | </dl> | |
273 | </blockquote> | |
274 | <p> | |
275 | <a name="fn-logger.prototype.removelistener"></a> | |
276 | <a class="mochidef reference" href="#fn-logger.prototype.removelistener">Logger.prototype.removeListener(ident)</a>:</p> | |
277 | <blockquote> | |
278 | <p>Remove a listener using the ident given to | |
279 | <a class="mochiref reference" href="#fn-logger.prototype.addlistener">Logger.prototype.addListener</a></p> | |
280 | <dl class="docutils"> | |
281 | <dt><em>Availability</em>:</dt> | |
282 | <dd>Available in MochiKit 1.3.1+</dd> | |
283 | </dl> | |
284 | </blockquote> | |
285 | </div> | |
286 | <div class="section"> | |
287 | <h2><a id="functions" name="functions">Functions</a></h2> | |
288 | <p> | |
289 | <a name="fn-alertlistener"></a> | |
290 | <a class="mochidef reference" href="#fn-alertlistener">alertListener(msg)</a>:</p> | |
291 | <blockquote> | |
292 | <p>Ultra-obnoxious <tt class="docutils literal"><span class="pre">alert(...)</span></tt> listener</p> | |
293 | <dl class="docutils"> | |
294 | <dt><em>Availability</em>:</dt> | |
295 | <dd>Available in MochiKit 1.3.1+</dd> | |
296 | </dl> | |
297 | </blockquote> | |
298 | <p> | |
299 | <a name="fn-log"></a> | |
300 | <a class="mochidef reference" href="#fn-log">log(message[, info[, ...]])</a>:</p> | |
301 | <blockquote> | |
302 | <p>Log an INFO message to the default logger</p> | |
303 | <dl class="docutils"> | |
304 | <dt><em>Availability</em>:</dt> | |
305 | <dd>Available in MochiKit 1.3.1+</dd> | |
306 | </dl> | |
307 | </blockquote> | |
308 | <p> | |
309 | <a name="fn-logdebug"></a> | |
310 | <a class="mochidef reference" href="#fn-logdebug">logDebug(message[, info[, ...]])</a>:</p> | |
311 | <blockquote> | |
312 | <p>Log a DEBUG message to the default logger</p> | |
313 | <dl class="docutils"> | |
314 | <dt><em>Availability</em>:</dt> | |
315 | <dd>Available in MochiKit 1.3.1+</dd> | |
316 | </dl> | |
317 | </blockquote> | |
318 | <p> | |
319 | <a name="fn-logerror"></a> | |
320 | <a class="mochidef reference" href="#fn-logerror">logError(message[, info[, ...]])</a>:</p> | |
321 | <blockquote> | |
322 | <p>Log an ERROR message to the default logger</p> | |
323 | <dl class="docutils"> | |
324 | <dt><em>Availability</em>:</dt> | |
325 | <dd>Available in MochiKit 1.3.1+</dd> | |
326 | </dl> | |
327 | </blockquote> | |
328 | <p> | |
329 | <a name="fn-logfatal"></a> | |
330 | <a class="mochidef reference" href="#fn-logfatal">logFatal(message[, info[, ...]])</a>:</p> | |
331 | <blockquote> | |
332 | <p>Log a FATAL message to the default logger</p> | |
333 | <dl class="docutils"> | |
334 | <dt><em>Availability</em>:</dt> | |
335 | <dd>Available in MochiKit 1.3.1+</dd> | |
336 | </dl> | |
337 | </blockquote> | |
338 | <p> | |
339 | <a name="fn-loglevelatleast"></a> | |
340 | <a class="mochidef reference" href="#fn-loglevelatleast">logLevelAtLeast(minLevel)</a>:</p> | |
341 | <blockquote> | |
342 | <p>Return a function that will match log messages whose level is at | |
343 | least minLevel</p> | |
344 | <dl class="docutils"> | |
345 | <dt><em>Availability</em>:</dt> | |
346 | <dd>Available in MochiKit 1.3.1+</dd> | |
347 | </dl> | |
348 | </blockquote> | |
349 | <p> | |
350 | <a name="fn-logwarning"></a> | |
351 | <a class="mochidef reference" href="#fn-logwarning">logWarning(message[, info[, ...]])</a>:</p> | |
352 | <blockquote> | |
353 | <p>Log a WARNING message to the default logger</p> | |
354 | <dl class="docutils"> | |
355 | <dt><em>Availability</em>:</dt> | |
356 | <dd>Available in MochiKit 1.3.1+</dd> | |
357 | </dl> | |
358 | </blockquote> | |
359 | </div> | |
360 | </div> | |
361 | <div class="section"> | |
362 | <h1><a id="see-also" name="see-also">See Also</a></h1> | |
363 | <table class="docutils footnote" frame="void" id="id6" rules="none"> | |
364 | <colgroup><col class="label" /><col /></colgroup> | |
365 | <tbody valign="top"> | |
366 | <tr><td class="label"><a class="fn-backref" href="#id1" name="id6">[1]</a></td><td>Python's logging module: <a class="reference" href="http://docs.python.org/lib/module-logging.html">http://docs.python.org/lib/module-logging.html</a></td></tr> | |
367 | </tbody> | |
368 | </table> | |
369 | <table class="docutils footnote" frame="void" id="id7" rules="none"> | |
370 | <colgroup><col class="label" /><col /></colgroup> | |
371 | <tbody valign="top"> | |
372 | <tr><td class="label"><a class="fn-backref" href="#id2" name="id7">[2]</a></td><td>PEP 282, where they admit all of the Java influence: <a class="reference" href="http://www.python.org/peps/pep-0282.html">http://www.python.org/peps/pep-0282.html</a></td></tr> | |
373 | </tbody> | |
374 | </table> | |
375 | <table class="docutils footnote" frame="void" id="id8" rules="none"> | |
376 | <colgroup><col class="label" /><col /></colgroup> | |
377 | <tbody valign="top"> | |
378 | <tr><td class="label"><a class="fn-backref" href="#id4" name="id8">[3]</a></td><td>Original Bookmarklet Based Debugging blather: <a class="reference" href="http://bob.pythonmac.org/archives/2005/07/03/bookmarklet-based-debugging/">http://bob.pythonmac.org/archives/2005/07/03/bookmarklet-based-debugging/</a></td></tr> | |
379 | </tbody> | |
380 | </table> | |
381 | </div> | |
382 | <div class="section"> | |
383 | <h1><a id="authors" name="authors">Authors</a></h1> | |
384 | <ul class="simple"> | |
385 | <li>Bob Ippolito <<a class="reference" href="mailto:bob@redivi.com">bob@redivi.com</a>></li> | |
386 | </ul> | |
387 | </div> | |
388 | <div class="section"> | |
389 | <h1><a id="copyright" name="copyright">Copyright</a></h1> | |
390 | <p>Copyright 2005 Bob Ippolito <<a class="reference" href="mailto:bob@redivi.com">bob@redivi.com</a>>. This program is | |
391 | dual-licensed free software; you can redistribute it and/or modify it | |
392 | under the terms of the <a class="reference" href="http://www.opensource.org/licenses/mit-license.php">MIT License</a> or the <a class="reference" href="http://www.opensource.org/licenses/afl-2.1.php">Academic Free License | |
393 | v2.1</a>.</p> | |
394 | </div> | |
395 | </div> | |
396 | ||
397 | </body> | |
398 | </html> |