@eagleoutice/flowr-dev/cli/repl/core.d.ts

Static Dataflow Analyzer and Program Slicer for the R Programming Language

import * as readline from 'readline';
import fs from 'fs';
import { type ReplOutput } from './commands/repl-main';
import type { MergeableRecord } from '../../util/objects';
import type { FlowrConfig } from '../../config';
import type { FlowrAnalyzer } from '../../project/flowr-analyzer';
/**
 * Completion suggestions for a specific REPL command
 */
export interface CommandCompletions {
    /** The possible completions for the current argument */
    readonly completions: string[];
    /**
     * The current argument fragment being completed, if any.
     * This is relevant if an argument is composed of multiple parts (e.g. comma-separated lists).
     */
    readonly argumentPart?: string;
    /** What Tab displays per completion, only used while several remain: readline inserts what it displays. */
    readonly labels?: ReadonlyMap<string, string>;
    /** Display-only suggestions (e.g. a `<string>` type placeholder): previewed as a ghost hint but never inserted on Tab. */
    readonly hints?: readonly string[];
    /**
     * The completer already selected these, so they must not be filtered against the typed fragment again.
     * Needed when a completion legitimately shares no prefix with what was typed, e.g. a glob expanding to the keys it matches.
     */
    readonly preFiltered?: boolean;
}
/** Labels a completion with what it does, see {@link CommandCompletions#labels|labels}. */
export declare function describeCompletion(insert: string, describe: string): string;
/**
 * Used by the repl to provide automatic completions for a given (partial) input line. Returns every matching
 * option, so Tab shows the full menu and only completes when a single option remains (standard readline behavior).
 */
export declare function replCompleter(line: string, config: FlowrConfig): [string[], string];
/**
 * The remaining text of the best (first) completion, i.e. what the inline ghost previews as you type; empty when
 * there is nothing to suggest. Independent of {@link replCompleter}: the ghost hints the best match even when Tab
 * would still offer several.
 */
export declare function completionSuggestion(line: string, config: FlowrConfig): string;
/**
 * Produces default readline options for the flowR REPL
 */
export declare function makeDefaultReplReadline(config: FlowrConfig, historyFile?: string | undefined): readline.ReadLineOptions;
/**
 * Handles a string input for the REPL, returning the parsed string and any remaining input.
 */
export declare function handleString(code: string): {
    rCode: string | undefined;
    remaining: never[];
};
/** Convert a statement containing {@link watchProtocol} into one using {@link fileProtocol} so it can be executed. */
export declare function toFileStatement(statement: string): string;
/** Return the watch path from the first `watch://<path>` token in `statement`, or `undefined` if none is present. */
export declare function extractWatchPath(statement: string): string | undefined;
/** Stop the active watcher. Pass `notify = false` when silently switching to a new watch target. */
export declare function stopWatching(output: ReplOutput, notify?: boolean): void;
/** `watchImpl` is injectable so tests can pass a fake `fs.watch`. */
export declare function startWatching(watchPath: string, output: ReplOutput, onFire: () => void, watchImpl?: typeof fs.watch): fs.FSWatcher;
/**
 * This function interprets the given `expr` as a REPL command (see {@link repl} for more on the semantics).
 * @param analyzer            - The flowR analyzer to use.
 * @param output              - Defines two methods that every function in the repl uses to output its data.
 * @param expr                - The expression to process.
 * @param allowRSessionAccess - If true, allows the execution of arbitrary R code.
 */
export declare function replProcessAnswer(analyzer: FlowrAnalyzer, output: ReplOutput, expr: string, allowRSessionAccess: boolean): Promise<void>;
/**
 * Options for the {@link repl} function.
 */
export interface FlowrReplOptions extends MergeableRecord {
    /**
     * The flowR analyzer to use.
     */
    readonly analyzer: FlowrAnalyzer;
    /**
     * A potentially customized readline interface to be used for the repl to *read* from the user, we write the output with the {@link ReplOutput | `output` } interface.
     * If you want to provide a custom one but use the same `completer`, refer to {@link replCompleter}.
     */
    readonly rl?: readline.Interface;
    /** Defines two methods that every function in the repl uses to output its data. */
    readonly output?: ReplOutput;
    /** The file to use for loading and persisting the repl's history. Passing an empty string neither reads nor writes it. */
    readonly historyFile?: string;
    /** If true, allows the execution of arbitrary R code. This is a security risk, as it allows the execution of arbitrary R code. */
    readonly allowRSessionAccess?: boolean;
}
/**
 * Provides a never-ending repl (read-evaluate-print loop) processor that can be used to interact with a {@link RShell} as well as all flowR scripts.
 *
 * The repl allows for two kinds of inputs:
 * - Starting with a colon `:`, indicating a command (probe `:help`, and refer to {@link commands}) </li>
 * - Starting with anything else, indicating default R code to be directly executed. If you kill the underlying shell, that is on you! </li>
 * @param options - The options for the repl. See {@link FlowrReplOptions} for more information.
 *
 * For the execution, this function makes use of {@link replProcessAnswer}.
 */
export declare function repl({ analyzer, historyFile, rl, output, allowRSessionAccess }: FlowrReplOptions): Promise<void>;
/**
 * Loads the REPL history from the given file.
 */
export declare function loadReplHistory(historyFile: string): string[] | undefined;