@eagleoutice/flowr-dev/project/context/flowr-analyzer-loading-order-context.d.ts

Static Dataflow Analyzer and Program Slicer for the R Programming Language

import { AbstractFlowrAnalyzerContext } from './abstract-flowr-analyzer-context';
import type { RParseRequest } from '../../r-bridge/retriever';
import { FlowrAnalyzerLoadingOrderPlugin } from '../plugins/loading-order-plugins/flowr-analyzer-loading-order-plugin';
import type { FlowrAnalyzerContext } from './flowr-analyzer-context';
/**
 * Read-only interface for the loading order context, which is used to determine the order in which script files are loaded in a project.
 *
 * This interface 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 FlowrAnalyzerLoadingOrderPlugin} and want to modify the available orders, you can use the {@link FlowrAnalyzerLoadingOrderContext} directly.
 */
export interface ReadOnlyFlowrAnalyzerLoadingOrderContext {
    /**
     * The name of this context.
     */
    readonly name: string;
    /**
     * Peek whether we have a loading order known or guessed, this does not trigger any plugin runs.
     * If you want to get the current loading order, including potential recompoutations, use {@link getLoadingOrder} instead.
     */
    peekLoadingOrder(): readonly RParseRequest[] | undefined;
    /**
     * Get the current loading order of requests, potentially triggering a re-computation if new requests have been added since the last computation.
     */
    getLoadingOrder(): readonly RParseRequest[];
    /**
     * Get all requests that have been added to this context, but for which no loading order is known or guessed.
     */
    getUnorderedRequests(): readonly RParseRequest[];
    /**
     * Get the current guesses for the loading order, if any. These are populated by {@link FlowrAnalyzerLoadingOrderPlugin}s.
     */
    currentGuesses(): readonly (readonly RParseRequest[])[];
    /**
     * Get the current known loading order, if any. This is populated by {@link FlowrAnalyzerLoadingOrderPlugin}s if they have a source of identifying the order definitively.
     */
    currentKnownOrder(): readonly RParseRequest[] | undefined;
}
/**
 * This context is responsible for managing the loading order of script files in a project, including guesses and known orders provided by {@link FlowrAnalyzerLoadingOrderPlugin}s.
 *
 * If you are interested in inspecting these orders, refer to {@link ReadOnlyFlowrAnalyzerLoadingOrderContext}.
 * Plugins, however, can use this context directly to modify order guesses.
 */
export declare class FlowrAnalyzerLoadingOrderContext extends AbstractFlowrAnalyzerContext<undefined, void, FlowrAnalyzerLoadingOrderPlugin> implements ReadOnlyFlowrAnalyzerLoadingOrderContext {
    readonly name = "flowr-analyzer-loading-order-context";
    private rerunRequired;
    constructor(ctx: FlowrAnalyzerContext, plugins: readonly FlowrAnalyzerLoadingOrderPlugin[] | undefined);
    private knownOrder?;
    private readonly guesses;
    /** just the base collection of requests we know nothing about the order! */
    private readonly unordered;
    /** what {@link unordered} already holds, so the same file is never analyzed (and reconstructed) twice */
    private readonly seen;
    reset(): void;
    /**
     * Registers `request` as unordered unless the same one is already there, reporting whether it was new.
     * Project discovery and the implicit-source scan reach the same file from both ends, so a file otherwise
     * lands in the loading order more than once and every later step repeats it.
     */
    private register;
    /**
     * Add one or multiple requests to the context.
     * These are considered unordered (i.e., ordered implicitly by the order of addition) until a plugin provides either a guess or a known order.
     *
     * This is a batched version of {@link addRequest}.
     */
    addRequests(requests: readonly RParseRequest[]): void;
    /**
     * Add a single request to the context.
     * This is considered unordered (i.e., ordered implicitly by the order of addition) until a plugin provides either a guess or a known order.
     *
     * If you want to add multiple requests, consider using {@link addRequests} instead for efficiency.
     */
    addRequest(request: RParseRequest): void;
    /**
     * Add a guess for the loading order. This is mostly for plugins to use.
     * In case you have a certain order, use the `certain` flag to indicate this -- but please take care of *really* being certain!
     */
    addGuess(guess: readonly RParseRequest[], certain?: boolean): void;
    /**
     * Move `requests` to the front of every order known so far, keeping their relative order.
     * Use this for files R evaluates before anything else (e.g. `.Rprofile`), as it refines the
     * existing orders instead of competing with them like {@link addGuess} would.
     */
    prependToOrder(requests: readonly RParseRequest[]): void;
    /**
     * Drop `requests` from every order known so far. Use this for files another file already
     * contains (e.g. the target of an Rmd `child` chunk), as it refines the existing orders instead
     * of competing with them like {@link addGuess} would.
     */
    removeFromOrder(requests: readonly RParseRequest[]): void;
    currentGuesses(): readonly (readonly RParseRequest[])[];
    currentKnownOrder(): readonly RParseRequest[] | undefined;
    peekLoadingOrder(): readonly RParseRequest[] | undefined;
    getUnorderedRequests(): readonly RParseRequest[];
    getLoadingOrder(): readonly RParseRequest[];
}