From f66ebd6fb20295cdf322833d1e6f0f16ed9a14b8 Mon Sep 17 00:00:00 2001 From: prxnvt <53838599+prxnvt@users.noreply.github.com> Date: Sun, 25 Oct 2026 03:17:42 -0400 Subject: [PATCH] Docs: debugging macros: actions, start options, the lock and the time limit per action - The start options are those of `macro.run`, refused as it refuses them. - The time limit applies to each debugger action; the step and parameter limits to the whole run. - The lock lists what runs between steps, and says the sheet and selection are put back. - Stop Action ends the run; the debugger is never a step and never recorded. - The answers' fields, including `changedCells`, `shifted`, `wroteFiles` and `message`. --- docs/macros.md | 52 ++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 42 insertions(+), 10 deletions(-) diff --git a/docs/macros.md b/docs/macros.md index 4006096a7..5b9d9be00 100644 --- a/docs/macros.md +++ b/docs/macros.md @@ -62,7 +62,7 @@ The engine has no macro recorder or management commands in this version, and no pass through a Repeat counts), passes its commands at most 256 MB of parameters, all steps together, and takes at most 60 seconds, all three shared by the footprint dry runs and the run itself (`timeLimit` to change the time; the web build has no clock, so there only the step and - parameter limits apply). + parameter limits apply). The debugger gives each of its actions the time limit on its own. ## Tokens @@ -145,15 +145,47 @@ on, as after any recalculation. ## Debugging -`macro.debug {action, …}` with `start` (`name`, `inputs`, `breakpoints`), `step`, `continue`, -`runTo` (`step`: a path), `stop` (`keep: true` keeps the changes) and `state`. `breakpoints` can -be given with any action; `breakpointsOnly: true` makes the list replace the steps' own flags. The -run stays one undo step; while it is open, edits of the workbooks it touched (its own, and any -other its steps changed) are refused with "Finish or stop the macro first", also when another -command makes them (stopping Record Actions saves a script), and so is Automate › Stop Action, -which would roll the run's undo group back under the debugger; `stop` ends the run instead. Other -workbooks stay editable. Each answer gives the next step with its parameters as they would run, the parameters -of the step that just ran, and the cells changed so far. +`macro.debug {action, …}` runs a macro a step at a time. The actions are: + +- `start` with `name` and the options of `macro.run` (`inputs`, `onConflict`, `overwrite`, + `approve`, `timeLimit`), refused as `macro.run` refuses them when they are of the wrong kind. The + checks, the approval and the footprint come first, as for `macro.run`; then the run pauses + before its first step. +- `step` runs the next step; `continue` runs to the next breakpoint or the end; `runTo` (`step`: + a path) runs to that step, stopping at a breakpoint on the way. +- `stop` ends the run: `keep: true` keeps the changes as one undo step, otherwise they are rolled + back. +- `state` answers without running anything (the default while a macro is being debugged). + +`breakpoints` (a list of step paths of the macro, at most 10,000) can be given with any action and +replaces the list set before; `breakpointsOnly: true` makes the list replace the steps' own +breakpoint flags, also when it is given without a list. An unknown action, a breakpoint or `runTo` +path the macro doesn't have, and `keep` or `breakpointsOnly` that isn't `true` or `false` are +refused before anything changes. The time limit applies to each action on its own (`start` with +its dry runs, and each `step`, `continue` or `runTo`); the step and parameter limits apply to the +whole run, counting the dry runs. + +Each answer gives the next step with its parameters as they would run (a Repeat over whole rows or +columns shows the part of the sheet in use, as the run goes over it), the parameters of the step +that just ran, the steps the run has executed (the dry runs not counted), and what the run has +changed in its workbook: `changed` lists at most 500 entries (cell ranges, and sheets added, +deleted or renamed) and `changedCells` counts the changed cells on the sheets it had at the start. `shifted` names the rule that made +room at the start, and `wroteFiles` the files the run wrote, which stay when the run is rolled +back; the answer to a rolled-back run says so in `message`. A run that ends (its last step, a +Stop step, or a failed step, which rolls it back) or is stopped answers with `state` `finished`, +`stopped` or `failed`. + +While a macro is being debugged, its workbook is locked between steps: only `macro.debug`, queries +(commands that only read), commands that look around (`selection.*`, Select All, `sheet.activate`, +`sheet.next` and `sheet.previous`, Go To, Go To Special, Find, Copy and the zoom commands), Switch +Window, Close (which ends the run with its workbook) and Automate › Stop Action run there. +Everything else, undoable or not, saving included, is refused with "Finish or stop the macro +first", also when another command runs it (stopping Record Actions saves a script). Other +workbooks stay editable. The person may look around between steps: before the next step runs, the +debugger puts the active sheet and the selection back where the run left them, so the run goes on +as `macro.run` would run it. A zoom change made meanwhile is part of the run, and is undone with +it. Stop Action rolls the run back and ends it, and its answer names the macro. The debugger runs +on its own, never as a step of a script or macro, and is never recorded. ## Storage