openalgo-script 0.1.0-alpha.1 → 0.4.0

package/src/core/emit/values.ts

@@ -0,0 +1,284 @@
+/**
+ * Values the compiler can work out before bar 0, and the folding that gets
+ * there.
+ *
+ * Two parts of the format need this and nothing else does. A constant pool
+ * entry is a value (`compiled-program.md` 2.9), and every declaration field is
+ * written with the value its option resolved to, defaults included (2.3). So a
+ * plot's colour, a study's precision and a table's corner all have to be a
+ * value here or they cannot be carried at all.
+ *
+ * The one thing that is a field and is not a value is the reference form
+ * `{ "input": "<key>" }`, which is why it is a member of this union rather than
+ * something a later stage substitutes. It may stand **in place of** a value and
+ * may not take part in one: `opacity = dim` is carried, `opacity = dim * 2` has
+ * nowhere in the format to live, and folding says so by refusing rather than by
+ * inventing a number from the input's default.
+ *
+ * The colour arithmetic is here because `stdlib.md` 11.2 defines it exactly:
+ * `fade(c, p)` is `withAlpha(c, (100 - p) / 100)`, and every call that computes
+ * a colour rounds the three channels with the language's own rounding, halves
+ * away from zero. Both are written out rather than approximated, because a
+ * colour folded here and the same colour computed by an engine have to be the
+ * same bits.
+ */
+import type { Argument, Call, Expression, NameReference } from '../ast/index.js';
+import { withoutGrouping } from '../ast/index.js';
+import { FOLDABLE_CALLS } from '../check/index.js';
+import type { Colour, Field } from './program.js';
+import { hexColour, namedColour } from './colours.js';
+
+export type Value =
+  | { readonly kind: 'absent' }
+  | { readonly kind: 'bool'; readonly value: boolean }
+  | { readonly kind: 'number'; readonly value: number }
+  | { readonly kind: 'string'; readonly value: string }
+  | { readonly kind: 'colour'; readonly value: Colour }
+  | { readonly kind: 'array'; readonly values: readonly Value[] }
+  /** Carried into a declaration field as the reference of 2.3, never computed with. */
+  | { readonly kind: 'input'; readonly key: string };
+
+export const ABSENT: Value = { kind: 'absent' };
+
+export interface FoldEnvironment {
+  /** What a bare name denotes before bar 0, or nothing when it denotes a bar. */
+  name(reference: NameReference): Value | undefined;
+  /** A resolved call: its library name and its arguments in parameter order. */
+  call(
+    call: Call,
+  ): { readonly name: string; readonly args: readonly (Argument | undefined)[] } | undefined;
+  /** The input an `input()` call declares, as the reference that names it. */
+  input(call: Call): Value | undefined;
+}
+
+/** The language's own rounding, halves away from zero, `stdlib.md` 8.1. */
+export function roundHalfAway(x: number): number {
+  return x < 0 ? -Math.floor(-x + 0.5) : Math.floor(x + 0.5);
+}
+
+/** Normalises a negative zero, which nothing in the language can observe (3.1). */
+function noNegativeZero(x: number): number {
+  return x === 0 ? 0 : x;
+}
+
+type Channels = readonly [number, number, number, number];
+
+function at(colour: Channels, index: number): number {
+  return colour[index] ?? 0;
+}
+
+function colourOf(value: Value | undefined): Colour | undefined {
+  return value !== undefined && value.kind === 'colour' ? value.value : undefined;
+}
+
+function numberOf(value: Value | undefined): number | undefined {
+  return value !== undefined && value.kind === 'number' ? value.value : undefined;
+}
+
+function channel(x: number): number {
+  return roundHalfAway(x);
+}
+
+/**
+ * The colour calls of `stdlib.md` 11.2 that a declaration field can hold.
+ *
+ * `mix` is included because it is the call that produces fractional channels
+ * and is therefore the one where the rounding rule bites; `alpha` is included
+ * because it returns a number and a script may use one in a field.
+ *
+ * Which names those are is the checker's `FOLDABLE_CALLS`, and is read from
+ * there rather than repeated here: the checker accepts a call in a field that
+ * has to be fixed before bar 0 on the strength of this folding it, so the two
+ * lists being one list is what keeps the compiler from refusing a script it had
+ * already passed.
+ */
+function foldColourCall(
+  name: string,
+  args: readonly (Value | undefined)[],
+): Value | undefined {
+  if (!FOLDABLE_CALLS.has(name)) return undefined;
+  if (name === 'rgb' || name === 'rgba') {
+    const r = numberOf(args[0]);
+    const g = numberOf(args[1]);
+    const b = numberOf(args[2]);
+    const a = name === 'rgba' ? numberOf(args[3]) : 1;
+    if (r === undefined || g === undefined || b === undefined || a === undefined) return undefined;
+    return { kind: 'colour', value: [channel(r), channel(g), channel(b), a] };
+  }
+  if (name === 'fade' || name === 'withAlpha') {
+    const colour = colourOf(args[0]);
+    const amount = numberOf(args[1]);
+    if (colour === undefined || amount === undefined) return undefined;
+    // fade takes transparency as a percentage and sets the alpha absolutely.
+    const alpha = name === 'fade' ? (100 - amount) / 100 : amount;
+    return { kind: 'colour', value: [colour[0], colour[1], colour[2], alpha] };
+  }
+  if (name === 'alpha') {
+    const colour = colourOf(args[0]);
+    return colour === undefined ? undefined : { kind: 'number', value: colour[3] };
+  }
+  if (name === 'mix') {
+    const a = colourOf(args[0]);
+    const b = colourOf(args[1]);
+    const weight = numberOf(args[2]);
+    if (a === undefined || b === undefined || weight === undefined) return undefined;
+    const blend = (i: number): number => channel(at(a, i) + (at(b, i) - at(a, i)) * weight);
+    return {
+      kind: 'colour',
+      value: [blend(0), blend(1), blend(2), a[3] + (b[3] - a[3]) * weight],
+    } as const;
+  }
+  return undefined;
+}
+
+function foldArithmetic(operator: string, left: Value, right: Value): Value | undefined {
+  if (operator === '+' && left.kind === 'string' && right.kind === 'string') {
+    return { kind: 'string', value: left.value + right.value };
+  }
+  if (left.kind !== 'number' || right.kind !== 'number') return undefined;
+  const a = left.value;
+  const b = right.value;
+  let result: number;
+  switch (operator) {
+    case '+':
+      result = a + b;
+      break;
+    case '-':
+      result = a - b;
+      break;
+    case '*':
+      result = a * b;
+      break;
+    case '/':
+      if (b === 0) return ABSENT;
+      result = a / b;
+      break;
+    case '%':
+      if (b === 0) return ABSENT;
+      result = a % b;
+      break;
+    default:
+      return undefined;
+  }
+  // Any result that is not finite is absent, checked after each operation (3.1).
+  return Number.isFinite(result)
+    ? { kind: 'number', value: noNegativeZero(result) }
+    : ABSENT;
+}
+
+/**
+ * The value an expression has before bar 0, or nothing when it has none.
+ *
+ * Nothing here reports a diagnostic. An expression the checker already accepted
+ * as a compile-time constant and this refuses is a shape the format cannot
+ * carry, and the caller is the one that knows which field it was going into.
+ */
+export function fold(expression: Expression, environment: FoldEnvironment): Value | undefined {
+  const inner = withoutGrouping(expression);
+  switch (inner.kind) {
+    case 'numberLiteral':
+      return { kind: 'number', value: noNegativeZero(inner.value) };
+    case 'stringLiteral':
+      return { kind: 'string', value: inner.value };
+    case 'booleanLiteral':
+      return { kind: 'bool', value: inner.value };
+    case 'noneLiteral':
+      return ABSENT;
+    case 'colorLiteral': {
+      const colour = hexColour(inner.text);
+      return colour === undefined ? undefined : { kind: 'colour', value: colour };
+    }
+    case 'nameReference': {
+      const named = namedColour(inner.name);
+      if (named !== undefined) return { kind: 'colour', value: named };
+      return environment.name(inner);
+    }
+    case 'member': {
+      const object = withoutGrouping(inner.object);
+      if (object.kind !== 'nameReference' || object.name !== 'math') return undefined;
+      if (inner.member.text === 'pi') return { kind: 'number', value: Math.PI };
+      if (inner.member.text === 'e') return { kind: 'number', value: Math.E };
+      return undefined;
+    }
+    case 'arrayLiteral': {
+      const values: Value[] = [];
+      for (const element of inner.elements) {
+        const value = fold(element, environment);
+        if (value === undefined) return undefined;
+        // A reference stands **in place of** a field's value and never inside
+        // one, so `range = [input(0, "Low"), 100]` has nowhere in the format to
+        // live and is refused here rather than written as an absent range.
+        if (value.kind === 'input') return undefined;
+        values.push(value);
+      }
+      return { kind: 'array', values };
+    }
+    case 'unary': {
+      const operand = fold(inner.operand, environment);
+      if (operand === undefined) return undefined;
+      if (operand.kind === 'absent') return ABSENT;
+      if (inner.operator === 'not') {
+        return operand.kind === 'bool' ? { kind: 'bool', value: !operand.value } : undefined;
+      }
+      if (operand.kind !== 'number') return undefined;
+      const value = inner.operator === '-' ? -operand.value : operand.value;
+      return { kind: 'number', value: noNegativeZero(value) };
+    }
+    case 'binary': {
+      const left = fold(inner.left, environment);
+      const right = fold(inner.right, environment);
+      if (left === undefined || right === undefined) return undefined;
+      if (left.kind === 'absent' || right.kind === 'absent') return ABSENT;
+      return foldArithmetic(inner.operator, left, right);
+    }
+    case 'ternary': {
+      const condition = fold(inner.condition, environment);
+      if (condition === undefined || condition.kind !== 'bool') return undefined;
+      return fold(condition.value ? inner.whenTrue : inner.whenFalse, environment);
+    }
+    case 'call': {
+      const resolved = environment.call(inner);
+      if (resolved === undefined) return undefined;
+      // An `input()` written in place is the reference of 2.3, exactly as the
+      // name a script bound one to is. `language.md` 13.2 admits both spellings
+      // of an option value and the declaration line can only write this one:
+      // it is the first statement of the file, so there is no name above it.
+      if (resolved.name === 'input') return environment.input(inner);
+      const args = resolved.args.map((one) =>
+        one === undefined ? undefined : fold(one.value, environment),
+      );
+      return foldColourCall(resolved.name, args);
+    }
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * A folded value as a declaration field, `compiled-program.md` 2.3.
+ *
+ * Absence is null, because absence is what an argument a script named none for
+ * resolves to and null is the effective value rather than a missing one. An
+ * input is carried as its reference and is resolved away before bar 0.
+ */
+export function fieldOf(value: Value | undefined): Field {
+  if (value === undefined) return null;
+  switch (value.kind) {
+    case 'absent':
+      return null;
+    case 'bool':
+      return value.value;
+    case 'number':
+      return value.value;
+    case 'string':
+      return value.value;
+    case 'colour':
+      return value.value;
+    case 'input':
+      return { input: value.key };
+    case 'array': {
+      const numbers = value.values.map((one) => (one.kind === 'number' ? one.value : Number.NaN));
+      return numbers.some((one) => Number.isNaN(one)) ? null : numbers;
+    }
+  }
+}

package/src/core/engine/alerts.ts

@@ -0,0 +1,152 @@
+/**
+ * The watched conditions, and the two rules that decide whether one fires.
+ *
+ * `outputs.alerts` is a declaration: a boolean channel, a message channel and a
+ * frequency (`compiled-program.md` 2.8). Turning that into an alert somebody is
+ * woken by is the engine's, because both rules that gate it are facts the
+ * engine holds and a host asked to apply them would be applying them
+ * differently in every host.
+ *
+ * **A confirmed bar, first.** The condition channel is declared `defer`, so it
+ * is applied at step 9 and only on a bar the engine decided (5.4). A condition
+ * that was true halfway through a bar and false when it closed never fires,
+ * which is the whole of what makes an alert worth acting on.
+ *
+ * **A bar the host is driving live, second.** `stdlib.md` 16.2: adding a study
+ * to a chart that already holds history fires nothing for those bars. The fact
+ * that separates the two is `bar.isRealtime`, which the host states and no
+ * engine can derive (`host-interface.md` 6.1 and 6.4): a history load states it
+ * false for every bar, and a live feed states it true for the bar it is
+ * driving. So the rule is one test against a fact somebody already had to
+ * state, rather than a watermark this would have to keep and get wrong after a
+ * recompute. An engine that only backtests states it false throughout and fires
+ * nothing, which is the same answer from the other direction.
+ *
+ * Neither rule is rolled back. A moving bar re-executes and its deferred
+ * channels are discarded each time, so nothing fires until the bar is decided;
+ * once one has fired, it has been sent, and no rollback unsends it. That is why
+ * `once` and `oncePerBar` are counted here rather than restored with the rest
+ * of the state.
+ */
+import { fieldValue } from './inputs.js';
+import type { ResolvedInput } from './inputs.js';
+import type { Alert, CompiledProgram, Field } from './types.js';
+import type { Value } from './values/index.js';
+
+/** One alert the engine raised, for the host to deliver. */
+export interface AlertFiring {
+  /** The entry's stable name: the script's `id`, or one derived from the line. */
+  readonly key: string;
+  readonly title: string;
+  /** The message, evaluated on the bar that fired, or absent where it was. */
+  readonly message: Value;
+  readonly bar: number;
+  /** The bar's open time in milliseconds, or null when the host stated none. */
+  readonly time: number | null;
+}
+
+/** What one execution of a bar offers the watch. */
+export interface AlertBar {
+  readonly index: number;
+  readonly time: number | null;
+  readonly isRealtime: boolean;
+}
+
+/** The three of `stdlib.md` 16.2, with the default first. */
+const ONCE_PER_BAR = 'oncePerBar';
+const ONCE = 'once';
+
+/**
+ * The watch for one program, with its declaration fields resolved.
+ *
+ * A title and a frequency are declaration fields, which a script may write with
+ * an `input()`, and inputs are resolved once at load. So they are read here,
+ * before bar 0, rather than per bar, as every other declaration the descriptor
+ * is built from is.
+ *
+ * A field that holds no string at all is a program whose field was lost or hand
+ * edited, and the frequency it falls back to is the safest of the three: at most
+ * one alert for a bar.
+ */
+export function alertsFor(
+  program: CompiledProgram,
+  inputs: readonly ResolvedInput[],
+): Alerts {
+  const text = (field: Field, fallback: string): string => {
+    const value = fieldValue(field, inputs);
+    return typeof value === 'string' ? value : fallback;
+  };
+  return new Alerts(
+    program.outputs.alerts,
+    program.outputs.alerts.map((one) => ({
+      title: text(one.title, ''),
+      frequency: text(one.frequency, ONCE_PER_BAR),
+    })),
+  );
+}
+
+/** One entry's declaration fields, resolved against the settings at load. */
+export interface AlertFields {
+  readonly title: string;
+  readonly frequency: string;
+}
+
+export class Alerts {
+  private readonly declared: readonly Alert[];
+  private readonly resolved: readonly AlertFields[];
+  /** The last bar each entry fired on, by declaration order. */
+  private readonly lastBar: number[];
+  private readonly everFired: boolean[];
+
+  constructor(declared: readonly Alert[], resolved: readonly AlertFields[]) {
+    this.declared = declared;
+    this.resolved = resolved;
+    this.lastBar = declared.map(() => -1);
+    this.everFired = declared.map(() => false);
+  }
+
+  /**
+   * Step 9 on a bar the engine decided: the alerts it raises, in order.
+   *
+   * `read` is the channel's published value for this bar. A condition that is
+   * absent is not true, which is `language.md` 6.6's three-valued logic reaching
+   * a surface: an alert under a guard that was absent during warmup does not
+   * fire, and that is the most common reason a new alert looks dead.
+   */
+  raise(bar: AlertBar, read: (channel: number) => Value): readonly AlertFiring[] {
+    if (this.declared.length === 0 || !bar.isRealtime) return [];
+    const out: AlertFiring[] = [];
+    for (let index = 0; index < this.declared.length; index += 1) {
+      const entry = this.declared[index];
+      const fields = this.resolved[index];
+      if (entry === undefined || fields === undefined) continue;
+      if (read(entry.condChannel) !== true) continue;
+      if (!this.allowed(index, bar.index, fields.frequency)) continue;
+      this.lastBar[index] = bar.index;
+      this.everFired[index] = true;
+      out.push({
+        key: entry.key,
+        title: fields.title,
+        message: entry.messageChannel === null ? null : read(entry.messageChannel),
+        bar: bar.index,
+        time: bar.time,
+      });
+    }
+    return out;
+  }
+
+  /**
+   * The frequency rule, which nothing else in the program implies.
+   *
+   * Two engines that guessed would fire different numbers of alerts from one
+   * program, so the compiler writes the effective value and this reads it.
+   * `everyUpdate` is the one that needs no test here: it fires on every decided
+   * execution of the bar, which is why it needs `meta.onUnconfirmed` true to
+   * mean anything and is OS3009 without it.
+   */
+  private allowed(index: number, bar: number, frequency: string): boolean {
+    if (frequency === ONCE) return this.everFired[index] !== true;
+    if (frequency === ONCE_PER_BAR) return this.lastBar[index] !== bar;
+    return true;
+  }
+}

package/src/core/engine/arithmetic.ts

@@ -0,0 +1,165 @@
+/**
+ * The operator instructions, `compiled-program.md` 4.5 to 4.7.
+ *
+ * Five rules live in this file and nowhere else, which is section 7's claim
+ * about the whole language: absence propagates through arithmetic and ordering
+ * comparison, is total under equality, is three-valued under `and`, `or` and
+ * `not`, and is false at a branch. The last one is `JUMP_FALSE` and is in the
+ * machine; the other four are here. An engine that gets all five right has the
+ * whole of `language.md` section 6, and an engine that special cases absence
+ * anywhere else has a bug.
+ *
+ * Two details that look like nothing and are not:
+ *
+ * **Finiteness is checked after each individual operation**, not at the end of
+ * an expression, so `(1e308 * 10) / 10` is absent rather than `1e307`. Checking
+ * per expression would make the answer depend on where an engine happened to
+ * round, which is the whole failure this project exists to prevent.
+ *
+ * **`MOD` is truncated division and the library's `mod` is floored.** They are
+ * different functions with the same name in two places on purpose: the operator
+ * follows the sign of its left operand, which is what every language's `%`
+ * does, and the library call follows the sign of its right operand, which is
+ * what a script wants when it wraps an index. Collapsing them would silently
+ * change one of the two.
+ */
+import type { Value } from './values/index.js';
+import { ABSENT, numberValue, valuesEqual } from './values/index.js';
+
+/** Whether a corrupt program reached an operator with tags it cannot take. */
+export class OperandMismatch extends Error {
+  readonly opcode: string;
+
+  constructor(opcode: string) {
+    super(opcode);
+    this.name = 'OperandMismatch';
+    this.opcode = opcode;
+  }
+}
+
+/**
+ * `ADD`: the sum of two numbers, or the concatenation of two strings.
+ *
+ * The only instruction that reads two tags. Any other combination is a program
+ * the checker should have rejected, and an engine treats it as corrupt rather
+ * than inventing a conversion: `language.md` 5.3 has no coercion anywhere, and
+ * an engine that grows one here becomes the only engine that runs that script.
+ */
+export function add(a: Value, b: Value): Value {
+  if (a === null || b === null) return ABSENT;
+  if (typeof a === 'number' && typeof b === 'number') return numberValue(a + b);
+  if (typeof a === 'string' && typeof b === 'string') return a + b;
+  throw new OperandMismatch('ADD');
+}
+
+export function subtract(a: Value, b: Value): Value {
+  return numeric('SUB', a, b, (x, y) => x - y);
+}
+
+export function multiply(a: Value, b: Value): Value {
+  return numeric('MUL', a, b, (x, y) => x * y);
+}
+
+/** `DIV`: absent when the divisor is zero, including `0 / 0`. */
+export function divide(a: Value, b: Value): Value {
+  if (a === null || b === null) return ABSENT;
+  if (typeof a !== 'number' || typeof b !== 'number') throw new OperandMismatch('DIV');
+  return b === 0 ? ABSENT : numberValue(a / b);
+}
+
+/** `MOD`: the remainder of truncated division, sign following the left operand. */
+export function remainder(a: Value, b: Value): Value {
+  if (a === null || b === null) return ABSENT;
+  if (typeof a !== 'number' || typeof b !== 'number') throw new OperandMismatch('MOD');
+  return b === 0 ? ABSENT : numberValue(a % b);
+}
+
+export function negate(a: Value): Value {
+  if (a === null) return ABSENT;
+  if (typeof a !== 'number') throw new OperandMismatch('NEG');
+  return numberValue(-a);
+}
+
+function numeric(
+  opcode: string,
+  a: Value,
+  b: Value,
+  of: (x: number, y: number) => number,
+): Value {
+  if (a === null || b === null) return ABSENT;
+  if (typeof a !== 'number' || typeof b !== 'number') throw new OperandMismatch(opcode);
+  return numberValue(of(a, b));
+}
+
+/**
+ * The four ordering comparisons, which **propagate absence**.
+ *
+ * An absent operand gives absence rather than `false` (`language.md` 6.4).
+ * Together with `EQ` being total, this is the one place in the language where
+ * absence is treated two ways, and it is deliberate: an operator that can
+ * itself be absent gives a script no way to ask whether a value is absent at
+ * all, so equality is the exception and every other comparison is not.
+ */
+export function compare(opcode: 'LT' | 'LE' | 'GT' | 'GE', a: Value, b: Value): Value {
+  if (a === null || b === null) return ABSENT;
+  const bothNumbers = typeof a === 'number' && typeof b === 'number';
+  const bothStrings = typeof a === 'string' && typeof b === 'string';
+  if (!bothNumbers && !bothStrings) throw new OperandMismatch(opcode);
+  switch (opcode) {
+    case 'LT':
+      return a < b;
+    case 'LE':
+      return a <= b;
+    case 'GT':
+      return a > b;
+    default:
+      return a >= b;
+  }
+}
+
+/** `EQ` and `NE` are total: they always produce a boolean. */
+export function equals(a: Value, b: Value): boolean {
+  return valuesEqual(a, b);
+}
+
+/** `NOT`: true becomes false, false becomes true, absent stays absent. */
+export function not(a: Value): Value {
+  if (a === null) return ABSENT;
+  if (typeof a !== 'boolean') throw new OperandMismatch('NOT');
+  return !a;
+}
+
+/**
+ * `AND`, the three-valued conjunction of `language.md` 6.6.
+ *
+ * The table holds only the cases the short circuit leaves to it: `AND_SHORT`
+ * has already decided a `false` left operand. A `false` on the right fixes the
+ * answer whatever an absent left operand would have held, which is what makes
+ * the operator commutative.
+ */
+export function and(a: Value, b: Value): Value {
+  if (a === false || b === false) return false;
+  if (a === null || b === null) return ABSENT;
+  if (typeof a !== 'boolean' || typeof b !== 'boolean') throw new OperandMismatch('AND');
+  return a && b;
+}
+
+/** `OR`, the disjunction beside it. A `true` on either side fixes the answer. */
+export function or(a: Value, b: Value): Value {
+  if (a === true || b === true) return true;
+  if (a === null || b === null) return ABSENT;
+  if (typeof a !== 'boolean' || typeof b !== 'boolean') throw new OperandMismatch('OR');
+  return a || b;
+}
+
+/**
+ * Whether a branch is taken, which is the fifth rule.
+ *
+ * `JUMP_FALSE` treats absence as false. This is the one place absence is
+ * absorbed rather than propagated, and it is unavoidable: execution has to go
+ * somewhere. It serves `if`, `else if`, `while`, the ternary and a `switch`
+ * condition arm, so the rule is written once in one instruction.
+ */
+export function isFalsey(value: Value): boolean {
+  return value === false || value === null;
+}