@eagleoutice/flowr/project/flowr-analyzer-builder.d.ts

Static Dataflow Analyzer and Program Slicer for the R Programming Language

import { type EngineConfig, FlowrConfig } from '../config';
import type { DeepWritable, PathValue } from 'ts-essentials';
import { FlowrAnalyzer } from './flowr-analyzer';
import type { KnownParser } from '../r-bridge/parser';
import type { FlowrAnalyzerPlugin } from './plugins/flowr-analyzer-plugin';
import type { NormalizeRequiredInput } from '../core/steps/all/core/10-normalize';
import type { BuiltInFlowrPluginName, PluginToRegister } from './plugins/plugin-registry';
import type { AutocompletablePaths } from '../util/objects';
/**
 * Builder for the {@link FlowrAnalyzer}, use it to configure all analysis aspects before creating the analyzer instance
 * with {@link FlowrAnalyzerBuilder#build|`.build()`} or {@link FlowrAnalyzerBuilder#buildSync|`.buildSync()`}.
 *
 * You can add new files and folders to analyze using the {@link FlowrAnalyzer#addRequest|`.addRequest()`} method on the resulting analyzer.
 * @example Let's create an analyzer for a single R script file:
 *
 * ```ts
 * const analyzer = new FlowrAnalyzerBuilder()
 *                      .setParser(new TreeSitterExecutor())
 *                      .buildSync()
 *                      .addRequest('file:///path/to/script.R')
 *
 * ```
 *
 * If you now want to get the dataflow information for the file, you can do this:
 *
 * ```ts
 * const dfInfo = await analyzer.dataflow();
 * console.log(dfInfo);
 * ```
 * @see https://github.com/flowr-analysis/flowr/wiki/Analyzer
 */
export declare class FlowrAnalyzerBuilder {
    private flowrConfig;
    private parser?;
    private input?;
    private readonly plugins;
    /**
     * Creates a new builder for the {@link FlowrAnalyzer}.
     * By default, the standard set of plugins as returned by {@link FlowrAnalyzerPluginDefaults} are registered.
     * @param withDefaultPlugins - Whether to register the default plugins upon creation. Default is `true`.
     * @see {@link FlowrAnalyzerPluginDefaults} - for the default plugin set.
     * @see {@link FlowrAnalyzerBuilder#registerPlugins} - to add more plugins.
     * @see {@link FlowrAnalyzerBuilder#unregisterPlugins} - to remove plugins.
     */
    constructor(withDefaultPlugins?: boolean);
    /**
     * Apply an amendment to the configuration the builder currently holds.
     * This is mostly intended for more complex logic to transform the config.
     * Please consider using {@link FlowrAnalyzerBuilder.configure} to set/amend individual values
     * Per default, the value returned by {@link FlowrConfig.default} is used.
     * @param func - Receives the current configuration of the builder and allows for amendment.
     */
    amendConfig(func: (config: DeepWritable<FlowrConfig>) => FlowrConfig | void): this;
    /**
     * Overwrite the configuration used by the resulting analyzer.
     * @param config - The new configuration.
     */
    setConfig(config: FlowrConfig): this;
    /**
     * Set a specific value in the configuration used by the resulting analyzer.
     */
    configure<K extends AutocompletablePaths<FlowrConfig>>(key: K, value: PathValue<FlowrConfig, K>): this;
    /**
     * Set the parser instance used by the analyzer.
     * This is an alternative to {@link FlowrAnalyzerBuilder#setEngine} if you already have a parser instance.
     * Please be aware, that if you want to parallelize multiple analyzers, there should be separate parser instances.
     */
    setParser(parser: KnownParser): this;
    /**
     * Set the engine and hence the parser that will be used by the analyzer.
     * This is an alternative to {@link FlowrAnalyzerBuilder#setParser} if you do not have a parser instance at hand.
     */
    setEngine(engine: EngineConfig['type']): this;
    /**
     * Additional parameters for the analyses.
     * @param input - The input.
     */
    setInput(input: Omit<NormalizeRequiredInput, 'context'>): this;
    /**
     * Register one or multiple additional plugins.
     * For the default plugin set, please refer to {@link FlowrAnalyzerPluginDefaults}, they can be registered
     * by passing `true` to the {@link FlowrAnalyzerBuilder} constructor.
     * @param plugin - One or multiple plugins to register.
     * @see {@link FlowrAnalyzerBuilder#unregisterPlugins} to remove plugins.
     */
    registerPlugins<T extends BuiltInFlowrPluginName | string>(...plugin: readonly PluginToRegister<T>[]): this;
    /**
     * Remove one or multiple plugins.
     * @see {@link FlowrAnalyzerBuilder#registerPlugins} to add plugins.
     */
    unregisterPlugins(...plugin: readonly (FlowrAnalyzerPlugin | string | BuiltInFlowrPluginName)[]): this;
    /**
     * Create the {@link FlowrAnalyzer} instance using the given information.
     * Please note that the only reason this is `async` is that if no parser is set,
     * we need to retrieve the default engine instance which is an async operation.
     * If you have already initialized the engine (e.g., with {@link TreeSitterExecutor#initTreeSitter}),
     * you can use the synchronous version {@link FlowrAnalyzerBuilder#buildSync} instead.
     */
    build(): Promise<FlowrAnalyzer>;
    /**
     * Synchronous version of {@link FlowrAnalyzerBuilder#build}, please only use this if you have set the parser using
     * {@link FlowrAnalyzerBuilder#setParser} before, otherwise an error will be thrown.
     */
    buildSync(): FlowrAnalyzer;
}