note 0.0.3 · OCaml Package

Events.

An event is a value with discrete occurrences over time. Consult the semantics and notations of events.

Events

type 'a t = 'a event

The type for events with occurrences of type 'a.

type 'a send = ?step:Step.t -> 'a -> unit

The type for functions sending event occurrences of type 'a. See create.

val obs : 'a t -> 'a option Logr.obs

obs e is an observation for e's occurrences.

val log : ?now:bool -> 'a event -> ('a -> unit) -> Logr.t option

log ?now e f is Some (Logr.(create ?now (const f $ obs e))) if e is not never and None otherwise.

val create : unit -> 'a event * 'a send

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 .
send ~step v generates an occurrence v of e at the time step. The function should not be called again before step is executed.

Warning. send must not be used in the definition of signals or events.

val value : 'a event -> 'a option

value e is the value of event e at call time. If this is None the event has no occurrence, if this is Some v, the event occurs with v.

val never : 'a event

never is a never occuring event, [never]_t = None.

val bind : 'a event -> ('a -> 'b event) -> 'b event

bind e f is the event that results from applying f to the last event of e:

[bind e f]_t = [f v]_t if [e]_≤t = Some v.
[bind e f]_t = never_t if [e]_≤t = None.

val join : 'a event event -> 'a event

join ee is bind ee (fun e -> e).

val swap : 'a event signal -> 'a event

swap es is the current event of es, [swap es]_t = [[es]_t]_t.

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 stamp : 'b event -> 'a -> 'a event

stamp e v is map e (fun _ -> v)

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

filter p e are the occurrences of e 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 filter_map : ('a -> 'b option) -> 'a event -> 'b event

filter_map fm e are e's occurrences filtered and mapped by fm.

[filter_map fm e]_t = Some v if fm [e]_t = Some v
[filter_map fm e]_t = None otherwise.

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

select el is the occurrences of every event in el. If more than one event occurs simlutanously, the leftmost is taken and the other are lost:

[select el]_t = [List.find (fun e -> [e]_t <> None) el]_t.
[select el]_t = None otherwise.

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

accum i e accumulates a value, starting with i, using e's functional occurrences.

[accum i e]_t = Some (f i) if [e]_t = Some f and [e]_<t = None.
[accum i e]_t = Some (f acc) if [e]_t = Some f and [accum i e]_<t = Some acc.
[accum i e] = None otherwise.

val until : ?limit:bool -> next:'a event -> 'b event -> 'b event

until ~limit ~next e is e's occurrences until next occurs. At that point if e occurs simultaneously the occurrence is discarded (limit is false, default) or kept (limit is true) and after this the event never occurs again.

[until ~limit ~next e]_t = [e]_t if [next]_≤t = None
[until ~limit:false ~next e]_t = None if [next]_t = Some _ and [next]_<t = None.
[until ~limit:true ~next e]_t = [e]_t if [next]_t = Some _ and [next]_<t = None.
[until ~limit ~next e]_t = None otherwise.

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

follow e ~on is e's occurrences whenever on is true.

[follow e ~on]_t = [e]_t if [on]_t = true
[follow e ~on]_t = None if [on]_t = false

val defer : 'a event -> 'a event

defer s is s delayed by an infinitesimal amount of time. At creation time init is used (defaults to S.value s).

[defer e]_t = None for t = 0.
[defer e]_t = [e]_t-dt otherwise.

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).

Stdlib types support

module Option : sig ... end

Option events

module Pair : sig ... end

Pair events.

package note

Events

Stdlib types support