package matrix

  1. Overview
  2. Docs

Module Matrix_testSource

Terminals emulated in a test's process, and the programs that run on them.

A terminal (Terminal.t) is an emulator (Vte) playing a profile (Profile.t). It applies what a program writes, answers the program's queries as that terminal does, keeps what the program asks of its host, and gives the bytes it sends for what its user does, in the encoding the program has set (its keyboard protocol, mouse format and paste mode). It performs no input or output itself.

A session (t) runs a program in the test's process on a terminal, with a clock that moves only inside the session's functions. The program runs on Matrix, or on a library built on it, with the session's configuration (config), which gives the run the terminal and the clock. A program that waits for its input, with Matrix.next as Mosaic.run does, runs unchanged (run). When it has nothing to do, it waits for the test instead of the terminal. A program that takes its own steps has the test take them (attach). Either way the program goes on only inside the session's functions, and between two calls nothing runs.

The terminal shows each write as it is made and sends each input as one write. So the run draws a frame asked for by input, a timer, a message or the runtime itself at the instant it is asked, and decodes a lone ESC as Escape at once. An animation's next frame, asked for from its frame, comes one frame interval later (Matrix.config's fps), as on any terminal, and a frame that input brings in between does not move the times of the animation's later frames. Time moves only by advance and set_time, and by the wait for an answer of a terminal that gives none (Profile.t's answers).

A session is settled when the program has nothing to do at the session's time and the work it runs off its loop, such as Mosaic's commands and workers, has finished or waits for something only the test can change. That work runs on an executor, the session's queue (perform) or the program's own, for which run and attach take a quiesce.

A session differs from a real terminal in two ways. A real terminal writes over time, so a lone ESC can wait for what may follow it, and a child on a pseudo-terminal (Child) shows that race. And a session draws at once every frame asked for outside a frame, where a run on a real terminal draws at once only the frames discrete input asks for, and draws the others on the grid (Matrix.request_redraw). The grid needs a real clock: on a session's clock, which moves only when the test moves it, a frame a timer or a post asks for would wait for a grid point that never comes. The grid is the same on both: a frame a session draws before the grid's next one is early (Matrix.early), as on a terminal, and an animation moves only in the frames that are not, as Mosaic's ticks do, so its goldens do not depend on the input, the timers or the messages.

The life cycle of a session:

  1. Terminal.create makes the terminal.
  2. run makes the session, starts the program, and settles; or create makes it, the program starts with config, and attach gives the session its steps.
  3. input, resize, settle and advance drive it, set_time moves its clock, and the readers of Terminal observe it.
  4. The run ends when the program returns, on its own or at the end of the input, which run gives once its body returns. The terminal then shows what the run left on it.

The functions that drive a session, input, resize, settle and advance, settle it before they return, and raise Invalid_argument if no program is attached or its run has ended. The other functions that take a session do not settle it, and raise only as their docs say.

This runs a program that counts keys, types two and prints the screen:

let term = Matrix_test.Terminal.create ~cols:20 ~rows:1 () in
Matrix_test.run term (fun s ->
    Matrix.run ~config:(Matrix_test.config s) @@ fun app ->
    let rec loop keys =
      match Matrix.next app with
      | Stopped -> ()
      | Event (Key _) ->
          Matrix.request_redraw app;
          loop (keys + 1)
      | Frame ->
          Matrix.draw app (fun grid ->
              Matrix.Grid.draw_text grid ~x:0 ~y:0
                ~text:(Printf.sprintf "%d keys" keys));
          loop keys
      | Event _ | Timer _ | Posted _ -> loop keys
    in
    loop 0)
@@ fun s ->
Matrix_test.input s (Matrix_test.Terminal.text term "ab");
print_string (Matrix_test.Screen.text (Matrix_test.Terminal.screen term))

A Mosaic program runs with Mosaic_test.run term app (library mosaic.test), which is Mosaic.run ~config:(Matrix_test.config s) ~process_perform:(Matrix_test.perform s) app under run, so that its work off the loop runs on the session's queue.

Profiles

Sourcemodule Profile : sig ... end

Terminal profiles, the facts of a terminal that a session plays.

Screens

Sourcemodule Screen : sig ... end

What a terminal shows at one moment.

Terminals

Sourcemodule Terminal : sig ... end

Terminals, emulators playing a profile.

Sessions

Sourcetype t

The type for sessions.

Sourceval run : ?config:Matrix.config -> ?now:int -> ?quiesce:(unit -> unit) -> Terminal.t -> (t -> unit) -> (t -> 'a) -> 'a

run term program body runs program s on a session s of term, whose run takes config s, until the program waits for input (Matrix.next, as in Mosaic.run) with nothing to do, then is body s. The program's first frame is on the terminal when body begins. The program stays where it waits, and each function of body that settles has it go on until it waits again. When body returns or raises, the input ends, and the program goes on until it returns, as it does at the end of its input. config is the configuration the run is given on the session's terminal (default Matrix.config ()), now as for create, and quiesce as for attach.

The program runs on the test's thread, under an effect handler that run installs: where the program would wait, the session performs an effect that suspends it, and the session's functions resume it. So the program must wait on the thread and in the domain that called run, inside program, and not under a handler of its own that catches every effect. A program that waits with an event loop of its own takes its steps through attach instead.

Raises what program raises, at the call that had it go on, and Invalid_argument if the program waits from another thread or domain.

Sourceval create : ?config:Matrix.config -> ?now:int -> Terminal.t -> t

create term is a session on term whose clock reads now (default 0) nanoseconds, for a program driven by its steps (attach), whose run takes config (default Matrix.config ()) on the session's terminal (config). A terminal must have at most one session.

Sourceval terminal : t -> Terminal.t

terminal s is s's terminal.

Sourceval config : t -> Matrix.config

config s is the configuration s was made with, for a run on s's terminal and clock. The run takes no descriptor and no environment of its own, since the terminal's profile has them.

Sourceval perform : t -> (unit -> unit) -> unit

perform s job queues job on the session's queue, an executor such as Mosaic.run's process_perform. Settling runs the queue in order, on the calling thread. A job must return and must not wait for the loop, so work that runs as long as the program does, such as a worker reading a stream, must run on the program's own executor, with a quiesce (attach).

Sourceval attach : ?quiesce:(unit -> unit) -> t -> step:(now:int -> [ `Stepped | `Idle | `Stopped ]) -> deadline:(unit -> int option) -> unit

attach s ~step ~deadline has s drive a program that takes its own steps, as one does that waits with an event loop of its own, and settles. step ~now takes the program's next step at now, as Matrix.step does, and says whether it took one, the program has nothing to do, or its run has stopped. deadline () is Matrix.deadline of the program's run. They are Mosaic.step and Mosaic.deadline for a Mosaic program. quiesce () must return once every piece of work the program's executor was given has finished or waits for something only the test can change. It defaults to running perform's queue.

Raises Invalid_argument if a program is attached.

Sourceval input : t -> string -> unit

input s bytes delivers bytes as one write, which the run reads until it has read all of it.

Sourceval resize : t -> cols:int -> rows:int -> unit

resize s ~cols ~rows resizes the terminal and tells the run as the terminal does: by a window signal and the mode 2048 report when the program has set it, or, for an output that is not a terminal, by the report alone.

Sourceval settle : t -> unit

settle s settles s, as after the test released work it held.

Sourceval advance : t -> int -> unit

advance s ns moves the clock ns nanoseconds forward, and settles at each deadline on the way (deadline) and at the end. So every timer and every animation frame on the way has an instant of its own.

Raises Invalid_argument if ns is negative.

Sourceval set_time : t -> int -> unit

set_time s time moves the clock to time without taking a step, so that input delivered next is read in the same turn as the timers due at time, and before them. It does not settle.

Raises Invalid_argument if time is earlier than the clock.

Sourceval check_presented : t -> unit

check_presented s checks that the terminal shows, on the rows of the frame (Matrix's live region in `Primary mode), the text of the frame the run believes it presented (Matrix.current_grid), which the run's own diff of frames wrote. A test calls it after its steps to catch output that puts on the terminal another frame than the run drew. Once the run has ended, and given the terminal back, it checks nothing.

Raises Failure, with each row that differs, if they differ, and Invalid_argument if no run has begun on s.

Sourceval now : t -> int

now s is the time of s's clock, in nanoseconds.

Sourceval deadline : t -> int option

deadline s is the next time the program has something to do, if any.

Raises Invalid_argument if no program is attached.

Sourceval frames : t -> int

frames s is the number of frames the run has begun.

Sourceval steps : t -> int

steps s is the number of steps the program has taken.

Sourceval ended : t -> bool

ended s is true once the program's run has stopped.

Programs in another process

Sourcemodule Child : sig ... end

Programs run as a child process on a pseudo-terminal.