openalgo-script 0.5.0 → 0.7.0

package/src/core/importer/expressions.ts

@@ -0,0 +1,247 @@
+/**
+ * Expressions in the source dialect, read by recursive descent.
+ *
+ * The precedence ladder is the source dialect's, and it is the same shape as
+ * OpenScript's (`language.md` 9.1): the ternary lowest, then `or`, `and`,
+ * equality, comparison, the additive and multiplicative operators, and the
+ * unary operators with `not` among them. So a tree read here prints back into
+ * OpenScript with parentheses only where the tree needs them, and never with a
+ * different grouping.
+ *
+ * What the reader does not accept it reports by throwing `Unreadable` with the
+ * place and a few words naming the form, and the statement reader turns that
+ * into a statement kept whole. It is the one exception in the importer, and it
+ * never leaves this module and the statement reader beside it.
+ */
+import type { Token } from './lexer.js';
+import { joined } from './syntax.js';
+import type { Arg, Expr, Place } from './syntax.js';
+
+/** A form the reader does not accept, and where it starts. */
+export class Unreadable extends Error {
+  readonly at: Place;
+  readonly construct: string;
+
+  constructor(at: Place, construct: string) {
+    super(construct);
+    this.at = at;
+    this.construct = construct;
+  }
+}
+
+/** Words that open a statement form and are never a value. */
+const STATEMENT_WORDS: Readonly<Record<string, string>> = {
+  if: 'an if used as a value',
+  switch: 'a switch used as a value',
+  for: 'a for loop used as a value',
+  while: 'a while loop used as a value',
+};
+
+/** The words the reader takes for a form it does not read, per bad token. */
+export function badConstruct(token: Token): string {
+  if (token.text.startsWith('"') || token.text.startsWith("'")) return 'a string that is never closed';
+  if (token.text.startsWith('#')) return `the colour literal ${token.text}`;
+  return `the character ${token.text}`;
+}
+
+export const UNREAD = 'a statement in a form its reader does not accept';
+
+export class Cursor {
+  index = 0;
+  readonly tokens: readonly Token[];
+
+  constructor(tokens: readonly Token[]) {
+    this.tokens = tokens;
+  }
+
+  peek(ahead = 0): Token | undefined {
+    return this.tokens[this.index + ahead];
+  }
+
+  /** Whether the next token is this operator or word. */
+  sees(text: string, ahead = 0): boolean {
+    const token = this.peek(ahead);
+    return token !== undefined && (token.kind === 'op' || token.kind === 'name') && token.text === text;
+  }
+
+  done(): boolean {
+    return this.index >= this.tokens.length;
+  }
+
+  take(): Token {
+    const token = this.tokens[this.index];
+    if (token === undefined) throw new Unreadable(this.endPlace(), UNREAD);
+    this.index += 1;
+    return token;
+  }
+
+  expect(text: string): Token {
+    if (!this.sees(text)) this.fail();
+    return this.take();
+  }
+
+  /** Refuse at the next token, or at the end of the line when there is none. */
+  fail(): never {
+    const token = this.peek();
+    if (token === undefined) throw new Unreadable(this.endPlace(), UNREAD);
+    if (token.kind === 'bad') throw new Unreadable(placeOf(token), badConstruct(token));
+    throw new Unreadable(placeOf(token), UNREAD);
+  }
+
+  /** Zero width, just after the last token. */
+  endPlace(): Place {
+    const last = this.tokens[this.tokens.length - 1];
+    return last === undefined ? { offset: 0, length: 0 } : { offset: last.offset + last.length, length: 0 };
+  }
+}
+
+export function placeOf(token: Token): Place {
+  return { offset: token.offset, length: token.length };
+}
+
+const COMPARISON = new Set(['<', '<=', '>', '>=']);
+const EQUALITY = new Set(['==', '!=']);
+const ADDITIVE = new Set(['+', '-']);
+const MULTIPLICATIVE = new Set(['*', '/', '%']);
+
+type Level = (c: Cursor) => Expr;
+
+/** One left associative level of binary operators. */
+function binaryLevel(operators: ReadonlySet<string>, next: Level, words = false): Level {
+  return (c) => {
+    let left = next(c);
+    for (;;) {
+      const token = c.peek();
+      if (token === undefined || !operators.has(token.text)) return left;
+      if (words ? token.kind !== 'name' : token.kind !== 'op') return left;
+      c.take();
+      const right = next(c);
+      left = { kind: 'binary', op: token.text, left, right, at: joined(left.at, right.at), opAt: placeOf(token) };
+    }
+  };
+}
+
+export function expression(c: Cursor): Expr {
+  return ternary(c);
+}
+
+function ternary(c: Cursor): Expr {
+  const condition = orLevel(c);
+  if (!c.sees('?')) return condition;
+  c.take();
+  const then = ternary(c);
+  c.expect(':');
+  const otherwise = ternary(c);
+  return { kind: 'ternary', condition, then, otherwise, at: joined(condition.at, otherwise.at) };
+}
+
+function unary(c: Cursor): Expr {
+  const token = c.peek();
+  if (token !== undefined) {
+    const sign = token.kind === 'op' && (token.text === '-' || token.text === '+');
+    const not = token.kind === 'name' && token.text === 'not';
+    if (sign || not) {
+      c.take();
+      const operand = unary(c);
+      return { kind: 'unary', op: token.text, operand, at: joined(placeOf(token), operand.at) };
+    }
+  }
+  return postfix(c);
+}
+
+const multiplicative = binaryLevel(MULTIPLICATIVE, unary);
+const additive = binaryLevel(ADDITIVE, multiplicative);
+const comparison = binaryLevel(COMPARISON, additive);
+const equality = binaryLevel(EQUALITY, comparison);
+const andLevel = binaryLevel(new Set(['and']), equality, true);
+const orLevel = binaryLevel(new Set(['or']), andLevel, true);
+
+function argumentsOf(c: Cursor): Arg[] {
+  const args: Arg[] = [];
+  if (c.sees(')')) return args;
+  for (;;) {
+    const first = c.peek();
+    let label: string | undefined;
+    if (first !== undefined && first.kind === 'name' && c.sees('=', 1)) {
+      label = first.text;
+      c.take();
+      c.take();
+    }
+    const value = expression(c);
+    args.push({ label, value, at: first === undefined ? value.at : joined(placeOf(first), value.at) });
+    if (!c.sees(',')) return args;
+    c.take();
+  }
+}
+
+function postfix(c: Cursor): Expr {
+  let expr = primary(c);
+  for (;;) {
+    if (c.sees('(')) {
+      c.take();
+      const args = argumentsOf(c);
+      const close = c.expect(')');
+      expr = { kind: 'call', callee: expr, args, at: joined(expr.at, placeOf(close)) };
+    } else if (c.sees('[')) {
+      c.take();
+      const index = expression(c);
+      const close = c.expect(']');
+      expr = { kind: 'index', target: expr, index, at: joined(expr.at, placeOf(close)) };
+    } else if (c.sees('.')) {
+      c.take();
+      const property = c.take();
+      if (property.kind !== 'name') throw new Unreadable(placeOf(property), UNREAD);
+      expr = { kind: 'member', object: expr, property: property.text, at: joined(expr.at, placeOf(property)) };
+    } else {
+      return expr;
+    }
+  }
+}
+
+function primary(c: Cursor): Expr {
+  const token = c.peek();
+  if (token === undefined) c.fail();
+  const at = placeOf(token);
+  switch (token.kind) {
+    case 'number':
+      c.take();
+      return { kind: 'number', text: token.text, at };
+    case 'string':
+      c.take();
+      return { kind: 'string', value: token.value, at };
+    case 'color':
+      c.take();
+      return { kind: 'color', text: token.text, at };
+    case 'bad':
+      throw new Unreadable(at, badConstruct(token));
+    case 'name': {
+      const word = STATEMENT_WORDS[token.text];
+      if (word !== undefined) throw new Unreadable(at, word);
+      c.take();
+      if (token.text === 'true' || token.text === 'false') {
+        return { kind: 'bool', value: token.text === 'true', at };
+      }
+      return { kind: 'name', name: token.text, at };
+    }
+    case 'op':
+      break;
+  }
+  if (token.text === '(') {
+    c.take();
+    const inner = expression(c);
+    const close = c.expect(')');
+    return { kind: 'group', inner, at: joined(at, placeOf(close)) };
+  }
+  if (token.text === '[') {
+    c.take();
+    const items: Expr[] = [];
+    while (!c.sees(']')) {
+      items.push(expression(c));
+      if (!c.sees(',')) break;
+      c.take();
+    }
+    const close = c.expect(']');
+    return { kind: 'list', items, at: joined(at, placeOf(close)) };
+  }
+  return c.fail();
+}

package/src/core/importer/importer.ts

@@ -0,0 +1,226 @@
+/**
+ * The importer: a script in the source dialect in, OpenScript and findings out.
+ *
+ * The source dialect is the widely used chart scripting language whose scripts
+ * open with a version annotation comment, declare themselves with an
+ * `indicator` or `strategy` call and reach their built-ins through namespaces
+ * such as `ta` and `math`. Versions 5 and 6 are read.
+ *
+ * It is text to text and nothing else: no file is read, no global is touched
+ * and nothing is evaluated. What it cannot translate faithfully it does not
+ * approximate. A statement is translated whole, with the source dialect's
+ * meaning, or kept as a comment line per source line and reported; a
+ * translation whose meaning differs in a way the importer can state is written
+ * and reported with a warning. Every finding points into the imported text.
+ */
+import { diagnosticFor } from '../diagnostics/index.js';
+import type { Diagnostic } from '../diagnostics/index.js';
+import { sourceFile } from '../source/index.js';
+import type { SourceFile } from '../source/index.js';
+import { Context } from './context.js';
+import type { Node, Reassignment, Version } from './context.js';
+import { readItems } from './lexer.js';
+import type { Item, Remark } from './lexer.js';
+import { binding } from './names.js';
+import { declarationLine } from './orders.js';
+import { readScript } from './parser.js';
+import { findingsOf, settle } from './settle.js';
+import type { Piece } from './settle.js';
+import { translateStatement } from './statements.js';
+import { pathOf } from './syntax.js';
+import type { Body, CallExpr, Named, Stmt } from './syntax.js';
+
+export interface ImportResult {
+  /** The OpenScript text, or the empty string where nothing could be translated. */
+  readonly source: string;
+  /** Every finding, positioned in the imported text, in the order a reader walks it. */
+  readonly findings: readonly Diagnostic[];
+}
+
+export interface ImportOptions {
+  /** What the imported text is called, for the first line of a rendered finding. */
+  readonly name?: string;
+}
+
+const ANNOTATION = /^\s*@version\s*=\s*(\d+)\s*$/;
+
+/** The version annotation, if one comes before the first line of code. */
+function annotationOf(items: readonly Item[]): { remark: Remark; version: string } | undefined {
+  for (const item of items) {
+    if (item.kind === 'code') return undefined;
+    if (item.kind !== 'remark') continue;
+    const found = ANNOTATION.exec(item.remark.text);
+    if (found !== null) return { remark: item.remark, version: found[1] ?? '' };
+  }
+  return undefined;
+}
+
+function declaresOf(stmt: Stmt): readonly Named[] {
+  switch (stmt.kind) {
+    case 'declare':
+    case 'function':
+      return [stmt.name];
+    case 'tuple':
+      return stmt.names;
+    case 'refused':
+      return stmt.declares;
+    default:
+      return [];
+  }
+}
+
+function nodeOf(stmt: Stmt, declaration: boolean): Node {
+  return {
+    stmt,
+    lines: stmt.lines,
+    declares: declaresOf(stmt),
+    reads: [],
+    output: [],
+    refusal: undefined,
+    failed: undefined,
+    lost: undefined,
+    notes: [],
+    declaration,
+  };
+}
+
+function visit(body: Body, each: (stmt: Stmt) => void): void {
+  for (const entry of body) {
+    if (entry.kind !== 'stmt') continue;
+    const stmt = entry.stmt;
+    each(stmt);
+    if (stmt.kind === 'if') {
+      for (const branch of stmt.branches) visit(branch.body, each);
+      if (stmt.otherwise !== undefined) visit(stmt.otherwise, each);
+    } else if (stmt.kind === 'for' || stmt.kind === 'while') visit(stmt.body, each);
+    else if (stmt.kind === 'switch') for (const arm of stmt.arms) visit(arm.body, each);
+    else if (stmt.kind === 'function' && Array.isArray(stmt.body)) visit(stmt.body as Body, each);
+  }
+}
+
+/** The side each literal entry id opens, read from the script's entry calls. */
+function entrySides(body: Body): Map<string, 'long' | 'short'> {
+  const sides = new Map<string, 'long' | 'short'>();
+  visit(body, (stmt) => {
+    if (stmt.kind !== 'evaluate' || stmt.expr.kind !== 'call') return;
+    if (pathOf(stmt.expr.callee) !== 'strategy.entry') return;
+    const args = stmt.expr.args;
+    const id = args.find((arg) => arg.label === 'id') ?? args.find((arg, i) => arg.label === undefined && i === 0);
+    const side = args.find((arg) => arg.label === 'direction') ?? args.filter((arg) => arg.label === undefined)[1];
+    const direction = side === undefined ? undefined : pathOf(side.value);
+    if (id?.value.kind !== 'string') return;
+    if (direction === 'strategy.long') sides.set(id.value.value, 'long');
+    if (direction === 'strategy.short') sides.set(id.value.value, 'short');
+  });
+  return sides;
+}
+
+function reassignments(body: Body): Map<string, Reassignment[]> {
+  const found = new Map<string, Reassignment[]>();
+  visit(body, (stmt) => {
+    if (stmt.kind !== 'assign') return;
+    const held = found.get(stmt.name.name) ?? [];
+    held.push({ op: stmt.op, value: stmt.value });
+    found.set(stmt.name.name, held);
+  });
+  return found;
+}
+
+function refusal(diagnostic: Diagnostic): ImportResult {
+  return { source: '', findings: [diagnostic] };
+}
+
+/** Zero width, where the first statement starts: where a declaration was expected. */
+function firstStatement(file: SourceFile, body: Body): Diagnostic['span'] {
+  const first = body.find((entry) => entry.kind === 'stmt');
+  return first?.kind === 'stmt' ? file.spanAt(first.stmt.at.offset, 0) : file.spanAt(file.text.length, 0);
+}
+
+function declarationOf(body: Body): { stmt: Stmt; call: CallExpr; path: string } | undefined {
+  for (const entry of body) {
+    if (entry.kind !== 'stmt' || entry.stmt.kind !== 'evaluate' || entry.stmt.expr.kind !== 'call') continue;
+    const path = pathOf(entry.stmt.expr.callee);
+    if (path === 'indicator' || path === 'strategy' || path === 'library') {
+      return { stmt: entry.stmt, call: entry.stmt.expr, path };
+    }
+  }
+  return undefined;
+}
+
+export function importScript(text: string, options: ImportOptions = {}): ImportResult {
+  const file = sourceFile(options.name ?? 'imported', text);
+  const items = readItems(file);
+  const annotation = annotationOf(items);
+  if (annotation === undefined || (annotation.version !== '5' && annotation.version !== '6')) {
+    const at = annotation === undefined ? file.spanAt(0, 0) : file.spanAt(annotation.remark.offset, annotation.remark.text.length + 2);
+    const found = annotation === undefined ? 'declares no version' : `declares version ${annotation.version}`;
+    return refusal(diagnosticFor('OS9001', at, { found }));
+  }
+
+  const body = readScript(items);
+  const declaration = declarationOf(body);
+  if (declaration === undefined) return refusal(diagnosticFor('OS9004', firstStatement(file, body), { found: 'has none' }));
+  if (declaration.path === 'library') {
+    return refusal(diagnosticFor('OS9004', file.spanAt(declaration.call.callee.at.offset, declaration.call.callee.at.length), { found: 'declares a library' }));
+  }
+
+  const used = new Set<string>();
+  for (const item of items) {
+    if (item.kind !== 'code') continue;
+    for (const token of item.logical.tokens) if (token.kind === 'name') used.add(token.text);
+  }
+  const version: Version = annotation.version === '5' ? 5 : 6;
+  const globals = new Set<string>();
+  for (const entry of body) if (entry.kind === 'stmt') for (const one of declaresOf(entry.stmt)) globals.add(one.name);
+  const ctx = new Context({ file, version, used, globals, reassigned: reassignments(body), entries: entrySides(body) });
+
+  const declared = nodeOf(declaration.stmt, true);
+  ctx.node = declared;
+  const trailing = declaration.stmt.remarks.map((one) => `  //${one.text}`).join('');
+  declared.output = [{ depth: 0, text: `${declarationLine(ctx, declaration.call, declaration.path)}${trailing}` }];
+  ctx.node = undefined;
+
+  const nodes: Node[] = [declared];
+  const pieces: Piece[] = [];
+  const later: Piece[] = [];
+  let stage: 'before' | 'header' | 'body' = 'before';
+  for (const entry of body) {
+    if (entry.kind === 'remark' && entry.remark === annotation.remark) {
+      pieces.push({ kind: 'text', text: 'version 1' }, { kind: 'blank' });
+      stage = 'header';
+      continue;
+    }
+    if (entry.kind === 'stmt' && entry.stmt === declaration.stmt) {
+      pieces.push({ kind: 'node', node: declared }, ...later);
+      later.length = 0;
+      stage = 'body';
+      continue;
+    }
+    const piece: Piece | undefined =
+      entry.kind === 'remark'
+        ? { kind: 'remark', remark: entry.remark, depth: 0 }
+        : entry.kind === 'blank'
+          ? { kind: 'blank' }
+          : undefined;
+    if (piece !== undefined) {
+      pieces.push(piece);
+      continue;
+    }
+    if (entry.kind !== 'stmt') continue;
+    const node = nodeOf(entry.stmt, false);
+    ctx.node = node;
+    node.output = translateStatement(ctx, entry.stmt, 0);
+    for (const one of node.declares) {
+      if (!ctx.fileScope.names.has(one.name)) {
+        ctx.fileScope.names.set(one.name, binding(ctx.namer.declare(one.name, false), 'variable', true));
+      }
+    }
+    ctx.node = undefined;
+    nodes.push(node);
+    if (stage === 'body') pieces.push({ kind: 'node', node });
+    else later.push({ kind: 'node', node });
+  }
+
+  const source = settle(ctx, nodes, pieces);
+  return { source, findings: findingsOf(nodes) };
+}

package/src/core/importer/index.ts

@@ -0,0 +1,19 @@
+/**
+ * The importer: a script written in another chart language, as OpenScript.
+ *
+ * `importScript` reads a script in the version-annotated chart dialect, the one
+ * whose scripts open with a `//@version=` comment and reach their built-ins
+ * through namespaces, and returns the OpenScript text and a finding for every
+ * statement it kept as a comment and every translation whose meaning differs in
+ * a stated way. It is pure: text in, text and findings out, and nothing read,
+ * written or evaluated on the way.
+ *
+ * `MAPPINGS` and `COLOURS` are the table of what translates to what. They are
+ * behind this door for the documentation page's comparison test and for a tool
+ * that wants to show a reader the same table; the package surface is
+ * `importScript` and its two types.
+ */
+export { importScript } from './importer.js';
+export type { ImportOptions, ImportResult } from './importer.js';
+export { COLOURS, MAPPINGS } from './table.js';
+export type { Difference, Mapping } from './table.js';