Home / Docs / Examples

metronome

Release v0.4.0

A metronome: a program that plays one beat every half second, tick on the first beat of each bar of four and tock on the others, until it is stopped.

This is a driven program, the host-driven step of spec/26 §2: the package declares no main. Its ita.una names, in a drive section, the module whose loop the host runs and the period of its ticks. The host calls init once for the first state, step once for each tick with the state to change, and on_stop once when the run is stopped. The driven programs guide explains each part.

What it demonstrates:

Run it

From this directory:

sh
una run . --stop-after-iterations 5   # copy examples/metronome

A driven program runs until it is stopped: Ctrl-C or SIGTERM stops it, on_stop prints where it stopped, and the run ends with exit code 0. --stop-after-iterations 5 stops it after five beats, so the run is the same every time:

una run . --stop-after-iterations 5Output
bar 1: tick
bar 1: tock
bar 1: tock
bar 1: tock
bar 2: tick
stopped at bar 2, beat 1

una build . makes an executable, target/una/metronome, that runs the same driver and takes the same flag:

sh
una build .   # copy examples/metronome
./target/una/metronome --stop-after-iterations 5

Check and test it

sh
una check .   # copy examples/metronome
una test .
una report .

una test . runs the two tests of advance:

una test .Output
test metronome "the first beat opens bar 1" ... ok
test metronome "the fourth beat is followed by the first of the next bar" ... ok

2 tests: 2 passed, 0 failed

How it works

The drive section names the module metronome and a tick every 500 milliseconds; run grants gives the console to its functions:

ita.unauna
run
  grants
    console

drive
  module metronome
  ticks 500

The state is a Metronome, the bar and the beat in it. init returns the state before the first beat, and step replaces it with the next beat and prints it:

src/metronome.unauna
pub step(edit state: Metronome, input: Tick) -> Unit
  uses @console: Console[print]
=
  state = advance(state)
  if state.beat == 1
    @console.print("bar {state.bar}: tick")
  else
    @console.print("bar {state.bar}: tock")

step reads the state and not its input: the beat count is the same however late a tick comes, which keeps the output of a stopped run the same in both engines.

Edition

Edition 0.4, a preview (edition).

Files

ita.unauna
ita metronome
  version 0.1.0
  edition 0.4

run
  grants
    console

drive
  module metronome
  ticks 500
ita.lock
-- Written by `una ita`; do not edit.
lock 1

solver
  encoding "una-smt-1"
  name "z3"
  version "5.1.0"
  logic "QF_UFLIA"
  steps 5000000
  seed 0
src/metronome.unauna
module metronome

import std.drive (Tick)

--- Where the metronome is: the bar it plays, and the beat in that bar, 0 before the first.
pub kind Metronome
  bar: Nat
  beat: Int in 0..4

--- The metronome before its first beat.
pub init() -> Metronome = Metronome(bar: 1, beat: 0)

--- The beat after `state`: the next one in the bar, or the first of the next bar after the
--- fourth.
pub advance(state: Metronome) -> Metronome
  ensures result.beat >= 1
  ensures state.beat < 4 implies result.bar == state.bar
=
  if state.beat < 4
    Metronome(bar: state.bar, beat: state.beat + 1)
  else
    Metronome(bar: state.bar + 1, beat: 1)

--- Plays one beat for each tick: `tick` on the first beat of a bar, `tock` on the others.
pub step(edit state: Metronome, input: Tick) -> Unit
  uses @console: Console[print]
=
  state = advance(state)
  if state.beat == 1
    @console.print("bar {state.bar}: tick")
  else
    @console.print("bar {state.bar}: tock")

--- Says where the metronome stopped.
pub on_stop(state: Metronome) -> Unit
  uses @console: Console[print]
=
  @console.print("stopped at bar {state.bar}, beat {state.beat}")

test "the first beat opens bar 1"
  do advance(init())
  expect result.bar == 1 and result.beat == 1

test "the fourth beat is followed by the first of the next bar"
  do advance(Metronome(bar: 1, beat: 4))
  expect result.bar == 2 and result.beat == 1