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: null | CellItem

Cell object whose formula is being evaluated, or null

cellId?

optional cellId: null | string

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: () => null | Table

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

Returns

null | Table

getWorkbookByKey()

getWorkbookByKey: (key) => undefined | Workbook

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

undefined | Workbook

isDirtyFormulaCell()?

optional isDirtyFormulaCell: (cell) => boolean

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

Parameters

cell

null | CellItem

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: null | (event) => void

Callback to report metrics

mode

mode: ModeBit

profile?

optional profile: null | Profile

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) => undefined | ASTNode

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

undefined | ASTNode

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?

null | string

Returns

FormulaError | DefinedName

resolveSheet()

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

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?

null | string

workbookName?

null | string

Returns

null | WorkSheet

resolveTable()

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

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?

null | string

Returns

null | Table

resolveWorkbook()

resolveWorkbook: (name?) => undefined | Workbook

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?

null | string

Returns

undefined | Workbook

sheetName?

optional sheetName: null | string

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: null | string

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

writeState()

writeState: () => ModelStateTree

Returns

ModelStateTree