Engines

This document was generated from 'src/documentation/print-engines-wiki.ts' on 2025-01-22, 17:48:38 UTC presenting an overview of flowR's engines (v2.2.1, using R v4.4.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 a 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 <span title="Description (Command Line Argument): The path to the R executable to use. Defaults to your PATH. This option is being phased out in favor of the engine configuration option "engine.r-shell.r-path", which should be used instead.">--r-path)
• --engine.tree-sitter.disabled to disable the TreeSitterExecutor engine
• --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 Tree-Sitter Engine

Warning

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

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.