@okcontract/lambdascript 0.1.0 → 0.2.0

package/README.md

@@ -18,24 +18,31 @@ reactive programs.
 Another notable property is the default use of `Rationals` for both integers
 and floats of arbitrary length throughout the standard library.
 
+## Installation
+
+```sh
+npm install @okcontract/lambdascript @okcontract/cells
+```
+
 ## Walkthrough
 
 ```ts
+import { type AnyCell, Sheet } from "@okcontract/cells";
 import { Environment, Rational } from "@okcontract/lambdascript";
-// create a new cell (see cells repo on how to create a proxy)
+
+const proxy = new Sheet().newProxy();
 const foo = proxy.new(new Rational(1));
-// create a λs Environment (and a standard library)
 const env = new Environment(proxy, {
   values: {
     foo,
   },
 });
-// expr the built reactive expression that will react to `foo` updates
-const expr = (await env.evaluateString("foo + 1")) as AnyCell<Rational>; // λs types are not known to TypeScript
+
+// The expression is recomputed whenever `foo` changes.
+const expr = (await env.evaluateString("foo + 1")) as AnyCell<Rational>;
 expect((await expr.get()).toString()).toBe("2");
-// we update foo
+
 foo.set(new Rational(2));
-// expr is automatically re-computed
 expect((await expr.get()).toString()).toBe("3");
 ```
 
@@ -53,6 +60,26 @@ const env1 = new Environment(proxy1, { lib });
 const env2 = new Environment(proxy2, { lib });
 ```
 
+## Development
+
+Building and testing `lambdascript` requires a system installation of
+[`bun`](https://bun.com). Bun is deliberately not included in the project's
+dependencies.
+
+```sh
+bun install --frozen-lockfile
+bun run grammar
+bun run test
+bun run build
+bun run definitions
+```
+
+[`biome`](https://biomejs.dev) is also deliberately not included as a project
+dependency. Install it as a system binary if you want to run `bun run format`
+or `bun run check`. The standard `bun run build` script formats the source
+before bundling, so it also expects `biome` to be available on `PATH`; direct
+use of `bun build` does not require Biome.
+
 # Design & Philosophy
 
 We aim for ease of use, correction and security, so chasing down any bug is

package/dist/ast.d.ts

@@ -1,5 +1,9 @@
-import { Rational } from "./rational";
+import { Rational } from "./rational.js";
 export type NodeType = ASTNode["type"];
+export type SourceRange = {
+    from: number;
+    to: number;
+};
 export declare const NameApplication = "app";
 export declare const NameConstant = "const";
 export declare const NameVariable = "var";
@@ -14,31 +18,39 @@ export type ASTNode = ApplicationNode | ConstantNode<unknown> | VariableNode | L
     type: "named";
     key: string;
     value: ASTNode;
+    range?: SourceRange;
 };
 export type ApplicationNode = {
     type: typeof NameApplication;
     function: ASTNode;
     params: ASTNode[];
+    range?: SourceRange;
 };
+export declare const apply: (fn: ASTNode, params: ASTNode[]) => ApplicationNode;
+export declare const applyName: (fn: string, params: ASTNode[]) => ApplicationNode;
 export type RawConstant = string | boolean | Rational;
 export interface ConstantNode<Extensions> {
     type: typeof NameConstant;
     value: RawConstant | Extensions;
+    range?: SourceRange;
 }
 export declare const newNumber: (n: string | number | bigint | Rational) => ConstantNode<unknown>;
 export declare const newConstant: (value: string | boolean | number | bigint) => ConstantNode<unknown>;
 export interface VariableNode {
     type: typeof NameVariable;
     name: string;
+    range?: SourceRange;
 }
 export declare const newVariable: (name: string) => VariableNode;
 export interface ListNode {
     type: typeof NameList;
     elements: ASTNode[];
+    range?: SourceRange;
 }
 export interface TupleNode {
     type: typeof NameTuple;
     elements: ASTNode[];
+    range?: SourceRange;
 }
 export declare const newList: (elements: ASTNode[]) => ListNode;
 export declare const newTuple: (elements: ASTNode[]) => TupleNode;
@@ -47,6 +59,7 @@ export interface ObjectNode {
     values: {
         [key: string]: ASTNode;
     };
+    range?: SourceRange;
 }
 export declare const newObject: (values: {
     [key: string]: ASTNode;
@@ -55,6 +68,7 @@ export declare const newFromJS: (value: unknown) => ASTNode;
 export type FieldNode = {
     type: typeof NameField;
     expr: ASTNode;
+    range?: SourceRange;
 } & ({
     field: string;
 } | {
@@ -64,10 +78,12 @@ export interface LambdaNode {
     type: typeof NameLambda;
     parameter: string;
     body: ASTNode;
+    range?: SourceRange;
 }
 export declare const newLambda: (parameter: string, body: ASTNode) => LambdaNode;
 export declare const newLambdaMulti: (parameters: string[], body: ASTNode) => LambdaNode;
 export interface ErrorNode {
     type: typeof NameError;
     value: string;
+    range?: SourceRange;
 }

package/dist/deps.d.ts

@@ -1,4 +1,4 @@
-import { type ASTNode } from "./ast";
+import { type ASTNode } from "./ast.js";
 /**
  * exprDependencies computes the free variables in a given expression.
  * @param expr

package/dist/env.d.ts

@@ -1,14 +1,17 @@
 import { type AnyCell, type SheetProxy } from "@okcontract/cells";
-import type { ASTNode } from "./ast";
-import { type Value } from "./eval";
-import type { ParserExtension } from "./highLevel";
-import { type ParseOptions } from "./parse";
-import { type LibraryElement, type StandardLibrary } from "./stdlib";
-import type { TypeScheme } from "./typeScheme";
+import type { ASTNode } from "./ast.js";
+import { type Value } from "./eval.js";
+import type { ParserExtension } from "./highLevel.js";
+import { type ParseOptions } from "./parse.js";
+import { type LibraryElement, type StandardLibrary } from "./stdlib.js";
+import type { TypeScheme } from "./typeScheme.js";
 export declare let envCounter: number;
 export type ValueMap = {
     [key: string]: Value<unknown>;
 };
+export type TypeMap = {
+    [key: string]: TypeScheme;
+};
 export type ValueDefinition = [string, Value<unknown>, TypeScheme];
 /**
  * Options for the Environment constructor.
@@ -17,9 +20,7 @@ export type EnvironmentOptions = {
     id?: string;
     lib?: StandardLibrary;
     values?: ValueMap;
-    types?: {
-        [key: string]: TypeScheme;
-    };
+    types?: TypeMap;
     cases?: {
         [key: string]: string;
     };
@@ -39,17 +40,16 @@ export declare class Environment {
      *       However, `inferType` for `NameLambda` uses an Environment updated
      *       with the type of the bound variable in the lambda.
      **/
-    _values: ValueMap;
+    private _values;
     /** type expressions (for values) */
     private _types;
     /** original cases for values and types */
     private _originalCases;
     readonly proxy: SheetProxy;
     initialValues: {};
-    initialTypes: {
-        [key: string]: TypeScheme;
-    };
+    initialTypes: TypeMap;
     options: EnvironmentOptions;
+    get values(): ValueMap;
     constructor(proxy: SheetProxy, options?: EnvironmentOptions);
     _updateLib(lib: StandardLibrary): void;
     library: (name: string) => LibraryElement | undefined;
@@ -76,6 +76,7 @@ export declare class Environment {
      */
     addExpression: (name: string, expr: ASTNode) => Promise<boolean>;
     addValueType: (name: string, value: Value<unknown>, type: TypeScheme) => boolean;
+    removeKey: (key: string) => void;
     /**
      * evaluateString evaluates an expression as string.
      * @param expr

package/dist/equal.d.ts

@@ -1,3 +1,3 @@
-export declare const allDiff: (a: unknown, b: unknown) => any[];
+export declare const allDiff: (a: unknown, b: unknown) => string[];
 export declare function firstDiff(a: unknown, b: unknown): string | null;
 export declare function isEqual(a: unknown, b: unknown): boolean;

package/dist/eval.d.ts

@@ -1,6 +1,6 @@
 import type { AnyCell } from "@okcontract/cells";
-import { type ASTNode } from "./ast";
-import type { Environment } from "./env";
+import { type ASTNode } from "./ast.js";
+import type { Environment } from "./env.js";
 export type PrimValue<V> = V | Value<V>[] | {
     [key: number | string]: Value<unknown>;
 };

package/dist/find.d.ts

@@ -1,14 +1,5 @@
-import { type AnyCell, type CellArray, type MapCell, type SheetProxy } from "@okcontract/cells";
-/**
- * mapArrayCell is a variant of `mapArray` with a function taking
- * element cells as arguments.
- * @param proxy
- * @param arr
- * @param fn
- * @returns mapped array cell
- */
-export declare const mapArrayCell: <T, U, NF extends boolean = false>(proxy: SheetProxy, arr: CellArray<T>, fn: AnyCell<(v: AnyCell<T>, idx?: number) => AnyCell<U>>, name?: string, nf?: NF) => MapCell<MapCell<U, NF>[], NF>;
+import { type AnyCell, type CellArray, type SheetProxy } from "@okcontract/cells";
 export declare const findCell: <T, NF extends boolean = false>(proxy: SheetProxy, arr: CellArray<T>, predicate: AnyCell<(v: AnyCell<T>) => AnyCell<boolean>>, findFunction?: {
     <S extends any>(predicate: (value: any, index: number, obj: any[]) => value is S, thisArg?: any): S;
     (predicate: (value: any, index: number, obj: any[]) => unknown, thisArg?: any): any;
-}, name?: string, nf?: NF) => MapCell<T, NF>;
+}, name?: string, nf?: NF) => import("@okcontract/cells").MapCell<any, NF>;

package/dist/format.d.ts

@@ -0,0 +1,16 @@
+export declare const Separator: {
+    readonly Space: " ";
+};
+export type Separator = (typeof Separator)[keyof typeof Separator];
+export type FormatSettings = {
+    separator: Separator;
+    spaces: number;
+    trailingCommas: boolean;
+    width: number;
+};
+export declare const defaultFormatSettings: FormatSettings;
+type FormatOptions = Partial<FormatSettings>;
+export declare const formatSource: (source: string, options?: FormatOptions) => string;
+export declare const formatExpression: (source: string, options?: FormatOptions) => string;
+export declare const formatProgram: (source: string, options?: FormatOptions) => string;
+export {};

package/dist/highLevel.d.ts

@@ -1,6 +1,6 @@
-import { type ASTNode } from "./ast";
-import type { LowLevelAST } from "./lowLevel";
-import type { TypeConst } from "./types";
+import { type ASTNode } from "./ast.js";
+import type { LowLevelAST } from "./lowLevel.js";
+import type { TypeConst } from "./types.js";
 export type ParserExtension<Result, Name extends string> = {
     elt: Name;
     pat: (value: unknown) => boolean;

package/dist/index.d.ts

@@ -1,14 +1,17 @@
-export { length, plural } from "./utils";
-export { NameApplication, NameConstant, NameError, NameField, NameLambda, NameList, NameObject, NameTuple, NameVariable, Names, newConstant, newFromJS, newLambda, newLambdaMulti, newList, newNumber, newObject, newVariable, type ASTNode, type ApplicationNode, type ConstantNode, type FieldNode, type LambdaNode, type ListNode, type ObjectNode, type VariableNode } from "./ast";
-export { newTypeScheme, type TypeScheme } from "./typeScheme";
-export { newTypeConst, newTypeObject, newTypeTuple, newTypeVar, typeAny, typeFunction, typeList, type MonoType, type TypeAny, type TypeConst } from "./types";
-export { allDiff, firstDiff, isEqual } from "./equal";
-export { toHighLevelAST, type ParserExtension } from "./highLevel";
-export { toLowLevelAST } from "./lowLevel";
-export { parseExpression, reservedKeywords } from "./parse";
-export { parser } from "./parser/λs";
-export { prettyPrint, prettyPrintType } from "./print";
-export { Environment, type ValueDefinition } from "./env";
-export { EvalOption, Program } from "./program";
-export { Rational, isRationalString, rationalNumberRegex, zero } from "./rational";
-export { defaultLibrary, rationalNumber, typeBoolean, typeBytes, typeFromJSValue, typeNumber, typeString, type FirstClassValue, type LibraryElement, type StandardLibrary } from "./stdlib";
+export { type ApplicationNode, type ASTNode, apply, applyName, type ConstantNode, type FieldNode, type LambdaNode, type ListNode, NameApplication, NameConstant, NameError, NameField, NameLambda, NameList, NameObject, Names, NameTuple, NameVariable, newConstant, newFromJS, newLambda, newLambdaMulti, newList, newNumber, newObject, newTuple, newVariable, type ObjectNode, type SourceRange, type TupleNode, type VariableNode } from "./ast.js";
+export { Environment, type EnvironmentOptions, type TypeMap, type ValueDefinition, type ValueMap } from "./env.js";
+export { allDiff, firstDiff, isEqual } from "./equal.js";
+export type { Value } from "./eval.js";
+export { defaultFormatSettings, type FormatSettings, formatExpression, formatProgram, formatSource, Separator } from "./format.js";
+export { type ParserExtension, toHighLevelAST } from "./highLevel.js";
+export { toLowLevelAST } from "./lowLevel.js";
+export { type ParsedProgram, type ProgramBinding, type ProgramComponent, parseExpression, parseProgram, reservedKeywords } from "./parse.js";
+export { parser } from "./parser/λs.js";
+export { prettyPrint, prettyPrintType } from "./print.js";
+export { type Binding, EvalOption, Program } from "./program.js";
+export { isRational, isRationalString, Rational, rationalNumberRegex, zero } from "./rational.js";
+export { evaluateASTSingle } from "./singleEval.js";
+export { defaultLibrary, type FirstClassValue, type LibraryElement, rationalNumber, type StandardLibrary, typeBoolean, typeBytes, typeFromJSValue, typeNumber, typeString } from "./stdlib.js";
+export { newTypeScheme, type TypeScheme } from "./typeScheme.js";
+export { type MonoType, newTypeConst, newTypeObject, newTypeTuple, newTypeVar, type TypeAny, type TypeConst, typeAny, typeFunction, typeList } from "./types.js";
+export { length, plural } from "./utils.js";

package/dist/infer.d.ts

@@ -1,7 +1,7 @@
-import { type ASTNode } from "./ast";
-import type { Environment } from "./env";
-import type { ParserExtension } from "./highLevel";
-import { Rational } from "./rational";
-import { type TypeScheme } from "./typeScheme";
+import { type ASTNode } from "./ast.js";
+import type { Environment } from "./env.js";
+import type { ParserExtension } from "./highLevel.js";
+import { Rational } from "./rational.js";
+import { type TypeScheme } from "./typeScheme.js";
 export declare const detectConstantType: (v: boolean | string | Rational, extensions?: ParserExtension<unknown, string>[]) => "boolean" | "string" | "number" | (typeof extensions)[number]["elt"];
 export declare const inferType: (env: Environment) => (node: ASTNode) => Promise<TypeScheme>;

package/dist/json.d.ts

@@ -1,4 +1,4 @@
-import { type ASTNode } from "./ast";
-import type { ParserExtension } from "./highLevel";
+import { type ASTNode } from "./ast.js";
+import type { ParserExtension } from "./highLevel.js";
 export declare function parseNode(node: ASTNode, ext?: ParserExtension<unknown, string>[]): ASTNode;
 export declare function parseAst(json: string, ext: ParserExtension<unknown, string>[]): ASTNode;