LineExecutionContext
Defined in: packages/engine/src/vm/VM.ts:288
Per-line execution context, threaded optionally through
executeBytecode down to CALL_PLUGIN’s plugin-function handlers
(see vm/VMBuiltins.ts’s pluginFunctionRegistry).
Exists so a package can implement cross-line features (prev, line<N>,
range/above aggregation. See packages/lines/) without every other
plugin function having to care: it’s optional, and every existing
handler ignores it unchanged. Before this, a plugin function’s only
input was its own call-site arguments, no line number, no access to
any other line’s cached result. getLineResult/isLineBoundary are
both undefined when there’s no real document (e.g.
ExpressionEngine.evaluateExpression()’s single-expression path, which
uses lineIndex = -1 as its existing “no document” sentinel), a
plugin function needing document access must check for that itself
and return a clear error, never silently treat it as line 0.
Properties
Section titled “Properties”calendar?
Section titled “calendar?”optional calendar?: CalendarBackend;Defined in: packages/engine/src/vm/VM.ts:320
The calendar backend this engine computes dates with (EngineContext.calendar).
A plugin function that reads or steps a date computes through it, so the
date it answers agrees with the one the VM’s own opcodes would produce.
Absent means the Date backend; calendarOf() in
calendar/DateCalendar.ts resolves either case.
evaluateLineWithBinding?
Section titled “evaluateLineWithBinding?”optional evaluateLineWithBinding?: (lineNumber, variable, bound, symbolicTolerant) => Value;Defined in: packages/engine/src/vm/VM.ts:368
Re-evaluate another line’s already-compiled expression with variable
bound to bound for that one evaluation, without disturbing the
document’s own value for it. This is the primitive goal seek
(packages/goalseek/) drives: binding a numeric candidate probes the
relationship, binding a symbolic placeholder (with symbolicTolerant)
reads it back in closed form. Returns an error Value when there is no
document, the line is not a plain expression ready to run, or its
re-evaluation itself faults. The binding is a call frame, so it shadows
the document’s value exactly the way a function parameter does and is
gone the moment the probe returns.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
lineNumber | number |
variable | string |
bound | Value |
symbolicTolerant | boolean |
Returns
Section titled “Returns”getLineCount?
Section titled “getLineCount?”optional getLineCount?: () => number;Defined in: packages/engine/src/vm/VM.ts:305
How many lines the document has now; absent when there is no document.
A form that declares a span before reading it (see noteLineRead) needs
to know where the document ends: a range written as line 1 : line 3000000 has no line to read past the last one, and declaring three
million positions that exist nowhere cost the heap for nothing. The
walk that reads the span already stops at the first line it cannot use.
Asked for rather than copied, because one context serves a document for as long as it is open: a count taken when the context was built was the count before the last insert, and a range declared under it stopped a line short.
Returns
Section titled “Returns”number
getLineReads?
Section titled “getLineReads?”optional getLineReads?: (lineNumber) => string[] | undefined;Defined in: packages/engine/src/vm/VM.ts:355
The variables another line’s expression reads, by 1-based line number, or
undefined when the line has no evaluated expression (forward reference,
out of range, or markdown). Goal seek (packages/goalseek/) uses it to
refuse up front when the variable it was asked to vary is one the target
line never reads, rather than searching a relationship that cannot move.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
lineNumber | number |
Returns
Section titled “Returns”string[] | undefined
getLineResult?
Section titled “getLineResult?”optional getLineResult?: (lineNumber) => Value | undefined;Defined in: packages/engine/src/vm/VM.ts:322
Look up another line’s cached result by 1-based line number. undefined = not evaluated yet (or out of range), distinct from a line that evaluated to an actual undefined-like Value, which can’t happen (every Value type has a concrete representation).
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
lineNumber | number |
Returns
Section titled “Returns”Value | undefined
getLineText?
Section titled “getLineText?”optional getLineText?: (lineNumber) => string | undefined;Defined in: packages/engine/src/vm/VM.ts:390
The RAW markdown text of line lineNumber (1-based), or undefined
when there is no real document or the line is out of range. Distinct
from getLineResult, which returns a line’s evaluated Value: a
markdown table’s rows are skipped by the evaluator and hold no result,
so reading a column as data has to go back to the source text. Backs
the tables package (packages/tables/), which walks upward from the
current line to find the nearest table and read one of its columns.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
lineNumber | number |
Returns
Section titled “Returns”string | undefined
getTaggedLines?
Section titled “getTaggedLines?”optional getTaggedLines?: (tag) => readonly number[] | undefined;Defined in: packages/engine/src/vm/VM.ts:345
The 1-based positions of the lines carrying #tag, ascending, or
undefined when this path keeps no index and the caller should walk the
document itself.
total of #tag used to look at every line of the document, so a notepad
of tagged amounts and totals cost aggregates x lines per pass. Both
document paths maintain an index instead, and answer from it here.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
tag | string |
Returns
Section titled “Returns”readonly number[] | undefined
goalSeekMaxIterations?
Section titled “goalSeekMaxIterations?”optional goalSeekMaxIterations?: number;Defined in: packages/engine/src/vm/VM.ts:380
The hard ceiling on goal seek’s bisection steps, from
config.vm.maxGoalSeekIterations. Carried on the context so the search,
which runs as a plugin function with no other view of engine config, is
bounded by the host’s configured limit rather than a hardcoded one.
isLineBoundary?
Section titled “isLineBoundary?”optional isLineBoundary?: (lineNumber) => boolean;Defined in: packages/engine/src/vm/VM.ts:347
Whether line lineNumber is a blank line or a # heading, the stopping condition for “total above”/“sum above”/“average above” aggregation.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
lineNumber | number |
Returns
Section titled “Returns”boolean
lineIndex
Section titled “lineIndex”lineIndex: number;Defined in: packages/engine/src/vm/VM.ts:290
1-based current line number, or -1 when there is no real document (see class doc above).
networkEnabled?
Section titled “networkEnabled?”optional networkEnabled?: boolean;Defined in: packages/engine/src/vm/VM.ts:312
Whether this engine may fetch live data (network.enabled). A plugin
function that reads a resolver’s cache uses it to say “live data is
switched off” when the cache is empty, rather than the “not preflighted”
message that describes a different fault. Absent means enabled.
noteLineRead?
Section titled “noteLineRead?”optional noteLineRead?: (lineNumber) => void;Defined in: packages/engine/src/vm/VM.ts:335
Say that this line is about to read lineNumber, before reading it.
A form that reads several lines stops at the first it cannot use, so the lines after that one are never read and, if reading were the only way the dependency graph learned of a read, never recorded. A cycle that closes through one of those lines was then invisible from scratch and visible from a history that had once read the whole span, and the two paths disagreed about whether the line was on a cycle at all. A form declares its whole span through this first, so what the graph knows does not depend on how far the form got. Absent where there is no document.
Parameters
Section titled “Parameters”| Parameter | Type |
|---|---|
lineNumber | number |
Returns
Section titled “Returns”void