# Module `React.E`

Event combinators.

Consult their semantics.

## Primitive and basics

`type 'a t`

`= 'a event`

The type for events with occurrences of type

`'a`

.

`val never : 'a event`

A never occuring event. For all t, [

`never`

]_{t}`= None`

.

`val create : unit -> 'a event * (?step:step -> 'a -> unit)`

`create ()`

is a primitive event`e`

and a`send`

function. The function`send`

is such that:`send v`

generates an occurrence`v`

of`e`

at the time it is called and triggers an update step.`send ~step v`

generates an occurence`v`

of`e`

on the step`step`

when`step`

is executed.`send ~step v`

raises`Invalid_argument`

if it was previously called with a step and this step has not executed yet or if the given`step`

was already executed.

**Warning.**`send`

must not be executed inside an update step.

`val retain : 'a event -> (unit -> unit) -> [ `R of unit -> unit ]`

`retain e c`

keeps a reference to the closure`c`

in`e`

and returns the previously retained value.`c`

will*never*be invoked.**Raises.**`Invalid_argument`

on`E.never`

.

`val stop : ?strong:bool -> 'a event -> unit`

`stop e`

stops`e`

from occuring. It conceptually becomes`never`

and cannot be restarted. Allows to disable effectful events.The

`strong`

argument should only be used on platforms where weak arrays have a strong semantics (i.e. JavaScript). See details.**Note.**If executed in an update step the event may still occur in the step.

## Transforming and filtering

`val once : 'a event -> 'a event`

`once e`

is`e`

with only its next occurence.- [
`once e`

]_{t}`= Some v`

if [`e`

]_{t}`= Some v`

and [`e`

]_{<t}`= None`

. - [
`once e`

]_{t}`= None`

otherwise.

- [

`val drop_once : 'a event -> 'a event`

`drop_once e`

is`e`

without its next occurrence.- [
`drop_once e`

]_{t}`= Some v`

if [`e`

]_{t}`= Some v`

and [`e`

]_{<t}`= Some _`

. - [
`drop_once e`

]_{t}`= None`

otherwise.

- [

`val app : ('a -> 'b) event -> 'a event -> 'b event`

`app ef e`

occurs when both`ef`

and`e`

occur simultaneously. The value is`ef`

's occurence applied to`e`

's one.- [
`app ef e`

]_{t}`= Some v'`

if [`ef`

]_{t}`= Some f`

and [`e`

]_{t}`= Some v`

and`f v = v'`

. - [
`app ef e`

]_{t}`= None`

otherwise.

- [

`val map : ('a -> 'b) -> 'a event -> 'b event`

`map f e`

applies`f`

to`e`

's occurrences.- [
`map f e`

]_{t}`= Some (f v)`

if [`e`

]_{t}`= Some v`

. - [
`map f e`

]_{t}`= None`

otherwise.

- [

`val filter : ('a -> bool) -> 'a event -> 'a event`

`filter p e`

are`e`

's occurrences that satisfy`p`

.- [
`filter p e`

]_{t}`= Some v`

if [`e`

]_{t}`= Some v`

and`p v = true`

- [
`filter p e`

]_{t}`= None`

otherwise.

- [

`val fmap : ('a -> 'b option) -> 'a event -> 'b event`

`fmap fm e`

are`e`

's occurrences filtered and mapped by`fm`

.- [
`fmap fm e`

]_{t}`= Some v`

if`fm`

[`e`

]_{t}`= Some v`

- [
`fmap fm e`

]_{t}`= None`

otherwise.

- [

`val diff : ('a -> 'a -> 'b) -> 'a event -> 'b event`

`diff f e`

occurs whenever`e`

occurs except on the next occurence. Occurences are`f v v'`

where`v`

is`e`

's current occurrence and`v'`

the previous one.- [
`diff f e`

]_{t}`= Some r`

if [`e`

]_{t}`= Some v`

, [`e`

]_{<t}`= Some v'`

and`f v v' = r`

. - [
`diff f e`

]_{t}`= None`

otherwise.

- [

`val changes : ?eq:('a -> 'a -> bool) -> 'a event -> 'a event`

`changes eq e`

is`e`

's occurrences with occurences equal to the previous one dropped. Equality is tested with`eq`

(defaults to structural equality).- [
`changes eq e`

]_{t}`= Some v`

if [`e`

]_{t}`= Some v`

and either [`e`

]_{<t}`= None`

or [`e`

]_{<t}`= Some v'`

and`eq v v' = false`

. - [
`changes eq e`

]_{t}`= None`

otherwise.

- [

`val on : bool signal -> 'a event -> 'a event`

`on c e`

is the occurrences of`e`

when`c`

is`true`

.- [
`on c e`

]_{t}`= Some v`

if [`c`

]_{t}`= true`

and [`e`

]_{t}`= Some v`

. - [
`on c e`

]_{t}`= None`

otherwise.

- [

## Accumulating

`val accum : ('a -> 'a) event -> 'a -> 'a event`

`accum ef i`

accumulates a value, starting with`i`

, using`e`

's functional occurrences.- [
`accum ef i`

]_{t}`= Some (f i)`

if [`ef`

]_{t}`= Some f`

and [`ef`

]_{<t}`= None`

. - [
`accum ef i`

]_{t}`= Some (f acc)`

if [`ef`

]_{t}`= Some f`

and [`accum ef i`

]_{<t}`= Some acc`

. - [
`accum ef i`

]`= None`

otherwise.

- [

`val fold : ('a -> 'b -> 'a) -> 'a -> 'b event -> 'a event`

`fold f i e`

accumulates`e`

's occurrences with`f`

starting with`i`

.- [
`fold f i e`

]_{t}`= Some (f i v)`

if [`e`

]_{t}`= Some v`

and [`e`

]_{<t}`= None`

. - [
`fold f i e`

]_{t}`= Some (f acc v)`

if [`e`

]_{t}`= Some v`

and [`fold f i e`

]_{<t}`= Some acc`

. - [
`fold f i e`

]_{t}`= None`

otherwise.

- [

## Combining

`val select : 'a event list -> 'a event`

`select el`

is the occurrences of every event in`el`

. If more than one event occurs simultaneously the leftmost is taken and the others are lost.- [
`select el`

]_{t}`=`

[`List.find (fun e ->`

[`e`

]_{t}`<> None) el`

]_{t}. - [
`select el`

]_{t}`= None`

otherwise.

- [

`val merge : ('a -> 'b -> 'a) -> 'a -> 'b event list -> 'a event`

`merge f a el`

merges the simultaneous occurrences of every event in`el`

using`f`

and the accumulator`a`

.[

`merge f a el`

]_{t}`= List.fold_left f a (List.filter (fun o -> o <> None) (List.map`

[]_{t}`el))`

.

`val switch : 'a event -> 'a event event -> 'a event`

`switch e ee`

is`e`

's occurrences until there is an occurrence`e'`

on`ee`

, the occurrences of`e'`

are then used until there is a new occurrence on`ee`

, etc..- [
`switch e ee`

]_{t}`=`

[`e`

]_{t}if [`ee`

]_{<=t}`= None`

. - [
`switch e ee`

]_{t}`=`

[`e'`

]_{t}if [`ee`

]_{<=t}`= Some e'`

.

- [

`val fix : ('a event -> 'a event * 'b) -> 'b`

`fix ef`

allows to refer to the value an event had an infinitesimal amount of time before.In

`fix ef`

,`ef`

is called with an event`e`

that represents the event returned by`ef`

delayed by an infinitesimal amount of time. If`e', r = ef e`

then`r`

is returned by`fix`

and`e`

is such that :- [
`e`

]_{t}`=`

`None`

if t = 0 - [
`e`

]_{t}`=`

[`e'`

]_{t-dt}otherwise

**Raises.**`Invalid_argument`

if`e'`

is directly a delayed event (i.e. an event given to a fixing function).- [

## Lifting

Lifting combinators. For a given `n`

the semantics is:

- [
`ln f e1 ... en`

]_{t}`= Some (f v1 ... vn)`

if for all i : [`ei`

]_{t}`= Some vi`

. - [
`ln f e1 ... en`

]_{t}`= None`

otherwise.

`val l1 : ('a -> 'b) -> 'a event -> 'b event`

`val l2 : ('a -> 'b -> 'c) -> 'a event -> 'b event -> 'c event`

`val l3 : ('a -> 'b -> 'c -> 'd) -> 'a event -> 'b event -> 'c event -> 'd event`

`val l4 : ('a -> 'b -> 'c -> 'd -> 'e) -> 'a event -> 'b event -> 'c event -> 'd event -> 'e event`

`val l5 : ('a -> 'b -> 'c -> 'd -> 'e -> 'f) -> 'a event -> 'b event -> 'c event -> 'd event -> 'e event -> 'f event`

`val l6 : ('a -> 'b -> 'c -> 'd -> 'e -> 'f -> 'g) -> 'a event -> 'b event -> 'c event -> 'd event -> 'e event -> 'f event -> 'g event`

## Stdlib support

`module Option : sig ... end`

Events with option occurences.