rdesign/frontend/node_modules/langium/lib/syntax-tree.d.ts

/******************************************************************************
 * Copyright 2021 TypeFox GmbH
 * This program and the accompanying materials are made available under the
 * terms of the MIT License, which is available in the project root.
 ******************************************************************************/
import type { TokenType } from 'chevrotain';
import type { URI } from './utils/uri-utils.js';
import type { AbstractElement } from './languages/generated/ast.js';
import type { DocumentSegment, LangiumDocument } from './workspace/documents.js';
/**
 * A node in the Abstract Syntax Tree (AST).
 */
export interface AstNode {
    /** Every AST node has a type corresponding to what was specified in the grammar declaration. */
    readonly $type: string;
    /** The container node in the AST; every node except the root node has a container. */
    readonly $container?: AstNode;
    /** The property of the `$container` node that contains this node. This is either a direct reference or an array. */
    readonly $containerProperty?: string;
    /** In case `$containerProperty` is an array, the array index is stored here. */
    readonly $containerIndex?: number;
    /** The Concrete Syntax Tree (CST) node of the text range from which this node was parsed. */
    readonly $cstNode?: CstNode;
    /** The document containing the AST; only the root node has a direct reference to the document. */
    readonly $document?: LangiumDocument;
}
export declare function isAstNode(obj: unknown): obj is AstNode;
export interface GenericAstNode extends AstNode {
    [key: string]: unknown;
}
type SpecificNodeProperties<N extends AstNode> = keyof Omit<N, keyof AstNode | number | symbol>;
/**
 * The property names of a given AST node type.
 */
export type Properties<N extends AstNode> = SpecificNodeProperties<N> extends never ? string : SpecificNodeProperties<N>;
/**
 * A cross-reference in the AST. Cross-references may or may not be successfully resolved.
 */
export interface Reference<T extends AstNode = AstNode> {
    /**
     * The target AST node of this reference. Accessing this property may trigger cross-reference
     * resolution by the `Linker` in case it has not been done yet. If the reference cannot be resolved,
     * the value is `undefined`.
     */
    readonly ref: T | undefined;
    /** If any problem occurred while resolving the reference, it is described by this property. */
    readonly error?: LinkingError;
    /** The CST node from which the reference was parsed */
    readonly $refNode?: CstNode;
    /** The actual text used to look up in the surrounding scope */
    readonly $refText: string;
    /** The node description for the AstNode returned by `ref`  */
    readonly $nodeDescription?: AstNodeDescription;
}
export interface MultiReference<T extends AstNode = AstNode> {
    /** The CST node from which the reference was parsed */
    readonly $refNode?: CstNode;
    /** The actual text used to look up in the surrounding scope */
    readonly $refText: string;
    /**
     * The resolved references. Accessing this property may trigger cross-reference
     * resolution by the `Linker` in case it has not been done yet.
     * If no references can be found, the array is empty (but not `undefined`)
     * and the `error` property is set.
     */
    readonly items: Array<MultiReferenceItem<T>>;
    /** If any problem occurred while resolving the reference, it is described by this property. */
    readonly error?: LinkingError;
}
/**
 * Represents a single resolved reference of a {@link MultiReference} instance.
 */
export interface MultiReferenceItem<T extends AstNode = AstNode> {
    /** The node description for the AstNode returned by `ref`  */
    readonly $nodeDescription?: AstNodeDescription;
    /**
     * The target AST node of this reference.
     */
    readonly ref: T;
}
export declare function isReference(obj: unknown): obj is Reference;
export declare function isMultiReference(obj: unknown): obj is MultiReference;
export type ResolvedReference<T extends AstNode = AstNode> = Reference<T> & {
    readonly ref: T;
};
/**
 * A description of an AST node is used when constructing scopes and looking up cross-reference targets.
 */
export interface AstNodeDescription {
    /** The target node; should be present only for local references (linking to the same document). */
    node?: AstNode;
    /**
     * The document segment that represents the range of the name of the AST node.
     */
    nameSegment?: DocumentSegment;
    /**
     * The document segment that represents the full range of the AST node.
     */
    selectionSegment?: DocumentSegment;
    /** `$type` property value of the AST node */
    type: string;
    /** Name of the AST node; this is usually determined by the `NameProvider` service. */
    name: string;
    /** URI to the document containing the AST node */
    documentUri: URI;
    /** Navigation path inside the document */
    path: string;
}
export declare function isAstNodeDescription(obj: unknown): obj is AstNodeDescription;
/**
 * Information about a cross-reference. This is used when traversing references in an AST or to describe
 * unresolved references.
 */
export interface ReferenceInfo {
    reference: Reference | MultiReference;
    container: AstNode;
    property: string;
    index?: number;
}
/**
 * Used to collect information when the `Linker` service fails to resolve a cross-reference.
 */
export interface LinkingError {
    message: string;
    info: ReferenceInfo;
    targetDescription?: AstNodeDescription;
}
export declare function isLinkingError(obj: unknown): obj is LinkingError;
/**
 * Service used for generic access to the structure of the AST. This service is shared between
 * all involved languages, so it operates on the superset of types of these languages.
 */
export interface AstReflection {
    readonly types: AstMetaData;
    getAllTypes(): string[];
    getReferenceType(refInfo: ReferenceInfo): string;
    getTypeMetaData(type: string): TypeMetaData;
    isInstance(node: unknown, type: string): boolean;
    isSubtype(subtype: string, supertype: string): boolean;
    getAllSubTypes(type: string): string[];
}
/**
 * An abstract implementation of the {@link AstReflection} interface.
 * Serves to cache subtype computation results to improve performance throughout different parts of Langium.
 */
export declare abstract class AbstractAstReflection implements AstReflection {
    readonly types: AstMetaData;
    protected subtypes: Record<string, Record<string, boolean | undefined>>;
    protected allSubtypes: Record<string, string[] | undefined>;
    getAllTypes(): string[];
    getReferenceType(refInfo: ReferenceInfo): string;
    getTypeMetaData(type: string): TypeMetaData;
    isInstance(node: unknown, type: string): boolean;
    isSubtype(subtype: string, supertype: string): boolean;
    getAllSubTypes(type: string): string[];
}
/**
 * A map of all AST node types and their meta data.
 */
export interface AstMetaData {
    [type: string]: TypeMetaData;
}
/**
 * Represents runtime meta data about an AST node type.
 */
export interface TypeMetaData {
    /** The name of this AST node type. Corresponds to the `AstNode.$type` value. */
    name: string;
    /** A list of properties with their relevant meta data. */
    properties: {
        [name: string]: PropertyMetaData;
    };
    /** The super types of this AST node type. */
    superTypes: string[];
}
/**
 * Describes the meta data of a property of an AST node.
 */
export interface PropertyMetaData {
    /** The name of this property. */
    name: string;
    /**
     * Indicates that the property is mandatory in the AST node.
     * For example, if an AST node contains an array, but no elements of this array have been parsed,
     * we still expect an empty array instead of `undefined`.
     */
    defaultValue?: PropertyType;
    /**
     * If the property is a reference, this is the type of the reference target.
     */
    referenceType?: string;
}
/**
 * Represents a default value for an AST property.
 */
export type PropertyType = number | string | boolean | PropertyType[];
/**
 * A node in the Concrete Syntax Tree (CST).
 */
export interface CstNode extends DocumentSegment {
    /** The container node in the CST */
    readonly container?: CompositeCstNode;
    /** The actual text */
    readonly text: string;
    /** The root CST node */
    readonly root: RootCstNode;
    /** The grammar element from which this node was parsed */
    readonly grammarSource?: AbstractElement;
    /** The AST node created from this CST node */
    readonly astNode: AstNode;
    /** Whether the token is hidden, i.e. not explicitly part of the containing grammar rule */
    readonly hidden: boolean;
}
/**
 * A composite CST node contains other nodes, but no directly associated token.
 */
export interface CompositeCstNode extends CstNode {
    readonly content: CstNode[];
}
export declare function isCompositeCstNode(node: unknown): node is CompositeCstNode;
/**
 * A leaf CST node corresponds to a token in the input token stream.
 */
export interface LeafCstNode extends CstNode {
    readonly tokenType: TokenType;
}
export declare function isLeafCstNode(node: unknown): node is LeafCstNode;
export interface RootCstNode extends CompositeCstNode {
    readonly fullText: string;
}
export declare function isRootCstNode(node: unknown): node is RootCstNode;
/**
 * Describes a union type including only names(!) of properties of type T whose property value is of a certain type K,
 *  or 'never' in case of no such properties.
 * It evaluates the value type regardless of the property being optional or not by converting T to Required<T>.
 * Note the '-?' in '[I in keyof T]-?:' that is required to map all optional but un-intended properties to 'never'.
 * Without that, optional props like those inherited from 'AstNode' would be mapped to 'never|undefined',
 *  and the subsequent value mapping ('...[keyof T]') would yield 'undefined' instead of 'never' for AstNode types
 *  not having any property matching type K, which in turn yields follow-up errors.
 */
type ExtractKeysOfValueType<T, K> = {
    [I in keyof T]-?: Required<T>[I] extends K ? I : never;
}[keyof T];
export type SingleCrossReferencesOfAstNodeType<N extends AstNode> = ExtractKeysOfValueType<N, Reference | Reference[]>;
export type MultiCrossReferencesOfAstNodeType<N extends AstNode> = ExtractKeysOfValueType<N, MultiReference | MultiReference[]>;
/**
 * Describes a union type including only names(!) of the cross-reference properties of the given AstNode type.
 * Enhances compile-time validation of cross-reference distinctions, e.g. in scope providers
 *  in combination with `assertUnreachable(context.property)`.
 */
export type CrossReferencesOfAstNodeType<N extends AstNode> = SingleCrossReferencesOfAstNodeType<N> | MultiCrossReferencesOfAstNodeType<N>;
/**
 * Represents the enumeration-like type, that lists all AstNode types of your grammar.
 */
export type AstTypeList<T> = Record<keyof T, AstNode>;
/**
 * Describes a union type including of all AstNode types containing cross-references.
 *  A is meant to be the interface `XXXAstType` fromm your generated `ast.ts` file.
 * Enhances compile-time validation of cross-reference distinctions, e.g. in scope providers
 *  in combination with `assertUnreachable(context.container)`.
 */
export type AstNodeTypesWithCrossReferences<A extends AstTypeList<A>> = {
    [T in keyof A]-?: CrossReferencesOfAstNodeType<A[T]> extends never ? never : A[T];
}[keyof A];
export type Mutable<T> = {
    -readonly [P in keyof T]: T[P];
};
export {};
//# sourceMappingURL=syntax-tree.d.ts.map