@eagleoutice/flowr-dev/dataflow/internal/process/functions/call/built-in/built-in-envir-utils.d.ts

Static Dataflow Analyzer and Program Slicer for the R Programming Language

/** Shared utilities for built-in functions that interact with tracked R environments. */
import type { DataflowProcessorInformation } from '../../../../../processor';
import type { DataflowInformation } from '../../../../../info';
import type { ParentInformation } from '../../../../../../r-bridge/lang-4.x/ast/model/processing/decorate';
import type { PotentiallyEmptyRArgument } from '../../../../../../r-bridge/lang-4.x/ast/model/nodes/r-function-call';
import type { NodeId } from '../../../../../../r-bridge/lang-4.x/ast/model/processing/node-id';
import type { IdentifierDefinition, NamedInGraphIdentifierDefinition } from '../../../../../environments/identifier';
import { Identifier } from '../../../../../environments/identifier';
import type { REnvironmentInformation } from '../../../../../environments/environment';
import type { RNode } from '../../../../../../r-bridge/lang-4.x/ast/model/model';
/** Result type for a successful envir-argument resolution. */
export interface EnvirResolution<OtherInfo> {
    /** `data` with its `environment` replaced by the resolved `envState` for in-env lookups. */
    readonly envirData: DataflowProcessorInformation<OtherInfo & ParentInformation>;
    /** The definition of the variable that holds the environment */
    readonly envDef: NamedInGraphIdentifierDefinition & {
        envState: REnvironmentInformation;
    };
    /** Node ID of the USE of the envir variable (e.g. the `e` in `envir=e`). */
    readonly envirNodeId: NodeId;
    /** `true` when this resolves to a real stack environment (`globalenv()`/`.GlobalEnv`), not a tracked custom env. */
    readonly isStackEnv?: boolean;
}
/**
 * The formal parameter names of the qualified call `id` (a `pkg::fn` {@link Identifier}) from the signature
 * database (excluding `...`), or `fallback` when the database is disabled or does not carry the function. Lets a
 * built-in argument matcher use R's real signature (via {@link ReadOnlyFlowrAnalyzerDependenciesContext#signatureOf})
 * instead of a hardcoded formal list, while staying correct -- and graph-invariant -- when no signature is available.
 */
export declare function signatureParamNames<OtherInfo>(data: DataflowProcessorInformation<OtherInfo & ParentInformation>, id: Identifier, fallback: readonly string[]): readonly string[];
/** The constant string a name-position node denotes at construction time (string literal, aliased variable, or a paste-like join of such); `undefined` if any part is dynamic or the paste builtin is user-shadowed. */
export declare function resolveConstantString<OtherInfo>(node: RNode<OtherInfo & ParentInformation>, data: DataflowProcessorInformation<OtherInfo & ParentInformation>): string | undefined;
/** The `returnsEnvState` of the first reaching definition that carries one, else `undefined`. */
export declare function findReturnsEnvState(defs: readonly IdentifierDefinition[] | undefined): REnvironmentInformation | undefined;
/** Resolves a single already-found argument (e.g. from {@link RFunctionCall.matchArgsToParams}) to an {@link EnvirResolution} when it is a symbol holding a tracked envState. */
export declare function resolveArgToEnvir<OtherInfo>(arg: PotentiallyEmptyRArgument<OtherInfo & ParentInformation>, data: DataflowProcessorInformation<OtherInfo & ParentInformation>): EnvirResolution<OtherInfo> | undefined;
/** Resolves the `argName` argument (default `'envir'`), named with pmatch, to an {@link EnvirResolution}. */
export declare function resolveEnvirArg<OtherInfo>(args: readonly PotentiallyEmptyRArgument<OtherInfo & ParentInformation>[], data: DataflowProcessorInformation<OtherInfo & ParentInformation>, argName?: string): EnvirResolution<OtherInfo> | undefined;
/** Resolves a symbol by name to an {@link EnvirResolution} when it holds a tracked environment. */
export declare function resolveSymbolToEnvir<OtherInfo>(symbolName: Identifier, nodeId: NodeId, data: DataflowProcessorInformation<OtherInfo & ParentInformation>): EnvirResolution<OtherInfo> | undefined;
/** Moves definitions written into a custom environment from the caller's scope into `envDef`'s tracked `envState`, re-defining the holder variable. */
export declare function routeWrittenToCustomEnv(result: DataflowInformation, envDef: NamedInGraphIdentifierDefinition & {
    envState: REnvironmentInformation;
}, newDefAt: NodeId, definedAt?: NodeId): DataflowInformation;
/**
 * The `search()` position the `pos` argument of a `library()` call requests, either given as a number or as the name of
 * an existing entry (`pos = "package:base"`). Returns `undefined` when there is no such argument, its value is unknown
 * or ambiguous, or it names an entry that is not on the search path; callers then attach at {@link DefaultAttachPosition}
 * (as R does, which warns in the last case).
 */
export declare function resolveAttachPosition<OtherInfo>(posId: NodeId | undefined, data: DataflowProcessorInformation<OtherInfo & ParentInformation>): number | undefined;