Arrowlets

API - Arrowlets

Arrowlets are modular units of behavior. All functions are also implicitly arrowlets, and may be used anywhere an arrowlet is required.

Arrowlets distinguishes between two types of function arrowlets: standard JavaScript functions, and tuple-aware functions. For standard JavaScript functions, if the input is a tuple, the function will be called with the flattened array representation of the tuple as arguments. Tuple-aware functions are just functions that take a single argument (which may be a tuple), and need to be explicitly converted into an arrowlet with the Arr constructor.

In the description below, Input/Output refers to the data received/returned by the arrowlets when used in a composition. Signals refer to events that are generated by arrowlets to track progress via ProgressA.

Arrowlets interface

var progressA = arrowlet.run(x)
Arrowlets may be run by calling arrowlet.run(x), where x is the input to the arrowlet.
Returns: progressA, a ProgressA arrowlet that may be used to track the progress of the running instance of arrowlet.
ProgressA
ProgressA arrowlets are associated with each running instance of arrowlets. They can only be created via arrowlet.run. ProgressA arrowlets are sources of events, and can be composed with EventA to detect progress of the associated arrowlet instances:
progressA.next(EventA(eventname)).next(eventhandler)
Asynchronous arrowlets such as DelayA will signal a "progress" event when executed, while SignalA may be used to signal a custom event.
Input: ignored
Output: the ProgressA arrowlet itself
Signal: none
Additional methods:
progressA.cancel()
Call this method to cancel the arrowlet associated with this ProgressA arrowlet.
ProgressA also conform to the EventTarget interface, much like regular HTML elements.

Arrowlets constructors

The following arrowlets constructors are currently available.

Arr(f)
Applies a tuple-aware function f to the input, which may be a tuple.
Input: anything
Output: the result of applying f to the input
Signal: none
Note that this differs from standard JavaScript functions which are applied to flattened tuples.
ConstA(constant)
Ignores its input, and returns a constant.
Input: ignored
Output: the value constant
Signal: none
ElementA(el)
Ignores its input, and returns an element in the document.
Input: ignored
Output:
if el is a string
the element #el in the document
if el is an element or document or window
el itself
otherwise
throws a TypeError exception
Signal: none
SignalA([eventname])
Signals an event to the ProgressA arrow. The event.type is eventname and event.detail the input to this arrow. The input will also be passed to the output.
Input: anything
Output: the input
Signal: eventname, or "signal" if undefined.
DelayA(delay)
Inserts a delay of length delay in milliseconds, passing the input to the output.
Input: anything
Output: the input
Signal: "progress" after the delay
EventA(eventname)
Waits for the event eventname to occur on an object.
Input: any object that supports the EventTarget interface, such an element in the document or document or window.
Output: the received event
Signal: "progress" when the event is received
HttpA(defaults)
Sends an asynchronous HTTP request for a network resource. Currently, only GET is support.
Input: a record describing the parameters for the request, with the following fields:
url
the URL to load
Output: a XMLHttpRequest object containing the result of the request
Signal: "progress" when the request succeeds

Low-level Arrowlets prototype constructors

AsyncA(f)
Custom arrowlets may be written using the AsyncA prototype constructor. This may be used to either construct the prototype of a new arrowlet constructor, or to wrap functions that need access to the arrowlet instance interface.
f should be a function of form function(x, a):
x
the input (from the previous arrowlet)
a
an AsyncA.Instance, which provides the low-level interface for arrowlets. f should call the following methods:
a.cont(y [, g [, h]])
This is the continuation function; call this method when f has completed, with y as the result. Up to two additional arrowlets g and h may added to the continuation stack as well to be run immediately after f.
a.addCanceller(canceller)
When f invokes an asynchronous operation (such as setTimeout), call this method to register canceller, a cancellation function of form function(). This allows the operation to be cancelled via the ProgressA arrowlet.
a.signal(event [, detail])
Use this method to send events to ProgressA observers. If event is a string, it will be converted into a ProgressA.Event object with properties:
{ type:event; detail:detail }
a.advance(canceller)
When f continues via an asynchronous operation (such as setTimeout), call this function to deregister canceller. This will also call a.signal("progress") to notify ProgressA observers.