@eagleoutice/flowr/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.
 *
 * - {@link bindArgs} - bind call arguments to formal parameter names using R's matching rules.
 * - {@link resolveArgToEnvir} - resolve a single already-found argument to an {@link EnvirResolution}.
 * - {@link resolveEnvirArg} / {@link resolveSymbolToEnvir} - resolve a named argument or
 *   symbol to an {@link EnvirResolution} when it holds a tracked {@link InGraphIdentifierDefinition#envState}.
 * - {@link routeWrittenToCustomEnv} - move written definitions from the caller's scope into
 *   the holder variable's `envState` after processing an expression that writes into a custom env.
 */
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 { Identifier, NamedInGraphIdentifierDefinition } from '../../../../../environments/identifier';
import type { REnvironmentInformation } from '../../../../../environments/environment';
/** 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;
}
/**
 * Binds call arguments to formal parameter names following R's standard matching rules:
 * 1. Exact name matches (named args bound to exact-matching formal params).
 * 2. Partial (pmatch) name matches via {@link findByPrefixIfUnique}.
 * 3. Remaining unnamed args fill remaining unbound formal params left-to-right.
 *
 * Pass `paramNames` as the full formal parameter list (excluding `...`) so ambiguous
 * prefixes are rejected correctly.  Use this when multiple formals must be found
 * simultaneously so that named-arg binding is consistent across all formals.
 */
export declare function bindArgs<OtherInfo>(args: readonly PotentiallyEmptyRArgument<OtherInfo & ParentInformation>[], paramNames: readonly string[]): ReadonlyMap<string, PotentiallyEmptyRArgument<OtherInfo & ParentInformation>>;
/**
 * Resolves a single already-found argument (e.g. from {@link bindArgs}) to an
 * {@link EnvirResolution} when the argument is a symbol that holds a tracked envState.
 * Returns `undefined` when the arg is empty, non-symbolic, or unresolved.
 */
export declare function resolveArgToEnvir<OtherInfo>(arg: PotentiallyEmptyRArgument<OtherInfo & ParentInformation>, data: DataflowProcessorInformation<OtherInfo & ParentInformation>): EnvirResolution<OtherInfo> | undefined;
/**
 * Scans `args` for an argument named `argName` (default `'envir'`), or - when
 * `positionalFallbackIndex` is given - for the arg at that positional index when
 * no named match is found.  When the resolved argument is a symbol that resolves
 * to a variable with a tracked {@link InGraphIdentifierDefinition#envState},
 * returns the resolved context; otherwise returns `undefined`.
 *
 * Named matching uses pmatch semantics: pass `allParamNames` (the full formal parameter
 * list) so ambiguous prefixes are rejected.  Defaults to `[argName]`, which allows
 * prefix matches for `argName` only.
 *
 * When multiple formals must be matched simultaneously (e.g. `data` and `expr` in `with`),
 * use {@link bindArgs} + {@link resolveArgToEnvir} instead so named binding is consistent.
 */
export declare function resolveEnvirArg<OtherInfo>(args: readonly PotentiallyEmptyRArgument<OtherInfo & ParentInformation>[], data: DataflowProcessorInformation<OtherInfo & ParentInformation>, argName?: string, positionalFallbackIndex?: number, allParamNames?: readonly string[]): EnvirResolution<OtherInfo> | undefined;
/**
 * Resolves a symbol by name to an {@link EnvirResolution} when the symbol holds a tracked
 * environment.  Handles multiple reaching definitions (e.g. from if/else branches) by
 * merging their envStates - see {@link resolveDefsToEnvirResolution}.
 * Returns `undefined` when the name cannot be resolved or none of its definitions carry an envState.
 */
export declare function resolveSymbolToEnvir<OtherInfo>(symbolName: Identifier, nodeId: NodeId, data: DataflowProcessorInformation<OtherInfo & ParentInformation>): EnvirResolution<OtherInfo> | undefined;
/**
 * After processing an expression that writes into a custom environment, moves the
 * written definitions from the caller's scope into `envDef`'s tracked `envState`
 * and re-defines the holder variable in the returned environment.
 */
export declare function routeWrittenToCustomEnv(result: DataflowInformation, envDef: NamedInGraphIdentifierDefinition & {
    envState: REnvironmentInformation;
}, newDefAt: NodeId, definedAt?: NodeId): DataflowInformation;