@eagleoutice/flowr/r-bridge/retriever.d.ts

Static Dataflow Analyzer and Program Slicer for the R Programming Language

import { type RShell } from './shell';
import type { AsyncOrSync } from 'ts-essentials';
import { RShellExecutor } from './shell-executor';
import { type NormalizedAst } from './lang-4.x/ast/model/processing/decorate';
export declare const fileProtocol = "file://";
export interface RParseRequestFromFile {
    readonly request: 'file';
    /**
     * The path to the file represented in the {@link FlowrAnalyzerFilesContext}.
     * See {@link RParseRequests} for multiple files.
     */
    readonly content: string;
}
/**
 * A request to parse R code given as text.
 * This option is mostly useful for quick tests or injects, as usually files are controlled by the {@link RParseRequestFromFile} request
 * referring to a file in the {@link FlowrAnalyzerFilesContext}.
 */
export interface RParseRequestFromText {
    readonly request: 'text';
    /**
     * Source code to parse (not a file path).
     * If you want to parse multiple files as one, either use {@link RParseRequests},
     * a higher request as a {@link FileAnalysisRequestMessage},
     * or concatenate their contents to pass them with this request.
     */
    readonly content: string;
}
/**
 * A provider for an {@link RParseRequests} that can be used, for example, to override source file parsing behavior in tests
 */
export interface RParseRequestProvider {
    /** returns the path if it exists, otherwise undefined */
    exists(path: string, ignoreCase: boolean): string | undefined;
    createRequest(path: string): RParseRequest;
}
export type RParseRequest = RParseRequestFromFile | RParseRequestFromText;
/**
 * Several requests that can be passed along to {@link retrieveParseDataFromRCode}.
 */
export type RParseRequests = RParseRequest | ReadonlyArray<RParseRequest>;
/**
 * Type guard for {@link RParseRequest}
 */
export declare function isParseRequest(request: unknown): request is RParseRequest;
export declare function requestFromInput(input: `${typeof fileProtocol}${string}`): RParseRequestFromFile;
export declare function requestFromInput(input: `${typeof fileProtocol}${string}`[]): RParseRequestFromFile[];
export declare function requestFromInput(input: string): RParseRequestFromText;
export declare function requestFromInput(input: readonly string[] | string): RParseRequests;
/**
 * Creates a {@link RParseRequestProvider} that reads from the file system.
 * Uses `fs.existsSync` to check for file existence.
 * @see {@link requestProviderFromText} for a provider that reads from a text map.
 */
export declare function requestProviderFromFile(): RParseRequestProvider;
/**
 * Creates a {@link RParseRequestProvider} that reads from the given text map.
 * @see {@link requestProviderFromFile} for a provider that reads from the file system.
 */
export declare function requestProviderFromText(text: Readonly<{
    [path: string]: string;
}>): RParseRequestProvider;
/**
 * Checks whether the given {@link RParseRequest} is empty (has no content).
 */
export declare function isEmptyRequest(request: RParseRequest): boolean;
export declare function retrieveParseDataFromRCode(request: RParseRequest, shell: RShell): Promise<string>;
export declare function retrieveParseDataFromRCode(request: RParseRequest, shell: RShellExecutor): string;
export declare function retrieveParseDataFromRCode(request: RParseRequest, shell: RShell | RShellExecutor): AsyncOrSync<string>;
/**
 * Uses {@link retrieveParseDataFromRCode} and returns the nicely formatted object-AST.
 * If successful, allows further querying the last result with {@link retrieveNumberOfRTokensOfLastParse}.
 * This function is outdated and should only be used for legacy reasons. Please use the {@link FlowrAnalyzer} instead.
 */
export declare function retrieveNormalizedAstFromRCode(request: RParseRequest, shell: RShell): Promise<NormalizedAst>;
/**
 * If the string has (R-)quotes around it, they will be removed; otherwise the string is returned unchanged.
 */
export declare function removeRQuotes(str: string): string;
/**
 * Needs to be called *after* {@link retrieveParseDataFromRCode} (or {@link retrieveNormalizedAstFromRCode})
 */
export declare function retrieveNumberOfRTokensOfLastParse(shell: RShell, ignoreComments?: boolean): Promise<number>;