Lens

View source
loreline.Lens (Class)

Utility class for analyzing Loreline scripts without executing them. Provides methods for finding nodes, variables, references, etc.

Instance Members

getNodeById(id: NodeId): Null<Node>
Name Type
id NodeId
Returns
Null<Node>
getNodeAtPosition(pos: Position): Null<Node>

Gets the node at the given position

Name Type Description
pos Position Position to check
Returns Description
Null<Node> Most specific node at that position, or null if none found
getClosestNodeAtOrBeforePosition(pos: Position): Null<Node>

Gets the closest node before or at the given position

Name Type Description
pos Position Position to check
Returns Description
Null<Node> Most specific node at that position or before, or null if none found
getNodesOfType(nodeType: Class<getNodesOfType.T>, ?includeImported: Bool = false): Array<getNodesOfType.T>

Gets all nodes of a specific type

Name Type Default Description
nodeType Class<getNodesOfType.T> Class type to find
includeImported Bool false
Returns Description
Array<getNodesOfType.T> Array of matching nodes
getDialogueSpeakers(node: Node): Array<String>

Collects the unique names of all characters that speak in a dialogue anywhere within the given node's subtree (including dialogues nested in choices, if branches, alternatives, etc.).

Name Type Description
node Node Root of the subtree to scan
Returns Description
Array<String> Unique speaker names, in first-seen order
getParentNode(node: Node): Null<Node>

Gets the parent node of a given node

Name Type Description
node Node Child node
Returns Description
Null<Node> Parent node or null if none found
getFirstParentOfType(node: Node, type: Class<getFirstParentOfType.T>): Null<getFirstParentOfType.T>

Gets the first parent node matching the given type

Name Type Description
node Node Child node
type Class<getFirstParentOfType.T>
Returns Description
Null<getFirstParentOfType.T> Parent node or null if none found
getNodeFilePath(node: Node, rootPath: String): String

Returns the file path of the file containing the given node. Walks up the parent chain through NImportStatement nodes to resolve the full path. Returns rootPath if the node is in the root file.

Name Type
node Node
rootPath String
Returns
String
getNodeAncestorFilePaths(node: Node): Array<String>

Returns the chain of file paths from the node's own source file up to the root script, with each Loreline extension stripped. Used by the interpreter for hierarchical translation fallback through the import ancestor chain.

The order is most-specific first, root last:

  • node in root.lor -> ["."]
  • node in imports/foo.lor (imported by root) -> ["imports/foo", "."]
  • node in imports/bar.lor (imported by foo.lor) -> ["imports/bar", "imports/foo", "."]
Name Type
node Node
Returns
Array<String>
getNodeRelativeFilePath(node: Node): String

Returns the path of the node's source file relative to the root script, with any Loreline extension (.lor/.lor.txt) stripped.

  • Returns "." for nodes in the root script.
  • Returns the import chain path joined and normalized for nodes in imported files (e.g. "imports/foo", "../bar"). Used by the interpreter to look up scoped translation keys.
Name Type
node Node
Returns
String
getImportedPaths(rootPath: String): Array<String>
Name Type
rootPath String
Returns
Array<String>
resolveArrayAccess(access: NArrayAccess): Null<Node>
Name Type
access NArrayAccess
Returns
Null<Node>
resolveAccess(access: NAccess): Null<Node>

Resolves an identifier access to its corresponding node in the AST. Resolution follows the same priority order as the interpreter:

  1. State fields in current scope and parent beats
  2. Top-level state fields
  3. Top-level character declarations
  4. Beat declarations
Name Type Description
access NAccess The access expression to resolve
Returns Description
Null<Node> The referenced node if found, null otherwise
findBeatFromAccess(access: NAccess): Null<NBeatDecl>

Finds and returns the beat declaration referenced by the given call. This method searches through the beat declarations to find a match based on the call's fields.

Name Type
access NAccess
Returns Description
Null<NBeatDecl> The referenced beat declaration if found, null otherwise
findBeatParamFromAccess(access: NAccess): Null<AnonStruct>

Finds the beat parameter referenced by the given bare access, if any. Walks the enclosing beats from innermost to outermost (matching the runtime scope precedence) and returns the first parameter whose name matches the access.

Name Type Description
access NAccess The access to resolve
Returns Description
Null The matching parameter and its owning beat, or null
findCallArgument(node: Node): Null<AnonStruct>

When the given node is (part of) an argument of a call, beat call, transition or insertion, returns the owner node and the argument index. Only expression chains that terminate directly in an args array count; the call target itself is not an argument.

Name Type Description
node Node The node to check (typically the hovered node)
Returns Description
Null The owner node and argument index, or null
findBeatFromTransition(transition: NTransition): Null<NBeatDecl>

Finds and returns the beat declaration referenced by the given transition. This method searches through the beat declarations to find a match based on the transition's fields.

Name Type Description
transition NTransition The transition object containing the reference to search for
Returns Description
Null<NBeatDecl> The referenced beat declaration if found, null otherwise
findBeatFromInsertion(insertion: NInsertion): Null<NBeatDecl>

Finds and returns the beat declaration referenced by the given insertion. This method searches through the beat declarations to find a match based on the insertion's fields.

Name Type Description
insertion NInsertion The insertion object containing the reference to search for
Returns Description
Null<NBeatDecl> The referenced beat declaration if found, null otherwise
findBeatByPathFromNode(path: String, node: Node): Null<NBeatDecl>
Name Type
path String
node Node
Returns
Null<NBeatDecl>
isTopLevelNode(node: Node): Bool
Name Type
node Node
Returns
Bool
findTopLevelBeatFromNode(node: Node): Null<NBeatDecl>
Name Type
node Node
Returns
Null<NBeatDecl>
findBeatByNameFromNode(name: String, node: Node): Null<NBeatDecl>
Name Type
name String
node Node
Returns
Null<NBeatDecl>
findCharacterFromDialogue(dialogue: NDialogueStatement): Null<NCharacterDecl>

Finds and returns the character declaration referenced by the given dialogue statement. This method searches through the character declarations to find a match based on the dialogue's character name.

Name Type Description
dialogue NDialogueStatement The dialogue statement containing the character reference
Returns Description
Null<NCharacterDecl> The referenced character declaration if found, null otherwise
findCharacterByNameFromNode(name: String, node: Node): Null<NCharacterDecl>
Name Type
name String
node Node
Returns
Null<NCharacterDecl>
findFunctionByNameFromNode(name: String, node: Node): Null<NFunctionDecl>
Name Type
name String
node Node
Returns
Null<NFunctionDecl>
getVisibleCharacters(): Array<NCharacterDecl>
Returns
Array<NCharacterDecl>
getVisibleFunctions(): Array<NFunctionDecl>
Returns
Array<NFunctionDecl>
getVisibleStateFields(fromNode: Node): Array<NObjectField>

Gets all state fields visible from a given position. This includes fields from both temporary and permanent states.

Name Type
fromNode Node
Returns
Array<NObjectField>
getVisibleBeats(fromNode: Node): Array<NBeatDecl>

Gets all beat declarations available from a given position. This includes both top-level beats and nested beats that are in scope.

Name Type
fromNode Node
Returns
Array<NBeatDecl>
getAllTags(): Array<String>

Gets all unique tags used in the script.

Returns Description
Array<String> Array of unique tag strings
countTags(): Map

Count every occurence of tags (hash comments)

Returns Description
Map Map of tag counts
findOutboundBeats(beatDecl: NBeatDecl): Array<Reference<NBeatDecl>>

Find all beats that can be reached from a given beat through transitions or calls.

Name Type Description
beatDecl NBeatDecl The beat declaration to analyze
Returns Description
Array<Reference<NBeatDecl>> Array of references to reachable beats
findReferencesToBeat(beatDecl: NBeatDecl): Array<Reference<NBeatDecl>>

Finds all nodes that reference a specific beat declaration.

Name Type Description
beatDecl NBeatDecl The beat declaration to find references to
Returns Description
Array<Reference<NBeatDecl>> Array of references to this beat
findModifiedStateFields(beatDecl: NBeatDecl): Array<Reference<NObjectField>>

Finds all state fields that are modified within a given beat

Name Type Description
beatDecl NBeatDecl The beat declaration to analyze
Returns Description
Array<Reference<NObjectField>> Array of references to modified state fields
findReadStateFields(beatDecl: NBeatDecl): Array<Reference<NObjectField>>

Finds all state fields that are read/accessed within a given beat

Name Type Description
beatDecl NBeatDecl The beat declaration to analyze
Returns Description
Array<Reference<NObjectField>> Array of references to read state fields
findBeatCharacters(beatDecl: NBeatDecl): Array<Reference<NCharacterDecl>>

Find all characters that have a presence in a given beat through:

  • Field access to character state
  • Dialogue statements
Name Type Description
beatDecl NBeatDecl The beat declaration to analyze
Returns Description
Array<Reference<NCharacterDecl>> Array of references to characters involved in the beat
findModifiedCharacterFields(beatDecl: NBeatDecl): Array<Reference<NObjectField>>

Finds all character fields that are modified within a given beat

Name Type Description
beatDecl NBeatDecl The beat declaration to analyze
Returns Description
Array<Reference<NObjectField>> Array of references to modified character fields
findReadCharacterFields(beatDecl: NBeatDecl): Array<Reference<NObjectField>>

Finds all character fields that are read/accessed within a given beat

Name Type Description
beatDecl NBeatDecl The beat declaration to analyze
Returns Description
Array<Reference<NObjectField>> Array of references to read character fields
traverse(node: Node, callback: Function): Void
Name Type
node Node
callback Function
getFuncLorscript(func: NFunctionDecl): FuncLorscript
Name Type
func NFunctionDecl
Returns
FuncLorscript
getLorscriptExpr(func: NFunctionDecl, pos: Position): loreline.lorscript.Expr
Name Type
func NFunctionDecl
pos Position
Returns
loreline.lorscript.Expr
resolveLorscriptAccess(func: NFunctionDecl, expr: loreline.lorscript.Expr): Null<Node>
Name Type
func NFunctionDecl
expr loreline.lorscript.Expr
Returns
Null<Node>
isLorscriptExpr(input: Any): Bool
Name Type
input Any
Returns
Bool
getLorscriptCompletion(func: NFunctionDecl, pos: Position): LorscriptCompletion
Name Type
func NFunctionDecl
pos Position
Returns
LorscriptCompletion
resolveAccessInFunction(func: NFunctionDecl, pos: Position): Null<Node>
Name Type
func NFunctionDecl
pos Position
Returns
Null<Node>
new(script: Script): Void
Name Type
script Script

Private Members

script: Script

The script being analyzed

nodesById: NodeIdMap<Node>

Map of all nodes by their unique ID

parentNodes: NodeIdMap<Node>

Map of node IDs to their parent nodes

childNodes: NodeIdMap<Array<Node>>

Map of node IDs to their child nodes

lorscriptFunctions: NodeIdMap<FuncLorscript>
initialize(): Void

Initialize all the lookups and analysis data

findStateField(access: NAccess): Null<NObjectField>

Find the state field being accessed by a field access expression

Name Type Description
access NAccess The field access to analyze
Returns Description
Null<NObjectField> The matching state field, if any