openalgo-script 0.1.0-alpha.0

package/dist/core/parse/branches.d.ts

@@ -0,0 +1,17 @@
+import type { IfStatement } from '../ast/index.js';
+import type { Cursor } from './cursor.js';
+/**
+ * `if`, `else if` and `else`, language.md 10.2.
+ *
+ * The branches are kept beside each other rather than nested, because `else if`
+ * is two words on one line and does not increase indentation, so a reader sees
+ * one statement with several arms and every pass over the tree should see the
+ * same thing.
+ *
+ * An `else` pairs with the `if` at its own indentation. The lexer has already
+ * closed the blocks between them, so the `else` that arrives here is the one
+ * that belongs to this `if`; what is left to check is that the two line up, and
+ * OS1016 when they do not.
+ */
+export declare function parseIfStatement(cursor: Cursor): IfStatement;
+//# sourceMappingURL=branches.d.ts.map

package/dist/core/parse/branches.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branches.d.ts","sourceRoot":"","sources":["../../../src/core/parse/branches.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAwB,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAKzE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAK1C;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CA0B5D"}

package/dist/core/parse/branches.js

@@ -0,0 +1,66 @@
+import { makeNode } from '../ast/index.js';
+import { spanning } from '../span/index.js';
+import { parseBlock } from './blocks.js';
+import { parseCondition } from './expressions.js';
+import { finishStatement } from './statements.js';
+/**
+ * `if`, `else if` and `else`, language.md 10.2.
+ *
+ * The branches are kept beside each other rather than nested, because `else if`
+ * is two words on one line and does not increase indentation, so a reader sees
+ * one statement with several arms and every pass over the tree should see the
+ * same thing.
+ *
+ * An `else` pairs with the `if` at its own indentation. The lexer has already
+ * closed the blocks between them, so the `else` that arrives here is the one
+ * that belongs to this `if`; what is left to check is that the two line up, and
+ * OS1016 when they do not.
+ */
+export function parseIfStatement(cursor) {
+    const keyword = cursor.token;
+    cursor.noteIf(keyword.span.column);
+    const branches = [parseBranch(cursor, 'if', keyword.span)];
+    let elseBranch;
+    let end = branches[0]?.span ?? keyword.span;
+    while (cursor.at('else')) {
+        const word = cursor.token;
+        pairWithIf(cursor, word, keyword);
+        cursor.advance();
+        if (cursor.at('if')) {
+            const branch = parseBranch(cursor, 'else if', word.span);
+            branches.push(branch);
+            end = branch.span;
+            continue;
+        }
+        elseBranch = parseElse(cursor, word);
+        end = elseBranch.span;
+        break;
+    }
+    return makeNode('ifStatement', spanning(keyword.span, end), { branches, elseBranch });
+}
+/** One `if` or `else if` header and the block under it. */
+function parseBranch(cursor, header, start) {
+    cursor.beginStatement();
+    const keyword = cursor.advance();
+    const condition = parseCondition(cursor);
+    finishStatement(cursor);
+    const body = parseBlock(cursor, header, spanning(start, keyword.span));
+    return makeNode('ifBranch', spanning(start, body.span), { condition, body });
+}
+function parseElse(cursor, word) {
+    cursor.beginStatement();
+    // Nothing may follow `else` on its line: there is no statement separator to
+    // end a one line body with, so a body is written indented underneath.
+    finishStatement(cursor);
+    const body = parseBlock(cursor, 'else', word.span);
+    return makeNode('elseBranch', spanning(word.span, body.span), { body });
+}
+function pairWithIf(cursor, word, keyword) {
+    if (word.span.column === keyword.span.column)
+        return;
+    cursor.report('OS1016', word.span, {
+        found: word.span.column - 1,
+        expected: keyword.span.column - 1,
+    });
+}
+//# sourceMappingURL=branches.js.map

package/dist/core/parse/branches.js.map

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

package/dist/core/parse/cursor.d.ts

@@ -0,0 +1,119 @@
+import type { DiagnosticCode, DiagnosticValues } from '../catalogue/index.js';
+import type { DiagnosticSink } from '../diagnostics/index.js';
+import type { SourceFile } from '../source/index.js';
+import type { Span } from '../span/index.js';
+import type { Token, TokenKind } from '../tokens/index.js';
+/**
+ * What a diagnostic calls a token when it has to quote one.
+ *
+ * A layout token carries no text, and a message that quoted one would quote
+ * nothing at all, so each is named by what a reader would call it.
+ */
+export declare function describeToken(token: Token): string;
+export declare class Cursor {
+    #private;
+    readonly file: SourceFile;
+    constructor(file: SourceFile, tokens: readonly Token[], sink: DiagnosticSink);
+    /** An index into the stream, which a loop compares to prove it made progress. */
+    get position(): number;
+    get token(): Token;
+    get kind(): TokenKind;
+    peek(ahead?: number): Token;
+    at(kind: TokenKind): boolean;
+    atStatementEnd(): boolean;
+    advance(): Token;
+    take(kind: TokenKind): Token | undefined;
+    /** The last token consumed, for a node that has to end where one ended. */
+    previous(): Token;
+    /**
+     * The token before this one, when it is one a reader wrote.
+     *
+     * OS1022 names the token the statement ran out after, which is the one to the
+     * left of the hole. At the start of a line there is no such token, and the
+     * caller names the one it is looking at instead.
+     */
+    previousMeaningful(): Token | undefined;
+    /**
+     * What the reader wrote across a span.
+     *
+     * A diagnostic that has to quote a piece of a program quotes the source
+     * rather than rebuilding it from the tree. `a.b` put back together out of a
+     * member node is a reconstruction, and one that differs from the page by so
+     * much as a space sends the reader looking for something they did not write.
+     */
+    textOf(span: Span): string;
+    /** An empty span where something should have been written and was not. */
+    holeSpan(): Span;
+    report<Code extends DiagnosticCode>(code: Code, span: Span, values: DiagnosticValues[Code]): void;
+    /**
+     * Whether this statement has already been reported on.
+     *
+     * One mistake is one diagnostic. A statement that has been reported on has
+     * nothing more to say about its own leftovers, so the second message about
+     * the same mistake is suppressed rather than the reader being left to work
+     * out which of the two to believe.
+     */
+    get reportedHere(): boolean;
+    /**
+     * A token where the grammar had one exact thing in mind, OS1018.
+     *
+     * The catalogue has no code for "a closing bracket belongs here", so the one
+     * it does have is used for all of them: OS1018 states what is true, that the
+     * token was not expected where it sits, and its fix names the two things that
+     * are usually wrong, a missing operator or a line that lost its newline.
+     */
+    unexpected(token: Token): void;
+    /**
+     * Whether one more level of expression nesting is within the ceiling.
+     *
+     * Refusing abandons the statement rather than only this level, because a
+     * parser that unwound from here would report the brackets it never reached
+     * the closers of, one per level, all of them about the expression that was
+     * already too deep.
+     */
+    deeper(span: Span): boolean;
+    shallower(): void;
+    /**
+     * The same ceiling for blocks, counted across statements rather than within
+     * one, because a block's depth is the file's shape and not a line's.
+     *
+     * A refusal here costs the block and not the statement: the caller skips the
+     * whole of it, so there is nothing left inside to report on twice.
+     */
+    openBlock(span: Span): boolean;
+    closeBlock(): void;
+    beginStatement(): void;
+    /**
+     * The first statement in the file, which is the line OS1021 names when a
+     * version declaration turns up below it.
+     */
+    noteStatement(line: number): void;
+    get firstStatementLine(): number | undefined;
+    /** Where the most recent `if` sat, which is what OS1016 pairs an `else` against. */
+    noteIf(column: number): void;
+    get nearestIfColumn(): number;
+    /**
+     * Whether a loop body is being read, which is the whole of OS1009.
+     *
+     * It is a count on the cursor rather than an argument threaded through every
+     * rule, because the one question `break` asks is whether any loop is open,
+     * and a function body cannot be inside one: functions are top level only.
+     */
+    enterLoop(): void;
+    leaveLoop(): void;
+    get insideLoop(): boolean;
+    /** To the end of this line, taking the newline, and no further. */
+    skipToEndOfLine(): void;
+    /**
+     * The whole statement, including a block written under it.
+     *
+     * This is the boundary to recover at when the line itself was not understood.
+     * A header the parser could not read still has its body indented beneath it,
+     * and reading that body as though it stood at the outer level would report
+     * every line of it.
+     */
+    skipStatement(): void;
+    /** A block, and the blocks inside it, when no statement can hold it. */
+    skipBlockBody(): void;
+}
+//# sourceMappingURL=cursor.d.ts.map

package/dist/core/parse/cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../../src/core/parse/cursor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAyC3D;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAYlD;AAED,qBAAa,MAAM;;IACjB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;gBAcd,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,KAAK,EAAE,EAAE,IAAI,EAAE,cAAc;IAU5E,iFAAiF;IACjF,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,IAAI,KAAK,IAAI,KAAK,CAEjB;IAED,IAAI,IAAI,IAAI,SAAS,CAEpB;IAED,IAAI,CAAC,KAAK,SAAI,GAAG,KAAK;IAItB,EAAE,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO;IAI5B,cAAc,IAAI,OAAO;IAIzB,OAAO,IAAI,KAAK;IAMhB,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,KAAK,GAAG,SAAS;IAIxC,2EAA2E;IAC3E,QAAQ,IAAI,KAAK;IAIjB;;;;;;OAMG;IACH,kBAAkB,IAAI,KAAK,GAAG,SAAS;IAKvC;;;;;;;OAOG;IACH,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM;IAI1B,0EAA0E;IAC1E,QAAQ,IAAI,IAAI;IAehB,MAAM,CAAC,IAAI,SAAS,cAAc,EAChC,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,gBAAgB,CAAC,IAAI,CAAC,GAC7B,IAAI;IAUP;;;;;;;OAOG;IACH,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED;;;;;;;OAOG;IACH,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAI9B;;;;;;;OAOG;IACH,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO;IAc3B,SAAS,IAAI,IAAI;IAIjB;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO;IAa9B,UAAU,IAAI,IAAI;IAQlB,cAAc,IAAI,IAAI;IAMtB;;;OAGG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIjC,IAAI,kBAAkB,IAAI,MAAM,GAAG,SAAS,CAE3C;IAED,oFAAoF;IACpF,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI5B,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED;;;;;;OAMG;IACH,SAAS,IAAI,IAAI;IAIjB,SAAS,IAAI,IAAI;IAIjB,IAAI,UAAU,IAAI,OAAO,CAExB;IAMD,mEAAmE;IACnE,eAAe,IAAI,IAAI;IAUvB;;;;;;;OAOG;IACH,aAAa,IAAI,IAAI;IAKrB,wEAAwE;IACxE,aAAa,IAAI,IAAI;CAStB"}

package/dist/core/parse/cursor.js

@@ -0,0 +1,305 @@
+import { endOffset } from '../span/index.js';
+/**
+ * The parser's place in the token stream, and the three things every rule of
+ * the grammar needs that are not grammar: where it is, how it reports, and how
+ * it gets out of trouble.
+ *
+ * Recovery lives here rather than in each rule because it has to be the same
+ * everywhere. A trader with three mistakes in a file wants three diagnostics,
+ * so no rule throws and no rule gives up on the file: it reports, skips to the
+ * next boundary the language guarantees, and carries on. The boundaries are the
+ * lexer's own layout tokens, which is what makes the skip reliable rather than
+ * a guess: a statement ends at a `newline`, and a block is bracketed by an
+ * `indent` and a `dedent`.
+ */
+/**
+ * The ceiling on source nesting, OS5005.
+ *
+ * Its purpose is a bounded stack: the parser descends one frame per level of
+ * brackets, and generated source is the usual way a file reaches a depth no
+ * person writes. The specification names no number, so this one is the
+ * compiler's, and it is far above anything written by hand: the deepest
+ * expression in the example scripts nests four.
+ */
+const MAX_NESTING = 128;
+/** The tokens that end a statement. None of them is ever part of one. */
+const STATEMENT_END = new Set([
+    'newline',
+    'dedent',
+    'endOfFile',
+]);
+const LAYOUT = new Set([
+    'newline',
+    'indent',
+    'dedent',
+    'endOfFile',
+]);
+/**
+ * What a diagnostic calls a token when it has to quote one.
+ *
+ * A layout token carries no text, and a message that quoted one would quote
+ * nothing at all, so each is named by what a reader would call it.
+ */
+export function describeToken(token) {
+    switch (token.kind) {
+        case 'newline':
+            return 'the end of the line';
+        case 'endOfFile':
+            return 'the end of the file';
+        case 'indent':
+        case 'dedent':
+            return 'the change of indentation';
+        default:
+            return token.text;
+    }
+}
+export class Cursor {
+    file;
+    #tokens;
+    #sink;
+    #at = 0;
+    /** Diagnostics reported since this statement began. See `reportedHere`. */
+    #reported = 0;
+    #expressions = 0;
+    #blocks = 0;
+    #abandoned = false;
+    #firstStatementLine;
+    #ifColumn;
+    #loops = 0;
+    constructor(file, tokens, sink) {
+        this.file = file;
+        this.#tokens = tokens;
+        this.#sink = sink;
+    }
+    // ---------------------------------------------------------------------------
+    // Where it is
+    // ---------------------------------------------------------------------------
+    /** An index into the stream, which a loop compares to prove it made progress. */
+    get position() {
+        return this.#at;
+    }
+    get token() {
+        return this.#tokenAt(this.#at);
+    }
+    get kind() {
+        return this.token.kind;
+    }
+    peek(ahead = 1) {
+        return this.#tokenAt(this.#at + ahead);
+    }
+    at(kind) {
+        return this.token.kind === kind;
+    }
+    atStatementEnd() {
+        return STATEMENT_END.has(this.token.kind);
+    }
+    advance() {
+        const token = this.token;
+        if (this.#at < this.#tokens.length - 1)
+            this.#at += 1;
+        return token;
+    }
+    take(kind) {
+        return this.at(kind) ? this.advance() : undefined;
+    }
+    /** The last token consumed, for a node that has to end where one ended. */
+    previous() {
+        return this.#tokenAt(this.#at - 1);
+    }
+    /**
+     * The token before this one, when it is one a reader wrote.
+     *
+     * OS1022 names the token the statement ran out after, which is the one to the
+     * left of the hole. At the start of a line there is no such token, and the
+     * caller names the one it is looking at instead.
+     */
+    previousMeaningful() {
+        const before = this.#tokenAt(this.#at - 1);
+        return this.#at > 0 && !LAYOUT.has(before.kind) ? before : undefined;
+    }
+    /**
+     * What the reader wrote across a span.
+     *
+     * A diagnostic that has to quote a piece of a program quotes the source
+     * rather than rebuilding it from the tree. `a.b` put back together out of a
+     * member node is a reconstruction, and one that differs from the page by so
+     * much as a space sends the reader looking for something they did not write.
+     */
+    textOf(span) {
+        return this.file.text.slice(span.offset, endOffset(span));
+    }
+    /** An empty span where something should have been written and was not. */
+    holeSpan() {
+        return this.file.spanAt(this.token.span.offset, 0);
+    }
+    #tokenAt(index) {
+        const clamped = Math.min(Math.max(index, 0), this.#tokens.length - 1);
+        // The stream always ends with an end of file token, so there is no empty
+        // case here to invent a token for.
+        return this.#tokens[clamped];
+    }
+    // ---------------------------------------------------------------------------
+    // How it reports
+    // ---------------------------------------------------------------------------
+    report(code, span, values) {
+        // An abandoned statement has said what it has to say. Everything an
+        // unwinding parser would report after it is about the same mistake, and a
+        // file that reports two hundred unclosed brackets for one expression that
+        // was too deep has told the reader nothing.
+        if (this.#abandoned)
+            return;
+        this.#reported += 1;
+        this.#sink.report(code, span, values);
+    }
+    /**
+     * Whether this statement has already been reported on.
+     *
+     * One mistake is one diagnostic. A statement that has been reported on has
+     * nothing more to say about its own leftovers, so the second message about
+     * the same mistake is suppressed rather than the reader being left to work
+     * out which of the two to believe.
+     */
+    get reportedHere() {
+        return this.#reported > 0;
+    }
+    /**
+     * A token where the grammar had one exact thing in mind, OS1018.
+     *
+     * The catalogue has no code for "a closing bracket belongs here", so the one
+     * it does have is used for all of them: OS1018 states what is true, that the
+     * token was not expected where it sits, and its fix names the two things that
+     * are usually wrong, a missing operator or a line that lost its newline.
+     */
+    unexpected(token) {
+        this.report('OS1018', token.span, { token: describeToken(token) });
+    }
+    /**
+     * Whether one more level of expression nesting is within the ceiling.
+     *
+     * Refusing abandons the statement rather than only this level, because a
+     * parser that unwound from here would report the brackets it never reached
+     * the closers of, one per level, all of them about the expression that was
+     * already too deep.
+     */
+    deeper(span) {
+        if (this.#expressions >= MAX_NESTING) {
+            this.report('OS5005', span, {
+                construct: 'An expression',
+                found: this.#expressions + 1,
+                max: MAX_NESTING,
+            });
+            this.#abandoned = true;
+            return false;
+        }
+        this.#expressions += 1;
+        return true;
+    }
+    shallower() {
+        this.#expressions -= 1;
+    }
+    /**
+     * The same ceiling for blocks, counted across statements rather than within
+     * one, because a block's depth is the file's shape and not a line's.
+     *
+     * A refusal here costs the block and not the statement: the caller skips the
+     * whole of it, so there is nothing left inside to report on twice.
+     */
+    openBlock(span) {
+        if (this.#blocks >= MAX_NESTING) {
+            this.report('OS5005', span, {
+                construct: 'A block',
+                found: this.#blocks + 1,
+                max: MAX_NESTING,
+            });
+            return false;
+        }
+        this.#blocks += 1;
+        return true;
+    }
+    closeBlock() {
+        this.#blocks -= 1;
+    }
+    // ---------------------------------------------------------------------------
+    // The file as a whole
+    // ---------------------------------------------------------------------------
+    beginStatement() {
+        this.#reported = 0;
+        this.#expressions = 0;
+        this.#abandoned = false;
+    }
+    /**
+     * The first statement in the file, which is the line OS1021 names when a
+     * version declaration turns up below it.
+     */
+    noteStatement(line) {
+        this.#firstStatementLine ??= line;
+    }
+    get firstStatementLine() {
+        return this.#firstStatementLine;
+    }
+    /** Where the most recent `if` sat, which is what OS1016 pairs an `else` against. */
+    noteIf(column) {
+        this.#ifColumn = column;
+    }
+    get nearestIfColumn() {
+        return this.#ifColumn ?? 1;
+    }
+    /**
+     * Whether a loop body is being read, which is the whole of OS1009.
+     *
+     * It is a count on the cursor rather than an argument threaded through every
+     * rule, because the one question `break` asks is whether any loop is open,
+     * and a function body cannot be inside one: functions are top level only.
+     */
+    enterLoop() {
+        this.#loops += 1;
+    }
+    leaveLoop() {
+        this.#loops -= 1;
+    }
+    get insideLoop() {
+        return this.#loops > 0;
+    }
+    // ---------------------------------------------------------------------------
+    // How it gets out of trouble
+    // ---------------------------------------------------------------------------
+    /** To the end of this line, taking the newline, and no further. */
+    skipToEndOfLine() {
+        const before = this.#at;
+        while (!this.atStatementEnd())
+            this.advance();
+        if (this.take('newline') !== undefined)
+            return;
+        // A skip that consumed nothing leaves the loop that called it where it
+        // began, and a compiler that hangs on a malformed file is worse than one
+        // that gives up on it.
+        if (this.#at === before && !this.at('endOfFile'))
+            this.advance();
+    }
+    /**
+     * The whole statement, including a block written under it.
+     *
+     * This is the boundary to recover at when the line itself was not understood.
+     * A header the parser could not read still has its body indented beneath it,
+     * and reading that body as though it stood at the outer level would report
+     * every line of it.
+     */
+    skipStatement() {
+        this.skipToEndOfLine();
+        this.skipBlockBody();
+    }
+    /** A block, and the blocks inside it, when no statement can hold it. */
+    skipBlockBody() {
+        if (!this.at('indent'))
+            return;
+        let depth = 0;
+        do {
+            if (this.at('indent'))
+                depth += 1;
+            else if (this.at('dedent'))
+                depth -= 1;
+            this.advance();
+        } while (depth > 0 && !this.at('endOfFile'));
+    }
+}
+//# sourceMappingURL=cursor.js.map

package/dist/core/parse/cursor.js.map

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

package/dist/core/parse/expressions.d.ts

@@ -0,0 +1,57 @@
+import type { Argument, Expression } from '../ast/index.js';
+import type { Span } from '../span/index.js';
+import type { Token, TokenKind } from '../tokens/index.js';
+import type { Cursor } from './cursor.js';
+/**
+ * Whether an expression can begin here, which is what tells one argument from
+ * the next and what keeps a list from reading a closing bracket as an item.
+ *
+ * A reserved word a reader meant as a name begins one too, because `parsePrimary`
+ * reads it as the name it was meant to be rather than leaving it where it sits.
+ */
+export declare function startsExpression(kind: TokenKind): boolean;
+interface List<Item> {
+    readonly items: readonly Item[];
+    /** Where the list ended, so the node around it can reach its closing bracket. */
+    readonly end: Span;
+}
+export declare function parseExpression(cursor: Cursor): Expression;
+/**
+ * An expression in a position where a value is being tested rather than stored.
+ *
+ * `if x = 5` is the one typo the language is shaped to catch: assignment is a
+ * statement and never an expression (10.1), so there is no reading of the line
+ * that compiles, and OS1006 can name the fix instead of a type error arriving
+ * three stages later. The `==` is built as though the fix had been applied, so
+ * the rest of the file still checks.
+ */
+export declare function parseCondition(cursor: Cursor): Expression;
+/**
+ * A comma separated list inside brackets: an argument list or an array literal.
+ *
+ * The two shapes are one function because their recovery is the same and has to
+ * stay the same: a missing comma is OS1014 and the list carries on, and a list
+ * that runs to the end of the line without a closer is the bracket's own error
+ * rather than one per item.
+ */
+export declare function parseBracketedList<Item>(cursor: Cursor, open: Token, parseItem: (cursor: Cursor) => Item): List<Item>;
+/**
+ * The closing bracket, or the two ways it can be missing.
+ *
+ * OS1012 is reported at the opening bracket rather than at the end of the file,
+ * because an open bracket continues the statement onto every following line
+ * (3.11) and the mistake is where the bracket was opened.
+ */
+export declare function closeBracket(cursor: Cursor, open: Token): Span;
+/**
+ * The hole a rule leaves where an expression was required.
+ *
+ * The span is empty and sits where the expression should have been, so it never
+ * takes a caret meant for its neighbour, and everything downstream still has a
+ * tree to walk over a file that is being typed.
+ */
+export declare function missingExpression(cursor: Cursor): Expression;
+/** An argument list, for the three statements that are a call in all but name. */
+export declare function parseArgumentList(cursor: Cursor, open: Token): List<Argument>;
+export {};
+//# sourceMappingURL=expressions.d.ts.map

package/dist/core/parse/expressions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expressions.d.ts","sourceRoot":"","sources":["../../../src/core/parse/expressions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,QAAQ,EAER,UAAU,EAEX,MAAM,iBAAiB,CAAC;AAOzB,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAuC1C;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAEzD;AAED,UAAU,IAAI,CAAC,IAAI;IACjB,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC;IAChC,iFAAiF;IACjF,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC;CACpB;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAK1D;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAYzD;AAiOD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EACrC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,KAAK,EACX,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAClC,IAAI,CAAC,IAAI,CAAC,CAuCZ;AAMD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI,CAmB9D;AAUD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAE5D;AAUD,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,CAE7E"}