package matrix
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:
Terminal.createmakes the terminal.runmakes the session, starts the program, and settles; orcreatemakes it, the program starts withconfig, andattachgives the session its steps.input,resize,settleandadvancedrive it,set_timemoves its clock, and the readers ofTerminalobserve it.- The run ends when the program returns, on its own or at the end of the input, which
rungives 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
Screens
Terminals
Sessions
The type for sessions.
val run :
?config:Matrix.config ->
?now:int ->
?quiesce:(unit -> unit) ->
Terminal.t ->
(t -> unit) ->
(t -> 'a) ->
'arun 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.
terminal s is s's terminal.
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.
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).
val attach :
?quiesce:(unit -> unit) ->
t ->
step:(now:int -> [ `Stepped | `Idle | `Stopped ]) ->
deadline:(unit -> int option) ->
unitattach 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.
input s bytes delivers bytes as one write, which the run reads until it has read all of it.
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.
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.
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.
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.
deadline s is the next time the program has something to do, if any.
Raises Invalid_argument if no program is attached.