Reading diagrams / Topic 27 of 42

Programs and what they ask for

The rule

Some programs keep their rules apart from the world. A pure program is a step: it takes what has happened so far and returns what to do next. It never reads or writes anything itself. When it needs the world, the value it returns is a request, such as “AskReviewer”, and other code performs it and hands the reply back. Gary Bernhardt calls this split a functional core and an imperative shell; it is also called sans-IO, and the Elm architecture works the same way.

The system map draws the program as a green box at the bottom of the wall, under the rail, with its package written above it. Its first line names the step and what it returns: “step → Next” is a function called step that answers with a Next. Under that, the box counts the package's definitions, and those it uses from other packages.

Each kind of request the step can return is an opening on the box's right edge, with the type the request carries. Every kind is drawn, so a request with no opening cannot be made. An opening struck through is still a request the step can make; the next topic says what the strike means.

The box's top right corner says whether the program's own package touches the world. “effects” struck through means it does not: every read and write happens outside the program. A red dot with a count, such as “1 effect”, means that many definitions in the package perform effects themselves.

review-desk: a small service whose rules live in a pure program.

Loading the system map.

review-desk-peek: the same program with one more definition, peek_source, in the program’s package.

Loading the system map.

problemsapi again. Its program band is at the bottom of the wall.

Loading the system map.

Loading the worked examples and practice.