12. Looks

Goal

Draw the system your own way.

New in this chapter

Steps

So far the stage has been drawn for you, by a default look. A look is a package like the others, but it only watches: it reacts to the facts of the trace, draws, and never changes what happens. Nothing you write in a look can alter a run, so you can change how a system looks without ever risking what it does.

A look reacts with when followed by a trace event: sim.Started, sim.Added n, net.Sent m from a to b. Trace events have no receiver, because they happen to the whole system. The words after the event name new names for the parts of the fact (n is the node that was added), or, if a name already exists, filter on it.

Look code runs in the fourth context, look. It reads the exported state of nodes, as it was after that fact, and it has the drawing phrases of std/look. Using std/look also switches the default look off, so the package must draw the cards itself. We start a new package, rumorlook, and import it from the demo; a package with observers is active as soon as it is imported. Step 1 puts the nodes on a ring with look.Layout "ring" and draws one card for each node:

Step 1

# package main
use example.com/tutorial/rumor
use example.com/tutorial/rumorlook
use std/net
use std/sim

define main
  sim.Seed 4
  set nodes to (sim.Cluster of 6 running rumor)
  set left to {(item 0 of nodes), (item 1 of nodes), (item 2 of nodes)}
  set right to {(item 3 of nodes), (item 4 of nodes), (item 5 of nodes)}
  rumor.Connect nodes
  deliver (message rumor.Rumor with Text "The leader is n1") to (item 0 of nodes)
  net.DropNext "Rumor" from (item 0 of nodes) to (item 1 of nodes)
  after 300ms
    net.Partition left from right
  after 3s
    net.Heal
# package rumorlook
use std/look
use std/sim

# Put the cards on a ring
when sim.Started
  look.Layout "ring"

# One card for each node, attached to the node as "card"
when (sim.Added n)
  draw (look.Card for n) as card for n

draw (look.Card for n) as card for n creates a shape, gives it the name card, and attaches it to the node n with for n. A shape has the type shape. Attached shapes can be reached later from any observer with card of n. Messages are invisible for now. Step 2 draws a ball per message: it takes off at net.Sent, flies between the two cards with look.Flight, and is removed when the message arrives. The ball is attached to the message id, net.Id m, so ball of (net.Id m) finds it later:

Step 2

# package rumorlook
use std/look
use std/net
use std/sim
use std/theme

# Put the cards on a ring
when sim.Started
  look.Layout "ring"

# One card for each node, attached to the node as "card"
when (sim.Added n)
  draw (look.Card for n) as card for n

# A ball takes off from the sender's card and flies to the receiver's
when (net.Sent m from a to b)
  draw (look.Circle 6) as ball for (net.Id m)
  look.Fill ball with theme.Accent
  look.Flight ball from (card of a) to (card of b) for m

# It lands and disappears
when (net.Arrived m from a to b)
  look.Remove (ball of (net.Id m))

A card should show what the node knows. A draw can end with an indented block that is reactive: it runs again whenever the state it reads changes, and the card morphs to the new look. A binding with a type, [n: rumor.Node], tells the compiler that n runs rumor, so n.rumor.Known is readable. Colors are values too, of type color, but only named ones: a color is a phrase with no holes whose result is the literal. Heard is ours, and theme.Quiet comes from std/theme:

Step 3

# package rumorlook
use example.com/tutorial/rumor
use std/look
use std/net
use std/sim
use std/theme

# The color of a card that knows the rumor
define Heard
  result #F4A340

# Quiet while a node knows nothing, Heard afterwards
define Tint [t: text]
  if (t is "")
    result theme.Quiet
  result Heard

# Put the cards on a ring
when sim.Started
  look.Layout "ring"

# One card for each node, whose color follows what the node knows
when (sim.Added [n: rumor.Node])
  draw (look.Card for n) as card for n
    look.Fill card with (Tint n.rumor.Known)

# A ball takes off from the sender's card and flies to the receiver's
when (net.Sent m from a to b)
  draw (look.Circle 6) as ball for (net.Id m)
  look.Fill ball with theme.Accent
  look.Flight ball from (card of a) to (card of b) for m

# It lands and disappears
when (net.Arrived m from a to b)
  look.Remove (ball of (net.Id m))

That is a lot of code to redo what the default look already did. A look package may use std/look/basic to keep the default and change only what it wants. Step 4 keeps the basic look (cards, messages, captions) and replaces just the card with a tinted one:

Step 4

# package rumorlook
use example.com/tutorial/rumor
use std/look
use std/look/basic
use std/sim
use std/theme

# The color of a card that knows the rumor
define Heard
  result #F4A340

# Quiet while a node knows nothing, Heard afterwards
define Tint [t: text]
  if (t is "")
    result theme.Quiet
  result Heard

# Replace the basic card with one whose color follows what the node knows
when (sim.Added [n: rumor.Node])
  draw (look.Card for n) as card for n
    look.Fill card with (Tint n.rumor.Known)

The colors in a look come from somewhere. theme.Quiet is a theme value: the program has one theme, a package with the header # theme <word> that defines every theme name once, from the colors (Paper, Ink, Accent…) to the type face (Sans) and the shape of a node card (NodeShape). Until now the program used the default theme of std. Step 5 picks its own. The default theme is the template: a program cannot write std/theme/default, so you copy its definitions into a new local package, rumortheme, and change what you like. Here Paper is a plum instead of navy, Accent is rose instead of amber, and Sans is a serif. A theme defines all of its names, not some of them. A program is given its theme by importing it in the main file, and a program with no theme import keeps the default one:

Step 5

# package main
use example.com/tutorial/rumor
use example.com/tutorial/rumorlook
use example.com/tutorial/rumortheme
use std/net
use std/sim

define main
  sim.Seed 4
  set nodes to (sim.Cluster of 6 running rumor)
  set left to {(item 0 of nodes), (item 1 of nodes), (item 2 of nodes)}
  set right to {(item 3 of nodes), (item 4 of nodes), (item 5 of nodes)}
  rumor.Connect nodes
  deliver (message rumor.Rumor with Text "The leader is n1") to (item 0 of nodes)
  net.DropNext "Rumor" from (item 0 of nodes) to (item 1 of nodes)
  after 300ms
    net.Partition left from right
  after 3s
    net.Heal
# theme rumortheme
# scene ground, a dark plum
define Paper
  result #1B1722

# node cards, primary text
define Ink
  result #EDE9E1

# links, borders
define Line
  result #3A4366

# secondary text, idle nodes
define Quiet
  result #8A90A8

# messages, the one thing to look at
define Accent
  result #E26D8F

# success, committed
define Good
  result #5CC8B8

# candidate, pending
define Warning
  result #E8C35A

# broken invariant, crashed
define Critical
  result #E86F5A

# message color 1
define Message1
  result #F4A340

# message color 2
define Message2
  result #7FB2F0

# message color 3
define Message3
  result #C79BEA

# message color 4
define Message4
  result #F08FB0

# edges not darkened
define Vignette
  result 0

# outlines not wobbled
define Sketch
  result 0

# glow blur
define Glow
  result 24

# no shadow
define Shadow
  result 0

# outline width
define StrokeWidth
  result 2

# rect corners
define CornerRadius
  result 12

# node cards are rects
define NodeShape
  result "card"

# node cards are filled
define NodeFill
  result "solid"

# links are opaque
define LinkOpacity
  result 1

# smootherstep moves
define Easing
  result "smooth"

# no drift
define Drift
  result 0

# default sans face, a serif here
define Sans
  result "Source Serif 4"

# default mono face
define Mono
  result "JetBrains Mono"

# title role
define TitleSize
  result 28

# label role
define LabelSize
  result 16

# value role
define ValueSize
  result 15

# caption role
define CaptionSize
  result 20

# title role
define TitleWeight
  result 600

# label, value, caption roles
define LabelWeight
  result 500

# no letter spacing
define Tracking
  result 0

# `look.Frame` inset
define Margin
  result 4

# layout scale
define Fill
  result 1

Like a look, a theme only changes how the run is drawn. The trace of step 5 is the trace of step 4 to the letter.

Looks are the place for taste. The behaviour never changes: run the program without the look and you get the same trace.

What to watch

Step 1: six empty cards on a ring and no messages. Step 2: balls travel between cards; a dropped message stops halfway. Step 3 and 4: a card is grey until its node learns the rumor, then it turns amber, smoothly. The partition is visible: the amber spreads on one side and waits on the other. Step 5: the same picture on a plum ground, the messages and captions in rose, and a serif face.

Why it looks like this

A look cannot change what happens. An observer that tries to set a node field is refused:

rumorlook/rumorlook.synod:25:7: error[context]: "set n.rumor.Known" is not allowed in look context
   |
25 |   set n.rumor.Known to ""
   |       ^^^^^^^^^^^^^
Error context

synod check says error[context]: setting state is not allowed in look context. This is what lets the trace be the same with and without a look.

A theme is held to the same standard: it must define every name. Take Fill out of rumortheme:

rumortheme/rumortheme.synod:1:1: error[bad-theme]: theme "rumortheme" does not define "Fill"
  |
1 | # theme rumortheme
  | ^^^^^^^^^^^^^^^^^^
  |
  = note: copy std/theme/default and change its values
Error bad-theme

synod check says error[bad-theme]: the theme "rumortheme" does not define "Fill". With a name missing, a look could ask for a value that does not exist, so the theme is refused before anything runs.

Exercises

  1. Change the colors: make unknowing cards theme.Critical.
Expected

Use theme.Critical in Tint. The cards start red and turn amber.

  1. In step 2 use look.Layout "row".
Expected

The six cards stand in a row instead of a ring.

  1. In step 4, remove the use std/look/basic line.
Expected

The program still checks, but messages are no longer drawn, because only the cards are drawn by this package.

  1. In step 5, change the result of NodeShape in rumortheme from "card" to "circle".
Expected

The cards become circles with the name in the middle; the ring, the colors and the messages are as before. The trace is the same, because a theme never changes what happens.