Metadata

Not everything in a program is about what the athlete does. Some of it is about how things are presented: what a piece of work is called on the athlete’s screen, or whether it should be named at all. Coach keeps that kind of information apart from the specification, as metadata.

Setting metadata

Metadata is written with an @ in front of a name, assigned like a variable, inside the body of an exec or a group:

action Plank [title: "Plank"]
output:|s| duration []

exec plank(seconds) {
    @title = "Core finisher"
    specify:Plank duration seconds
}

plank(45|s|)

The value can be any expression, so it can depend on parameters and on anything else the program knows:

action Squat [title: "Back squat"]
output:number reps []

exec squat_set(n, of) {
    @title = "Squat, set " + n + " of " + of
    specify:Squat reps 5
}

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

Every call gets its own metadata. Setting @title in one call of squat_set does not change the title of the next one.

Metadata belongs to an exec or a group, so it can only be set inside one. Writing @title = … at the top level of a file is an error.

Nested keys

A metadata key can have parts, separated by dots, just like a path into a map:

action Run [title: "Easy run"]
output:|km| distance []

exec easy_run() {
    @coach.cue = "Conversational pace"
    specify:Run distance 5|km|
}

easy_run()

Reading metadata

Inside the same body, @key reads back what was set, which lets later lines depend on earlier ones. The standard library uses this to decide whether to give an exercise a title at all:

action Squat [title: "Back squat"]
output:number reps []

exec squat(show) {
    @hidden = !show
    if (!@hidden) {
        @title = "Back squat"
    }
    specify:Squat reps 5
}

squat(true)

What the apps use

Any key you like can be set, and your program can read it back, but two keys change what the athlete sees:

Key	Effect
@title	The name shown at the top of the athlete’s screen. It comes from the exec they are in or, if that one is hidden, from the nearest group around it that is not. Without a title, the exec or group’s own name is shown.
@hidden	When true, the exec or group is skipped when naming where the athlete is.

When nothing on the way is visible, the screen simply reads Active Program. The exec and group pages go through both keys in detail.

The Starting Strength example titles its two workouts this way:

import "coach/strength/squat.cl"

group workout_a() {
    @title = "Workout A"
    squat([weight: 60|kg|, reps: 5], [reps: true], [])
}

workout_a()

The standard library’s exercises are hidden unless you pass them a location option, so while the athlete squats, the top of their screen reads Workout A. Pass [location: true] instead and it reads Back Squat.

The rest exec of the standard library sets @hidden = true, so a rest between sets is never mistaken for a piece of work of its own.