openalgo-script 0.1.0-alpha.1 → 0.2.0

package/src/core/emit/program.ts

@@ -0,0 +1,385 @@
+/**
+ * The compiled program, as `compiled-program.md` section 2 defines it.
+ *
+ * This file is the artifact's shape and nothing else: no logic, no defaults, no
+ * decisions. It is separate because the artifact is the public contract of the
+ * project. Somebody implementing an engine in another language reads the
+ * specification and then reads this to check the two agree, and a type with a
+ * field the specification does not have, or missing one it does, is the defect
+ * no test of our own engine would ever catch.
+ *
+ * Field order here follows the specification's. It is not the order canonical
+ * encoding writes: that one sorts keys, and `canonical.ts` is where it happens.
+ */
+
+/** One entry of the constant pool, `compiled-program.md` 2.9. */
+export type Constant =
+  | readonly ['z', null]
+  | readonly ['b', boolean]
+  | readonly ['n', number]
+  | readonly ['s', string]
+  | readonly ['c', Colour];
+
+/** Red, green and blue as whole numbers 0 to 255, alpha as a number 0 to 1. */
+export type Colour = readonly [number, number, number, number];
+
+/**
+ * One instruction: the opcode name, then its operands.
+ *
+ * The opcode is a string because the format says so (2.14), so a program is
+ * readable and diffable by hand and a format that adds an opcode renumbers
+ * nothing.
+ */
+export type Instruction = readonly [string, ...number[]];
+
+/**
+ * A declaration field a script wrote with an `input()`, 2.3.
+ *
+ * The engine resolves it once at load and substitutes the value, so nothing of
+ * this form survives to bar 0.
+ */
+export interface InputReference {
+  readonly input: string;
+}
+
+/**
+ * A fact the host states at load, named where a request's identity is fixed.
+ *
+ * `req.symbol(leg, chart.interval, ...)` reads the chart's own interval, and
+ * `exchange = chart.exchange` is the default `stdlib.md` 15.1 writes out. Both
+ * are settled before bar 0 and neither is a value this compiler can know, so
+ * the request names the fact and the engine resolves it at load (2.16).
+ */
+export interface ChartReference {
+  readonly chart: 'symbol' | 'exchange' | 'interval';
+}
+
+/** Anything a declaration field may hold: a value, or a reference to an input. */
+export type Field =
+  | null
+  | boolean
+  | number
+  | string
+  | Colour
+  | readonly number[]
+  | InputReference;
+
+/** What fixes one part of a request's identity, 2.16. */
+export type RequestField = Field | ChartReference;
+
+export interface FormatVersion {
+  readonly format: string;
+  readonly language: number;
+}
+
+export interface CompilerStamp {
+  readonly name: string;
+  readonly version: string;
+}
+
+export interface SourceStamp {
+  readonly hash: string;
+  readonly lines: number;
+  readonly file: string | null;
+}
+
+export interface StrategyMeta {
+  readonly capital: Field;
+  readonly currency: Field;
+  readonly qty: Field;
+  readonly qtyType: Field;
+  readonly product: Field;
+  readonly fillOn: Field;
+  readonly slippage: Field;
+  readonly commission: Field;
+  readonly commissionType: Field;
+  readonly pyramiding: Field;
+  readonly closeOnSessionEnd: Field;
+}
+
+export interface Meta {
+  readonly kind: 'study' | 'strategy';
+  readonly title: Field;
+  readonly short: Field;
+  readonly overlay: Field;
+  readonly precision: Field;
+  readonly format: Field;
+  readonly range: Field;
+  readonly scale: Field;
+  readonly group: Field;
+  readonly onUnconfirmed: Field;
+  /** Present only when `kind` is `"strategy"`, 2.3. */
+  readonly strategy?: StrategyMeta;
+}
+
+export interface Limits {
+  readonly loops: number;
+  readonly history: number | null;
+}
+
+export interface LibraryFunction {
+  readonly name: string;
+  readonly arity: number;
+  readonly state: boolean;
+  readonly effect: 'none' | 'signal' | 'order' | 'draw' | 'log';
+}
+
+export interface Library {
+  readonly manifest: number;
+  readonly functions: readonly LibraryFunction[];
+}
+
+export interface CompiledInput {
+  readonly key: string;
+  readonly kind: string;
+  readonly label: string;
+  readonly default: Constant;
+  readonly min: number | null;
+  readonly max: number | null;
+  readonly step: number | null;
+  readonly options: readonly Constant[] | null;
+  readonly group: string;
+  readonly tooltip: string | null;
+  readonly slot: number;
+}
+
+export interface Channel {
+  readonly id: number;
+  readonly type: 'number' | 'string' | 'color' | 'bool';
+  readonly defer: boolean;
+  readonly once: boolean;
+}
+
+export interface CandleChannels {
+  readonly open: number;
+  readonly high: number;
+  readonly low: number;
+  readonly close: number;
+  readonly colorUp: Field;
+  readonly colorDown: Field;
+  readonly wickColor: Field;
+  readonly borderColor: Field;
+  readonly colorUpChannel: number | null;
+  readonly colorDownChannel: number | null;
+  readonly wickColorChannel: number | null;
+  readonly borderColorChannel: number | null;
+}
+
+export interface Plot {
+  readonly key: string;
+  readonly title: Field;
+  readonly type: string;
+  readonly channel: number;
+  readonly color: Field;
+  readonly colorChannel: number | null;
+  readonly width: Field;
+  readonly lineStyle: Field;
+  readonly offset: Field;
+  readonly overlay: Field;
+  readonly scale: Field;
+  readonly precision: Field;
+  readonly priceFormat: Field;
+  readonly ohlc: CandleChannels | null;
+}
+
+export interface Band {
+  readonly between: readonly [string, string];
+  readonly colorUp: Field;
+  readonly colorDown: Field;
+  readonly colorUpChannel: number | null;
+  readonly colorDownChannel: number | null;
+  readonly opacity: Field;
+  readonly overlay: Field;
+}
+
+export interface Level {
+  readonly title: Field;
+  readonly channel: number;
+  readonly color: Field;
+  readonly lineStyle: Field;
+  readonly lineWidth: Field;
+}
+
+export interface Marker {
+  readonly key: string;
+  readonly channel: number;
+  readonly position: Field;
+  readonly shape: Field;
+  readonly color: Field;
+  readonly textColor: Field;
+}
+
+export interface TableOptions {
+  readonly textColor: Field;
+  readonly bgColor: Field;
+  readonly borderWidth: Field;
+}
+
+export interface Grid {
+  readonly key: string;
+  readonly title: Field;
+  readonly slot: number;
+  readonly position: Field;
+  readonly rows: Field;
+  readonly cols: Field;
+  readonly options: TableOptions;
+}
+
+export interface Alert {
+  readonly key: string;
+  readonly title: Field;
+  readonly condChannel: number;
+  readonly messageChannel: number | null;
+  readonly frequency: Field;
+}
+
+export interface Paint {
+  readonly channel: number;
+}
+
+export interface Outputs {
+  readonly plots: readonly Plot[];
+  readonly fills: readonly Band[];
+  readonly levels: readonly Level[];
+  readonly markers: readonly Marker[];
+  readonly tables: readonly Grid[];
+  readonly alerts: readonly Alert[];
+  readonly barColor: Paint | null;
+  readonly background: Paint | null;
+}
+
+export interface Register {
+  readonly id: number;
+  /**
+   * Where the register's entry for a bar comes from, 2.10.
+   *
+   * `request` and `input` are the two the engine fills rather than the program:
+   * the first from the answer to the read that names it in 2.16, the second
+   * from a resolved setting. Neither is ever written by an instruction.
+   */
+  readonly kind: 'bar' | 'computed' | 'argument' | 'request' | 'input';
+  readonly field: string | null;
+  readonly name: string | null;
+}
+
+export interface Frame {
+  readonly slots: number;
+}
+
+export interface Cell {
+  readonly id: number;
+  readonly kind: 'var' | 'live';
+  readonly name: string | null;
+}
+
+export interface StateRegion {
+  readonly id: number;
+  readonly fn: number;
+}
+
+export interface CompiledFunction {
+  readonly name: string;
+  readonly params: number;
+  readonly slots: number;
+  readonly code: readonly Instruction[];
+}
+
+export interface CallSite {
+  readonly fn: number;
+  readonly argc: number;
+  readonly cellBase: number;
+  readonly stateBase: number;
+  readonly series: readonly number[];
+}
+
+export interface Loop {
+  readonly id: number;
+  readonly kind: 'for' | 'forIn' | 'while';
+  readonly line: number;
+  readonly col: number;
+}
+
+/** `[instructionIndex, line, column]`, ascending by index, 2.15. */
+export type Position = readonly [number, number, number];
+
+/**
+ * One setting a read's expression reads, 2.16.
+ *
+ * It names a register rather than a slot because a body is one expression with
+ * no statement to write a slot from, and because a function body inside it
+ * reaches a register from any frame and a slot only from its own.
+ */
+export interface RequestInput {
+  readonly input: string;
+  readonly series: number;
+}
+
+/** An expression compiled over requested bars, 2.16. */
+export interface RequestBody {
+  readonly inputs: readonly RequestInput[];
+  readonly series: readonly Register[];
+  readonly frame: Frame;
+  readonly cells: readonly Cell[];
+  readonly states: readonly StateRegion[];
+  readonly functions: readonly CompiledFunction[];
+  readonly callSites: readonly CallSite[];
+  readonly loops: readonly Loop[];
+  /** Reads written inside this one, over bars the body's own bars fold from. */
+  readonly requests: readonly Request[];
+  readonly code: readonly Instruction[];
+  readonly pos: readonly Position[];
+  readonly fnPos: readonly (readonly [number, readonly Position[]])[];
+}
+
+/** One higher timeframe or other instrument read, 2.16. */
+export interface Request {
+  readonly id: number;
+  readonly read: 'timeframe' | 'symbol';
+  readonly symbol: RequestField;
+  readonly exchange: RequestField;
+  readonly timeframe: RequestField;
+  readonly mode: 'confirmed' | 'developing' | 'lookahead';
+  /** The register the read's value for each chart bar lands in. */
+  readonly series: number;
+  /** Requested bars of history the body needs, or null when no floor is known. */
+  readonly warmup: number | null;
+  readonly body: RequestBody;
+}
+
+export interface DebugNames {
+  readonly slots: readonly string[];
+  readonly cells: readonly string[];
+  readonly series: readonly string[];
+  readonly channels: readonly string[];
+}
+
+export interface Debug {
+  readonly pos: readonly Position[];
+  readonly fnPos: readonly (readonly [number, readonly Position[]])[];
+  readonly names: DebugNames;
+  readonly retain: boolean;
+}
+
+export interface CompiledProgram {
+  readonly openscript: FormatVersion;
+  readonly requires: readonly string[];
+  readonly compiler: CompilerStamp;
+  readonly source: SourceStamp;
+  readonly meta: Meta;
+  readonly limits: Limits;
+  readonly lib: Library;
+  readonly inputs: readonly CompiledInput[];
+  readonly channels: readonly Channel[];
+  readonly outputs: Outputs;
+  readonly consts: readonly Constant[];
+  readonly series: readonly Register[];
+  readonly frame: Frame;
+  readonly cells: readonly Cell[];
+  readonly states: readonly StateRegion[];
+  readonly functions: readonly CompiledFunction[];
+  readonly callSites: readonly CallSite[];
+  readonly loops: readonly Loop[];
+  readonly code: readonly Instruction[];
+  readonly debug: Debug;
+  readonly requests: readonly Request[];
+}

package/src/core/emit/registers.ts

@@ -0,0 +1,179 @@
+/**
+ * Which values get a series register, and which of the three regions a name
+ * ends up in.
+ *
+ * The checker answers most of this already: a top-level name whose history the
+ * program reads is a register, a `var` is a cell, everything else is a slot
+ * (`compiled-program.md` 2.10 and 2.11). Two cases are left over, and both are
+ * the emitter's because both are about the shape of the instruction set rather
+ * than about the language.
+ *
+ * **A persistent name whose history is read is both.** `x[1]` on a `var` is
+ * "both" in `language.md` 8.3's own words: the cell carries the value forward
+ * and the register carries the past. Only a register has history, so a `var`
+ * the program indexes needs one beside its cell.
+ *
+ * **A slot cannot be read from another frame.** Slots are per frame (3.2), so a
+ * function body that reads a file-scope name has no instruction that reaches
+ * it. A name recomputed every bar can be given a register instead, which is
+ * addressed the same way from every frame and holds the same value the slot
+ * would have. A `var` cannot be promoted that way, because a register has no
+ * persistence: it keeps its cell and takes a register beside it, filled from
+ * the cell at the start of the bar and again at every assignment, so a body
+ * called anywhere in the bar reads what the cell holds at that point.
+ */
+import { walk, withoutGrouping } from '../ast/index.js';
+import type { Binding } from '../check/index.js';
+import type { Emitter } from './context.js';
+import { declaredNames } from './context.js';
+
+/** The bar fields an engine fills from the host's bar, `compiled-program.md` 2.10. */
+export const BAR_FIELDS: readonly string[] = [
+  'open',
+  'high',
+  'low',
+  'close',
+  'volume',
+  'time',
+  'hl2',
+  'hlc3',
+  'ohlc4',
+  'hlcc4',
+  'oi',
+];
+
+/** The `bar.*` facts of `language.md` 7.2, which 2.10 makes registers as well. */
+export const BAR_FACTS: readonly string[] = [
+  'bar.index',
+  'bar.count',
+  'bar.isFirst',
+  'bar.isLast',
+  'bar.isConfirmed',
+  'bar.isRealtime',
+  'bar.isNew',
+  'bar.updates',
+];
+
+/** `oi` is a built-in series and 2.10's table of bar fields does not list it. */
+const UNLISTED_BAR_FIELD = 'oi';
+
+export type Placement = 'slot' | 'cell' | 'register';
+
+/**
+ * The register a built-in series is read from, or nothing when the name is not
+ * one.
+ */
+export function registerOfName(e: Emitter, name: string): number | undefined {
+  if (name === UNLISTED_BAR_FIELD) {
+    e.gap(
+      "`oi` is a built-in series of stdlib.md 3.1 and 2.10's table of bar register fields " +
+        'does not list it, so the field name it is filled from is this compiler\'s choice',
+      'compiled-program.md 2.10, against stdlib.md 3.1',
+      undefined,
+      false,
+    );
+    return e.layout.bar(UNLISTED_BAR_FIELD);
+  }
+  if (BAR_FIELDS.includes(name) || BAR_FACTS.includes(name)) return e.layout.bar(name);
+  return undefined;
+}
+
+/**
+ * Names whose value is a declaration handle, which `var` cannot change.
+ *
+ * A handle is settled before bar 0 and the engine writes it into the slot the
+ * declaration names (2.11), so there is nothing for a cell to carry forward and
+ * nothing to carry it forward from: `var grid = table(...)` and
+ * `grid = table(...)` are the same declaration, and a reader who wrote the
+ * first should not get a different program from the second.
+ */
+export function markDeclarationHandles(e: Emitter): void {
+  for (const declared of declaredNames(e)) {
+    const inner = withoutGrouping(declared.value);
+    if (inner.kind !== 'call') continue;
+    const name = e.callAt(inner)?.name ?? '';
+    if (!e.isDeclaration(name)) continue;
+    // `input()` is the one declaration call that also has a value, so it is the
+    // one a `var` says something about: `var len = input(14, "Length")` is an
+    // ordinary `var` initialised from the setting, and what it buys is a cell a
+    // later assignment keeps (`language.md` 8.2 and 13.4). The name therefore
+    // does not stand for the declaration the way `grid = table(...)` does, and
+    // the input keeps a slot of its own for the engine to write at step 5.
+    if (declared.persistent && name === 'input') continue;
+    const binding = e.checked.targets.get(declared.name);
+    if (binding !== undefined) e.handles.add(binding.id);
+  }
+}
+
+/** Where a name's value lives, the checker's answer with the three cases above. */
+export function placementOf(e: Emitter, binding: Binding): Placement {
+  if (e.handles.has(binding.id)) return 'slot';
+  if (binding.persistence !== 'none') return 'cell';
+  if (binding.storage === 'register' || e.promoted.has(binding.id)) return 'register';
+  return 'slot';
+}
+
+/** The register a history read of a name reads from, allocating it if needed. */
+export function shadowRegister(e: Emitter, binding: Binding): number {
+  // A setting read inside a read's expression already has one, filled by the
+  // engine on every requested bar, and a second would hold nothing (2.16).
+  return e.request?.registerFor(e, binding) ?? e.layout.computedFor(binding);
+}
+
+/**
+ * Decides every register before a single instruction is emitted.
+ *
+ * It has to happen first because the prologue and the epilogue that keep a
+ * shadow register in step with its cell are instructions like any other, and
+ * they cannot be written after the list they belong at the ends of.
+ */
+export function prepareRegisters(e: Emitter): void {
+  markDeclarationHandles(e);
+  const readInsideFunction = namesReadInsideFunctions(e);
+
+  for (const binding of e.checked.bindings) {
+    if (binding.kind === 'library' || binding.kind === 'function') continue;
+
+    const crossesFrame = binding.kind === 'file' && readInsideFunction.has(binding.id);
+    const retained = e.options.retain === true && binding.kind === 'file';
+    if (binding.persistence === 'none' && (crossesFrame || retained)) {
+      e.promoted.add(binding.id);
+    }
+
+    const placement = placementOf(e, binding);
+    if (placement === 'register') {
+      e.layout.computedFor(binding);
+      continue;
+    }
+    // A `var` a function body reads cannot be promoted, because a register has
+    // no persistence: it gets a register beside its cell instead, and the two
+    // are kept in step through the bar rather than only at the end of it.
+    if (placement === 'cell' && crossesFrame) {
+      e.layout.computedFor(binding);
+      e.shadowed.add(binding.id);
+      e.carried.add(binding.id);
+      continue;
+    }
+    // A cell or an input slot whose past is read carries a register beside it,
+    // written once per bar so the entry for a bar is the value it ended with.
+    if (binding.readsHistory) {
+      e.layout.computedFor(binding);
+      e.shadowed.add(binding.id);
+    }
+  }
+}
+
+/** Every file-scope name some function body reads, which a slot cannot serve. */
+function namesReadInsideFunctions(e: Emitter): ReadonlySet<number> {
+  const found = new Set<number>();
+  for (const declared of e.checked.functions) {
+    walk(declared.declaration, {
+      enter: (node) => {
+        if (node.kind !== 'nameReference') return;
+        const binding = e.checked.references.get(node);
+        if (binding !== undefined && binding.kind === 'file') found.add(binding.id);
+      },
+    });
+  }
+  return found;
+}

package/src/core/emit/request-scope.ts

@@ -0,0 +1,52 @@
+/**
+ * One read's expression while it is being emitted, and the settings it reads.
+ *
+ * Its own file rather than a class inside `context.ts`, because it is not the
+ * state one compile shares: it is the state of one expression compiled over
+ * another instrument's bars, and the one thing that crosses the boundary
+ * between the two.
+ */
+import type { Binding, CheckedInput } from '../check/index.js';
+import { inputHeldBy } from '../check/index.js';
+import type { Emitter } from './context.js';
+import { inputKey } from './context.js';
+import type { RequestInput } from './program.js';
+
+/**
+ * `stdlib.md` 15.4 lets an expression inside a read name a setting and nothing
+ * else of the file, because a setting resolves before bar 0 and holds for the
+ * run while a per-bar name has no counterpart on the requested bars. Each one
+ * read here is filled into a register of the body's own table, named by
+ * `inputs` on the request (2.16).
+ */
+export class RequestScope {
+  readonly inputs: RequestInput[] = [];
+  private readonly byInput = new Map<number, number>();
+
+  /** The register a setting is filled into, or nothing when this is not one. */
+  registerFor(e: Emitter, binding: Binding): number | undefined {
+    const held = inputHeldBy(binding);
+    if (held === undefined) return undefined;
+    const input = e.checked.inputs[held];
+    return input === undefined ? undefined : this.registerForInput(e, input);
+  }
+
+  /**
+   * The same register for an `input()` written inside the expression itself.
+   *
+   * The two forms are one question. `stdlib.md` 15.4 lets a read's expression
+   * name a setting because a setting resolves before bar 0 and holds for the
+   * run, and that is a fact about the input rather than about whether a name
+   * was put in front of it. So both resolve here, keyed by the input, and two
+   * reads of one setting inside one body share one register rather than asking
+   * the engine to fill the same value twice.
+   */
+  registerForInput(e: Emitter, input: CheckedInput): number {
+    const found = this.byInput.get(input.id);
+    if (found !== undefined) return found;
+    const register = e.layout.filled('input', inputKey(input));
+    this.byInput.set(input.id, register);
+    this.inputs.push({ input: inputKey(input), series: register });
+    return register;
+  }
+}