---
title: "metronome"
url: https://una-lang.org/en/docs/examples/metronome/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/examples/metronome/README.md
---

# metronome

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`](https://una-lang.org/en/docs/spec/26-long-running-programs/): 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](https://una-lang.org/en/docs/guides/driven-programs/) explains each part.

What it demonstrates:

- a manifest in `ita.una`, edition `0.4`, a preview ([manifest](https://una-lang.org/en/docs/configure/ita/manifest/)), with a `drive` section;
- `init`, `step` and `on_stop`, the three functions the host calls, with a state of a kind of the package and a `Tick` of `std.drive`;
- a `step` whose `edit` parameter carries the state from one tick to the next;
- [tests](https://una-lang.org/en/docs/language/examples/test/) of `advance`, the function `step` calls, which the host never needs to run.

## 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:

```text una="run . --stop-after-iterations 5"
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`:

```text una="test ."
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:

```text file="ita.una"
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:

```text file="src/metronome.una"
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](https://una-lang.org/en/docs/configure/package/edition/)).

## Files

`ita.una`

```una
ita metronome
  version 0.1.0
  edition 0.4

run
  grants
    console

drive
  module metronome
  ticks 500
```

`ita.lock`

```text
-- 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.una`

```una
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
```
