DocumentReferences

Defined in: packages/engine/src/language/DocumentReferences.ts:308

Reference queries and edits over whole documents, for one engine.

The machinery behind LanguageService’s findReferences, getDefinition, getHover, rename and shiftLineReferences; a host calls those rather than this. Every method takes the document’s full text, reads it the way the engine’s batch pass does, and returns positions or edits without evaluating anything or changing the engine.

Constructors

Constructor

new DocumentReferences(engine): DocumentReferences;

Defined in: packages/engine/src/language/DocumentReferences.ts:310

Parameters

Parameter	Type	Description
engine	ExpressionEngine	The engine whose vocabulary decides what is code: the one the document is evaluated with, or one registered with the same packages.

Returns

DocumentReferences

Methods

findReferences()

findReferences(text, position): VariableReference[];

Defined in: packages/engine/src/language/DocumentReferences.ts:316

Every place the variable at position is named, definitions and reads alike, in document order. Empty when position is not on a variable.

Parameters

Parameter	Type
text	string
position	DocumentPosition

Returns

VariableReference[]

---

getDefinition()

getDefinition(text, position):
  | VariableReference
  | null;

Defined in: packages/engine/src/language/DocumentReferences.ts:332

The definition the variable at position reads: the last one above it, or the occurrence itself where it is a definition. Null when position is not on a variable, or nothing above defines it.

Parameters

Parameter	Type
text	string
position	DocumentPosition

Returns

| VariableReference | null

---

getHover()

getHover(
   text,
   position,
   results?
):
  | VariableHover
  | null;

Defined in: packages/engine/src/language/DocumentReferences.ts:343

The hover for the variable at position: the occurrence, its definition, the defining line’s text, and that line’s value from results. Null when position is not on a variable.

Parameters

Parameter	Type
text	string
position	DocumentPosition
results?	LineResults

Returns

| VariableHover | null

---

rename()

rename(
   text,
   position,
   newName
): RenameResult;

Defined in: packages/engine/src/language/DocumentReferences.ts:372

Rename the variable at position to newName, everywhere it is named and nowhere else.

Refused, with a named reason, when position is not on a variable, the variable is a global, newName is not a name the engine would read as a variable (a keyword, a unit, anything that is not one identifier), the document already uses newName, or an edited line would read differently afterwards. The last is checked by reading each edited line again, so a rename is only returned when every line it touches keeps its structure.

Parameters

Parameter	Type
text	string
position	DocumentPosition
newName	string

Returns

RenameResult

---

shiftLineReferences()

shiftLineReferences(text, change): LineShiftResult;

Defined in: packages/engine/src/language/DocumentReferences.ts:448

The edits that keep every absolute line N reference on the line it meant after change, the way a spreadsheet keeps a cell reference on its row when a row is inserted above it.

text is the document after the change. Its references still carry the numbers they were written with, and these edits bring them up to date:

• A reference to a line that moved is renumbered to where it now stands.
• A reference into a deleted line becomes line deleted, which answers with a named error rather than silently reading whichever line moved up into its place. It is also listed in deleted.
• A range’s ends move independently, as a spreadsheet range’s do: a line inserted inside a range is inside it afterwards, a range loses the lines deleted from it, and only a range with none of its lines left becomes line deleted at both ends.
• The inserted lines themselves are left as written: they were written against the document as it now stands.

Refused when the change does not fit the document.

Parameters

Parameter	Type
text	string
change	LineShift

Returns

LineShiftResult