Skip to content
Apiary

Internal defined names

Apiary stores some extra formulas in a workbook for its internal use, as ordinary DefinedName objects distinguished by a reserved prefix on their id. There are two kinds:

  • A cached formula (__gridcf__) is the result of a formula evaluated by Model.runFormula. A repeated call returns the stored value, and because the entry sits in the dependency graph, recalculation keeps that value current as the cells it reads change.
  • An extracted subexpression (__gridef__) is a subexpression that several formulas repeat, hoisted out of them by the optimizer so that it is evaluated only once per recalculation, and reused by each formula containing it. The optimizer runs as a workbook is added to the model (Model.fromJSF, Model.addWorkbook or Model.attachWorkbook), unless extractExpressions: false or readOnly: true is passed. It affects only the evaluation of those formulas; the cell’s formula text is unchanged.

Working with a workbook that has them

Section titled “Working with a workbook that has them”

DefinedName.isInternal reports whether a name is one of these, and DefinedName.isExtractedSubexpression distinguishes the two kinds. Treat internal names as read-only, and leave them out when listing a workbook’s defined names for a user: they are not part of the document. Export leaves them out already, so they do not appear in JSF or XLSX output. They do survive serializeModel, which snapshots the live model rather than exporting a document.

An edit that rewrites a formula (a cell move, or a row or column insert or delete) undoes the optimization: the formula goes back to computing the repeated subexpression itself, at the same value. The optimization currently happens only when a workbook is added, so nothing re-extracts the subexpression afterwards.