@eagleoutice/flowr/documentation/print-search-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_files_1 = require("./doc-util/doc-files");
const doc_auto_gen_1 = require("./doc-util/doc-auto-gen");
const doc_search_1 = require("./doc-util/doc-search");
const flowr_search_builder_1 = require("../search/flowr-search-builder");
const vertex_1 = require("../dataflow/graph/vertex");
const doc_types_1 = require("./doc-util/doc-types");
const path_1 = __importDefault(require("path"));
const flowr_search_executor_1 = require("../search/flowr-search-executor");
async function getText(shell) {
    const rversion = (await shell.usedRVersion())?.format() ?? 'unknown';
    const types = (0, doc_types_1.getTypesFromFolder)({
        rootFolder: path_1.default.resolve('./src/search/'),
        inlineTypes: doc_types_1.mermaidHide
    });
    return `${(0, doc_auto_gen_1.autoGenHeader)({ filename: module.filename, purpose: 'search API', rVersion: rversion })}

This page briefly summarizes flowR's search API which provides a set of functions to search for nodes in the [Dataflow Graph](${doc_files_1.FlowrWikiBaseRef}/Dataflow%20Graph) and the 
[Normalized AST](${doc_files_1.FlowrWikiBaseRef}/Normalized%20AST) of a given R code (the search will always consider both, with respect to your search query).
Please see the [Interface](${doc_files_1.FlowrWikiBaseRef}/Interface) wiki page for more information on how to access this API.
Within code, you can execute a search using the ${(0, doc_types_1.shortLink)(flowr_search_executor_1.runSearch.name, types.info)} function.

For an initial motivation, let's have a look at the following example:

${await (0, doc_search_1.showSearch)(shell, 'x <- x * x', flowr_search_builder_1.Q.var('x'))}

This returns all references to the variable \`x\` in the code.
However, the search API is not limited to simple variable references and can do much more.

For example, let's have every definition of \`x\` in the code but the first one:

${await (0, doc_search_1.showSearch)(shell, 'x <- x * x\nprint(x)\nx <- y <- 3\nprint(x)\nx <- 2', flowr_search_builder_1.Q.var('x').filter(vertex_1.VertexType.VariableDefinition).skip(1))}

In summary, every search has two parts. It is initialized with a _generator_ (such as \`Q.var('x')\`)
and can be further refined with _transformers_ or _modifiers_.
Such queries can be constructed starting from the ${(0, doc_types_1.shortLink)('Q', types.info)} object (backed by ${(0, doc_types_1.shortLink)('FlowrSearchGenerator', types.info)}) and
are fully serializable so you can use them when communicating with the [Query API](${doc_files_1.FlowrWikiBaseRef}/Query%20API).

We offer the following generators:

${Object.keys(flowr_search_builder_1.Q).sort().map(key => `- ${(0, doc_types_1.shortLink)(`FlowrSearchGenerator::${key}`, types.info)}\\\n${(0, doc_types_1.getDocumentationForType)(`FlowrSearchGenerator::${key}`, types.info)}`).join('\n')}

Likewise, we have a palette of _transformers_ and _modifiers_:

${
    /* let's iterate over all methods of FlowrSearchBuilder */
    Object.getOwnPropertyNames(Object.getPrototypeOf(new flowr_search_builder_1.FlowrSearchBuilder(undefined)))
        .filter(n => n !== 'constructor').sort().map(key => `- ${(0, doc_types_1.shortLink)(`FlowrSearchBuilder::${key}`, types.info)}\\\n${(0, doc_types_1.getDocumentationForType)(`FlowrSearchBuilder::${key}`, types.info)}`).join('\n')}

Every search (and consequently the search pipeline) works with an array of ${(0, doc_types_1.shortLink)('FlowrSearchElement', types.info)} (neatly wrapped in ${(0, doc_types_1.shortLink)('FlowrSearchElements', types.info)}).
Hence, even operations such as \`.first\` or \`.last\` return an array of elements (albeit with a single or no element).
The search API does its best to stay typesafe wrt. to the return type and the transformers in use. 
In addition, it offers optimizer passes to optimize the search pipeline before execution.
They are executed with \`.build\` which may happen automatically, whenever you want to run a search using ${(0, doc_types_1.shortLink)('runSearch', types.info)}.

`;
}
/** 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-search-wiki.js.map