openalgo-script 0.1.0-alpha.0 → 0.2.0

package/src/core/emit/defaults.ts

@@ -0,0 +1,150 @@
+/**
+ * The effective value of every declaration option a script left out.
+ *
+ * `compiled-program.md` 2.3 is unusually firm about this: every field of
+ * `meta`, of `meta.strategy` and of every declaration in `outputs` is written
+ * with the value that option resolved to, defaults included, rather than
+ * omitted or written as null. So an engine 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.
+ *
+ * That is also why this file exists and why it is only this. These are the
+ * defaults of `language.md` 13.2 and 13.3 and of `stdlib.md` 14.2, 14.3, 16 and
+ * 10.7, transcribed once. Nothing here is a runtime argument default: those
+ * belong to the library manifest, and `calls.ts` says what happens where the
+ * two are confused.
+ */
+import type { Value } from './values.js';
+import { namedColour } from './colours.js';
+
+const ABSENT: Value = { kind: 'absent' };
+
+function number(value: number): Value {
+  return { kind: 'number', value };
+}
+
+function string(value: string): Value {
+  return { kind: 'string', value };
+}
+
+function bool(value: boolean): Value {
+  return { kind: 'bool', value };
+}
+
+function colour(name: string): Value {
+  const value = namedColour(name);
+  return value === undefined ? ABSENT : { kind: 'colour', value };
+}
+
+/** `language.md` 13.2. `title` is required and `short` falls back to it. */
+export const STUDY_DEFAULTS: Readonly<Record<string, Value>> = {
+  overlay: bool(false),
+  precision: number(4),
+  format: string('price'),
+  range: ABSENT,
+  scale: string('right'),
+  group: string(''),
+  onUnconfirmed: bool(false),
+};
+
+/** `language.md` 13.3, the options only a `strategy()` adds. */
+export const STRATEGY_DEFAULTS: Readonly<Record<string, Value>> = {
+  capital: number(100000),
+  currency: string(''),
+  qty: number(1),
+  qtyType: string('units'),
+  product: string('intraday'),
+  fillOn: string('nextOpen'),
+  slippage: number(0),
+  commission: number(0),
+  commissionType: string('perTrade'),
+  pyramiding: number(1),
+  closeOnSessionEnd: bool(false),
+};
+
+/** The order `meta.strategy` lists them in, 2.3. */
+export const STRATEGY_OPTIONS: readonly string[] = [
+  'capital',
+  'currency',
+  'qty',
+  'qtyType',
+  'product',
+  'fillOn',
+  'slippage',
+  'commission',
+  'commissionType',
+  'pyramiding',
+  'closeOnSessionEnd',
+];
+
+/**
+ * `stdlib.md` 14.2.
+ *
+ * `lineStyle` has no argument on `plot` at all: the call's `style` names the
+ * column's shape and becomes the entry's `type`. A plot therefore always
+ * carries the one line style a host draws an undecorated line with.
+ */
+export const PLOT_DEFAULTS: Readonly<Record<string, Value>> = {
+  color: ABSENT,
+  width: number(1.5),
+  style: string('line'),
+  offset: number(0),
+  overlay: ABSENT,
+  precision: ABSENT,
+  format: ABSENT,
+  scale: string('right'),
+};
+
+export const PLOT_LINE_STYLE: Value = string('solid');
+
+/** `stdlib.md` 14.2. A candle's border takes a plot's own width and style. */
+export const CANDLE_DEFAULTS: Readonly<Record<string, Value>> = {
+  colorUp: colour('lime'),
+  colorDown: colour('red'),
+  wickColor: ABSENT,
+  borderColor: ABSENT,
+};
+
+export const FILL_DEFAULTS: Readonly<Record<string, Value>> = {
+  color: ABSENT,
+  colorUp: ABSENT,
+  colorDown: ABSENT,
+  opacity: number(1),
+  overlay: ABSENT,
+};
+
+export const LEVEL_DEFAULTS: Readonly<Record<string, Value>> = {
+  title: string(''),
+  color: colour('gray'),
+  style: string('dashed'),
+  width: number(1),
+};
+
+/** `stdlib.md` 14.3. `title`, `rows` and `cols` have no default. */
+export const TABLE_DEFAULTS: Readonly<Record<string, Value>> = {
+  position: string('topRight'),
+  textColor: ABSENT,
+  bgColor: ABSENT,
+  borderWidth: number(0),
+};
+
+export const MARKER_DEFAULTS: Readonly<Record<string, Value>> = {
+  color: ABSENT,
+  at: string('above'),
+  shape: string('label'),
+};
+
+export const ALERT_DEFAULTS: Readonly<Record<string, Value>> = {
+  id: string(''),
+  title: string(''),
+  frequency: string('oncePerBar'),
+};
+
+/** `stdlib.md` 13.2, the arguments every input kind accepts. */
+export const INPUT_DEFAULTS: Readonly<Record<string, Value>> = {
+  group: string(''),
+  tooltip: string(''),
+};
+
+/** `language.md` 10.7 and 7.4, carried by `limits` whether or not it was written. */
+export const LOOP_BUDGET = 2_000_000;

package/src/core/emit/emit.ts

@@ -0,0 +1,313 @@
+/**
+ * A checked file in, a compiled program out.
+ *
+ * The order below is the order the format forces, and each step is here rather
+ * than inside a pass because each one needs a total the passes do not have
+ * until they have finished.
+ *
+ * Registers first, because the two instructions that keep a shadow register in
+ * step with a cell have to be the first and the last thing a bar does, and a
+ * prologue cannot be written after the list it belongs at the front of. Inputs
+ * next, because each one owns a slot the engine writes at step 5 and the slots
+ * have to exist before a statement reads one. Then the statements. Then the
+ * bases of every call site, which can only be assigned once the top level's own
+ * cells and state regions are counted.
+ *
+ * The last step is the one worth defending: the emitter walks its own
+ * instruction lists and computes the stack depth exactly as section 3.5 check 5
+ * says an engine will. A compiler that cannot compute that number does not know
+ * whether it emitted a program any engine will load, and finding out from a
+ * verifier in another language is finding out too late.
+ */
+import { CATALOGUE_LANGUAGE_VERSION } from '../catalogue/index.js';
+import type { CheckedScript } from '../check/index.js';
+import type { DiagnosticSink } from '../diagnostics/index.js';
+import type { SourceFile } from '../source/index.js';
+import type { Span } from '../span/index.js';
+import { COMPILED_FORMAT_VERSION, VERSION } from '../version/index.js';
+import { sourceHash } from './canonical.js';
+import { orderChannels, renumberCode, renumberOutputs } from './channels.js';
+import { walkDepths } from './code.js';
+import { Emitter, Frame } from './context.js';
+import type { EmitOptions } from './context.js';
+import type { Gap } from './gaps.js';
+import { assignRegions } from './functions.js';
+import { buildInputs } from './inputs.js';
+
+import { buildLimits, buildMeta } from './meta.js';
+import type { CompiledProgram, Instruction, Request } from './program.js';
+import { placementOf, prepareRegisters } from './registers.js';
+import { linkRequestNames } from './requests.js';
+import { requiresOf } from './requires.js';
+import { emitStatement } from './statements.js';
+
+export interface EmitResult {
+  /** The program, or nothing when a gap stopped a faithful one being produced. */
+  readonly program: CompiledProgram | undefined;
+  readonly gaps: readonly Gap[];
+}
+
+/** The library manifest version, tied to `openscript.language` (2.5). */
+const DEFAULT_MANIFEST = 1;
+
+export function emit(
+  file: SourceFile,
+  checked: CheckedScript,
+  sink: DiagnosticSink,
+  options: EmitOptions = {},
+): EmitResult {
+  const e = new Emitter(file, checked, sink, options);
+  const top = new Frame(true);
+
+  prepareRegisters(e);
+  buildInputs(e, top);
+  openCarriedRegisters(e, top);
+  linkRequestNames(e);
+
+  for (const item of checked.script.items) {
+    if (item.kind === 'functionDeclaration') continue;
+    emitStatement(e, top, item);
+  }
+
+  closeShadowRegisters(e, top);
+  // `HALT` takes the position of whatever came before it, which is 12.2's own
+  // reading of a run of instructions costing one triple.
+  if (top.builder.here === 0) top.builder.at(checked.script.span);
+  top.builder.push('HALT');
+
+  const { cells, states } = assignRegions(e, top);
+  // The channel table is written in the order `outputs` lists its groups, which
+  // is not the order the declarations were met in; `channels.ts` says why.
+  const order = orderChannels(e);
+  const code = renumberCode(top.builder.code, order.moved);
+  const functions = e.functions.map((one) => ({
+    ...one,
+    code: renumberCode(one.code, order.moved),
+  }));
+  checkDepths(e, top, code);
+  checkLimits(e, code, states.length);
+
+  const program: CompiledProgram = {
+    openscript: { format: COMPILED_FORMAT_VERSION, language: languageOf(checked) },
+    requires: requiresOf(e, code),
+    compiler: { name: 'openscript', version: VERSION },
+    source: { hash: sourceHash(file.text), lines: file.lineCount, file: file.name },
+    meta: buildMeta(e),
+    limits: buildLimits(e),
+    lib: { manifest: options.manifest ?? DEFAULT_MANIFEST, functions: e.libraryFunctions },
+    inputs: e.inputs,
+    channels: order.channels,
+    outputs: renumberOutputs(e, order.moved),
+    consts: e.pool.all,
+    series: e.layout.registers,
+    frame: { slots: top.layout.slotCount },
+    cells,
+    states,
+    functions,
+    callSites: e.sites.map((site) => ({
+      fn: site.fn,
+      argc: site.argc,
+      cellBase: site.cellBase,
+      stateBase: site.stateBase,
+      series: site.series,
+    })),
+    loops: e.loops,
+    code,
+    requests: e.requests,
+    debug: {
+      pos: top.builder.pos,
+      fnPos: e.functionPos,
+      names: {
+        slots: top.layout.slotNames,
+        cells: cells.map((one) => one.name ?? ''),
+        series: e.layout.registers.map((one) => one.name ?? ''),
+        channels: order.names,
+      },
+      retain: options.retain === true,
+    },
+  };
+
+  if (!e.gaps.blocked) return { program, gaps: e.gaps.gaps };
+  reportRefusal(e);
+  return { program: undefined, gaps: e.gaps.gaps };
+}
+
+/**
+ * Why there is no program, said to the person who asked for one.
+ *
+ * A gap is a note between the parts of this project and nobody outside it ever
+ * reads one, so an emitter that returned nothing and logged a gap left a trader
+ * with a compile that produced no program, no message and nothing to ask a
+ * question about. That is the worst failure this compiler has available: the
+ * script may be perfectly good, and silence gives its author no way to find out
+ * whether it is.
+ *
+ * So every gap that stopped a program becomes a diagnostic. It carries the line
+ * that provoked it, what could not be done, and the section that asks for it,
+ * and it says where to take it. The sentence is careful about whose fault it
+ * is, because this runs whether or not an earlier stage refused the file: a
+ * checked tree the emitter cannot emit is a defect in the compiler only when
+ * nothing else was reported about it.
+ */
+function reportRefusal(e: Emitter): void {
+  for (const gap of e.gaps.gaps) {
+    if (!gap.blocking) continue;
+    e.sink.report('OS6018', gap.span ?? e.checked.script.span, {
+      location: gap.specification,
+      reason:
+        `${gap.what}; this compiler produced no program rather than a wrong one, and if ` +
+        'nothing else was reported about this script that is a defect in the compiler ' +
+        'rather than in the script: please report it, with the script that produced it',
+    });
+  }
+}
+
+function languageOf(checked: CheckedScript): number {
+  const line = checked.script.items.find((item) => item.kind === 'versionLine');
+  return line !== undefined && line.kind === 'versionLine'
+    ? line.version.value
+    : CATALOGUE_LANGUAGE_VERSION;
+}
+
+/**
+ * The register beside a `var` a function body reads, filled before the bar runs.
+ *
+ * The pair at the end of the bar (below) writes the entry for the bar. This one
+ * writes the value the bar starts with, so a body called before the first
+ * assignment reads what the cell carried in rather than an absence. On bar 0
+ * the cell has not been initialised yet and reads absent, which is what the
+ * name is worth before its declaration line (3.4).
+ */
+function openCarriedRegisters(e: Emitter, top: Frame): void {
+  for (const binding of e.checked.bindings) {
+    if (!e.carried.has(binding.id)) continue;
+    const register = e.layout.registerFor(binding);
+    if (register === undefined) continue;
+    top.builder.at(binding.declaredAt);
+    top.builder.push('LOADC', top.layout.cellFor(binding));
+    top.builder.push('SSTORE', register);
+  }
+}
+
+/**
+ * The one instruction pair that keeps a persistent name's past readable.
+ *
+ * A cell has no history and a register has no persistence, so `x[1]` on a `var`
+ * needs both (`language.md` 8.3). The register's entry for a bar is written
+ * from the cell at the end of the bar rather than at each assignment, because a
+ * bar on which the `var` was not assigned still holds a value, and a register
+ * written only where the source writes the name would be absent there and say
+ * the value had never existed.
+ */
+function closeShadowRegisters(e: Emitter, top: Frame): void {
+  for (const binding of e.checked.bindings) {
+    if (!e.shadowed.has(binding.id)) continue;
+    if (placementOf(e, binding) !== 'cell') continue;
+    if (!top.layout.hasCellFor(binding)) continue;
+    const register = e.layout.registerFor(binding);
+    if (register === undefined) continue;
+    top.builder.at(binding.declaredAt);
+    top.builder.push('LOADC', top.layout.cellFor(binding));
+    top.builder.push('SSTORE', register);
+  }
+}
+
+/** Every instruction a read's body holds, its own reads included. */
+function instructionsIn(requests: readonly Request[]): number {
+  let total = 0;
+  for (const request of requests) {
+    total += request.body.code.length;
+    for (const one of request.body.functions) total += one.code.length;
+    total += instructionsIn(request.body.requests);
+  }
+  return total;
+}
+
+/** Section 3.5 check 5, run here so a defect is found where it was written. */
+function checkDepths(e: Emitter, top: Frame, code: readonly Instruction[]): void {
+  const argcOf = (site: number): number => e.sites[site]?.argc ?? 0;
+  const lists: readonly (readonly Instruction[])[] = [code, ...e.functions.map((one) => one.code)];
+
+  for (const request of e.requests) checkRequestDepths(e, request);
+
+  lists.forEach((list, index) => {
+    const walk = walkDepths(list, argcOf);
+    const at = walk.conflict ?? walk.underflow ?? walk.terminal;
+    if (at === undefined) return;
+    e.gap(
+      `the stack depth this compiler emitted does not survive its own walk at instruction ${at}, ` +
+        'so an engine would refuse the program at load',
+      'compiled-program.md 3.5 check 5',
+      // The bar's own list is the one whose positions are to hand, and it is
+      // where all but one of these can happen. A line beats no line: whoever
+      // reads this next starts at the statement rather than at the file.
+      index === 0 ? lineOfInstruction(e, top, at) : undefined,
+      true,
+    );
+  });
+}
+
+/**
+ * The same walk over a read's body, which counts its own call sites (2.16).
+ *
+ * A body has no positions in the bar's own table, so a failure here carries the
+ * read's line rather than a line from the wrong list.
+ */
+function checkRequestDepths(e: Emitter, request: Request): void {
+  const argcOf = (site: number): number => request.body.callSites[site]?.argc ?? 0;
+  const lists = [request.body.code, ...request.body.functions.map((one) => one.code)];
+  for (const list of lists) {
+    const walk = walkDepths(list, argcOf);
+    const at = walk.conflict ?? walk.underflow ?? walk.terminal;
+    if (at === undefined) continue;
+    e.gap(
+      `the stack depth this compiler emitted for a read's expression does not survive its ` +
+        `own walk at instruction ${at}, so an engine would refuse the program at load`,
+      'compiled-program.md 3.5 check 5 and 2.16',
+      undefined,
+      true,
+    );
+  }
+  for (const nested of request.body.requests) checkRequestDepths(e, nested);
+}
+
+/** Where the instruction at this index came from, from the debug positions. */
+function lineOfInstruction(e: Emitter, top: Frame, index: number): Span | undefined {
+  let found: readonly [number, number, number] | undefined;
+  for (const position of top.builder.pos) {
+    if (position[0] > index) break;
+    found = position;
+  }
+  if (found === undefined) return undefined;
+  return e.file.spanAt(e.file.offsetAt({ line: found[1], column: found[2] }), 1);
+}
+
+/**
+ * OS5004 and OS5009, the two limits the compiler rather than the engine finds.
+ *
+ * Both are reported only against a ceiling a host actually declared. A compiler
+ * that invented one would refuse a program every engine present could run.
+ */
+function checkLimits(e: Emitter, code: readonly Instruction[], states: number): void {
+  const span = e.checked.script.span;
+  const maxStates = e.options.maxStates;
+  if (maxStates !== undefined && states > maxStates) {
+    e.sink.report('OS5004', span, {
+      found: states,
+      max: maxStates,
+      first: e.functions[0]?.name ?? '',
+      second: e.functions[1]?.name ?? e.functions[0]?.name ?? '',
+    });
+  }
+
+  const maxInstructions = e.options.maxInstructions;
+  const total =
+    code.length +
+    e.functions.reduce((sum, one) => sum + one.code.length, 0) +
+    // A read's expression is instructions an engine executes, once per
+    // requested bar, so it counts against the ceiling like any other (2.16).
+    instructionsIn(e.requests);
+  if (maxInstructions !== undefined && total > maxInstructions) {
+    e.sink.report('OS5009', span, { found: total, max: maxInstructions });
+  }
+}

package/src/core/emit/events.ts

@@ -0,0 +1,141 @@
+/**
+ * The four calls that draw something for one bar: a marker, an alert, a bar
+ * colour and a pane background.
+ *
+ * All four are `EMIT` and a declared channel, and none of them is a library
+ * call an engine performs. One instruction covers every drawing surface
+ * (`compiled-program.md` 4.11); an instruction per surface would have added six
+ * opcodes that all do the same thing and would have made every new surface a
+ * format change.
+ *
+ * The alert is the one worth reading. `stdlib.md` 16.1 says the compiler lifts
+ * each call into a watched condition whose predicate is the chain of guards
+ * that reaches it. Nothing has to be lifted: the call site is only reached when
+ * those guards passed, so writing `true` into the condition channel there is
+ * the predicate, exactly. On a bar the guards refused, nothing writes the
+ * channel and a channel nothing wrote is absent, which is no alert.
+ */
+import type { Call } from '../ast/index.js';
+import { alertKey } from '../check/index.js';
+import type { Emitter, Frame } from './context.js';
+import { ALERT_DEFAULTS, MARKER_DEFAULTS } from './defaults.js';
+import { emitExpression } from './expressions.js';
+import { argumentFor, fieldFor } from './outputs.js';
+
+export function emitEventCall(e: Emitter, f: Frame, call: Call, name: string): void {
+  switch (name) {
+    case 'signal':
+      emitMarker(e, f, call);
+      return;
+    case 'alert':
+      emitAlert(e, f, call);
+      return;
+    case 'barColor':
+      e.barColor = { channel: emitPaint(e, f, call, e.barColor?.channel, 'bar colour') };
+      return;
+    case 'background':
+      e.background = { channel: emitPaint(e, f, call, e.background?.channel, 'background') };
+      return;
+    default:
+      return;
+  }
+}
+
+/**
+ * One entry per `signal()` call site, and a channel that is held back on a bar
+ * that is still moving.
+ *
+ * A marker is emitted when its channel holds a string for the bar and not
+ * otherwise, so a call site inside an `if` produces a marker on the bars the
+ * branch was taken and nothing anywhere else. The channel is not declared
+ * `once` for that reason: a signal may sit under a condition, which is the
+ * whole point of one.
+ */
+function emitMarker(e: Emitter, f: Frame, call: Call): void {
+  const text = argumentFor(e, call, 'text');
+  // A marker's channel is named after the text it carries when that is a
+  // literal, which is what 12.2's `debug.names.channels` shows.
+  const literal = text === undefined ? undefined : e.fold(text.value);
+  const name = literal?.kind === 'string' ? literal.value : `marker ${e.markers.length}`;
+  const channel = e.layout.channel('string', true, false, name);
+  if (text === undefined) {
+    f.builder.at(call.span);
+    f.builder.push('CONST', e.pool.absent());
+  } else {
+    emitExpression(e, f, text.value);
+  }
+  f.builder.at(call.span);
+  f.builder.push('EMIT', channel);
+
+  e.markers.push({
+    key: `m${e.markers.length}`,
+    channel,
+    position: fieldFor(e, call, 'at', MARKER_DEFAULTS),
+    shape: fieldFor(e, call, 'shape', MARKER_DEFAULTS),
+    color: fieldFor(e, call, 'color', MARKER_DEFAULTS),
+    // `markers[].textColor` has no argument in the library: `signal` takes one
+    // colour and it is the plate's. Null is the effective value of a field no
+    // script can express, which is 2.8's own reading of a table's text size.
+    textColor: null,
+  });
+}
+
+function emitAlert(e: Emitter, f: Frame, call: Call): void {
+  const id = fieldFor(e, call, 'id', ALERT_DEFAULTS);
+  // `id` is the stable name of the entry, so a user's alert subscription
+  // survives an edit to the script. With none, the compiler derives one from
+  // the call's position, which is what OS8008 already warns about, and the
+  // checker refuses two alerts that would land under one name with OS3017.
+  const key = alertKey(typeof id === 'string' ? id : undefined, call.span.line);
+  const condChannel = e.layout.channel('bool', true, false, key);
+  const messageChannel = e.layout.channel('string', true, false, `${key} message`);
+
+  f.builder.at(call.span);
+  f.builder.push('CONST', e.pool.bool(true));
+  f.builder.push('EMIT', condChannel);
+
+  const message = argumentFor(e, call, 'message');
+  if (message === undefined) {
+    f.builder.at(call.span);
+    f.builder.push('CONST', e.pool.absent());
+  } else {
+    emitExpression(e, f, message.value);
+  }
+  f.builder.at(call.span);
+  f.builder.push('EMIT', messageChannel);
+
+  e.alerts.push({
+    key,
+    title: fieldFor(e, call, 'title', ALERT_DEFAULTS),
+    condChannel,
+    messageChannel,
+    frequency: fieldFor(e, call, 'frequency', ALERT_DEFAULTS),
+  });
+}
+
+/**
+ * `barColor` and `background`: one channel each per program.
+ *
+ * A script with three `barColor()` calls writes the same channel three times
+ * and the last write on the bar wins, which is the same rule as any other
+ * channel and needs no sentence of its own (2.8).
+ */
+function emitPaint(
+  e: Emitter,
+  f: Frame,
+  call: Call,
+  existing: number | undefined,
+  name: string,
+): number {
+  const channel = existing ?? e.layout.channel('color', false, false, name);
+  const colour = argumentFor(e, call, 'color');
+  if (colour === undefined) {
+    f.builder.at(call.span);
+    f.builder.push('CONST', e.pool.absent());
+  } else {
+    emitExpression(e, f, colour.value);
+  }
+  f.builder.at(call.span);
+  f.builder.push('EMIT', channel);
+  return channel;
+}