import type { ContextStack } from '../evaluator/ContextStack';
import type { EvaluateNode } from '../evaluator/interface';
import type { GetUndefinedSymbols, UndefinedSymbols } from '../getUndefinedSymbols';
import type { Any, Arr } from '../interface';
import type { AstNode, UserDefinedFunction } from '../parser/types';
import type { SourceCodeInfo } from '../tokenizer/token';
import type { MaybePromise } from '../utils/maybePromise';
import type { SpecialExpressions } from '.';
export type Arity = {
    min?: number;
    max?: number;
};
declare const dataTypes: readonly ["number", "string", "object", "array", "vector", "matrix", "grid", "boolean", "atom", "function", "integer", "any", "null", "collection", "sequence", "regexp", "effect", "never"];
export type DataType = typeof dataTypes[number];
export declare function isDataType(arg: string): arg is DataType;
export declare const categoryRecord: {
    readonly 'special-expression': true;
    readonly predicate: true;
    readonly sequence: true;
    readonly collection: true;
    readonly array: true;
    readonly object: true;
    readonly string: true;
    readonly math: true;
    readonly functional: true;
    readonly 'regular-expression': true;
    readonly bitwise: true;
    readonly misc: true;
    readonly meta: true;
    readonly assertion: true;
    readonly vector: true;
    readonly linearAlgebra: true;
    readonly matrix: true;
    readonly grid: true;
    readonly numberTheory: true;
    readonly convert: true;
    readonly json: true;
    readonly time: true;
    readonly effectHandler: true;
    readonly macros: true;
    readonly shorthand: true;
    readonly datatype: true;
    readonly effect: true;
    readonly 'playground-effect': true;
    readonly ast: true;
    readonly test: true;
};
export type Category = keyof typeof categoryRecord;
export declare const categories: Category[];
export declare const moduleCategories: Category[];
export declare const coreCategories: Category[];
export declare const coreCategoryDescriptions: Record<string, string>;
export interface TypedValue {
    type: DataType[] | DataType;
    rest?: true;
    array?: true;
}
export type Argument = TypedValue & {
    description?: string;
};
export interface Variant {
    argumentNames: string[];
}
export type ExampleEntry = string | {
    code: string;
    noRun: true;
} | {
    code: string;
    throws: true;
} | {
    code: string;
    noCheck: true;
} | {
    code: string;
    noRun: true;
    noCheck: true;
};
export interface FunctionDocs {
    category: Category;
    description: string;
    returns: TypedValue;
    args: Record<string, Argument>;
    variants: Variant[];
    examples: ExampleEntry[];
    seeAlso?: string[];
    hideOperatorForm?: true;
    tags?: string[];
    /** Type annotation in Dvala syntax, parsed by the typechecker.
     * e.g. "(Number, Number) -> Number" or "(x: Unknown) -> x is Number" */
    type?: string;
    /**
     * Handler-wrapper metadata. When set, the declared function is a
     * wrapper that installs a handler over its thunk argument. The
     * typechecker attaches a `HandlerWrapperInfo` to the parsed function
     * type so call sites apply the handler-typing application law:
     * `(thunk_effects \ handled) ∪ introduced`.
     *
     * - `paramIndex`: zero-based index of the thunk parameter.
     * - `handled`: names of effects the wrapper catches.
     * - `introduced`: names of effects the wrapper's inner handler
     *   clauses or transform perform (which become visible in the
     *   outer effect set).
     *
     * Effect names must be declared (either as builtin effects or via
     * `effect @name(T) -> U`) before the module is registered — the
     * typechecker looks up each name's arg/ret signatures in the effect
     * registry.
     *
     * Note: `handled` and `introduced` do not cancel in degenerate
     * cases. `retry` declares both as `[dvala.error]` because on final
     * retry exhaustion it re-performs the error, so calling `retry(n, pureBody)`
     * conservatively surfaces `@dvala.error` in the caller's effect set
     * even when the body never performs it. This is a sound
     * over-approximation — at runtime the effect may or may not occur
     * depending on control flow, and the type system picks the upper
     * bound. Concrete cancellation would require conditional typing
     * that Dvala's effect system does not (and probably shouldn't) model.
     */
    wrapper?: {
        paramIndex: number;
        handled: string[];
        introduced: string[];
    };
}
export interface CustomDocs {
    category: Category;
    description: string;
    customVariants: string[];
    details?: [string, string, string | undefined][];
    returns?: TypedValue;
    examples: ExampleEntry[];
    seeAlso?: string[];
    tags?: string[];
}
export type SpecialExpressionDocs = FunctionDocs | CustomDocs;
export declare function isFunctionDocs(docs: SpecialExpressionDocs): docs is FunctionDocs;
type NormalExpressionEvaluator<T> = (params: Arr, sourceCodeInfo: SourceCodeInfo | undefined, contextStack: ContextStack) => MaybePromise<T>;
export interface BuiltinNormalExpression<T> {
    evaluate: NormalExpressionEvaluator<T>;
    pure?: boolean;
    name?: string;
    arity: Arity;
    docs?: FunctionDocs;
    dvalaImpl?: UserDefinedFunction;
}
export type BuiltinNormalExpressions = Record<string, BuiltinNormalExpression<Any>>;
interface EvaluateHelpers {
    evaluateNode: EvaluateNode;
    builtin: Builtin;
    getUndefinedSymbols: GetUndefinedSymbols;
}
export interface BuiltinSpecialExpression<T, N extends AstNode> {
    evaluate?: (node: N, contextStack: ContextStack, helpers: EvaluateHelpers) => MaybePromise<T>;
    evaluateAsNormalExpression?: NormalExpressionEvaluator<T>;
    arity: Arity;
    docs?: SpecialExpressionDocs;
    getUndefinedSymbols?: (node: N, contextStack: ContextStack, params: {
        getUndefinedSymbols: GetUndefinedSymbols;
        builtin: Builtin;
    }) => UndefinedSymbols;
}
export interface Builtin {
    normalExpressions: BuiltinNormalExpressions;
    specialExpressions: SpecialExpressions;
}
export {};