Exec

An Exec (short for execution) is one of the core elements of the Coach language and probably the most important one. It is a named and parameterized collection of specify and measure commands (among others) that, when called, generates the specification of what the athlete should perform and what they should measure.

Every exec call is a halt: one screen on the athlete’s phone, typically one set of an exercise.

Definition

To define an exec you need the keyword exec, a name, a list of parameters in parentheses (which may be empty) and a body in curly braces:

action BackSquat [title: "Back squat"]
output:number reps [title: "Reps"]
output:|kg| weight [title: "Weight"]
input:number reps [title: "Reps"]

exec squat() {
    specify:BackSquat reps 5, weight 100|kg|
    measure reps
}

The name has the usual naming limitations, i.e. it has to start with a letter and may contain letters, digits, _ and ?. The Trainerflow convention is to use a lowercase (snake_case) name for execs.

Calling an exec

An exec definition does nothing by itself. To use it you call it, exactly like a function in other languages:

squat()

When an exec is called, the following happens:

1. Its body runs and every specify and measure command adds to the specification.
2. When the body finishes, the program halts and the athlete is given the specification: the actions with their specified outputs, and the inputs they should measure.
3. The athlete performs it, fills in the measured inputs and continues.
4. The program picks up right after the call, and the call returns the athlete’s feedback.

An exec that ends up specifying and measuring nothing does not halt at all.

Parameters

An exec can also accept parameters whose values are provided when you call it. Using parameters is a great way to re-use the same exec. Say we have an exec that specifies a duration of 45|min| for a Run. Every call specifies the same 45|min|, but what if we wanted 60|min| on Mondays? This is exactly what parameters are for:

action Run [title: "Easy run"]
output:|min| duration [title: "Duration"]

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

run(45|min|)
run(60|min|)

A parameter is a name that you can think of as a placeholder for a value that will be provided when the exec is called. Inside the exec you use it like any other value, including in expressions:

action BackSquat [title: "Back squat"]
output:number reps [title: "Reps"]
output:|kg| weight [title: "Weight"]

exec squat(reps, top) {
    specify:BackSquat reps reps, weight top * 0.9
}

squat(5, 100|kg|)

Notice that reps is both the name of the parameter and the name of the output: in specify:BackSquat reps reps the first reps is the output and the second is the value. Calling an exec with the wrong number of arguments shows a warning in the editor.

An exec can also use anything defined outside of it, like variables declared earlier in the file.

The feedback

Calling an exec returns its feedback: what the athlete reported for every input the exec measured. Store it in a variable and read the inputs with a .:

action BackSquat [title: "Back squat"]
output:number reps [title: "Reps"]
output:|kg| weight [title: "Weight"]
input:number reps [title: "Reps"]

exec squat(load) {
    specify:BackSquat reps 5, weight load
    measure reps
}

let set = squat(100|kg|)
if (set.reps < 5) {
    squat(90|kg|)
}

The feedback also remembers what was specified. Put a & in front to read the prescription instead of the athlete’s answer, e.g. &set.BackSquat.reps is 5 whatever the athlete did. The feedback page has all the details.

Supersets

An exec can specify more than one action. All of them end up on the same screen, which makes an exec the natural way to write a superset:

action BenchPress [title: "Bench press"]
action BentOverRow [title: "Bent-over row"]
output:number reps [title: "Reps"]
output:|kg| weight [title: "Weight"]

exec push_pull() {
    specify:BenchPress reps 8, weight 60|kg|
    specify:BentOverRow reps 10, weight 50|kg|
}

push_pull()

This is still a single halt: the athlete does both exercises and then continues.

Metadata

An exec can set metadata to change how it is presented to the athlete. Any key can be set, but the mobile app reads two of them:

Key	What it does
@title	The name at the top of the athlete’s screen while they are in this exec, and the name of its entry in the run’s history. Without it, the exec’s own name is shown, e.g. squat.
@hidden	When true, the screen is named after the nearest group around the exec instead. A hidden exec is also left out of the plan.

action BackSquat [title: "Back squat"]
output:number reps [title: "Reps"]

exec squat(set, of) {
    @title = "Back squat, set " + set + " of " + of
    specify:BackSquat reps 5
}

repeat i:3 { squat(i, 3) }

The athlete sees Back squat, set 1 of 3, then set 2 of 3 and so on, instead of squat three times over.

What goes inside

Inside an exec you can define actions, inputs, outputs and variables, use the specify, measure and ask commands, branch with if and loop with repeat and while. You can also set metadata, such as the title of the screen.

The specify command only makes sense inside an exec; outside of one the editor reports it as an error. If you want several screens in a row, that is the job of a group.