EvaluationContext

Context object for formula evaluation. Historically often called options or opts when passed to spreadsheet functions and other evaluation-related functions.

Properties

allowBoxed?

optional allowBoxed: boolean;

Allow ValueBox values to be returned without unboxing first

---

allowMatrices?

optional allowMatrices: boolean;

false (the default) if a Matrix result should be mapped to a #VALUE! error, true to return it as-is.

---

cell?

optional cell: CellItem | null;

Cell object whose formula is being evaluated, or null

---

cellId?

optional cellId: string | null;

Unprefixed ID (name or A1 address) of the cell containing the formula being evaluated, null if not evaluating a cell formula.

---

checkAllReferences?

optional checkAllReferences: boolean;

---

coerceNullToZero

coerceNullToZero: CoercionMode;

---

collectReferencesFromLambdaDefinitions?

optional collectReferencesFromLambdaDefinitions: boolean;

True if static references should be collected inside lambda definitions. Normally that is not done because the act of defining a lambda does not depend on any values of cells referenced by the lambda (those values will be looked up only when the defined lambda is called). However, when the static dependencies of a lambda call are too tricky to determine because of lambdas returning lambdas, we fall back on recording all references, in the lambda definition and in all arguments of the call to it, and marking them all conditional. That’s done in a sub-context with this property set to true, to tell the reference analysis to descend into lambda definitions.

---

env?

optional env: ReadonlyMap<string, MaybeBoxedFormulaArgument>;

---

evaluateAST()

evaluateAST: (ast, options) => MaybeBoxedFormulaValue;

Evaluate a whole formula, expressed as an AST, in this context. NOTE: this must be a function, not arrow function, and be invoked on an evaluation context, so that it captures the correct this context.

Parameters

ast

ASTRootNode

options

EvaluationContext

Returns

MaybeBoxedFormulaValue

---

evaluateASTNode

evaluateASTNode: FnEvaluateASTNode;

Evaluate an expression, expressed as an AST node, in this context. NOTE: this must be a function, not arrow function, and be invoked on an evaluation context, so that it captures the correct this context.

---

getContextTable()?

optional getContextTable: () => Table | null;

Used to resolve the context table for unprefixed structured references (e.g. =[[#This row], [Column]]).

Returns

Table | null

---

getWorkbookByKey()

getWorkbookByKey: (key) => Workbook | undefined;

Get the workbook with the given dependency-graph key (based uniquely on the workbook name in a case-insensitive way by the wbNameToKey function).

Parameters

key

number

Returns

Workbook | undefined

---

isDirtyFormulaCell()?

optional isDirtyFormulaCell: (cell) => boolean;

Check whether the given cell is in a state considered dirty in the current evaluation context.

Parameters

cell

CellItem | null

Returns

boolean

---

lambdaBindings?

optional lambdaBindings: LambdaBindings;

Bindings of lambda parameter names to unique symbols, and symbols to the arguments for those parameters and their evaluation contexts. The layer of indirection (as opposed to just mapping names directly to arguments) is to ensure the scoping of lambda parameters: they should be visible in nested lambda contexts only if lexically in scope, i.e. LAMBDA(x, LAMBDA(y, x + y)), and not e.g. in LAMBDA(x, OtherLambda(x)) where OtherLambda is defined as LAMBDA(y, x + y) … because in the latter case, the x in OtherLambda refers to the defined name x, not the lambda parameter x of the calling lambda.

---

metricsCallback?

optional metricsCallback: (event) => void | null;

Callback to report metrics

---

mode

mode: ModeBit;

---

profile?

optional profile: Profile | null;

Profiling information

---

rawOutput?

optional rawOutput: boolean;

false (the default) if the result of AST evaluation should be postprocessed (reference resolved, number rounded to 15 decimal places) before returning it; true to return it as-is.

---

recordDependencyUse()?

optional recordDependencyUse: (ref) => void;

Callback to report the use of a dependency in evaluating a formula

Parameters

ref

Reference

Returns

void

---

recurseIntoContextDependentNames?

optional recurseIntoContextDependentNames: boolean;

True if reference analysis should recurse into context-dependent defined names to discover their context-specific dependencies. When a cell references a defined name whose formula is context-dependent (like =INDIRECT("B2")), the actual dependencies depend on the calling context’s sheet. Setting this to true causes reference analysis to recurse into such names and yield their context-specific references, in addition to a nonvalue reference to the name itself.

---

resolveLambdaArgumentAST()?

optional resolveLambdaArgumentAST: (param) => ASTNode | undefined;

Look up an argument expression AST of a lambda call by parameter symbol. This exists in the context of finding references in a specific lambda call.

Parameters

param

LambdaParameterSymbol

Returns

ASTNode | undefined

---

resolveName()

resolveName: (name, sheetName?) =>
  | FormulaError
  | DefinedName;

Get the cell object for the given defined name (matched case-insensitively) in the indicated scope or in this context. If sheetName is given, then only sheet-scoped defined names will be considered, not workbook-scoped defined names. If this context permits cross-workbook name resolution, then a match in the current workbook will be preferred but if no match is found there, then the first match across all workbooks in model order will be returned. If no match is found, #NAME? is returned.

Parameters

name

string

sheetName?

string | null

Returns

| FormulaError | DefinedName

---

resolveSheet()

resolveSheet: (sheetName?, workbookName?) => WorkSheet | null;

Get the sheet with the given name (matched case-insensitively), or the first sheet of the context workbook if no name is given. The context workbook is the default (first) workbook of the model if not evaluating in the context of a specific workbook.

Parameters

sheetName?

string | null

workbookName?

string | null

Returns

WorkSheet | null

---

resolveTable()

resolveTable: (name, workbookName?) => Table | null;

Get the table with the given name (matched case-insensitively) in the context workbook, or if not found there, then in the first workbook in the model that contains a table by this name.

Parameters

name

string

workbookName?

string | null

Returns

Table | null

---

resolveWorkbook()

resolveWorkbook: (name?) => Workbook | undefined;

Get the workbook with the given case-insensitive name, or if no name is given, the context workbook, or the default (first) workbook of the model if not evaluating in the context of a specific workbook.

Parameters

name?

string | null

Returns

Workbook | undefined

---

sheetName?

optional sheetName: string | null;

Name of the sheet containing the reference or formula, null for references in workbook-scoped defined-names, and for formulas in GRID elements

---

singleCell?

optional singleCell: boolean;

True if formulas should be evaluated in single-cell (non-array) mode. Default false.

See

ISO/IEC 29500 section 18.17.2.7, “Single- and Array Formulas”

---

supportedFunctionNames?

optional supportedFunctionNames: Set<string>;

Set of function names supported in GRID (irrespective of mode). Exposed via the evaluation context to dodge a circular import because the CELL function needs this set but is imported by the module that populates and exports it.

---

upToDateState?

optional upToDateState: number;

The up-to-date state of the context workbook after the latest completed recalculation, a non-negative integer.

• Cells with state > upToDateState and state < upToDateState + NUM_STATES are dirty.
• Cells can have state === upToDateState + NUM_STATES during recalculation, as that is the new up-to-date state, to which the workbook’s upToDateState attribute will be raised when recalculation completes.
• Cells cannot have state > upToDateState + NUM_STATES.

---

visitedContextDependentNames?

optional visitedContextDependentNames: Set<string>;

Set of defined name identifiers that have already been visited during context-dependent name recursion. Used to prevent infinite recursion when context-dependent names reference each other (e.g., name1 = ROW() + name2, name2 = ROW() + name1).

---

workbookName

workbookName: string | null;

Name of the workbook containing the reference or formula, null for a GRID element formula

---

writeState()

writeState: () => ModelStateTree;

Returns

ModelStateTree