Repository navigation
Relay Language
Håkon Olav Torvik edited this page Oct 24, 2026
·
1 revision
Part of the Relay design spec. See the contents.
The hard part
Carried over from chainlang, with one extension: a named block can be used as a number in duration arithmetic.
relay = "(" element (sep element)* ")"
sep = "," | NEWLINE // # starts a comment, to the end of the line
element = ref | dur_expr [STRING] | call | relay // STRING: optional label, e.g. 5m "stretch"
ref = IDENT // bare name: a reference step, keeps its identity and sound
call = "repeat" "(" int_expr "," element ")"
| "range" "(" num_expr "," num_expr ["," num_expr] ")" // fractional allowed
dur_expr = dur_term (("+" | "-") dur_term)*
dur_term = literal | int_expr | ref_value
ref_value = IDENT // inside arithmetic: that block's total duration NEW
literal = (NUMBER "h")? (NUMBER "m")? (NUMBER "s")?
int_expr = int_term (("+" | "-") int_term)* // bare number = minutes
int_term = NUMBER | "RANDOM" "(" int_expr "," int_expr ")"
| ("MINUTE" | "HOUR" | "SECOND") "(" "NOW" (("+"|"-") literal)? ")"
| "(" int_expr ")"
num_expr = int_expr with decimal NUMBERs allowed // minutes, rounded to whole seconds
-
A bare name is a reference:
(Test2)runs Test2 as a step, with its own sound. References are resolved when a run starts, so retuning Test2 updates every relay that uses it. Once started, a run is a frozen snapshot. -
A name inside arithmetic is a value
new: with Test2 = 10m,(Test2 - 2)is a relay of one anonymous 8m step.Test2 + 30salso works. A relay name used this way contributes its total duration. A result ≤ 0 is an error. Sound: with exactly one name in the expression, the step inherits that block's sound. Otherwise it uses the relay default. -
range(a, b, step)expands to anonymous steps of a, a+step, … minutes, including b when it lands on a step (range(1, 3)is 1, 2, 3;range(1, 4, 2)is 1, 3), which reads naturally to non-programmers. Direction-aware; fractional values allowed:range(1, 3, 0.5)gives 1m, 1m30s, 2m, 2m30s, 3m.arangeis droppedchanged. - An anonymous step can carry a display-only label, written
5m "stretch", which is shown at ring time.new -
NOWis evaluated once, when the run starts. -
#starts a comment that runs to the end of the line (except inside a quoted label).new
| Block | Definition | Total |
|---|---|---|
| Work | Timer · 25m · sound: sadsong | 25m |
| Break | Timer · 5m · sound: happysong | 5m |
| Session | Relay · repeat(4, (Work, Break)) · seamless |
2h |
| Workday | Relay · (Session, 30, Session, 60, Work)
|
5h 55m |
| Wake | Relay · (Nudge, Nudge, Louder, Loud, Siren), five 5m timers with escalating sounds · interaction required · scheduled Mon–Fri 06:30 |
25m |
Wake is the snooze-less wake-up call. Each boundary rings with the ending step's sound until you tap Continue, which starts the next five minutes. It's snooze with character, and Stop relay ends it when you're actually up.
| Limit | Default | Configurable |
|---|---|---|
| Reference graph is a DAG (no self-containment) | always | No |
| Max reference depth | 20 | No |
| Max resolved plan size, counted across all references | 300 steps | Yes, hard ceiling 1000 |
| Max repeat/range multiplier | 200 | No |
| Max expression length | 2000 chars | No |
| Long-relay warning | above 24 h | Yes |
| Check | When | Catches |
|---|---|---|
| Cycle check over the whole reference graph | Every save and rename of a relay or timer | Self-containment, direct (R1 → R1) or indirect (R1 → R2 → R1), with the path in the error |
| Shape check on one script's AST | Every keystroke and save, before expansion | Nesting bombs inside one script (repeat(200, repeat(200, …))). It treats each reference as one opaque step, so on its own it does not catch cycles or big referenced blocks |
| Plan check on the fully expanded plan | Run start, and in the editor preview | Totals across references (repeat(200, BigRelay)) and max depth. It also stops expanding if the depth limit is hit, so a cycle that slips past save (a bad import, say) fails safely instead of overflowing the stack new
|
v0.5 gap: only the first two existed. The run engine expanded referenced relays recursively without re-checking the combined size or depth, so a relay made of big referenced relays could exceed the plan cap.
Relay · spec v1.0 · clean-restart baseline, update as screens get built