@venn-lang/core 0.1.0

package/src/expr/prelude.ts

@@ -0,0 +1,75 @@
+import { isClosure } from "./closure.js";
+import { invoke } from "./invoke.js";
+import { isNativeFn, nativeFn } from "./native.types.js";
+import { startTask } from "./task.js";
+
+/**
+ * Render a value the way `print` and `str` do: a string as itself, anything
+ * else as JSON. A value JSON cannot hold falls back to its plain text rather
+ * than throwing, because printing must never be the thing that fails a flow.
+ */
+export function display(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value === null || value === undefined) return String(value);
+  if (typeof value !== "object") return String(value);
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+/**
+ * The name of a value's type, as the language talks about it: "null", "list",
+ * "fn", "map", "bool", "string", "number", or a unit's own kind.
+ */
+export function typeName(value: unknown): string {
+  if (value === null || value === undefined) return "null";
+  if (Array.isArray(value)) return "list";
+  if (isClosure(value) || isNativeFn(value)) return "fn";
+  const kind = (value as { kind?: unknown }).kind;
+  if (typeof value === "object" && typeof kind === "string") return kind;
+  if (typeof value === "object") return "map";
+  return typeof value === "boolean" ? "bool" : typeof value;
+}
+
+/** `range(3)` → [0,1,2]; `range(1, 4)` → [1,2,3]; `range(0, 10, 2)` → [0,2,4,6,8]. */
+function range(args: readonly unknown[]): number[] {
+  const [a, b, c] = args.map(Number);
+  const from = args.length > 1 ? (a ?? 0) : 0;
+  const to = args.length > 1 ? (b ?? 0) : (a ?? 0);
+  const step = c && c !== 0 ? c : from <= to ? 1 : -1;
+  const out: number[] = [];
+  for (let n = from; step > 0 ? n < to : n > to; n += step) out.push(n);
+  return out;
+}
+
+/**
+ * The whole prelude of values: what has no receiver to hang off.
+ *
+ * `len(xs)`, `sum(xs)`, `keys(m)` and `round(x, 2)` are deliberately absent:
+ * they read better as `xs.len`, `xs.sum`, `m.keys` and `x.round(2)`, and a
+ * second spelling would only be a second way to say the same thing. Those names
+ * are also exactly the ones a script wants to bind (`const sum = …`), and a
+ * binding would silently shadow them.
+ */
+export const PRELUDE_VALUES: Readonly<Record<string, unknown>> = {
+  // Builds a list out of nothing: there is no receiver to ask.
+  range: nativeFn(range),
+  // Works on `null`, which can carry no method of its own.
+  str: nativeFn((args) => args.map(display).join(" ")),
+  typeOf: nativeFn((args) => typeName(args[0])),
+  // `fmt.json(x, 2)` without the import: the everyday "show me this".
+  pretty: nativeFn((args) => prettyJson(args[0])),
+  // Start work without stopping for it. Everything else waits by itself, so
+  // this is the only way to say "carry on"; `.wait` asks for it back.
+  spawn: nativeFn((args) => startTask(() => invoke(args[0], []))),
+};
+
+function prettyJson(value: unknown): string {
+  try {
+    return JSON.stringify(value, null, 2) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}

package/src/expr/task.ts

@@ -0,0 +1,71 @@
+import { type Method, nativeFn } from "./native.types.js";
+
+const TASK = Symbol("venn.task");
+
+/**
+ * Work already under way, held rather than waited for.
+ *
+ * Every call in Venn waits by itself, which is what makes `async` and `await`
+ * unnecessary. `spawn` is how to opt out and start something without stopping
+ * for it, the other half of the same feature.
+ *
+ * A task is deliberately not a promise. A promise handed to `let` would be
+ * waited for by the statement, which is exactly what `spawn` exists to avoid,
+ * so the promise is kept inside and `.wait` is how a reader asks for it back.
+ */
+export interface Task {
+  readonly [TASK]: true;
+  readonly promise: Promise<unknown>;
+  settled: boolean;
+  failed: boolean;
+}
+
+/** Whether this value is a running task. */
+export function isTask(value: unknown): value is Task {
+  return typeof value === "object" && value !== null && TASK in value;
+}
+
+/**
+ * Start work and hand back a handle to it.
+ *
+ * The work begins on the next microtask, and the handle observes the promise
+ * straight away, so a task nobody waits for cannot raise an unhandled
+ * rejection.
+ */
+export function startTask(run: () => unknown): Task {
+  const task: Task = {
+    [TASK]: true,
+    promise: Promise.resolve().then(run),
+    settled: false,
+    failed: false,
+  };
+  void task.promise.then(
+    () => {
+      task.settled = true;
+    },
+    () => {
+      task.settled = true;
+      task.failed = true;
+    },
+  );
+  return task;
+}
+
+/**
+ * What a task answers to.
+ *
+ * `.wait` gives back the promise and the statement that binds it does the
+ * waiting, which is the same rule as everywhere else.
+ */
+export const TASK_METHODS: Record<string, Method> = {
+  wait: (task: Task) => task.promise,
+  done: (task: Task) => task.settled,
+  failed: (task: Task) => task.failed,
+  // Failure is the caller's to handle: a task nobody waits for must not take
+  // the process down with an unhandled rejection.
+  settle: (task: Task) => nativeFn(() => task.promise.then(ok, () => undefined)),
+};
+
+function ok(value: unknown): unknown {
+  return value;
+}

package/src/format/format-text.ts

@@ -0,0 +1,22 @@
+import { DEFAULT_FORMAT, type FormatOptions } from "./format.types.js";
+import { organizeHeader } from "./organize-header.js";
+import { reindent } from "./reindent.js";
+
+/**
+ * Format a `.vn` source: group the header, then re-indent. Line-oriented by
+ * design, so it never joins or splits lines. That makes it idempotent, and a
+ * one-line block stays on one line.
+ */
+export function formatText(source: string, options?: Partial<FormatOptions>): string {
+  const settings = { ...DEFAULT_FORMAT, ...options };
+  const eol = source.includes("\r\n") ? "\r\n" : "\n";
+  const lines = source.split(/\r?\n/);
+  const organized = settings.organizeHeader
+    ? organizeHeader(lines, settings.sortHeader)
+    : [...lines];
+  return reindent(organized, unitOf(settings)).join(eol);
+}
+
+function unitOf(options: FormatOptions): string {
+  return options.useTabs ? "\t" : " ".repeat(Math.max(1, options.indentWidth));
+}

package/src/format/format.types.ts

@@ -0,0 +1,18 @@
+/** How to format a `.vn` file. Mirrors the `[format]` table of `venn.toml`. */
+export interface FormatOptions {
+  /** Spaces per indent level. Ignored when {@link useTabs} is on. */
+  indentWidth: number;
+  useTabs: boolean;
+  /** Move every `use` above every `import`. */
+  organizeHeader: boolean;
+  /** Sort each header group alphabetically. */
+  sortHeader: boolean;
+}
+
+/** What the formatter does when `venn.toml` says nothing. */
+export const DEFAULT_FORMAT: FormatOptions = {
+  indentWidth: 2,
+  useTabs: false,
+  organizeHeader: true,
+  sortHeader: false,
+};

package/src/format/from-settings.ts

@@ -0,0 +1,40 @@
+import type { FormatOptions } from "./format.types.js";
+
+/** The shape of the `[format]` table, loose enough for a parsed TOML record. */
+export interface FormatTable {
+  indent?: unknown;
+  tabs?: unknown;
+  organize?: unknown;
+  sort?: unknown;
+}
+
+/**
+ * Map the raw `[format]` table of `venn.toml` onto formatter options. Keys the
+ * project did not set are dropped, so the defaults survive the merge.
+ */
+export function formatOptionsFrom(settings: FormatTable | undefined): Partial<FormatOptions> {
+  const table: FormatTable = settings ?? {};
+  return prune({
+    indentWidth: numberOf(table.indent),
+    useTabs: booleanOf(table.tabs),
+    organizeHeader: booleanOf(table.organize),
+    sortHeader: booleanOf(table.sort),
+  });
+}
+
+function prune(options: Partial<FormatOptions>): Partial<FormatOptions> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(options)) {
+    if (value !== undefined) out[key] = value;
+  }
+  return out as Partial<FormatOptions>;
+}
+
+function numberOf(value: unknown): number | undefined {
+  const parsed = Number(value);
+  return value === undefined || Number.isNaN(parsed) ? undefined : parsed;
+}
+
+function booleanOf(value: unknown): boolean | undefined {
+  return value === undefined ? undefined : value === true || value === "true";
+}

package/src/format/index.ts

@@ -0,0 +1,5 @@
+export { DEFAULT_FORMAT, type FormatOptions } from "./format.types.js";
+export { formatText } from "./format-text.js";
+export { type FormatTable, formatOptionsFrom } from "./from-settings.js";
+export { organizeHeader } from "./organize-header.js";
+export { reindent } from "./reindent.js";

package/src/format/organize-header.ts

@@ -0,0 +1,66 @@
+interface Entry {
+  kind: "use" | "import";
+  comments: string[];
+  line: string;
+}
+
+interface Header {
+  head: string[];
+  entries: Entry[];
+  floating: string[];
+  rest: string[];
+}
+
+/**
+ * Put every `use` above every `import`. A comment sitting directly on top of a
+ * line travels with it; a comment separated by a blank line is left where the
+ * header begins, so nothing is silently re-attached to the wrong statement.
+ */
+export function organizeHeader(lines: readonly string[], sort: boolean): string[] {
+  const header = split(lines);
+  if (header.entries.length === 0) return [...lines];
+  const head = header.head.length > 0 ? [...header.head, ""] : [];
+  const uses = group(header.entries, "use", sort);
+  const imports = group(header.entries, "import", sort);
+  return [...head, ...uses, ...imports, ...header.floating, ...header.rest];
+}
+
+function split(lines: readonly string[]): Header {
+  const header: Header = { head: [], entries: [], floating: [], rest: [] };
+  let pending: string[] = [];
+  let index = 0;
+  for (; index < lines.length; index++) {
+    const line = (lines[index] ?? "").trim();
+    const kind = kindOf(line);
+    if (kind) {
+      header.entries.push({ kind, comments: pending, line });
+      pending = [];
+    } else if (/^module\s/.test(line)) {
+      header.head.push(...pending, line);
+      pending = [];
+    } else if (line.startsWith("#")) pending.push(line);
+    else if (line === "") pending = park(header, pending);
+    else break;
+  }
+  header.rest = [...pending, ...lines.slice(index)];
+  return header;
+}
+
+// A comment block cut off by a blank line belongs to nobody: keep it in place.
+function park(header: Header, pending: string[]): string[] {
+  if (pending.length > 0)
+    (header.entries.length === 0 ? header.head : header.floating).push(...pending);
+  return [];
+}
+
+function group(entries: readonly Entry[], kind: Entry["kind"], sort: boolean): string[] {
+  const picked = entries.filter((entry) => entry.kind === kind);
+  const ordered = sort ? [...picked].sort((a, b) => a.line.localeCompare(b.line)) : picked;
+  if (ordered.length === 0) return [];
+  return [...ordered.flatMap((entry) => [...entry.comments, entry.line]), ""];
+}
+
+function kindOf(line: string): Entry["kind"] | undefined {
+  if (/^use\s/.test(line)) return "use";
+  return /^(pub\s+)?import\s/.test(line) ? "import" : undefined;
+}

package/src/format/reindent.ts

@@ -0,0 +1,35 @@
+const OPEN = /[{[(]/g;
+const CLOSE = /[}\])]/g;
+
+/**
+ * Re-indent by bracket depth. Venn statements are newline terminated, so this
+ * only ever rewrites the leading whitespace of a line. It never joins or splits
+ * lines, which makes it idempotent by construction.
+ *
+ * @param unit The string for one indent level, either spaces or a tab.
+ */
+export function reindent(lines: readonly string[], unit: string): string[] {
+  const out: string[] = [];
+  let depth = 0;
+  for (const line of lines) {
+    const stripped = stripLiterals(line).trim();
+    const level = Math.max(0, depth - leadingClosers(stripped));
+    const trimmed = line.trim();
+    out.push(trimmed === "" ? "" : unit.repeat(level) + trimmed);
+    depth = Math.max(0, depth + count(stripped, OPEN) - count(stripped, CLOSE));
+  }
+  return out;
+}
+
+// Brackets inside strings or comments must not move the depth.
+function stripLiterals(line: string): string {
+  return line.replace(/"(\\.|[^"\\])*"/g, '""').replace(/#.*$/, "");
+}
+
+function leadingClosers(stripped: string): number {
+  return /^[}\])]*/.exec(stripped)?.[0].length ?? 0;
+}
+
+function count(text: string, pattern: RegExp): number {
+  return text.match(pattern)?.length ?? 0;
+}