@spyglassmc/core 0.1.0

package/lib/symbol/SymbolUtil.d.ts

@@ -0,0 +1,407 @@
+/// <reference types="node" />
+import EventEmitter from 'events';
+import { TextDocument } from 'vscode-languageserver-textdocument';
+import type { AstNode } from '../node';
+import type { RangeLike } from '../source';
+import type { AllCategory, Symbol, SymbolLocationBuiltInContributor, SymbolLocationMetadata, SymbolMap, SymbolMetadata, SymbolTable, SymbolUsageType } from './Symbol';
+import { SymbolLocation, SymbolVisibility } from './Symbol';
+export interface LookupResult {
+    /**
+     * The {@link SymbolMap} that contains the symbol. If `symbol` is `undefined`, this property will be the map that could
+     * potentially store the symbol if it's ever created. `undefined` if no such map exists.
+     */
+    parentMap: SymbolMap | undefined;
+    /**
+     * The {@link Symbol} of which `symbol` is a member. If `symbol` is `undefined`, this property will be the symbol that could
+     * potentially store the symbol as a member if it's ever created. `undefined` if no such symbol exists.
+     */
+    parentSymbol: Symbol | undefined;
+    /**
+     * The {@link Symbol} corresponding to the `path`. `undefined` if no such symbol exists.
+     */
+    symbol: Symbol | undefined;
+}
+interface SymbolEvent {
+    symbol: Symbol;
+}
+interface SymbolLocationEvent extends SymbolEvent {
+    type: SymbolUsageType;
+    location: SymbolLocation;
+}
+export interface SymbolUtil {
+    on(event: 'symbolCreated', callbackFn: (data: SymbolEvent) => void): this;
+    on(event: 'symbolAmended', callbackFn: (data: SymbolEvent) => void): this;
+    on(event: 'symbolRemoved', callbackFn: (data: SymbolEvent) => void): this;
+    on(event: 'symbolLocationCreated', callbackFn: (data: SymbolLocationEvent) => void): this;
+    on(event: 'symbolLocationRemoved', callbackFn: (data: SymbolLocationEvent) => void): this;
+    once(event: 'symbolCreated', callbackFn: (data: SymbolEvent) => void): this;
+    once(event: 'symbolAmended', callbackFn: (data: SymbolEvent) => void): this;
+    once(event: 'symbolRemoved', callbackFn: (data: SymbolEvent) => void): this;
+    once(event: 'symbolLocationCreated', callbackFn: (data: SymbolLocationEvent) => void): this;
+    once(event: 'symbolLocationRemoved', callbackFn: (data: SymbolLocationEvent) => void): this;
+    emit(event: 'symbolCreated', data: SymbolEvent): boolean;
+    emit(event: 'symbolAmended', data: SymbolEvent): boolean;
+    emit(event: 'symbolRemoved', data: SymbolEvent): boolean;
+    emit(event: 'symbolLocationCreated', data: SymbolLocationEvent): boolean;
+    emit(event: 'symbolLocationRemoved', data: SymbolLocationEvent): boolean;
+}
+interface DocAndNode {
+    doc: TextDocument;
+    node: AstNode;
+}
+export declare class SymbolUtil extends EventEmitter {
+    #private;
+    /**
+     * @internal
+     */
+    _delayedOps: ((this: void) => unknown)[];
+    /**
+     * @internal
+     */
+    _inDelayMode: boolean;
+    get global(): SymbolTable;
+    constructor(global: SymbolTable, 
+    /** @internal */
+    _currentContributor?: string, 
+    /** @internal */
+    _inDelayMode?: boolean);
+    /**
+     * Build the internal cache of the SymbolUtil according to the current global symbol table.
+     */
+    buildCache(): void;
+    /**
+     * @returns A clone of this SymbolUtil that is in delay mode: changes to the symbol table happened in the clone will
+     * not take effect until the {@link SymbolUtil.applyDelayedEdits} method is called on that clone.
+     *
+     * The clone shares the same reference of the global symbol table and symbol stacks, meaning that after
+     * `applyDelayedEdits` is called, the original SymbolUtil will also be modified.
+     */
+    clone(): SymbolUtil;
+    /**
+     * Apply edits done during the delay mode.
+     */
+    applyDelayedEdits(): void;
+    /**
+     * All symbol locations added in `fn` are associated with the specified `contributor`.
+     *
+     * @param contributor The name of the contributor which will add symbols to the symbol table. See {@link SymbolLocation.contributor}
+     * @param fn All symbols added in this function will be considered as URI bound.
+     * @param keepExisting Default to `false`, indicating existing symbols contributed by the specified contributor will be removed first. Set to `true` to keep them instead.
+     */
+    contributeAs(contributor: SymbolLocationBuiltInContributor, fn: () => unknown): this;
+    contributeAs(contributor: string, fn: () => unknown): this;
+    /**
+     * This is an asynchronous version of {@link contributeAs}.
+     */
+    contributeAsAsync(contributor: SymbolLocationBuiltInContributor, fn: () => PromiseLike<unknown>): Promise<this>;
+    contributeAsAsync(contributor: string, fn: () => PromiseLike<unknown>): Promise<this>;
+    /**
+     * @param
+     * 	- `contributor` - clear symbol locations contributed by this contributor. Pass in `undefined`
+     * 	to select all symbol locations that don't have a contributor.
+     * 	- `uri` - clear symbol locations associated with this URI.
+     * 	- `predicate` - clear symbol locations matching this predicate
+     */
+    clear({ uri, contributor, predicate }: {
+        contributor?: string;
+        uri?: string;
+        predicate?: (this: void, data: SymbolLocationEvent) => boolean;
+    }): void;
+    /**
+     * @param uri Optional. The corresponding {@link SymbolStack} of the file will also be looked up if this is specified.
+     *
+     * @returns A {@link LookupResult}
+     */
+    lookup(category: AllCategory, path: readonly string[], node?: AstNode): LookupResult;
+    lookup(category: string, path: readonly string[], node?: AstNode): LookupResult;
+    /**
+     * @param doc A {@link TextDocument} or a string URI. It is used to both check the visibility of symbols and serve as
+     * the location of future entered symbol usages. If a string URI is provided, all `range`s specified while entering
+     * symbol usages latter will be ignored and seen as `[0, 0)`.
+     *
+     * @throws When the queried symbol belongs to another non-existent symbol, or when no contributor is specified.
+     */
+    query(doc: DocAndNode | TextDocument | string, category: AllCategory, ...path: string[]): SymbolQuery;
+    query(doc: DocAndNode | TextDocument | string, category: string, ...path: string[]): SymbolQuery;
+    getVisibleSymbols(category: AllCategory, uri?: string): SymbolMap;
+    getVisibleSymbols(category: string, uri?: string): SymbolMap;
+    static toUri(uri: DocAndNode | TextDocument | string): string;
+    /**
+     * @see {@link SymbolUtil.trimMap}
+     */
+    trim(table: SymbolTable): void;
+    removeLocationsFromSymbol(symbol: Symbol, predicate: (this: void, data: SymbolLocationEvent) => boolean): void;
+    /**
+     * Enters a symbol into a symbol map. If there is already a symbol with the specified identifier under the map,
+     * it will be amended with the information provided in `addition`. Otherwise, a new symbol with that identifier
+     * will be created.
+     *
+     * @param map The map where this symbol will be entered into.
+     * @param category The category of this symbol.
+     * @param identifier The identifier of this symbol.
+     * @param addition The metadata and usage that will be amended onto this symbol if it already exists, or
+     * to create the symbol if it doesn't exist yet.
+     * @param doc The `TextDocument` where this symbol belongs to.
+     * @param isUriBinding Whether this entering is done by a URI binder or not.
+     *
+     * @returns The created/amended symbol.
+     */
+    enterMap(parentSymbol: Symbol | undefined, map: SymbolMap, category: AllCategory, path: readonly string[], identifier: string, addition: SymbolAddition, doc: TextDocument, contributor: string | undefined): Symbol;
+    enterMap(parentSymbol: Symbol | undefined, map: SymbolMap, category: string, path: readonly string[], identifier: string, addition: SymbolAddition, doc: TextDocument, contributor: string | undefined): Symbol;
+    /**
+     * @returns A {@link LookupResult}
+     */
+    static lookupTable(table: SymbolTable, category: AllCategory, path: readonly string[]): LookupResult;
+    static lookupTable(table: SymbolTable, category: string, path: readonly string[]): LookupResult;
+    /**
+     * @param tables Should be ordered from global to the toppest block.
+     *
+     * @returns A {@link LookupResult}
+     */
+    static lookupTables(tables: SymbolTable[], category: AllCategory, path: readonly string[]): LookupResult;
+    static lookupTables(tables: SymbolTable[], category: string, path: readonly string[]): LookupResult;
+    createSymbol(category: string, parentSymbol: Symbol | undefined, parentMap: SymbolMap, path: readonly string[], identifier: string, addition: SymbolAddition, doc: TextDocument, contributor: string | undefined): Symbol;
+    amendSymbol(symbol: Symbol, addition: SymbolAddition, doc: TextDocument, contributor: string | undefined): void;
+    private amendSymbolMetadata;
+    private amendSymbolUsage;
+    /**
+     * @returns The ultimate symbol being pointed by the passed-in `symbol`'s alias.
+     */
+    resolveAlias(symbol: Symbol | undefined): Symbol | undefined;
+    static filterVisibleSymbols(uri: string | undefined, map?: SymbolMap): SymbolMap;
+    static isTrimmable(symbol: Symbol): boolean;
+    /**
+     * @returns
+     * - For `Block` and `File` visibilities, always `true` as `Symbol`s of these visibilities are validated at the
+     * `SymbolStack` level, instead of here.
+     * - For `Public` visibility, also always `true`, obviously.
+     * - For `Restricted` visibility, // TODO: roots.
+     */
+    static isVisible(symbol: Symbol, uri: string): boolean;
+    static isVisible(symbol: Symbol, uri: string | undefined): boolean | undefined;
+    /**
+     * @returns If the symbol has declarations or definitions.
+     */
+    static isDeclared(symbol: Symbol | undefined): boolean;
+    /**
+     * @returns If the symbol has definitions, or declarations and implementations.
+     */
+    static isDefined(symbol: Symbol | undefined): symbol is Symbol;
+    /**
+     * @returns If the symbol has implementations or definitions.
+     */
+    static isImplemented(symbol: Symbol | undefined): symbol is Symbol;
+    /**
+     * @returns If the symbol has references.
+     */
+    static isReferenced(symbol: Symbol | undefined): symbol is Symbol;
+    /**
+     * @returns If the symbol has type definitions.
+     */
+    static isTypeDefined(symbol: Symbol | undefined): symbol is Symbol;
+    /**
+     * @throws If the symbol does not have any declarations or definitions.
+     */
+    static getDeclaredLocation(symbol: Symbol): SymbolLocation;
+    static forEachSymbolInMap(map: SymbolMap, fn: (symbol: Symbol) => unknown): void;
+    static forEachSymbol(table: SymbolTable, fn: (symbol: Symbol) => unknown): void;
+    static forEachLocationOfSymbol(symbol: Symbol, fn: (data: {
+        type: SymbolUsageType;
+        location: SymbolLocation;
+    }) => unknown): void;
+    static isVisibilityInGlobal(v: SymbolVisibility | undefined): boolean;
+    static areVisibilitiesCompatible(v1: SymbolVisibility | undefined, v2: SymbolVisibility | undefined): boolean;
+}
+interface SymbolAddition {
+    data?: SymbolMetadata;
+    usage?: SymbolAdditionUsage;
+}
+declare type SymbolAdditionUsage = SymbolAdditionUsageWithRange | SymbolAdditionUsageWithNode;
+interface SymbolAdditionUsageBase extends SymbolLocationMetadata {
+    /**
+     * The type of this usage. Use `definition` when the usage consists both a `declaration` and an `implementation`.
+     */
+    type?: SymbolUsageType;
+    /**
+     * The range of the full declaration/implementation of this {@link Symbol}. For example, for the following piece of
+     * nbtdoc code,
+     * ```nbtdoc
+     * 0123456789012345
+     * compound Foo {}
+     * ```
+     *
+     * The `range` for the Symbol `Foo` is `[9, 12)`, while the `fullRange` for it is `[0, 15)`.
+     */
+    fullRange?: RangeLike;
+}
+interface SymbolAdditionUsageWithRange extends SymbolAdditionUsageBase {
+    /**
+     * The range of this symbol usage. It should contain exactly the symbol identifier itself, with no
+     * whitespaces whatsoever included.
+     *
+     * This property is ignored when the specified document's URI is not of `file:` schema. It is also ignored and
+     * set to `[0, 0)` if only a file URI, instead of a {@link TextDocument}, is provided.
+     *
+     * Please use `node` instead of this property whenever it makes sense. Learn more at the documentation
+     * for that property.
+     *
+     * If neither `node` nor `range` is provided, the range falls back to `[0, 0)`.
+     */
+    range?: RangeLike;
+    node?: undefined;
+}
+declare namespace SymbolAdditionUsageWithRange {
+    function is(usage: SymbolAdditionUsage | undefined): usage is SymbolAdditionUsageWithRange;
+}
+interface SymbolAdditionUsageWithNode extends SymbolAdditionUsageBase {
+    /**
+     * The node associated with this symbol usage. It should contain exactly the symbol identifier itself, with no
+     * wrapper nodes whatsoever included.
+     *
+     * This property is ignored when the specified document's URI is not of `file:` schema. It is also ignored and
+     * treated as `range: [0, 0)` if only a file URI, instead of a {@link TextDocument}, is provided.
+     *
+     * Either this property or `range` could be used to represent the range of this usage.
+     *
+     * However, using `node` also have the benefit of auto setting `node.symbol` to the queried symbol.
+     * It is recommended to use `node` whenever applicable.
+     *
+     * If neither `node` nor `range` is provided, the range falls back to `[0, 0)`.
+     */
+    node?: AstNode;
+    range?: undefined;
+}
+declare namespace SymbolAdditionUsageWithNode {
+    function is(usage: SymbolAdditionUsage | undefined): usage is SymbolAdditionUsageWithNode;
+}
+/**
+ * A stack of {@link SymbolTable}s. The first element represents the `File` visibility scope,
+ * which is accessible by any later elements but not saved to the global `SymbolTable`.
+ * Later elements represent different levels of `Block` visibility scopes.
+ */
+export declare type SymbolStack = [SymbolTable, ...SymbolTable[]];
+declare type QueryCallback<S extends Symbol | undefined = Symbol | undefined> = (this: SymbolQuery, symbol: S, query: SymbolQuery) => unknown;
+declare type QueryMemberCallback = (this: void, query: SymbolQuery) => unknown;
+export declare class SymbolQuery {
+    #private;
+    readonly category: string;
+    readonly path: readonly string[];
+    /**
+     * The {@link SymbolUtil} where this query was created.
+     */
+    util: SymbolUtil;
+    get symbol(): Symbol | undefined;
+    get visibleMembers(): SymbolMap;
+    constructor({ category, contributor, doc, map, parentSymbol, path, symbol, util }: {
+        category: string;
+        contributor: string | undefined;
+        doc: DocAndNode | TextDocument | string;
+        map: SymbolMap | undefined;
+        parentSymbol: Symbol | undefined;
+        path: readonly string[];
+        symbol: Symbol | undefined;
+        util: SymbolUtil;
+    });
+    heyGimmeDaSymbol(): Symbol | undefined;
+    with(fn: QueryMemberCallback): this;
+    if(predicate: (this: void, symbol: Symbol | undefined) => symbol is undefined, fn: QueryCallback<undefined>): this;
+    if(predicate: (this: void, symbol: Symbol | undefined) => symbol is Symbol, fn: QueryCallback<Symbol>): this;
+    if(predicate: QueryCallback, fn: QueryCallback): this;
+    /**
+     * Calls `fn` if the queried symbol does not exist.
+     */
+    ifUnknown(fn: QueryCallback<undefined>): this;
+    /**
+     * Calls `fn` if the queried symbol exists (i.e. has any of declarations/definitions/implementations/references/typeDefinitions).
+     */
+    ifKnown(fn: QueryCallback<Symbol>): this;
+    /**
+     * Calls `fn` if the queried symbol has declarations or definitions.
+     */
+    ifDeclared(fn: QueryCallback<Symbol>): this;
+    /**
+     * Calls `fn` if the queried symbol has definitions, or both declarations and implementations.
+     */
+    ifDefined(fn: QueryCallback<Symbol>): this;
+    /**
+     * Calls `fn` if the queried symbol has implementations or definitions.
+     */
+    ifImplemented(fn: QueryCallback<Symbol>): this;
+    /**
+     * Calls `fn` if the queried symbol has references.
+     */
+    ifReferenced(fn: QueryCallback<Symbol>): this;
+    /**
+     * Calls `fn` if the queried symbol has type definitions.
+     */
+    ifTypeDefined(fn: QueryCallback<Symbol>): this;
+    /**
+     * Calls `fn` if none of the former `if` conditions are met.
+     */
+    else(fn: QueryCallback): this;
+    /**
+     * Enters the queried symbol if none of the former `if` conditions are met.
+     */
+    elseEnter(symbol: SymbolAddition): this;
+    /**
+     * Resolves the queried symbol if it is an alias and if none of the former `if` conditions are met.
+     *
+     * @throws If the current symbol points to an non-existent symbol.
+     */
+    elseResolveAlias(): this;
+    private _enter;
+    /**
+     * Enters the queried symbol.
+     *
+     * @throws If the parent of this symbol doesn't exist either.
+     */
+    enter(addition: SymbolAddition): this;
+    /**
+     * Amends the queried symbol if the queried symbol exists (i.e. has any of declarations/definitions/implementations/references/typeDefinitions) and is visible at the current scope.
+     *
+     * This is equivalent to calling
+     * ```typescript
+     * query.ifKnown(function () {
+     * 	this.enter(symbol)
+     * })
+     * ```
+     *
+     * Therefore, if the symbol is successfully amended, `elseX` methods afterwards will **not** be executed.
+     */
+    amend(symbol: SymbolAddition): this;
+    /**
+     * Resolves this symbol if it exists and is an alias.
+     *
+     * @throws If the current symbol points to an non-existent symbol. The state of this object will not be changed
+     * after the error is thrown.
+     */
+    resolveAlias(): this;
+    /**
+     * @param identifier The identifier of the member symbol.
+     * @param fn A callback function where `this` is the member symbol's query result.
+     *
+     * @throws If the current queried symbol doesn't exist.
+     */
+    member(identifier: string, fn: QueryMemberCallback): this;
+    member(doc: TextDocument | string, identifier: string, fn: QueryMemberCallback): this;
+    /**
+     * Do something with this query on each value in a given iterable. The query itself will be included
+     * in the callback function as the second parameter.
+     */
+    onEach<T>(values: Iterable<T>, fn: (this: this, value: T, query: this) => unknown): this;
+    forEachMember(fn: (this: void, identifier: string, query: SymbolQuery) => unknown): this;
+    private getPath;
+}
+/**
+ * A series of methods for converting symbol structures to human-readable outputs. Mostly for debug purposes.
+ */
+export declare namespace SymbolFormatter {
+    function stringifySymbolStack(stack: SymbolStack): string;
+    function stringifySymbolTable(table: SymbolTable, indent?: string): string;
+    function stringifySymbolMap(map: SymbolMap | undefined, indent?: string): string;
+    function stringifySymbol(symbol: Symbol | undefined, indent?: string): string;
+    function stringifyVisibility(visibility: SymbolVisibility | undefined, visibilityRestriction?: string[]): string;
+    function stringifyLookupResult(result: LookupResult): string;
+}
+export {};
+//# sourceMappingURL=SymbolUtil.d.ts.map