@eagleoutice/flowr-dev
Version:
Static Dataflow Analyzer and Program Slicer for the R Programming Language
1,176 lines • 81.4 kB
JavaScript
"use strict";
var __importDefault = (this && this.__importDefault) || function (mod) {
return (mod && mod.__esModule) ? mod : { "default": mod };
};
Object.defineProperty(exports, "__esModule", { value: true });
exports.WikiDataflowGraph = void 0;
const graph_1 = require("../dataflow/graph/graph");
const quoted_1 = require("../dataflow/internal/process/functions/call/quoted");
const nse_1 = require("../dataflow/internal/process/functions/call/nse");
const deferred_1 = require("../dataflow/internal/process/functions/call/deferred");
const doc_query_1 = require("./doc-util/doc-query");
const vertex_1 = require("../dataflow/graph/vertex");
const edge_1 = require("../dataflow/graph/edge");
const dataflowgraph_builder_1 = require("../dataflow/graph/dataflowgraph-builder");
const assert_1 = require("../util/assert");
const doc_dfg_1 = require("./doc-util/doc-dfg");
const doc_files_1 = require("./doc-util/doc-files");
const json_1 = require("../util/json");
const doc_env_1 = require("./doc-util/doc-env");
const doc_data_dfg_util_1 = require("./data/dfg/doc-data-dfg-util");
const doc_cli_option_1 = require("./doc-util/doc-cli-option");
const doc_types_1 = require("./doc-util/doc-types");
const doc_structure_1 = require("./doc-util/doc-structure");
const doc_code_1 = require("./doc-util/doc-code");
const path_1 = __importDefault(require("path"));
const doc_general_1 = require("./doc-util/doc-general");
const node_id_1 = require("../r-bridge/lang-4.x/ast/model/processing/node-id");
const identifier_1 = require("../dataflow/environments/identifier");
const r_function_call_1 = require("../r-bridge/lang-4.x/ast/model/nodes/r-function-call");
const default_pipelines_1 = require("../core/steps/pipeline/default-pipelines");
const text_1 = require("../util/text/text");
const linker_1 = require("../dataflow/internal/linker");
const apply_kill_1 = require("../dataflow/environments/apply-kill");
const doc_normalized_ast_1 = require("./doc-util/doc-normalized-ast");
const identify_link_to_last_call_relation_1 = require("../queries/catalog/call-context-query/identify-link-to-last-call-relation");
const alias_tracking_1 = require("../dataflow/eval/resolve/alias-tracking");
const doc_issue_1 = require("./doc-util/doc-issue");
const unnamed_call_handling_1 = require("../dataflow/internal/process/functions/call/unnamed-call-handling");
const environment_builder_1 = require("../../test/functionality/_helper/dataflow/environment-builder");
const flowr_analyzer_builder_1 = require("../project/flowr-analyzer-builder");
const flowr_analyzer_context_1 = require("../project/context/flowr-analyzer-context");
const doc_maker_1 = require("./wiki-mk/doc-maker");
const flowr_analyzer_1 = require("../project/flowr-analyzer");
const dfg_1 = require("../util/mermaid/dfg");
const mermaid_1 = require("../util/mermaid/mermaid");
const r_number_1 = require("../r-bridge/lang-4.x/ast/model/nodes/r-number");
const model_1 = require("../r-bridge/lang-4.x/ast/model/model");
const range_1 = require("../util/range");
const df_helper_1 = require("../dataflow/graph/df-helper");
const resolve_helper_1 = require("../dataflow/environments/resolve-helper");
const built_in_proc_name_1 = require("../dataflow/environments/built-in-proc-name");
const vertex_2 = require("../dataflow/graph/vertex");
async function subExplanation(parser, ctx, { description, code, expectedSubgraph }) {
expectedSubgraph = await (0, doc_dfg_1.verifyExpectedSubgraph)(parser, code, expectedSubgraph);
const marks = [];
for (const [id] of expectedSubgraph.vertices(true)) {
marks.push(id);
}
for (const [from, targets] of expectedSubgraph.edges()) {
for (const [to] of targets) {
marks.push(`${from}->${to}`);
}
}
return `
${await (0, doc_dfg_1.printDfGraphForCode)(parser, code, { mark: new Set(marks), ctx })}
${description}`;
}
async function printAllSubExplanations(parser, ctx, expls) {
let result = `
<details>
<summary>Additional Case${expls.length > 1 ? 's' : ''}</summary>
`;
for (const sub of expls) {
result += `#### ${sub.name}\n`;
result += await subExplanation(parser, ctx, sub) + '\n';
}
return result + '\n\n</details>';
}
async function explanation({ name, type, description, code, expectedSubgraph }, parser, ctx, index, ...subExplanations) {
await (0, doc_dfg_1.verifyExpectedSubgraph)(parser, code, expectedSubgraph);
return `
<a id='${name.toLowerCase().replaceAll(' ', '-')}'> </a>
<a id='${String(type).toLowerCase().replaceAll(' ', '-')}-vertex'> </a>
### ${index}) ${name}
Type: \`${type}\` (this is the bit-flag value, e.g., when looking at the serialization)
${await subExplanation(parser, ctx, { name, description, code, expectedSubgraph })}
${subExplanations.length > 0 ? await printAllSubExplanations(parser, ctx, subExplanations) : ''}
`;
}
function edgeTypeToId(edgeType) {
return edge_1.DfEdge.typeToName(edgeType).toLowerCase().replaceAll(' ', '-');
}
function linkEdgeName(edgeType, page = '') {
return `[\`${edge_1.DfEdge.typeToName(edgeType)}\`](${page}#${edgeTypeToId(edgeType)})`;
}
async function getVertexExplanations(parser, ctx) {
/* we use the map to ensure order easily :D */
const vertexExplanations = new Map();
vertexExplanations.set(vertex_1.VertexType.Value, [{
name: 'Value Vertex',
type: vertex_1.VertexType.Value,
description: `
Describes a constant value (numbers, booleans/logicals, strings, ...).
In general, the respective vertex is more or less a dummy vertex as you can see from its implementation.
${ctx.hierarchy('DataflowGraphVertexValue')}
${(0, doc_structure_1.block)({
type: 'NOTE',
content: `
The value is not stored in the vertex itself, but in the normalized AST.
To access the value, you can use the \`id\` of the vertex to access the respective node in the ${ctx.linkPage('wiki/Normalized AST', 'normalized AST')}
and ask for the value associated with it.
`
})}
Please be aware that such nodes may be the result from language semantics as well, and not just from constants directly in the source.
For example, an access operation like \`df$column\` will treat the column name as a constant value.
${(0, doc_structure_1.details)('Example: Semantics Create a Value', `In the following graph, the original type printed by mermaid is still \`RSymbol\` (from the ${ctx.linkPage('wiki/Normalized AST', 'normalized AST')}), however, the shape of the vertex signals to you that the symbol is in-fact treated as a constant! If you do not know what \`df$column\` even means, please refer to the [R topic](https://rdrr.io/r/base/Extract.html).\n` +
await (0, doc_dfg_1.printDfGraphForCode)(parser, 'df$column', { mark: new Set([1]), ctx }))}
`,
code: '42',
expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().constant('0')
}, []]);
vertexExplanations.set(vertex_1.VertexType.Use, [{
name: 'Use Vertex',
type: vertex_1.VertexType.Use,
description: `
Describes symbol/variable references which are read (or potentially read at a given position).
Similar to the [value vertex](#value-vertex) described above, this is more a marker vertex as
you can see from the implementation.
${ctx.hierarchy('DataflowGraphVertexUse')}
${(0, doc_structure_1.block)({
type: 'NOTE',
content: `
The name of the symbol is not actually part of what we store in the dataflow graph,
as we have it within the normalized AST.
To access the name, you can use the \`id\` of the vertex:
${(0, doc_code_1.codeBlock)('ts', `const name = ${node_id_1.recoverName.name}(id, graph.idMap);`)}
`
})}
Most often, you will see the _use_ vertex whenever a variable is read.
However, similar to the [value vertex](#value-vertex), the _use_ vertex can also be the result of language semantics.
Consider a case, in which we refer to a variable with a string, as in \`get("x")\`.
${(0, doc_structure_1.details)('Example: Semantics Create a Symbol', `In the following graph, the original type printed by mermaid is still \`RString\` (from the ${ctx.linkPage('wiki/Normalized AST', 'normalized AST')}), however, the shape of the vertex signals to you that the symbol is in-fact treated as a variable use! ` +
'If you are unsure what `get` does, refer to the [documentation](https://www.rdocumentation.org/packages/base/versions/3.6.2/topics/get). ' +
'Please note, that the lexeme being printed as `"x"` may be misleading (after all it is recovered from the AST), the quotes are not part of the reference.\n' +
await (0, doc_dfg_1.printDfGraphForCode)(parser, 'get("x")', { mark: new Set([1]), ctx }))}
But now to the interesting stuff: how do we actually know which values are read by the respective variable use?
This usually involves a [variable definition](#variable-definition-vertex) and a [reads edge](#reads-edge) linking the two.
${(0, doc_structure_1.details)('Example: Reads Edge Identifying a Single Definition', 'In the following graph, the `x` is read from the definition `x <- 1`.\n' +
await (0, doc_dfg_1.printDfGraphForCode)(parser, 'x <- 1\nprint(x)', { mark: new Set([3, '0->3']), codeOpen: true, ctx }))}
In general, there may be many such edges, identifying every possible definition of the variable.
${(0, doc_structure_1.details)('Example: Reads Edge Identifying Multiple Definitions (conditional)', await (0, doc_dfg_1.printDfGraphForCode)(parser, 'x <- 1\nif(u) x <- 2\nprint(x)', { mark: new Set([10, '10->0', '10->4']), codeOpen: true, ctx }))}
${(0, doc_structure_1.details)('Example: Reads Edge Identifying Multiple Definitions (loop)', await (0, doc_dfg_1.printDfGraphForCode)(parser, 'x <- 1\nfor(i in v) x <- 2\nprint(x)', { mark: new Set([11, '11->0', '11->5']), codeOpen: true, ctx }))}
${(0, doc_structure_1.details)('Example: Reads Edge Identifying Multiple Definitions (side-effect)', await (0, doc_dfg_1.printDfGraphForCode)(parser, 'f <- function() x <<- 2\nx <- 2\nif(u) f()\nprint(x)', { mark: new Set([16, '16->1', '16->7']), codeOpen: true, ctx }))}
${(0, doc_structure_1.block)({
type: 'IMPORTANT',
content: `
If you want to obtain the locations where a variable is defined, or read, or re-defined, refrain from tracking these details manually in the dataflow graph
as there are some edge-cases that require special attention.
In general, the ${ctx.link(df_helper_1.Dataflow.origin)} (which is also available as ${ctx.linkO(df_helper_1.Dataflow, 'origin')}) function explained below in ${ctx.linkPage('wiki/Dataflow Graph', 'working with the dataflow graph', 'dfg-working')} will help you to get the information you need.
`
})}
`,
code: 'x',
expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().use('1@x', 'x')
}, []]);
vertexExplanations.set(vertex_1.VertexType.FunctionCall, [{
name: 'Function Call Vertex',
type: vertex_1.VertexType.FunctionCall,
description: `
Describes any kind of function call, including unnamed calls and those that happen implicitly!
In general the vertex provides you with information about
the _name_ of the called function, the passed _arguments_, and the _environment_ in which the call happens (if it is of importance).
Whenever flowR can determine which package a call resolves to — via a loaded \`library()\`/\`::\`, or via the always-available base-R packages taken from the ${ctx.linkPage('wiki/Signature Database', 'signature database')} — the mermaid visualization prints the **package-qualified name** in place of the bare one (e.g. \`acf\` is shown as \`stats::acf\`). To obtain this qualified identifier programmatically, prefer ${ctx.linkO(df_helper_1.Dataflow, 'qualify')} which, given only a call's id and its graph, reconstructs the \`pkg::fn\` identifier from the origins (and, for base R, from the exporting package) — the compact form of \`Identifier.toQualified\` (see the \`origin\` property below and the ${ctx.linkPage('wiki/Signature Database', 'signature database')} for where the base-R knowledge comes from).
However, the implementation reveals that it may hold an additional \`onlyBuiltin\` flag to indicate that the call is only calling builtin functions — however, this is only a flag to improve performance,
and it should not be relied on as it may under-approximate the actual calling targets (e.g., being \`false\` even though all calls resolve to builtins).
${ctx.hierarchy('DataflowGraphVertexFunctionCall')}
The related function argument references are defined like this:
${ctx.hierarchy('FunctionArgument')}
There is another element of potential interest to you, the \`origin\` property which records how flowR created the respective function call.
These origins may hold the name of any processor that is part of the ${ctx.link('BuiltInProcName')} enumeration to signal that the respective processor (cf. ${ctx.link('BuiltInProcessorMapper')}) was responsible for creating the vertex.
The entry \`${built_in_proc_name_1.BuiltInProcName.Function}\` signals that flowR used a processor for a user-defined function defined within the source code, \`${built_in_proc_name_1.BuiltInProcName.Unnamed}\` signals that the function as an anonymous function definition.
However, in general, flowR may use any fitting handler as an origin (see the ${ctx.link('BuiltInProcName')} enum for a *complete* list). For example, within a access definition, flowR will correspondingly redefine the meaning of \`:=\` to that of the \`${built_in_proc_name_1.BuiltInProcName.TableAssignment}\`.
${(0, doc_structure_1.details)('Example: Simple Function Call (unresolved)', await (async () => {
const code = 'foo(x,3,y=3,)';
const [text, info] = await (0, doc_dfg_1.printDfGraphForCode)(parser, code, { mark: new Set([8]), exposeResult: true, ctx });
const callInfo = info.dataflow.graph.vertices(true).find(([, vertex]) => vertex_2.FunctionCallVertex.is(vertex) && identifier_1.Identifier.getName(vertex.name) === 'foo');
(0, assert_1.guard)(callInfo !== undefined, () => `Could not find call vertex for ${code}`);
const [callId, callVert] = callInfo;
const inverseMapReferenceTypes = Object.fromEntries(Object.entries(identifier_1.ReferenceType).map(([k, v]) => [v, k]));
const identifierType = (0, doc_types_1.getTypesFromFolder)({
files: [path_1.default.resolve('./src/dataflow/environments/identifier.ts')],
inlineTypes: ['ControlDependency']
});
return `
To get a better understanding, let's look at a simple function call without any known call target, like \`${code}\`:
${text}
In this case, we have a function call vertex with id \`${callId}\` and the following arguments:
${(0, doc_code_1.codeBlock)('json', JSON.stringify(callVert.args, json_1.jsonReplacer, 2))}
Of course now, this is hard to read in this form (although the ids of the arguments can be mapped pretty easily to the visualization),
as the \`type\` of these references is a bit-mask, encoding one of the following reference types:
| Value | Reference Type |
|------:|----------------|
${Object.values(identifier_1.ReferenceType).filter(k => typeof k === 'string').map(k => `| ${identifier_1.ReferenceType[k]} | ${k} |`).join('\n')}
In other words, we classify the references as ${(0, doc_general_1.lastJoin)(callVert.args.map(a => {
if (a === r_function_call_1.EmptyArgument) {
return `the (special) empty argument type (\`${r_function_call_1.EmptyArgument}\`)`;
}
else {
return inverseMapReferenceTypes[a.type];
}
}), ', ', ', and ')}.
For more information on the types of references, please consult the implementation.
${(0, doc_types_1.printHierarchy)({ program: identifierType.program, info: identifierType.info, root: 'ReferenceType' })}
`;
})())}
${(0, doc_structure_1.block)({
type: 'NOTE',
content: `
But how do you know which definitions are actually called by the function?
So first of all, some frontends of _flowR_ (like the ${(0, doc_cli_option_1.getReplCommand)('slicer')} and ${(0, doc_cli_option_1.getReplCommand)('query')} with the ${ctx.linkPage('wiki/Query API', 'Query API')}) already provide you with this information.
In general there are three scenarios you may be interested in:
${(0, doc_structure_1.details)('1) the function resolves only to builtin definitions (like <code><-</code>)', `
Let's have a look at a simple assignment:
${await (0, doc_dfg_1.printDfGraphForCode)(parser, 'x <- 2', { ctx })}
In this case, the call does not have a single ${linkEdgeName(edge_1.EdgeType.Calls)} edge, which in general means (i.e., if the analysis is done and you are not looking at an intermediate result) it is bound to anything
global beyond the scope of the given script. _flowR_ generally (theoretically at least) does not know if the call really refers to a built-in variable or function,
as any code that is not part of the analysis could cause the semantics to change.
However, it is (in most cases) safe to assume we call a builtin if there is a builtin function with the given name and if there is no ${linkEdgeName(edge_1.EdgeType.Calls)} edge attached to a call.
If you want to check the resolve targets, refer to ${ctx.link(resolve_helper_1.Resolve.byNameAndType)}.
`)}
${(0, doc_structure_1.details)('2) the function only resolves to definitions that are present in the program', `
Let's have a look at a call to a function named \`foo\` which is defined in the same script:
${await (async () => {
const code = 'foo <- function() 3\nfoo()';
const [text, info] = await (0, doc_dfg_1.printDfGraphForCode)(parser, code, { exposeResult: true, mark: new Set([6, '6->0', '6->1', '6->3']), ctx });
const numberOfEdges = [...info.dataflow.graph.edges()].flatMap(e => [...e[1].keys()]).length;
const callVertex = info.dataflow.graph.vertices(true).find(([, vertex]) => vertex_2.FunctionCallVertex.is(vertex) && identifier_1.Identifier.getName(vertex.name) === 'foo');
(0, assert_1.guard)(callVertex !== undefined, () => `Could not find call vertex for ${code}`);
const [callId] = callVertex;
return `
${text}
Now, there are several edges, ${numberOfEdges} to be precise, although we are primarily interested in the ${info.dataflow.graph.outgoingEdges(callId)?.size ?? 0}
edges going out from the call vertex \`${callId}\`.
The ${linkEdgeName(edge_1.EdgeType.Reads)} edge signals all definitions which are read by the \`foo\` identifier (similar to a [use vertex](#use-vertex)).
While it seems to be somewhat redundant given the ${linkEdgeName(edge_1.EdgeType.Calls)} edge that identifies the called [function definition](#function-definition-vertex),
you have to consider cases in which aliases are involved in the call resolution (e.g., with higher order functions).
${(0, doc_structure_1.details)('Example: Alias in Call Resolution', `In the following example, \`g\` ${linkEdgeName(edge_1.EdgeType.Reads)} the previous definition, but ${linkEdgeName(edge_1.EdgeType.Calls)} the function assigned to \`f\`.\n`
+ await (0, doc_dfg_1.printDfGraphForCode)(parser, 'f <- function() 3\ng <- f\ng()', { mark: new Set(['9', '9->5', '9->3']), ctx }))}
Lastly, the ${linkEdgeName(edge_1.EdgeType.Returns)} edge links the call to the return vertices(s) of the function.
Please be aware, that these multiple exit points may be counter intuitive as they often appear with a nested call (usually a call to the built-in \`{\` function).
${(0, doc_structure_1.details)('(Advanced) Example: Multiple Exit Points May Still Reflect As One', await (0, doc_dfg_1.printDfGraphForCode)(parser, `
f <- function() {
if(u) return(3)
if(v) return(2)
1
}
f()`.trim(), { mark: new Set([22, '22->18']), ctx }) +
`
In this case the call of \`f\` still only has one ${linkEdgeName(edge_1.EdgeType.Returns)} edge, although the function _looks_ as if it would have multiple exit points!
But you have to beware that \`{\` is a function call as well (see below) and it may be redefined, or at least affect the actual returns of the function.
In this scenario we show two types of such returns (or exit points): _explicit_ returns with the \`return\` function and _implicit_ returns (the result of the last evaluated expression).
However, they are actually linked with the call of the built-in function \`{\` (and, in fact, they are highlighted in the mermaid graph).
`)}
`;
})()}
`)}
${(0, doc_structure_1.details)('3) the function resolves to a mix of both', `
Users may write… interesting pieces of code - for reasons we should not be interested in!
Consider a case in which you have a built-in function (like the assignment operator \`<-\`) and a user that wants to redefine the meaning of the function call _sometimes_:
${await (async () => {
const [text, info] = await (0, doc_dfg_1.printDfGraphForCode)(parser, 'x <- 2\nif(u) `<-` <- `*`\nx <- 3', { switchCodeAndGraph: true, mark: new Set([9, '9->0', '9->10']), exposeResult: true, ctx });
const interestingUseOfAssignment = info.dataflow.graph.vertices(true).find(([, vertex]) => vertex.id === 11);
(0, assert_1.guard)(interestingUseOfAssignment !== undefined, () => 'Could not find interesting assignment vertex for the code');
const [id, interestingVertex] = interestingUseOfAssignment;
const env = interestingVertex.environment;
(0, assert_1.guard)(env !== undefined, () => 'Could not find environment for interesting assignment vertex');
const name = interestingVertex.name;
(0, assert_1.guard)(name !== undefined, () => 'Could not find name for interesting assignment vertex');
return `
${text}
Interesting program, right? Running this with \`u <- TRUE\` will cause the last line to evaluate to \`6\` because we redefined the assignment
operator to mean multiplication, while with \`u <- FALSE\` causes \`x\` to be assigned to \`3\`.
In short: the last line may either refer to a definition or to a use of \`x\`, and we are not fully equipped to visualize this (this causes a warning).
First of all how can you spot that something weird is happening? Well, this definition has a ${linkEdgeName(edge_1.EdgeType.Reads)} and a ${linkEdgeName(edge_1.EdgeType.DefinedBy)} edge,
but this of course does not apply to the general case.
For starters, let's have a look at the environment of the call to \`<-\` in the last line:
${(0, doc_env_1.printEnvironmentToMarkdown)(env.current)}
Great, you should see a definition of \`<-\` which is constraint by the [control dependency](#control-dependencies) to the \`if\`.
Hence, trying to re-resolve the call using ${ctx.link(linker_1.getAllFunctionCallTargets)} (defined in ${(0, doc_files_1.getFilePathMd)('../dataflow/internal/linker.ts')}) with the id \`${id}\` of the call as starting point will present you with
the following target ids: { \`${[...(0, linker_1.getAllFunctionCallTargets)(id, info.dataflow.graph)].join('`, `')}\` }.
This way we know that the call may refer to the built-in assignment operator or to the multiplication.
Similarly, trying to resolve the name with ${ctx.link(resolve_helper_1.Resolve.byNameAndType)}\` using the environment attached to the call vertex (filtering for any reference type) returns (in a similar fashion):
{ \`${resolve_helper_1.Resolve.byName(identifier_1.Identifier.make(name), env)?.map(d => d.nodeId).join('`, `')}\` } (however, the latter will not trace aliases).
`;
})()}
`)}
Similar to finding the definitions read by a variable use, please use the ${ctx.link(linker_1.getAllFunctionCallTargets)} function to find all possible definitions of a function call,
as explained in the ${ctx.linkPage('wiki/Dataflow Graph', 'working with the dataflow graph', 'dfg-working')} section.`
})}
Function calls are the most complicated mechanism in R as essentially everything is a function call.
Even **control structures** like \`if(p) a else b\` are desugared into function calls (e.g., as \`\` \`if\`(p, a, b) \`\`).
${(0, doc_structure_1.details)('Example: <code>if</code> as a Function Call', await (0, doc_dfg_1.printDfGraphForCode)(parser, 'if(p) a else b', { ctx }))}
Similarly, you should be aware of calls to **anonymous functions**, which may appear given directly (e.g. as \`(function() 1)()\`) or indirectly, with code
directly calling the return of another function call: \`foo()()\`.
${(0, doc_structure_1.details)('Example: Anonymous Function Call (given directly)', await (0, doc_dfg_1.printDfGraphForCode)(parser, '(function() 1)()', { mark: new Set([6, '6->4']), ctx }))}
${(0, doc_structure_1.details)('Example: Anonymous Function Call (given indirectly)', await (0, doc_dfg_1.printDfGraphForCode)(parser, 'foo <- function() return(function() 3)\nfoo()()', { mark: new Set([12, '12->4']), ctx }))}
${(0, doc_structure_1.block)({
type: 'NOTE',
content: `Now you might be asking yourself how to differentiate anonymous and named functions and what you have to keep in mind when working with them?
Unnamed functions have an array of signatures which you can use to identify them.
But in short: the \`origin\` attribute of the ${ctx.link('DataflowGraphVertexFunctionCall')} is \`${built_in_proc_name_1.BuiltInProcName.Unnamed}\`.
Please be aware that unnamed functions still have a \`name\` property to give it a unique identifier that can be used for debugging and reference.
This name _always_ starts with \`${unnamed_call_handling_1.UnnamedFunctionCallPrefix}\`.
To identify these calls please do not rely on the ${ctx.linkPage('wiki/Normalized AST', 'normalized AST')}. An expression like \`1 + 1\` will be correctly
identified as a syntactical binary operation. Yet, from a dataflow/semantic perspective this is equivalent to \`\` \`+\`(1, 1) \`\` (which is a named function call and marked as such in the dataflow graph).
To know which function is called, please rely on the ${linkEdgeName(edge_1.EdgeType.Calls)} edge.
`
})}
Another interesting case is a function with **side effects**, most prominently with the super-assignment \`<<-\`.
In this case, you may encounter the ${linkEdgeName(edge_1.EdgeType.SideEffectOnCall)} as exemplified below.
${(0, doc_structure_1.details)('Example: Function Call with a Side-Effect', await (0, doc_dfg_1.printDfGraphForCode)(parser, 'f <- function() x <<- 3\n f()', { mark: new Set([8, '1->8']), ctx }))}
`,
code: 'foo()',
expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().call('1@foo', 'foo', [])
}, []]);
vertexExplanations.set(vertex_1.VertexType.VariableDefinition, [{
name: 'Variable Definition Vertex',
type: vertex_1.VertexType.VariableDefinition,
description: `
Defined variables most commonly occur in the context of an assignment, for example, with the \`<-\` operator as shown above.
${(0, doc_structure_1.details)('Example: Super Definition (<code><<-</code>)', await (0, doc_dfg_1.printDfGraphForCode)(parser, 'x <<- 1', { mark: new Set([0]), ctx }))}
The implementation is relatively sparse and similar to the other marker vertices:
${ctx.hierarchy('DataflowGraphVertexVariableDefinition')}
Of only interest is \`par\`, which signals that the definitions is partial (e.g., in the case of \`x[a] <- 1\`).
Of course, there are not just operators that define variables, but also functions, like \`assign\`.
${(0, doc_structure_1.details)('Example: Using <code>assign</code>', await (0, doc_dfg_1.printDfGraphForCode)(parser, 'assign("x", 1)\nx', { mark: new Set([1]), ctx })
+ `\nThe example may be misleading as the visualization uses \`${node_id_1.recoverName.name}\` to print the lexeme of the variable. However, this actually defines the variable \`x\` (without the quotes) as you can see with the ${linkEdgeName(edge_1.EdgeType.Reads)} edge.`)}
Please be aware, that the name of the symbol defined may differ from what you read in the program as R allows the assignments to strings, escaped names, and more:
${(0, doc_structure_1.details)('Example: Assigning with an Escaped Name', await (0, doc_dfg_1.printDfGraphForCode)(parser, '`x` <- 1\nx', { mark: new Set([0]), ctx }))}
${(0, doc_structure_1.details)('Example: Assigning with a String', await (0, doc_dfg_1.printDfGraphForCode)(parser, '"x" <- 1\nx', { mark: new Set([0]), ctx }))}
Definitions may be constrained by conditionals (_flowR_ takes care of calculating the dominating front for you).
${(0, doc_structure_1.details)('Conditional Assignments', await (async () => {
const constrainedDefinitions = await (0, doc_dfg_1.printDfGraphForCode)(parser, 'x <- 0\nif(u) x <- 1 else x <- 2\nx', { exposeResult: true, ctx });
const [text, info] = constrainedDefinitions;
const finalEnvironment = (0, doc_env_1.printEnvironmentToMarkdown)(info.dataflow.environment.current);
return `
${text}
In this case, the definition of \`x\` is constrained by the conditional, which is reflected in the environment at the end of the analysis:
${finalEnvironment}
As you can see, _flowR_ is able to recognize that the initial definition of \`x\` has no influence on the final value of the variable.
`;
})())}
`,
code: 'x <- 1',
expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().defineVariable('1@x', 'x')
}, []]);
vertexExplanations.set(vertex_1.VertexType.FunctionDefinition, [{
name: 'Function Definition Vertex',
type: vertex_1.VertexType.FunctionDefinition,
description: `
Defining a function does do a lot of things: 1) it creates a new scope, 2) it may introduce parameters which act as promises and which are only evaluated if they are actually required in the body, 3) it may access the enclosing environments and the callstack.
The vertex object in the dataflow graph stores multiple things, including all exit points, the enclosing environment if necessary, and the information of the subflow (the "body" of the function).
${ctx.hierarchy('DataflowGraphVertexFunctionDefinition')}
The subflow is defined like this:
${ctx.hierarchy('DataflowFunctionFlowInformation')}
And if you are interested in the exit points, they are defined like this:
${ctx.hierarchy('ExitPoint')}
Whenever we visualize a function definition, we use a dedicated node to represent the anonymous function object,
and a subgraph (usually with the name \`"function <id>"\`) to encompass the body of the function (they are linked with a dotted line).
${(0, doc_structure_1.block)({
type: 'NOTE',
content: `
You may ask yourself: How can I know which vertices are part of the function body? how do i know the parameters?
All vertices that are part of the graph are present in the \`graph\` property of the function definition — it contains a set of all ids of the contained vertices:
the actual dataflow graph is flat, and you can query all root vertices (i.e., those not part of any function definition) using
\`${new graph_1.DataflowGraph(undefined).rootIds.name}\`. Additionally, most functions that you can call on the dataflow graph offer a flag whether you want to include
vertices of function definitions or not (e.g., \`${new graph_1.DataflowGraph(undefined).vertices.name}\`)
${(0, doc_structure_1.details)('Example: Nested Function Definitions', await (async () => {
const [text, info] = await (0, doc_dfg_1.printDfGraphForCode)(parser, 'f <- function() { g <- function() 3 }', { mark: new Set([9, 6]), exposeResult: true, ctx });
const definitions = info.dataflow.graph.verticesOfType(vertex_1.VertexType.FunctionDefinition)
.map(([id, vertex]) => `| \`${id}\` | { \`${[...vertex.subflow.graph].join('`, `')}\` } |`)
.toArray();
return `
${text}
As you can see, the vertex ids of the subflow do not contain those of nested function definitions but again only those which are part of the respective scope (creating a tree-like structure):
| Id | Vertex Ids in Subflow |
|---:|-----------------------|
${definitions.join('\n')}
`;
})())}
But now there is still an open question: how do you know which vertices are the parameters?
In short: there is no direct way to infer this from the dataflow graph (as parameters are handled as open references which are promises).
However, you can use the ${ctx.linkPage('wiki/Normalized AST', 'normalized AST')} to get the parameters used.
${(0, doc_structure_1.details)('Example: Parameters of a Function', await (async () => {
const code = 'f <- function(x, y = 3) x + y';
const [text, info] = await (0, doc_dfg_1.printDfGraphForCode)(parser, code, { mark: new Set([10, 1, 3]), exposeResult: true, ctx });
const ast = await (0, doc_normalized_ast_1.printNormalizedAstForCode)(parser, code, { prefix: 'flowchart LR\n', showCode: false, ctx });
const functionDefinition = info.dataflow.graph.vertices(true).find(([, vertex]) => vertex_2.FunctionDefinitionVertex.is(vertex));
(0, assert_1.guard)(functionDefinition !== undefined, () => `Could not find function definition for ${code}`);
const [id] = functionDefinition;
const normalized = info.normalize.idMap.get(id);
return `
Let's first consider the following dataflow graph (of \`${code}\`):
${text}
The function definition we are interested in has the id \`${id}\`. Looking at the ${ctx.linkPage('wiki/Normalized AST', 'normalized AST')} of the code,
we can get the parameters simply be requesting the \`parameters\` property of the function definition (yielding the names: [${normalized.parameters.map(p => `\`${p.name.content}\``).join(', ')}]):
${ast}
`;
})())}
`
})}
Last but not least, please keep in mind that R offers another way of writing anonymous functions (using the backslash):
${await (0, doc_dfg_1.printDfGraphForCode)(parser, '\\(x) x + 1', { switchCodeAndGraph: true, ctx })}
Besides this being a theoretically "shorter" way of defining a function, this behaves similarly to the use of \`function\`.
`,
code: 'function() 1',
expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().defineFunction('1@function', [0], { hooks: [], graph: new Set('0'), in: [{ nodeId: 0, cds: [], type: identifier_1.ReferenceType.Constant, name: undefined }], out: [], unknownReferences: [], entryPoint: 0, environment: (0, environment_builder_1.defaultEnv)() })
}, []]);
const results = [];
let i = 0;
for (const [, vertex] of (0, doc_data_dfg_util_1.getAllVertices)()) {
const get = vertexExplanations.get(vertex);
(0, assert_1.guard)(get !== undefined, () => `No explanation for vertex type ${vertex}`);
const [expl, subExplanations] = get;
results.push(await explanation(expl, parser, ctx, ++i, ...subExplanations));
}
return results.join('\n');
}
async function getEdgesExplanations(parser, ctx) {
const edgeExplanations = new Map();
edgeExplanations.set(edge_1.EdgeType.Reads, [{
name: 'Reads Edge',
type: edge_1.EdgeType.Reads,
description: `
Reads edges mark that the source vertex (usually a [use vertex](#use-vertex)) reads whatever is defined by the target vertex (usually a [variable definition](#variable-definition-vertex)).
${(0, doc_structure_1.block)({
type: 'NOTE',
content: `
A ${linkEdgeName(edge_1.EdgeType.Reads)} edge is not a transitive closure and only links the "directly read" definition(s).
Our abstract domains resolving transitive ${linkEdgeName(edge_1.EdgeType.Reads)} edges (and for that matter, following ${linkEdgeName(edge_1.EdgeType.Returns)} as well)
are currently tailored to what we need in _flowR_. Hence, we offer a function like ${ctx.link(linker_1.getAllFunctionCallTargets)},
as well as ${ctx.link(resolve_helper_1.Resolve.toBuiltIn)} which do this for specific cases.
Refer to ${ctx.link(df_helper_1.Dataflow.origin)} for a more general solution, as explained in ${ctx.linkPage('wiki/Dataflow Graph', 'working with the dataflow graph', 'dfg-working')}.
${(0, doc_structure_1.details)('Example: Multi-Level Reads', await (0, doc_dfg_1.printDfGraphForCode)(parser, 'x <- 3\ny <- x\nprint(y)', { mark: new Set(['9->7', '7->3', '4->0']), ctx }))}
Similarly, ${linkEdgeName(edge_1.EdgeType.Reads)} can be cyclic, for example in the context of loops:
${(0, doc_structure_1.details)('Example: Cyclic Reads', await (0, doc_dfg_1.printDfGraphForCode)(parser, 'for(i in v) x <- x + 1', { mark: new Set(['3->2']), ctx }))}
`
})}
Reads edges may point to built-in definitions as well, to signal that something relates to a built-in element of flowR.
Their targets are not part of the ${ctx.link(graph_1.DataflowGraph)} but only markers to signal that the respective definition is a built-in.
Please refer to the explanation of the respective vertices for more information.
`,
code: 'x <- 2\nprint(x)',
expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().reads('2@x', '1@x')
}, [{
name: 'Reads Edge (Call)',
description: 'Named calls are resolved too, linking to the symbol that holds the anonymous function definition (indirectly or directly)',
code: 'foo <- function() {}\nfoo()',
expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().reads('2@foo', '1@foo')
}, {
name: 'Reads Edge (Parameter)',
description: 'Parameters can read from each other as well.',
code: 'f <- function(x, y=x) {}',
expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().reads('1:20', '1@x')
}]]);
edgeExplanations.set(edge_1.EdgeType.DefinedBy, [{
name: 'DefinedBy Edge', /* concat for link generation */
type: edge_1.EdgeType.DefinedBy,
description: `
The source vertex is usually a [\`variable definition\`](#variable-definition-vertex) linking the defined symbol to the entry point of the resulting side.
${(0, doc_structure_1.details)('In general, this does not have to be the right hand side of the operator.', await (0, doc_dfg_1.printDfGraphForCode)(parser, '3 -> x', { mark: new Set([0]), ctx }))}
However, nested definitions can carry it (in the nested case, \`x\` is defined by the return value of <code>\\\`<-\\\`(y, z)</code>). Additionally, we link the assignment function.
`,
code: 'x <- y',
expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().definedBy('1@x', '1@y').definedBy('1@x', '1:3')
}, [{
name: 'DefinedBy Edge (Nested)',
description: `Nested definitions can carry the ${linkEdgeName(edge_1.EdgeType.DefinedBy)} edge as well.`,
code: 'x <- y <- z',
expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().definedBy('1@x', '1:3').definedBy('1@x', '1:8').definedBy('1@y', '1:8')
}, {
name: 'DefinedBy Edge (Expression)',
description: 'Here, we define by the result of the `+` expression.',
code: 'x <- y + z',
expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().definedBy('1@x', '1:8')
}]]);
edgeExplanations.set(edge_1.EdgeType.Calls, [{
name: 'Calls Edge',
type: edge_1.EdgeType.Calls,
description: `Link the [function call](#function-call-vertex) to the [function definition](#function-definition-vertex) that is called. To find all called definitions,
please use the ${ctx.link(df_helper_1.Dataflow.origin.name)} function, as explained in ${ctx.linkPage('wiki/Dataflow Graph', 'working with the dataflow graph', 'dfg-working')}.
If you are interested in the call graph, refer to ${ctx.linkM(flowr_analyzer_1.FlowrAnalyzer, 'callGraph')} and consult the ${ctx.linkPage('wiki/Dataflow Graph', 'call graph wiki', 'perspectives-cg')} for more information.
`,
code: 'foo <- function() {}\nfoo()',
expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().calls('2@foo', '1@function')
}, []]);
edgeExplanations.set(edge_1.EdgeType.Returns, [{
name: 'Returns Edge',
type: edge_1.EdgeType.Returns,
description: `Link the [function call](#function-call-vertex) to the exit points of the target definition (this may incorporate the call-context).
As you can see in the example, this happens for user-defined functions (like \`foo\`) as well as for built-in functions (like \`<-\`).
However, these edges are specific to scenarios in which flowR knows that a specific element is returned.
For contrast, compare this to a use of, for example, \`+\`:
${(0, doc_structure_1.details)('Example: No returns edge for +', await (0, doc_dfg_1.printDfGraphForCode)(parser, '1 + 1', { ctx }))}
Here, we do not get a ${linkEdgeName(edge_1.EdgeType.Returns)} edge as this function call creates a new value based on its arguments.
In these scenarios you should rely on the \`args\` property of the ${ctx.link('DataflowGraphVertexFunctionCall')}
and use the arguments to calculate what you need to know. Alternatively, you can track the ${linkEdgeName(edge_1.EdgeType.Argument)} edges.
In general, the ${linkEdgeName(edge_1.EdgeType.Returns)} edge already does most of the heavy lifting for you, by respecting control flow influences and
(as long as flowR is able to detect it) dead code.
${(0, doc_structure_1.details)('Example: Tricky Returns', `We show the _simplified_ DFG for simplicity and highlight all ${linkEdgeName(edge_1.EdgeType.Returns)} edges involved in tracking the return of a call to \`f\` (as ${linkEdgeName(edge_1.EdgeType.Returns)} are never transitive and must hence be followed):\n` +
await (0, doc_dfg_1.printDfGraphForCode)(parser, 'f <- function() { if(u) { return(3); 2 } else 42 }\nf()', {
simplified: true,
mark: new Set(['19->15', '15->14', '14->12', '14->11', '11->9', '9->7']),
ctx
})
+ '\n\n Note, that the `2` should be completely absent of the dataflow graph (recognized as dead code).')}
<br/>
${(0, doc_structure_1.block)({
type: 'NOTE',
content: `You might find it an inconvenience that there is no ${linkEdgeName(edge_1.EdgeType.Returns)} edge for _every_ function call.
If there is particular function for which you think flowR should be able to detect the return, please open a [new issue](${doc_issue_1.NewIssueUrl}).
Yet the problem of flowR not tracking returns for functions that create new/transform existing values is a fundamental design decision — if this irritates you ~~you may be eligible for compensation~~, you may be interested in an
alternative with the ${ctx.linkPage('wiki/Control Flow Graph', 'Control Flow Graph', 'cfg-exit-points')} which not just tracks all possible execution orders of the program,
but also the exit points of _all_ function calls.
`
})}
`,
code: 'foo <- function() x\nfoo()',
expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().returns('2@foo', '1@x').returns('1@<-', '1@foo').argument('1@<-', '1@foo')
}, []]);
const lateBindingExample = `
f <- function() x
x <- 3
f()
`.trim();
const dfInfo = await (0, doc_dfg_1.printDfGraphForCode)(parser, lateBindingExample, { switchCodeAndGraph: true, codeOpen: true, mark: new Set([1, '1->5', '9->5']), ctx });
edgeExplanations.set(edge_1.EdgeType.DefinesOnCall, [{
name: 'DefinesOnCall Edge',
type: edge_1.EdgeType.DefinesOnCall,
description: `*This edge is usually joined with ${linkEdgeName(edge_1.EdgeType.DefinedByOnCall)}!*
Links an argument to whichever parameter they cause to be defined if the related function call is invoked.
In the context of functions which access their closure environment these edges play another tricky role as there are many cases
made more difficult by R's way of allowing closure environments to later receive variables.
Consider the following scenario in which we first define a function which returns the value of a variable named \`x\` and then define \`x\`
only after we defined the function:
${dfInfo}
The final call evaluates to \`3\` (similar to if we defined \`x\` before the function definition).
Within a dataflow graph you can see this with two edges. The \`x\` within the function body will have a ${linkEdgeName(edge_1.EdgeType.DefinedByOnCall)}
to every definition it _may_ refer to. In turn, each call vertex calling the function which encloses the use of \`x\` will have a
${linkEdgeName(edge_1.EdgeType.DefinesOnCall)} edge to the definition(s) it causes to be active within the function body.
`,
code: 'f <- function(x) {}\nf(x=1)',
// here we use the ids as the argument wrappers are not easily selected with slicing criteria
expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().definesOnCall('$11', '$1').definedByOnCall('$1', '$11')
}, []]);
edgeExplanations.set(edge_1.EdgeType.DefinedByOnCall, [{
name: 'DefinedByOnCall Edge',
type: edge_1.EdgeType.DefinedByOnCall,
description: `*This edge is usually joined with ${linkEdgeName(edge_1.EdgeType.DefinesOnCall)}!*
This represents the other part of the ${linkEdgeName(edge_1.EdgeType.DefinesOnCall)} edge (e.g., links the parameter to the argument). Please look there for further documentation.`,
code: 'f <- function(x) {}\nf(x=1)',
expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().definesOnCall('$11', '$1').definedByOnCall('$1', '$11')
}, []]);
edgeExplanations.set(edge_1.EdgeType.Argument, [{
name: 'Argument Edge',
type: edge_1.EdgeType.Argument,
description: `Links a [function call](#function-call-vertex) to the entry point of its arguments. If we do not know the target of such a call, we automatically assume that all arguments are read by the call as well!
The exception to this is the [function definition](#function-definition-vertex) which does no longer hold these argument relationships (as they are not implicit in the structure).
`,
code: 'f(x,y)',
expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().argument('1@f', '1@x').reads('1@f', '1@x').argument('1@f', '1@y').reads('1@f', '1@y')
}, []]);
edgeExplanations.set(edge_1.EdgeType.SideEffectOnCall, [{
name: 'SideEffectOnCall Edge',
type: edge_1.EdgeType.SideEffectOnCall,
description: 'Links a global side effect to an affected function call (e.g., a super definition within the function body)',
code: 'f <- function() { x <<- 2 }\nf()',
expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().sideEffectOnCall('1@x', '2@f')
}, []]);
edgeExplanations.set(edge_1.EdgeType.NonStandardEvaluation, [{
name: 'NonStandardEvaluation Edge',
type: edge_1.EdgeType.NonStandardEvaluation,
description: `
Marks cases in which R's non-standard evaluation mechanisms cause the default semantics to deviate (see the case below for multiple vertices)
${(0, doc_structure_1.block)({
type: 'NOTE',
content: `
What to do if you encounter a vertex marked with this edge?
This depends on your analysis. To handle many real-world sources correctly you are probably fine with just ignoring it.
Yet, you may choose to follow these references for other queries. For now, _flowR's_ support for non-standard evaluation is limited.
Besides the obvious quotation there are other cases in which _flowR_ may choose to create a ${linkEdgeName(edge_1.EdgeType.NonStandardEvaluation)} edge, there are
some that may appear to be counter-intuitive. For example, a for-loop body, as in the following example.
${(0, doc_structure_1.details)('Example: For-Loop Body', await (0, doc_dfg_1.printDfGraphForCode)(parser, 'for(i in v) b', { mark: new Set([2, '4->2']), ctx }))}
${(0, doc_structure_1.details)('Example: While-Loop Body', await (0, doc_dfg_1.printDfGraphForCode)(parser, 'while(TRUE) b', { mark: new Set([1, '3->1']), ctx }))}
Three helpers decide what such a mark means once the graph is complete:
${ctx.link(quoted_1.Quoted.name, undefined, { type: 'variable' })} settles what a capture reaches when it is handed to \`eval\` (see ${ctx.linkO(quoted_1.Quoted, 'finalize')}),
${ctx.link(nse_1.Nse.name, undefined, { type: 'variable' })} models the escapes a quoting function offers (rlang's \`!!\` and \`bquote\`'s \`.(x)\`), and
${ctx.link(deferred_1.Deferred.name, undefined, { type: 'variable' })} links an expression R evaluates at a moment we cannot pin down, as \`delayedAssign\` binds one.
`
})}
`,
code: 'quote(x)',
expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)().argument('1@quote', '1@x').nse('1@quote', '1@x')
}, [{
name: 'Complete Expressions',
description: 'This works, even if we have a larger expression in `quote`.',
code: 'quote(x + y)',
expectedSubgraph: (0, dataflowgraph_builder_1.emptyGraph)()
.argument('1@quote', '1@+').nse('1@quote', '1@+')
.nse('1@quote', '1@x')
.nse('1@quote', '1@y')
}]]);
const results = [];
let i = 0;
for (const [, edge] of (0, doc_data_dfg_util_1.getAllEdges)()) {
const get = edgeExplanations.get(edge);
(0, assert_1.guard)(get !== undefined, () => `No explanation for edge type ${edge}`);
const [expl, subExplanations] = get;
results.push(`<a id='${edgeTypeToId(edge)}'></a>` + await explanation(expl, parser, ctx, ++i, ...subExplanations));
}
return results.join('\n');
}
async function dummyDataflow() {
const analyzer = await new flowr_analyzer_builder_1.FlowrAnalyzerBuilder().build();
analyzer.addRequest('x <- 1\nx + 1');
const result = await analyzer.dataflow();
analyzer.close();
return result;
}
/**
* https://github.com/flowr-analysis/flowr/wiki/Dataflow-Graph
*/
class WikiDataflowGraph extends doc_maker_1.DocMaker {
constructor() {
super('wiki/Dataflow Graph.md', module.filename, 'dataflow graph');
}
async text({ ctx, treeSitter }) {
const introExampleCode = 'x <- 3\ny <- x + 1\ny';
return `
This page briefly summarizes flowR's dataflow graph (${ctx.link(graph_1.DataflowGraph)}).
If you are interested in which features we support and which features are still to be worked on, please refer to our ${ctx.linkPage('wiki/Capabilities')} page.
In case you want to manually build such a graph (e.g., for testing), you can use the ${ctx.link(dataflowgraph_builder_1.DataflowGraphBuilder)}.
In summary, we discuss the following topics in this wiki page:
- [Reading the Visualization](#reading-the-visualization)
- [Vertices](#vertices)
- [Edges](#edges)
- [Control Dependencies](#control-dependencies)
- [Dataflow Information](#dataflow-information)
- [Unknown Side Effects](#unknown-side-effects)
- [Perspectives on the Dataflow Graph](#perspectives)
- [Call Graph Perspective](#perspectives-cg)
- [Working with the Dataflow Graph](#dfg-working)
Please be aware that the accompanied [dataflow information](#dataflow-information) (${ctx.link('DataflowInformation')}) returned by _flowR_
contains things besides the graph, like the entry and exit points of the subgraphs, and currently active references (see [below](#dataflow-information)).
Additionally, you may be interested in the [Unknown Side Effects](#unknown-side-effects), marking calls which _flowR_ is unable to handle correctly.
> [!TIP]
> To investigate the dataflow graph,
> you can either use the ${ctx.linkPage('flowr:vscode')} or the ${ctx.replCmd('dataflow*')}
> command in the REPL (see the ${ctx.linkPage('wiki/Interface', 'Interface wiki page')}).
> There is also a simplified version available with ${ctx.replCmd('dataflowsimple*')} that does not show everything but is easier to read.
> For small graphs, you can also use ${ctx.replCmd('dataflowascii')} to print the graph as ASCII art.
>
> If you receive a dataflow graph in its serialized form (e.g., by talking to a ${ctx.linkPage('wiki/Interface', '_flowR_ server')}), you can use ${ctx.linkM(graph_1.DataflowGraph, 'fromJson', { realNameWrapper: 'i', codeFont: true })} to recover the graph object.
>
> Also, check out the [${doc_files_1.FlowrGithubGroupName}/sample-analyzer-df-diff](${doc_files_1.FlowrGithubBaseRef}/sample-analyzer-df-diff) repository for a complete example project creating and comparing dataflow graphs.
To get started, let's look at the graph for the following code snippet:
${(0, doc_code_1.codeBlock)('r', introExampleCode)}
With this code, the corresponding dataflow graph looks like this:
${await (0, doc_dfg_1.printDfGraphForCode)(treeSitter, introExampleCode, { showCode: false, ctx })}
The above dataflow graph showcases the general gist. We define a dataflow graph as a directed graph G = (V, E),
differentiating between ${(0, doc_data_dfg_util_1.getAllVertices)().length} types of vertices V and
${(0, doc_data_dfg_util_1.getAllEdges)().length} types of edges E allowing each vertex to have a single, and each edge to have multiple distinct types.
Additionally, every node may have links to its [control dependencies](#control-dependencies) (which you may view as a ${(0, text_1.nth)((0, doc_data_dfg_util_1.getAllEdges)().length + 1)} edge type,
although they are explicitly no data dependency and relate to the ${ctx.linkPage('wiki/Control Flow Graph')}.
${(0, doc_structure_1.details)('Simplified Version of the graph', await (0, doc_dfg_1.printDfGraphForCode)(treeSitter, 'x <- 3\ny <- x + 1\ny', { simplified: true, showCode: false, ctx }))}
The following vertices types exist:
1. ${(0, doc_data_dfg_util_1.getAllVertices)().map(([k, v]) => `[\`${k}\`](#${v.toLowerCase().replace(/\s/g, '-')}-vertex)`).join('\n1. ')}
${(0, doc_structure_1.details)('Class Diagram', 'All boxes should link to their respective implementation:\n' + (0, doc_code_1.codeBlock)('mermaid', ctx.mermaid('DataflowGraphVertexInfo', { inlineTypes: ['MergeableRecord'] })))}
The following edges types exist, internally we use bitmasks to represent multiple types in a compact form, so you
should use the ${ctx.link('DfEdge', { codeFont: false, realNameWrapper: 'i' }, { type: 'variable' })} object and its methods to work with them:
1. ${(0, doc_data_dfg_util_1.getAllEdges)().map(([k, v], index) => `[\`${k}\` (${v})](#${index + 1}-${k.toLowerCase().replace(/\s/g, '-')}-edge)`).join('\n1. ')}
${(0, doc_structure_1.details)('Class Diagram', 'All boxes should link to their respective implementation:\n' + (0, doc_code_1.codeBlock)('mermaid', ctx.mermaid('EdgeType', { inlineTypes: ['MergeableRecord'] })))}
From an implementation perspective all of these types are represented by respective interfaces, see ${(0, doc_files_1.getFilePathMd)('../dataflow/graph/vertex.ts')} and ${(0, doc_files_1.getFilePathMd)('../dataflow/graph/edge.ts')}.
The following sections present details on the different types of vertices and edges, including examples and explanations.
> [!NOTE]
> Every dataflow vertex holds an \`id\` which links it to the respective node in the ${ctx.linkPage('wiki/Normalized AST', 'normalized AST')}.
> So if you want more information about the respective vertex, you can usually access more information
> using the <code>${ctx.link(`${graph_1.DataflowGraph.name}`, { codeFont: false, realNameWrapper: 'i' })}::idMap</code> linked to the dataflow graph:
${(0, doc_general_1.prefixLines)((0, doc_code_1.codeBlock)('ts', 'const node = graph.idMap.get(id);'), '> ')}
> In case you just need the name (\`lexeme\`) of the respective vertex, ${ctx.link(node_id_1.recoverName)} can help you out:
${(0, doc_general_1.prefixLines)((0, doc_code_1.codeBlock)('ts', `const name = ${node_id_1.recoverName.name}(id, graph.idMap);`), '> ')}
>
> Please note, that not every node in the ${ctx.linkPage('wiki/Normalized AST', 'normalized AST')} is represented in the dataflow graph.
> For example, if the node is unreachable in a way that can be detected during the analysis and flowR
> is configured to ignore dead code (there are more powerful dead code capabilities with the ${ctx.linkPage('wiki/Control Flow Graph', 'CFG')}). Likewise, empty argument wrappers do not have a corresponding
> dataflow graph vertex (as they are not relevant for the dataflow graph). It depends on the scenario what to do in such a case.
> For argument wrappers you can access the dataflow information for their value. For dead code, however, flowR currently contains
> some core heuristics that remove it which cannot be reversed easily. So please open [an issue](${doc_issue_1.NewIssueUrl}) if you encounter such a case and require the node to be present in the dataflow graph.
${(0, doc_structure_1.section)('Reading the Visualizations', 2, 'reading-the-visualization')}
Before we dive into the details of the different vertices and edges, let's briefly talk about how to read the visualizations.
For this, let's have a look at a very simple graph, created for the number \`42\`:
${await (0, doc_dfg_1.printDfGraphForCode)(treeSitter, '42', { showCode: false, ctx })}
${(0, doc_structure_1.section)('Vertex Shape', 3, 'vtx-shape')}
The _shape_ of the vertex tells you the type of the vertex in the dataflow graph using the following scheme (the types are
explained in more detail in the following sections):
${(0, doc_code_1.codeBlock)('mermaid', 'flowchart TD\n' +
// use mermaidNodeBrackets to get open and closing bracket
Object.entries(vertex_1.VertexType)
.map(([k, v]) => {
const { open, close } = (0, dfg_1.mermaidNodeBrackets)(v);
return ` ${v}${open}${k}${close}`;
}).join('\n') +
// we add a subflow for the function definition
'\n subgraph fbox ["function body"]\n body((...))\n end\n fdef-->fbox')}
${(0, doc_structure_1.section)('Syntactic Types', 3, 'vtx-synt-type')}
Within the shape, in square brackets, you can find the syntactic type of the vertex
which is linked to the node in the ${ctx.linkPage('wiki/Normalized AST')}.
For more information on valid types and what to do with them, please refer to the ${ctx.linkPage('wiki/Normalized AST', 'normalized AST wiki page')}
and the corresponding helper objects (e.g., ${ctx.link(r_number_1.RNumber, undefined, { type: 'variable' })}).
${(0, doc_structure_1.section)('Lexeme', 3, 'vtx-lexeme')}
Also in the first line, next to the [syntactic type](#vtx-synt-type), you can find the lexeme of the vertex (if it has one, e.g., for a variable definition or use).
This usually represents the textual source string of the respective vertex, and is also linked to the ${ctx.linkPage('wiki/Normalized AST')}.
For a clearer hierarchy, the lexeme is rendered in **bold** while the [syntactic type](#vtx-synt-type) is de-emphasized in _italics_ (mermaid markdown labels do not support a per-token font color, so a true gray tone would require styling the whole node). Only the token the source actually wrote is bold: when a call is shown with a package-qualified name that flowR *added* (e.g. the code wrote \`acf\` but it is displayed as \`stats::acf\`), the added \`stats::\` prefix stays non-bold, whereas a namespace written verbatim in the source is part of the lexeme and is bold as a whole.
You can access the lexeme too with ${ctx.linkO(model_1.RNode, 'lexeme')}.
${(0, doc_structure_1.section)('Vertex Id', 3, 'vtx-id')}
In the second line, you will usually find the id (in the form of a ${ctx.link(node_id_1.NodeId, undefined, { type: 'variable' })}) of the vertex — kept compact by sharing the line with the [location](#vtx-location), in the form \`*location* (**id: <id>**)\` with the id in **bold** —
alongside its [control dependencies](#control-dependencies) if it has any. This id links the vertex to the respective node in the ${ctx.linkPage('wiki/Normalized AST')} (and all other perspectives created by flowR).
To give you an example, have a look at the following graph:
${await (0, doc_dfg_1.printDfGraphForCode)(treeSitter, 'if(u) a', { showCode: false, mark: new Set(['1']), ctx })}
The \`3+\` tells you that \`a\` has a [control dependency](#control-dependencies) on the vertex with id \`3\`, the \`if\`,
which only triggers when the condition is \`true\`; a \`-\` suffix marks the \`false\` case.
Other vertices are named by their id too: \`v: <id>\` is the value of a definition, \`links: <id>\` the AST vertices that
contributed to the vertex. Mermaid rejects some characters in an id, so a space or a bracket shows as \`_\`
(see ${ctx.linkO(mermaid_1.Mermaid, 'escapeId')}); a path keeps its \`/\` and \`.\`.
${(0, doc_structure_1.section)('Location', 3, 'vtx-location')}
The second line also indicates the compressed ${ctx.link(range_1.SourceRange)} of the vertex (directly before the [id](#vtx-id)) in the format \`startLine.startCharacter - endLine.endCharacter\`. If the range reads \`1.7\`,
this is short for \`1.7-1.7\`, likewise, \`1.7-9\` is short for \`1.7-1.9\`. So, \`1.7-9\` describes something starting
in the first line at the seventh character and ending in the first line at the ninth character.
${(0, doc_structure_1.section)('Arguments and Additional Information', 3, 'vtx-additional-info')}
Some vertices (e.g., [function calls](#function-call-vertex)) have additional information, like the arguments of the call.
As you can see with the \`if\` example above alongside the [vertex id](#vtx-id),
these vertices also have an additional line (prefixed with \`arg:\`) which lists the ids of the arguments in order to clear any ambiguity in case, for example,
the mermaid graph layouting fumbles the order.
${(0, doc_structure_1.section)('Vertices', 2, 'vertices')}
1. ${(0, doc_data_dfg_util_1.getAllVertices)().map(([k, v]) => `[\`${k}\`](#${v.toLowerCase().replaceAll(/\s/g, '-')}-vertex)`).join('\n1. ')}
${await getVertexExplanations(treeSitter, ctx)}
${(0, doc_structure_1.section)('Edges', 2, 'edges')}
1. ${(0, doc_data_dfg_util_1.getAllEdges)().map(([k, v], index) => `[\`${k}\` (${v})](#${index + 1}-${k.toLowerCase().replaceAll(/\s/g, '-')}-edge)`).join('\n1. ')}
${await getEdgesExplanations(treeSitter, ctx)}
${(0, doc_structure_1.section)('Control Dependencies', 2, 'control-dependencies')}
Each vertex may have a list of active control dependencies.
They hold the ${ctx.link('NodeId')} of all nodes that effect if the current vertex is part of the execution or not,
and a boolean flag \`when\` to indicate if the control dependency is active when the condition is \`true\` or \`false\`.
As an example, consider the following dataflow graph:
${await (0, doc_dfg_1.printDfGraphForCode)(treeSitter, 'if(p) a else b', { ctx })}
Whenever we visualize a graph, we represent the control dependencies as grayed out edges with a \`CD\` prefix, followed
by the \`when\` flag.
In the above example, both \`a\` and \`b\` depend on the \`if\`. Please note that they are _not_ linked to the result of
the condition itself as this is the more general linkage point (and harmonizes with other control structures, especially those which are user-defined).
${(0, doc_structure_1.details)('Example: Multiple Vertices (Assignment)', await (0, doc_dfg_1.printDfGraphForCode)(treeSitter, 'if(p) a <- 1', { ctx }))}
${(0, doc_structure_1.details)('Example: Multiple Vertices (Arithmetic Expression)', await (0, doc_dfg_1.printDfGraphForCode)(treeSitter, 'if(p) 3 + 2', { ctx }))}
${(0, doc_structure_1.details)('Example: Nested Conditionals', await (0, doc_dfg_1.printDfGraphForCode)(treeSitter, 'if(x) { if(y) a else b } else c', { ctx }))}
${(0, doc_structure_1.section)('Dataflow Information', 2, 'dataflow-information')}
Using _flowR's_ code interface (see the ${ctx.linkPage('wiki/Interface', 'Interface', 'creating-analyses-with-flowr')} wiki page for more), you can generate the dataflow information
for a given piece of R code (in this case \`x <- 1; x + 1\`) as follows:
${(0, doc_code_1.codeBlock)('ts', `
const analyzer = await new FlowrAnalyzerBuilder(requestFromInput('x <- 1\nx + 1')).build();
const result = await analyzer.dataflow();
`)}
<details>
<summary style="color:gray">Transpiled Code</summary>
The actual code we are using in case the example above gets oudated:
${(0, doc_code_1.codeBlock)('ts', dummyDataflow.toString())}
</details>
Now, you can find the dataflow _information_ with \`result.dataflow\`. More specifically, the graph is stored in \`result.dataflow.graph\` and looks like this:
${await (async () => {
const result = await dummyDataflow();
const dfGraphString = (0, doc_dfg_1.printDfGraph)(result.graph);
return `
${dfGraphString}
However, the dataflow information contains more, quite a lot of information in fact.
<details>
<summary style="color:gray">Dataflow Information as Json</summary>
_As the information is pretty long, we inhibit pretty printing and syntax highlighting:_
${(0, doc_code_1.codeBlock)('text', JSON.stringify(result, json_1.jsonReplacer))}
</details>
You may be interested in its implementation:
${ctx.hierarchy('DataflowInformation')}
Let's start by looking at the properties of the dataflow information object: ${Object.keys(result).map(k => `\`${k}\``).join(', ')}.
${(() => {
/* this includes the meta field for timing and the quick CFG in order to enable re-use and improve performance */
(0, assert_1.guard)(Object.keys(result).length === 11, () => 'Update Dataflow Documentation! (Keys: ' + Object.keys(result).join(', ') + ')');
return '';
})()}
There are three sets of references.
**in** (ids: ${JSON.stringify(new Set(result.in.map(n => n.nodeId)), json_1.jsonReplacer)}) and **out** (ids: ${JSON.stringify(new Set(result.out.map(n => n.nodeId)), json_1.jsonReplacer)}) contain the
ingoing and outgoing references of the subgraph at hand (in this case, the whole code, as we are at the end of the dataflow analysis).
Besides the Ids, they also contain important meta-information (e.g., what is to be read).
The third set, **unknownReferences**, contains all references that are not yet identified as read or written
(the example does not have any, but, for example, \`x\` (with id 0) would first be unknown and then later classified as a definition).
The **environment** property contains the active environment information of the subgraph.
In other words, this is a linked list of tables (scopes), mapping identifiers to their respective definitions.
A summarized version of the produced environment looks like this:
${(0, doc_env_1.printEnvironmentToMarkdown)(result.environment.current)}
This shows us that the local environment contains a single definition for \`x\` (with id 0) and that the parent environment is the built-in environment.
Additionally, we get the information that the node with the id 2 was responsible for the definition of \`x\`.
#### Attached Packages and the Search Path
Calling \`library(pkg)\` (or \`require\`) attaches a package to the search path.
Mirroring R's \`search()\`, _flowR_ inserts the package's namespace and imports environments *below* the global environment (\`.GlobalEnv\`), so resolution walks **current scope -> enclosing scopes -> global -> attached packages -> built-ins**.
A global binding shadows a package export of the same name, exactly as in R.
The most recently attached package is the nearest one, and re-attaching neither moves nor duplicates it.
The \`pos\` argument attaches further down the search path instead, given either as a position or as the name of an existing entry (an unknown position or name falls back to the default of 2, directly below the global environment).
Attaching inside a function propagates to the caller (R attaches globally), and across branches every possibly-attached package is kept (a sound over-approximation of R's single runtime path).
Last but not least, the information contains the single **entry point** (${JSON.stringify(result.entryPoint)}) and a set of **exit points** (${JSON.stringify(result.exitPoints.map(e => e.nodeId))}).
Besides marking potential exits, the exit points also provide information about why the exit occurs and which control dependencies affect the exit.
Finally, the **kill** property (${ctx.link('KillReference', undefined, { type: 'type' })}) tracks references that are removed from scope within the current subtree (e.g., via \`rm(x)\`).
It is \`undefined\` unless such a removal occurred and, like the outgoing references, bubbles up so that the enclosing scope can apply the removal (see ${ctx.link(apply_kill_1.applyKills)}) at the right location.
### Unknown Side Effects
In case _flowR_ encounters a function call that it cannot handle, it marks the call as an unknown side effect.
You can find these as part of the dataflow graph, specifically as \`unknownSideEffects\` (with a leading underscore if sesrialized as JSON).
In the following graph, _flowR_ realizes that it is unable to correctly handle the impacts of the \`load\` call and therefore marks it as such (marked in bright red):
${await (0, doc_dfg_1.printDfGraphForCode)(treeSitter, 'load("file")\nprint(x + y)', { ctx })}
In general, as we cannot handle these correctly, we leave it up to other analyses (and ${ctx.linkPage('wiki/Query API', 'queries')}) to handle these cases
as they see fit.
The \`load\` call above degrades to an unknown side effect only because the file could not be found.
When the referenced \`.rda\`/\`.rdata\` file _is_ resolvable, flowR instead parses it natively (see ${ctx.link('RDAParser')}, supporting \`gzip\`- and \`bzip2\`-compressed files) and ${ctx.link('processLoadCall')} injects the loaded variable names into the dataflow graph as definitions, so subsequent uses resolve against them.
You can disable this and always treat \`load\` as an unknown side effect with the ${ctx.linkConfig('ignoreLoadCalls')} configuration option.
#### Linked Unknown Side Effects
Not all side effects are created equal in the sense that they stem from a specific function call.
Consider R's basic [\`graphics\`](https://www.rdocumentation.org/packages/graphics/) which
implicitly draws on the current device and does not explicitly link a function like \`points\` to the last call opening a new graphic device. In such a scenario, we use a linked side effect to mark the relation:
${await (async () => {
const [result, df] = await (0, doc_dfg_1.printDfGraphForCode)(treeSitter, 'plot(data)\npoints(data2)', { exposeResult: true, ctx });
return `
${result}
Such side effects are not marked explicitly (with a big edge) but they are part of the unknown side effects: [${[...df.dataflow.graph.unknownSideEffects].map(doc_dfg_1.formatSideEffect).join(',')}].
Additionally, we express this by a ${linkEdgeName(edge_1.EdgeType.Reads)} edge.
`;
})()}
${(0, doc_structure_1.section)('Perspectives on the Dataflow Graph', 2, 'perspectives')}
For certain questions, handling the *full* dataflow graph may be too complex or unnecessary, given that you might have to consider edge interactions, or trace
transitive relationships by yourself.
Perspectives are simplified views on the dataflow graph, tailored to specific questions, which still comply with the ${ctx.link(graph_1.DataflowGraph)} interface
so you can use them as drop-in replacements for the full dataflow graph. Although, please be aware that this does not mean that every function will work correctly—a
call graph will no longer contain information on variables, for example.
${(0, doc_structure_1.section)('Call Graphs', 3, 'perspectives-cg')}
These are simplified views on the dataflow graph, following the ${ctx.link('CallGraph')} type.
It can be obtained, e.g., by ${ctx.linkM(flowr_analyzer_1.FlowrAnalyzer, 'callGraph')}.
These graphs only contain function definitions and function calls as vertices, and ${linkEdgeName(edge_1.EdgeType.Calls)} edges.
Consider the following example:
${(0, doc_code_1.codeBlock)('r', 'f <- function() f()')}
The resulting call graph looks like this:
${await (0, doc_dfg_1.printDfGraphForCode)(treeSitter, 'f <- function() f()', { callGraph: true, ctx })}
Please note, that, due to the over-approximative nature of call-graphs, the call-graph may label some function calls that are *not*
marked as such in the full dataflow graph (which may have more precise information).
For example, if we call an unknown alias:
${(0, doc_code_1.codeBlock)('r', 'alias <- unknown\nalias(print)')}
The resulting call graph looks like this:
${await (0, doc_dfg_1.printDfGraphForCode)(treeSitter, 'alias <- unknown\nalias()', { callGraph: true, ctx })}
Here, \`unknown\` is a function call, while it is a symbol in the full dataflow graph (as we cannot resolve it):
${await (0, doc_dfg_1.printDfGraphForCode)(treeSitter, 'alias <- unknown\nalias()', { callGraph: false, ctx })}
${(0, doc_structure_1.section)('Working with the Dataflow Graph', 2, 'dfg-working')}
The ${ctx.link('DataflowInformation')} is the core result of _flowR_ and summarizes a lot of information.
Depending on what you are interested in, there exists a plethora of functions and queries to help you out, answering the most important questions.
Generally, we recommend you check out the ${ctx.link(df_helper_1.Dataflow, undefined, { type: 'variable' })} helper object!
* The **${ctx.linkPage('wiki/Query API')}** provides many functions to query the dataflow graph for specific information (dependencies, calls, slices, clusters, ...)
* The **${ctx.linkPage('wiki/Search API')}** allows you to search for specific vertices or edges in the dataflow graph or the original program
* ${ctx.link(node_id_1.recoverName)} and ${ctx.link(node_id_1.recoverContent)} to get the name or content of a vertex in the dataflow graph
* ${ctx.link(resolve_helper_1.Resolve.toValue)} to resolve the value of a variable or id (if possible, see [below](#dfg-resolving-values))
* ${ctx.link(alias_tracking_1.getAliases)} to get all (potentially currently) aliases of a given definition
* ${ctx.link(identify_link_to_last_call_relation_1.getValueOfArgument)} to get the (syntactical) value of an argument in a function call
* ${ctx.link(df_helper_1.Dataflow.origin)} to get information about where a read, call, ... comes from (see [below](#dfg-resolving-values))
FlowR also provides various helper objects (with the same name as the corresponding type) to help you work with the dataflow graph:
* ${ctx.link(edge_1.DfEdge, undefined, { type: 'variable' })} to get helpful functions wrt. edges (see [below](#dfg-resolving-values))
* ${ctx.link(identifier_1.Identifier, undefined, { type: 'variable' })} to get helpful functions wrt. identifiers
* ${ctx.link(graph_1.FunctionArgument, undefined, { type: 'variable' })} to get helpful functions wrt. function arguments
* ${ctx.link(resolve_helper_1.Resolve, undefined, { type: 'variable' })} (also reachable as \`Dataflow.resolve\`) to resolve a name against an environment or a node to its value.
The entry points differ a lot in cost, so take the narrowest one that answers your question: \`byName\` walks the environment layers once and is served from the layer cache,
\`byNameAndType\` additionally filters and merges the definitions of every layer it passes, and \`toValue\` as well as the \`argument\` family run the evaluator on top of a resolution.
Some of these functions have been explained in their respective wiki pages. However, some are part of the ${ctx.linkPage('wiki/Dataflow Graph', 'Dataflow Graph API')} and so we explain them here.
If you are interested in which features we support and which features are still to be worked on, please refer to our ${ctx.linkPage('wiki/Capabilities', 'capabilities')} page.
${(0, doc_structure_1.section)('Resolving Values', 3, 'dfg-resolving-values')}
FlowR supports a ${ctx.linkPage('wiki/Interface', 'configurable', 'configuring-flowr')} level of value tracking—all with the goal of knowing the static value domain of a variable.
These capabilities are exposed by the ${(0, doc_query_1.linkToQueryOfName)('resolve-value', 'resolve value Query')} and backed by two important functions:
${ctx.link(resolve_helper_1.Resolve.toValue)} provides an environment-sensitive (see ${ctx.link('REnvironmentInformation')})
value resolution depending on if the environment is provided.
The idea of ${ctx.link(resolve_helper_1.Resolve.toValue)} is to provide a compromise between precision and performance, to
be used _during_ and _after_ the core analysis. After the dataflow analysis completes, there are much more expensive queries possible (such as the resolution of the data frame shape, see the ${ctx.linkPage('wiki/Query API', 'Query API')}).
Additionally, to ${ctx.link(resolve_helper_1.Resolve.toValue)}, we offer the aforementioned ${ctx.link(identify_link_to_last_call_relation_1.getValueOfArgument)} to retrieve the value of an argument in a function call.
Be aware, that this function is currently not optimized for speed, so if you frequently require the values of multiple arguments of the same function call, you may want to open [an issue](${doc_issue_1.NewIssueUrl}) to request support for resolving
multiple arguments at once.
${(0, doc_structure_1.section)('Assessing Edges', 3, 'dfg-assess-edge')}
The [edges](#edges) of the dataflow graph use bitmasks to represent an edge with multiple types. While this compacts the representation greatly, it makes it
difficult to check whether a given edge is a read edge.
Consider the following example:
${await (0, doc_dfg_1.printDfGraphForCode)(treeSitter, 'print(x)', { mark: new Set(['3->1']), ctx })}
Retrieving the _types_ of the edge from the print call to its argument returns:
${await (async () => {
const dfg = await (0, default_pipelines_1.createDataflowPipeline)(treeSitter, {
context: (0, flowr_analyzer_context_1.contextFromInput)('print(x)')
}).allRemainingSteps();
const edge = dfg.dataflow.graph.outgoingEdges(3);
if (edge) {
const wanted = edge.get(1);
if (wanted) {
return '`' + wanted.types + '`';
}
}
throw new Error('Could not find edge');
})()}—which is usually not very helpful.
You can use ${ctx.linkO(edge_1.DfEdge, 'splitTypes')} to get the individual bitmasks of all included types, and
${ctx.linkO(edge_1.DfEdge, 'includesType')} to check whether a specific type (or one of a collection of types) is included in the edge.
${(0, doc_structure_1.section)('Handling Origins', 3, 'dfg-handling-origins')}
If you are writing another analysis on top of the dataflow graph, you probably want to know all definitions that serve as the source of a read, all functions
that are called by an invocation, and more.
For this, the ${ctx.link(df_helper_1.Dataflow.origin)} (this is also accessible with ${ctx.linkO(df_helper_1.Dataflow, 'origin')}) function provides you with a collection of ${ctx.link('Origin')} objects:
${ctx.hierarchy('Origin', { openTop: true })}
Their respective uses are documented alongside their implementation:
${['SimpleOrigin', 'FunctionCallOrigin', 'BuiltInFunctionOrigin'].sort((a, b) => a.localeCompare(b)).map(key => `- ${ctx.link(key)}\\\n${ctx.doc(key, { type: 'interface' })}`).join('\n')}
Please note, the current structure of this function is biased by what implementations already exist in flowR.
Hence, we do not just track definitions and constants, but also the origins of function calls, albeit we do not yet track the origins of values (only resorting to
a constant origin). If you are confused by this please start a discussion—in a way we are still deciding on a good API for this.
`;
})()}
`;
}
}
exports.WikiDataflowGraph = WikiDataflowGraph;
//# sourceMappingURL=wiki-dataflow-graph.js.map