@eagleoutice/flowr-dev/dataflow/environments/built-in.d.ts

Static Dataflow Analyzer and Program Slicer for the R Programming Language

import type { DataflowProcessorInformation } from '../processor';
import type { DataflowInformation, ExitPointType } from '../info';
import { NseArguments } from '../internal/process/functions/call/known-call-handling';
import { processAccess } from '../internal/process/functions/call/built-in/built-in-access';
import { processIfThenElse } from '../internal/process/functions/call/built-in/built-in-if-then-else';
import { processAssignment, processAssignmentLike, processDefineArgument } from '../internal/process/functions/call/built-in/built-in-assignment';
import { processSpecialBinOp } from '../internal/process/functions/call/built-in/built-in-special-bin-op';
import { processPipe } from '../internal/process/functions/call/built-in/built-in-pipe';
import { processForLoop } from '../internal/process/functions/call/built-in/built-in-for-loop';
import { processRepeatLoop } from '../internal/process/functions/call/built-in/built-in-repeat-loop';
import { processWhileLoop } from '../internal/process/functions/call/built-in/built-in-while-loop';
import { type BrandedIdentifier, type IdentifierDefinition, type IdentifierReference, ReferenceType } from './identifier';
import { processReplacementFunction } from '../internal/process/functions/call/built-in/built-in-replacement';
import { processQuote } from '../internal/process/functions/call/built-in/built-in-quote';
import { processFunctionDefinition } from '../internal/process/functions/call/built-in/built-in-function-definition';
import { processExpressionList } from '../internal/process/functions/call/built-in/built-in-expression-list';
import { processGet } from '../internal/process/functions/call/built-in/built-in-get';
import type { ParentInformation, RNodeWithParent } 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 { RSymbol } from '../../r-bridge/lang-4.x/ast/model/nodes/r-symbol';
import { type BuiltIn, NodeId } from '../../r-bridge/lang-4.x/ast/model/processing/node-id';
import { processLibrary } from '../internal/process/functions/call/built-in/built-in-library';
import { processSourceCall } from '../internal/process/functions/call/built-in/built-in-source';
import type { ForceArguments } from '../internal/process/functions/call/common';
import { processApply } from '../internal/process/functions/call/built-in/built-in-apply';
import type { LinkTo } from '../../queries/catalog/call-context-query/call-context-query-format';
import { processList } from '../internal/process/functions/call/built-in/built-in-list';
import { processVector } from '../internal/process/functions/call/built-in/built-in-vector';
import { processRm } from '../internal/process/functions/call/built-in/built-in-rm';
import { processEvalCall } from '../internal/process/functions/call/built-in/built-in-eval';
import type { Value } from '../eval/values/r-value';
import type { ResolveInfo } from '../eval/resolve/alias-tracking';
import { resolveAsSeq, resolveAsVector } from '../eval/resolve/resolve';
import { resolveAsStringFn } from '../eval/resolve/resolve-strings';
import { resolveAsComparison, resolveAsGroup, resolveAsLogical } from '../eval/resolve/resolve-operators';
import { resolveAsNumeric } from '../eval/resolve/resolve-numbers';
import type { VariableResolve } from '../../config';
import type { BuiltInConstantDefinition, BuiltInDefinition, BuiltInFunctionDefinition, BuiltInReplacementDefinition } from './built-in-config';
import { processStopIfNot } from '../internal/process/functions/call/built-in/built-in-stop-if-not';
import { processTryCatch } from '../internal/process/functions/call/built-in/built-in-try-catch';
import { processRegisterHook } from '../internal/process/functions/call/built-in/built-in-register-hook';
import { processLocal } from '../internal/process/functions/call/built-in/built-in-local';
import { processS3Dispatch } from '../internal/process/functions/call/built-in/built-in-s-three-dispatch';
import { processRecall } from '../internal/process/functions/call/built-in/built-in-recall';
import { processS7NewGeneric, processMakeConstructor } from '../internal/process/functions/call/built-in/built-in-s-seven-new-generic';
import { processS7Dispatch } from '../internal/process/functions/call/built-in/built-in-s-seven-dispatch';
import { BuiltInProcName } from './built-in-proc-name';
import { processPurrrFormula } from '../internal/process/functions/call/built-in/built-in-purrr-formula';
import { processNewEnv } from '../internal/process/functions/call/built-in/built-in-new-env';
import { processClassGenerator } from '../internal/process/functions/call/built-in/built-in-class-generator';
import { processStackEnv } from '../internal/process/functions/call/built-in/built-in-stack-env';
import { processAttach } from '../internal/process/functions/call/built-in/built-in-attach';
import { processWithEnv } from '../internal/process/functions/call/built-in/built-in-with';
import { processNamespaceAccess } from '../internal/process/functions/call/built-in/built-in-namespace-access';
import { processLoadCall } from '../internal/process/functions/call/built-in/built-in-load';
import { processStringTemplate } from '../internal/process/functions/call/built-in/built-in-string-template';
import { type BuiltInFnInfo } from './built-in-props';
export type BuiltInIdentifierProcessor = <OtherInfo>(name: RSymbol<OtherInfo & ParentInformation>, args: readonly PotentiallyEmptyRArgument<OtherInfo & ParentInformation>[], rootId: NodeId, data: DataflowProcessorInformation<OtherInfo & ParentInformation>) => DataflowInformation;
export type BuiltInIdentifierProcessorWithConfig<Config> = <OtherInfo>(name: RSymbol<OtherInfo & ParentInformation>, args: readonly PotentiallyEmptyRArgument<OtherInfo & ParentInformation>[], rootId: NodeId, data: DataflowProcessorInformation<OtherInfo & ParentInformation>, config: Config) => DataflowInformation;
export interface BuiltInIdentifierDefinition extends IdentifierReference {
    type: ReferenceType.BuiltInFunction;
    definedAt: BuiltIn;
    processor: BuiltInIdentifierProcessor;
    config?: ConfigOfBuiltInMappingName<keyof typeof BuiltInProcessorMapper> & BuiltInFnInfo & {
        libFn?: boolean;
    };
    /** folds a call to this function to a constant, see {@link BuiltInEvalHandlerMapper} */
    evalHandler?: BuiltInEvalHandler;
}
/**
 * Whether the definition states that the call does not evaluate some of its arguments the standard way, either
 * by quoting them or by handing them a data mask. Only such a definition changes what the arguments read, so
 * only it has to run in place of the default processor.
 */
export declare function statesNonStandardEvaluation(definition: BuiltInIdentifierDefinition | undefined): boolean;
export interface BuiltInIdentifierConstant<T = unknown> extends IdentifierReference {
    type: ReferenceType.BuiltInConstant;
    definedAt: BuiltIn;
    value: T;
}
export interface DefaultBuiltInProcessorConfiguration extends ForceArguments, BuiltInFnInfo {
    readonly cfg?: ExitPointType;
    readonly readAllArguments?: boolean;
    /**
     * Propagate the `out` references produced by the arguments instead of dropping them.
     * Set this for functions that are transparent about their arguments, like `(`.
     */
    readonly keepArgumentOut?: boolean;
    readonly hasUnknownSideEffects?: boolean | LinkTo<RegExp | string>;
    /** record mapping the actual function name called to the arguments that should be treated as function calls */
    readonly treatAsFnCall?: Record<string, readonly string[]>;
    /** Mark the given arguments as {@link EdgeType.NonStandardEvaluation|non-standard-evaluated}, like `quote`. */
    readonly markArgsAsNSE?: NseArguments | readonly number[];
    /**
     * Mark the given arguments as evaluated in a data mask, like `subset`: their symbols may name columns of the
     * data instead of variables, while everything else in them is evaluated in the caller's frame as usual.
     */
    readonly markArgsAsMasked?: NseArguments | readonly number[];
    /**
     * Name that should be used for the origin (useful when needing to differentiate between
     * functions like 'return' that use the default builtin processor)
     */
    readonly useAsProcessor?: BuiltInProcName;
}
/** the {@link ResolveInfo} a handler continues to resolve with, plus the node it is asked to fold */
export interface BuiltInEvalHandlerArgs extends ResolveInfo {
    resolve: VariableResolve;
    node: RNodeWithParent;
}
export type BuiltInEvalHandler = (args: BuiltInEvalHandlerArgs) => Value;
declare function defaultBuiltInProcessor<OtherInfo>(name: RSymbol<OtherInfo & ParentInformation>, args: readonly PotentiallyEmptyRArgument<OtherInfo & ParentInformation>[], rootId: NodeId, data: DataflowProcessorInformation<OtherInfo & ParentInformation>, { useAsProcessor, forceArgs, readAllArguments, cfg, hasUnknownSideEffects, treatAsFnCall, markArgsAsNSE: nse, markArgsAsMasked: masked, keepArgumentOut, sig }: DefaultBuiltInProcessorConfiguration): DataflowInformation;
declare function defaultBuiltInProcessorReadallArgs<OtherInfo>(name: RSymbol<OtherInfo & ParentInformation>, args: readonly PotentiallyEmptyRArgument<OtherInfo & ParentInformation>[], rootId: NodeId, data: DataflowProcessorInformation<OtherInfo & ParentInformation>, { useAsProcessor, forceArgs, markArgsAsNSE: nse, markArgsAsMasked: masked, sig }: Pick<DefaultBuiltInProcessorConfiguration, 'useAsProcessor' | 'forceArgs' | 'markArgsAsNSE' | 'markArgsAsMasked' | 'sig'>): DataflowInformation;
export declare const BuiltInProcessorMapper: {
    readonly "builtin:acc": typeof processAccess;
    readonly "builtin:app": typeof processApply;
    readonly "builtin:assign": typeof processAssignment;
    readonly "builtin:assign-l": typeof processAssignmentLike;
    readonly "builtin:define-arg": typeof processDefineArgument;
    readonly "builtin:d": typeof defaultBuiltInProcessor;
    readonly "builtin:d-ra": typeof defaultBuiltInProcessorReadallArgs;
    readonly "builtin:string-template": typeof processStringTemplate;
    readonly "builtin:eval": typeof processEvalCall;
    readonly "builtin:el": typeof processExpressionList;
    readonly "builtin:fl": typeof processForLoop;
    readonly "builtin:f-def": typeof processFunctionDefinition;
    readonly "builtin:get": typeof processGet;
    readonly "builtin:ite": typeof processIfThenElse;
    readonly "builtin:lib": typeof processLibrary;
    readonly "builtin:list": typeof processList;
    readonly "builtin:load": typeof processLoadCall;
    readonly "builtin:local": typeof processLocal;
    readonly "builtin:ns-access": typeof processNamespaceAccess;
    readonly "builtin:pipe": typeof processPipe;
    readonly "builtin:purrr-f": typeof processPurrrFormula;
    readonly "builtin:quote": typeof processQuote;
    readonly "builtin:recall": typeof processRecall;
    readonly "builtin:r-hook": typeof processRegisterHook;
    readonly "builtin:rl": typeof processRepeatLoop;
    readonly "builtin:repl": typeof processReplacementFunction;
    readonly "builtin:rm": typeof processRm;
    readonly "builtin:s3-dp": typeof processS3Dispatch;
    readonly "builtin:s7-new-generic": typeof processS7NewGeneric;
    readonly "builtin:s7-make-constructor": typeof processMakeConstructor;
    readonly "builtin:s7-dispatch": typeof processS7Dispatch;
    readonly "builtin:source": typeof processSourceCall;
    readonly "builtin:s-bop": typeof processSpecialBinOp;
    readonly "builtin:stopifnot": typeof processStopIfNot;
    readonly "builtin:try": typeof processTryCatch;
    readonly "builtin:attach": typeof processAttach;
    readonly "builtin:nenv": typeof processNewEnv;
    readonly "builtin:class-gen": typeof processClassGenerator;
    readonly "builtin:stack-env": typeof processStackEnv;
    readonly "builtin:with": typeof processWithEnv;
    readonly "builtin:vector": typeof processVector;
    readonly "builtin:wl": typeof processWhileLoop;
};
/**
 * The value-solver function behind every {@link BuiltInEvalName}, the counterpart of the {@link BuiltInProcessorMapper}.
 * A built-in picks one of these by name with its serializable {@link BuiltInFunctionDefinition#evalHandler}.
 */
export declare const BuiltInEvalHandlerMapper: {
    readonly "eval:vector": typeof resolveAsVector;
    readonly "eval:seq": typeof resolveAsSeq;
    readonly "eval:numeric": typeof resolveAsNumeric;
    readonly "eval:cmp": typeof resolveAsComparison;
    readonly "eval:logical": typeof resolveAsLogical;
    readonly "eval:string-fn": typeof resolveAsStringFn;
    readonly "eval:group": typeof resolveAsGroup;
};
export type ConfigOfBuiltInMappingName<N extends keyof typeof BuiltInProcessorMapper> = Parameters<typeof BuiltInProcessorMapper[N]>[4];
export type BuiltInMemory = Map<BrandedIdentifier, IdentifierDefinition[]>;
export declare class BuiltIns {
    /**
     * Register a built-in constant (like `NULL` or `TRUE`) to the given {@link BuiltIns}
     */
    registerBuiltInConstant<T>({ names, value, assumePrimitive }: BuiltInConstantDefinition<T>): void;
    /**
     * Register a built-in function (like `print` or `c`) to the given {@link BuiltIns}
     */
    registerBuiltInFunctions<BuiltInProcessor extends keyof typeof BuiltInProcessorMapper>({ names, processor, config, assumePrimitive, evalHandler }: BuiltInFunctionDefinition<BuiltInProcessor>): void;
    /**
     * Registers all combinations of replacements
     */
    registerReplacementFunctions({ names, suffixes, assumePrimitive, config }: BuiltInReplacementDefinition): void;
    /**
     * Register a single {@link BuiltInDefinition} to the given memories in {@link BuiltIns}
     */
    registerBuiltInDefinition(definition: BuiltInDefinition): void;
    /**
     * The built-in {@link REnvironmentInformation|environment} is the root of all environments.
     *
     * For its default content (when not overwritten by a flowR config),
     * see the {@link DefaultBuiltinConfig}.
     */
    builtInMemory: BuiltInMemory;
    /**
     * The twin of the {@link builtInMemory} but with less built ins defined for
     * cases in which we want some commonly overwritten variables to remain open.
     * If you do not know if you need the empty environment, you do not need the empty environment (right now).
     * @see {@link builtInMemory}
     */
    emptyBuiltInMemory: BuiltInMemory;
    set(identifier: BrandedIdentifier, definition: IdentifierDefinition[], includeInEmptyMemory: boolean | undefined): void;
}
export {};