Module type S.TERM

type 'a t

An 'a t is a term that produces a value of type 'a.

type description

Information about operations hidden behind a bind.

val active : Output.active -> 'a t

active x is a term indicating that the result is not determined yet.

val return : ?label:string -> 'a -> 'a t

return x is a term that immediately succeeds with x.

  • parameter label

    Label the constant in the diagrams.

val fail : string -> 'a t

fail m is a term that immediately fails with message m.

val state : ?hidden:bool -> 'a t -> ('a, [ `Active of Output.active | `Msg of string ]) Stdlib.result t

state t always immediately returns a successful result giving the current state of t.

  • parameter hidden

    If true, don't show a separate node for this on the diagrams.

val catch : ?hidden:bool -> 'a t -> 'a or_error t

catch t successfully returns Ok x if t evaluates successfully to x, or successfully returns Error e if t fails with error e. If t is active then catch t will be active too.

  • parameter hidden

    If true, don't show a separate node for this on the diagrams.

val ignore_value : 'a t -> unit t

ignore_value x is map ignore x.

val of_output : 'a Output.t -> 'a t

of_output x is a returned, failed or active term.

Sequencing terms

Applicative operations

val map : ?eq:('b -> 'b -> bool) -> ('a -> 'b) -> 'a t -> 'b t

map f x is a term that runs x and then transforms the result using f.

The optional equality function ?eq defaults to physical equality. When f produces an updated result following a change in x, the equality function will be called with the previous and the new value eq b_old b_new: returning true indicates that the change can be ignored and should not propagate further down the pipeline.

val map_error : (string -> string) -> 'a t -> 'a t

map_error f x is a term that runs x and then transforms the error string (if any) using f.

val pair : 'a t -> 'b t -> ('a * 'b) t

pair a b is the pair containing the results of evaluating a and b (in parallel).

val list_map : (module ORDERED with type t = 'a) -> ?collapse_key:string -> ?label:string -> ('a t -> 'b t) -> 'a list t -> 'b list t

list_map (module T) f xs adds f to the end of each input term and collects all the results into a single list.

  • parameter T

    Used to display labels for each item, and to avoid recreating pipelines unnecessarily.

  • parameter collapse_key

    If given, each element is wrapped with collapse.

  • parameter label

    Label the list in the diagrams.

val list_iter : (module ORDERED with type t = 'a) -> ?collapse_key:string -> ?label:string -> ('a t -> unit t) -> 'a list t -> unit t

Like list_map but for the simpler case when the result is unit.

  • parameter label

    Label the list in the diagrams.

val list_seq : 'a t list -> 'a list t

list_seq x evaluates to a list containing the results of evaluating each element in x, once all elements of x have successfully completed.

val option_map : ?label:string -> ('a t -> 'b t) -> 'a option t -> 'b option t

option_map f x is a term that evaluates to Some (f y) if x evaluates to Some y, or to None otherwise.

  • parameter label

    Label the optional in the diagrams.

val option_iter : ?label:string -> ('a t -> unit t) -> 'a option t -> unit t

Like option_map but for the simpler case when the result is unit.

  • parameter label

    Label the list in the diagrams.

val option_seq : 'a t option -> 'a option t

option_seq None is Current.return None and option_seq (Some x) is Current.map some x. This is useful for handling optional arguments that are currents.

val all : unit t list -> unit t

all xs is a term that succeeds if every term in xs succeeds.

val all_labelled : (string * unit t) list -> unit t

all xs is a term that succeeds if every term in xs succeeds. The labels are used if some terms fail, to indicate which ones are failing.

val gate : on:unit t -> 'a t -> 'a t

gate ~on:ctrl x is the same as x, once ctrl succeeds.

Note: gate does not delay x; it only delays whatever you put after the gate. e.g.

let binary = build src in
let tests_ok = test binary in
binary |> gate ~on:tests_ok |> deploy
val cutoff : eq:('a -> 'a -> bool) -> 'a t -> 'a t

cutoff ~eq x is the same as x, but changes to x that are equal according to eq do not propagate further down. It should be used when values of type 'a have a precise definition of equality to avoid triggering redundant work.

Diagram control

val collapse : key:string -> value:string -> input:_ t -> 'a t -> 'a t

collapse ~key ~value ~input t is a term that behaves just like t, but when shown in a diagram it can be expanded or collapsed. When collapsed, it is shown as "input -> +" and the user can expand it to show t instead. The idea is that input is a dependency of t and the "+" represents everything in t after that. key and value are used as the parameters (e.g. in a URL) to control whether this is expanded or not. For example collapse ~key:"repo" ~value:"mirage/mirage-www" ~input:repo (process repo) Note: list_map ~collapse_key provides an easy way to use this.

val collapse_list : key:string -> value:string -> input:_ t -> 'a t list -> 'a t list * unit t

collapse_list ~key ~value ~input t is a term that behaves just like t list, but when shown in a diagram it can be expanded or collapsed.

val with_context : _ t -> (unit -> 'a t) -> 'a t

with_context ctx f is the term f (), where f is evaluated in context ctx. This means that ctx will be treated as an input to all terms created by f in the diagrams.

Monadic operations

N.B. these operations create terms that cannot be statically analysed until after they are executed.

val bind : ?info:description -> ?eq:('b -> 'b -> bool) -> ('a -> 'b t) -> 'a t -> 'b t

bind f x is a term that first runs x to get y and then behaves as the term f y. Static analysis cannot look inside the f function until x is ready, so using bind makes static analysis less useful. You can use the info argument to provide some information here.

Primitives

type metadata

See ANALYSIS.

type 'a primitive
val primitive : info:description -> ('a -> 'b primitive) -> 'a t -> 'b t

primitive ~info f x is a term that evaluates f on each new value of x. This is used to provide the primitive operations, which can then be combined using the other combinators in this module. info is used to label the operation in the diagram.

val component : ('a, Stdlib.Format.formatter, unit, description) Stdlib.format4 -> 'a

component name is used to annotate binds, so that the system can show a name for the operations hidden inside the bind's function. name is used as the label for the bind in the generated dot diagrams. For convenience, name can also be a format string.

val observe : 'a t -> 'a Output.Blockable.t

observe x evaluates the current state of term x. A `Blocked value occurs when the term failed because an upstream dependency errored.

module Syntax : sig ... end