openalgo-script 0.1.0-alpha.0 → 0.2.0

package/src/core/emit/inputs.ts

@@ -0,0 +1,179 @@
+/**
+ * `inputs[]`, one entry per `input()` call, in source order.
+ *
+ * Each input owns a slot in the top-level frame and the engine writes the
+ * effective value into that slot at the start of every bar
+ * (`compiled-program.md` 2.6 and 5.1 step 5). There is no instruction for an
+ * `input()` anywhere in the program, which is why this runs before a single
+ * statement is emitted: the slots have to exist first, and the two instructions
+ * that keep a register in step with one have to be the first thing the bar does.
+ *
+ * A `"source"` input's default names a series rather than holding one, written
+ * `["s", "<field>"]` in the same form as every other default. The `kind` field
+ * is what says the string names a series, so the constant pool needs no tag of
+ * its own for one.
+ */
+import type { Argument, Call } from '../ast/index.js';
+import { withoutGrouping } from '../ast/index.js';
+import type { CheckedInput } from '../check/index.js';
+import { inputHeldBy } from '../check/index.js';
+import type { Span } from '../span/index.js';
+import type { Emitter, Frame } from './context.js';
+import { argumentAt, inputKey } from './context.js';
+import { INPUT_DEFAULTS } from './defaults.js';
+import type { CompiledInput, Constant } from './program.js';
+import { constantOf } from './pool.js';
+import { placementOf } from './registers.js';
+import { fieldOf } from './values.js';
+import type { Value } from './values.js';
+
+export function buildInputs(e: Emitter, f: Frame): void {
+  const shadows: { readonly slot: number; readonly register: number; readonly span: Span }[] = [];
+
+  // One entry per checked input, in the checker's own order, so an input's `id`
+  // is its index here as well and `emitInputRead` can find the slot it was
+  // given without a second table to keep in step.
+  for (const input of e.checked.inputs) {
+    // The name a `var` gives an input is the input's key and its label, and it
+    // is not the input's slot: `var` declares a cell the bar may write again
+    // (`language.md` 8.2), so the slot the engine fills at step 5 stays the
+    // input's own and the cell is initialised from it like any other value.
+    const binding = e.checked.bindings.find((one) => inputHeldBy(one) === input.id);
+    const slot = binding === undefined ? f.layout.slot(input.name) : f.layout.slotFor(binding);
+    e.inputs.push(entryFor(e, input, slot));
+
+    if (binding === undefined) continue;
+    const register = e.layout.registerFor(binding);
+    if (register === undefined) continue;
+    if (placementOf(e, binding) === 'slot' && !e.shadowed.has(binding.id)) continue;
+    shadows.push({ slot, register, span: input.span });
+  }
+
+  // An input read through `[]`, or read from inside a `fn`, needs a register as
+  // well as its slot; the engine fills the slot and this fills the register
+  // from it, once, before anything reads either.
+  for (const shadow of shadows) {
+    f.builder.at(shadow.span);
+    f.builder.push('LOAD', shadow.slot);
+    f.builder.push('SSTORE', shadow.register);
+  }
+}
+
+/**
+ * An `input()` written where a value belongs, which is a read of its slot.
+ *
+ * Reaching here means the call stands in an expression rather than being the
+ * whole of a statement, and `outputs.ts` is where that split is decided and
+ * argued. The declaration itself still emits nothing: the row and the slot are
+ * made above, before a statement is emitted, and the engine writes the slot at
+ * step 5 of every bar. All this adds is the one instruction that puts what the
+ * engine wrote on the stack.
+ *
+ * **A slot belongs to one frame** (3.2), and an input's slot belongs to the top
+ * level's. So a read from inside a function body has no instruction that reaches
+ * it. `language.md` 13.4 puts an `input()` at the top level of a file in the
+ * first place, and where the checker has not already refused one this says the
+ * compiler cannot carry it rather than loading a slot of another frame that
+ * happens to have the same number.
+ *
+ * **A read's expression is the case that is not that one.** It is compiled as a
+ * program of its own over other bars, so it cannot reach the slot either, and
+ * it does not need to: 2.16's `inputs` on the request exists exactly so a
+ * setting can cross into a body, the engine resolves the key in the enclosing
+ * program before the body runs and fills a register of the body's own table
+ * with it, and `stdlib.md` 15.4 has always let the expression name a setting.
+ * That the setting is written in place rather than behind a name changes
+ * nothing about any of it, so the call resolves through the same scope the
+ * name does and loads the same register.
+ */
+export function emitInputRead(e: Emitter, f: Frame, call: Call): void {
+  const input = e.inputAt(call);
+  if (e.request !== undefined && input !== undefined) {
+    f.builder.at(call.span);
+    f.builder.push('SLOAD', e.request.registerForInput(e, input));
+    return;
+  }
+
+  const slot = input === undefined ? undefined : e.inputs[input.id]?.slot;
+  f.builder.at(call.span);
+  if (slot === undefined || !f.topLevel) {
+    e.gap(
+      "an input() read from anywhere but the file's top level cannot be carried: an input's " +
+        'slot belongs to the top-level frame and no instruction reaches it from another one',
+      'compiled-program.md 2.6 and 3.2, against language.md 13.4',
+      call.span,
+      true,
+    );
+    // Absent rather than nothing, so the one refusal above is what a reader
+    // sees instead of a second one about a stack that does not add up.
+    f.builder.push('CONST', e.pool.absent());
+    return;
+  }
+  f.builder.push('LOAD', slot);
+}
+
+function entryFor(e: Emitter, input: CheckedInput, slot: number): CompiledInput {
+  const checked = e.callAt(input.call);
+  const entry = checked?.entry;
+  const argument = (name: string): Argument | undefined =>
+    checked === undefined || entry === undefined ? undefined : argumentAt(checked, entry, name);
+
+  const numberOption = (name: string): number | null => {
+    const written = argument(name);
+    if (written === undefined) return null;
+    const value = e.fold(written.value);
+    return value !== undefined && value.kind === 'number' ? value.value : null;
+  };
+
+  const stringOption = (name: string, fallback: string | null): string | null => {
+    const written = argument(name);
+    if (written === undefined) return fallback;
+    const value = e.fold(written.value);
+    return value !== undefined && value.kind === 'string' ? value.value : fallback;
+  };
+
+  return {
+    key: inputKey(input),
+    kind: input.kind,
+    label: input.title,
+    default: defaultOf(e, input, argument('value')),
+    min: numberOption('min'),
+    max: numberOption('max'),
+    step: numberOption('step'),
+    options: optionsOf(e, argument('options')),
+    group: stringOption('group', stringValue(INPUT_DEFAULTS['group'])) ?? '',
+    // The worked example of section 12.2 writes null for an input that named no
+    // tooltip, which is the one place the effective value is an absence.
+    tooltip: stringOption('tooltip', null),
+    slot,
+  };
+}
+
+function defaultOf(e: Emitter, input: CheckedInput, written: Argument | undefined): Constant {
+  if (written === undefined) return ['z', null];
+  if (input.kind === 'source') {
+    const inner = withoutGrouping(written.value);
+    return ['s', inner.kind === 'nameReference' ? inner.name : ''];
+  }
+  const value = e.fold(written.value);
+  if (value === undefined) return ['z', null];
+  return constantOf(value) ?? ['z', null];
+}
+
+function optionsOf(e: Emitter, written: Argument | undefined): readonly Constant[] | null {
+  if (written === undefined) return null;
+  const value = e.fold(written.value);
+  if (value === undefined || value.kind !== 'array') return null;
+  const entries: Constant[] = [];
+  for (const one of value.values) {
+    const constant = constantOf(one);
+    if (constant === undefined) return null;
+    entries.push(constant);
+  }
+  return entries;
+}
+
+function stringValue(value: Value | undefined): string {
+  const field = fieldOf(value);
+  return typeof field === 'string' ? field : '';
+}

package/src/core/emit/layout.ts

@@ -0,0 +1,165 @@
+/**
+ * Where every value the program holds is put: slots, cells, registers,
+ * channels and state regions.
+ *
+ * `compiled-program.md` 2.10 and 2.11 describe three regions with three
+ * lifetimes, and the checker has already decided which one each name belongs
+ * to. What is left is the arithmetic: an index per name, per frame, in a table
+ * an engine reads by position. That is all this file does, and keeping it out
+ * of the passes that emit code is what stops an index being allocated twice in
+ * one place and read as a different number in another.
+ *
+ * The one decision here rather than in the checker is the frame. Slots and cell
+ * operands are relative to the frame that holds them, so a function body
+ * numbers its own from zero and the call site supplies the base (2.12). A
+ * single global counter would produce a program that runs correctly from one
+ * call site and wrongly from the second.
+ */
+import type { Binding } from '../check/index.js';
+import type { Cell, Channel, Register } from './program.js';
+
+/** One frame's slots, its cells and the library state its body needs. */
+export class FrameLayout {
+  readonly slotNames: string[] = [];
+  readonly cellNames: (string | null)[] = [];
+  readonly cellKinds: ('var' | 'live')[] = [];
+  /** Relative state index to the index into `lib.functions` that owns it. */
+  readonly stateFns: number[] = [];
+
+  private readonly bindingSlot = new Map<number, number>();
+  private readonly bindingCell = new Map<number, number>();
+
+  /** A slot with no name in the source: a loop's limit, a step, a cursor. */
+  slot(name: string): number {
+    const index = this.slotNames.length;
+    this.slotNames.push(name);
+    return index;
+  }
+
+  slotFor(binding: Binding): number {
+    const found = this.bindingSlot.get(binding.id);
+    if (found !== undefined) return found;
+    const index = this.slot(binding.name);
+    this.bindingSlot.set(binding.id, index);
+    return index;
+  }
+
+  hasSlotFor(binding: Binding): boolean {
+    return this.bindingSlot.has(binding.id);
+  }
+
+  cellFor(binding: Binding): number {
+    const found = this.bindingCell.get(binding.id);
+    if (found !== undefined) return found;
+    const index = this.cellNames.length;
+    this.cellNames.push(binding.name);
+    this.cellKinds.push(binding.persistence === 'live' ? 'live' : 'var');
+    this.bindingCell.set(binding.id, index);
+    return index;
+  }
+
+  hasCellFor(binding: Binding): boolean {
+    return this.bindingCell.has(binding.id);
+  }
+
+  /** A per-call-site region for a stateful library call, relative to the base. */
+  state(libraryFunction: number): number {
+    const index = this.stateFns.length;
+    this.stateFns.push(libraryFunction);
+    return index;
+  }
+
+  get slotCount(): number {
+    return this.slotNames.length;
+  }
+}
+
+/**
+ * The tables that are one per program rather than one per frame.
+ *
+ * A register, a channel and a library function entry are addressed the same way
+ * from every frame, which is what lets a function body read a series and write
+ * a plot column without knowing where it was called from.
+ */
+export class Layout {
+  readonly registers: Register[] = [];
+  readonly channels: Channel[] = [];
+  readonly channelNames: string[] = [];
+
+  private readonly barFields = new Map<string, number>();
+  private readonly bindingRegister = new Map<number, number>();
+
+  /** The register the engine fills from the host's bar, 2.10. One per field. */
+  bar(field: string): number {
+    const found = this.barFields.get(field);
+    if (found !== undefined) return found;
+    const id = this.registers.length;
+    this.registers.push({ id, kind: 'bar', field, name: field });
+    this.barFields.set(field, id);
+    return id;
+  }
+
+  /** A top-level name whose history the program reads, written by `SSTORE`. */
+  computedFor(binding: Binding): number {
+    const found = this.bindingRegister.get(binding.id);
+    if (found !== undefined) return found;
+    const id = this.computed(binding.name);
+    this.bindingRegister.set(binding.id, id);
+    return id;
+  }
+
+  hasComputedFor(binding: Binding): boolean {
+    return this.bindingRegister.has(binding.id);
+  }
+
+  registerFor(binding: Binding): number | undefined {
+    return this.bindingRegister.get(binding.id);
+  }
+
+  computed(name: string): number {
+    const id = this.registers.length;
+    this.registers.push({ id, kind: 'computed', field: null, name });
+    return id;
+  }
+
+  /** A series argument retained for one call site, 2.10 and 4.10. */
+  argument(name: string): number {
+    const id = this.registers.length;
+    this.registers.push({ id, kind: 'argument', field: null, name });
+    return id;
+  }
+
+  /**
+   * A register the engine fills rather than the program, 2.10 and 2.16.
+   *
+   * A read's value per chart bar, and a setting a read's expression needs on
+   * every requested bar. Neither is ever written by an instruction, which is
+   * why neither is a `computed`.
+   */
+  filled(kind: 'request' | 'input', name: string): number {
+    const id = this.registers.length;
+    this.registers.push({ id, kind, field: null, name });
+    return id;
+  }
+
+  channel(
+    type: Channel['type'],
+    defer: boolean,
+    once: boolean,
+    name: string,
+  ): number {
+    const id = this.channels.length;
+    this.channels.push({ id, type, defer, once });
+    this.channelNames.push(name);
+    return id;
+  }
+}
+
+/** The cells of one frame, as the program's `cells[]` carries them. */
+export function cellsOf(frame: FrameLayout, base: number): Cell[] {
+  return frame.cellKinds.map((kind, index) => ({
+    id: base + index,
+    kind,
+    name: frame.cellNames[index] ?? null,
+  }));
+}

package/src/core/emit/meta.ts

@@ -0,0 +1,104 @@
+/**
+ * `meta` and `limits`: the declaration statement and the budget line, as the
+ * two objects an engine reads once.
+ *
+ * Every field is written with its effective value, defaults included, which is
+ * `compiled-program.md` 2.3's firmest rule. An engine therefore never needs a
+ * table of defaults, and a default that changes in a later language version
+ * cannot silently change an old program, because the old program carries the
+ * old value in writing.
+ */
+import type { Argument, Expression } from '../ast/index.js';
+import type { Emitter } from './context.js';
+import {
+  LOOP_BUDGET,
+  STRATEGY_DEFAULTS,
+  STRATEGY_OPTIONS,
+  STUDY_DEFAULTS,
+} from './defaults.js';
+import type { Field, Limits, Meta, StrategyMeta } from './program.js';
+import { fieldOf } from './values.js';
+import type { Value } from './values.js';
+
+function optionField(
+  e: Emitter,
+  options: ReadonlyMap<string, Expression>,
+  name: string,
+  defaults: Readonly<Record<string, Value>>,
+): Field {
+  const written = options.get(name);
+  if (written === undefined) return fieldOf(defaults[name]);
+  const value = e.fold(written);
+  if (value !== undefined) return fieldOf(value);
+  e.gap(
+    'a declaration option written as an expression over an input cannot be carried: a field ' +
+      'holds a value or a reference to one input, and this is neither',
+    'compiled-program.md 2.3, against language.md 13.2',
+    written.span,
+    true,
+  );
+  return null;
+}
+
+export function buildMeta(e: Emitter): Meta {
+  const declaration = e.checked.declaration;
+  const options = declaration?.options ?? new Map<string, Expression>();
+  const title = optionField(e, options, 'title', {});
+
+  const base = {
+    kind: declaration?.form ?? 'study',
+    title,
+    // `short` falls back to `title`, which is the one default that is another
+    // option's value rather than a constant (language.md 13.2).
+    short: options.has('short') ? optionField(e, options, 'short', {}) : title,
+    overlay: optionField(e, options, 'overlay', STUDY_DEFAULTS),
+    precision: optionField(e, options, 'precision', STUDY_DEFAULTS),
+    format: optionField(e, options, 'format', STUDY_DEFAULTS),
+    range: optionField(e, options, 'range', STUDY_DEFAULTS),
+    scale: optionField(e, options, 'scale', STUDY_DEFAULTS),
+    group: optionField(e, options, 'group', STUDY_DEFAULTS),
+    onUnconfirmed: optionField(e, options, 'onUnconfirmed', STUDY_DEFAULTS),
+  } as const;
+
+  if (base.kind !== 'strategy') return base;
+
+  const strategy: Record<string, Field> = {};
+  for (const option of STRATEGY_OPTIONS) {
+    strategy[option] = optionField(e, options, option, STRATEGY_DEFAULTS);
+  }
+  return { ...base, strategy: strategy as unknown as StrategyMeta };
+}
+
+/**
+ * `limits()`, whose values are literal numbers rather than compile-time
+ * constants.
+ *
+ * The host is asked whether it will run them before the program is loaded, and
+ * an `input()` is not resolved that early (`language.md` 10.7). A host that
+ * will not spend what a program asks for refuses at load with OS5003 and must
+ * not silently cap it.
+ */
+export function buildLimits(e: Emitter): Limits {
+  const line = e.checked.script.items.find((item) => item.kind === 'limitsLine');
+  if (line === undefined || line.kind !== 'limitsLine') {
+    return { loops: LOOP_BUDGET, history: null };
+  }
+  return {
+    loops: literalOption(e, line.args, 'loops', 0) ?? LOOP_BUDGET,
+    history: literalOption(e, line.args, 'history', 1) ?? null,
+  };
+}
+
+function literalOption(
+  e: Emitter,
+  args: readonly Argument[],
+  name: string,
+  position: number,
+): number | undefined {
+  const labelled = args.find((one) => one.label?.text === name);
+  const positional = args.filter((one) => one.label === undefined)[position];
+  const chosen = labelled ?? positional;
+  if (chosen === undefined) return undefined;
+  const value = e.fold(chosen.value);
+  return value !== undefined && value.kind === 'number' ? value.value : undefined;
+}

package/src/core/emit/opcodes.ts

@@ -0,0 +1,160 @@
+/**
+ * The forty-one instructions of `compiled-program.md` section 4, and the two
+ * facts an emitter has to get right about each one.
+ *
+ * The operand count is here so that a mistyped instruction is caught where it
+ * is built rather than by an engine's verifier three systems away. The depth
+ * change is here because section 3.5 check 5 requires the stack depth to be
+ * computable by walking the list, to agree at every join and to be zero at
+ * `HALT`; a compiler that cannot compute it cannot know it emitted a program
+ * any engine will load, and this is the table that makes it computable.
+ *
+ * `ARRAY`, `CALL_LIB` and `CALL_FN` have a depth that depends on an operand, so
+ * their entries carry the rule rather than a number.
+ */
+
+export const OPCODES = [
+  'CONST',
+  'DUP',
+  'POP',
+  'LOAD',
+  'STORE',
+  'CELL_INIT',
+  'LOADC',
+  'STOREC',
+  'SLOAD',
+  'SSTORE',
+  'HIST',
+  'HISTP',
+  'ADD',
+  'SUB',
+  'MUL',
+  'DIV',
+  'MOD',
+  'NEG',
+  'LT',
+  'LE',
+  'GT',
+  'GE',
+  'EQ',
+  'NE',
+  'NOT',
+  'AND',
+  'OR',
+  'AND_SHORT',
+  'OR_SHORT',
+  'JUMP',
+  'JUMP_FALSE',
+  'TICK',
+  'FOR_INIT',
+  'FOR_NEXT',
+  'ARRAY',
+  'ELEM',
+  'CALL_LIB',
+  'CALL_FN',
+  'RET',
+  'EMIT',
+  'HALT',
+] as const;
+
+export type Opcode = (typeof OPCODES)[number];
+
+interface Shape {
+  /** How many operands the instruction takes, section 4's tables. */
+  readonly operands: number;
+  /**
+   * The change in stack depth, or the operand position it is computed from.
+   *
+   * `ARRAY n` is `1 - n` and `CALL_LIB f n st` is `1 - n`, so both read their
+   * count from an operand. `CALL_FN` reads it from the call site, which is not
+   * an operand of the instruction, so it is the one entry the walker has to be
+   * told about.
+   */
+  readonly depth: number | 'arrayCount' | 'callCount' | 'callSite';
+}
+
+const SHAPES: Readonly<Record<Opcode, Shape>> = {
+  CONST: { operands: 1, depth: 1 },
+  DUP: { operands: 0, depth: 1 },
+  POP: { operands: 0, depth: -1 },
+  LOAD: { operands: 1, depth: 1 },
+  STORE: { operands: 1, depth: -1 },
+  CELL_INIT: { operands: 2, depth: 0 },
+  LOADC: { operands: 1, depth: 1 },
+  STOREC: { operands: 1, depth: -1 },
+  SLOAD: { operands: 1, depth: 1 },
+  SSTORE: { operands: 1, depth: -1 },
+  HIST: { operands: 1, depth: 0 },
+  HISTP: { operands: 1, depth: 0 },
+  ADD: { operands: 0, depth: -1 },
+  SUB: { operands: 0, depth: -1 },
+  MUL: { operands: 0, depth: -1 },
+  DIV: { operands: 0, depth: -1 },
+  MOD: { operands: 0, depth: -1 },
+  NEG: { operands: 0, depth: 0 },
+  LT: { operands: 0, depth: -1 },
+  LE: { operands: 0, depth: -1 },
+  GT: { operands: 0, depth: -1 },
+  GE: { operands: 0, depth: -1 },
+  EQ: { operands: 0, depth: -1 },
+  NE: { operands: 0, depth: -1 },
+  NOT: { operands: 0, depth: 0 },
+  AND: { operands: 0, depth: -1 },
+  OR: { operands: 0, depth: -1 },
+  AND_SHORT: { operands: 1, depth: 0 },
+  OR_SHORT: { operands: 1, depth: 0 },
+  JUMP: { operands: 1, depth: 0 },
+  JUMP_FALSE: { operands: 1, depth: -1 },
+  TICK: { operands: 1, depth: 0 },
+  FOR_INIT: { operands: 5, depth: -3 },
+  FOR_NEXT: { operands: 5, depth: 0 },
+  ARRAY: { operands: 1, depth: 'arrayCount' },
+  ELEM: { operands: 0, depth: -1 },
+  CALL_LIB: { operands: 3, depth: 'callCount' },
+  CALL_FN: { operands: 1, depth: 'callSite' },
+  RET: { operands: 0, depth: -1 },
+  EMIT: { operands: 1, depth: -1 },
+  HALT: { operands: 0, depth: 0 },
+};
+
+export function operandCount(opcode: Opcode): number {
+  return SHAPES[opcode].operands;
+}
+
+/**
+ * The stack depth change of one instruction.
+ *
+ * `argcOf` answers for a `CALL_FN`, because its count lives in the call site
+ * table rather than in the instruction, and the walker is the only caller that
+ * has that table in hand.
+ */
+export function depthChange(
+  opcode: Opcode,
+  operands: readonly number[],
+  argcOf: (site: number) => number,
+): number {
+  const shape = SHAPES[opcode];
+  if (shape.depth === 'arrayCount') return 1 - (operands[0] ?? 0);
+  if (shape.depth === 'callCount') return 1 - (operands[1] ?? 0);
+  if (shape.depth === 'callSite') return 1 - argcOf(operands[0] ?? 0);
+  return shape.depth;
+}
+
+/** The operand positions that hold a jump target, for the verifier's check 3. */
+const TARGETS: Partial<Record<Opcode, readonly number[]>> = {
+  CELL_INIT: [1],
+  AND_SHORT: [0],
+  OR_SHORT: [0],
+  JUMP: [0],
+  JUMP_FALSE: [0],
+  FOR_INIT: [4],
+  FOR_NEXT: [4],
+};
+
+export function targetPositions(opcode: Opcode): readonly number[] {
+  return TARGETS[opcode] ?? [];
+}
+
+export function isOpcode(name: string): name is Opcode {
+  return (OPCODES as readonly string[]).includes(name);
+}