@eagleoutice/flowr/abstract-interpretation/data-frame/mappers/arguments.d.ts

Static Dataflow Analyzer and Program Slicer for the R Programming Language

import type { ResolveInfo } from '../../../dataflow/eval/resolve/alias-tracking';
import type { DataflowGraph } from '../../../dataflow/graph/graph';
import { RNode } from '../../../r-bridge/lang-4.x/ast/model/model';
import type { RArgument } from '../../../r-bridge/lang-4.x/ast/model/nodes/r-argument';
import { type RFunctionArgument, type RFunctionCall, EmptyArgument } from '../../../r-bridge/lang-4.x/ast/model/nodes/r-function-call';
import type { RSymbol } from '../../../r-bridge/lang-4.x/ast/model/nodes/r-symbol';
import type { ParentInformation } from '../../../r-bridge/lang-4.x/ast/model/processing/decorate';
import { RNull } from '../../../r-bridge/lang-4.x/convert-values';
import type { RParseRequest } from '../../../r-bridge/retriever';
import type { DataFrameShapeInferenceVisitor } from '../shape-inference';
import { Identifier } from '../../../dataflow/environments/identifier';
/**
 * The location of a function parameter for mapping function call arguments to function parameters.
 * - `pos` contains the position of the function parameter (use `-1` for non-existent or non-positional arguments)
 * - `name` optionally contains the name of the function parameter
 * - `default` optionally contains the default value of the function parameter
 */
export interface FunctionParameterLocation<T = never> {
    pos: number;
    name?: string;
    default?: T;
}
/**
 * Escapes a regular expression given as string by escaping all special regular expression characters.
 * @param text        - The text to escape
 * @param allowTokens - Whether to allow and keep unescaped tokens like `\s`, `\t`, or `\n`
 * @returns The escaped text
 */
export declare function escapeRegExp(text: string, allowTokens?: boolean): string;
/**
 * Maps all invalid, duplicate, or empty column names to top depending on the provided arguments.
 * @param colnames     - The columns names to filter
 * @param checkNames   - Whether to map all invalid column names to top (`undefined`)
 * @param noDupNames   - Whether to map all duplicate column names to top (`undefined`)
 * @param noEmptyNames - Whether to map all empty column names to top (`undefined`)
 * @param collapseDups - Whether duplicate columns should be collapsed to single occurrences afterward (excluding `undefined` values)
 * @returns The filtered column names
 */
export declare function filterValidNames(colnames: (string | undefined)[] | undefined, checkNames?: boolean, noDupNames?: boolean, noEmptyNames?: boolean, collapseDups?: boolean): (string | undefined)[] | undefined;
/**
 * Gets the value of an argument that specified as {@link FunctionParameterLocation}.
 * @param args     - The arguments to get the requested argument from
 * @param argument - The specification of the argument to get the value for
 * @param info     - Argument resolve information
 * @returns The resolved value of the argument or `undefined`
 */
export declare function getArgumentValue<T>(args: readonly RFunctionArgument<ParentInformation>[], argument: FunctionParameterLocation<T> | string, info: ResolveInfo): string | number | boolean | (string | number | boolean)[] | T | undefined;
/**
 * Gets all effective argument from a list of arguments by removing all arguments whose names should be excluded.
 * @param args     - The list of arguments to filter
 * @param excluded - The names of the arguments to exclude
 * @returns The filtered list of arguments
 */
export declare function getEffectiveArgs(args: readonly RFunctionArgument<ParentInformation>[], excluded: string[]): readonly RFunctionArgument<ParentInformation>[];
/**
 * Gets an argument specified as {@link FunctionParameterLocation} from a list of arguments.
 * @param args     - The arguments to get the requested argument from
 * @param argument - The specification of the argument to get
 * @param info     - Argument resolve information
 * @returns An argument matching the specified `argument` or `undefined`
 */
export declare function getFunctionArgument(args: readonly RFunctionArgument<ParentInformation>[], argument: FunctionParameterLocation<unknown> | string, info: ResolveInfo): RFunctionArgument<ParentInformation> | undefined;
/**
 * Get all function arguments of a function call node in the data flow graph.
 * @param node - The function call node to get the arguments for
 * @param dfg  - The data flow graph for retrieving the arguments
 * @returns The arguments of the function call in the data flow graph
 */
export declare function getFunctionArguments(node: RFunctionCall<ParentInformation>, dfg: DataflowGraph): readonly RFunctionArgument<ParentInformation>[];
/**
 * Gets all nested symbols in an expression that have no outgoing edges in the data flow graph.
 * @param expression - The expression to get the symbols from
 * @param dfg        - The data flow graph for checking the outgoing edges
 * @returns The name of all unresolved symbols in the expression
 */
export declare function getUnresolvedSymbolsInExpression(expression: RNode<ParentInformation> | typeof EmptyArgument | undefined, dfg?: DataflowGraph): Identifier[];
/**
 * Checks whether a list of arguments contains any critical argument.
 * @param args     - The list of arguments to check
 * @param critical - The critical arguments to search for (as string or {@link FunctionParameterLocation}s)
 * @param info     - Argument resolve information
 * @returns Whether the arguments contain any critical argument
 */
export declare function hasCriticalArgument(args: readonly RFunctionArgument<ParentInformation>[], critical: (FunctionParameterLocation<unknown> | string)[] | undefined, info: ResolveInfo): boolean;
/**
 * Checks if a given argument has an inferred data frame shape and therefore represents a data frame
 * @param arg       - The argument to check
 * @param inference - The data frame shape inference visitor to use
 * @returns Whether the argument represents a data frame
 */
export declare function isDataFrameArgument(arg: RNode<ParentInformation> | undefined, inference: DataFrameShapeInferenceVisitor): arg is RNode<ParentInformation>;
export declare function isDataFrameArgument(arg: RFunctionArgument<ParentInformation> | undefined, inference: DataFrameShapeInferenceVisitor): arg is RArgument<ParentInformation> & {
    value: RNode<ParentInformation>;
};
/**
 * Checks whether a function argument is a names argument.
 */
export declare function isNamedArgument(arg: RFunctionArgument<ParentInformation> | undefined): arg is RArgument<ParentInformation> & {
    name: RSymbol<ParentInformation>;
};
/**
 * Checks whether a node is `NULL` in R (represents a `NULL` symbol).
 */
export declare function isRNull(node: RNode<ParentInformation> | undefined): node is RSymbol<ParentInformation, typeof RNull>;
export declare function isRNull(node: RFunctionArgument<ParentInformation> | undefined): node is RArgument<ParentInformation> & {
    value: RSymbol<ParentInformation, typeof RNull>;
};
/**
 * Checks whether a string is a valid columns name according to the flag `check.names` in R.
 */
export declare function isValidColName(colname: string | undefined): boolean;
/**
 * Parses a text of file parse request using the provided parser function.
 */
export declare function parseRequestContent(request: RParseRequest, parser: (line: Buffer | string, lineNumber: number) => void, maxLines?: number): boolean;