[dygraphs.git] / mochikit_v14 / doc / rst / MochiKit / Logging.rst

.. title:: MochiKit.Logging - we're all tired of alert()

Name
====

MochiKit.Logging - we're all tired of alert()


Synopsis
========

::

    log("INFO messages are so boring");
    logDebug("DEBUG messages are even worse");
    log("good thing I can pass", objects, "conveniently");


Description
===========

MochiKit.Logging steals some ideas from Python's logging module [1]_,
but completely forgot about the Java [2]_ inspiration. This is a KISS
module for logging that provides enough flexibility to do just about
anything via listeners, but without all the cruft.


Dependencies
============

- :mochiref:`MochiKit.Base`


Overview
========

Native Console Logging
----------------------

As of MochiKit 1.3, the default logger will log all messages to your
browser's native console. This is currently supported in Safari, Opera
9, and Firefox when the `FireBug`_ extension is installed. MochiKit
1.4 adds support for the relevant APIs for Internet Explorer (the
Debugger and the Atlas framework, see `here`__).

.. __: http://www.nikhilk.net/Entry.aspx?id=93
.. _`FireBug`: http://www.joehewitt.com/software/firebug/

To disable this behavior::

    MochiKit.Logging.logger.useNativeConsole = false;


Bookmarklet Based Debugging
---------------------------

JavaScript is at a serious disadvantage without a standard console for
"print" statements. Everything else has one. The closest thing that
you get in a browser environment is the ``alert`` function, which is
absolutely evil.

This leaves you with one reasonable solution: do your logging in the
page somehow. The problem here is that you don't want to clutter the
page with debugging tools. The solution to that problem is what we
call BBD, or Bookmarklet Based Debugging [3]_.

Simply create a bookmarklet for
`javascript:MochiKit.Logging.logger.debuggingBookmarklet()`__, and
whack it whenever you want to see what's in the logger. Of course,
this means you must drink the MochiKit.Logging kool-aid. It's tangy
and sweet, don't worry.

.. __: javascript:MochiKit.Logging.logger.debuggingBookmarklet()

Currently this is an ugly ``alert``, but we'll have something spiffy
Real Soon Now, and when we do, you only have to upgrade
MochiKit.Logging, not your bookmarklet!


API Reference
=============

Constructors
------------

:mochidef:`LogMessage(num, level, info)`:

    Properties:

        ``num``:
            Identifier for the log message

        ``level``:
            Level of the log message (``"INFO"``, ``"WARN"``,
            ``"DEBUG"``, etc.)

        ``info``:
            All other arguments passed to log function as an ``Array``

        ``timestamp``:
            ``Date`` object timestamping the log message

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Logger([maxSize])`:

    A basic logger object that has a buffer of recent messages plus a
    listener dispatch mechanism for "real-time" logging of important
    messages.

    ``maxSize`` is the maximum number of entries in the log.  If
    ``maxSize >= 0``, then the log will not buffer more than that many
    messages. So if you don't like logging at all, be sure to pass
    ``0``.

    There is a default logger available named "logger", and several of
    its methods are also global functions:

        ``logger.log``      -> ``log``
        ``logger.debug``    -> ``logDebug``
        ``logger.warning``  -> ``logWarning``
        ``logger.error``    -> ``logError``
        ``logger.fatal``    -> ``logFatal``

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Logger.prototype.addListener(ident, filter, listener)`:

    Add a listener for log messages.

    ``ident`` is a unique identifier that may be used to remove the
    listener later on.

    ``filter`` can be one of the following:

        ``null``:
            ``listener(msg)`` will be called for every log message
            received.

        ``string``:
            :mochiref:`logLevelAtLeast(filter)` will be used as the
            function (see below).

        ``function``:
            ``filter(msg)`` will be called for every msg, if it
            returns true then ``listener(msg)`` will be called.

    ``listener`` is a function that takes one argument, a log
    message. A log message is an object (:mochiref:`LogMessage`
    instance) that has at least these properties:

        ``num``:
            A counter that uniquely identifies a log message
            (per-logger)

        ``level``:
            A string or number representing the log level. If string,
            you may want to use ``LogLevel[level]`` for comparison.

        ``info``:
            An Array of objects passed as additional arguments to the
            ``log`` function.

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Logger.prototype.baseLog(level, message[, ...])`:

    The base functionality behind all of the log functions.  The first
    argument is the log level as a string or number, and all other
    arguments are used as the info list.

    This function is available partially applied as:

        ==============  =========
        Logger.debug    'DEBUG'
        Logger.log      'INFO'
        Logger.error    'ERROR'
        Logger.fatal    'FATAL'
        Logger.warning  'WARNING'
        ==============  =========

    For the default logger, these are also available as global
    functions, see the :mochiref:`Logger` constructor documentation
    for more info.

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Logger.prototype.clear()`:

    Clear all messages from the message buffer.

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Logger.prototype.debuggingBookmarklet()`:

    Display the contents of the logger in a useful way for browsers.

    Currently, if :mochiref:`MochiKit.LoggingPane` is loaded, then a
    pop-up :mochiref:`MochiKit.LoggingPane.LoggingPane` will be
    used. Otherwise, it will be an alert with
    :mochiref:`Logger.prototype.getMessageText()`.

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Logger.prototype.dispatchListeners(msg)`:

    Dispatch a log message to all listeners.

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Logger.prototype.getMessages(howMany)`:

    Return a list of up to ``howMany`` messages from the message
    buffer.

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Logger.prototype.getMessageText(howMany)`:

    Get a string representing up to the last ``howMany`` messages in
    the message buffer. The default is ``30``.

    The message looks like this::

        LAST {messages.length} MESSAGES:
          [{msg.num}] {msg.level}: {m.info.join(' ')}
          [{msg.num}] {msg.level}: {m.info.join(' ')}
          ...

    If you want some other format, use
    :mochiref:`Logger.prototype.getMessages` and do it yourself.

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`Logger.prototype.removeListener(ident)`:

    Remove a listener using the ident given to
    :mochiref:`Logger.prototype.addListener`

    *Availability*:
        Available in MochiKit 1.3.1+


Functions
---------

:mochidef:`alertListener(msg)`:

    Ultra-obnoxious ``alert(...)`` listener

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`log(message[, info[, ...]])`:

    Log an INFO message to the default logger

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`logDebug(message[, info[, ...]])`:

    Log a DEBUG message to the default logger

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`logError(message[, info[, ...]])`:

    Log an ERROR message to the default logger

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`logFatal(message[, info[, ...]])`:

    Log a FATAL message to the default logger

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`logLevelAtLeast(minLevel)`:

    Return a function that will match log messages whose level is at
    least minLevel

    *Availability*:
        Available in MochiKit 1.3.1+


:mochidef:`logWarning(message[, info[, ...]])`:

    Log a WARNING message to the default logger

    *Availability*:
        Available in MochiKit 1.3.1+


See Also
========

.. [1] Python's logging module: http://docs.python.org/lib/module-logging.html
.. [2] PEP 282, where they admit all of the Java influence: http://www.python.org/peps/pep-0282.html
.. [3] Original Bookmarklet Based Debugging blather: http://bob.pythonmac.org/archives/2005/07/03/bookmarklet-based-debugging/


Authors
=======

- Bob Ippolito <bob@redivi.com>


Copyright
=========

Copyright 2005 Bob Ippolito <bob@redivi.com>. This program is
dual-licensed free software; you can redistribute it and/or modify it
under the terms of the `MIT License`_ or the `Academic Free License
v2.1`_.

.. _`MIT License`: http://www.opensource.org/licenses/mit-license.php
.. _`Academic Free License v2.1`: http://www.opensource.org/licenses/afl-2.1.php
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