Up  

Module Fr


module Fr: sig .. end
Functional Reactive core functions

Data types


type +'a event
The type of events.

An event is a signal which occurs as discrete points in time.

type +'a behavior
The type of behaviors.

A behavior is a signal which occurs continuously throughout time.


Events



Basic events


val never : 'a event
never is an event which never occurs.
val now : unit event
now is an event which occurs exactly once, when a it is first instantiated (i.e. registered or switched to).

TODO: should this accept an argument? (we can currently achieve this with tag_e)


Event receivers


type -'a event_receiver
The type of event receivers.
val event_receiver : unit -> 'a event_receiver * 'a event
Create a new event receiver.
val send_event : 'a event_receiver -> 'a -> unit
Send a value to an event receiver.

Event functions


val tag_e : 'a -> 'b event -> 'a event
tag_e v a replaces the value of the event a with v.
val map_e : ('a -> 'b) -> 'a event -> 'b event
map_e f e transforms the value of the event a with f.

(on e -> f) is syntactic sugar for map_e f e, and (on e a ... -> ...) is syntactic sugar for map_e (fun a ... -> ...) e.

val filter_e : ('a -> bool) -> 'a event -> 'a event
filter_e f e passes all occurrences of e for which f returns true.
val may_e : 'a option event -> 'a event
may_e e occurs whenever e is Some v, and has the value v.
val zip_e : 'a event -> 'b event -> ('a * 'b) event
zip_e a b occurs whenever both a and b occur, and has the value of a paired with b.

TODO: should this accept a tuple instead of two arguments?

val unzip_e : ('a * 'b) event -> 'a event * 'b event
unzip_e e produces two events synchronous with e whose values are the first and second halves of the value of e.
val merge_e : 'a event list -> 'a event
merge_e l occurs when any event in l occurs, with the value of that event. If more than one event occurs at the same time, the leftmost event takes precedence.

TODO: should this also accept a function used to resolve collisions? (we can currently acheive this with par_e and List.fold_left)

val par_e : 'a event list -> 'a list event
par_e l occurs when at least one event in l occurs, with the value of all occuring events joined in a list. List order is preserved.
val once_e : 'a event -> 'a event
once_e e passes only the first occurrence of e.
val snapshot_e : 'a event -> 'b event -> 'a option event
snapshot_e e trigger occurs whenever event trigger occurs. If event e occurs simultaneously, its value is used, otherwise the event occurs with the value None.

Accumulators


val accum_e : 'a -> ('a -> 'a) event -> 'a event
accum_e i e creates a event with memory which occurs whenever its internal state changes. e is an event which carries a function which is used to update the internal state each time it occurs. The initial value of the state is given by i.
val collect_e : ('a -> 'b -> 'a) -> 'a -> 'b event -> 'a event
collect_e f i e is similar to accum_e but passes the value of the event e to the function f in order to update the internal state.

Converters


val changes : 'a behavior -> 'a event
changes b occurs whenever b changes, and has the new value of b. Equality is determined with ( =* ).
val changesq : 'a behavior -> 'a event
changesq b is similar to changes b but detects changes using physical equality.
val delta : ('a -> 'a -> 'b) -> 'a behavior -> 'b event
delta f b is similar to changesq b but the value of the event it creates is determined by applying f to the old and new values, respectively, of b. For example, delta first b emits the value b had just before it changed.
val when_e : bool behavior -> unit event
when_e b occurs whenever b becomes true.

TODO: should this be renamed when?

val edge_e : 'a option behavior -> 'a event
edge_e b occurs whenever b transitions from None to Some v, and has the value v.

TODO: should this be renamed edge?


Higher-order signals


val switch_e : 'a event -> 'a event event -> 'a event
switch_e i e is an event isomorphic to the last occurrence of e (or i, if e has not yet occurred).
val map_wait_e : ('a -> 'b event) -> 'a event -> 'b event
map_wait_e f e is a convenience function similar to map in that it creates an event by applying the function f to the event e whenever e occurs. However, it does not occur until the event returned by f first occurs. It is identical to the Fr_mt expression async_map_e (fun v -> wait (f v)) e but does not require threading to be enabled.
val collapse_e : 'a event behavior -> 'a event
collapse_e b is an event isomorphic to the current value of b.
val fix_e : ('a -> 'b event) -> ('b event -> 'a) -> 'a
fix_e g f allows f to reference an event before it is defined: the result of applying f to this "phantom" event is passed to g, whose output is used to "fill in" the phantom event. fix_e returns the output of f.

TODO: this should have some syntactic sugar associated with it


Behaviors



Cells


type -'a cell
The type of cells.
val new_cell : 'a -> 'a cell * 'a behavior
Create a new cell with the given initial value.
val set_cell : 'a cell -> 'a -> unit
Set the value of a cell.

Basic functions


val snapshot_b : 'a behavior -> 'b event -> 'a event
snapshot b e is an event which occurs with the value of b when the event e occurs.
val latch : 'a behavior -> 'b event -> 'a event
latch b e is similar to snapshot b e but carries the value b had just before e occured.
val hold : 'a -> 'a event -> 'a behavior
hold i e is a behavior equal to the last occurrence of e (or i, if e has not yet occurred).
val gate_b : 'a behavior -> 'b event -> 'a behavior
gate b e is a behavior which follows b, but changes only when the event e occurs.
val track : 'a -> 'a option behavior -> 'a behavior
track i b is a behavior which follows b whenever it is not None.
val zip_b : 'a behavior -> 'b behavior -> ('a * 'b) behavior
zip_b a b is a behavior with the value of a paired with b.
val unzip_b : ('a * 'b) behavior -> 'a behavior * 'b behavior
unzip_b b produces two behaviors whose values are the first and second halves of the value of b.
val par_b : 'a behavior list -> 'a list behavior
par_b l is a behavior whose value is a list of the values of all behaviors in the list l. List order is preserved.
val accum_b : 'a -> ('a -> 'a) event -> 'a behavior
accum_b is identical to accum_e but produces a behavior rather than an event.
val collect_b : ('a -> 'b -> 'a) -> 'a -> 'b event -> 'a behavior
collect_b is identical to collect_e but produces a behavior rather than an event.

Higher-order signals


val switch_b : 'a behavior -> 'a behavior event -> 'a behavior
switch_b i e is a behavior isomorphic to the last occurrence of e (or i, if e has not yet occurred).
val sswitch_b : ('a -> 'b) ->
       ('b -> 'a behavior) ->
       'b -> ('b -> 'a behavior) event -> 'a behavior
sswitch_b g f i e is similar to switch_b but allows state to be maintained across switches. g is a function which extracts the current state of a behavior from its value. e is an event which carries a function which produces a behavior when given an initial state. f applied to i determines the initial behavior.

Note that the state of g must be fully observable from its output value for sswitch_b to work as expected.

val collapse_b : 'a behavior behavior -> 'a behavior
collapse_b b is a behavior isomorphic to the current value of b.
val scollapse_b : ('a -> 'b) -> 'b -> ('b -> 'a behavior) behavior -> 'a behavior
scollapse_b g i e is similar to collapse_b but allows state to be maintained across switches. g is a function which extracts the current state of a behavior from its value. b is an event which carries a function which produces a behavior when given an initial state. The initial value of b applied to i determines the initial behavior.

Note that the state of g must be fully observable from its output value for scollapse_b to work as expected.

val fix_b : ('a -> 'b behavior) -> ('b behavior -> 'a) -> 'a
fix_b is identical to fix_e but works with a behavior.

Lifting


val lift0 : 'a -> 'a behavior
lift0 a is a behavior which is always equal to a.
val lift1 : ('a -> 'b) -> 'a behavior -> 'b behavior
lift1 f returns a function which, when applied to a behavior, returns a behavior which is always equal to f applied to the current value of the behavior.
val lift2 : ('a -> 'b -> 'c) -> 'a behavior -> 'b behavior -> 'c behavior
val lift3 : ('a -> 'b -> 'c -> 'd) ->
       'a behavior -> 'b behavior -> 'c behavior -> 'd behavior
val lift1q : ('a -> 'b) -> 'a behavior -> 'b behavior
val lift2q : ('a -> 'b -> 'c) -> 'a behavior -> 'b behavior -> 'c behavior
val lift3q : ('a -> 'b -> 'c -> 'd) ->
       'a behavior -> 'b behavior -> 'c behavior -> 'd behavior

Endpoints


type endpoint
The type of a endpoint.
val register_e : 'a event -> endpoint
register_e e marks the event e as an endpoint.

register_b b marks the behavior b as an endpoint.

val register_b : 'a behavior -> endpoint
unregister h destroys the endpoint h. It is guaranteed not to be evaluated again.
val unregister : endpoint -> unit

Lazy signal sources


val event_source : ('a event_receiver -> 'b) -> ('b -> unit) -> 'a event
event_source start stop creates an event. When the event becomes referenced in a signal path, the function start is called with the event's receiver as an argument. start is expected to start a thread or co-routine which uses the provided receiver to generate events. When the event is no longer referenced in any signal path, the stop function is called with the value returned by start as an argument. stop may then terminate the thread or co-routine started by start.

TODO: should event_source have a "force" function like behavior_source to determine if an event is occurring *right now*? (i.e. for switchers)

val behavior_source : (unit -> 'a) -> ('a cell -> 'b) -> ('b -> unit) -> 'a behavior
behavior_source force start stop creates a behavior. Like event_source, start and stop are called when the behavior is first referenced and last unreferenced, respectively. Additionally, the force function is called when the behavior is first referenced. The value it returns is used as the value of the behavior until it is explicitly set to some value.

Useful functions


val id : 'a -> 'a
val dup : 'a -> 'a * 'a
val some : 'a -> 'a option
val curry2 : ('a * 'b -> 'c) -> 'a -> 'b -> 'c
val uncurry2 : ('a -> 'b -> 'c) -> 'a * 'b -> 'c
val curry3 : (('a * 'b) * 'c -> 'd) -> 'a -> 'b -> 'c -> 'd
val uncurry3 : ('a -> 'b -> 'c -> 'd) -> ('a * 'b) * 'c -> 'd
val ($) : ('a -> 'b) -> ('c -> 'a) -> 'c -> 'b
val first : 'a -> 'b -> 'a
val second : 'a -> 'b -> 'b
val (=*) : 'a -> 'a -> bool
Compare two objects structurally with (=), falling back to physical equality with (==) if this is not possible.
val (<>*) : 'a -> 'a -> bool
The negation of =*.

Mixed-mode signals (experimental)


module Mixed: sig .. end
type 'a mixed = 'a Mixed.t