openalgo-script 0.1.0-alpha.1 → 0.4.0

package/src/core/emit/expressions.ts

@@ -0,0 +1,292 @@
+/**
+ * An expression, as instructions.
+ *
+ * Every expression is emitted left to right and leaves exactly one value on the
+ * stack. That is not a style: `compiled-program.md` 4.1 has no swap and no
+ * rotate precisely so that there is one way to compile an expression, and two
+ * compilers that agree about the language cannot then disagree about the
+ * program.
+ *
+ * The three places this file makes a decision rather than following a rule are
+ * marked where they are made: where a name's value lives, what a history read
+ * of something that is not a name reads from, and how a named colour reaches a
+ * bar.
+ */
+import type { Binary, Expression, Index, NameReference } from '../ast/index.js';
+import type { Span } from '../span/index.js';
+import { withoutGrouping } from '../ast/index.js';
+import { endOffset } from '../span/index.js';
+import type { Binding } from '../check/index.js';
+import { elementOf } from '../check/index.js';
+import { emitCall, emitLibraryValue } from './calls.js';
+import type { Emitter, Frame } from './context.js';
+import { hexColour } from './colours.js';
+import { placementOf, registerOfName, shadowRegister } from './registers.js';
+
+const ARITHMETIC: Readonly<Record<string, 'ADD' | 'SUB' | 'MUL' | 'DIV' | 'MOD'>> = {
+  '+': 'ADD',
+  '-': 'SUB',
+  '*': 'MUL',
+  '/': 'DIV',
+  '%': 'MOD',
+};
+
+/** A line comment, which is the only thing that can hide an operator token. */
+const COMMENT = /\/\/[^\r\n]*/g;
+
+const COMPARISON: Readonly<Record<string, 'LT' | 'LE' | 'GT' | 'GE' | 'EQ' | 'NE'>> = {
+  '<': 'LT',
+  '<=': 'LE',
+  '>': 'GT',
+  '>=': 'GE',
+  '==': 'EQ',
+  '!=': 'NE',
+};
+
+export function emitExpression(e: Emitter, f: Frame, expression: Expression): void {
+  const node = withoutGrouping(expression);
+  f.builder.at(node.span);
+
+  switch (node.kind) {
+    case 'numberLiteral':
+      f.builder.push('CONST', e.pool.number(node.value));
+      return;
+    case 'stringLiteral':
+      f.builder.push('CONST', e.pool.string(node.value));
+      return;
+    case 'booleanLiteral':
+      f.builder.push('CONST', e.pool.bool(node.value));
+      return;
+    case 'noneLiteral':
+    case 'missingExpression':
+      f.builder.push('CONST', e.pool.absent());
+      return;
+    case 'colorLiteral': {
+      const colour = hexColour(node.text);
+      f.builder.push('CONST', colour === undefined ? e.pool.absent() : e.pool.colour(colour));
+      return;
+    }
+    case 'arrayLiteral':
+      // A new array on every evaluation, which is why it is never pooled (2.9).
+      for (const element of node.elements) emitExpression(e, f, element);
+      f.builder.at(node.span);
+      f.builder.push('ARRAY', node.elements.length);
+      return;
+    case 'nameReference':
+      emitNameRead(e, f, node);
+      return;
+    case 'member':
+      emitLibraryValue(e, f, node);
+      return;
+    case 'unary': {
+      emitExpression(e, f, node.operand);
+      f.builder.at(node.span);
+      // There is no instruction for unary plus: on a number it is the identity
+      // and its type is already checked, so it compiles to nothing at all (4.5).
+      if (node.operator === '-') f.builder.push('NEG');
+      else if (node.operator === 'not') f.builder.push('NOT');
+      return;
+    }
+    case 'binary':
+      emitBinary(e, f, node);
+      return;
+    case 'ternary': {
+      emitExpression(e, f, node.condition);
+      f.builder.at(node.span);
+      const toElse = f.builder.push('JUMP_FALSE', 0);
+      emitExpression(e, f, node.whenTrue);
+      f.builder.at(node.span);
+      const toEnd = f.builder.push('JUMP', 0);
+      f.builder.patch(toElse, 0, f.builder.here);
+      emitExpression(e, f, node.whenFalse);
+      f.builder.patch(toEnd, 0, f.builder.here);
+      return;
+    }
+    case 'call':
+      emitCall(e, f, node);
+      return;
+    case 'index':
+      emitIndex(e, f, node);
+      return;
+  }
+}
+
+/**
+ * Where an operator's instruction is said to be, for `debug.pos`.
+ *
+ * The caret an engine draws for a runtime error comes from this table, and 12.2
+ * puts a `GT` under the `>` and an `ADD` under the `+` rather than under the
+ * start of the expression they are part of. The tree carries no span for the
+ * operator token, so it is found in the gap between the two operands, where the
+ * only thing that can stand between them is a comment or a line continuation.
+ */
+function operatorAt(e: Emitter, node: Binary): Span {
+  const from = endOffset(node.left.span);
+  const to = node.right.span.offset;
+  const gap = e.file.text.slice(from, to);
+  const cleaned = gap.replace(COMMENT, (match) => ' '.repeat(match.length));
+  const found = cleaned.indexOf(node.operator);
+  return found < 0 ? node.span : e.file.spanAt(from + found, node.operator.length);
+}
+
+function emitBinary(e: Emitter, f: Frame, node: Extract<Expression, { kind: 'binary' }>): void {
+  const operator = operatorAt(e, node);
+  if (node.operator === 'and' || node.operator === 'or') {
+    // Each operator short-circuits on the one value that decides the answer by
+    // itself and leaves it on the stack; absence short-circuits neither,
+    // because the other side can still decide (4.7).
+    emitExpression(e, f, node.left);
+    f.builder.at(operator);
+    const short = f.builder.push(node.operator === 'and' ? 'AND_SHORT' : 'OR_SHORT', 0);
+    emitExpression(e, f, node.right);
+    f.builder.at(operator);
+    f.builder.push(node.operator === 'and' ? 'AND' : 'OR');
+    f.builder.patch(short, 0, f.builder.here);
+    return;
+  }
+
+  emitExpression(e, f, node.left);
+  emitExpression(e, f, node.right);
+  f.builder.at(operator);
+  const arithmetic = ARITHMETIC[node.operator];
+  if (arithmetic !== undefined) {
+    f.builder.push(arithmetic);
+    return;
+  }
+  const comparison = COMPARISON[node.operator];
+  if (comparison !== undefined) f.builder.push(comparison);
+}
+
+/** Where a name's value lives, which the checker decided and this reads off. */
+export function emitNameRead(e: Emitter, f: Frame, node: NameReference): void {
+  const binding = e.bindingAt(node);
+  if (binding === undefined) {
+    emitLibraryValue(e, f, node);
+    return;
+  }
+  emitBindingRead(e, f, binding, node.span);
+}
+
+export function emitBindingRead(e: Emitter, f: Frame, binding: Binding, at: Span): void {
+  f.builder.at(at);
+  // Inside a read's expression a setting is a register of the body's own table
+  // (2.16), reachable from the body and from any function it calls. The only
+  // other file-scope name admitted there is OS6003, which the checker reported.
+  const setting = e.request?.registerFor(e, binding);
+  if (setting !== undefined) {
+    f.builder.push('SLOAD', setting);
+    return;
+  }
+  const placement = placementOf(e, binding);
+  if (placement === 'cell') {
+    if (!f.layout.hasCellFor(binding) && !f.topLevel) {
+      // A frame reaches its own cells through its base, so a body cannot name
+      // a cell of the frame that called it (2.11, 3.3). The register beside the
+      // cell is what it reads instead, and `registers.ts` says how it is filled.
+      const carried = e.carried.has(binding.id) ? e.layout.registerFor(binding) : undefined;
+      if (carried !== undefined) {
+        f.builder.push('SLOAD', carried);
+        return;
+      }
+      e.gap(
+        'a function body reads a `var` declared at the file scope, and a cell operand is ' +
+          "relative to the frame's cellBase, so no instruction can reach it",
+        'compiled-program.md 2.11 and 3.3, against language.md 12.2',
+        at,
+        true,
+      );
+      f.builder.push('CONST', e.pool.absent());
+      return;
+    }
+    f.builder.push('LOADC', f.layout.cellFor(binding));
+    return;
+  }
+  if (placement === 'register') {
+    f.builder.push('SLOAD', e.layout.computedFor(binding));
+    return;
+  }
+  f.builder.push('LOAD', f.layout.slotFor(binding));
+}
+
+/**
+ * `target[index]`: an element of an array, or a value some bars back.
+ *
+ * The checker has already decided which of the two this is, from the target's
+ * type, so there is no run-time dispatch and no third meaning (`language.md`
+ * 9.6). What is left is where the history comes from, and only a register has
+ * any (2.10).
+ */
+function emitIndex(e: Emitter, f: Frame, node: Index): void {
+  const type = e.checked.types.get(node.target);
+  if (type !== undefined && elementOf(type).kind === 'array') {
+    emitExpression(e, f, node.target);
+    emitExpression(e, f, node.index);
+    f.builder.at(node.span);
+    f.builder.push('ELEM');
+    return;
+  }
+
+  const target = withoutGrouping(node.target);
+  if (target.kind === 'nameReference') {
+    const binding = e.bindingAt(target);
+    if (binding !== undefined) {
+      const parameter = f.parameters.get(binding.id);
+      if (parameter !== undefined) {
+        emitExpression(e, f, node.index);
+        f.builder.at(node.span);
+        f.builder.push('HISTP', parameter);
+        return;
+      }
+      emitExpression(e, f, node.index);
+      f.builder.at(node.span);
+      f.builder.push('HIST', shadowRegister(e, binding));
+      return;
+    }
+    const register = registerOfName(e, target.name);
+    if (register !== undefined) {
+      emitExpression(e, f, node.index);
+      f.builder.at(node.span);
+      f.builder.push('HIST', register);
+      return;
+    }
+  }
+
+  if (target.kind === 'member') {
+    const register = registerOfName(e, memberText(target));
+    if (register !== undefined) {
+      emitExpression(e, f, node.index);
+      f.builder.at(node.span);
+      f.builder.push('HIST', register);
+      return;
+    }
+  }
+
+  // Anything else with history is a call or a namespace read the language
+  // allows `[]` on (`language.md` 5.2). The format has no register kind for an
+  // expression that is not a name, so one is allocated as a `computed` and the
+  // value is written to it where it is produced. That is the honest reading of
+  // 2.10 and not a spelling it states.
+  e.gap(
+    'a history read of an expression that is not a name needs a register, and 2.10 names ' +
+      'a computed register for a top-level name only',
+    'compiled-program.md 2.10',
+    node.span,
+    false,
+  );
+  const register = e.layout.computed(textOf(e, node.target));
+  emitExpression(e, f, node.target);
+  f.builder.at(node.span);
+  f.builder.push('SSTORE', register);
+  emitExpression(e, f, node.index);
+  f.builder.at(node.span);
+  f.builder.push('HIST', register);
+}
+
+function memberText(node: Extract<Expression, { kind: 'member' }>): string {
+  const object = withoutGrouping(node.object);
+  return object.kind === 'nameReference' ? `${object.name}.${node.member.text}` : node.member.text;
+}
+
+function textOf(e: Emitter, expression: Expression): string {
+  return e.file.text.slice(expression.span.offset, expression.span.offset + expression.span.length);
+}

package/src/core/emit/functions.ts

@@ -0,0 +1,195 @@
+/**
+ * Function bodies, and the call sites that give one body many pieces of state.
+ *
+ * `compiled-program.md` 2.12 allocates state per **call path** rather than per
+ * syntactic call, so a stateful helper called from two places keeps two
+ * independent counters. A body addresses its cells and its state regions
+ * relative to the frame's bases and the call site supplies them, which is what
+ * lets one body serve both.
+ *
+ * There is one place where that arrangement does not close, and it is the
+ * reason this file is not four lines long. A `CALL_FN` names a call site by an
+ * absolute index into `callSites`, so a body holding a call to another function
+ * names one site and not one per path. A body that calls nothing therefore
+ * serves every path and is emitted once; a body that calls something is emitted
+ * once per path, so that its inner `CALL_FN` can name the site belonging to that
+ * path. Both are legal: nothing in the format says two entries of `functions`
+ * may not share a name. The emitter reports the tension rather than leaving a
+ * reader to find it.
+ */
+import { leavesValue } from './calls.js';
+import type { Emitter, Site } from './context.js';
+import { Frame } from './context.js';
+import { emitExpression } from './expressions.js';
+import { cellsOf } from './layout.js';
+import type { Cell, StateRegion } from './program.js';
+import { emitBlock } from './statements.js';
+
+/** The `functions` entry a call site should name, emitting the body if needed. */
+export function bodyFor(e: Emitter, checkedFunction: number, site: Site): number {
+  const shared = e.shareableBody(checkedFunction);
+  if (shared !== undefined) {
+    site.frame = e.functionFrames[shared];
+    return shared;
+  }
+
+  const declared = e.checked.functions[checkedFunction];
+  if (declared === undefined) return 0;
+
+  if (e.emitting.has(checkedFunction)) {
+    // Recursion is an error the checker reports, and the call graph it leaves
+    // is acyclic. A cycle reaching here is a defect, not a program.
+    e.gap(
+      'a function reaches itself, so the set of call paths is not finite and no call site ' +
+        'table can enumerate it',
+      'compiled-program.md 2.12, against language.md 11.4',
+      declared.declaration.span,
+      true,
+    );
+    return 0;
+  }
+
+  e.emitting.add(checkedFunction);
+  try {
+    return emitBody(e, checkedFunction, site);
+  } finally {
+    e.emitting.delete(checkedFunction);
+  }
+}
+
+function emitBody(e: Emitter, checkedFunction: number, site: Site): number {
+  const declared = e.checked.functions[checkedFunction];
+  if (declared === undefined) return 0;
+  const f = new Frame(false);
+
+  // Parameters occupy slots 0 to params - 1, in declaration order (2.12).
+  declared.parameters.forEach((parameter, index) => {
+    f.layout.slotFor(parameter);
+    f.parameters.set(parameter.id, index);
+  });
+
+  const body = declared.declaration.body;
+  if (body.kind === 'block') {
+    // The last statement of a body, when it is a bare expression, is the return
+    // value (`language.md` 11.3). So it is emitted and returned rather than
+    // emitted and discarded, which is what every other expression statement is.
+    const statements = body.statements;
+    const last = statements[statements.length - 1];
+    const returns =
+      last !== undefined && last.kind === 'expressionStatement' && leavesValue(e, last.expression)
+        ? last
+        : undefined;
+
+    emitBlock(e, f, returns === undefined ? body : { ...body, statements: statements.slice(0, -1) });
+    if (returns !== undefined) {
+      emitExpression(e, f, returns.expression);
+      f.builder.at(returns.span);
+      f.builder.push('RET');
+    }
+
+    const emitted = f.builder.code[f.builder.code.length - 1];
+    if (emitted?.[0] !== 'RET') {
+      // A body that ends without an expression returns absent, so every
+      // function returns a value and `RET` never has to decide (4.10).
+      f.builder.at(declared.declaration.span);
+      f.builder.push('CONST', e.pool.absent());
+      f.builder.push('RET');
+    }
+  } else {
+    emitExpression(e, f, body);
+    f.builder.at(declared.declaration.span);
+    f.builder.push('RET');
+  }
+
+  const index = e.functions.length;
+  e.functions.push({
+    name: declared.declaration.name.text,
+    params: declared.parameters.length,
+    slots: f.layout.slotCount,
+    code: f.builder.code,
+  });
+  e.functionFrames.push(f.layout);
+  e.functionPos.push([index, f.builder.pos]);
+
+  site.frame = f.layout;
+  site.children = f.sites;
+
+  if (f.sites.length === 0) {
+    e.rememberShareableBody(checkedFunction, index);
+  } else {
+    e.gap(
+      'a function body holding a call to another function is emitted once per call path, ' +
+        'because a CALL_FN names a call site by an absolute index and a shared body could ' +
+        'only name one',
+      'compiled-program.md 2.12 and 4.10',
+      declared.declaration.span,
+      false,
+    );
+  }
+  return index;
+}
+
+/**
+ * The cell and state base of every call site, once the top level's own totals
+ * are known.
+ *
+ * A body numbers its cells and its state regions from zero and the site adds
+ * the base, so the only requirement is that the blocks do not overlap. Walking
+ * the sites depth first with one counter is the whole of it: a site's own block
+ * is taken, then the blocks of every site its body reaches.
+ */
+export function assignBases(e: Emitter, topCells: number, topStates: number): void {
+  let cell = topCells;
+  let state = topStates;
+  const done = new Set<number>();
+
+  const assign = (index: number): void => {
+    if (done.has(index)) return;
+    done.add(index);
+    const site = e.sites[index];
+    if (site === undefined) return;
+    site.cellBase = cell;
+    site.stateBase = state;
+    cell += site.frame?.cellNames.length ?? 0;
+    state += site.frame?.stateFns.length ?? 0;
+    for (const child of site.children) assign(child);
+  };
+
+  for (let i = 0; i < e.sites.length; i += 1) assign(i);
+}
+
+/**
+ * `cells` and `states`, once one frame and every call path reached from it are
+ * counted.
+ *
+ * A body numbers its own from zero and the call site adds the base, so the two
+ * tables are that frame's own block followed by one block per site, in the
+ * order the bases were handed out. It is the same arithmetic for the top level
+ * of a program and for the body of a read (2.16), which evaluates on its own
+ * bars and so counts its own regions from zero.
+ */
+export function assignRegions(
+  e: Emitter,
+  top: Frame,
+): { readonly cells: readonly Cell[]; readonly states: readonly StateRegion[] } {
+  const topCells = top.layout.cellNames.length;
+  const topStates = top.layout.stateFns.length;
+  assignBases(e, topCells, topStates);
+
+  const cells: Cell[] = cellsOf(top.layout, 0);
+  const states: StateRegion[] = top.layout.stateFns.map((fn, index) => ({ id: index, fn }));
+
+  const ordered = [...e.sites].sort((a, b) => a.cellBase - b.cellBase || a.stateBase - b.stateBase);
+  for (const site of ordered) {
+    const frame = site.frame;
+    if (frame === undefined) continue;
+    cells.push(...cellsOf(frame, site.cellBase));
+    frame.stateFns.forEach((fn, index) => {
+      states.push({ id: site.stateBase + index, fn });
+    });
+  }
+
+  cells.sort((a, b) => a.id - b.id);
+  states.sort((a, b) => a.id - b.id);
+  return { cells, states };
+}

package/src/core/emit/gaps.ts

@@ -0,0 +1,44 @@
+/**
+ * What the emitter could not do, and which specification asked for it.
+ *
+ * Every diagnostic in this compiler carries a catalogue code, and the catalogue
+ * is closed: a stage that meets something it cannot express reports a gap
+ * rather than inventing a code for it. A gap is not a diagnostic. It is a note
+ * from one part of the project to the people who write the other parts, saying
+ * that two specifications, or a specification and the catalogue, do not yet meet.
+ *
+ * It carries a span when one exists, because the fastest way to understand a
+ * gap is to look at the line that provoked it. `blocking` is what separates
+ * "this program is emitted and something about it is unresolved" from "this
+ * program is not emitted at all", and an emitter that returned a program while
+ * a blocking gap stood would be handing somebody an artifact that computes the
+ * wrong numbers.
+ */
+import type { Span } from '../span/index.js';
+
+export interface Gap {
+  /** What could not be done, in one sentence, in the compiler's own voice. */
+  readonly what: string;
+  /** The section that asks for it, so a reader can go and check. */
+  readonly specification: string;
+  readonly span: Span | undefined;
+  /** Whether it stopped a faithful program from being produced. */
+  readonly blocking: boolean;
+}
+
+export class GapLog {
+  private readonly seen = new Set<string>();
+  readonly gaps: Gap[] = [];
+
+  /** Records a gap once per distinct sentence, however many lines provoke it. */
+  add(gap: Gap): void {
+    const key = `${gap.specification}|${gap.what}`;
+    if (this.seen.has(key)) return;
+    this.seen.add(key);
+    this.gaps.push(gap);
+  }
+
+  get blocked(): boolean {
+    return this.gaps.some((one) => one.blocking);
+  }
+}

package/src/core/emit/index.ts

@@ -0,0 +1,76 @@
+/**
+ * The compiled program emitter: the artifact this whole project exists to
+ * produce.
+ *
+ * Everything else in `src/core` serves one compiler. This produces the thing
+ * somebody else's engine reads, in Java, in Go or in Python, from
+ * `spec/compiled-program.md` and nothing else. So the surface here is narrow on
+ * purpose: a function that emits one, the types that describe one, and the
+ * canonical encoding that makes a hash of one mean something.
+ *
+ * `COMPILED_FORMAT_VERSION` is generated from the specification and the release
+ * refuses to publish if the compiler and the specification disagree, which is why
+ * nothing here writes a version literal.
+ */
+export { emit } from './emit.js';
+export type { EmitResult } from './emit.js';
+export type { EmitOptions } from './context.js';
+export { DECLARATION_CALLS, arityOf, effectOf } from './context.js';
+export { declarationDefaultText } from './defaults.js';
+export { namedColour } from './colours.js';
+export { BAR_FACTS, BAR_FIELDS } from './registers.js';
+export { REQUEST_CALLS, REQUEST_STATUS_CALLS } from './requests.js';
+
+export type { Gap } from './gaps.js';
+
+export { canonicalise, canonicalNumber, canonicalString, programHash, sourceHash } from './canonical.js';
+export { sha256, utf8 } from './sha256.js';
+
+export { OPCODES, depthChange, isOpcode, operandCount, targetPositions } from './opcodes.js';
+export type { Opcode } from './opcodes.js';
+
+export { walkDepths } from './code.js';
+export type { Walk } from './code.js';
+
+export type {
+  Alert,
+  Band,
+  CallSite,
+  CandleChannels,
+  Cell,
+  Channel,
+  Colour,
+  CompiledFunction,
+  CompiledInput,
+  CompiledProgram,
+  CompilerStamp,
+  Constant,
+  Debug,
+  DebugNames,
+  Field,
+  FormatVersion,
+  Frame,
+  Grid,
+  InputReference,
+  Instruction,
+  Level,
+  Library,
+  LibraryFunction,
+  Limits,
+  Loop,
+  Marker,
+  Meta,
+  Outputs,
+  Paint,
+  Plot,
+  Position,
+  Register,
+  Request,
+  RequestBody,
+  RequestField,
+  RequestInput,
+  SourceStamp,
+  StateRegion,
+  StrategyMeta,
+  TableOptions,
+} from './program.js';