@eagleoutice/flowr-dev/documentation/wiki-search.js

Static Dataflow Analyzer and Program Slicer for the R Programming Language

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.WikiSearch = void 0;
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 flowr_search_executor_1 = require("../search/flowr-search-executor");
const doc_maker_1 = require("./wiki-mk/doc-maker");
const flowr_search_1 = require("../search/flowr-search");
/**
 * https://github.com/flowr-analysis/flowr/wiki/Search-API
 */
class WikiSearch extends doc_maker_1.DocMaker {
    constructor() {
        super('wiki/Search API.md', module.filename, 'search API');
    }
    async text({ ctx, shell }) {
        return `
This page briefly summarizes flowR's search API which provides a set of functions to search for nodes in the ${ctx.linkPage('wiki/Dataflow Graph', 'Dataflow Graph')} and the
${ctx.linkPage('wiki/Normalized AST', 'Normalized AST')} of a given R code (the search will always consider both, with respect to your search query).
Please see the ${ctx.linkPage('wiki/Interface', 'Interface')} wiki page for more information on how to access this API.
Within code, you can execute a search using the ${ctx.link(flowr_search_executor_1.runSearch)} 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 ${ctx.link('Q')} object (backed by ${ctx.link('FlowrSearchGenerator')}) and
are fully serializable so you can use them when communicating with the ${ctx.linkPage('wiki/Query API', 'Query API')}.

## File Path Filtering

Many convenience functions and the \`get\` generator support filtering by file path using the \`filePathRegex\` parameter.
This is useful when you want to search for nodes only in specific files.
Additionally, inline code (code without a file path) is treated as having an empty path \`""\` for regex matching purposes.

The ${ctx.link(flowr_search_builder_1.FlowrSearchGenerator)} provides several convenience functions for searching variables with file path filtering.
${ctx.linkO(flowr_search_builder_1.FlowrSearchGenerator, 'var')} and other functions like ${ctx.linkO(flowr_search_builder_1.FlowrSearchGenerator, 'get')}
also allow you to pass in a regex to only match files that fit your specified pattern! 


We offer the following generators:

${Object.keys(flowr_search_builder_1.Q).filter(n => n !== 'name').sort((a, b) => a.localeCompare(b)).map(key => `- ${ctx.linkO(flowr_search_builder_1.FlowrSearchGenerator, key)}\\\n${ctx.docO(flowr_search_builder_1.FlowrSearchGenerator, key)}`).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' && n !== 'name').sort().map(key => `- ${ctx.linkM(flowr_search_builder_1.FlowrSearchBuilder, key)}\\\n${ctx.docM(flowr_search_builder_1.FlowrSearchBuilder, key)}`).join('\n')}

Every search (and consequently the search pipeline) works with an array of ${ctx.link('FlowrSearchElement')} (neatly wrapped in ${ctx.link(flowr_search_1.FlowrSearchElements)}).
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 ${ctx.link(flowr_search_executor_1.runSearch)}.
`;
    }
}
exports.WikiSearch = WikiSearch;
//# sourceMappingURL=wiki-search.js.map