@dallaylaen/ski-interpreter 2.6.3 → 2.8.0

package/lib/types/expr.d.ts

@@ -1,7 +1,6 @@
-import { z } from 'zod';
 import { TraverseValue } from './internal';
 /**
- * @desc Control primitives for fold() and traverse() methods.
+ *  Control primitives for fold() and traverse() methods.
  */
 export declare const control: {
     descend: <T>(value?: T) => import("./internal").TraverseControl<T>;
@@ -10,7 +9,7 @@ export declare const control: {
     stop: <T>(value?: T) => import("./internal").TraverseControl<T>;
 };
 /**
- * @desc List of predefined native combinators.
+ *  List of predefined native combinators.
  * This is required for toSKI() to work, otherwise could as well have been in parser.js.
  */
 export declare const native: Record<string, Native>;
@@ -42,20 +41,19 @@ export type RunOptions = {
     throw?: boolean;
     maxSize?: number;
 };
-export declare const FormatOptionsSchema: z.ZodObject<{
-    terse: z.ZodOptional<z.ZodBoolean>;
-    html: z.ZodOptional<z.ZodBoolean>;
-    brackets: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodString], null>>;
-    space: z.ZodOptional<z.ZodString>;
-    var: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodString], null>>;
-    lambda: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodString, z.ZodString], null>>;
-    around: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodString], null>>;
-    redex: z.ZodOptional<z.ZodTuple<[z.ZodString, z.ZodString], null>>;
-    inventory: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodCustom<Expr, Expr>>>;
-}, z.core.$strip>;
-export type FormatOptions = z.infer<typeof FormatOptionsSchema>;
+export type FormatOptions = {
+    terse?: boolean;
+    html?: boolean;
+    brackets?: [string, string];
+    space?: string;
+    var?: [string, string];
+    lambda?: [string, string, string];
+    around?: [string, string];
+    redex?: [string, string];
+    inventory?: Record<string, Named>;
+};
 /**
- * @desc A version of FormatOptions with defaults plugged in,
+ *  A version of FormatOptions with defaults plugged in,
  *       use for mandatory formatImpl implementation in Expr subclasses.
  */
 export type RefinedFormatOptions = {
@@ -69,45 +67,52 @@ export type RefinedFormatOptions = {
     redex: [string, string];
     inventory?: Record<string, Expr>;
 };
-type TraverseOptions = {
+export type TraverseOptions = {
     order?: 'LO' | 'LI' | 'leftmost-outermost' | 'leftmost-innermost';
 };
-type TraverseCallback = (e: Expr) => TraverseValue<Expr>;
+export type TraverseCallback = (e: Expr) => TraverseValue<Expr>;
+export type ToposortResult = {
+    list: Expr[];
+    env: Record<string, Named>;
+};
+/**
+ *   A combinatory logic expression.
+ *
+ *  Applications, variables, lambdas, combinators per se,
+ *  and other expression subtypes all extend this class.
+ *
+ *  Expr itself cannot (or at least should not) be instantiated.
+ *
+ *  @abstract
+ */
 export declare abstract class Expr {
-    /**
-     *  @desc A combinatory logic expression.
-     *
-     *  Applications, variables, lambdas, combinators per se,
-     *  and other expression subtypes all extend this class.
-     *
-     *  Expr itself cannot (or at least should not) be instantiated.
-     *
-     *  @abstract
-     */
-    /** @desc optional context for the term. Is set by the parser with addContext: true */
+    /**  optional context for the term. Is set by the parser with addContext: true */
     context?: {
         scope?: object;
         env?: Record<string, Expr>;
         src?: string;
         parser: object;
     };
-    /** @desc number of arguments the term is waiting for (if known) */
+    /**  number of arguments the term is waiting for (if known) */
     arity?: number;
-    /** @desc a brief description what the term does */
+    /**  a brief description what the term does */
     note?: string;
-    /** @desc the properties of the term, typically inferred from its behavior.
+    /**  the properties of the term, typically inferred from its behavior.
      *      This is used internally when declaring Native / Alias terms.
      */
     props?: TermInfo;
-    /** @desc An estimated number of nodes in the expression tree.
+    /**  An estimated number of nodes in the expression tree.
      *     Used to prevent runaway computations.
      */
     size?: number;
     /**
+     * Add metadata based on user-supplied values and/or the properties of the term itself.
      *
-     * @desc Define properties of the term based on user supplied options and/or inference results.
-     *       Typically useful for declaring Native and Alias terms.
-     * @protected
+     * Typically applied to named terms shortly after instantiation.
+     *
+     * Experimental. Name and meaning may change in the future.
+     *
+     * @experimental
      * @param {Object} options
      * @param {string} [options.note] - a brief description what the term does
      * @param {number} [options.arity] - number of arguments the term is waiting for (if known)
@@ -117,7 +122,7 @@ export declare abstract class Expr {
      * @param {number} [options.maxArgs] - maximum number of arguments for inference, if canonize is true
      * @return {this}
      */
-    _setup(options?: {
+    annotate(options?: {
         note?: string;
         arity?: number;
         fancy?: string;
@@ -126,19 +131,19 @@ export declare abstract class Expr {
         maxArgs?: number;
     }): this;
     /**
-     * @desc apply self to zero or more terms and return the resulting term,
+     *  apply self to zero or more terms and return the resulting term,
      * without performing any calculations whatsoever
      * @param {Expr} args
      * @return {Expr}
      */
     apply(...args: Expr[]): Expr;
     /**
-     * @desc Replace all aliases in the expression with their definitions, recursively.
+     *  Replace all aliases in the expression with their definitions, recursively.
      * @return {Expr}
      */
     expand(): Expr;
     /**
-     * @desc Traverse the expression tree, applying change() to each node.
+     *  Traverse the expression tree, applying change() to each node.
      *       If change() returns an Expr, the node is replaced with that value.
      *       A null/undefined value is interpreted as
      *       "descend further if applicable, or leave the node unchanged".
@@ -162,18 +167,22 @@ export declare abstract class Expr {
      * }} [options]
      * @param {(e:Expr) => TraverseValue<Expr>} change
      * @returns {Expr|null}
-     * @final
+     * @sealed
      */
     traverse(options: TraverseOptions | TraverseCallback, change?: TraverseCallback): Expr | null;
     /**
+     *
+     *
      * @protected
-     * @final
+     *
      * @param {Object} options
      * @param {(e:Expr) => TraverseValue<Expr>} change
      * @returns {TraverseValue<Expr>}
      */
     _traverse_redo(options: TraverseOptions, change: TraverseCallback): TraverseValue<Expr>;
     /**
+     * Apply a {@link traverse} callback to the subterms of the expression, without changing the expression itself.
+     *
      * @protected
      * @param {Object} options
      * @param {(e:Expr) => TraverseValue<Expr>} change
@@ -181,14 +190,14 @@ export declare abstract class Expr {
      */
     _traverse_descend(options: TraverseOptions, change: TraverseCallback): TraverseValue<Expr>;
     /**
-     * @desc Returns true if predicate() is true for any subterm of the expression, false otherwise.
+     *  Returns true if predicate() is true for any subterm of the expression, false otherwise.
      *
      * @param {(e: Expr) => boolean} predicate
      * @returns {boolean}
      */
     any(predicate: (e: Expr) => boolean): boolean;
     /**
-     * @desc Fold the expression into a single value by recursively applying combine() to its subterms.
+     *  Fold the expression into a single value by recursively applying combine() to its subterms.
      *       Nodes are traversed in leftmost-outermost order, i.e. the same order as reduction steps are taken.
      *
      * null or undefined return value from combine() means "keep current value and descend further".
@@ -204,7 +213,7 @@ export declare abstract class Expr {
      * expr.fold(0, (acc, e) => acc + 1);
      *
      * @experimental
-     * @final
+     *
      * @template T
      * @param {T} initial
      * @param {(acc: T, expr: Expr) => TraverseValue<T>} combine
@@ -212,7 +221,7 @@ export declare abstract class Expr {
      */
     fold<T>(initial: T, combine: (acc: T, expr: Expr) => TraverseValue<T>): T;
     /**
-     * @desc Internal method for fold(), which performs the actual folding.
+     *  Internal method for fold(), which performs the actual folding.
      *       Should be implemented in subclasses having any internal structure.
      *
      * @protected
@@ -222,7 +231,7 @@ export declare abstract class Expr {
     _fold<T>(initial: T, combine: (acc: T, expr: Expr) => TraverseValue<T>): TraverseValue<T>;
     /**
      * @experimental
-     * @desc  Fold an application tree bottom to top.
+     *   Fold an application tree bottom to top.
      *        For each subtree, the function is given the term in the root position and
      *        a list of the results of folding its arguments.
      *
@@ -246,7 +255,7 @@ export declare abstract class Expr {
      */
     foldBottomUp<T>(fun: (head: Expr, tail: T[]) => T): T;
     /**
-     * @desc Try to empirically find an equivalent lambda term for the expression,
+     *  Try to empirically find an equivalent lambda term for the expression,
      *       returning also the term's arity and some other properties.
      *
      *       This is used internally when declaring a Native / Alias term,
@@ -257,7 +266,7 @@ export declare abstract class Expr {
      *
      *       Use toLambda() if you want to get a lambda term in any case.
      *
-     * @final
+     * @sealed
      * @param {{max?: number, maxArgs?: number}} options
      * @return {TermInfo}
      */
@@ -267,7 +276,7 @@ export declare abstract class Expr {
         maxSize?: number;
     }): TermInfo;
     /**
-     * @desc Internal method for infer(), which performs the actual inference.
+     *  Internal method for infer(), which performs the actual inference.
      * @param {{max: number, maxArgs: number}} options
      * @param {number} nargs - var index to avoid name clashes
      * @returns {TermInfo}
@@ -280,7 +289,7 @@ export declare abstract class Expr {
         skipNames: Record<string, boolean>;
     }, nargs: number): TermInfo;
     /**
-     * @desc Expand an expression into a list of terms
+     *  Expand an expression into a list of terms
      * that give the initial expression when applied from left to right:
      * ((a, b), (c, d)) => [a, b, (c, d)]
      *
@@ -292,7 +301,7 @@ export declare abstract class Expr {
      */
     unroll(): Expr[];
     /**
-     * @desc Returns a series of lambda terms equivalent to the given expression,
+     *  Returns a series of lambda terms equivalent to the given expression,
      *       up to the provided computation steps limit.
      *
      *       Unlike infer(), this method will always return something,
@@ -300,7 +309,7 @@ export declare abstract class Expr {
      *
      *       See also Expr.walk() and Expr.toSKI().
      *
-     * @final
+     * @sealed
      * @param {{
      *   max?: number,
      *   maxArgs?: number,
@@ -319,17 +328,20 @@ export declare abstract class Expr {
         steps: number;
     }, void, unknown>;
     /**
-     * @desc Rewrite the expression into S, K, and I combinators step by step.
+     *  Rewrite the expression into S, K, and I combinators step by step.
      *     Returns an iterator yielding the intermediate expressions,
      *     along with the number of steps taken to reach them.
      *
      *     See also Expr.walk() and Expr.toLambda().
      *
-     * @final
+     * @sealed
      * @param {{max?: number}} [options]
      * @return {IterableIterator<{final: boolean, expr: Expr, steps: number}>}
      */
-    toSKI(_options?: {}): Generator<{
+    toSKI(options?: {
+        max?: number;
+        maxArgs?: number;
+    }): Generator<{
         expr: Expr;
         steps: number;
         final: boolean;
@@ -350,7 +362,7 @@ export declare abstract class Expr {
      */
     subst(search: Expr, replace: Expr): Expr | null;
     /**
-     * @desc Apply term reduction rules, if any, to the given argument.
+     *  Apply term reduction rules, if any, to the given argument.
      * A returned value of null means no reduction is possible.
      * A returned value of Expr means the reduction is complete and the application
      *     of this and arg can be replaced with the result.
@@ -370,25 +382,33 @@ export declare abstract class Expr {
      */
     invoke(arg: Expr): Invocation | null;
     /**
-     * @desc iterate one step of a calculation.
+     *  iterate one step of a calculation.
      * @return {{expr: Expr, steps: number, changed: boolean}}
      */
     step(): Step;
     /**
-     * @desc Run uninterrupted sequence of step() applications
-     *       until the expression is irreducible, or max number of steps is reached.
-     *       Default number of steps = 1000.
-     * @final
+     * Iteratively apply {@link step} to the expression until it's irreducible,
+     * or until the provided limits are reached.
+     *
+     * Returns { expr: Expr, steps: number, final: boolean }.
+     *
+     * If { throw: true } is given and no irreducible form was reached within the limits, an error is thrown.
+     *
+     * @sealed
      * @param {{max?: number, steps?: number, throw?: boolean}|Expr} [opt]
      * @param {Expr} args
      * @return {{expr: Expr, steps: number, final: boolean}}
      */
     run(opt?: RunOptions | Expr, ...args: Expr[]): Run;
     /**
-     * Execute step() while possible, yielding a brief description of events after each step.
+     * Returns an iterator of reduction steps of the expression, up to the provided limits.
+     * Each step is an object of { expr, steps, final }, same as in {@link run}.
+     *
+     * Mnemonics: like {@link run} but slower.
+     *
+     * @remarks
+     * This method is final. Do not override, override {@link step} instead.
      *
-     * Mnemonics: like run() but slower.
-     * @final
      * @param {{max?: number}} options
      * @return {IterableIterator<{final: boolean, expr: Expr, steps: number}>}
      */
@@ -397,20 +417,21 @@ export declare abstract class Expr {
         maxSize?: number;
     }): IterableIterator<Run>;
     /**
-     * @desc True is the expressions are identical, false otherwise.
+     *  True is the expressions are identical, false otherwise.
      *       Aliases are expanded.
      *       Bound variables in lambda terms are renamed consistently.
      *       However, no reductions are attempted.
      *
      *       E.g. a->b->a == x->y->x is true, but a->b->a == K is false.
      *
+     * @remarks Final. Current implementation is a frontend to {@link diff}.
+     *
      * @param {Expr} other
      * @return {boolean}
-     * @final
      */
     equals(other: Expr): boolean;
     /**
-     * @desc Recursively compare two expressions and return a string
+     *  Recursively compare two expressions and return a string
      *       describing the first point of difference.
      *       Returns null if expressions are identical.
      *
@@ -434,49 +455,51 @@ export declare abstract class Expr {
      */
     diff(other: Expr, swap?: boolean): string | null;
     /**
-     * @desc Assert expression equality. Can be used in tests.
+     *  Assert expression equality. Can be used in tests.
      *
      * `this` is the expected value and the argument is the actual one.
      * Mnemonic: the expected value is always a combinator, the actual one may be anything.
      *
      * In case of failure, an error is thrown with a message describing the first point of difference
      * and `expected` and `actual` properties like in AssertionError.
-     * AssertionError is not used directly to because browsers don't recognize it.
+     * AssertionError is not used directly because browsers don't recognize it.
      *
-     * @final
+     * @sealed
      * @param {Expr} actual
      * @param {string} comment
      */
     expect(actual: Expr | object, comment?: string): void;
     /**
-     * @desc Returns string representation of the expression.
+     *       Returns string representation of the expression.
      *       Same as format() without options.
      *
      *       Use formatImpl() to override in subclasses.
      * @return {string}
-     * @final
+     * @sealed
      */
     toString(): string;
     /**
-     * @desc Whether the expression needs parentheses when printed.
-     * @param {boolean} [first] - whether this is the first term in a sequence
+     * Whether the expression needs to be parenthesized when printed in terse mode.
+     * (see {@link format})
+     * @param isFirst whether this is the first term in a sequence
      * @return {boolean}
      * @protected
      */
-    _braced(_first?: boolean): boolean;
+    _braced(isFirst?: boolean): boolean;
     /**
-     * @desc Whether the expression can be printed without a space when followed by arg.
+     *  Whether the expression can be printed without a space when followed by arg.
      * @param {Expr} arg
      * @returns {boolean}
      * @protected
      */
     _unspaced(arg: Expr): boolean;
     /**
-     * @desc    Stringify the expression with fancy formatting options.
+     *          Stringify the expression with fancy formatting options.
      *          Said options mostly include wrappers around various constructs in form of ['(', ')'],
      *          as well as `terse` and `html` flags that fill in appropriate defaults.
      *          Format without options is equivalent to toString() and can be parsed back.
-     * @final
+     *
+     * @sealed
      *
      * @param   {Object} [options]  - formatting options
      * @param   {boolean} [options.terse]   - whether to use terse formatting (omitting unnecessary spaces and parentheses)
@@ -500,14 +523,14 @@ export declare abstract class Expr {
      * @example foo.format({terse: false}) // spell out all parentheses
      * @example foo.format({html: true}) // use HTML tags and entities
      * @example foo.format({ around: ['(', ')'], brackets: ['', ''], lambda: ['(', '->', ')'] }) // lisp style, still back-parsable
-     * @exapmle foo.format({ lambda: ['&lambda;', '.', ''] }) // pretty-print for the math department
+     * @example foo.format({ lambda: ['&lambda;', '.', ''] }) // pretty-print for the math department
      * @example foo.format({ lambda: ['', '=>', ''], terse: false }) // make it javascript
      * @example foo.format({ inventory: { T } }) // use T as a named term, expand all others
      *
      */
     format(options?: FormatOptions): string;
     /**
-     * @desc Internal method for format(), which performs the actual formatting.
+     *  Internal method for format(), which performs the actual formatting.
      * @param {Object} options
      * @param {number} nargs
      * @returns {string}
@@ -516,7 +539,7 @@ export declare abstract class Expr {
      */
     abstract formatImpl(options: RefinedFormatOptions, nargs: number): string;
     /**
-     * @desc Returns a string representation of the expression tree, with indentation to show structure.
+     *  Returns a string representation of the expression tree, with indentation to show structure.
      *
      *       Applications are flattened to avoid excessive nesting.
      *       Variables include ids to distinguish different instances of the same variable name.
@@ -537,25 +560,33 @@ export declare abstract class Expr {
      *       FreeVar: x[54]
      */
     diag(indent?: string): string;
+    declare(options?: FormatOptions & {
+        declaration?: [string, string, string];
+    }): string;
     /**
-     * @desc Convert the expression to a JSON-serializable format.
-     * @returns {string}
-     * @final
+     * Convert the expression to a JSON-serializable format.
+     * Sadly the format is not yet finalized and may change in the future.
+     *
+     * @experimental
+     * @sealed
      */
     toJSON(): string | object;
 }
+/**
+ *  Application of two {@link Expr} terms.
+ *
+ *  Never ever call `new App(fun, arg)` directly, use `fun.apply(...args)` instead.
+ */
 export declare class App extends Expr {
-    /**
-     * @desc Application of fun() to args.
-     * Never ever use new App(fun, arg) directly, use fun.apply(...args) instead.
-     * @param {Expr} fun
-     * @param {Expr} arg
-     */
     fun: Expr;
     arg: Expr;
+    /** If irreducible, cache it and don't try anymore */
     final?: boolean;
+    /**
+     * @param fun
+     * @param arg
+     */
     constructor(fun: Expr, arg: Expr);
-    /** @property {boolean} [final] */
     _traverse_descend(options: TraverseOptions, change: TraverseCallback): TraverseValue<Expr>;
     any(predicate: (e: Expr) => boolean): boolean;
     _fold<T>(initial: T, combine: (acc: T, expr: Expr) => TraverseValue<T>): TraverseValue<T>;
@@ -567,40 +598,38 @@ export declare class App extends Expr {
     invoke(arg: Expr): Invocation | null;
     unroll(): Expr[];
     diff(other: Expr, swap?: boolean): string | null;
-    _braced(first?: boolean): boolean;
+    _braced(isFirst?: boolean): boolean;
     formatImpl(options: RefinedFormatOptions, nargs: number): string;
     diag(indent?: string): string;
     _unspaced(arg: Expr): boolean;
 }
+/**
+ *  An abstract class representing a named term.
+ *
+ * @param {String} name
+ */
 export declare class Named extends Expr {
-    /**
-     * @desc An abstract class representing a term named 'name'.
-     *
-     * @param {String} name
-     */
     name: string;
     fancyName?: string;
     constructor(name: string);
     _unspaced(arg: Expr): boolean;
     formatImpl(options: RefinedFormatOptions, nargs: number): string;
 }
+/**
+ * A named variable.
+ *
+ * Given the functional nature of combinatory logic, variables are treated
+ * as functions that we don't know how to evaluate just yet.
+ *
+ * Two variables are considered the same iff they have the same `name` and `scope` properties.
+ * If `scope` is not given, the variable is only equal to itself.
+ *
+ * By convention, FreeVar.global is a constant denoting a global unbound variable.
+ */
 export declare class FreeVar extends Named {
     /**
-     * @desc A named variable.
-     *
-     * Given the functional nature of combinatory logic, variables are treated
-     * as functions that we don't know how to evaluate just yet.
-     *
-     * By default, two different variables even with the same name are considered different.
-     * They display it via a hidden id property.
-     *
-     * If a scope object is given, however, two variables with the same name and scope
-     * are considered identical.
-     *
-     * By convention, FreeVar.global is a constant denoting a global unbound variable.
-     *
-     * @param {string} name - name of the variable
-     * @param {any} scope - an object representing where the variable belongs to.
+     * @param name - name of the variable
+     * @param scope - an object representing where the variable belongs to.
      */
     scope?: object;
     id: number;
@@ -611,22 +640,23 @@ export declare class FreeVar extends Named {
     diag(indent?: string): string;
     static global: string[];
 }
+/**
+ *  A named term with a known rewriting rule.
+ *       'impl' is a function with signature Expr => Expr => ... => Expr
+ *       (see typedef Partial).
+ *       This is how S, K, I, and company are implemented.
+ *
+ *       Note that as of current something like a=>b=>b(a) is not possible,
+ *       use full form instead: a=>b=>b.apply(a).
+ *
+ * @example new Native('K', x => y => x); // constant
+ * @example new Native('Y', function(f) { return f.apply(this.apply(f)); }); // self-application
+ */
 export declare class Native extends Named {
     /**
-     * @desc A named term with a known rewriting rule.
-     *       'impl' is a function with signature Expr => Expr => ... => Expr
-     *       (see typedef Partial).
-     *       This is how S, K, I, and company are implemented.
-     *
-     *       Note that as of current something like a=>b=>b(a) is not possible,
-     *       use full form instead: a=>b=>b.apply(a).
-     *
-     * @example new Native('K', x => y => x); // constant
-     * @example new Native('Y', function(f) { return f.apply(this.apply(f)); }); // self-application
-     *
-     * @param {String} name
-     * @param {Partial} impl
-     * @param {{note?: string, arity?: number, canonize?: boolean }} [opt]
+     * @param name Name of the term
+     * @param impl A javascript implementation of the term's rewriting rule.
+     * @param opt Optional settings.
      */
     constructor(name: string, impl: (e: Expr) => Invocation, opt?: {
         note?: string;
@@ -634,24 +664,23 @@ export declare class Native extends Named {
         canonize?: boolean;
     });
 }
+/**
+ *  A lambda abstraction.
+ *
+ *  Takes an arg: {@link FreeVar} and an impl: {@link Expr}.
+ *  Upon evaluation, all occurrences of `arg` within `impl`
+ *  will be replaced by the given term.
+ *
+ *  Note that 'arg' will be replaced by a localized placeholder,
+ *  so the original variable can be used elsewhere without interference.
+ */
 export declare class Lambda extends Expr {
+    arg: FreeVar;
+    impl: Expr;
     /**
-     * @desc Lambda abstraction of arg over impl.
-     *     Upon evaluation, all occurrences of 'arg' within 'impl' will be replaced
-     *     with the provided argument.
-     *
-     * Note that 'arg' will be replaced by a localized placeholder, so the original
-     * variable can be used elsewhere without interference.
-     * Listing symbols contained in the lambda will omit such placeholder.
-     *
-     * Legacy ([FreeVar], impl) constructor is supported but deprecated.
-     * It will create a nested lambda expression.
-     *
      * @param {FreeVar} arg
      * @param {Expr} impl
      */
-    arg: FreeVar;
-    impl: Expr;
     constructor(arg: FreeVar, impl: Expr);
     invoke(arg: Expr): Expr;
     _traverse_descend(options: TraverseOptions, change: TraverseCallback): TraverseValue<Expr>;
@@ -661,43 +690,45 @@ export declare class Lambda extends Expr {
     diff(other: Expr, swap?: boolean): string | null;
     formatImpl(options: RefinedFormatOptions, nargs: number): string;
     diag(indent?: string): string;
-    _braced(first: boolean): boolean;
+    _braced(isFirst: boolean): boolean;
 }
+/**
+ *  Church numeral representing non-negative integer `n`:
+ *  `n f x = f(f(...(f x)...))` with `f` applied `n` times.
+ */
 export declare class Church extends Expr {
+    n: number;
     /**
-     * @desc Church numeral representing non-negative integer n:
-     *      n f x = f(f(...(f x)...)) with f applied n times.
      * @param {number} n
      */
-    n: number;
     constructor(n: number);
     diff(other: Expr, swap?: boolean): string | null;
     _unspaced(arg: Expr): boolean;
     formatImpl(options: RefinedFormatOptions, nargs: number): string;
 }
+/**
+ *  A named alias for an existing expression.
+ *
+ * Aliasing allows declaring new terms without a native implementation.
+ * This is what happens when one writes `B = S(KS)K` in the interpreter.
+ *
+ * Aliases are transparent in terms of `equals` and `expect`;
+ * for that reason, Alias.diag() in not adding to the indentation.
+ *
+ * Aliases have an `inline` property. Tf true, the alias will be replaced with its implementation
+ * everywhere, unless specifically told otherwise e.g. by { inventory: { ... } } option of format().
+ *
+ * Upon creation, the aliases arity is calculated (unless `canonize` is false).
+ *
+ * Upon evaluation, the alias will be replaced with its implementation,
+ * _unless_ it's not inline and has positive arity,
+ * in which case it will wait for the required number of arguments before such replacement.
+ */
 export declare class Alias extends Named {
     /**
-     * @desc A named alias for an existing expression.
-     *
-     * Aliasing allows declaring new terms without a native implementation.
-     * This is what happens when one writes `B = S(KS)K` in the interpreter.
-     *
-     * Aliases are transparent in terms of `equals` and `expect`;
-     * for that reason, Alias.diag() in not adding to the indentation.
-     *
-     * Aliases have an `inline` property. Tf true, the alias will be replaced with its implementation
-     * everywhere, unless specifically told otherwise e.g. by { inventory: { ... } } option of format().
-     *
-     * Upon creation, the aliases arity is calculated (unless `canonize` is false).
-     *
-     * Upon evaluation, the alias will be replaced with its implementation,
-     * _unless_ it's not inline and has positive arity,
-     * in which case it will wait for the required number of arguments before such replacement.
-     *
-     *
-     * @param {String} name
-     * @param {Expr} impl
-     * @param {{canonize?: boolean, max?: number, maxArgs?: number, note?: string, inline?: boolean}} [options]
+     * @param name
+     * @param impl
+     * @param options
      */
     impl: Expr;
     inline?: boolean;
@@ -710,11 +741,13 @@ export declare class Alias extends Named {
         arity?: number;
     });
     /**
-     * @desc Make the alias inline, i.e. replace it with its implementation everywhere.
+     * Make the alias inline, i.e. replace it with its implementation everywhere.
      *
      * Replaces the old `outdated` attribute.
      * Used by the parser when a term definition is removed or updated.
      *
+     *
+     *
      * May change in future versions, use with caution.
      *
      * @experimental
@@ -735,10 +768,28 @@ export declare class Alias extends Named {
      */
     step(): Step;
     diff(other: Expr, swap?: boolean): string | null;
-    _braced(first: boolean): boolean;
+    _braced(isFirst: boolean): boolean;
     formatImpl(options: RefinedFormatOptions, nargs: number): string;
     diag(indent?: string): string;
 }
+/**
+ * Topologically sort a list of terms, extending it with any missing dependency terms,
+ * if necessary. The output list is guaranteed to contain at least the input terms.
+ *
+ * @param options
+ * @param [options.list] - a single expression or a list of expressions to sort.
+ * @param [options.env]  - a set of terms assumed to be known (and thus not required in the output list).
+ * @param [options.allow]  - a set of terms that are allowed in the returned list (aside from the input list).
+ *
+ * @example
+ *    const expr = ski.parse(src);
+ *    toposort([expr], ski.getTerms()); // returns all terms appearing in Expr in correct order
+ */
+export declare function toposort(options: {
+    list?: Expr | Expr[];
+    env?: Record<string, Named>;
+    allow?: Record<string, Named>;
+}): ToposortResult;
 export declare const classes: {
     Expr: typeof Expr;
     App: typeof App;
@@ -749,4 +800,3 @@ export declare const classes: {
     Church: typeof Church;
     Alias: typeof Alias;
 };
-export {};