@eagleoutice/flowr/search/flowr-search-builder.d.ts

Static Dataflow Analyzer and Program Slicer for the R Programming Language

import type { NodeId } from '../r-bridge/lang-4.x/ast/model/processing/node-id';
import type { FlowrSearchElement, FlowrSearchElements, FlowrSearchGetFilter } from './flowr-search';
import type { FlowrFilterExpression } from './flowr-search-filters';
import type { FlowrSearchGeneratorNode, GeneratorNames } from './search-executor/search-generators';
import type { FlowrSearchTransformerNode, GetOutputOfTransformer, TransformerNames } from './search-executor/search-transformer';
import type { SlicingCriteria } from '../slicing/criterion/parse';
import type { ParentInformation } from '../r-bridge/lang-4.x/ast/model/processing/decorate';
type FlowrCriteriaReturn<C extends SlicingCriteria> = FlowrSearchElements<ParentInformation, C extends [] ? never : C extends [infer _] ? [
    FlowrSearchElement<ParentInformation>
] : FlowrSearchElement<ParentInformation>[]>;
/**
 * This object holds all the methods to generate search queries.
 * For compatibility, please use the {@link Q} identifier object to access these methods.
 */
export declare const FlowrSearchGenerator: {
    /**
     * Initialize a search query with the given elements.
     * <b>This is not intended to serialize well</b> wrt. the nodes,
     * see {@link FlowrSearchGenerator.criterion} for a serializable alternative (passing the ids with `$id`).
     */
    readonly from: (from: FlowrSearchElement<ParentInformation> | FlowrSearchElement<ParentInformation>[]) => FlowrSearchBuilder<"from">;
    /**
     * Returns all elements (nodes/dataflow vertices) from the given data.
     */
    readonly all: () => FlowrSearchBuilder<"all">;
    /**
     * Returns all elements that match the given {@link FlowrSearchGetFilters|filters}.
     * You may pass a negative line number to count from the back.
     * Please note that this is currently only working for single files, it approximates over the nodes, and it is not to be used for "production".
     */
    readonly get: (filter: FlowrSearchGetFilter) => FlowrSearchBuilder<"get">;
    /**
     * Returns all elements that match the given {@link SlicingCriteria|criteria}
     * (e.g., `criterion('2@x', '3@<-')`,
     * to retrieve the first use of `x` in the second line and the first `<-` assignment in the third line).
     * This will throw an error, if any criteria cannot be resolved to an id.
     */
    readonly criterion: <Criteria extends SlicingCriteria>(...criterion: Criteria) => FlowrSearchBuilder<"criterion", [], ParentInformation, FlowrCriteriaReturn<Criteria>>;
    /**
     * Short form of {@link get} with only the
     * {@link FlowrSearchGetFilters#line|line} and {@link FlowrSearchGetFilters#column|column} filters:
     * `get({line, column})`.
     */
    readonly loc: (line?: number, column?: number) => FlowrSearchBuilder<"get">;
    /**
     * Short form of {@link get} with only the {@link FlowrSearchGetFilters#name|name} and {@link FlowrSearchGetFilters#line|line} filters:
     * `get({name, line})`.
     */
    readonly varInLine: (name: string, line: number) => FlowrSearchBuilder<"get">;
    /**
     * Short form of {@link get} with only the {@link FlowrSearchGetFilters#name|name} filter:
     * `get({name})`.
     */
    readonly var: (name: string) => FlowrSearchBuilder<"get">;
    /**
     * Short form of {@link get} with only the {@link FlowrSearchGetFilters#id|id} filter:
     * `get({id})`.
     */
    readonly id: (id: NodeId) => FlowrSearchBuilder<"get">;
};
/**
 * This is the root object to use for creating searches.
 * See the {@link FlowrSearchGenerator} for the available methods.
 * After the query is generated,
 * you can use what is provided by the {@link FlowrSearchBuilder} to further refine the search.
 */
export declare const Q: {
    /**
     * Initialize a search query with the given elements.
     * <b>This is not intended to serialize well</b> wrt. the nodes,
     * see {@link FlowrSearchGenerator.criterion} for a serializable alternative (passing the ids with `$id`).
     */
    readonly from: (from: FlowrSearchElement<ParentInformation> | FlowrSearchElement<ParentInformation>[]) => FlowrSearchBuilder<"from">;
    /**
     * Returns all elements (nodes/dataflow vertices) from the given data.
     */
    readonly all: () => FlowrSearchBuilder<"all">;
    /**
     * Returns all elements that match the given {@link FlowrSearchGetFilters|filters}.
     * You may pass a negative line number to count from the back.
     * Please note that this is currently only working for single files, it approximates over the nodes, and it is not to be used for "production".
     */
    readonly get: (filter: FlowrSearchGetFilter) => FlowrSearchBuilder<"get">;
    /**
     * Returns all elements that match the given {@link SlicingCriteria|criteria}
     * (e.g., `criterion('2@x', '3@<-')`,
     * to retrieve the first use of `x` in the second line and the first `<-` assignment in the third line).
     * This will throw an error, if any criteria cannot be resolved to an id.
     */
    readonly criterion: <Criteria extends SlicingCriteria>(...criterion: Criteria) => FlowrSearchBuilder<"criterion", [], ParentInformation, FlowrCriteriaReturn<Criteria>>;
    /**
     * Short form of {@link get} with only the
     * {@link FlowrSearchGetFilters#line|line} and {@link FlowrSearchGetFilters#column|column} filters:
     * `get({line, column})`.
     */
    readonly loc: (line?: number, column?: number) => FlowrSearchBuilder<"get">;
    /**
     * Short form of {@link get} with only the {@link FlowrSearchGetFilters#name|name} and {@link FlowrSearchGetFilters#line|line} filters:
     * `get({name, line})`.
     */
    readonly varInLine: (name: string, line: number) => FlowrSearchBuilder<"get">;
    /**
     * Short form of {@link get} with only the {@link FlowrSearchGetFilters#name|name} filter:
     * `get({name})`.
     */
    readonly var: (name: string) => FlowrSearchBuilder<"get">;
    /**
     * Short form of {@link get} with only the {@link FlowrSearchGetFilters#id|id} filter:
     * `get({id})`.
     */
    readonly id: (id: NodeId) => FlowrSearchBuilder<"get">;
};
export type FlowrSearchBuilderType<Generator extends GeneratorNames = GeneratorNames, Transformers extends TransformerNames[] = TransformerNames[], Info = ParentInformation, ElementType = FlowrSearchElements<Info, FlowrSearchElement<Info>[]>> = FlowrSearchBuilder<Generator, Transformers, Info, ElementType>;
/**
 * The search query is a combination of a generator and a list of transformers
 * and allows this view to pass such queries in a serialized form.
 *
 * @typeParam Transformers - The list of transformers that are applied to the generator's output.
 */
export interface FlowrSearch<Info = ParentInformation, _Generator extends GeneratorNames = GeneratorNames, _Transformers extends readonly TransformerNames[] = readonly TransformerNames[], _ElementType = FlowrSearchElements<Info, FlowrSearchElement<Info>[]>> {
    readonly generator: FlowrSearchGeneratorNode;
    readonly search: readonly FlowrSearchTransformerNode[];
}
type FlowrSearchBuilderOut<Generator extends GeneratorNames, Transformers extends TransformerNames[], Info, Transformer extends TransformerNames> = FlowrSearchBuilder<Generator, [...Transformers, Transformer], Info, GetOutputOfTransformer<Transformer>>;
/**
 * Allows you to construct a search query from a {@link FlowrSearchGeneratorNode}.
 * Please use the {@link Q} object to create an object of this class!
 * In the end, you _can_ freeze the search by calling {@link FlowrSearchBuilder#build},
 * however, the search executors may do that for you.
 *
 * @see {@link FlowrSearchGenerator}
 * @see {@link FlowrSearch}
 * @see {@link FlowrSearchLike}
 */
export declare class FlowrSearchBuilder<Generator extends GeneratorNames, Transformers extends TransformerNames[] = [], Info = ParentInformation, ElementType = FlowrSearchElements<Info, FlowrSearchElement<Info>[]>> {
    private readonly generator;
    private readonly search;
    constructor(generator: FlowrSearchGeneratorNode);
    /**
     * only returns the elements that match the given filter.
     */
    filter(filter: FlowrFilterExpression): FlowrSearchBuilderOut<Generator, Transformers, Info, 'filter'>;
    /**
     * first either returns the first element of the search or nothing, if no elements are present.
     */
    first(): FlowrSearchBuilderOut<Generator, Transformers, Info, 'first'>;
    /**
     * last either returns the last element of the search or nothing, if no elements are present.
     */
    last(): FlowrSearchBuilderOut<Generator, Transformers, Info, 'last'>;
    /**
     * index returns the element at the given index if it exists
     */
    index<Idx extends number>(index: Idx): FlowrSearchBuilderOut<Generator, Transformers, Info, 'index'>;
    /**
     * tail returns all elements of the search except the first one.
     */
    tail(): FlowrSearchBuilderOut<Generator, Transformers, Info, 'tail'>;
    /**
     * take returns the first `count` elements of the search.
     */
    take<Count extends number>(count: Count): FlowrSearchBuilderOut<Generator, Transformers, Info, 'take'>;
    /**
     * skip returns all elements of the search except the first `count` ones.
     */
    skip<Count extends number>(count: Count): FlowrSearchBuilderOut<Generator, Transformers, Info, 'skip'>;
    /**
     * select returns only the elements at the given indices.
     */
    select<Select extends number[]>(...select: Select): FlowrSearchBuilderOut<Generator, Transformers, Info, 'select'>;
    /**
     * merge combines the search results with those of another search.
     */
    merge<Generator2 extends GeneratorNames, Transformers2 extends TransformerNames[], OtherElementType extends FlowrSearchElements<Info, FlowrSearchElement<Info>[]>>(other: FlowrSearchBuilder<Generator2, Transformers2, Info, OtherElementType>): FlowrSearchBuilder<Generator, Transformers, Info>;
    /**
     * Construct the final search (this may happen automatically with most search handlers).
     *
     * @param shouldOptimize - This may optimize the search.
     */
    build(shouldOptimize?: boolean): FlowrSearch<Info, Generator, Transformers, ElementType>;
}
/**
 * This type summarizes all types that can be used in places in which the API expects you to provide a search query.
 * @see {@link FlowrSearch}
 */
export type FlowrSearchLike = FlowrSearch | FlowrSearchBuilderType;
export type SearchOutput<Search> = Search extends FlowrSearch ? Search : Search extends FlowrSearchBuilderType<infer Generator, infer Transformers, infer Info, infer Elements> ? FlowrSearch<Info, Generator, Transformers, Elements> : never;
/**
 * Freezes any accepted {@link FlowrSearchLike} into a {@link FlowrSearch}.
 */
export declare function getFlowrSearch<Search extends FlowrSearchLike>(search: Search, optimizeIfBuild?: boolean): SearchOutput<Search>;
export {};