@eagleoutice/flowr

import { NodeId } from '../../r-bridge/lang-4.x/ast/model/processing/node-id'; import type { AstIdMap } from '../../r-bridge/lang-4.x/ast/model/processing/decorate'; import { type DataflowFunctionFlowInformation, DataflowGraph, FunctionArgument } from './graph'; import { type IEnvironment, type REnvironmentInformation } from '../environments/environment'; import { type DataflowGraphVertexFunctionDefinition, type DataflowGraphVertexArgument, type DataflowGraphVertexAstLink, type DataflowGraphVertexInfo, type DataflowGraphVertexUse, type FunctionOriginInformation } from './vertex'; import type { ControlDependency, ExitPoint } from '../info'; import type { LinkTo } from '../../queries/catalog/call-context-query/call-context-query-format'; import type { FlowrSearchLike } from '../../search/flowr-search-builder'; import type { ReadonlyFlowrAnalysisProvider } from '../../project/flowr-analyzer'; import type { HookInformation } from '../hooks'; /** * Creates an empty dataflow graph. * Should only be used in tests and documentation. */ export declare function emptyGraph(this: void, cleanEnv?: REnvironmentInformation, idMap?: AstIdMap): DataflowGraphBuilder<DataflowGraphVertexInfo>; export type DataflowGraphEdgeTarget = NodeId | (readonly NodeId[]); /** * This DataflowGraphBuilder extends {@link DataflowGraph} with builder methods to * easily and compactly add vertices and edges to a dataflow graph. Its usage thus * simplifies writing tests for dataflow graphs. */ export declare class DataflowGraphBuilder<Vertex extends DataflowGraphVertexInfo = DataflowGraphVertexInfo> extends DataflowGraph { private readonly defaultEnvironment; constructor(cleanEnv?: REnvironmentInformation, idMap?: AstIdMap); addVertexWithDefaultEnv(vertex: DataflowGraphVertexArgument & Omit<Vertex, keyof DataflowGraphVertexArgument>, asRoot?: boolean, overwrite?: boolean): this; /** * Adds a **vertex** for a **function definition** (V1). * @param id - AST node ID * @param subflow - Subflow data graph for the defined function. * @param exitPoints - Node IDs for exit point vertices. * @param info - Additional/optional properties. * @param asRoot - should the vertex be part of the root vertex set of the graph * (i.e., be a valid entry point), or is it nested (e.g., as part of a function definition) */ defineFunction(id: NodeId, exitPoints: readonly ExitPoint[] | readonly NodeId[], subflow: Omit<DataflowFunctionFlowInformation, 'hooks'> & { hooks?: HookInformation[]; }, info?: { environment?: REnvironmentInformation; builtInEnvironment?: IEnvironment; cds?: ControlDependency[]; readParams?: [NodeId, boolean][]; mode?: DataflowGraphVertexFunctionDefinition['mode']; }, asRoot?: boolean): this; /** * Adds a **vertex** for a **function call** (V2). * @param id - AST node ID * @param name - Function name * @param args - Function arguments; may be empty * @param info - Additional/optional properties. * @param asRoot - should the vertex be part of the root vertex set of the graph * (i.e., be a valid entry point), or is it nested (e.g., as part of a function definition) */ call(id: NodeId, name: string, args: FunctionArgument[], info?: { returns?: readonly NodeId[]; reads?: readonly NodeId[]; onlyBuiltIn?: boolean; environment?: REnvironmentInformation; builtInEnvironment?: IEnvironment; cds?: ControlDependency[]; origin?: FunctionOriginInformation[]; link?: DataflowGraphVertexAstLink; omitArgs?: boolean; }, asRoot?: boolean): this; /** automatically adds argument links if they do not already exist */ private addArgumentLinks; /** * Adds a **vertex** for a **variable definition** (V4). * @param id - AST node ID * @param name - Variable name * @param info - Additional/optional properties. * @param asRoot - Should the vertex be part of the root vertex set of the graph * (i.e., be a valid entry point), or is it nested (e.g., as part of a function definition) */ defineVariable(id: NodeId, name?: string, info?: { cds?: ControlDependency[]; definedBy?: NodeId[]; }, asRoot?: boolean): this; /** * Adds a **vertex** for **variable use** (V5). Intended for creating dataflow graphs as part of function tests. * @param id - AST node id * @param name - Variable name * @param info - Additional/optional properties; i.e., scope, when, or environment. * @param asRoot - should the vertex be part of the root vertex set of the graph * (i.e., be a valid entry point) or is it nested (e.g., as part of a function definition) */ use(id: NodeId, name?: string, info?: Partial<DataflowGraphVertexUse>, asRoot?: boolean): this; /** * Adds a **vertex** for a **constant value** (V6). * @param id - AST node ID * @param options - Additional/optional properties; * @param asRoot - should the vertex be part of the root vertex set of the graph * (i.e., be a valid entry point), or is it nested (e.g., as part of a function definition) */ constant(id: NodeId, options?: { cds?: ControlDependency[]; }, asRoot?: boolean): this; private edgeHelper; private queryHelper; /** * Adds a **read edge**. * @param from - NodeId of the source vertex * @param to - Either a single or multiple target ids. * If you pass multiple this will construct a single edge for each of them. */ reads(from: NodeId, to: DataflowGraphEdgeTarget): this; /** * Adds a **read edge** with a query for the from and/or to vertices. * @param from - Either a node id or a query to find the node id. * @param to - Either a node id or a query to find the node id. * @param input - The input to search in i.e. the dataflow graph. */ readsQuery(from: FromQueryParam, to: ToQueryParam, input: ReadonlyFlowrAnalysisProvider): Promise<this>; /** * Adds a **defined-by edge** with from as defined variable, and to * as a variable/function contributing to its definition. * @see {@link DataflowGraphBuilder#reads|reads} for parameters. */ definedBy(from: NodeId, to: DataflowGraphEdgeTarget): this; /** * Adds a **defined-by edge** with a query for the from and/or to vertices. * @see {@link DataflowGraphBuilder#readsQuery|readsQuery} for parameters. */ definedByQuery(from: FromQueryParam, to: ToQueryParam, data: ReadonlyFlowrAnalysisProvider): Promise<this>; /** * Adds a **call edge** with from as caller, and to as callee. * @see {@link DataflowGraphBuilder#reads|reads} for parameters. */ calls(from: NodeId, to: DataflowGraphEdgeTarget): this; /** * Adds a **call edge** with a query for the from and/or to vertices. * @see {@link DataflowGraphBuilder#readsQuery|readsQuery} for parameters. */ callsQuery(from: FromQueryParam, to: ToQueryParam, data: ReadonlyFlowrAnalysisProvider): Promise<this>; /** * Adds a **return edge** with from as function, and to as exit point. * @see {@link DataflowGraphBuilder#reads|reads} for parameters. */ returns(from: NodeId, to: DataflowGraphEdgeTarget): this; /** * Adds a **return edge** with a query for the from and/or to vertices. * @see {@link DataflowGraphBuilder#readsQuery|readsQuery} for parameters. */ returnsQuery(from: FromQueryParam, to: ToQueryParam, data: ReadonlyFlowrAnalysisProvider): Promise<this>; /** * Adds a **defines-on-call edge** with from as variable, and to as its definition * @see {@link DataflowGraphBuilder#reads|reads} for parameters. */ definesOnCall(from: NodeId, to: DataflowGraphEdgeTarget): this; /** * Adds a **defines-on-call edge** with a query for the from and/or to vertices. * @see {@link DataflowGraphBuilder#readsQuery|readsQuery} for parameters. */ definesOnCallQuery(from: FromQueryParam, to: ToQueryParam, data: ReadonlyFlowrAnalysisProvider): Promise<this>; /** * Adds a **defined-by-on-call edge** with from as definition, and to as variable. * @see {@link DataflowGraphBuilder#reads|reads} for parameters. */ definedByOnCall(from: NodeId, to: DataflowGraphEdgeTarget): this; /** * Adds a **defined-by-on-call edge** with a query for the from and/or to vertices. * @see {@link DataflowGraphBuilder#readsQuery|readsQuery} for parameters. */ definedByOnCallQuery(from: FromQueryParam, to: ToQueryParam, data: ReadonlyFlowrAnalysisProvider): Promise<this>; /** * Adds an **argument edge** with from as function call, and to as argument. * @see {@link DataflowGraphBuilder#reads|reads} for parameters. */ argument(from: NodeId, to: DataflowGraphEdgeTarget): this; /** * Adds a **argument edge** with a query for the from and/or to vertices. * @see {@link DataflowGraphBuilder#readsQuery|readsQuery} for parameters. */ argumentQuery(from: FromQueryParam, to: ToQueryParam, data: ReadonlyFlowrAnalysisProvider): Promise<this>; /** * Adds a **non-standard evaluation edge** with from as vertex, and to as vertex. * @see {@link DataflowGraphBuilder#reads|reads} for parameters. */ nse(from: NodeId, to: DataflowGraphEdgeTarget): this; /** * Adds a **non-standard evaluation edge** with a query for the from and/or to vertices. * @see {@link DataflowGraphBuilder#readsQuery|readsQuery} for parameters. */ nseQuery(from: FromQueryParam, to: ToQueryParam, data: ReadonlyFlowrAnalysisProvider): Promise<this>; /** * Adds a **side-effect-on-call edge** with from as vertex, and to as vertex. * @see {@link DataflowGraphBuilder#reads|reads} for parameters. */ sideEffectOnCall(from: NodeId, to: DataflowGraphEdgeTarget): this; /** * Adds a **side-effect-on-call edge** with a query for the from and/or to vertices. * @see {@link DataflowGraphBuilder#readsQuery|readsQuery} for parameters. */ sideEffectOnCallQuery(from: FromQueryParam, to: ToQueryParam, data: ReadonlyFlowrAnalysisProvider): Promise<this>; /** * explicitly overwrite the root ids of the graph, * this is just an easier variant in case you working with a lot of functions this saves you a lot of `false` flags. */ overwriteRootIds(ids: readonly NodeId[]): this; } /** * */ export declare function getBuiltInSideEffect(name: string): LinkTo<RegExp> | undefined; interface Query { query: FlowrSearchLike; } type FromQueryParam = { nodeId: NodeId; } | Query; type ToQueryParam = { target: DataflowGraphEdgeTarget; } | Query; export {};