Engines

This document was generated from 'src/documentation/wiki-engine.ts' on 2026-02-19, 10:46:20 UTC presenting an overview of flowR's engines (v2.9.11, using R v4.5.0). Please do not edit this file/wiki page directly.

To analyze R scripts, flowR needs to parse the R code and for that, we require a parser. Originally, flowR shipped with an RShell, an asynchronous interface to the R interpreter, still available today. Later we extended this with the RShellExecutor, the synchronous counterpart to the RShell. However, these interfaces are relatively slow as they require communication with an underlying R interpreter. Using tree-sitter, with its node bindings and R grammar, we can provide the TreeSitterExecutor which is synchronous, faster, and no longer needs an R installation, but requires the appropriate bindings. To allow users of R to freely choose their backend between the R interpreter and the tree-sitter parser, we provide the concept of engines.

Engines can be loaded with flowR's configuration file. Additionally, they are exposed with some command line options (e.g., when using the docker image of flowR):

• --engine.r-shell.disabled to disable the RShell engine
• --engine.r-shell.r-path (which is the canonical version of --r-path)
• --engine.tree-sitter.disabled to disable the TreeSitterExecutor engine
• --engine.tree-sitter.lax to use lax parsing with tree-sitter
• --engine.tree-sitter.wasm-path pass the path to the wasm of the r grammar of tree-sitter (see below)
• --engine.tree-sitter.tree-sitter-wasm-path pass the path to the wasm of tree-sitter (see below)
• --default-engine to set the default engine to use

Dealing with the R Shell Engine

The RShell engine is the original engine of flowR and is still available today. It provides a powerful interface to the R interpreter, allowing for complex interactions and the execution of R code. There are two interfaces available:

• The RShell which is asynchronous and allows for non-blocking interactions with the R interpreter. This is the default engine.
• The RShellExecutor which is synchronous and blocks the execution until the R code is executed. This can be useful for certain use cases where you want to ensure that the R code is executed before proceeding with the analysis.

Please note, that these classes are available to you even if you do not use/enable the R shell engine. The selection and preparation of the engine just reflects what the flowR analysis will use.

Dealing with the Tree-Sitter Engine

Warning

As the tree-sitter engine is only for parsing, it cannot execute R code. This engine is now the default.

In general, there is no need for you to pass custom paths using either --engine.tree-sitter.wasm-path or --engine.tree-sitter.tree-sitter-wasm-path. However, you may want to experiment with the R grammar or provide a newer one in case that of flowR is outdated.

To use a newer R grammar, you first must build the new wasm file. For this you have to:

1. Install the dependencies with npm ci in the tree-sitter-r repository.
2. Build the wasm using tree-sitter build --wasm . the tree sitter cli which should be a dev dependency.
3. Pass the tree-sitter-r.wasm to flowR.

For tree-sitter, please rely on the releases.

Note

The tree-sitter grammar may not be able to parse all valid R code due to some bugs in the parser grammar. In that case, please report these to the tree-sitter-r repository.