| 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 |