Commit | Line | Data |
---|---|---|
6a1aa64f DV |
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 |