Narrative JavaScript

Coding: The Yielding Operator

Narrative JavaScript looks exactly like regular JavaScript except for the addition of a yielding operator. The yielding operator is denoted by

    ->

and is placed immediately prior to the parenthesis of a method call. It's presence indicates that the function block until an event has fired with return value. For example:

    function doSomething() {
        var r1 = doAsynch->();            // correct
        var r2 = myObject.doAsynch->(r1); // correct

        myObject->doAsynch();  // incorrect, parse error
    }

Yielding method calls may be nested and may be placed within while or for loops:

    function doSomething() {
        for (var i = 0; i < 10; i++) {
            doNested->(i);
        }
    }

    function doNested(i) {
        return doAsynch->(i);
    }

Yielding within with() blocks is not yet supported.

Coding: Notifiers

In order to integrate smoothly with callback-based JavaScript APIs, Narrative JavaScript provides notifier callbacks. A notifier is an event handler that resumes yielded functions when an event is received. Notifiers may be used as callback event handlers for any JavaScript event API.

For example, you can use a notifier to wait for a button click:

    function waitForButton() {
        // do some work
        
        // create our notifier
        var notifier = new EventNotifier();
        
        // attach our notifier to the button
        document.getElementById("myButton").onclick = notifier;
        
        // wait for the button to be clicked
        notifier.wait->();
        
        // do more work
    }

As stated above, notifiers can be used for any JavaScript event, including DOM events and XmlHttp onReadyStateChange events.

There are other types of notifier objects as well, such as the ResultNotifier (for use as promises and futures) and the QueueNotifier (for mailboxes).

Notifiers can also be chained to yield a value. In other words, if the result of a notifier is in turn another notifier, the result of this other notifier will be retrieved automatically.

Notifiers are discussed in greater detail in the upcoming example and in the API reference.