@eagleoutice/flowr 2.6.1 → 2.6.3

package/documentation/doc-util/doc-code.js

@@ -5,12 +5,36 @@ exports.codeInline = codeInline;
 exports.jsonWithLimit = jsonWithLimit;
 const json_1 = require("../../util/json");
 const environment_1 = require("../../dataflow/environments/environment");
+/**
+ * Produces a code block in markdown format.
+ * @example
+ * ```typescript
+ * codeBlock('ts', 'const x = 42;');
+ * // Produces:
+ * //
+ * // ```ts
+ * // const x = 42;
+ * // ```
+ * ```
+ */
 function codeBlock(language, code) {
     return `\n\`\`\`${language}\n${code?.trim() ?? ''}\n\`\`\`\n`;
 }
+/**
+ * Produces an inline code span in markdown format.
+ * @example
+ * ```typescript
+ * codeInline('const x = 42;');
+ * // Produces: `<code>const x = 42;</code>`
+ * ```
+ */
 function codeInline(code) {
     return `<code>${code}</code>`;
 }
+/**
+ * Produces a JSON code block in markdown format, with optional length limit.
+ * If the pretty-printed JSON exceeds the limit, a message is shown instead of the full JSON.
+ */
 function jsonWithLimit(object, maxLength = 5_000, tooLongText = '_As the code is pretty long, we inhibit pretty printing and syntax highlighting (JSON, hiding built-in):_') {
     const prettyPrinted = JSON.stringify(object, json_1.jsonReplacer, 2);
     return `

package/documentation/doc-util/doc-dfg.d.ts

@@ -1,9 +1,12 @@
-import type { DataflowGraph, UnknownSidEffect } from '../../dataflow/graph/graph';
-import type { RShell } from '../../r-bridge/shell';
-import type { MermaidMarkdownMark } from '../../util/mermaid/dfg';
-import { DEFAULT_DATAFLOW_PIPELINE } from '../../core/steps/pipeline/default-pipelines';
+import type { DataflowGraph, UnknownSideEffect } from '../../dataflow/graph/graph';
+import { type MermaidMarkdownMark } from '../../util/mermaid/dfg';
+import type { DEFAULT_DATAFLOW_PIPELINE } from '../../core/steps/pipeline/default-pipelines';
 import type { PipelineOutput } from '../../core/steps/pipeline/pipeline';
 import type { KnownParser } from '../../r-bridge/parser';
+/**
+ * Visualizes the dataflow graph as a mermaid graph inside a markdown code block.
+ * Please use this only for documentation purposes, for programmatic usage use {@link graphToMermaid} directly.
+ */
 export declare function printDfGraph(graph: DataflowGraph, mark?: ReadonlySet<MermaidMarkdownMark>, simplified?: boolean): string;
 export interface PrintDataflowGraphOptions {
     readonly mark?: ReadonlySet<MermaidMarkdownMark>;
@@ -13,7 +16,10 @@ export interface PrintDataflowGraphOptions {
     readonly switchCodeAndGraph?: boolean;
     readonly simplified?: boolean;
 }
-export declare function formatSideEffect(ef: UnknownSidEffect): string;
+/**
+ * Visualizes a side effect for documentation purposes.
+ */
+export declare function formatSideEffect(ef: UnknownSideEffect): string;
 export declare function printDfGraphForCode(parser: KnownParser, code: string, options: PrintDataflowGraphOptions & {
     exposeResult: true;
 }): Promise<[string, PipelineOutput<typeof DEFAULT_DATAFLOW_PIPELINE>]>;
@@ -21,4 +27,4 @@ export declare function printDfGraphForCode(parser: KnownParser, code: string, o
     exposeResult?: false | undefined;
 }): Promise<string>;
 /** returns resolved expected df graph */
-export declare function verifyExpectedSubgraph(shell: RShell, code: string, expectedSubgraph: DataflowGraph): Promise<DataflowGraph>;
+export declare function verifyExpectedSubgraph(parser: KnownParser, code: string, expectedSubgraph: DataflowGraph): Promise<DataflowGraph>;

package/documentation/doc-util/doc-dfg.js

@@ -5,9 +5,7 @@ exports.formatSideEffect = formatSideEffect;
 exports.printDfGraphForCode = printDfGraphForCode;
 exports.verifyExpectedSubgraph = verifyExpectedSubgraph;
 const dfg_1 = require("../../util/mermaid/dfg");
-const pipeline_executor_1 = require("../../core/pipeline-executor");
 const default_pipelines_1 = require("../../core/steps/pipeline/default-pipelines");
-const retriever_1 = require("../../r-bridge/retriever");
 const decorate_1 = require("../../r-bridge/lang-4.x/ast/model/processing/decorate");
 const resolve_graph_1 = require("../../dataflow/graph/resolve-graph");
 const diff_dataflow_graph_1 = require("../../dataflow/graph/diff-dataflow-graph");
@@ -15,7 +13,11 @@ const assert_1 = require("../../util/assert");
 const time_1 = require("../../util/text/time");
 const doc_files_1 = require("./doc-files");
 const doc_code_1 = require("./doc-code");
-const config_1 = require("../../config");
+const flowr_analyzer_context_1 = require("../../project/context/flowr-analyzer-context");
+/**
+ * Visualizes the dataflow graph as a mermaid graph inside a markdown code block.
+ * Please use this only for documentation purposes, for programmatic usage use {@link graphToMermaid} directly.
+ */
 function printDfGraph(graph, mark, simplified = false) {
     return `
 ${(0, doc_code_1.codeBlock)('mermaid', (0, dfg_1.graphToMermaid)({
@@ -26,6 +28,9 @@ ${(0, doc_code_1.codeBlock)('mermaid', (0, dfg_1.graphToMermaid)({
     }).string)}
 	`;
 }
+/**
+ * Visualizes a side effect for documentation purposes.
+ */
 function formatSideEffect(ef) {
     if (typeof ef === 'object') {
         return `${ef.id} (linked)`;
@@ -34,11 +39,16 @@ function formatSideEffect(ef) {
         return `${ef}`;
     }
 }
+/**
+ * Visualizes the dataflow graph of the given R code using the given parser.
+ * This function returns a markdown string containing the dataflow graph as a mermaid code block,
+ * along with the R code itself in a collapsible section.
+ */
 async function printDfGraphForCode(parser, code, { simplified = false, mark, showCode = true, codeOpen = false, exposeResult, switchCodeAndGraph = false } = {}) {
     const now = performance.now();
     const result = await (0, default_pipelines_1.createDataflowPipeline)(parser, {
-        request: (0, retriever_1.requestFromInput)(code)
-    }, config_1.defaultConfigOptions).allRemainingSteps();
+        context: (0, flowr_analyzer_context_1.contextFromInput)(code)
+    }).allRemainingSteps();
     const duration = performance.now() - now;
     if (switchCodeAndGraph) {
         (0, assert_1.guard)(showCode, 'can not switch code and graph if code is not shown');
@@ -71,13 +81,12 @@ ${switchCodeAndGraph ? dfGraph : codeText}
     return exposeResult ? [resultText, result] : resultText;
 }
 /** returns resolved expected df graph */
-async function verifyExpectedSubgraph(shell, code, expectedSubgraph) {
+async function verifyExpectedSubgraph(parser, code, expectedSubgraph) {
     /* we verify that we get what we want first! */
-    const info = await new pipeline_executor_1.PipelineExecutor(default_pipelines_1.DEFAULT_DATAFLOW_PIPELINE, {
-        parser: shell,
-        request: (0, retriever_1.requestFromInput)(code),
+    const info = await (0, default_pipelines_1.createDataflowPipeline)(parser, {
+        context: (0, flowr_analyzer_context_1.contextFromInput)(code),
         getId: (0, decorate_1.deterministicCountingIdGenerator)(0)
-    }, config_1.defaultConfigOptions).allRemainingSteps();
+    }).allRemainingSteps();
     expectedSubgraph.setIdMap(info.normalize.idMap);
     expectedSubgraph = (0, resolve_graph_1.resolveDataflowGraph)(expectedSubgraph);
     const report = (0, diff_dataflow_graph_1.diffOfDataflowGraphs)({ name: 'expected', graph: expectedSubgraph }, { name: 'got', graph: info.dataflow.graph }, {

package/documentation/doc-util/doc-env.d.ts

@@ -1,2 +1,5 @@
 import type { IEnvironment } from '../../dataflow/environments/environment';
+/**
+ *
+ */
 export declare function printEnvironmentToMarkdown(env: IEnvironment | undefined): string;

package/documentation/doc-util/doc-env.js

@@ -2,6 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.printEnvironmentToMarkdown = printEnvironmentToMarkdown;
 const dfg_1 = require("../../util/mermaid/dfg");
+/**
+ *
+ */
 function printEnvironmentToMarkdown(env) {
     if (env === undefined) {
         return '?? (error)';

package/documentation/doc-util/doc-escape.d.ts

@@ -1,7 +1,12 @@
 /**
  * Escapes HTML special characters in a string.
- *
  * @param str - The string to escape
  * @returns The escaped string
  */
 export declare function escapeHTML(str: string | undefined): string | undefined;
+/**
+ * Escapes newline characters in a string (Supports Windows and Unix newlines).
+ * @param str - The string to escape
+ * @returns The escaped string
+ */
+export declare function escapeNewline(str: string): string;

package/documentation/doc-util/doc-escape.js

@@ -1,9 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.escapeHTML = escapeHTML;
+exports.escapeNewline = escapeNewline;
 /**
  * Escapes HTML special characters in a string.
- *
  * @param str - The string to escape
  * @returns The escaped string
  */
@@ -16,4 +16,14 @@ function escapeHTML(str) {
         "'": ''',
     }[tag] ?? tag));
 }
+/**
+ * Escapes newline characters in a string (Supports Windows and Unix newlines).
+ * @param str - The string to escape
+ * @returns The escaped string
+ */
+function escapeNewline(str) {
+    return str.replace(/([\n\r])/g, (match) => {
+        return match == '\n' ? '\\n' : '\\r';
+    });
+}
 //# sourceMappingURL=doc-escape.js.map

package/documentation/doc-util/doc-files.d.ts

@@ -1,3 +1,4 @@
+export declare const FlowrGithubGroupName = "flowr-analysis";
 export declare const FlowrGithubBaseRef = "https://github.com/flowr-analysis";
 export declare const FlowrSiteBaseRef = "https://flowr-analysis.github.io/flowr";
 export declare const RemoteFlowrFilePathBaseRef = "https://github.com/flowr-analysis/flowr/tree/main/";
@@ -7,6 +8,16 @@ export declare const FlowrDockerRef = "https://hub.docker.com/r/eagleoutice/flow
 export declare const FlowrCodecovRef = "https://app.codecov.io/gh/flowr-analysis/flowr";
 export declare const FlowrVsCode = "https://marketplace.visualstudio.com/items?itemName=code-inspect.vscode-flowr";
 export declare const FlowrPositron = "https://open-vsx.org/extension/code-inspect/vscode-flowr";
+/**
+ * Returns a markdown link to the given file path relative to the project root.
+ */
 export declare function getFilePathMd(path: string): string;
+/**
+ * Returns the content of a file located at the given path relative to the project root.
+ * This reads the file synchronously from disk.
+ */
 export declare function getFileContentFromRoot(path: string): string;
+/**
+ * Returns a markdown link to the given flowr source file path.
+ */
 export declare function linkFlowRSourceFile(path: string): string;

package/documentation/doc-util/doc-files.js

@@ -3,20 +3,24 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FlowrPositron = exports.FlowrVsCode = exports.FlowrCodecovRef = exports.FlowrDockerRef = exports.FlowrNpmRef = exports.FlowrWikiBaseRef = exports.RemoteFlowrFilePathBaseRef = exports.FlowrSiteBaseRef = exports.FlowrGithubBaseRef = void 0;
+exports.FlowrPositron = exports.FlowrVsCode = exports.FlowrCodecovRef = exports.FlowrDockerRef = exports.FlowrNpmRef = exports.FlowrWikiBaseRef = exports.RemoteFlowrFilePathBaseRef = exports.FlowrSiteBaseRef = exports.FlowrGithubBaseRef = exports.FlowrGithubGroupName = void 0;
 exports.getFilePathMd = getFilePathMd;
 exports.getFileContentFromRoot = getFileContentFromRoot;
 exports.linkFlowRSourceFile = linkFlowRSourceFile;
 const fs_1 = __importDefault(require("fs"));
-exports.FlowrGithubBaseRef = 'https://github.com/flowr-analysis';
-exports.FlowrSiteBaseRef = 'https://flowr-analysis.github.io/flowr';
+exports.FlowrGithubGroupName = 'flowr-analysis';
+exports.FlowrGithubBaseRef = `https://github.com/${exports.FlowrGithubGroupName}`;
+exports.FlowrSiteBaseRef = `https://${exports.FlowrGithubGroupName}.github.io/flowr`;
 exports.RemoteFlowrFilePathBaseRef = `${exports.FlowrGithubBaseRef}/flowr/tree/main/`;
 exports.FlowrWikiBaseRef = `${exports.FlowrGithubBaseRef}/flowr/wiki`;
 exports.FlowrNpmRef = 'https://www.npmjs.com/package/@eagleoutice/flowr';
 exports.FlowrDockerRef = 'https://hub.docker.com/r/eagleoutice/flowr';
-exports.FlowrCodecovRef = 'https://app.codecov.io/gh/flowr-analysis/flowr';
+exports.FlowrCodecovRef = `https://app.codecov.io/gh/${exports.FlowrGithubGroupName}/flowr`;
 exports.FlowrVsCode = 'https://marketplace.visualstudio.com/items?itemName=code-inspect.vscode-flowr';
 exports.FlowrPositron = 'https://open-vsx.org/extension/code-inspect/vscode-flowr';
+/**
+ * Returns a markdown link to the given file path relative to the project root.
+ */
 function getFilePathMd(path) {
     // we go one up as we are in doc-util now :D #convenience
     const fullpath = require.resolve('../' + path);
@@ -26,10 +30,17 @@ function getFilePathMd(path) {
     /* remove project prefix */
     return `[\`${relative}\`](${exports.RemoteFlowrFilePathBaseRef}${relative})`;
 }
+/**
+ * Returns the content of a file located at the given path relative to the project root.
+ * This reads the file synchronously from disk.
+ */
 function getFileContentFromRoot(path) {
     const fullpath = require.resolve('../../../' + path);
     return fs_1.default.readFileSync(fullpath, 'utf-8');
 }
+/**
+ * Returns a markdown link to the given flowr source file path.
+ */
 function linkFlowRSourceFile(path) {
     return `[${path}](${exports.RemoteFlowrFilePathBaseRef}/${path})`;
 }

package/documentation/doc-util/doc-general.d.ts

@@ -1,2 +1,28 @@
+/**
+ * Prefixes each line in the given string with the given prefix.
+ * @example
+ * ```ts
+ * const text = `Line 1
+ * Line 2
+ * Line 3`;
+ * const prefixed = prefixLines(text, '> ');
+ * console.log(prefixed);
+ * ```
+ * This will output:
+ * ```md
+ * > Line 1
+ * > Line 2
+ * > Line 3
+ * ```
+ */
 export declare function prefixLines(line: string, prefix: string): string;
+/**
+ * Joins the given elements using the given join string, but uses a different string for the last join.
+ * @example
+ * ```ts
+ * const items = ['apple', 'banana', 'cherry'];
+ * const result = lastJoin(items, ', ', ' and ');
+ * console.log(result); // Output: "apple, banana and cherry"
+ * ```
+ */
 export declare function lastJoin(elements: readonly string[], join: string, lastjoin: string): string;

package/documentation/doc-util/doc-general.js

@@ -2,9 +2,35 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.prefixLines = prefixLines;
 exports.lastJoin = lastJoin;
+/**
+ * Prefixes each line in the given string with the given prefix.
+ * @example
+ * ```ts
+ * const text = `Line 1
+ * Line 2
+ * Line 3`;
+ * const prefixed = prefixLines(text, '> ');
+ * console.log(prefixed);
+ * ```
+ * This will output:
+ * ```md
+ * > Line 1
+ * > Line 2
+ * > Line 3
+ * ```
+ */
 function prefixLines(line, prefix) {
     return line.split('\n').map(l => `${prefix}${l}`).join('\n');
 }
+/**
+ * Joins the given elements using the given join string, but uses a different string for the last join.
+ * @example
+ * ```ts
+ * const items = ['apple', 'banana', 'cherry'];
+ * const result = lastJoin(items, ', ', ' and ');
+ * console.log(result); // Output: "apple, banana and cherry"
+ * ```
+ */
 function lastJoin(elements, join, lastjoin) {
     if (elements.length <= 1) {
         return elements.join(lastjoin);

package/documentation/doc-util/doc-normalized-ast.d.ts

@@ -1,12 +1,23 @@
 import type { DataflowGraph } from '../../dataflow/graph/graph';
 import type { RShell } from '../../r-bridge/shell';
-import type { RNodeWithParent } from '../../r-bridge/lang-4.x/ast/model/processing/decorate';
+import { type ParentInformation, type RNodeWithParent } from '../../r-bridge/lang-4.x/ast/model/processing/decorate';
 import type { KnownParser } from '../../r-bridge/parser';
-export declare function printNormalizedAst(ast: RNodeWithParent, prefix?: string): string;
+import type { RProject } from '../../r-bridge/lang-4.x/ast/model/nodes/r-project';
+/**
+ * Visualizes the normalized AST using mermaid syntax.
+ * This is mainly intended for documentation purposes.
+ */
+export declare function printNormalizedAst(ast: RProject<ParentInformation> | RNodeWithParent, prefix?: string): string;
 export interface PrintNormalizedAstOptions {
     readonly showCode?: boolean;
     readonly prefix?: string;
 }
+/**
+ * Generates and prints the normalized AST for the given code, along with optional metadata and the original code.
+ * This is intended for documentation purposes.
+ */
 export declare function printNormalizedAstForCode(parser: KnownParser, code: string, { showCode, prefix }?: PrintNormalizedAstOptions): Promise<string>;
-/** returns resolved expected df graph */
+/**
+ * returns resolved expected df graph
+ */
 export declare function verifyExpectedSubgraph(shell: RShell, code: string, expectedSubgraph: DataflowGraph): Promise<DataflowGraph>;

package/documentation/doc-util/doc-normalized-ast.js

@@ -4,7 +4,6 @@ exports.printNormalizedAst = printNormalizedAst;
 exports.printNormalizedAstForCode = printNormalizedAstForCode;
 exports.verifyExpectedSubgraph = verifyExpectedSubgraph;
 const default_pipelines_1 = require("../../core/steps/pipeline/default-pipelines");
-const retriever_1 = require("../../r-bridge/retriever");
 const decorate_1 = require("../../r-bridge/lang-4.x/ast/model/processing/decorate");
 const resolve_graph_1 = require("../../dataflow/graph/resolve-graph");
 const diff_dataflow_graph_1 = require("../../dataflow/graph/diff-dataflow-graph");
@@ -12,7 +11,11 @@ const assert_1 = require("../../util/assert");
 const ast_1 = require("../../util/mermaid/ast");
 const time_1 = require("../../util/text/time");
 const doc_files_1 = require("./doc-files");
-const config_1 = require("../../config");
+const flowr_analyzer_context_1 = require("../../project/context/flowr-analyzer-context");
+/**
+ * Visualizes the normalized AST using mermaid syntax.
+ * This is mainly intended for documentation purposes.
+ */
 function printNormalizedAst(ast, prefix = 'flowchart TD\n') {
     return `
 \`\`\`mermaid
@@ -20,11 +23,15 @@ ${(0, ast_1.normalizedAstToMermaid)(ast, prefix)}
 \`\`\`
 	`;
 }
+/**
+ * Generates and prints the normalized AST for the given code, along with optional metadata and the original code.
+ * This is intended for documentation purposes.
+ */
 async function printNormalizedAstForCode(parser, code, { showCode = true, prefix = 'flowchart TD\n' } = {}) {
     const now = performance.now();
     const result = await (0, default_pipelines_1.createNormalizePipeline)(parser, {
-        request: (0, retriever_1.requestFromInput)(code)
-    }, config_1.defaultConfigOptions).allRemainingSteps();
+        context: (0, flowr_analyzer_context_1.contextFromInput)(code)
+    }).allRemainingSteps();
     const duration = performance.now() - now;
     const metaInfo = `The analysis required _${(0, time_1.printAsMs)(duration)}_ (including parsing with the [${parser.name}](${doc_files_1.FlowrWikiBaseRef}/Engines) engine) within the generation environment.`;
     return '\n\n' + printNormalizedAst(result.normalize.ast, prefix) + (showCode ? `
@@ -52,13 +59,15 @@ ${(0, ast_1.normalizedAstToMermaid)(result.normalize.ast, prefix)}
 
 ` : '\n(' + metaInfo + ')\n\n');
 }
-/** returns resolved expected df graph */
+/**
+ * returns resolved expected df graph
+ */
 async function verifyExpectedSubgraph(shell, code, expectedSubgraph) {
     /* we verify that we get what we want first! */
     const info = await (0, default_pipelines_1.createDataflowPipeline)(shell, {
-        request: (0, retriever_1.requestFromInput)(code),
+        context: (0, flowr_analyzer_context_1.contextFromInput)(code),
         getId: (0, decorate_1.deterministicCountingIdGenerator)(0)
-    }, config_1.defaultConfigOptions).allRemainingSteps();
+    }).allRemainingSteps();
     expectedSubgraph.setIdMap(info.normalize.idMap);
     expectedSubgraph = (0, resolve_graph_1.resolveDataflowGraph)(expectedSubgraph);
     const report = (0, diff_dataflow_graph_1.diffOfDataflowGraphs)({ name: 'expected', graph: expectedSubgraph }, { name: 'got', graph: info.dataflow.graph }, {

package/documentation/doc-util/doc-query.d.ts

@@ -2,25 +2,48 @@ import type { RShell } from '../../r-bridge/shell';
 import type { Queries, SupportedQueryTypes } from '../../queries/query';
 import type { SupportedVirtualQueryTypes } from '../../queries/virtual-query/virtual-queries';
 import type { VirtualCompoundConstraint } from '../../queries/virtual-query/compound-query';
+import type { SlicingCriteria } from '../../slicing/criterion/parse';
+import type { GeneralDocContext } from '../wiki-mk/doc-context';
+import type { KnownParser } from '../../r-bridge/parser';
 export interface ShowQueryOptions {
     readonly showCode?: boolean;
     readonly collapseResult?: boolean;
     readonly collapseQuery?: boolean;
+    readonly shorthand?: string;
 }
-export declare function showQuery<Base extends SupportedQueryTypes, VirtualArguments extends VirtualCompoundConstraint<Base> = VirtualCompoundConstraint<Base>>(shell: RShell, code: string, queries: Queries<Base, VirtualArguments>, { showCode, collapseResult, collapseQuery }?: ShowQueryOptions): Promise<string>;
+/**
+ * Visualizes a query and its results in markdown format.
+ */
+export declare function showQuery<Base extends SupportedQueryTypes, VirtualArguments extends VirtualCompoundConstraint<Base> = VirtualCompoundConstraint<Base>>(parser: KnownParser, code: string, queries: Queries<Base, VirtualArguments>, { showCode, collapseResult, collapseQuery, shorthand }?: ShowQueryOptions): Promise<string>;
 export interface QueryDocumentation {
     readonly name: string;
     readonly type: 'virtual' | 'active';
     readonly shortDescription: string;
     readonly functionName: string;
     readonly functionFile: string;
-    readonly buildExplanation: (shell: RShell) => Promise<string>;
+    readonly buildExplanation: (shell: RShell, ctx: GeneralDocContext) => Promise<string>;
 }
 export declare const RegisteredQueries: {
     active: Map<string, QueryDocumentation>;
     virtual: Map<string, QueryDocumentation>;
 };
+/**
+ * Registers a new documentation for a query.
+ */
 export declare function registerQueryDocumentation(query: SupportedQueryTypes | SupportedVirtualQueryTypes, doc: QueryDocumentation): void;
+/**
+ * Creates a REPL shorthand for the given slicing criteria and R code.
+ */
+export declare function sliceQueryShorthand(criteria: SlicingCriteria, code: string, forward?: boolean): string;
+/**
+ *
+ */
 export declare function linkToQueryOfName(id: SupportedQueryTypes | SupportedVirtualQueryTypes): string;
+/**
+ *
+ */
 export declare function tocForQueryType(type: 'active' | 'virtual'): string;
-export declare function explainQueries(shell: RShell, type: 'active' | 'virtual'): Promise<string>;
+/**
+ *
+ */
+export declare function explainQueries(shell: RShell, ctx: GeneralDocContext, type: 'active' | 'virtual'): Promise<string>;

package/documentation/doc-util/doc-query.js

@@ -3,10 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RegisteredQueries = void 0;
 exports.showQuery = showQuery;
 exports.registerQueryDocumentation = registerQueryDocumentation;
+exports.sliceQueryShorthand = sliceQueryShorthand;
 exports.linkToQueryOfName = linkToQueryOfName;
 exports.tocForQueryType = tocForQueryType;
 exports.explainQueries = explainQueries;
-const retriever_1 = require("../../r-bridge/retriever");
 const json_1 = require("../../util/json");
 const ansi_1 = require("../../util/text/ansi");
 const doc_files_1 = require("./doc-files");
@@ -16,9 +16,13 @@ const time_1 = require("../../util/text/time");
 const query_print_1 = require("../../queries/query-print");
 const flowr_analyzer_builder_1 = require("../../project/flowr-analyzer-builder");
 const doc_cli_option_1 = require("./doc-cli-option");
-async function showQuery(shell, code, queries, { showCode, collapseResult, collapseQuery } = {}) {
+/**
+ * Visualizes a query and its results in markdown format.
+ */
+async function showQuery(parser, code, queries, { showCode, collapseResult, collapseQuery, shorthand } = {}) {
     const now = performance.now();
-    const analyzer = await new flowr_analyzer_builder_1.FlowrAnalyzerBuilder((0, retriever_1.requestFromInput)(code)).setParser(shell).build();
+    const analyzer = await new flowr_analyzer_builder_1.FlowrAnalyzerBuilder().setParser(parser).build();
+    analyzer.addRequest(code);
     const results = await analyzer.query(queries);
     const duration = performance.now() - now;
     const metaInfo = `
@@ -30,8 +34,8 @@ The analysis required _${(0, time_1.printAsMs)(duration)}_ (including parsing an
 ${(0, doc_code_1.codeBlock)('json', collapseQuery ? str.split('\n').join(' ').replace(/([{[])\s{2,}/g, '$1 ').replace(/\s{2,}([\]}])/g, ' $1') : str)}
 
 ${(function () {
-        if (queries.length === 1 && Object.keys(queries[0]).length === 1) {
-            return `(This query can be shortened to \`@${queries[0].type}\` when used within the REPL command ${(0, doc_cli_option_1.getReplCommand)('query')}).`;
+        if ((queries.length === 1 && Object.keys(queries[0]).length === 1) || shorthand) {
+            return `(This query can be shortened to \`@${queries[0].type}${shorthand ? ' ' + shorthand : ''}\` when used within the REPL command ${(0, doc_cli_option_1.getReplCommand)('query')}).`;
         }
         else {
             return '';
@@ -46,7 +50,7 @@ ${await (0, query_print_1.asciiSummaryOfQueryResult)(ansi_1.markdownFormatter, d
 
 <details> <summary style="color:gray">Show Detailed Results as Json</summary>
 
-${metaInfo}	
+${metaInfo}
 
 In general, the JSON contains the Ids of the nodes in question as they are present in the normalized AST or the dataflow graph of flowR.
 Please consult the [Interface](${doc_files_1.FlowrWikiBaseRef}/Interface) wiki page for more information on how to get those.
@@ -58,7 +62,7 @@ ${(0, doc_code_1.jsonWithLimit)(results)}
 ${showCode ? `
 <details> <summary style="color:gray">Original Code</summary>
 
-${await (0, doc_dfg_1.printDfGraphForCode)(shell, code, { switchCodeAndGraph: true })}
+${await (0, doc_dfg_1.printDfGraphForCode)(parser, code, { switchCodeAndGraph: true })}
 
 </details>
 	` : ''}
@@ -71,6 +75,9 @@ exports.RegisteredQueries = {
     'active': new Map(),
     'virtual': new Map()
 };
+/**
+ * Registers a new documentation for a query.
+ */
 function registerQueryDocumentation(query, doc) {
     const map = exports.RegisteredQueries[doc.type];
     if (map.has(query)) {
@@ -78,9 +85,18 @@ function registerQueryDocumentation(query, doc) {
     }
     map.set(query, doc);
 }
+/**
+ * Creates a REPL shorthand for the given slicing criteria and R code.
+ */
+function sliceQueryShorthand(criteria, code, forward) {
+    return `(${(criteria.join(';'))})${forward ? 'f' : ''} "${code}"`;
+}
 function linkify(name) {
     return name.toLowerCase().replace(/ /g, '-');
 }
+/**
+ *
+ */
 function linkToQueryOfName(id) {
     const query = exports.RegisteredQueries.active.get(id) ?? exports.RegisteredQueries.virtual.get(id);
     if (!query) {
@@ -88,6 +104,9 @@ function linkToQueryOfName(id) {
     }
     return `[${query.name}](#${linkify(query.name)})`;
 }
+/**
+ *
+ */
 function tocForQueryType(type) {
     const queries = [...exports.RegisteredQueries[type].entries()].sort(([, { name: a }], [, { name: b }]) => a.localeCompare(b));
     const result = [];
@@ -96,11 +115,11 @@ function tocForQueryType(type) {
     }
     return result.join('\n');
 }
-async function explainQuery(shell, { name, functionName, functionFile, buildExplanation }) {
+async function explainQuery(shell, ctx, { name, functionName, functionFile, buildExplanation }) {
     return `
 ### ${name}
 
-${await buildExplanation(shell)}
+${await buildExplanation(shell, ctx)}
 
 <details> 
 
@@ -108,15 +127,18 @@ ${await buildExplanation(shell)}
 
 Responsible for the execution of the ${name} query is \`${functionName}\` in ${(0, doc_files_1.getFilePathMd)(functionFile)}.
 
-</details>	
+</details>
 
 `;
 }
-async function explainQueries(shell, type) {
+/**
+ *
+ */
+async function explainQueries(shell, ctx, type) {
     const queries = [...exports.RegisteredQueries[type].entries()].sort(([, { name: a }], [, { name: b }]) => a.localeCompare(b));
     const result = [];
     for (const [, doc] of queries) {
-        result.push(await explainQuery(shell, doc));
+        result.push(await explainQuery(shell, ctx, doc));
     }
     return result.join(`\n${'-'.repeat(5)}\n\n`);
 }

package/documentation/doc-util/doc-repl.d.ts

@@ -1,4 +1,7 @@
 import type { KnownParser } from '../../r-bridge/parser';
+/**
+ *
+ */
 export declare function printReplHelpAsMarkdownTable(): string;
 export interface DocumentReplSessionOptions {
     /** defaults to false and shows starting the repl */
@@ -14,4 +17,7 @@ export interface DocumentReplCommand {
     command: string;
     description: string;
 }
+/**
+ *
+ */
 export declare function documentReplSession(parser: KnownParser, commands: readonly DocumentReplCommand[], options?: DocumentReplSessionOptions): Promise<string>;

package/documentation/doc-util/doc-repl.js

@@ -23,6 +23,9 @@ function printHelpForScript(script, starredVersion) {
     const aliases = script[1].aliases;
     return `${base} (alias${aliases.length > 1 ? 'es' : ''}: ${aliases.map(a => '**:' + (0, html_hover_over_1.textWithTooltip)(a, `Alias of ':${script[0]}'. ${script[1].description}`) + '**').join(', ')}) |`;
 }
+/**
+ *
+ */
 function printReplHelpAsMarkdownTable() {
     const scriptHelp = [];
     const cmds = (0, repl_commands_1.getReplCommands)();
@@ -39,6 +42,9 @@ function printReplHelpAsMarkdownTable() {
 ${scriptHelp.sort().join('\n')}
 `;
 }
+/**
+ *
+ */
 async function documentReplSession(parser, commands, options) {
     const collect = [];
     for (const command of commands) {