@eagleoutice/flowr/project/context/flowr-analyzer-files-context.d.ts

Static Dataflow Analyzer and Program Slicer for the R Programming Language

import { AbstractFlowrAnalyzerContext } from './abstract-flowr-analyzer-context';
import type { RParseRequestFromText, RParseRequest, RParseRequestFromFile } from '../../r-bridge/retriever';
import type { FlowrAnalyzerLoadingOrderContext, ReadOnlyFlowrAnalyzerLoadingOrderContext } from './flowr-analyzer-loading-order-context';
import { FlowrAnalyzerProjectDiscoveryPlugin } from '../plugins/project-discovery/flowr-analyzer-project-discovery-plugin';
import { FlowrAnalyzerFilePlugin } from '../plugins/file-plugins/flowr-analyzer-file-plugin';
import { FlowrFile, type FlowrFileProvider, FileRole } from './flowr-file';
import type { FlowrDescriptionFile } from '../plugins/file-plugins/files/flowr-description-file';
import type { FlowrNewsFile } from '../plugins/file-plugins/files/flowr-news-file';
import type { FlowrNamespaceFile } from '../plugins/file-plugins/files/flowr-namespace-file';
/**
 * This is a request to process a folder as a project, which will be expanded by the registered {@link FlowrAnalyzerProjectDiscoveryPlugin}s.
 */
export interface RProjectAnalysisRequest {
    readonly request: 'project';
    /**
     * The path to the root folder (an absolute path is probably best here).
     */
    readonly content: string;
}
export type RAnalysisRequest = RParseRequest | RProjectAnalysisRequest;
export type RoleBasedFiles = {
    [FileRole.Description]: FlowrDescriptionFile[];
    [FileRole.News]: FlowrNewsFile[];
    [FileRole.Namespace]: FlowrNamespaceFile[];
    [FileRole.Vignette]: FlowrFileProvider[];
    [FileRole.Test]: FlowrFileProvider[];
    [FileRole.License]: FlowrFileProvider[];
    [FileRole.Source]: FlowrFileProvider[];
    [FileRole.Data]: FlowrFileProvider[];
    [FileRole.Other]: FlowrFileProvider[];
};
/**
 * This is the read-only interface for the files context, which is used to manage all files known to the {@link FlowrAnalyzer}.
 * It prevents you from modifying the available files, but allows you to inspect them (which is probably what you want when using the {@link FlowrAnalyzer}).
 * If you are a {@link FlowrAnalyzerProjectDiscoveryPlugin} and want to modify the available files, you can use the {@link FlowrAnalyzerFilesContext} directly.
 */
export interface ReadOnlyFlowrAnalyzerFilesContext {
    /**
     * The name of this context.
     */
    readonly name: string;
    /**
     * The loading order context provides access to the loading order of script files in the project.
     */
    readonly loadingOrder: ReadOnlyFlowrAnalyzerLoadingOrderContext;
    /**
     * Get all requests that have been added to this context.
     * @example If you want to obtain all description files, use
     * ```ts
     * getFilesByRole(SpecialFileRole.Description)
     * ```
     */
    getFilesByRole<Role extends FileRole>(role: Role): RoleBasedFiles[Role];
    /**
     * Get all files known to this context.
     * @returns An array of all files.
     */
    getAllFiles(): FlowrFileProvider[];
    /**
     * Check if the context has a file with the given path.
     * Please note, that this may also check the file system, depending on the configuration
     * (see {@link FlowrConfig.project.resolveUnknownPathsOnDisk}).
     * @param path - The path to the file.
     *
     * If you do not know the exact path or, e.g., casing of the file, use {@link exists} instead.
     */
    hasFile(path: string): boolean;
    /**
     * Check if a file exists at the given path, optionally ignoring case.
     * @param path - The path to the file.
     * @param ignoreCase - Whether to ignore case when checking for the file.
     *
     * Please note that this method checks the file system based on the configuration (see {@link FlowrConfig.project.resolveUnknownPathsOnDisk}).
     * @returns The actual path of the file if it exists, otherwise `undefined`.
     */
    exists(path: string, ignoreCase: boolean): string | undefined;
    /**
     * Until parsers support multiple request types from the virtual context system,
     * we resolve their contents.
     */
    resolveRequest(r: RParseRequest): {
        r: RParseRequestFromText;
        path?: string;
    };
    /**
     * Get all files that have been considered during dataflow analysis.
     */
    consideredFilesList(): readonly string[];
}
/**
 * This is the analyzer file context to be modified by all plugins that affect the files.
 * If you are interested in inspecting these files, refer to {@link ReadOnlyFlowrAnalyzerFilesContext}.
 * Plugins, however, can use this context directly to modify files.
 */
export declare class FlowrAnalyzerFilesContext extends AbstractFlowrAnalyzerContext<RProjectAnalysisRequest, (RParseRequest | FlowrFile<string>)[], FlowrAnalyzerProjectDiscoveryPlugin> implements ReadOnlyFlowrAnalyzerFilesContext {
    readonly name = "flowr-analyzer-files-context";
    readonly loadingOrder: FlowrAnalyzerLoadingOrderContext;
    private files;
    private inlineFiles;
    private readonly fileLoaders;
    /** these are all the paths of files that have been considered by the dataflow graph (even if not added) */
    private readonly consideredFiles;
    private byRole;
    constructor(loadingOrder: FlowrAnalyzerLoadingOrderContext, plugins: readonly FlowrAnalyzerProjectDiscoveryPlugin[], fileLoaders: readonly FlowrAnalyzerFilePlugin[]);
    reset(): void;
    /**
     * Record that a file has been considered during dataflow analysis.
     */
    addConsideredFile(path: string): void;
    /**
     * Get all files that have been considered during dataflow analysis.
     */
    consideredFilesList(): readonly string[];
    /**
     * Add multiple requests to the context. This is just a convenience method that calls {@link addRequest} for each request.
     */
    addRequests(requests: readonly RAnalysisRequest[]): void;
    /**
     * Add a request to the context. If the request is of type `project`, it will be expanded using the registered {@link FlowrAnalyzerProjectDiscoveryPlugin}s.
     */
    private addRequest;
    /**
     * Add multiple files to the context. This is just a convenience method that calls {@link addFile} for each file.
     */
    addFiles(files: (string | FlowrFileProvider | RParseRequestFromFile)[]): void;
    /**
     * Add a file to the context. If the file has a special role, it will be added to the corresponding list of special files.
     * This method also applies any registered {@link FlowrAnalyzerFilePlugin}s to the file before adding it to the context.
     */
    addFile(file: string | FlowrFileProvider | RParseRequestFromFile, roles?: readonly FileRole[]): FlowrFileProvider<{
        toString(): string;
    }>;
    hasFile(path: string): boolean;
    exists(p: string, ignoreCase: boolean): string | undefined;
    private fileLoadPlugins;
    resolveRequest(r: RParseRequest): {
        r: RParseRequestFromText;
        path?: string;
    };
    /**
     * Get all requests that have been added to this context.
     * This is a convenience method that calls {@link FlowrAnalyzerLoadingOrderContext.getLoadingOrder}.
     */
    computeLoadingOrder(): readonly RParseRequest[];
    getFilesByRole<Role extends FileRole>(role: Role): RoleBasedFiles[Role];
    getAllFiles(): FlowrFileProvider[];
}