@eagleoutice/flowr/documentation/print-engines-wiki.js

Static Dataflow Analyzer and Program Slicer for the R Programming Language

"use strict";
var __importDefault = (this && this.__importDefault) || function (mod) {
    return (mod && mod.__esModule) ? mod : { "default": mod };
};
Object.defineProperty(exports, "__esModule", { value: true });
const shell_1 = require("../r-bridge/shell");
const log_1 = require("../../test/functionality/_helper/log");
const doc_auto_gen_1 = require("./doc-util/doc-auto-gen");
const doc_types_1 = require("./doc-util/doc-types");
const path_1 = __importDefault(require("path"));
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_cli_option_1 = require("./doc-util/doc-cli-option");
const doc_structure_1 = require("./doc-util/doc-structure");
async function getText(shell) {
    const rversion = (await shell.usedRVersion())?.format() ?? 'unknown';
    const types = (0, doc_types_1.getTypesFromFolder)({
        rootFolder: path_1.default.resolve('src/r-bridge/lang-4.x/tree-sitter/'),
        files: [path_1.default.resolve('./src/config.ts'), path_1.default.resolve('./src/r-bridge/shell.ts'), path_1.default.resolve('./src/r-bridge/shell-executor.ts')],
        inlineTypes: doc_types_1.mermaidHide
    });
    return `${(0, doc_auto_gen_1.autoGenHeader)({ filename: module.filename, purpose: 'engines', rVersion: rversion })}

To analyze R scripts, flowR needs to parse the R code and for that, we require a parser.
Originally, flowR shipped with an ${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info)}, an asynchronous interface to the R interpreter, still available today.
Later we extended this with the ${(0, doc_types_1.shortLink)(shell_executor_1.RShellExecutor.name, types.info)}, the synchronous counterpart to the ${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info)}.
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 ${(0, doc_types_1.shortLink)(tree_sitter_executor_1.TreeSitterExecutor.name, types.info)} 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):

- ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'engine.r-shell.disabled', false)} to disable the ${(0, doc_types_1.shortLink)(shell_1.RShell.name, types.info)} engine
- ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'engine.r-shell.r-path', false)} (which is the canonical version of ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'r-path')})
- ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'engine.tree-sitter.disabled', false)} to disable the ${(0, doc_types_1.shortLink)(tree_sitter_executor_1.TreeSitterExecutor.name, types.info)} engine
- ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'engine.tree-sitter.lax', false)} to use lax parsing with tree-sitter
- ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'engine.tree-sitter.wasm-path', false)} pass the path to the wasm of the r grammar of tree-sitter (see [below](#tree-sitter))
- ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'engine.tree-sitter.tree-sitter-wasm-path', false)} pass the path to the wasm of tree-sitter (see [below](#tree-sitter))
- ${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'default-engine', false)} to set the default engine to 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 
${(0, doc_cli_option_1.getCliLongOptionOf)('flowr', 'engine.tree-sitter.wasm-path', false)} or
${(0, doc_cli_option_1.getCliLongOptionOf)('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).

`;
}
/** if we run this script, we want a Markdown representation of the capabilities */
if (require.main === module) {
    (0, log_1.setMinLevelOfAllLogs)(6 /* LogLevel.Fatal */);
    const shell = new shell_1.RShell();
    void getText(shell).then(str => {
        console.log(str);
    }).finally(() => {
        shell.close();
    });
}
//# sourceMappingURL=print-engines-wiki.js.map