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 viaarrowlet.run
.ProgressA
arrowlets are sources of events, and can be composed withEventA
to detect progress of the associated arrowlet instances:
Asynchronous arrowlets such asprogressA.next(EventA(eventname)).next(eventhandler)
DelayA
will signal a"progress"
event when executed, whileSignalA
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
orwindow
- el itself
- otherwise
- throws a TypeError exception
- Signal: none
SignalA([eventname])
- Signals an event to the
ProgressA
arrow. Theevent.type
is eventname andevent.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
orwindow
. - 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 formfunction
(). This allows the operation to be cancelled via theProgressA
arrowlet. a.signal(event [, detail])
- Use this method to send events to
ProgressA
observers. If event is a string, it will be converted into aProgressA.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 calla.signal("progress")
to notifyProgressA
observers.