septima-lang 0.0.1

package/dist/src/value.d.ts

@@ -0,0 +1,128 @@
+import { AstNode, Lambda } from './ast-node';
+import { CallEvaluator } from './find-array-method';
+import { Span } from './location';
+import * as Stack from './stack';
+import { SymbolTable } from './symbol-table';
+declare type LambdaEvaluator = (names: string[], ast: AstNode, table: SymbolTable) => Value;
+declare type Inner = {
+    tag: 'arr';
+    val: Value[];
+} | {
+    tag: 'bool';
+    val: boolean;
+} | {
+    tag: 'foreign';
+    val: (...args: Value[]) => unknown;
+} | {
+    tag: 'lambda';
+    val: {
+        ast: Lambda;
+        table: SymbolTable;
+    };
+} | {
+    tag: 'num';
+    val: number;
+} | {
+    tag: 'obj';
+    val: Record<string, Value>;
+} | {
+    tag: 'sink';
+    val: undefined;
+    span?: Span;
+    trace?: Stack.T;
+    symbols?: SymbolTable;
+} | {
+    tag: 'str';
+    val: string;
+};
+export declare class Value {
+    readonly inner: Inner;
+    private constructor();
+    static bool(val: boolean): Value;
+    static num(val: number): Value;
+    /**
+     * Returns a Value which is essentially a "sink": (almost) every computation involving a sink evaluates to sink. A few
+     * quick examples: `5+sink`, `sink.x`, `sink()`, `Object.keys(sink)`, `if (sink) 4 else 8` all evaluate to `sink`. The
+     * raitonale is that once an expression evaluates to `sink` all expressions depending on it also evaluate to `sink`.
+     *
+     * There are however a few (intentional) exemptions:
+     * (i) a sink can be passed as an actual parameter in a function call. Hence `(fun (x,y) y)(sink, 5)` will evaluate
+     *    to `5`.
+     * (ii) a sink can be compared with itself.
+     * (iii) in `if()` expressions, only one of the branches is evlauated (based on the condition's value). As a result,
+     *    evluation of a sink-producing branch can be skipping. Specifically, `if (true) 5 else sink` evaluates to `5`.
+     * (iv) in `||` and `&&` expressions, the evaluation of the right hand side can be skipped. Specifically,
+     *    `true || sink` evaluates to `true` and `false && sink` evaluates to `false`.
+     */
+    static sink(span?: Span, trace?: Stack.T, symbols?: SymbolTable): Value;
+    static str(val: string): Value;
+    static arr(val: Value[]): Value;
+    static obj(val: Record<string, Value>): Value;
+    static lambda(ast: Lambda, table: SymbolTable): Value;
+    static foreign(f: (...args: Value[]) => unknown): Value;
+    isSink(): boolean;
+    unwrap(): unknown;
+    assertBool(): boolean;
+    assertNum(): number;
+    assertStr(): string;
+    assertArr(): Value[];
+    assertObj(): Record<string, Value>;
+    assertLambda(): {
+        ast: Lambda;
+        table: SymbolTable;
+    };
+    isLambda(): boolean;
+    ifElse(positive: () => Value, negative: () => Value): Value;
+    bindToSpan(span: Span): Value;
+    trace(): AstNode[] | undefined;
+    symbols(): SymbolTable | undefined;
+    span(): Span | undefined;
+    or(that: () => Value): Value;
+    and(that: () => Value): Value;
+    unsink(that: () => Value): Value;
+    equalsTo(that: Value): Value;
+    not(): Value;
+    private binaryNumericOperator;
+    plus(that: Value): Value;
+    minus(that: Value): Value;
+    times(that: Value): Value;
+    power(that: Value): Value;
+    over(that: Value): Value;
+    modulo(that: Value): Value;
+    negate(): Value;
+    isToZero(comparator: '<' | '<=' | '==' | '!=' | '>=' | '>'): Value;
+    isTrue(): boolean;
+    isZero(): boolean;
+    /**
+     * Determines the order beteween `this` and the given argument (`that`). The behavior of this method is dictated by
+     * the following principles:
+     *
+     * (i) if a < b then b >= a (i.e., it provides a consistent answer regardless of the whether `this` is `a`
+     *    and `that` is `b` or vice versa)
+     * (ii) ordering two values of different type result in runtime error.
+     * (iii) orderingg a value with itself evaluates to `0`
+     *
+     * Principles (i) and (iii) realizes the intuitive behavior of comparisons. (ii) realizes the idea that
+     * "one cannot compare oranges and apples". This is essentially a design decision. We could have gone with defining
+     * some order between types (the tag of a Value object), but we feel that a saner approach is to say "we do not know
+     * how to sort an array containing numbers and booleans".
+     *
+     * IMPORTANT: these principles overpower other principles. In parituclar, the principles that "an expression with
+     * sink evaluates to sink" is trumped by comparison principle (ii)
+     *
+     * @param that
+     * @returns
+     */
+    order(that: Value): Value;
+    static toStringOrNumber(input: string | Value): string | number;
+    access(indexValue: string | Value, callEvaluator: CallEvaluator): Value;
+    call(args: Value[], evaluator: LambdaEvaluator): Value;
+    keys(): Value;
+    entries(): Value;
+    fromEntries(): Value;
+    toString(): string;
+    toJSON(): unknown;
+    export(): unknown;
+    static from(u: unknown): Value;
+}
+export {};