mochikit_v14/doc/rst/MochiKit/Logging.rst

   1 .. title:: MochiKit.Logging - we're all tired of alert()
   2
   3 Name
   4 ====
   5
   6 MochiKit.Logging - we're all tired of alert()
   7
   8
   9 Synopsis
  10 ========
  11
  12 ::
  13
  14     log("INFO messages are so boring");
  15     logDebug("DEBUG messages are even worse");
  16     log("good thing I can pass", objects, "conveniently");
  17
  18
  19 Description
  20 ===========
  21
  22 MochiKit.Logging steals some ideas from Python's logging module [1]_,
  23 but completely forgot about the Java [2]_ inspiration. This is a KISS
  24 module for logging that provides enough flexibility to do just about
  25 anything via listeners, but without all the cruft.
  26
  27
  28 Dependencies
  29 ============
  30
  31 - :mochiref:`MochiKit.Base`
  32
  33
  34 Overview
  35 ========
  36
  37 Native Console Logging
  38 ----------------------
  39
  40 As of MochiKit 1.3, the default logger will log all messages to your
  41 browser's native console. This is currently supported in Safari, Opera
  42 9, and Firefox when the `FireBug`_ extension is installed. MochiKit
  43 1.4 adds support for the relevant APIs for Internet Explorer (the
  44 Debugger and the Atlas framework, see `here`__).
  45
  46 .. __: http://www.nikhilk.net/Entry.aspx?id=93
  47 .. _`FireBug`: http://www.joehewitt.com/software/firebug/
  48
  49 To disable this behavior::
  50
  51     MochiKit.Logging.logger.useNativeConsole = false;
  52
  53
  54 Bookmarklet Based Debugging
  55 ---------------------------
  56
  57 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 ``alert`` function, which is
  60 absolutely evil.
  61
  62 This leaves you with one reasonable solution: do your logging in the
  63 page somehow. The problem here is that you don't want to clutter the
  64 page with debugging tools. The solution to that problem is what we
  65 call BBD, or Bookmarklet Based Debugging [3]_.
  66
  67 Simply create a bookmarklet for
  68 `javascript:MochiKit.Logging.logger.debuggingBookmarklet()`__, and
  69 whack it whenever you want to see what's in the logger. Of course,
  70 this means you must drink the MochiKit.Logging kool-aid. It's tangy
  71 and sweet, don't worry.
  72
  73 .. __: javascript:MochiKit.Logging.logger.debuggingBookmarklet()
  74
  75 Currently this is an ugly ``alert``, but we'll have something spiffy
  76 Real Soon Now, and when we do, you only have to upgrade
  77 MochiKit.Logging, not your bookmarklet!
  78
  79
  80 API Reference
  81 =============
  82
  83 Constructors
  84 ------------
  85
  86 :mochidef:`LogMessage(num, level, info)`:
  87
  88     Properties:
  89
  90         ``num``:
  91             Identifier for the log message
  92
  93         ``level``:
  94             Level of the log message (``"INFO"``, ``"WARN"``,
  95             ``"DEBUG"``, etc.)
  96
  97         ``info``:
  98             All other arguments passed to log function as an ``Array``
  99
 100         ``timestamp``:
 101             ``Date`` object timestamping the log message
 102
 103     *Availability*:
 104         Available in MochiKit 1.3.1+
 105
 106
 107 :mochidef:`Logger([maxSize])`:
 108
 109     A basic logger object that has a buffer of recent messages plus a
 110     listener dispatch mechanism for "real-time" logging of important
 111     messages.
 112
 113     ``maxSize`` is the maximum number of entries in the log.  If
 114     ``maxSize >= 0``, then the log will not buffer more than that many
 115     messages. So if you don't like logging at all, be sure to pass
 116     ``0``.
 117
 118     There is a default logger available named "logger", and several of
 119     its methods are also global functions:
 120
 121         ``logger.log``      -> ``log``
 122         ``logger.debug``    -> ``logDebug``
 123         ``logger.warning``  -> ``logWarning``
 124         ``logger.error``    -> ``logError``
 125         ``logger.fatal``    -> ``logFatal``
 126
 127     *Availability*:
 128         Available in MochiKit 1.3.1+
 129
 130
 131 :mochidef:`Logger.prototype.addListener(ident, filter, listener)`:
 132
 133     Add a listener for log messages.
 134
 135     ``ident`` is a unique identifier that may be used to remove the
 136     listener later on.
 137
 138     ``filter`` can be one of the following:
 139
 140         ``null``:
 141             ``listener(msg)`` will be called for every log message
 142             received.
 143
 144         ``string``:
 145             :mochiref:`logLevelAtLeast(filter)` will be used as the
 146             function (see below).
 147
 148         ``function``:
 149             ``filter(msg)`` will be called for every msg, if it
 150             returns true then ``listener(msg)`` will be called.
 151
 152     ``listener`` is a function that takes one argument, a log
 153     message. A log message is an object (:mochiref:`LogMessage`
 154     instance) that has at least these properties:
 155
 156         ``num``:
 157             A counter that uniquely identifies a log message
 158             (per-logger)
 159
 160         ``level``:
 161             A string or number representing the log level. If string,
 162             you may want to use ``LogLevel[level]`` for comparison.
 163
 164         ``info``:
 165             An Array of objects passed as additional arguments to the
 166             ``log`` function.
 167
 168     *Availability*:
 169         Available in MochiKit 1.3.1+
 170
 171
 172 :mochidef:`Logger.prototype.baseLog(level, message[, ...])`:
 173
 174     The base functionality behind all of the log functions.  The first
 175     argument is the log level as a string or number, and all other
 176     arguments are used as the info list.
 177
 178     This function is available partially applied as:
 179
 180         ==============  =========
 181         Logger.debug    'DEBUG'
 182         Logger.log      'INFO'
 183         Logger.error    'ERROR'
 184         Logger.fatal    'FATAL'
 185         Logger.warning  'WARNING'
 186         ==============  =========
 187
 188     For the default logger, these are also available as global
 189     functions, see the :mochiref:`Logger` constructor documentation
 190     for more info.
 191
 192     *Availability*:
 193         Available in MochiKit 1.3.1+
 194
 195
 196 :mochidef:`Logger.prototype.clear()`:
 197
 198     Clear all messages from the message buffer.
 199
 200     *Availability*:
 201         Available in MochiKit 1.3.1+
 202
 203
 204 :mochidef:`Logger.prototype.debuggingBookmarklet()`:
 205
 206     Display the contents of the logger in a useful way for browsers.
 207
 208     Currently, if :mochiref:`MochiKit.LoggingPane` is loaded, then a
 209     pop-up :mochiref:`MochiKit.LoggingPane.LoggingPane` will be
 210     used. Otherwise, it will be an alert with
 211     :mochiref:`Logger.prototype.getMessageText()`.
 212
 213     *Availability*:
 214         Available in MochiKit 1.3.1+
 215
 216
 217 :mochidef:`Logger.prototype.dispatchListeners(msg)`:
 218
 219     Dispatch a log message to all listeners.
 220
 221     *Availability*:
 222         Available in MochiKit 1.3.1+
 223
 224
 225 :mochidef:`Logger.prototype.getMessages(howMany)`:
 226
 227     Return a list of up to ``howMany`` messages from the message
 228     buffer.
 229
 230     *Availability*:
 231         Available in MochiKit 1.3.1+
 232
 233
 234 :mochidef:`Logger.prototype.getMessageText(howMany)`:
 235
 236     Get a string representing up to the last ``howMany`` messages in
 237     the message buffer. The default is ``30``.
 238
 239     The message looks like this::
 240
 241         LAST {messages.length} MESSAGES:
 242           [{msg.num}] {msg.level}: {m.info.join(' ')}
 243           [{msg.num}] {msg.level}: {m.info.join(' ')}
 244           ...
 245
 246     If you want some other format, use
 247     :mochiref:`Logger.prototype.getMessages` and do it yourself.
 248
 249     *Availability*:
 250         Available in MochiKit 1.3.1+
 251
 252
 253 :mochidef:`Logger.prototype.removeListener(ident)`:
 254
 255     Remove a listener using the ident given to
 256     :mochiref:`Logger.prototype.addListener`
 257
 258     *Availability*:
 259         Available in MochiKit 1.3.1+
 260
 261
 262 Functions
 263 ---------
 264
 265 :mochidef:`alertListener(msg)`:
 266
 267     Ultra-obnoxious ``alert(...)`` listener
 268
 269     *Availability*:
 270         Available in MochiKit 1.3.1+
 271
 272
 273 :mochidef:`log(message[, info[, ...]])`:
 274
 275     Log an INFO message to the default logger
 276
 277     *Availability*:
 278         Available in MochiKit 1.3.1+
 279
 280
 281 :mochidef:`logDebug(message[, info[, ...]])`:
 282
 283     Log a DEBUG message to the default logger
 284
 285     *Availability*:
 286         Available in MochiKit 1.3.1+
 287
 288
 289 :mochidef:`logError(message[, info[, ...]])`:
 290
 291     Log an ERROR message to the default logger
 292
 293     *Availability*:
 294         Available in MochiKit 1.3.1+
 295
 296
 297 :mochidef:`logFatal(message[, info[, ...]])`:
 298
 299     Log a FATAL message to the default logger
 300
 301     *Availability*:
 302         Available in MochiKit 1.3.1+
 303
 304
 305 :mochidef:`logLevelAtLeast(minLevel)`:
 306
 307     Return a function that will match log messages whose level is at
 308     least minLevel
 309
 310     *Availability*:
 311         Available in MochiKit 1.3.1+
 312
 313
 314 :mochidef:`logWarning(message[, info[, ...]])`:
 315
 316     Log a WARNING message to the default logger
 317
 318     *Availability*:
 319         Available in MochiKit 1.3.1+
 320
 321
 322 See Also
 323 ========
 324
 325 .. [1] Python's logging module: http://docs.python.org/lib/module-logging.html
 326 .. [2] PEP 282, where they admit all of the Java influence: http://www.python.org/peps/pep-0282.html
 327 .. [3] Original Bookmarklet Based Debugging blather: http://bob.pythonmac.org/archives/2005/07/03/bookmarklet-based-debugging/
 328
 329
 330 Authors
 331 =======
 332
 333 - Bob Ippolito <bob@redivi.com>
 334
 335
 336 Copyright
 337 =========
 338
 339 Copyright 2005 Bob Ippolito <bob@redivi.com>. This program is
 340 dual-licensed free software; you can redistribute it and/or modify it
 341 under the terms of the `MIT License`_ or the `Academic Free License
 342 v2.1`_.
 343
 344 .. _`MIT License`: http://www.opensource.org/licenses/mit-license.php
 345 .. _`Academic Free License v2.1`: http://www.opensource.org/licenses/afl-2.1.php