@eagleoutice/flowr/documentation/wiki-engine.js

Static Dataflow Analyzer and Program Slicer for the R Programming Language

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.WikiEngine = void 0;
const shell_1 = require("../r-bridge/shell");
const shell_executor_1 = require("../r-bridge/shell-executor");
const tree_sitter_executor_1 = require("../r-bridge/lang-4.x/tree-sitter/tree-sitter-executor");
const doc_files_1 = require("./doc-util/doc-files");
const doc_structure_1 = require("./doc-util/doc-structure");
const doc_maker_1 = require("./wiki-mk/doc-maker");
/**
 * https://github.com/flowr-analysis/flowr/wiki/Engines
 */
class WikiEngine extends doc_maker_1.DocMaker {
    constructor() {
        super('wiki/Engines.md', module.filename, 'engines');
    }
    text({ ctx }) {
        return `
To analyze R scripts, flowR needs to parse the R code and for that, we require a parser.
Originally, flowR shipped with an ${ctx.link(shell_1.RShell)}, an asynchronous interface to the R interpreter, still available today.
Later we extended this with the ${ctx.link(shell_executor_1.RShellExecutor)}, the synchronous counterpart to the ${ctx.link(shell_1.RShell)}.
However, these interfaces are relatively slow as they require communication with an underlying R interpreter.
Using [tree-sitter](https://tree-sitter.github.io/tree-sitter/), with its [node bindings](https://github.com/tree-sitter/node-tree-sitter)
and [R grammar](https://github.com/r-lib/tree-sitter-r), we can provide the ${ctx.link(tree_sitter_executor_1.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](${doc_files_1.FlowrWikiBaseRef}/Interface#configuring-flowr). Additionally, they
are exposed with some command line options (e.g., when using the docker image of flowR):

- ${ctx.cliOption('flowr', 'engine.r-shell.disabled', false)} to disable the ${ctx.link(shell_1.RShell)} engine
- ${ctx.cliOption('flowr', 'engine.r-shell.r-path', false)} (which is the canonical version of ${ctx.cliOption('flowr', 'r-path')})
- ${ctx.cliOption('flowr', 'engine.tree-sitter.disabled', false)} to disable the ${ctx.link(tree_sitter_executor_1.TreeSitterExecutor)} engine
- ${ctx.cliOption('flowr', 'engine.tree-sitter.lax', false)} to use lax parsing with tree-sitter
- ${ctx.cliOption('flowr', 'engine.tree-sitter.wasm-path', false)} pass the path to the wasm of the r grammar of tree-sitter (see [below](#tree-sitter))
- ${ctx.cliOption('flowr', 'engine.tree-sitter.tree-sitter-wasm-path', false)} pass the path to the wasm of tree-sitter (see [below](#tree-sitter))
- ${ctx.cliOption('flowr', 'default-engine', false)} to set the default engine to use

<a id="r-shell"></a>
## Dealing with the R Shell Engine

The ${ctx.link(shell_1.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 ${ctx.link(shell_1.RShell)} which is asynchronous and allows for non-blocking interactions with the R interpreter. This is the default engine.
* The ${ctx.link(shell_executor_1.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. 

<a id="tree-sitter"></a>
## Dealing with the Tree-Sitter Engine

${(0, doc_structure_1.block)({
            type: 'WARNING',
            content: '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
${ctx.cliOption('flowr', 'engine.tree-sitter.wasm-path', false)} or
${ctx.cliOption('flowr', 'engine.tree-sitter.tree-sitter-wasm-path', false)}.
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](https://github.com/r-lib/tree-sitter-r),
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](https://github.com/tree-sitter/tree-sitter) which should be a dev dependency.
3. Pass the \`tree-sitter-r.wasm\` to flowR. 

For tree-sitter, please rely on the [releases](https://github.com/tree-sitter/tree-sitter/releases).

${(0, doc_structure_1.block)({
            type: 'NOTE',
            content: '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](https://github.com/r-lib/tree-sitter-r).'
        })}
`;
    }
}
exports.WikiEngine = WikiEngine;
//# sourceMappingURL=wiki-engine.js.map