Hooks & macros reference

Hooks are blocks of logic that run at moments in a workout's lifecycle — they read what happened (reps, weights, whether you hit your targets) and write back training-max and state changes that make a program adapt from session to session. A progression macro packages hook logic (and optionally a set scheme) into a reusable rule you attach to as many exercises as you like with using.

This is the complete reference. For a gentler introduction, start with Progressions & hooks.

Two flavours of macro

A macro may contain both. The built-in macros (below) are set-scheme only — they lay out reps and percentages but do not progress the training max on their own. Pair them with a hook (inline or your own macro) to add progression.

A macro's on_complete hook drives progression today; an on_set hook is parsed and validated but not yet evaluated at runtime (see runtime caveats below).

Attach with using:

Parameters

A macro declares parameters in parentheses. Each may have an optional : type annotation (number or weight) and an optional = default:

progression "ramp" (increment = 2.5, bump: weight = 2.5kg, target: weight) { ... }

• A weight default carries a unit (2.5kg); the type is inferred from a weight default.
• An omitted parameter falls back to its default. An omitted parameter with no default is a compile error.
• Parameter names may shadow built-in variables — that's intentional, so a macro can name a parameter target_reps or similar without a conflict. They can't shadow a language keyword (week, state, using, and so on).

Value- vs reference-binding

How you bind an argument at the using site decides whether the macro can write to it — this is what makes a macro stateful.

Barbell Row {
  8-12 @state.row_weight
  using "double_prog" (load: state.row_weight, top: 12)
}

A set-scheme macro takes literal arguments only — passing a state reference to one is an error, because there's no number to expand into a set.

Override & precedence rules

• A using macro that supplies sets makes the exercise's own explicit sets ignored (with a warning) — write the sets in one place.
• An inline on_complete / on_set hook on the exercise overrides a hook the macro would supply.
• A script-level progression "name" with the same name as a built-in overrides the built-in.
• An unknown macro name is a warning; the exercise keeps its own sets.

Built-in macros

Four set-scheme macros ship with every program — use them by name without defining anything. Each declares an increment parameter for convention, but remember these are set layouts, not progression logic:

Bench Press {
  using "dp"
}

Built-in functions

Available inside any hook body (and therefore any macro hook):

Unit-aware increments

Weights in ReptoLang are raw numbers labelled with a unit — nothing ever converts kg ↔ lbs. To bump by the right amount for either lifter, write a unit pair { <kg>, <lbs> }:

{ Akg, Blbs } is shorthand for pick(unit_is_metric, A, B). It needs exactly one kg and one lbs slot (order doesn't matter), each a non-negative weight literal — a leading - is a parse error, so write a subtraction (tm.self -= { 2.5kg, 5lbs }) instead.

The two hook kinds

on_set is meant to run during a workout; on_complete runs when you complete the session.

on_set is parsed and validated but not yet evaluated at runtime. The compiler accepts on_set blocks (inline or supplied by a macro), but the app currently drives behavior from on_complete only — next_set_weight / next_set_reps are not applied yet. Write on_set logic if you like, but don't depend on it taking effect today.

Hook scopes

on_complete can be attached at three scopes. They are evaluated in this order when a session completes:

1. Exercise — once per completed exercise block.
2. Day — once, after every exercise in the day.
3. Week — once, only on the session that completes the last day of the week.

State writes thread forward: a state change made by an exercise hook is visible to the day hook, and the day's writes are visible to the week hook.

Program-level on_complete is parsed but not evaluated. The grammar accepts a top-level on_complete block, but the app does not run it at workout completion — don't rely on it. Use exercise, day, or week scope instead.

Variables by scope

Every variable is a number (booleans are 1/0). Weights are in the lifter's own unit and are never converted. Which variables exist depends on the scope, because day- and week-level hooks have no single "current set" to report.

Exercise on_complete

Plus tm.self (this exercise's training max), tm.<exercise> (any TM in the tm { } block), and state.<name> (any declared state variable).

Day on_complete

Day hooks see only program-context variables — no per-set data, and no tm.self:

week_index, day_index, session_count, day_volume (weight × reps across the whole day), unit_is_metric, and state.<name>.

Week on_complete

Everything a day hook sees, plus week_volume (weight × reps across every session in the week).

on_set outputs

on_set is intended to run mid-workout and expose the in-progress set context. The two variables it may write are the only way to influence the next set (note the runtime caveat above — these outputs aren't applied yet):

What a hook may write

Anything else is rejected at compile time. In particular, deep paths like state.x.y and reserved keys (__proto__, constructor, prototype, hasOwnProperty) are forbidden.

Type rules

Hook bodies are type-checked at compile time, distinguishing plain numbers from unit-carrying weights:

• Adding or subtracting a weight and a unit-less number is a compile error (tm.self + 5 — write tm.self + 5kg, or use a unit pair).
• Multiplying a weight by a weight is a compile error (kg² has no meaning).
• Dividing a plain number by a weight is a compile error.
• Assigning a unit-less number to a weight target (tm.self, tm.<exercise>) is a compile error.
• Comparing a weight to a plain number produces a warning, not an error.

Runtime caveats

These rules are enforced when the app evaluates your hooks. A hook can be syntactically valid yet silently do nothing if it ignores them.

• Day and week hooks cannot change a training max. tm.self only has meaning in an exercise's context, so any tm write from a day- or week-level hook is ignored (with a warning). Use state to accumulate across a day or week, then act at the exercise level.
• Training-max changes are capped at ±20% of the current value in a single evaluation. A larger requested change is clamped to the cap.
• Big TM moves aren't applied silently. A TM increase within one normal step (≤ 5 kg / ≤ 10 lb) applies automatically. A larger increase, or any decrease, is held for you to confirm on the workout summary rather than applied behind your back.
• A broken hook never breaks your workout. If a hook fails to parse or is rejected, evaluation degrades to "no mutation" — your session completes normally with no changes.

Deload weeks

On a deload week, on_complete hooks are suppressed by default so a back-off week doesn't trigger progression. on_set still runs. Re-enable on_complete with hooks: enabled at the week (or day) level:

A real example

This is the 5/3/1 main-lift progression: on the week-3 AMRAP top set, if you hit at least one rep, bump the training max by the unit-correct amount.

For the full grammar, see the language reference.