openalgo-script 0.1.0-alpha.0

package/dist/core/ast/script.d.ts

@@ -0,0 +1,57 @@
+import type { Positioned } from '../span/index.js';
+import type { TypeAnnotation } from './annotations.js';
+import type { Expression } from './expressions.js';
+import type { Name } from './name.js';
+import type { Block, Statement } from './statements.js';
+/**
+ * A parameter of a user function, language.md 11.2.
+ *
+ * A parameter is an ordinary identifier and a reserved word is OS1019 here,
+ * which is the rule a named argument label does not follow: the body refers to
+ * a parameter and nothing ever refers to a label.
+ */
+export interface Parameter extends Positioned {
+    readonly kind: 'parameter';
+    readonly name: Name;
+    readonly annotation: TypeAnnotation | undefined;
+    readonly defaultValue: Expression | undefined;
+}
+/**
+ * `fn name(parameters) => body`, language.md 11.1.
+ *
+ * The body is an expression for the single line form and a block for the
+ * indented one, kept apart rather than wrapped, because the single line form
+ * has no block to give a span to and an editor folding a function should fold
+ * what was written.
+ *
+ * A function is not a statement. It may not be assigned to a name and it may
+ * not be nested, so the only place one belongs is the top level of a file. A
+ * block holds one all the same, because a reader who nested one has written it
+ * and OS1023 has to name the line it is on; what the tree says is where it was
+ * written, and the diagnostic says whether that was allowed.
+ */
+export interface FunctionDeclaration extends Positioned {
+    readonly kind: 'functionDeclaration';
+    readonly name: Name;
+    readonly parameters: readonly Parameter[];
+    readonly body: Block | Expression;
+}
+export type TopLevelItem = Statement | FunctionDeclaration;
+/**
+ * One source file.
+ *
+ * The items are everything the file holds, in source order, including the
+ * version line, the declaration and the limits line: a header node is a
+ * statement (see header.ts) and sits among the rest. So a file with no
+ * declaration, a file with two, and a version line halfway down all have a tree,
+ * which is what OS2007, OS2008 and OS1021 need in order to report a line number
+ * and a fix instead of a parse failure.
+ *
+ * A consumer reaches the declaration by looking through the items for the one
+ * kind it wants, and finds every occurrence rather than the first.
+ */
+export interface Script extends Positioned {
+    readonly kind: 'script';
+    readonly items: readonly TopLevelItem[];
+}
+//# sourceMappingURL=script.d.ts.map

package/dist/core/ast/script.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"script.d.ts","sourceRoot":"","sources":["../../../src/core/ast/script.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,WAAW,SAAU,SAAQ,UAAU;IAC3C,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,cAAc,GAAG,SAAS,CAAC;IAChD,QAAQ,CAAC,YAAY,EAAE,UAAU,GAAG,SAAS,CAAC;CAC/C;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,mBAAoB,SAAQ,UAAU;IACrD,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,UAAU,CAAC;CACnC;AAED,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,mBAAmB,CAAC;AAE3D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,MAAO,SAAQ,UAAU;IACxC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;CACzC"}

package/dist/core/ast/script.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=script.js.map

package/dist/core/ast/script.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"script.js","sourceRoot":"","sources":["../../../src/core/ast/script.ts"],"names":[],"mappings":""}

package/dist/core/ast/statements.d.ts

@@ -0,0 +1,161 @@
+import type { Positioned } from '../span/index.js';
+import type { TypeAnnotation } from './annotations.js';
+import type { Expression } from './expressions.js';
+import type { LimitsLine, ScriptDeclaration, VersionLine } from './header.js';
+import type { Name } from './name.js';
+import type { FunctionDeclaration } from './script.js';
+/**
+ * Every statement form of language.md section 10, plus the block they nest in.
+ *
+ * There is no statement that is also an expression and no expression that is
+ * also a statement: assignment is a statement (10.1), and `switch` is a
+ * statement rather than a value (10.6). That is why `if x = 5` can be OS1006
+ * with a fix naming `==` instead of a type error three stages later.
+ */
+export declare const ASSIGNMENT_OPERATORS: readonly ["=", "+=", "-=", "*=", "/=", "%="];
+export type AssignmentOperator = (typeof ASSIGNMENT_OPERATORS)[number];
+/**
+ * The indented lines under a header, language.md 3.10.
+ *
+ * A block is a node with a span of its own so that OS1003 and OS1010 have
+ * something to point at, and so an editor can fold one. Blank and comment only
+ * lines produce no token, so they are not statements and never appear here.
+ *
+ * A function declaration may be written here and may not be legal here, which
+ * is the same arrangement the header statements already have: a version line
+ * inside a block is OS1021 and a declaration inside one is OS1023, and both
+ * diagnostics name a line and suggest a move, which a tree that refused to hold
+ * the node could not do. So a nested declaration stays where it was written,
+ * where the reader has to change it, rather than being dropped, which would
+ * hide it from every pass after the parser, or lifted to the top level, which
+ * would compile a file the language refuses.
+ */
+export interface Block extends Positioned {
+    readonly kind: 'block';
+    readonly statements: readonly (Statement | FunctionDeclaration)[];
+}
+/** A bare expression on a line, which is how a script calls `plot` or `signal`. */
+export interface ExpressionStatement extends Positioned {
+    readonly kind: 'expressionStatement';
+    readonly expression: Expression;
+}
+/**
+ * `name = value`, and the five compound forms.
+ *
+ * The target is a bare name, because that is the whole of the form: there is no
+ * `a[i] = v` and no `a.b = v` in the language, so an element is written with
+ * `set(arr, i, v)` and a runtime object with a `draw` setter.
+ */
+export interface Assignment extends Positioned {
+    readonly kind: 'assignment';
+    readonly target: Name;
+    readonly operator: AssignmentOperator;
+    readonly value: Expression;
+}
+/**
+ * `var name = initial`, and `live var name = initial`, language.md 8.2.
+ *
+ * The initialiser is required rather than optional, because `var name` with no
+ * value is OS1011 and the fix names `= none`. A parser reporting it puts a
+ * `missingExpression` here and carries on, so the name is still declared for
+ * every later diagnostic about it.
+ */
+export interface VarDeclaration extends Positioned {
+    readonly kind: 'varDeclaration';
+    /** `live var`: the value does not roll back when the moving bar re-executes. */
+    readonly live: boolean;
+    readonly name: Name;
+    readonly annotation: TypeAnnotation | undefined;
+    readonly initialiser: Expression;
+}
+/** One `if` or `else if` header and the block under it. */
+export interface IfBranch extends Positioned {
+    readonly kind: 'ifBranch';
+    readonly condition: Expression;
+    readonly body: Block;
+}
+/** The final `else` and its block. A node, so the word itself has a span. */
+export interface ElseBranch extends Positioned {
+    readonly kind: 'elseBranch';
+    readonly body: Block;
+}
+/**
+ * `if`, with its `else if` branches beside it rather than nested inside it.
+ *
+ * `else if` is two words on one line and does not increase indentation
+ * (language.md 10.2), so a reader sees one statement with several branches.
+ * Nesting each branch inside the previous one would make a chain of five read
+ * as five statements to every pass that walks the tree, and the depth would be
+ * visible in every diagnostic and every fold an editor offers.
+ */
+export interface IfStatement extends Positioned {
+    readonly kind: 'ifStatement';
+    /** At least one: the `if` itself, then each `else if` in source order. */
+    readonly branches: readonly IfBranch[];
+    readonly elseBranch: ElseBranch | undefined;
+}
+/**
+ * `for i = 0 to 9` and `for i = 9 to 0 step -1`, language.md 10.3. Both ends
+ * are inclusive, and a missing `step` means one rather than a hidden node, so
+ * that OS3004 on a step of zero always has a span the reader wrote.
+ */
+export interface ForRangeStatement extends Positioned {
+    readonly kind: 'forRangeStatement';
+    readonly variable: Name;
+    readonly from: Expression;
+    readonly to: Expression;
+    readonly step: Expression | undefined;
+    readonly body: Block;
+}
+/** `for price in prices`: the loop variable takes each element, not each index. */
+export interface ForInStatement extends Positioned {
+    readonly kind: 'forInStatement';
+    readonly variable: Name;
+    readonly iterable: Expression;
+    readonly body: Block;
+}
+export interface WhileStatement extends Positioned {
+    readonly kind: 'whileStatement';
+    readonly condition: Expression;
+    readonly body: Block;
+}
+/** One `case` arm. Several values are one arm, not several arms. */
+export interface SwitchCase extends Positioned {
+    readonly kind: 'switchCase';
+    readonly values: readonly Expression[];
+    readonly body: Block;
+}
+export interface SwitchDefault extends Positioned {
+    readonly kind: 'switchDefault';
+    readonly body: Block;
+}
+/**
+ * `switch`, in both forms of language.md 10.6.
+ *
+ * With a subject, each case value is compared against it. Without one, each
+ * case value is a condition and the first true arm runs. The absent subject is
+ * the difference between the two forms and needs no flag beside it.
+ *
+ * `default` has its own slot rather than sitting among the cases, because it
+ * must be last and because the arms do not fall through, so nothing downstream
+ * has to check the order it found them in.
+ */
+export interface SwitchStatement extends Positioned {
+    readonly kind: 'switchStatement';
+    readonly subject: Expression | undefined;
+    readonly cases: readonly SwitchCase[];
+    readonly defaultCase: SwitchDefault | undefined;
+}
+export interface BreakStatement extends Positioned {
+    readonly kind: 'breakStatement';
+}
+export interface ContinueStatement extends Positioned {
+    readonly kind: 'continueStatement';
+}
+/** `return expression`, or a bare `return`, which returns `none`. */
+export interface ReturnStatement extends Positioned {
+    readonly kind: 'returnStatement';
+    readonly value: Expression | undefined;
+}
+export type Statement = ExpressionStatement | Assignment | VarDeclaration | IfStatement | ForRangeStatement | ForInStatement | WhileStatement | SwitchStatement | BreakStatement | ContinueStatement | ReturnStatement | VersionLine | ScriptDeclaration | LimitsLine;
+//# sourceMappingURL=statements.d.ts.map

package/dist/core/ast/statements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statements.d.ts","sourceRoot":"","sources":["../../../src/core/ast/statements.ts"],"names":[],"mappings":"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"}

package/dist/core/ast/statements.js

@@ -0,0 +1,10 @@
+/**
+ * Every statement form of language.md section 10, plus the block they nest in.
+ *
+ * There is no statement that is also an expression and no expression that is
+ * also a statement: assignment is a statement (10.1), and `switch` is a
+ * statement rather than a value (10.6). That is why `if x = 5` can be OS1006
+ * with a fix naming `==` instead of a type error three stages later.
+ */
+export const ASSIGNMENT_OPERATORS = ['=', '+=', '-=', '*=', '/=', '%='];
+//# sourceMappingURL=statements.js.map

package/dist/core/ast/statements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"statements.js","sourceRoot":"","sources":["../../../src/core/ast/statements.ts"],"names":[],"mappings":"AAOA;;;;;;;GAOG;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAU,CAAC"}

package/dist/core/ast/walk.d.ts

@@ -0,0 +1,39 @@
+import type { AstNode } from './node.js';
+/** Returning `skip` from `enter` leaves that node's children unvisited. */
+export type Visit = 'skip' | void;
+export interface Visitor {
+    readonly enter?: (node: AstNode, parent: AstNode | undefined) => Visit;
+    readonly leave?: (node: AstNode, parent: AstNode | undefined) => void;
+}
+/**
+ * Every node, depth first, parents before children and children in source
+ * order.
+ *
+ * `leave` runs for a node whose children were skipped, so a pass that opens
+ * something on the way in and closes it on the way out stays balanced whatever
+ * it skips. A scope left open by a skipped node is the kind of fault that shows
+ * up as a name resolving in the wrong place, three files away from its cause.
+ *
+ * A pass that has to handle every kind should not use this. It should switch on
+ * `node.kind` with no default arm, so that the compiler names the kinds it has
+ * missed; this is for a pass that cares about a few kinds and wants the rest
+ * walked for it.
+ */
+export declare function walk(root: AstNode, visitor: Visitor): void;
+/**
+ * The nodes covering an offset, outermost first, ending at the smallest one.
+ *
+ * This is what an editor asks for and it is one function rather than three,
+ * because hover, completion and signature help each need the node under the
+ * caret and the ancestors above it, and three copies of a descent through the
+ * tree would answer differently at a boundary.
+ *
+ * A span covers its first character and stops before the one after it, and a
+ * span of no length covers nothing, so a caret sitting between two characters
+ * is inside the one on its left: an editor asking about a caret asks about the
+ * offset before it.
+ */
+export declare function pathAtOffset(root: AstNode, offset: number): readonly AstNode[];
+/** The smallest node covering an offset, or nothing when the offset is outside. */
+export declare function nodeAtOffset(root: AstNode, offset: number): AstNode | undefined;
+//# sourceMappingURL=walk.d.ts.map

package/dist/core/ast/walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../../../src/core/ast/walk.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,2EAA2E;AAC3E,MAAM,MAAM,KAAK,GAAG,MAAM,GAAG,IAAI,CAAC;AAElC,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,SAAS,KAAK,KAAK,CAAC;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,SAAS,KAAK,IAAI,CAAC;CACvE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAE1D;AASD;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,OAAO,EAAE,CAU9E;AAED,mFAAmF;AACnF,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAG/E"}

package/dist/core/ast/walk.js

@@ -0,0 +1,54 @@
+import { containsOffset } from '../span/index.js';
+import { childrenOf } from './children.js';
+/**
+ * Every node, depth first, parents before children and children in source
+ * order.
+ *
+ * `leave` runs for a node whose children were skipped, so a pass that opens
+ * something on the way in and closes it on the way out stays balanced whatever
+ * it skips. A scope left open by a skipped node is the kind of fault that shows
+ * up as a name resolving in the wrong place, three files away from its cause.
+ *
+ * A pass that has to handle every kind should not use this. It should switch on
+ * `node.kind` with no default arm, so that the compiler names the kinds it has
+ * missed; this is for a pass that cares about a few kinds and wants the rest
+ * walked for it.
+ */
+export function walk(root, visitor) {
+    visitNode(root, undefined, visitor);
+}
+function visitNode(node, parent, visitor) {
+    if (visitor.enter?.(node, parent) !== 'skip') {
+        for (const child of childrenOf(node))
+            visitNode(child, node, visitor);
+    }
+    visitor.leave?.(node, parent);
+}
+/**
+ * The nodes covering an offset, outermost first, ending at the smallest one.
+ *
+ * This is what an editor asks for and it is one function rather than three,
+ * because hover, completion and signature help each need the node under the
+ * caret and the ancestors above it, and three copies of a descent through the
+ * tree would answer differently at a boundary.
+ *
+ * A span covers its first character and stops before the one after it, and a
+ * span of no length covers nothing, so a caret sitting between two characters
+ * is inside the one on its left: an editor asking about a caret asks about the
+ * offset before it.
+ */
+export function pathAtOffset(root, offset) {
+    const path = [];
+    let current = containsOffset(root.span, offset) ? root : undefined;
+    while (current !== undefined) {
+        path.push(current);
+        current = childrenOf(current).find((child) => containsOffset(child.span, offset));
+    }
+    return path;
+}
+/** The smallest node covering an offset, or nothing when the offset is outside. */
+export function nodeAtOffset(root, offset) {
+    const path = pathAtOffset(root, offset);
+    return path[path.length - 1];
+}
+//# sourceMappingURL=walk.js.map

package/dist/core/ast/walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.js","sourceRoot":"","sources":["../../../src/core/ast/walk.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAW3C;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,IAAI,CAAC,IAAa,EAAE,OAAgB;IAClD,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;AACtC,CAAC;AAED,SAAS,SAAS,CAAC,IAAa,EAAE,MAA2B,EAAE,OAAgB;IAC7E,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,MAAM,EAAE,CAAC;QAC7C,KAAK,MAAM,KAAK,IAAI,UAAU,CAAC,IAAI,CAAC;YAAE,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACxE,CAAC;IACD,OAAO,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,IAAa,EAAE,MAAc;IACxD,MAAM,IAAI,GAAc,EAAE,CAAC;IAC3B,IAAI,OAAO,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IAEnE,OAAO,OAAO,KAAK,SAAS,EAAE,CAAC;QAC7B,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACnB,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IACpF,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,YAAY,CAAC,IAAa,EAAE,MAAc;IACxD,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACxC,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAC/B,CAAC"}