openalgo-script 0.5.0 → 0.6.0

package/src/core/importer/calls.ts

@@ -0,0 +1,274 @@
+/**
+ * Calls, written out as OpenScript text.
+ *
+ * A call to a function the script declares keeps its arguments, with a named
+ * argument's label following the parameter's new spelling where it was renamed.
+ * A call to a built-in is translated from its row in the table, one argument to
+ * one argument where they line up, and by a translator of its own where they do
+ * not: the highest and lowest of a window that default their source, a
+ * deviation whose `biased` flag is the negation of OpenScript's `sample`, a
+ * true range whose absent first bar is a flag, and the handful of conversions
+ * that are an expression rather than a call in OpenScript.
+ *
+ * A call that draws or trades is a statement, not a value, and its translator
+ * lives with the other statements; used as a value it is refused.
+ */
+import { diagnosticFor } from '../diagnostics/index.js';
+import { canonicalNumber } from '../emit/index.js';
+import type { Context } from './context.js';
+import type { Binding } from './names.js';
+import { levelCall, plotCall, translateInput } from './outputs.js';
+import { neverAbsent } from './presence.js';
+import { pathOf } from './syntax.js';
+import type { Arg, CallExpr, Place } from './syntax.js';
+import { CALLS } from './table.js';
+import type { Mapping } from './table.js';
+import { NOTHING, PREC, atom, translate, wrap } from './values.js';
+import type { Out } from './values.js';
+
+/** A call's arguments against a parameter list: by name, and what fitted none. */
+export interface Bound {
+  readonly byName: ReadonlyMap<string, Arg>;
+  /** Arguments past the positional list, named by their position. */
+  readonly stray: readonly { readonly arg: Arg; readonly name: string }[];
+}
+
+export function bind(call: CallExpr, positional: readonly string[]): Bound {
+  const byName = new Map<string, Arg>();
+  const stray: { arg: Arg; name: string }[] = [];
+  let position = 0;
+  for (const arg of call.args) {
+    if (arg.label !== undefined) {
+      byName.set(arg.label, arg);
+      continue;
+    }
+    const name = positional[position];
+    if (name === undefined) stray.push({ arg, name: `argument ${canonicalNumber(position + 1)}` });
+    else byName.set(name, arg);
+    position += 1;
+  }
+  return { byName, stray };
+}
+
+/**
+ * Refuses the first argument that is not one of `known`, with OS9006. Returns
+ * whether the call may go on.
+ */
+export function onlyKnown(ctx: Context, path: string, bound: Bound, known: readonly string[]): boolean {
+  const first = bound.stray[0];
+  if (first !== undefined) {
+    ctx.refuse(diagnosticFor('OS9006', ctx.span(first.arg.at), { argument: first.name, call: path }));
+    return false;
+  }
+  for (const [name, arg] of bound.byName) {
+    if (known.includes(name)) continue;
+    ctx.refuse(diagnosticFor('OS9006', ctx.span(arg.at), { argument: name, call: path }));
+    return false;
+  }
+  return true;
+}
+
+/** OS9007, once per built-in: its first bars follow OpenScript's own rules. */
+export function warmupNote(ctx: Context, at: Place, call: string, target: string): void {
+  ctx.note(diagnosticFor('OS9007', ctx.span(at), { call, target }), `OS9007 ${call}`);
+}
+
+/** The translated text of one argument, or undefined where the call left it out. */
+export function argText(ctx: Context, bound: Bound, name: string): string | undefined {
+  const arg = bound.byName.get(name);
+  return arg === undefined ? undefined : translate(ctx, arg.value).text;
+}
+
+/** Arguments by position up to the first one left out, and by name after it. */
+function written(texts: readonly (string | undefined)[], labels: readonly string[]): string[] | undefined {
+  const parts: string[] = [];
+  let gap = false;
+  for (let i = 0; i < texts.length; i += 1) {
+    const text = texts[i];
+    if (text === undefined) {
+      gap = true;
+      continue;
+    }
+    if (!gap) parts.push(text);
+    else {
+      const label = labels[i];
+      if (label === undefined) return undefined;
+      parts.push(`${label} = ${text}`);
+    }
+  }
+  return parts;
+}
+
+/** A row whose arguments line up one to one, which is most of the table. */
+export function generic(ctx: Context, call: CallExpr, row: Mapping, path: string): Out {
+  const bound = bind(call, row.params);
+  if (!onlyKnown(ctx, path, bound, row.params)) return NOTHING;
+  const parts = written(row.params.map((name) => argText(ctx, bound, name)), row.targets);
+  if (parts === undefined) {
+    ctx.refuse(diagnosticFor('OS9006', ctx.span(call.at), { argument: 'an argument left out before another', call: path }));
+    return NOTHING;
+  }
+  if (row.difference === 'warmup') warmupNote(ctx, call.callee.at, path, row.target);
+  return atom(`${row.target}(${parts.join(', ')})`);
+}
+
+function userCall(ctx: Context, call: CallExpr, binding: Binding): Out {
+  const parts = call.args.map((arg) => {
+    const text = translate(ctx, arg.value).text;
+    if (arg.label === undefined) return text;
+    return `${binding.labels?.get(arg.label) ?? arg.label} = ${text}`;
+  });
+  return atom(`${binding.output}(${parts.join(', ')})`);
+}
+
+/** `ta.tr` read as a value, which is the call with `handle_na` false. */
+export function trueRangeValue(): Out {
+  return { text: 'isNone(close[1]) ? none : trueRange()', prec: PREC.ternary };
+}
+
+function trueRangeCall(ctx: Context, call: CallExpr, path: string): Out {
+  const bound = bind(call, ['handle_na']);
+  if (!onlyKnown(ctx, path, bound, ['handle_na'])) return NOTHING;
+  const flag = bound.byName.get('handle_na')?.value;
+  if (flag === undefined || (flag.kind === 'bool' && !flag.value)) return trueRangeValue();
+  if (flag.kind === 'bool') return atom('trueRange()');
+  const handled = translate(ctx, flag);
+  return { text: `${wrap(handled, PREC.or)} or not isNone(close[1]) ? trueRange() : none`, prec: PREC.ternary };
+}
+
+function extreme(ctx: Context, call: CallExpr, row: Mapping, path: string): Out {
+  const one = call.args.length === 1 && call.args[0]?.label === undefined;
+  const bound = bind(call, one ? ['length'] : ['source', 'length']);
+  if (!onlyKnown(ctx, path, bound, ['source', 'length'])) return NOTHING;
+  const source = argText(ctx, bound, 'source') ?? (row.target === 'highest' ? 'high' : 'low');
+  const length = argText(ctx, bound, 'length');
+  if (length === undefined) {
+    ctx.refuse(diagnosticFor('OS9006', ctx.span(call.at), { argument: 'length', call: path }));
+    return NOTHING;
+  }
+  warmupNote(ctx, call.callee.at, path, row.target);
+  return atom(`${row.target}(${source}, ${length})`);
+}
+
+function deviation(ctx: Context, call: CallExpr, row: Mapping, path: string): Out {
+  const bound = bind(call, row.params);
+  if (!onlyKnown(ctx, path, bound, row.params)) return NOTHING;
+  const source = argText(ctx, bound, 'source');
+  const length = argText(ctx, bound, 'length');
+  if (source === undefined || length === undefined) {
+    ctx.refuse(diagnosticFor('OS9006', ctx.span(call.at), { argument: source === undefined ? 'source' : 'length', call: path }));
+    return NOTHING;
+  }
+  const biased = bound.byName.get('biased')?.value;
+  let sample = '';
+  if (biased !== undefined && !(biased.kind === 'bool' && biased.value)) {
+    sample = biased.kind === 'bool' ? ', sample = true' : `, sample = not ${wrap(translate(ctx, biased), PREC.unary)}`;
+  }
+  warmupNote(ctx, call.callee.at, path, row.target);
+  return atom(`${row.target}(${source}, ${length}${sample})`);
+}
+
+/** A condition handed to a counting built-in, which the source dialect never sees absent. */
+function condition(ctx: Context, call: CallExpr, row: Mapping, path: string): Out {
+  const bound = bind(call, row.params);
+  if (!onlyKnown(ctx, path, bound, row.params)) return NOTHING;
+  const texts = row.params.map((name) => {
+    const arg = bound.byName.get(name);
+    if (arg === undefined) return undefined;
+    const text = translate(ctx, arg.value).text;
+    return name === 'condition' && !neverAbsent(ctx, arg.value) ? `orElse(${text}, false)` : text;
+  });
+  const parts = written(texts, row.targets);
+  if (parts === undefined || texts[0] === undefined) {
+    ctx.refuse(diagnosticFor('OS9006', ctx.span(call.at), { argument: 'condition', call: path }));
+    return NOTHING;
+  }
+  warmupNote(ctx, call.callee.at, path, row.target);
+  return atom(`${row.target}(${parts.join(', ')})`);
+}
+
+/** `math.max` and `math.min` take any number of arguments; OpenScript's take two. */
+function extremes(ctx: Context, call: CallExpr, row: Mapping, path: string): Out {
+  const labelled = call.args.find((arg) => arg.label !== undefined);
+  if (labelled !== undefined || call.args.length < 2) {
+    const at = labelled?.at ?? call.at;
+    ctx.refuse(diagnosticFor('OS9006', ctx.span(at), { argument: labelled?.label ?? 'a single argument', call: path }));
+    return NOTHING;
+  }
+  const texts = call.args.map((arg) => translate(ctx, arg.value).text);
+  let text = texts[0] ?? '';
+  for (const next of texts.slice(1)) text = `${row.target}(${text}, ${next})`;
+  return atom(text);
+}
+
+function fallback(ctx: Context, call: CallExpr, row: Mapping, path: string): Out {
+  const bound = bind(call, row.params);
+  if (!onlyKnown(ctx, path, bound, row.params)) return NOTHING;
+  const source = argText(ctx, bound, 'source');
+  if (source === undefined) {
+    ctx.refuse(diagnosticFor('OS9006', ctx.span(call.at), { argument: 'source', call: path }));
+    return NOTHING;
+  }
+  return atom(`orElse(${source}, ${argText(ctx, bound, 'replacement') ?? '0'})`);
+}
+
+function rgb(ctx: Context, call: CallExpr, row: Mapping, path: string): Out {
+  const bound = bind(call, row.params);
+  if (!onlyKnown(ctx, path, bound, row.params)) return NOTHING;
+  const channels = ['red', 'green', 'blue'].map((name) => argText(ctx, bound, name));
+  if (channels.some((one) => one === undefined)) {
+    ctx.refuse(diagnosticFor('OS9006', ctx.span(call.at), { argument: 'a colour channel', call: path }));
+    return NOTHING;
+  }
+  const colour = `rgb(${channels.join(', ')})`;
+  const transp = argText(ctx, bound, 'transp');
+  return atom(transp === undefined ? colour : `fade(${colour}, ${transp})`);
+}
+
+export function translateCall(ctx: Context, call: CallExpr): Out {
+  const path = pathOf(call.callee);
+  const root = path?.split('.')[0];
+  const binding = root === undefined ? undefined : ctx.lookup(root, call.callee.at);
+  if (path === undefined || (binding !== undefined && (path !== root || binding.kind !== 'function'))) {
+    ctx.refuse(diagnosticFor('OS9002', ctx.span(call.callee.at), { construct: 'a call on a value' }));
+    return NOTHING;
+  }
+  if (binding !== undefined) return userCall(ctx, call, binding);
+  const row = CALLS.get(path);
+  if (row === undefined) {
+    ctx.refuse(diagnosticFor('OS9003', ctx.span(call.callee.at), { name: path }));
+    return NOTHING;
+  }
+  switch (row.special) {
+    case undefined:
+      return generic(ctx, call, row, path);
+    case 'trueRange':
+      return trueRangeCall(ctx, call, path);
+    case 'extreme':
+      return extreme(ctx, call, row, path);
+    case 'deviation':
+      return deviation(ctx, call, row, path);
+    case 'condition':
+      return condition(ctx, call, row, path);
+    case 'extremes':
+      return extremes(ctx, call, row, path);
+    case 'fallback':
+      return fallback(ctx, call, row, path);
+    case 'rgb':
+      return rgb(ctx, call, row, path);
+    case 'float': {
+      const bound = bind(call, row.params);
+      if (!onlyKnown(ctx, path, bound, row.params)) return NOTHING;
+      const arg = bound.byName.get('x');
+      return arg === undefined ? atom('none') : atom(`(${translate(ctx, arg.value).text})`);
+    }
+    case 'input':
+      return translateInput(ctx, call, path, false);
+    case 'plot':
+      return plotCall(ctx, call, path);
+    case 'hline':
+      return levelCall(ctx, call, path);
+  }
+  ctx.refuse(diagnosticFor('OS9002', ctx.span(call.callee.at), { construct: `${path} used as a value` }));
+  return NOTHING;
+}

package/src/core/importer/context.ts

@@ -0,0 +1,197 @@
+/**
+ * What the translators share while they work through one script.
+ *
+ * A translation is kept or refused per top level statement, never per line
+ * inside one: a block with one line missing is a block that means something
+ * the original did not, so the unit that is kept as a comment is the whole
+ * statement at the top level. `Node` is that unit, and everything a refusal or
+ * a warning needs to point at is recorded against it rather than decided on the
+ * spot, because a statement translated now can still be refused later: by the
+ * compiler, or because an earlier statement it reads was refused.
+ */
+import type { Diagnostic } from '../diagnostics/index.js';
+import { canonicalNumber } from '../emit/index.js';
+import type { SourceFile } from '../source/index.js';
+import type { Span } from '../span/index.js';
+import { Namer, Scope } from './names.js';
+import type { Binding } from './names.js';
+import type { Expr, Lines, Named, Place, Stmt } from './syntax.js';
+
+export interface OutLine {
+  readonly depth: number;
+  readonly text: string;
+}
+
+/** A finding on a statement that is kept, and the key that makes it once per script where it is once per built-in. */
+export interface Note {
+  readonly diagnostic: Diagnostic;
+  readonly once: string | undefined;
+}
+
+export interface Node {
+  readonly stmt: Stmt;
+  readonly lines: Lines;
+  /** Top level names the statement declares, so what reads them can follow it. */
+  readonly declares: readonly Named[];
+  /** Top level names it reads, in source order, with where. */
+  readonly reads: Named[];
+  output: OutLine[];
+  /** Why its translation was refused, if it was. */
+  refusal: Diagnostic | undefined;
+  /** Why the compiler refused the translation, if it did. */
+  failed: Diagnostic | undefined;
+  /** Why it reads a name a refused statement declared, recomputed on every pass. */
+  lost: Diagnostic | undefined;
+  readonly notes: Note[];
+  /** The declaration, which is placed first and is never kept as a comment. */
+  readonly declaration: boolean;
+}
+
+export function isKept(node: Node): boolean {
+  return node.refusal === undefined && node.failed === undefined && node.lost === undefined;
+}
+
+/** The first reason a node is not kept, in the order the reasons are found. */
+export function reasonOf(node: Node): Diagnostic | undefined {
+  return node.refusal ?? node.failed ?? node.lost;
+}
+
+export type Version = 5 | 6;
+
+export interface Reassignment {
+  readonly op: string;
+  readonly value: Expr;
+}
+
+/** Everything about the script the translators need before they start. */
+export interface Facts {
+  readonly file: SourceFile;
+  readonly version: Version;
+  /** Every identifier the source writes. */
+  readonly used: ReadonlySet<string>;
+  /**
+   * Every reassignment the source makes, by name, anywhere in the file. A name
+   * with any is never a constant, and is present only if every value it is
+   * given is.
+   */
+  readonly reassigned: ReadonlyMap<string, readonly Reassignment[]>;
+  /**
+   * Every name the file declares at the top level, wherever. OpenScript lets a
+   * block or a function see one declared below it, so an inner declaration of
+   * the same name is renamed, which the source dialect's meaning allows.
+   */
+  readonly globals: ReadonlySet<string>;
+  /** The side each literal entry id opens, from the script's entry calls. */
+  readonly entries: ReadonlyMap<string, 'long' | 'short'>;
+}
+
+export class Context {
+  readonly namer: Namer;
+  readonly fileScope = new Scope(undefined);
+  scope: Scope = this.fileScope;
+  /** The statement being translated. */
+  node: Node | undefined;
+  /** Lines a statement needs evaluated before it, and whether it may have them. */
+  hoisted: OutLine[] = [];
+  mayHoist = false;
+  /** Inside a ternary arm, where the source dialect evaluates lazily as OpenScript does. */
+  lazy = 0;
+  depth = 0;
+  /** The declaration's pyramiding, read as the source dialect reads it: 0 is 1. */
+  pyramiding = 1;
+  /**
+   * Whether the declaration sizes orders in units. The source dialect counts a
+   * quantity written on an entry in contracts whatever the declaration says,
+   * and OpenScript counts it in the declaration's own unit.
+   */
+  qtyInUnits = true;
+  readonly titles = new Map<string, Set<string>>();
+  readonly facts: Facts;
+
+  constructor(facts: Facts) {
+    this.facts = facts;
+    this.namer = new Namer(facts.used);
+  }
+
+  span(at: Place): Span {
+    return this.facts.file.spanAt(at.offset, at.length);
+  }
+
+  /** Records the first reason the current statement cannot be translated. */
+  refuse(diagnostic: Diagnostic): void {
+    if (this.node !== undefined && this.node.refusal === undefined) this.node.refusal = diagnostic;
+  }
+
+  get refused(): boolean {
+    return this.node?.refusal !== undefined;
+  }
+
+  note(diagnostic: Diagnostic, once?: string): void {
+    this.node?.notes.push({ diagnostic, once });
+  }
+
+  /** Whether declaring `name` in the current scope needs a new spelling to keep it apart. */
+  hides(name: string): boolean {
+    return this.scope.find(name) !== undefined || (!this.scope.isGlobal && this.facts.globals.has(name));
+  }
+
+  /** The binding a source name has here, recording a read of a top level one. */
+  lookup(name: string, at: Place): Binding | undefined {
+    const found = this.scope.find(name);
+    if (found !== undefined && found.topLevel) this.node?.reads.push({ name, at });
+    return found;
+  }
+
+  /** Enters a block scope for the length of `work`. */
+  within<T>(work: () => T): T {
+    const outer = this.scope;
+    this.scope = new Scope(outer);
+    try {
+      return work();
+    } finally {
+      this.scope = outer;
+    }
+  }
+
+  /**
+   * Moves an expression to its own line before the current statement, and
+   * returns the name it is read under, or undefined where it cannot be moved.
+   */
+  hoist(text: string): string | undefined {
+    if (!this.mayHoist || this.lazy > 0) return undefined;
+    const name = this.namer.fresh('everyBar');
+    this.hoisted.push({ depth: this.depth, text: `${name} = ${text}` });
+    return name;
+  }
+
+  /** A title for a declared output that no other output of its kind has. */
+  title(kind: string, wanted: string): string {
+    let seen = this.titles.get(kind);
+    if (seen === undefined) {
+      seen = new Set();
+      this.titles.set(kind, seen);
+    }
+    let title = wanted;
+    for (let n = 2; seen.has(title); n += 1) title = `${wanted} ${canonicalNumber(n)}`;
+    seen.add(title);
+    return title;
+  }
+}
+
+const HEX = '0123456789abcdef';
+
+/** A string literal in OpenScript's spelling of it (`language.md` 3.6). */
+export function quoted(value: string): string {
+  let out = '"';
+  for (const c of value) {
+    const code = c.codePointAt(0) ?? 0;
+    if (c === '"') out += '\\"';
+    else if (c === '\\') out += '\\\\';
+    else if (c === '\n') out += '\\n';
+    else if (c === '\t') out += '\\t';
+    else if (c === '\r') out += '\\r';
+    else if (code < 0x20) out += `\\u00${HEX[code >> 4] ?? '0'}${HEX[code & 15] ?? '0'}`;
+    else out += c;
+  }
+  return `${out}"`;
+}