Module run 

Running a macro.

1. Gate: every step’s command goes through macro_policy. Denied commands stop the macro before anything runs; commands that touch files must be listed in the macro’s permissions; a macro from a file someone else made, or one that touches files, runs only once the person approves it (once per macro content, for the session).
2. Inputs: each declared input is bound to a range (given, its default, or the selection) and checked against its shape and column types, with messages that name the cells.
3. Footprint: unless the macro may overwrite, it first runs on the real workbook in dry-run mode, the changes are compared with CellStore::diff, and everything is put back. Cells it would write outside its inputs that already hold data are conflicts, handled by the output rule: ask, fail, overwrite, or shift the data down or right (and check again). The footprint can miss a write (a dry run stops early at a file step or Solver, and RAND or NOW can send the run another way than the dry run), so the run also checks each step as it goes.
4. Run: one undo step (Session::grouped); an error at any step rolls everything back and names the step.

The steps run on a small machine with an explicit frame stack, so the debugger can stop between any two steps and pick up again on a later frame.

Structs

Begun

A macro that passed its checks and is about to run.

Footprint

What a macro would change, from a dry run on the real workbook.

Machine

A macro run in progress: which step is next, and what has run.

Prepared

A macro ready to run: its inputs bound and checked, its output anchor resolved.

SheetFootprint

The cells a macro would write on one sheet, outside its inputs.

StepError

Where and why a step failed.

Stopwatch

A stopwatch for the time limit. Instant::now traps on wasm, so there it measures nothing.

Constants

DEFAULT_TIME_LIMIT_MS

How long a run may take, in milliseconds. The web build has no clock; there only the step limit applies.

MAX_EXECUTED_STEPS

The most steps one run executes (counting each pass through a Repeat).

MAX_INPUT_CELLS

The most cells an input may have for its content to be checked.

MAX_PARAM_BYTES

The most bytes of parameters one run passes to its commands, all steps together: on the web build, where there is no clock, this and the step limit bound the work a run does.

Functions

approve

Approves the macro for this session when approve is set, or asks (an EngineError::Approve) when it needs approval it doesn’t have.

begin

The checks before a run, on the active workbook: the macro exists, the policy allows it, the person approved it if it needs that, and its inputs are right.

check

macro.check: what running the macro would do, without changing anything.

check_params

Refuses run parameters that would otherwise be ignored: an input the macro doesn’t have, an input given as something other than reference text, onConflict, overwrite, approve or timeLimit of the wrong kind, and an output that isn’t reference text of at most MAX_MACRO_REF characters (null counts as not given).

footprint

Runs the macro in dry-run mode on its workbook, puts everything back, and says what it would change. The dry run spends from run’s budget: its clock and time limit, its steps and the bytes of parameters it passed.

gate

Checks every enabled step against the policy: denied commands and undeclared file access are errors; otherwise returns what the person must approve (empty when nothing).

make_way

The footprint check and the output rule, inside the run’s undo group: an error when the macro would fail or write over data it may not, after shifting the data if the rule says so. Returns the machine for the run and whether it shifted. The dry runs count towards the run’s time limit.

prepare

Binds the macro’s inputs on the active document (given: {"Input": "B2:D9"}, or a reference for the first input) and checks them. Errors list every problem found.

rolled_back

What a run that rolled back leaves: “Nothing was changed.”, or the files it wrote before.

run

Runs macro name on the active workbook: {inputs?, onConflict?, overwrite?, approve?, timeLimit?} (see macro.run).

Type Aliases

Bound

An input bound to a range: name, where, whether its first row is a header.