@eagleoutice/flowr-dev/r-bridge/lang-4.x/ast/model/processing/node-id.d.ts

Static Dataflow Analyzer and Program Slicer for the R Programming Language

import type { AstIdMap } from './decorate';
import type { DataflowGraph } from '../../../../../dataflow/graph/graph';
import type { BuiltInProcName } from '../../../../../dataflow/environments/built-in-proc-name';
/** The type of the id assigned to each node. Branded to avoid problematic usages with other string or numeric types. */
export type NodeId<T extends string | number = string | number> = T & {
    __brand?: 'node-id';
};
/**
 * A variant of {@link NodeId} that represents built-in functions or operators. The string is prefixed with `built-in:` to avoid confusion with other node ids.
 */
export type BuiltIn<T extends string = string> = `built-in:${T}`;
export declare const NodeId: {
    readonly name: "NodeId";
    /**
     * Normalizes a node id by converting numeric strings to numbers.
     * This allows us to use numeric ids without storing them as strings, while still allowing custom string ids if needed.
     */
    readonly normalize: (this: void, id: NodeId) => NodeId;
    /**
     * The prefix used for built-in function or operator ids.
     */
    readonly builtInPrefix: "built-in:";
    /**
     * Checks if a given node id is a built-in function or operator id by checking if it is a string that starts with the built-in prefix.
     * @see {@link toBuiltIn} - to convert a built-in function or operator name to a built-in id
     * @see {@link fromBuiltIn} - to recover the built-in function or operator name from a built-in id
     */
    readonly isBuiltIn: (this: void, id: BuiltIn | NodeId | undefined) => id is BuiltIn;
    /**
     * Converts a built-in function or operator name to a built-in id by prefixing it with the built-in prefix.
     * @see {@link isBuiltIn} - to check if a given node id is a built-in function or operator id
     * @see {@link fromBuiltIn} - to recover the built-in function or operator name from a built-in id
     */
    readonly toBuiltIn: <T extends string>(this: void, name: T) => BuiltIn<T>;
    /**
     * The canonical `pkg:fn` identifier of a package's exported function (e.g. `ggplot2:ggplot`). The single
     * source of this form: `Package.functionIdentifier` delegates here, and {@link fromPkgFn} wraps it.
     */
    readonly pkgFnName: <P extends string, F extends string>(this: void, pkg: P, fn: F) => `${P}:${F}`;
    /**
     * The built-in id of a package's exported function, e.g. `fromPkgFn('ggplot2', 'ggplot')` yields
     * `built-in:ggplot2:ggplot` -- {@link toBuiltIn} over the {@link pkgFnName} `pkg:fn` form.
     */
    readonly fromPkgFn: <P extends string, F extends string>(this: void, pkg: P, fn: F) => BuiltIn<`${P}:${F}`>;
    /**
     * Inverse of {@link fromPkgFn}: split a package-function built-in id (`built-in:pkg:fn`) into its `[pkg, fn]`
     * parts, or `undefined` when `id` is not one (a non-builtin id, or a bare builtin without a package such as
     * `built-in:print`). A package name never contains a `:`, so the first one separates it from the function.
     */
    readonly toPkgFn: (this: void, id: BuiltIn | NodeId | undefined) => readonly [pkg: string, fn: string] | undefined;
    /**
     * Converts a built-in function or operator name or id to a built-in id by prefixing it with the built-in prefix if it is not already a built-in id.
     * This allows us to accept both built-in names and ids in contexts where we want to work with built-in ids.
     */
    readonly mapBuiltInProc: <T extends BuiltInProcName>(this: void, proc: T) => T extends `builtin:${infer S}` ? BuiltIn<S> : BuiltIn<T>;
    /**
     * Recovers the built-in function or operator name from a built-in id by removing the built-in prefix.
     * @see {@link isBuiltIn} - to check if a given node id is a built-in function or operator id
     * @see {@link toBuiltIn} - to convert a built-in function or operator name to a built-in id
     */
    readonly fromBuiltIn: <T extends string>(this: void, id: BuiltIn<T>) => T;
};
/**
 * Recovers the lexeme of a {@link RNode|node} from its id in the {@link AstIdMap|id map}.
 * @see {@link recoverContent} - to recover the content of a node
 */
export declare function recoverName(id: NodeId, idMap?: AstIdMap): string | undefined;
/**
 * Recovers the content of a {@link RNode|node} from its id in the {@link DataflowGraph|dataflow graph}.
 */
export declare function recoverContent(id: NodeId, graph: DataflowGraph): string | undefined;