mochikit_v14/doc/rst/MochiKit/Async.rst

   1 .. title:: MochiKit.Async - manage asynchronous tasks
   2
   3 Name
   4 ====
   5
   6 MochiKit.Async - manage asynchronous tasks
   7
   8
   9 Synopsis
  10 ========
  11
  12 ::
  13
  14     var url = "/src/b/bo/bob/MochiKit.Async/META.json";
  15     /*
  16
  17         META.json looks something like this:
  18
  19         {"name": "MochiKit", "version": "0.5"}
  20
  21     */
  22     var d = loadJSONDoc(url);
  23     var gotMetadata = function (meta) {
  24         if (MochiKit.Async.VERSION == meta.version) {
  25             alert("You have the newest MochiKit.Async!");
  26         } else {
  27             alert("MochiKit.Async "
  28                 + meta.version
  29                 + " is available, upgrade!");
  30         }
  31     };
  32     var metadataFetchFailed = function (err) {
  33       alert("The metadata for MochiKit.Async could not be fetched :(");
  34     };
  35     d.addCallbacks(gotMetadata, metadataFetchFailed);
  36
  37
  38 Description
  39 ===========
  40
  41 MochiKit.Async provides facilities to manage asynchronous (as in AJAX
  42 [1]_) tasks. The model for asynchronous computation used in this
  43 module is heavily inspired by Twisted [2]_.
  44
  45
  46 Dependencies
  47 ============
  48
  49 - :mochiref:`MochiKit.Base`
  50
  51
  52 Overview
  53 ========
  54
  55 Deferred
  56 --------
  57
  58 The Deferred constructor encapsulates a single value that is not
  59 available yet. The most important example of this in the context of a
  60 web browser would be an ``XMLHttpRequest`` to a server. The importance
  61 of the Deferred is that it allows a consistent API to be exposed for
  62 all asynchronous computations that occur exactly once.
  63
  64 The producer of the Deferred is responsible for doing all of the
  65 complicated work behind the scenes. This often means waiting for a
  66 timer to fire, or waiting for an event (e.g. ``onreadystatechange`` of
  67 ``XMLHttpRequest``).  It could also be coordinating several events
  68 (e.g.  ``XMLHttpRequest`` with a timeout, or several Deferreds
  69 (e.g. fetching a set of XML documents that should be processed at the
  70 same time).
  71
  72 Since these sorts of tasks do not respond immediately, the producer of
  73 the Deferred does the following steps before returning to the
  74 consumer:
  75
  76 1. Create a ``new`` :mochiref:`Deferred();` object and keep a
  77    reference to it, because it will be needed later when the value is
  78    ready.
  79 2. Setup the conditions to create the value requested (e.g.  create a
  80    new ``XMLHttpRequest``, set its ``onreadystatechange``).
  81 3. Return the :mochiref:`Deferred` object.
  82
  83 Since the value is not yet ready, the consumer attaches a function to
  84 the Deferred that will be called when the value is ready. This is not
  85 unlike ``setTimeout``, or other similar facilities you may already be
  86 familiar with.  The consumer can also attach an "errback" to the
  87 :mochiref:`Deferred`, which is a callback for error handling.
  88
  89 When the value is ready, the producer simply calls
  90 ``myDeferred.callback(theValue)``. If an error occurred, it should
  91 call ``myDeferred.errback(theValue)`` instead.  As soon as this
  92 happens, the callback that the consumer attached to the
  93 :mochiref:`Deferred` is called with ``theValue`` as the only argument.
  94
  95 There are quite a few additional "advanced" features baked into
  96 :mochiref:`Deferred`, such as cancellation and callback chains, so
  97 take a look at the API reference if you would like to know more!
  98
  99 API Reference
 100 =============
 101
 102 Errors
 103 ------
 104
 105 :mochidef:`AlreadyCalledError`:
 106
 107     Thrown by a :mochiref:`Deferred` if ``.callback`` or ``.errback``
 108     are called more than once.
 109
 110     *Availability*:
 111         Available in MochiKit 1.3.1+
 112
 113
 114 :mochidef:`BrowserComplianceError`:
 115
 116     Thrown when the JavaScript runtime is not capable of performing
 117     the given function. Currently, this happens if the browser does
 118     not support ``XMLHttpRequest``.
 119
 120     *Availability*:
 121         Available in MochiKit 1.3.1+
 122
 123
 124 :mochidef:`CancelledError`:
 125
 126     Thrown by a :mochiref:`Deferred` when it is cancelled, unless a
 127     canceller is present and throws something else.
 128
 129     *Availability*:
 130         Available in MochiKit 1.3.1+
 131
 132
 133 :mochidef:`GenericError`:
 134
 135     Results passed to ``.fail`` or ``.errback`` of a
 136     :mochiref:`Deferred` are wrapped by this ``Error`` if ``!(result
 137     instanceof Error)``.
 138
 139     *Availability*:
 140         Available in MochiKit 1.3.1+
 141
 142
 143 :mochidef:`XMLHttpRequestError`:
 144
 145     Thrown when an ``XMLHttpRequest`` does not complete successfully
 146     for any reason. The ``req`` property of the error is the failed
 147     ``XMLHttpRequest`` object, and for convenience the ``number``
 148     property corresponds to ``req.status``.
 149
 150     *Availability*:
 151         Available in MochiKit 1.3.1+
 152
 153
 154 Constructors
 155 ------------
 156
 157 :mochidef:`Deferred()`:
 158
 159     Encapsulates a sequence of callbacks in response to a value that
 160     may not yet be available. This is modeled after the Deferred class
 161     from Twisted [3]_.
 162
 163 .. _`Twisted`: http://twistedmatrix.com/
 164
 165     Why do we want this?  JavaScript has no threads, and even if it
 166     did, threads are hard. Deferreds are a way of abstracting
 167     non-blocking events, such as the final response to an
 168     ``XMLHttpRequest``.
 169
 170     The sequence of callbacks is internally represented as a list of
 171     2-tuples containing the callback/errback pair. For example, the
 172     following call sequence::
 173
 174         var d = new Deferred();
 175         d.addCallback(myCallback);
 176         d.addErrback(myErrback);
 177         d.addBoth(myBoth);
 178         d.addCallbacks(myCallback, myErrback);
 179
 180     is translated into a :mochiref:`Deferred` with the following
 181     internal representation::
 182
 183         [
 184             [myCallback, null],
 185             [null, myErrback],
 186             [myBoth, myBoth],
 187             [myCallback, myErrback]
 188         ]
 189
 190     The :mochiref:`Deferred` also keeps track of its current status
 191     (fired).  Its status may be one of the following three values:
 192
 193
 194         ===== ================================
 195         Value Condition
 196         ===== ================================
 197         -1    no value yet (initial condition)
 198         0     success
 199         1     error
 200         ===== ================================
 201
 202     A :mochiref:`Deferred` will be in the error state if one of the
 203     following conditions are met:
 204
 205     1. The result given to callback or errback is "``instanceof
 206        Error``"
 207     2. The callback or errback threw while executing. If the thrown
 208        object is not ``instanceof Error``, it will be wrapped with
 209        :mochiref:`GenericError`.
 210
 211     Otherwise, the :mochiref:`Deferred` will be in the success
 212     state. The state of the :mochiref:`Deferred` determines the next
 213     element in the callback sequence to run.
 214
 215     When a callback or errback occurs with the example deferred chain,
 216     something equivalent to the following will happen (imagine that
 217     exceptions are caught and returned as-is)::
 218
 219         // d.callback(result) or d.errback(result)
 220         if (!(result instanceof Error)) {
 221             result = myCallback(result);
 222         }
 223         if (result instanceof Error) {
 224             result = myErrback(result);
 225         }
 226         result = myBoth(result);
 227         if (result instanceof Error) {
 228             result = myErrback(result);
 229         } else {
 230             result = myCallback(result);
 231         }
 232
 233     The result is then stored away in case another step is added to
 234     the callback sequence. Since the :mochiref:`Deferred` already has
 235     a value available, any new callbacks added will be called
 236     immediately.
 237
 238     There are two other "advanced" details about this implementation
 239     that are useful:
 240
 241     Callbacks are allowed to return :mochiref:`Deferred` instances, so
 242     you can build complicated sequences of events with (relative)
 243     ease.
 244
 245     The creator of the :mochiref:`Deferred` may specify a
 246     canceller. The canceller is a function that will be called if
 247     :mochiref:`Deferred.prototype.cancel` is called before the
 248     :mochiref:`Deferred` fires. You can use this to allow an
 249     ``XMLHttpRequest`` to be cleanly cancelled, for example. Note that
 250     cancel will fire the :mochiref:`Deferred` with a
 251     :mochiref:`CancelledError` (unless your canceller throws or
 252     returns a different ``Error``), so errbacks should be prepared to
 253     handle that ``Error`` gracefully for cancellable
 254     :mochiref:`Deferred` instances.
 255
 256     *Availability*:
 257         Available in MochiKit 1.3.1+
 258
 259
 260 :mochidef:`Deferred.prototype.addBoth(func)`:
 261
 262     Add the same function as both a callback and an errback as the
 263     next element on the callback sequence. This is useful for code
 264     that you want to guarantee to run, e.g. a finalizer.
 265
 266     If additional arguments are given, then ``func`` will be replaced
 267     with :mochiref:`MochiKit.Base.partial.apply(null,
 268     arguments)`. This differs from `Twisted`_, because the result of
 269     the callback or errback will be the *last* argument passed to
 270     ``func``.
 271
 272     If ``func`` returns a :mochiref:`Deferred`, then it will be
 273     chained (its value or error will be passed to the next
 274     callback). Note that once the returned ``Deferred`` is chained, it
 275     can no longer accept new callbacks.
 276
 277     *Availability*:
 278         Available in MochiKit 1.3.1+
 279
 280
 281 :mochidef:`Deferred.prototype.addCallback(func[, ...])`:
 282
 283     Add a single callback to the end of the callback sequence.
 284
 285     If additional arguments are given, then ``func`` will be replaced
 286     with :mochiref:`MochiKit.Base.partial.apply(null,
 287     arguments)`. This differs from `Twisted`_, because the result of
 288     the callback will be the *last* argument passed to ``func``.
 289
 290     If ``func`` returns a :mochiref:`Deferred`, then it will be
 291     chained (its value or error will be passed to the next
 292     callback). Note that once the returned ``Deferred`` is chained, it
 293     can no longer accept new callbacks.
 294
 295     *Availability*:
 296         Available in MochiKit 1.3.1+
 297
 298
 299 :mochidef:`Deferred.prototype.addCallbacks(callback, errback)`:
 300
 301     Add separate callback and errback to the end of the callback
 302     sequence. Either callback or errback may be ``null``, but not
 303     both.
 304
 305     If ``callback`` or ``errback`` returns a :mochiref:`Deferred`,
 306     then it will be chained (its value or error will be passed to the
 307     next callback). Note that once the returned ``Deferred`` is
 308     chained, it can no longer accept new callbacks.
 309
 310     *Availability*:
 311         Available in MochiKit 1.3.1+
 312
 313
 314 :mochidef:`Deferred.prototype.addErrback(func)`:
 315
 316     Add a single errback to the end of the callback sequence.
 317
 318     If additional arguments are given, then ``func`` will be replaced
 319     with :mochiref:`MochiKit.Base.partial.apply(null,
 320     arguments)`. This differs from `Twisted`_, because the result of
 321     the errback will be the *last* argument passed to ``func``.
 322
 323     If ``func`` returns a :mochiref:`Deferred`, then it will be
 324     chained (its value or error will be passed to the next
 325     callback). Note that once the returned ``Deferred`` is chained, it
 326     can no longer accept new callbacks.
 327
 328     *Availability*:
 329         Available in MochiKit 1.3.1+
 330
 331
 332 :mochidef:`Deferred.prototype.callback([result])`:
 333
 334     Begin the callback sequence with a non-``Error`` result. Result
 335     may be any value except for a :mochiref:`Deferred`.
 336
 337     Either ``.callback`` or ``.errback`` should be called exactly once
 338     on a :mochiref:`Deferred`.
 339
 340     *Availability*:
 341         Available in MochiKit 1.3.1+
 342
 343
 344 :mochidef:`Deferred.prototype.cancel()`:
 345
 346     Cancels a :mochiref:`Deferred` that has not yet received a value,
 347     or is waiting on another :mochiref:`Deferred` as its value.
 348
 349     If a canceller is defined, the canceller is called.  If the
 350     canceller did not return an ``Error``, or there was no canceller,
 351     then the errback chain is started with :mochiref:`CancelledError`.
 352
 353     *Availability*:
 354         Available in MochiKit 1.3.1+
 355
 356
 357 :mochidef:`Deferred.prototype.errback([result])`:
 358
 359     Begin the callback sequence with an error result.  Result may be
 360     any value except for a :mochiref:`Deferred`, but if ``!(result
 361     instanceof Error)``, it will be wrapped with
 362     :mochiref:`GenericError`.
 363
 364     Either ``.callback`` or ``.errback`` should be called exactly once
 365     on a :mochidef:`Deferred`.
 366
 367     *Availability*:
 368         Available in MochiKit 1.3.1+
 369
 370
 371 :mochidef:`DeferredLock()`:
 372
 373     A lock for asynchronous systems.
 374
 375     The ``locked`` property of a :mochiref:`DeferredLock` will be
 376     ``true`` if it locked, ``false`` otherwise. Do not change this
 377     property.
 378
 379     *Availability*:
 380         Available in MochiKit 1.3.1+
 381
 382
 383 :mochidef:`DeferredLock.prototype.acquire()`:
 384
 385     Attempt to acquire the lock. Returns a :mochiref:`Deferred` that
 386     fires on lock acquisition with the :mochiref:`DeferredLock` as the
 387     value.  If the lock is locked, then the :mochiref:`Deferred` goes
 388     into a waiting list.
 389
 390     *Availability*:
 391         Available in MochiKit 1.3.1+
 392
 393
 394 :mochidef:`DeferredLock.prototype.release()`:
 395
 396     Release the lock. If there is a waiting list, then the first
 397     :mochiref:`Deferred` in that waiting list will be called back.
 398
 399     *Availability*:
 400         Available in MochiKit 1.3.1+
 401
 402
 403 :mochidef:`DeferredList(list, [fireOnOneCallback, fireOnOneErrback, consumeErrors, canceller])`:
 404
 405     Combine a list of :mochiref:`Deferred` into one. Track the
 406     callbacks and return a list of (success, result) tuples, 'success'
 407     being a boolean indicating whether result is a normal result or an
 408     error.
 409
 410     Once created, you have access to all :mochiref:`Deferred` methods,
 411     like addCallback, addErrback, addBoth. The behaviour can be
 412     changed by the following options:
 413
 414     ``fireOnOneCallback``:
 415         Flag for launching the callback once the first Deferred of the
 416         list has returned.
 417
 418     ``fireOnOneErrback``:
 419         Flag for calling the errback at the first error of a Deferred.
 420
 421     ``consumeErrors``:
 422         Flag indicating that any errors raised in the Deferreds should
 423         be consumed by the DeferredList.
 424
 425     Example::
 426
 427         // We need to fetch data from 2 different urls
 428         var d1 = loadJSONDoc(url1);
 429         var d2 = loadJSONDoc(url2);
 430         var l1 = new DeferredList([d1, d2], false, false, true);
 431         l1.addCallback(function (resultList) {
 432             MochiKit.Base.map(function (result) {
 433                 if (result[0]) {
 434                     alert("Data is here: " + result[1]);
 435                 } else {
 436                     alert("Got an error: " + result[1]);
 437                 }
 438             }, resultList);
 439         });
 440
 441     *Availability*:
 442         Available in MochiKit 1.3.1+
 443
 444
 445 Functions
 446 ---------
 447
 448 :mochidef:`callLater(seconds, func[, args...])`:
 449
 450     Call ``func(args...)`` after at least ``seconds`` seconds have
 451     elapsed.  This is a convenience method for::
 452
 453         func = partial.apply(extend(null, arguments, 1));
 454         return wait(seconds).addCallback(function (res) { return func() });
 455
 456     Returns a cancellable :mochiref:`Deferred`.
 457
 458     *Availability*:
 459         Available in MochiKit 1.3.1+
 460
 461
 462 :mochidef:`doXHR(url[, {option: value, ...}])`:
 463
 464     Perform a customized ``XMLHttpRequest`` and wrap it with a
 465     :mochiref:`Deferred` that may be cancelled.
 466
 467     Note that only ``200`` (OK), ``201`` (CREATED),
 468     ``204`` (NO CONTENT) and ``304`` (NOT MODIFIED) are considered
 469     success codes. All other status codes will
 470     result in an errback with an ``XMLHttpRequestError``.
 471
 472     ``url``:
 473         The URL for this request.
 474
 475     The following options are currently accepted:
 476
 477     ``method``:
 478         The HTTP method. Default is ``'GET'``.
 479
 480     ``sendContent``:
 481         The content to send (e.g. with POST). Default is no content.
 482
 483     ``queryString``:
 484         If present it will be used to build a query string to append to
 485         the url using :mochiref:`MochiKit.Base.queryString`. Default is
 486         no query string.
 487
 488     ``username``:
 489         The username for the request. Default is no username.
 490
 491     ``password``:
 492         The password for the request. Default is no password.
 493
 494     ``headers``:
 495         Additional headers to set in the request, either as an object
 496         such as ``{'Accept': 'text/xml'}`` or as an Array of 2-Arrays
 497         ``[['Accept', 'text/xml']]``. Default is no additional headers.
 498
 499     ``mimeType``:
 500         An override mime type. The typical use of this is to pass
 501         'text/xml' to force XMLHttpRequest to attempt to parse responseXML.
 502         Default is no override.
 503
 504     *returns*:
 505         :mochiref:`Deferred` that will callback with the
 506         ``XMLHttpRequest`` instance on success
 507
 508     *Availability*:
 509         Available in MochiKit 1.4+.
 510
 511
 512 :mochidef:`doSimpleXMLHttpRequest(url[, queryArguments...])`:
 513
 514     Perform a simple ``XMLHttpRequest`` and wrap it with a
 515     :mochiref:`Deferred` that may be cancelled.
 516
 517     Note that only ``200`` (OK), ``201`` (CREATED),
 518     ``204`` (NO CONTENT) and ``304`` (NOT MODIFIED) are considered
 519     success codes. All other status codes will
 520     result in an errback with an ``XMLHttpRequestError``.
 521
 522     ``url``:
 523         The URL to GET
 524
 525     ``queryArguments``:
 526         If this function is called with more than one argument, a
 527         ``"?"`` and the result of
 528         :mochiref:`MochiKit.Base.queryString` with the rest of the
 529         arguments are appended to the URL.
 530
 531         For example, this will do a GET request to the URL
 532         ``http://example.com?bar=baz``::
 533
 534             doSimpleXMLHttpRequest("http://example.com", {bar: "baz"});
 535
 536     *returns*:
 537         :mochiref:`Deferred` that will callback with the
 538         ``XMLHttpRequest`` instance on success
 539
 540     *Availability*:
 541         Available in MochiKit 1.3.1+. Support for 201 and 204 were added in
 542         MochiKit 1.4.
 543
 544
 545 :mochidef:`evalJSONRequest(req)`:
 546
 547     Evaluate a JSON [4]_ ``XMLHttpRequest``
 548
 549     ``req``:
 550         The request whose ``.responseText`` property is to be
 551         evaluated
 552
 553     *returns*:
 554         A JavaScript object
 555
 556     *Availability*:
 557         Available in MochiKit 1.3.1+
 558
 559
 560 :mochidef:`fail([result])`:
 561
 562     Return a :mochiref:`Deferred` that has already had
 563     ``.errback(result)`` called.
 564
 565     See ``succeed`` documentation for rationale.
 566
 567     ``result``:
 568         The result to give to
 569         :mochiref:`Deferred.prototype.errback(result)`.
 570
 571     *returns*:
 572         A ``new`` :mochiref:`Deferred()`
 573
 574     *Availability*:
 575         Available in MochiKit 1.3.1+
 576
 577
 578 :mochidef:`gatherResults(deferreds)`:
 579
 580     A convenience function that returns a :mochiref:`DeferredList`
 581     from the given ``Array`` of :mochiref:`Deferred` instances that
 582     will callback with an ``Array`` of just results when they're
 583     available, or errback on the first array.
 584
 585     *Availability*:
 586         Available in MochiKit 1.3.1+
 587
 588
 589 :mochidef:`getXMLHttpRequest()`:
 590
 591     Return an ``XMLHttpRequest`` compliant object for the current
 592     platform.
 593
 594     In order of preference:
 595
 596     - ``new XMLHttpRequest()``
 597     - ``new ActiveXObject('Msxml2.XMLHTTP')``
 598     - ``new ActiveXObject('Microsoft.XMLHTTP')``
 599     - ``new ActiveXObject('Msxml2.XMLHTTP.4.0')``
 600
 601     *Availability*:
 602         Available in MochiKit 1.3.1+
 603
 604
 605 :mochidef:`maybeDeferred(func[, argument...])`:
 606
 607     Call a ``func`` with the given arguments and ensure the result is
 608     a :mochiref:`Deferred`.
 609
 610     ``func``:
 611         The function to call.
 612
 613     *returns*:
 614         A new :mochiref:`Deferred` based on the call to ``func``. If
 615         ``func`` does not naturally return a :mochiref:`Deferred`, its
 616         result or error value will be wrapped by one.
 617
 618     *Availability*:
 619         Available in MochiKit 1.3.1+
 620
 621
 622 :mochidef:`loadJSONDoc(url[, queryArguments...])`:
 623
 624     Do a simple ``XMLHttpRequest`` to a URL and get the response as a
 625     JSON [4]_ document.
 626
 627     ``url``:
 628         The URL to GET
 629
 630     ``queryArguments``:
 631         If this function is called with more than one argument, a
 632         ``"?"`` and the result of
 633         :mochiref:`MochiKit.Base.queryString` with the rest of the
 634         arguments are appended to the URL.
 635
 636         For example, this will do a GET request to the URL
 637         ``http://example.com?bar=baz``::
 638
 639             loadJSONDoc("http://example.com", {bar: "baz"});
 640
 641     *returns*:
 642         :mochiref:`Deferred` that will callback with the evaluated
 643         JSON [4]_ response upon successful ``XMLHttpRequest``
 644
 645     *Availability*:
 646         Available in MochiKit 1.3.1+
 647
 648
 649 :mochidef:`sendXMLHttpRequest(req[, sendContent])`:
 650
 651     Set an ``onreadystatechange`` handler on an ``XMLHttpRequest``
 652     object and send it off. Will return a cancellable
 653     :mochiref:`Deferred` that will callback on success.
 654
 655     Note that only ``200`` (OK), ``201`` (CREATED),
 656     ``204`` (NO CONTENT) and ``304`` (NOT MODIFIED) are considered
 657     success codes. All other status codes will
 658     result in an errback with an ``XMLHttpRequestError``.
 659
 660     ``req``:
 661         An preconfigured ``XMLHttpRequest`` object (open has been
 662         called).
 663
 664     ``sendContent``:
 665         Optional string or DOM content to send over the
 666         ``XMLHttpRequest``.
 667
 668     *returns*:
 669         :mochiref:`Deferred` that will callback with the
 670         ``XMLHttpRequest`` instance on success.
 671
 672     *Availability*:
 673         Available in MochiKit 1.3.1+. Support for 201 and 204 were added in
 674         MochiKit 1.4.
 675
 676
 677 :mochidef:`succeed([result])`:
 678
 679     Return a :mochiref:`Deferred` that has already had
 680     ``.callback(result)`` called.
 681
 682     This is useful when you're writing synchronous code to an
 683     asynchronous interface: i.e., some code is calling you expecting a
 684     :mochiref:`Deferred` result, but you don't actually need to do
 685     anything asynchronous. Just return ``succeed(theResult)``.
 686
 687     See ``fail`` for a version of this function that uses a failing
 688     :mochiref:`Deferred` rather than a successful one.
 689
 690     ``result``:
 691         The result to give to
 692         :mochiref:`Deferred.prototype.callback(result)`
 693
 694     *returns*:
 695         a ``new`` :mochiref:`Deferred`
 696
 697     *Availability*:
 698         Available in MochiKit 1.3.1+
 699
 700
 701 :mochidef:`wait(seconds[, res])`:
 702
 703     Return a new cancellable :mochiref:`Deferred` that will
 704     ``.callback(res)`` after at least ``seconds`` seconds have
 705     elapsed.
 706
 707     *Availability*:
 708         Available in MochiKit 1.3.1+
 709
 710
 711 See Also
 712 ========
 713
 714 .. [1] AJAX, Asynchronous JavaScript and XML: http://en.wikipedia.org/wiki/AJAX
 715 .. [2] Twisted, an event-driven networking framework written in Python: http://twistedmatrix.com/
 716 .. [3] Twisted Deferred Reference: http://twistedmatrix.com/projects/core/documentation/howto/defer.html
 717 .. [4] JSON, JavaScript Object Notation: http://json.org/
 718
 719
 720 Authors
 721 =======
 722
 723 - Bob Ippolito <bob@redivi.com>
 724
 725
 726 Copyright
 727 =========
 728
 729 Copyright 2005 Bob Ippolito <bob@redivi.com>. This program is
 730 dual-licensed free software; you can redistribute it and/or modify it
 731 under the terms of the `MIT License`_ or the `Academic Free License
 732 v2.1`_.
 733
 734 .. _`MIT License`: http://www.opensource.org/licenses/mit-license.php
 735 .. _`Academic Free License v2.1`: http://www.opensource.org/licenses/afl-2.1.php