openalgo-script 0.1.0-alpha.0

package/src/core/ast/annotations.ts

@@ -0,0 +1,68 @@
+import type { Positioned } from '../span/index.js';
+
+/**
+ * A type as a script writes it, on a parameter, a `var` or a function result.
+ *
+ * The tree keeps the words rather than a resolved type. A resolved type is the
+ * checker's, it has no source position, and it exists for expressions that were
+ * never annotated at all; an annotation is a piece of syntax with a span that a
+ * caret can land on.
+ */
+
+/** The types a value can have, language.md 5.1. */
+export const VALUE_TYPE_NAMES = ['number', 'string', 'bool', 'color'] as const;
+export type ValueTypeName = (typeof VALUE_TYPE_NAMES)[number];
+
+/**
+ * The runtime object types of language.md 5.4.
+ *
+ * These five are recognised in a type position only and are ordinary global
+ * function names everywhere else, which is why they are not reserved words. The
+ * declaration handle types `plot`, `fill` and `level` are deliberately missing:
+ * a handle can never be a `var`, a parameter, a result or an array element, so
+ * it can never be annotated.
+ */
+export const OBJECT_TYPE_NAMES = ['line', 'label', 'box', 'polyline', 'table'] as const;
+export type ObjectTypeName = (typeof OBJECT_TYPE_NAMES)[number];
+
+export function isValueTypeName(text: string): text is ValueTypeName {
+  return (VALUE_TYPE_NAMES as readonly string[]).includes(text);
+}
+
+export function isObjectTypeName(text: string): text is ObjectTypeName {
+  return (OBJECT_TYPE_NAMES as readonly string[]).includes(text);
+}
+
+/**
+ * A type written as one word.
+ *
+ * The word is an arbitrary string rather than one of the two unions above,
+ * because "that is not a type" is OS2016 and OS2016 is a check, not a parse
+ * error. A parser that could only build a legal annotation would have to report
+ * a syntax error at `len: whole`, and the reader would get a caret and no
+ * sentence naming the types that do exist.
+ */
+export interface NamedType extends Positioned {
+  readonly kind: 'namedType';
+  readonly name: string;
+}
+
+/** `series number`: one value of the element type per bar, language.md 5.2. */
+export interface SeriesType extends Positioned {
+  readonly kind: 'seriesType';
+  readonly element: TypeAnnotation;
+}
+
+/**
+ * `array<number>`, language.md 14.1.
+ *
+ * The element is any annotation and not just a legal element type, for the
+ * reason `namedType` holds any word: `array<plot>` has to reach the checker so
+ * that OS2019 can name the types an array does hold.
+ */
+export interface ArrayType extends Positioned {
+  readonly kind: 'arrayType';
+  readonly element: TypeAnnotation;
+}
+
+export type TypeAnnotation = NamedType | SeriesType | ArrayType;

package/src/core/ast/build.ts

@@ -0,0 +1,35 @@
+import type { Span } from '../span/index.js';
+import type { NodeKind, NodeOfKind } from './node.js';
+
+/** Everything a node of one kind carries beyond its kind and its span. */
+export type NodeFields<K extends NodeKind> = Omit<NodeOfKind<K>, 'kind' | 'span'>;
+
+/**
+ * Builds any node.
+ *
+ * One constructor rather than forty two, because forty two would be a second
+ * place that has to agree with the interfaces, and the day one of them drifts
+ * is the day a field goes missing from a tree that still type checks at every
+ * call site. Here the fields are the interface, minus the two parts every node
+ * has, so a missing field, a misspelt one and a stray one are each a compile
+ * error at the parser's own line.
+ *
+ * It also reads as what it builds. `makeNode('binary', span, { operator, left,
+ * right })` names its three parts, where a positional constructor of the same
+ * arity would let a parser swap two of them and compile.
+ *
+ * No field is optional. A slot a script may leave out, such as a `step` or an
+ * `else`, is `undefined` and still has to be passed, because a parser that
+ * forgets one should hear about it rather than produce a node that is missing
+ * a branch.
+ */
+export function makeNode<K extends NodeKind>(
+  kind: K,
+  span: Span,
+  fields: NodeFields<K>,
+): NodeOfKind<K> {
+  // The spread of a generic Omit cannot be proved to reconstruct the node it
+  // was taken from, so the one assertion in the module is here, where the
+  // signature above has already checked every field of every call.
+  return { ...fields, kind, span } as unknown as NodeOfKind<K>;
+}

package/src/core/ast/children.ts

@@ -0,0 +1,110 @@
+import type { AstNode } from './node.js';
+
+const NO_CHILDREN: readonly AstNode[] = [];
+
+/** The nodes among these that are there, keeping the order they were given in. */
+function present(...nodes: readonly (AstNode | undefined)[]): readonly AstNode[] {
+  return nodes.filter((node): node is AstNode => node !== undefined);
+}
+
+/**
+ * The children of a node, in source order.
+ *
+ * This is the only place the shape of the tree is written down twice, and it is
+ * deliberately the only one. Everything that walks the tree walks it through
+ * here, so a field added to a node is connected once and every pass sees it,
+ * rather than being connected in the checker, forgotten in the code generator,
+ * and found by a user whose script compiled to something with a hole in it.
+ *
+ * The switch has no default arm on purpose: a new node kind stops the build
+ * here, at the one place that has to know about it.
+ */
+export function childrenOf(node: AstNode): readonly AstNode[] {
+  switch (node.kind) {
+    // The file and what only the file holds.
+    case 'script':
+      return node.items;
+    case 'functionDeclaration':
+      return [node.name, ...node.parameters, node.body];
+    case 'parameter':
+      return present(node.name, node.annotation, node.defaultValue);
+
+    // The header lines, which are statements wherever they are written.
+    case 'versionLine':
+      return [node.version];
+    case 'scriptDeclaration':
+      return node.args;
+    case 'limitsLine':
+      return node.args;
+
+    // Statements.
+    case 'expressionStatement':
+      return [node.expression];
+    case 'assignment':
+      return [node.target, node.value];
+    case 'varDeclaration':
+      return present(node.name, node.annotation, node.initialiser);
+    case 'ifStatement':
+      return present(...node.branches, node.elseBranch);
+    case 'ifBranch':
+      return [node.condition, node.body];
+    case 'elseBranch':
+      return [node.body];
+    case 'forRangeStatement':
+      return present(node.variable, node.from, node.to, node.step, node.body);
+    case 'forInStatement':
+      return [node.variable, node.iterable, node.body];
+    case 'whileStatement':
+      return [node.condition, node.body];
+    case 'switchStatement':
+      return present(node.subject, ...node.cases, node.defaultCase);
+    case 'switchCase':
+      return [...node.values, node.body];
+    case 'switchDefault':
+      return [node.body];
+    case 'breakStatement':
+    case 'continueStatement':
+      return NO_CHILDREN;
+    case 'returnStatement':
+      return present(node.value);
+    case 'block':
+      return node.statements;
+
+    // Expressions.
+    case 'numberLiteral':
+    case 'stringLiteral':
+    case 'booleanLiteral':
+    case 'colorLiteral':
+    case 'noneLiteral':
+    case 'nameReference':
+    case 'missingExpression':
+      return NO_CHILDREN;
+    case 'arrayLiteral':
+      return node.elements;
+    case 'grouping':
+      return [node.expression];
+    case 'unary':
+      return [node.operand];
+    case 'binary':
+      return [node.left, node.right];
+    case 'ternary':
+      return [node.condition, node.whenTrue, node.whenFalse];
+    case 'call':
+      return [node.callee, ...node.args];
+    case 'argument':
+      return present(node.label, node.value);
+    case 'index':
+      return [node.target, node.index];
+    case 'member':
+      return [node.object, node.member];
+
+    // Type annotations, and a name where one is written.
+    case 'namedType':
+      return NO_CHILDREN;
+    case 'seriesType':
+    case 'arrayType':
+      return [node.element];
+    case 'name':
+      return NO_CHILDREN;
+  }
+}

package/src/core/ast/expressions.ts

@@ -0,0 +1,254 @@
+import type { Positioned } from '../span/index.js';
+import type { Name } from './name.js';
+
+/**
+ * Every expression form of language.md section 9.
+ *
+ * Precedence is not a field anywhere below. It is in the shape of the tree: the
+ * parser reads the levels of 9.1 and the result is already grouped, so a later
+ * pass never has to know that `*` binds tighter than `+`. The one thing the
+ * tree does keep is the brackets a script wrote, because they are the
+ * difference between a caret under `(a < b)` and a caret under a whole line.
+ */
+
+export const ARITHMETIC_OPERATORS = ['+', '-', '*', '/', '%'] as const;
+export type ArithmeticOperator = (typeof ARITHMETIC_OPERATORS)[number];
+
+export const COMPARISON_OPERATORS = ['<', '<=', '>', '>='] as const;
+export type ComparisonOperator = (typeof COMPARISON_OPERATORS)[number];
+
+export const EQUALITY_OPERATORS = ['==', '!='] as const;
+export type EqualityOperator = (typeof EQUALITY_OPERATORS)[number];
+
+export const LOGICAL_OPERATORS = ['and', 'or'] as const;
+export type LogicalOperator = (typeof LOGICAL_OPERATORS)[number];
+
+export type BinaryOperator =
+  | ArithmeticOperator
+  | ComparisonOperator
+  | EqualityOperator
+  | LogicalOperator;
+
+export const UNARY_OPERATORS = ['-', '+', 'not'] as const;
+export type UnaryOperator = (typeof UNARY_OPERATORS)[number];
+
+/**
+ * The level each binary operator sits at in language.md 9.1, where a lower
+ * number binds more tightly.
+ *
+ * The numbers are the specification's own rather than a private scale that runs
+ * the other way, so a reader can check this table against language.md 9.1
+ * without translating it as they read. It sits next to the operators because a
+ * parser and a formatter that each kept a copy would disagree about one
+ * operator eventually, and that disagreement reaches a chart as a wrong number.
+ */
+const BINARY_PRECEDENCE: Readonly<Record<BinaryOperator, number>> = {
+  '*': 3,
+  '/': 3,
+  '%': 3,
+  '+': 4,
+  '-': 4,
+  '<': 5,
+  '<=': 5,
+  '>': 5,
+  '>=': 5,
+  '==': 6,
+  '!=': 6,
+  and: 7,
+  or: 8,
+};
+
+export function binaryPrecedence(operator: BinaryOperator): number {
+  return BINARY_PRECEDENCE[operator];
+}
+
+/**
+ * The value a number literal denotes, already read.
+ *
+ * The digit group underscores and the hexadecimal form of language.md 3.5 are
+ * resolved by the lexer, so nothing downstream reads the text a second time and
+ * nothing downstream can disagree with the lexer about what it meant.
+ */
+export interface NumberLiteral extends Positioned {
+  readonly kind: 'numberLiteral';
+  readonly value: number;
+}
+
+/** A string literal with its escape sequences already resolved. */
+export interface StringLiteral extends Positioned {
+  readonly kind: 'stringLiteral';
+  readonly value: string;
+}
+
+export interface BooleanLiteral extends Positioned {
+  readonly kind: 'booleanLiteral';
+  readonly value: boolean;
+}
+
+/**
+ * The `#rrggbb` and `#rrggbbaa` forms of language.md 3.8, text and all.
+ *
+ * A named colour is not one of these. The nineteen names are ordinary globals
+ * so the standard library can add more without a grammar change, so `aqua` is a
+ * `nameReference` and the checker resolves it like any other name.
+ *
+ * The text is kept rather than four channel numbers, because the channels are
+ * the checker's reading of it and a diagnostic about a malformed colour has to
+ * quote what was written.
+ */
+export interface ColorLiteral extends Positioned {
+  readonly kind: 'colorLiteral';
+  readonly text: string;
+}
+
+/** `none`, the absent value of language.md section 6. */
+export interface NoneLiteral extends Positioned {
+  readonly kind: 'noneLiteral';
+}
+
+/**
+ * `[1, 2, 3]`, and `[]`.
+ *
+ * An empty literal is legal here. Its element type is unknown until the checker
+ * finds an annotation or a first use, and OS2015 when it finds neither.
+ */
+export interface ArrayLiteral extends Positioned {
+  readonly kind: 'arrayLiteral';
+  readonly elements: readonly Expression[];
+}
+
+/** A name used as a value. Its span is the name, so it carries no child. */
+export interface NameReference extends Positioned {
+  readonly kind: 'nameReference';
+  readonly name: string;
+}
+
+/**
+ * `(expression)`.
+ *
+ * Kept rather than folded away, because both passes that point back at source
+ * need it: a diagnostic about a grouped expression underlines the brackets a
+ * reader can see, and a formatter that dropped them would turn `(a + b) * c`
+ * into something else on its first reprint. A pass that wants the value inside
+ * calls `withoutGrouping`.
+ */
+export interface Grouping extends Positioned {
+  readonly kind: 'grouping';
+  readonly expression: Expression;
+}
+
+export interface Unary extends Positioned {
+  readonly kind: 'unary';
+  readonly operator: UnaryOperator;
+  readonly operand: Expression;
+}
+
+export interface Binary extends Positioned {
+  readonly kind: 'binary';
+  readonly operator: BinaryOperator;
+  readonly left: Expression;
+  readonly right: Expression;
+}
+
+/** `condition ? whenTrue : whenFalse`, language.md 9.5. */
+export interface Ternary extends Positioned {
+  readonly kind: 'ternary';
+  readonly condition: Expression;
+  readonly whenTrue: Expression;
+  readonly whenFalse: Expression;
+}
+
+/**
+ * One argument of a call, of `study()`, of `strategy()` or of `limits()`.
+ *
+ * A label is a `Name` and not a `nameReference` because it is never resolved.
+ * It is matched against the callee's parameter list, which is what lets a
+ * reserved word stand as one (language.md 3.4).
+ */
+export interface Argument extends Positioned {
+  readonly kind: 'argument';
+  readonly label: Name | undefined;
+  readonly value: Expression;
+}
+
+/**
+ * A call, with its arguments in the order they were written.
+ *
+ * Positional after named is OS3005, a check rather than a shape, so nothing is
+ * sorted on the way in and the tree keeps the order that error has to quote.
+ * The callee is an expression because `draw.box(...)` is an argument list
+ * applied to a member access, and because `f(1)(2)` has to parse before it can
+ * be told that it is not a thing OpenScript does.
+ */
+export interface Call extends Positioned {
+  readonly kind: 'call';
+  readonly callee: Expression;
+  readonly args: readonly Argument[];
+}
+
+/**
+ * `target[index]`: history when the target is a series, element access when it
+ * is an array, and the checker decides which from the target's type
+ * (language.md 9.6). There is no run-time dispatch and no third meaning.
+ *
+ * The explicit forms `history(expr, n)` and `element(arr, i)` are ordinary
+ * calls and are not this node.
+ */
+export interface Index extends Positioned {
+  readonly kind: 'index';
+  readonly target: Expression;
+  readonly index: Expression;
+}
+
+/**
+ * `object.member`.
+ *
+ * A namespace read such as `bar.index` and a field of a runtime object are one
+ * shape here. Which of the two it is, and whether the member exists at all
+ * (OS2009), is the checker's answer.
+ */
+export interface Member extends Positioned {
+  readonly kind: 'member';
+  readonly object: Expression;
+  readonly member: Name;
+}
+
+/**
+ * A hole where an expression was required and none was written.
+ *
+ * The parser puts one here after reporting OS1022, OS1011 or OS1015, so a file
+ * with a mistake in it still produces a tree. Everything downstream runs on
+ * broken files by definition: an editor asks for completions inside a half
+ * typed line, and a checker that stopped at the first syntax error would report
+ * one mistake per compile.
+ *
+ * The span is where the expression should have been, and is usually empty, so
+ * it never takes a caret meant for its neighbour.
+ */
+export interface MissingExpression extends Positioned {
+  readonly kind: 'missingExpression';
+}
+
+export type Expression =
+  | NumberLiteral
+  | StringLiteral
+  | BooleanLiteral
+  | ColorLiteral
+  | NoneLiteral
+  | ArrayLiteral
+  | NameReference
+  | Grouping
+  | Unary
+  | Binary
+  | Ternary
+  | Call
+  | Index
+  | Member
+  | MissingExpression;
+
+/** The expression inside however many brackets were written around it. */
+export function withoutGrouping(expression: Expression): Expression {
+  let inner = expression;
+  while (inner.kind === 'grouping') inner = inner.expression;
+  return inner;
+}

package/src/core/ast/header.ts

@@ -0,0 +1,53 @@
+import type { Positioned } from '../span/index.js';
+import type { Argument, NumberLiteral } from './expressions.js';
+
+/**
+ * The three lines that describe the file rather than compute anything: the
+ * version line, the study or strategy declaration, and the limits line.
+ *
+ * All three are statements, and the tree lets them appear anywhere a statement
+ * appears. The specification calls each one a statement (4, 13.1 and 10.7), and
+ * more to the point the errors for putting one in the wrong place are OS1021,
+ * OS2007 and OS2008, which name a line and suggest a move. A tree with one slot
+ * for the declaration could not hold the second one long enough for OS2008 to
+ * say where it was, and a tree that refused a file with no declaration at all
+ * would turn OS2007 into a parse failure with nothing else checked.
+ */
+
+/**
+ * `version 1`.
+ *
+ * `version` is not a reserved word: it is an ordinary identifier to the lexer,
+ * recognised here by its position, so that a script written before the word
+ * existed keeps compiling (language.md 3.4 and 4.1).
+ */
+export interface VersionLine extends Positioned {
+  readonly kind: 'versionLine';
+  readonly version: NumberLiteral;
+}
+
+/**
+ * `study("Name", ...)` or `strategy("Name", ...)`, language.md 13.1.
+ *
+ * The form is kept as the word that was written rather than as a boolean,
+ * because it is what OS2008 and OS7001 quote back to the reader, and because a
+ * later version that adds a third form adds a member here rather than a second
+ * flag.
+ */
+export interface ScriptDeclaration extends Positioned {
+  readonly kind: 'scriptDeclaration';
+  readonly form: 'study' | 'strategy';
+  readonly args: readonly Argument[];
+}
+
+/**
+ * `limits(loops = 50_000_000)`, language.md 10.7.
+ *
+ * Which options exist, that the values are literal numbers, and that the host
+ * is willing to run them (OS5003) are all decided later. The tree carries the
+ * arguments as written.
+ */
+export interface LimitsLine extends Positioned {
+  readonly kind: 'limitsLine';
+  readonly args: readonly Argument[];
+}

package/src/core/ast/index.ts

@@ -0,0 +1,102 @@
+/**
+ * The syntax tree of language.md, and the one traversal over it.
+ *
+ * Types and constructors, and no parsing: the tree is what the parser produces
+ * and what the checker, the code generator and the editor's intelligence all
+ * read, so it is defined on its own and none of the four owns it.
+ *
+ * Two things here are worth knowing before reading the rest. Every node carries
+ * a `Span`, so anything the compiler says about a node has a caret. And every
+ * node is a member of one discriminated union, `AstNode`, so a pass that
+ * switches on `kind` without a default arm is told at compile time about the
+ * kinds it has not handled.
+ */
+
+export type { Name } from './name.js';
+
+export type {
+  ArrayType,
+  NamedType,
+  ObjectTypeName,
+  SeriesType,
+  TypeAnnotation,
+  ValueTypeName,
+} from './annotations.js';
+export {
+  OBJECT_TYPE_NAMES,
+  VALUE_TYPE_NAMES,
+  isObjectTypeName,
+  isValueTypeName,
+} from './annotations.js';
+
+export type {
+  ArithmeticOperator,
+  Argument,
+  ArrayLiteral,
+  Binary,
+  BinaryOperator,
+  BooleanLiteral,
+  Call,
+  ColorLiteral,
+  ComparisonOperator,
+  EqualityOperator,
+  Expression,
+  Grouping,
+  Index,
+  LogicalOperator,
+  Member,
+  MissingExpression,
+  NameReference,
+  NoneLiteral,
+  NumberLiteral,
+  StringLiteral,
+  Ternary,
+  Unary,
+  UnaryOperator,
+} from './expressions.js';
+export {
+  ARITHMETIC_OPERATORS,
+  COMPARISON_OPERATORS,
+  EQUALITY_OPERATORS,
+  LOGICAL_OPERATORS,
+  UNARY_OPERATORS,
+  binaryPrecedence,
+  withoutGrouping,
+} from './expressions.js';
+
+export type { LimitsLine, ScriptDeclaration, VersionLine } from './header.js';
+
+export type {
+  Assignment,
+  AssignmentOperator,
+  Block,
+  BreakStatement,
+  ContinueStatement,
+  ElseBranch,
+  ExpressionStatement,
+  ForInStatement,
+  ForRangeStatement,
+  IfBranch,
+  IfStatement,
+  ReturnStatement,
+  Statement,
+  SwitchCase,
+  SwitchDefault,
+  SwitchStatement,
+  VarDeclaration,
+  WhileStatement,
+} from './statements.js';
+export { ASSIGNMENT_OPERATORS } from './statements.js';
+
+export type { FunctionDeclaration, Parameter, Script, TopLevelItem } from './script.js';
+
+export type { AstNode, NodeKind, NodeOfKind } from './node.js';
+export { isExpression, isStatement, isTypeAnnotation, typeAnnotationText } from './node.js';
+
+export type { NodeFields } from './build.js';
+export { makeNode } from './build.js';
+
+export { childrenOf } from './children.js';
+
+export type { Visit, Visitor } from './walk.js';
+export { nodeAtOffset, pathAtOffset, walk } from './walk.js';

package/src/core/ast/name.ts

@@ -0,0 +1,24 @@
+import type { Positioned } from '../span/index.js';
+
+/**
+ * A name at the place it is written rather than the place it is read.
+ *
+ * A name used as a value is a `nameReference`, which the checker resolves
+ * against a scope. Every other name in the language is this node instead: the
+ * left side of an assignment, the name a `var` introduces, a loop variable, a
+ * function's name, a parameter's name, the word after a dot, and the label of a
+ * named argument.
+ *
+ * The two are separate kinds because a pass that walks the tree collecting uses
+ * of a name must not collect the places that introduce one. With a single kind
+ * every such pass has to ask the parent what it is holding, and the pass that
+ * forgets reports OS2001 on the very name being declared.
+ *
+ * The text is not always a legal identifier: a named argument's label may be a
+ * reserved word, because a label is matched against a parameter list and is
+ * never looked up in a scope (language.md 3.4).
+ */
+export interface Name extends Positioned {
+  readonly kind: 'name';
+  readonly text: string;
+}