mirror of
https://github.com/storytold/gridcraft.git
synced 2026-10-29 21:26:48 -06:00
prxnvt
7d31c5a4ed
Opening a workbook accepted a macro whose format version `v` was above MACRO_VERSION. Serde dropped the fields this build doesn't know, and the next save wrote the reduced macro back with `v: 2`, so a newer build would read it as a complete version 2 macro. A version above MACRO_VERSION is now refused by Macro::check_limits, and parse_macro checks the raw `v` before reading the steps. Such a macro takes the existing per-macro path: it is left out with the usual single warning (which now names a newer format), and the rest of the workbook opens. Tests cover JSON and xlsx hidden names, with current and missing versions as controls.
67 lines
3.4 KiB
Markdown
67 lines
3.4 KiB
Markdown
# Macros
|
||
|
||
> **Last updated:** 2026-10-21 · **Change:** major (created: the macro format and storage)
|
||
|
||
GridCraft macros are typed, declarative lists of commands, not VBA. Every step runs a GridCraft
|
||
command (the same ids the ribbon, CLI and MCP use) or one of three bounded control steps. A macro
|
||
declares the inputs it works on.
|
||
|
||
This page describes the macro format and how macros are saved in a workbook. Step parameters
|
||
can hold tokens such as `Input` and `Output`; the engine does not resolve or run them in this
|
||
version.
|
||
|
||
## A macro
|
||
|
||
```json
|
||
{
|
||
"name": "Totals",
|
||
"description": "Adds a total next to the amounts",
|
||
"inputs": [{"name": "Input", "header": true, "cols": [2, 2], "colTypes": ["text", "number"]}],
|
||
"output": {"anchor": "Input.right(2).cell(1,2)", "onConflict": "ask"},
|
||
"steps": [
|
||
{"type": "command", "id": "cell.set", "params": {"cell": "Output", "input": "Total"}},
|
||
{"type": "command", "id": "cell.set", "params": {"cell": "Output.offset(1,0)", "input": "=SUM({{Input.data.col(2)}})"}},
|
||
{"type": "repeat", "over": "Input.data", "of": "rows", "max": 1000, "body": [
|
||
{"type": "if", "cell": "Row.cell(1,2)", "op": "gt", "value": 100,
|
||
"then": [{"type": "command", "id": "home.bold", "params": {"range": "Row"}}]}
|
||
]},
|
||
{"type": "stop", "message": "Done."}
|
||
],
|
||
"permissions": []
|
||
}
|
||
```
|
||
|
||
- **Steps**: `command` (`id`, `params`), `repeat` (each row or column of `over`, at most `max`
|
||
times), `if` (`cell` compared with `value` by `eq`, `ne`, `gt`, `ge`, `lt`, `le`, `empty`,
|
||
`notEmpty` or `contains`; `then` and `else` lists) and `stop` (`message`; `rollback: true`
|
||
undoes the run). Every step can carry `enabled`, `breakpoint` and `note`. The short form
|
||
`{"command": "cell.set", "params": {…}}` is accepted for a command step.
|
||
- **Inputs**: `kind` (`cell` or `range`), `rows` and `cols` as `[min, max]` (0 for no maximum;
|
||
rows exclude the header), `header`, `colTypes` (`number`, `text`, `date`, `bool`, `any`),
|
||
`nonEmpty` and `defaultRef`. A run binds each input to the range it is given, its default, or
|
||
(for the first input) the selection, and refuses with messages that name the cells:
|
||
"Input column 2 (Amount) must hold numbers; C4 holds text."
|
||
- **Limits**: 1,000 macros a workbook, 10,000 steps a macro, and Repeat and If nested 4 deep.
|
||
|
||
## Storage
|
||
|
||
Macros are saved in the workbook: as a field in GridCraft's JSON format, and in xlsx as hidden
|
||
defined names (`_gc_macro_<n>_<k>`, the macro's JSON split into string literals within Excel's
|
||
limits), which other spreadsheet applications keep but do not run.
|
||
|
||
Each macro carries its format version, `v` (1 in this version; a missing `v` reads as 1). When a
|
||
file is opened, a macro that is damaged, over the limits or in a newer format (a `v` above 1) is
|
||
left out with one warning, and the rest of the workbook and its other macros open. A newer
|
||
macro is never read in part, so a save can't write it back with its newer fields missing; a
|
||
macro that was left out is not in the saved file.
|
||
|
||
## Automate scripts and VBA
|
||
|
||
Automate scripts (`automate.recordActions`, `newScript`, `allScripts`, `runScript`,
|
||
`deleteScript`) are an older, separate feature. They keep their commands, parameters, storage
|
||
(`_sc_scripts`) and results, and View › Macros (`view.macros`) still lists them. Macros neither
|
||
read nor change them; a workbook can hold a script and a macro with the same name.
|
||
|
||
A VBA project in an `.xlsm` or `.xltm` file is preserved on save and never run. GridCraft macros
|
||
are stored apart from it.
|