package bonsai

Converts a Value.t to a Computation.t. Unlike most Computations, the Computation.t returned by read can be used in multiple locations without maintaining multiple copies of any models or building duplicate incremental graphs.

read is most commonly used in the final expression of a let%sub chain, like so:

fun i ->
  let%sub a = f i in
  let%sub b = g i in
  read
    (let%map a = a
     and b = b in
     a + b)

or to use some APIs that require Computation.t like so:

val cond : bool Value.t
val x : 'a Value.t
val some_computation : 'a Computation.t

let y = if_ cond ~then_:some_computation ~else_:(read x)
val y : 'a Computation.t

Creates a Computation.t that provides a constant value.

Retrieves the path to the current computation as a string. This string is not human-readable, but can be used as an ID which is unique to this particular instance of a component.

Lifts a regular OCaml function into one that takes a Value as input, and produces a Computation as output.

Given a first-class module that has no input (unit input type), and the default value of the state machine, of_module0 will create a Computation that produces values of that module's Result.t type.

The same as of_module0, but this one has an input type 'i. Because input to the component is required, this function also expects a Value.t that provides its input. It is common for this function to be partially applied like so:

val a : int Value.t
val b : int Value.t

let f = of_module1 (module struct ... end) ~default_model in
let%sub a = f a in
let%sub b = f b in
...

Where the Value.t values are passed in later.

The same as of_module1 but with two inputs.

A constructor for Computation.t that models a simple state machine. The first-class module implementing Model describes the states in the state machine, while the first-class module implementing Action describes the transitions between states.

default_model is the initial state for the state machine, and apply_action implements the transition function that looks at the current state and the requested transition, and produces a new state.

(It is very common for inject and schedule_event to be unused)

Identical to actor1 but it takes 0 inputs instead of 1.

actor1 is very similar to state_machine1, with two major exceptions:

• the apply-action function for state-machine is renamed recv, and it returns a "response", in addition to a new model.
• the 2nd value returned by the component allows for the sender of an action to handle the effect and read the response.

Because the semantics of this function feel like an actor system, we've decided to name the function accordingly.

A frequently used state-machine is the trivial 'set-state' transition, where the action always replaces the value contained inside. This helper-function implements that state-machine, providing access to the current state, as well as an inject function that updates the state.

Similar to state, but stores an option of the model instead. default_model is optional and defaults to None.

The same as state_machine0, but apply_action also takes an input from a Value.t.

Because all Bonsai computation-returning-functions are eagerly evaluated, attempting to use "let rec" to construct a recursive component will recurse infinitely. One way to avoid this is to use a lazy computation and Bonsai.lazy_ to defer evaluating the Computation.t.

let rec some_component arg1 arg2 =
  ...
  let _ = Bonsai.lazy_ (lazy (some_component ...)) in
  ...

assoc is used to apply a Bonsai computation to each element of a map. This function signature is very similar to Map.mapi or Incr_map.mapi', and for good reason!

It is doing the same thing (taking a map and a function and returning a new map with the function applied to every key-value pair), but this function does it with the Bonsai values, which means that the computation is done incrementally and also maintains a state machine for every key-value pair.

enum is used for matching on a value and providing different behaviors on different values. The type of the value must be enumerable (there must be a finite number of possible values), and it must be comparable and sexpable.

The rest of the parameters are named like you might expect from pattern-matching syntax, with match_ taking the value to match on, and with_ taking a function that choose which behavior to use.

wrap wraps a Computation (built using f) and provides a model and injection function that the wrapped component can use. Especially of note is that the apply_action for this outer-model has access to the result value of the Computation being wrapped.

with_model_resetter extends a computation with the ability to reset the state machine for that computation back to its default. This can be useful for e.g. clearing a form of all input values.

Functions allowing for the creation of time-dependent computations in a testable way.

All the functions in this module incorporate the concept of "edge-triggering", which is the terminology that we use to describe actions that occur when a value changes.

This module implements dynamic variable scoping. Once a dynamic variable is created, you can store values in it, and lookup those same values. A lookup will find the nearest-most grandparent set_within call.

This Let_syntax module is basically just Value.Let_syntax with the addition of the sub function, which operates on Computations.