@eagleoutice/flowr-dev/documentation/doc-util/doc-query.d.ts

Static Dataflow Analyzer and Program Slicer for the R Programming Language

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;
    readonly ctx?: GeneralDocContext;
    /** additional in-memory files registered before the request, e.g. the targets of `source(...)` calls */
    readonly files?: readonly {
        readonly name: string;
        readonly content: 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, ctx, files }?: ShowQueryOptions): Promise<string>;
export interface QueryDocumentation {
    /** only for virtual queries, active ones carry their {@link SupportedQuery.title} */
    readonly name?: string;
    readonly type: 'virtual' | 'active';
    readonly shortDescription: string;
    readonly functionName: string;
    /** Path to the file implementing the query function, the wiki generation will fail if this isn't found */
    readonly functionFile: 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 (`f` requests a forward slice,
 * `i` inlines resolvable `source()` calls into the reconstruction; the flags may be combined as `fi`).
 */
export declare function sliceQueryShorthand(criteria: SlicingCriteria, code: string, forward?: boolean, inline?: boolean): string;
/** The display name of a query, from its definition or, for a virtual query, its documentation. */
export declare function getQueryTitle(id: string): string;
/** Mirrors the `[Linting Rule] ...` pages, see `getPageNameForLintingRule`. */
export declare function getPageNameForQuery(id: string): string;
/** `linkText` defaults to the query's title. */
export declare function linkToQueryOfName(id: SupportedQueryTypes | SupportedVirtualQueryTypes, linkText?: string): string;
/**
 *
 */
export declare function tocForQueryType(type: 'active' | 'virtual'): string;
/** Keyed by the file path each page is written to. */
export declare function queryPages(shell: RShell, ctx: GeneralDocContext, type: 'active' | 'virtual'): Promise<Record<string, string>>;
/** Without this, a new query would silently end up without a wiki page. */
export declare function assertAllQueriesDocumented(): void;