@eagleoutice/flowr
Version:
Static Dataflow Analyzer and Program Slicer for the R Programming Language
219 lines (218 loc) • 10 kB
TypeScript
import type { 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, FunctionArgument } from './graph';
import { DataflowGraph } from './graph';
import type { REnvironmentInformation } from '../environments/environment';
import type { DataflowGraphVertexUse } from './vertex';
import type { ControlDependency } 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 { Pipeline } from '../../core/steps/pipeline/pipeline';
import type { FlowrSearchInput } from '../../search/flowr-search';
export declare function emptyGraph(idMap?: AstIdMap): DataflowGraphBuilder;
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 extends DataflowGraph {
/**
* 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 NodeId[], subflow: DataflowFunctionFlowInformation, info?: {
environment?: REnvironmentInformation;
controlDependencies?: ControlDependency[];
}, 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;
controlDependencies?: ControlDependency[];
}, 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?: {
controlDependencies?: 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?: {
controlDependencies?: 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 data - The data to search in i.e. the dataflow graph.
*/
readsQuery<P extends Pipeline>(from: FromQueryParam, to: ToQueryParam, data: FlowrSearchInput<P>): 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<P extends Pipeline>(from: FromQueryParam, to: ToQueryParam, data: FlowrSearchInput<P>): 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<P extends Pipeline>(from: FromQueryParam, to: ToQueryParam, data: FlowrSearchInput<P>): 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<P extends Pipeline>(from: FromQueryParam, to: ToQueryParam, data: FlowrSearchInput<P>): 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<P extends Pipeline>(from: FromQueryParam, to: ToQueryParam, data: FlowrSearchInput<P>): 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<P extends Pipeline>(from: FromQueryParam, to: ToQueryParam, data: FlowrSearchInput<P>): 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<P extends Pipeline>(from: FromQueryParam, to: ToQueryParam, data: FlowrSearchInput<P>): 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<P extends Pipeline>(from: FromQueryParam, to: ToQueryParam, data: FlowrSearchInput<P>): 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<P extends Pipeline>(from: FromQueryParam, to: ToQueryParam, data: FlowrSearchInput<P>): 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 {};