mochikit_v14/doc/html/MochiKit/Logging.html

   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(&quot;INFO messages are so boring&quot;);
  24 logDebug(&quot;DEBUG messages are even worse&quot;);
  25 log(&quot;good thing I can pass&quot;, objects, &quot;conveniently&quot;);
  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 &quot;print&quot; 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">&quot;INFO&quot;</span></tt>, <tt class="docutils literal"><span class="pre">&quot;WARN&quot;</span></tt>,
  90 <tt class="docutils literal"><span class="pre">&quot;DEBUG&quot;</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 &quot;real-time&quot; 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">&gt;=</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 &quot;logger&quot;, 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>      -&gt; <tt class="docutils literal"><span class="pre">log</span></tt>
 117 <tt class="docutils literal"><span class="pre">logger.debug</span></tt>    -&gt; <tt class="docutils literal"><span class="pre">logDebug</span></tt>
 118 <tt class="docutils literal"><span class="pre">logger.warning</span></tt>  -&gt; <tt class="docutils literal"><span class="pre">logWarning</span></tt>
 119 <tt class="docutils literal"><span class="pre">logger.error</span></tt>    -&gt; <tt class="docutils literal"><span class="pre">logError</span></tt>
 120 <tt class="docutils literal"><span class="pre">logger.fatal</span></tt>    -&gt; <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 &lt;<a class="reference" href="mailto:bob&#64;redivi.com">bob&#64;redivi.com</a>&gt;</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 &lt;<a class="reference" href="mailto:bob&#64;redivi.com">bob&#64;redivi.com</a>&gt;. 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>