While

Purpose

The While command is pretty similar to the repeat command and can be used whenever you want to repeat a bunch of commands while a test expression is true.

To issue a while command you need the expression that is calculated on every repetition to check (test) when to stop. We call this expression its test expression.

Some example uses would be:

1. You want to create a program that never ends: it goes on forever, until the athlete stops it. The natural thing to do is to use a while command with its test expression set to true.
2. You want to repeat an exec until the athlete fails it.

Definition

A while command is the keyword while, the test expression and the commands to repeat, in curly braces:

action PushUp [title: "Push-up"]
output:number reps [title: "Reps"]
input:number reps [title: "Reps"]

exec push_ups(target) {
    specify:PushUp reps target
    measure reps
}

let target = 10
let set = push_ups(target)
while (set.reps >= target) {
    target = target + 2
    set = push_ups(target)
}

Every time the athlete makes all their reps, the next set asks for two more. The first time they fall short, the while stops.

Execution

A while command first calculates its test expression. If the result is something other than false or nil, it runs its commands one by one and, when the last one finishes, calculates the test expression again. If the result is false (or nil), it does not run the commands another time and the program continues with the command after the while.

The commands you can put inside a while are dictated by the surrounding context, i.e. whether the while is inside an exec, inside a group or at the top level of a file.

Break and continue

As with repeat, break stops the while right away and continue skips the rest of the current repetition. A while (true) with a break inside is a common way to write a loop whose condition is easier to check in the middle:

import "coach/common/rest.cl"

action Run [title: "Easy run"]
output:|min| duration [title: "Duration"]
input:boolean more? [title: "Up for another week?"]

exec run(time) {
    specify:Run duration time
}

exec check_in() {
    measure more?
}

let minutes = 20|min|
while (true) {
    repeat 3 {
        run(minutes)
        rest(2|day|)
    }
    if (!check_in().more?) {
        break
    }
    minutes = minutes + 5|min|
}