brighterscript 1.0.0-alpha.5 → 1.0.0-alpha.51

package/dist/SymbolTable.d.ts

@@ -1,67 +1,186 @@
-import type { Range } from './astUtils';
 import type { BscType } from './types/BscType';
+import type { ExtraSymbolData, GetTypeOptions } from './interfaces';
+import { CacheVerifier } from './CacheVerifier';
+import type { ReferenceType } from './types/ReferenceType';
+import type { UnionType } from './types/UnionType';
+import { SymbolTypeFlag } from './SymbolTypeFlag';
+import type { UninitializedType } from './types/UninitializedType';
 /**
  * Stores the types associated with variables and functions in the Brighterscript code
  * Can be part of a hierarchy, so lookups can reference parent scopes
  */
-export declare class SymbolTable {
-    private parent?;
-    constructor(parent?: SymbolTable | undefined);
+export declare class SymbolTable implements SymbolTypeGetter {
+    name: string;
+    constructor(name: string, parentProvider?: SymbolTableProvider);
     /**
      * The map of symbols declared directly in this SymbolTable (excludes parent SymbolTable).
      * Indexed by lower symbol name
      */
     private symbolMap;
+    private parentProviders;
+    private cacheToken;
+    private typeCache;
     /**
-     * Get list of symbols declared directly in this SymbolTable (excludes parent SymbolTable).
+     * Used to invalidate the cache for all symbol tables.
+     *
+     * This is not the most optimized solution as cache will be shared across all instances of SymbolTable across all programs,
+     * but this is the easiest way to handle nested/linked symbol table cache management so we can optimize this in the future some time...
      */
-    get ownSymbols(): BscSymbol[];
+    static cacheVerifier: CacheVerifier;
+    static referenceTypeFactory: (memberKey: string, fullName: any, flags: SymbolTypeFlag, tableProvider: SymbolTypeGetterProvider) => ReferenceType;
+    static unionTypeFactory: (types: BscType[]) => UnionType;
+    static uninitializedTypeFactory: () => UninitializedType;
     /**
-     * Sets the parent table for lookups
-     *
-     * @param [parent]
+     * Push a function that will provide a parent SymbolTable when requested
+     */
+    pushParentProvider(provider: SymbolTableProvider): () => void;
+    /**
+     * Pop the current parentProvider
      */
-    setParent(parent?: SymbolTable): void;
+    popParentProvider(): void;
+    /**
+     * The parent SymbolTable (if there is one)
+     */
+    get parent(): SymbolTable | undefined;
+    private siblings;
+    /**
+     * Add a sibling symbol table (which will be inspected first before walking upward to the parent
+     */
+    addSibling(sibling: SymbolTable): () => void;
+    /**
+     * Remove a sibling symbol table
+     */
+    removeSibling(sibling: SymbolTable): void;
+    /**
+     * Does the order of symbols in this symbol table matter?
+     * Normally, this would only be for symbol tables referencing symbols declared within a function
+     */
+    isOrdered: boolean;
+    pocketTables: PocketTable[];
+    addPocketTable(pocketTable: PocketTable): () => void;
+    private isPocketTable;
+    private getCurrentPocketTableDepth;
+    getStatementIndexOfPocketTable(symbolTable: SymbolTable): number;
+    private complementsTables;
+    /**
+     * This table complements this other table
+     * Eg. This is an else branch, it complements a then branch
+     */
+    complementOtherTable(otherTable: SymbolTable): void;
+    clearSymbols(): void;
     /**
      * Checks if the symbol table contains the given symbol by name
      * If the identifier is not in this table, it will check the parent
      *
      * @param name the name to lookup
-     * @param searchParent should we look to our parent if we don't have the symbol?
+     * @param bitFlags flags to match (See SymbolTypeFlags)
      * @returns true if this symbol is in the symbol table
      */
-    hasSymbol(name: string, searchParent?: boolean): boolean;
+    hasSymbol(name: string, bitFlags: SymbolTypeFlag): boolean;
     /**
      * Gets the name/type pair for a given named variable or function name
      * If the identifier is not in this table, it will check the parent
      *
      * @param  name the name to lookup
-     * @param searchParent should we look to our parent if we don't have the symbol?
+     * @param bitFlags flags to match
      * @returns An array of BscSymbols - one for each time this symbol had a type implicitly defined
      */
-    getSymbol(name: string, searchParent?: boolean): BscSymbol[];
+    getSymbol(name: string, bitFlags: SymbolTypeFlag, additionalOptions?: GetSymbolAdditionalOptions): BscSymbol[];
+    private augmentSymbolResultsWithPocketTableResults;
+    private getSymbolDataFromPocketTables;
     /**
      * Adds a new symbol to the table
-     * @param name
-     * @param  type
      */
-    addSymbol(name: string, range: Range, type: BscType): void;
+    addSymbol(name: string, data: ExtraSymbolData, type: BscType, bitFlags: SymbolTypeFlag): void;
     /**
-     * Gets the type for a symbol
-     * @param name the name of the symbol to get the type for
-     * @param searchParent should we look to our parent if we don't have the symbol?
-     * @returns The type, if found. If the type has ever changed, return DynamicType. If not found, returns UninitializedType
+     * Removes a new symbol from the table
      */
-    getSymbolType(name: string, searchParent?: boolean): BscType;
+    removeSymbol(name: string): void;
+    getSymbolTypes(name: string, options: GetSymbolTypeOptions, sortByStatementIndex?: boolean): TypeCacheEntry[];
+    getSymbolType(name: string, options: GetSymbolTypeOptions): BscType;
+    isSymbolTypeInstance(name: string): boolean;
     /**
-     * Adds all the symbols from another table to this one
-     * It will overwrite any existing symbols in this table
-     * @param symbolTable
+     * Adds all the symbols from another table to this one.
+     * Source symbols are shared by reference (not cloned) since BscSymbol is treated as immutable.
+     * The destination still owns its own array per key, so subsequent addSymbol calls on either
+     * table do not leak across.
      */
     mergeSymbolTable(symbolTable: SymbolTable): void;
+    mergeNamespaceSymbolTables(symbolTable: SymbolTable): (() => void)[];
+    /**
+     * Get list of symbols declared directly in this SymbolTable (excludes parent SymbolTable).
+     */
+    getOwnSymbols(bitFlags: SymbolTypeFlag): BscSymbol[];
+    private cachedCircularReferenceCheck;
+    private hasCircularReferenceWithAncestor;
+    /**
+     * Get list of all symbols declared in this SymbolTable (includes parent SymbolTable).
+     */
+    getAllSymbols(bitFlags: SymbolTypeFlag): BscSymbol[];
+    private resetTypeCache;
+    getCachedType(name: string, options: GetTypeOptions): TypeCacheEntry;
+    setCachedType(name: string, cacheEntry: TypeCacheEntry, options: GetTypeOptions): Map<string, TypeCacheEntry>;
+    private getCacheKey;
+    /**
+     * Serialize this SymbolTable to JSON (useful for debugging reasons)
+     */
+    private toJSON;
+    private sortSymbolsByAssignmentOrderInPlace;
+    private getPossiblePocketTables;
+    private getSymbolLookupFilter;
 }
+/**
+ * A symbol entry stored in a SymbolTable.
+ * Treated as immutable once added: range and type must not be reassigned, and the object
+ * may be shared by reference across multiple symbol tables (e.g. via mergeSymbolTable).
+ */
 export interface BscSymbol {
     name: string;
-    range: Range;
+    data: ExtraSymbolData;
+    type: BscType;
+    flags: SymbolTypeFlag;
+}
+export interface BscSymbolWithSource extends BscSymbol {
+    comesFromAncestor: boolean;
+}
+export interface SymbolTypeGetter {
+    name: string;
+    getSymbolType(name: string, options: GetSymbolTypeOptions): BscType;
+    setCachedType(name: string, cacheEntry: TypeCacheEntry, options: GetSymbolTypeOptions): any;
+    addSibling(symbolTable: SymbolTable): any;
+}
+/**
+ * A function that returns a symbol table.
+ */
+export declare type SymbolTableProvider = () => SymbolTable;
+/**
+ * A function that returns a symbol types getter - smaller interface used in types
+ */
+export declare type SymbolTypeGetterProvider = () => SymbolTypeGetter;
+export interface GetSymbolTypeOptions extends GetTypeOptions {
+    fullName?: string;
+    tableProvider?: SymbolTableProvider;
+}
+export interface TypeCacheEntry {
     type: BscType;
+    data?: ExtraSymbolData;
+    flags?: SymbolTypeFlag;
+}
+export interface PocketTable {
+    table: SymbolTable;
+    /**
+     * The index of the statement that contains this table within its parent block
+     */
+    index: number;
+    /**
+     * Will the code this pocket table represents always be executed?
+     * Eg. Conditional Compile blocks will always be executed because only valid #if blocks are validated
+     */
+    willAlwaysBeExecuted?: boolean;
+}
+export interface GetSymbolAdditionalOptions {
+    ignoreParentsAndSiblings?: boolean;
+    precedingAssignmentIndex?: number;
+    maxStatementIndex?: number;
+    depth?: number;
 }