rooklang 0.0.0-stage → 0.3.1

package/dist/parser/statements.js

@@ -0,0 +1,267 @@
+import { SimpleStatementParser } from "./simple-statements.js";
+import { FOREIGN_KEYWORDS, FUNCTION_BODY, describe } from "./syntax.js";
+// Statements: blocks, `return`, `mount()`, and which statement a token starts.
+export class StatementParser extends SimpleStatementParser {
+    parseStatements(isEnd) {
+        const body = [];
+        this.parseSeparated(isEnd, () => {
+            body.push(this.parseStatement());
+        });
+        return body;
+    }
+    parseStatement() {
+        if (!this.context.inMarkup)
+            return this.parseOrdinaryStatement();
+        const start = this.peek().start;
+        if (this.check('JsxTagOpen')) {
+            const element = this.parseJsxElement();
+            this.endStatement();
+            return { kind: 'JsxElementStatement', element, ...this.span(start) };
+        }
+        const statement = this.parseOrdinaryStatement();
+        const allowed = statement.kind === 'IfStatement' ||
+            statement.kind === 'ForStatement' ||
+            (statement.kind === 'ForInStatement' && !statement.go) ||
+            statement.kind === 'SwitchStatement' ||
+            (statement.kind === 'VariableDeclaration' && statement.keyword === 'const');
+        if (statement.kind === 'BreakStatement' || statement.kind === 'ContinueStatement') {
+            const word = statement.kind === 'BreakStatement' ? 'break' : 'continue';
+            this.error(`"${word}" cannot be used inside markup: put the content in an if instead`, statement.start, statement.end);
+        }
+        else if (!allowed) {
+            this.error('inside markup only elements, if, for, switch and const can be written', statement.start, statement.end);
+        }
+        return statement;
+    }
+    parseOrdinaryStatement() {
+        const token = this.peek();
+        const declaration = this.parseDeclaration(token.start, false);
+        if (declaration)
+            return declaration;
+        switch (token.kind) {
+            case 'import':
+                return this.parseImport();
+            case 'export':
+                return this.parseExport();
+            case '{':
+                return this.parseBlock();
+            case 'return':
+                return this.parseReturn();
+            case 'if':
+                return this.parseIf();
+            case 'for':
+                return this.parseFor();
+            case 'go':
+                if (this.peek(1).kind === 'for')
+                    return this.parseGoFor();
+                break;
+            case 'switch':
+                return this.parseSwitch();
+            case 'break':
+            case 'continue':
+                return this.parseBreakOrContinue();
+            case 'throw':
+                return this.parseThrow();
+            case 'try':
+                return this.parseTry();
+            case 'defer':
+                return this.parseDefer();
+            default:
+                break;
+        }
+        const hint = token.kind === 'Identifier' ? FOREIGN_KEYWORDS.get(token.text) : undefined;
+        if (hint !== undefined && this.peek(1).kind === 'Identifier') {
+            this.fail(`"${token.text}" is not a Rook keyword: ${hint}`);
+        }
+        // `select` is a keyword only before `{`: elsewhere it is a name, such as a function's.
+        if (this.checkWord('select') && this.peek(1).kind === '{')
+            return this.parseSelect();
+        if (this.isStyleBlock()) {
+            // The lexer has read the block as CSS, so it is parsed as one to report a single error.
+            const style = this.parseStyle();
+            this.error(this.context.inComponent
+                ? 'style is declared at the top level of a component, not inside blocks or functions'
+                : 'style can only be declared inside a component', style.start, style.start + 'style'.length);
+            this.endStatement();
+            return style;
+        }
+        const misplaced = this.isStateDeclaration() || this.isRefDeclaration()
+            ? this.peek().text
+            : this.isMountDeclaration()
+                ? 'mount()'
+                : this.isEffectDeclaration()
+                    ? 'effect'
+                    : null;
+        if (misplaced !== null) {
+            this.fail(this.context.inComponent
+                ? `${misplaced} is declared at the top level of a component, not inside blocks or functions`
+                : `${misplaced} can only be declared inside a component`);
+        }
+        const statement = this.parseSimpleStatement();
+        if (statement.kind === 'ExpressionStatement') {
+            const { expression } = statement;
+            // `await save()` and `<-done` wait for something.
+            const awaited = expression.kind === 'UnaryExpression' &&
+                (expression.operator === 'await' || expression.operator === '<-');
+            const call = expression.kind === 'CallExpression' ||
+                expression.kind === 'NewExpression' ||
+                expression.kind === 'GoExpression';
+            if (!call && !awaited) {
+                this.error('this expression does nothing: only function calls can be used as statements', expression.start, expression.end);
+            }
+        }
+        this.endStatement();
+        return statement;
+    }
+    /** Parses a declaration if the current token starts one, otherwise returns `undefined`. */
+    parseDeclaration(start, exported) {
+        switch (this.peek().kind) {
+            case 'func':
+                // `func(...)` without a name is a function literal, e.g. one that is called right away.
+                if (this.peek(1).kind !== 'Identifier')
+                    return undefined;
+                return this.parseFuncDeclaration(start, exported);
+            case 'async':
+                if (this.peek(1).kind === 'comp') {
+                    this.fail('a component cannot be async: load the data in mount() or in an async func');
+                }
+                if (this.peek(1).kind !== 'func' || this.peek(2).kind !== 'Identifier')
+                    return undefined;
+                return this.parseFuncDeclaration(start, exported);
+            case 'let':
+            case 'const': {
+                const declaration = this.parseVariableDeclaration(start, exported);
+                this.endStatement();
+                return declaration;
+            }
+            case 'class':
+                return this.parseClass(start, exported);
+            case 'comp':
+                return this.parseComponent(start, exported);
+            case '@':
+                // `@visible.show()` is a call; `@html-tag comp Page() {...}` and
+                // `@visible("300px") export comp Page() {...}` are components with decorators.
+                if (this.isDecoratorMember())
+                    return undefined;
+                return this.parseDecorated(start, exported);
+            case 'interface':
+                return this.parseInterface(start, exported);
+            case 'type': {
+                const declaration = this.parseTypeAlias(start, exported);
+                this.endStatement();
+                return declaration;
+            }
+            default:
+                if (this.isDecoratorDeclaration())
+                    return this.parseDecoratorDeclaration(start, exported);
+                return undefined;
+        }
+    }
+    /** A statement ends with a newline or `;`, or right before the `}` that closes its block. */
+    endStatement() {
+        if (this.accept(';') || this.check('}') || this.check('EOF'))
+            return;
+        const token = this.peek();
+        if (token.kind === '++' || token.kind === '--') {
+            this.fail(`"${token.kind}" is a statement and cannot be used inside an expression`);
+        }
+        this.fail(`expected newline or ";" after statement, found ${describe(token)}`);
+    }
+    /**
+     * `state count = 0` or `derived double = count * 2`: `state` and `derived` are keywords only at
+     * the start of a statement in a component.
+     */
+    isStateDeclaration() {
+        return ((this.checkWord('state') || this.checkWord('derived')) && this.peek(1).kind === 'Identifier');
+    }
+    /** `ref input`: like `state`, a keyword only at the start of a statement in a component. */
+    isRefDeclaration() {
+        return this.checkWord('ref') && this.peek(1).kind === 'Identifier';
+    }
+    /** `style {`: the lexer reads the block as CSS where it starts a statement. */
+    isStyleBlock() {
+        return this.checkWord('style') && this.peek(1).kind === '{';
+    }
+    /** `style { ... }`: CSS text and, in the values of declarations, `{expression}`. */
+    parseStyle() {
+        const { start } = this.next();
+        const parts = [];
+        this.expect('{');
+        while (!this.check('}') && !this.check('EOF')) {
+            const token = this.peek();
+            if (token.kind === 'CssText') {
+                this.next();
+                parts.push({ kind: 'CssText', value: token.value, start: token.start, end: token.end });
+            }
+            else {
+                this.expect('{');
+                parts.push(this.withContext({ noObjectLiteral: false }, () => this.parseExpression()));
+                this.expect('}');
+            }
+        }
+        this.expect('}');
+        return { kind: 'StyleStatement', parts, ...this.span(start) };
+    }
+    /** `effect {`: like `state`, a keyword only at the start of a statement in a component. */
+    isEffectDeclaration() {
+        return this.checkWord('effect') && this.peek(1).kind === '{';
+    }
+    /** `mount() {`: like `state`, a keyword only at the start of a statement in a component. */
+    isMountDeclaration() {
+        return (this.checkWord('mount') &&
+            this.peek(1).kind === '(' &&
+            this.peek(2).kind === ')' &&
+            this.peek(3).kind === '{');
+    }
+    /** `mount() { ... }`; its body is a function that runs later, so `return` is its own. */
+    parseMount() {
+        const { start } = this.next();
+        this.expect('(');
+        this.expect(')');
+        const body = this.withContext({ ...FUNCTION_BODY, inComponent: true }, () => this.parseBlock());
+        return { kind: 'MountStatement', body, ...this.span(start) };
+    }
+    /** `effect { ... }`: its body runs again later, so `return` and `defer` are its own. */
+    parseEffect() {
+        const { start } = this.next();
+        const body = this.withContext({ ...FUNCTION_BODY, inComponent: true }, () => this.parseBlock());
+        return { kind: 'EffectStatement', body, ...this.span(start) };
+    }
+    parseBlock() {
+        const start = this.expect('{').start;
+        const body = this.withContext({ topLevel: false, noObjectLiteral: false }, () => this.parseStatements(() => this.check('}')));
+        this.expect('}');
+        return { kind: 'BlockStatement', body, ...this.span(start) };
+    }
+    parseFunctionBody(async = false) {
+        return this.withContext({ ...FUNCTION_BODY, inAsync: async }, () => this.parseBlock());
+    }
+    /** An if/for/switch header, where `{` starts the block rather than an object literal. */
+    parseHeaderExpression() {
+        return this.withContext({ noObjectLiteral: true }, () => this.parseExpression());
+    }
+    parseReturn() {
+        const start = this.next().start;
+        if (this.context.inGoFor) {
+            this.error('"return" cannot leave "go for": its body runs in workers; skip an element with "continue"', start, this.span(start).end);
+        }
+        else if (!this.context.inFunction) {
+            this.error('"return" outside of a function', start, this.span(start).end);
+        }
+        else if (this.context.inDefer) {
+            this.error('"return" is not allowed inside "defer"', start, this.span(start).end);
+        }
+        const values = this.check(';') || this.check('}') || this.check('EOF') ? [] : this.parseExpressionList();
+        const statement = { kind: 'ReturnStatement', values, ...this.span(start) };
+        this.endStatement();
+        return statement;
+    }
+    /** `}` + newline + `else`: the newline ends the `if`, so explain the error instead of failing. */
+    checkSameLine(keyword) {
+        if (this.isImplicitSemicolon() && this.peek(1).kind === keyword) {
+            const token = this.peek(1);
+            this.error(`"${keyword}" must be on the same line as the closing "}"`, token.start, token.end);
+            this.next();
+        }
+    }
+}

package/dist/parser/syntax.d.ts

@@ -0,0 +1,51 @@
+import type * as ast from '../ast.ts';
+import type { StringToken, Token, TokenKind } from '../lexer/token.ts';
+/** Binary operators and their precedence (higher binds tighter), as in JS. */
+export declare const BINARY_PRECEDENCE: Readonly<Record<ast.BinaryOperator, number>>;
+export declare const UNARY_OPERATORS: ReadonlySet<string>;
+export declare const ASSIGNMENT_OPERATORS: ReadonlySet<string>;
+export declare function isBinaryOperator(kind: TokenKind): kind is ast.BinaryOperator;
+export declare function isUnaryOperator(kind: TokenKind): kind is ast.UnaryOperator;
+export declare function isAssignmentOperator(kind: TokenKind): kind is ast.AssignmentOperator;
+export declare const RESERVED: ReadonlySet<string>;
+export declare const MODIFIERS: ReadonlySet<string>;
+/** Words from JS that Rook spells differently. */
+export declare const FOREIGN_KEYWORDS: ReadonlyMap<string, string>;
+/** Keywords that start a statement; used to find where to resume after a syntax error. */
+export declare const STATEMENT_KEYWORDS: ReadonlySet<TokenKind>;
+/** Closing brackets and the opening brackets they match. */
+export declare const BRACKETS: Readonly<Partial<Record<TokenKind, TokenKind>>>;
+export interface Context {
+    /** At the top level of the module, where imports and exports are allowed. */
+    topLevel: boolean;
+    inFunction: boolean;
+    inLoop: boolean;
+    /** Inside a loop or switch, where `break` is allowed. */
+    inBreakable: boolean;
+    inDefer: boolean;
+    /** In the body of `go for`, which `return` and `break` cannot leave. */
+    inGoFor: boolean;
+    /** In an async function or at the top level of the module, where `await` is allowed. */
+    inAsync: boolean;
+    /** In an if/for/switch header, where `{` starts the block rather than an object literal. */
+    noObjectLiteral: boolean;
+    /** Inside a component, for the error about `state` in a nested block. */
+    inComponent: boolean;
+    /** In the blocks of `{if ...}` and `{for ...}` inside markup, where elements are statements. */
+    inMarkup: boolean;
+}
+export declare const FUNCTION_BODY: Partial<Context>;
+/** Thrown to abandon the current statement after its syntax error has been reported. */
+export declare class ParseError extends Error {
+}
+export declare function describe(token: Token): string;
+export declare function plural(count: number, word: string): string;
+/** The text of a template part without its delimiters: "`" or "}" before it, "`" or "${" after it. */
+/**
+ * Whitespace in markup text as in JSX: lines are trimmed and joined with a space, and lines with
+ * only whitespace disappear. Text without line breaks is kept as it is.
+ */
+export declare function cleanJsxText(text: string): string;
+/** In `on*` attributes, these are the handler itself rather than code to run. */
+export declare function isHandlerReference(node: ast.Expression): boolean;
+export declare function templateElement(token: StringToken): ast.TemplateElement;

package/dist/parser/syntax.js

@@ -0,0 +1,173 @@
+// Tables and small functions of the parser: operators and their precedence, keywords, the parsing context.
+/** Binary operators and their precedence (higher binds tighter), as in JS. */
+export const BINARY_PRECEDENCE = {
+    '??': 1,
+    '||': 2,
+    '&&': 3,
+    '|': 4,
+    '^': 5,
+    '&': 6,
+    '==': 7,
+    '!=': 7,
+    '<': 8,
+    '>': 8,
+    '<=': 8,
+    '>=': 8,
+    instanceof: 8,
+    '<<': 9,
+    '>>': 9,
+    '>>>': 9,
+    '+': 10,
+    '-': 10,
+    '*': 11,
+    '/': 11,
+    '%': 11,
+    '**': 12,
+};
+export const UNARY_OPERATORS = new Set([
+    '!',
+    '-',
+    '+',
+    '~',
+    'typeof',
+    'await',
+    '<-',
+]);
+export const ASSIGNMENT_OPERATORS = new Set([
+    '=',
+    '+=',
+    '-=',
+    '*=',
+    '/=',
+    '%=',
+    '**=',
+    '&=',
+    '|=',
+    '^=',
+    '<<=',
+    '>>=',
+    '>>>=',
+    '&&=',
+    '||=',
+    '??=',
+]);
+export function isBinaryOperator(kind) {
+    return Object.hasOwn(BINARY_PRECEDENCE, kind);
+}
+export function isUnaryOperator(kind) {
+    return UNARY_OPERATORS.has(kind);
+}
+export function isAssignmentOperator(kind) {
+    return ASSIGNMENT_OPERATORS.has(kind);
+}
+export const RESERVED = new Set(['map']);
+export const MODIFIERS = new Set(['public', 'protected', 'private', 'static']);
+/** Words from JS that Rook spells differently. */
+export const FOREIGN_KEYWORDS = new Map([
+    ['function', 'declare functions with "func"'],
+    ['var', 'declare variables with "let" or "const"'],
+    ['while', 'write loops as "for condition { ... }"'],
+]);
+/** Keywords that start a statement; used to find where to resume after a syntax error. */
+export const STATEMENT_KEYWORDS = new Set([
+    'import',
+    'export',
+    'func',
+    'comp',
+    'let',
+    'const',
+    'class',
+    'interface',
+    'type',
+    'return',
+    'if',
+    'for',
+    'switch',
+    'break',
+    'continue',
+    'throw',
+    'try',
+    'defer',
+]);
+/** Closing brackets and the opening brackets they match. */
+export const BRACKETS = {
+    ')': '(',
+    ']': '[',
+    '}': '{',
+    TemplateTail: 'TemplateHead',
+};
+export const FUNCTION_BODY = {
+    topLevel: false,
+    inFunction: true,
+    inLoop: false,
+    inBreakable: false,
+    inDefer: false,
+    inGoFor: false,
+    inAsync: false,
+    noObjectLiteral: false,
+    inMarkup: false,
+};
+/** Thrown to abandon the current statement after its syntax error has been reported. */
+export class ParseError extends Error {
+}
+export function describe(token) {
+    switch (token.kind) {
+        case 'EOF':
+            return 'end of file';
+        case ';':
+            return token.text === '' ? 'newline' : '";"';
+        case 'String':
+            return 'string';
+        case 'Number':
+            return `number ${token.text}`;
+        case 'BigInt':
+            return `bigint ${token.text}`;
+        case 'Template':
+        case 'TemplateHead':
+            return 'template literal';
+        default:
+            return `"${token.text}"`;
+    }
+}
+export function plural(count, word) {
+    return `${count} ${word}${count === 1 ? '' : 's'}`;
+}
+/** The text of a template part without its delimiters: "`" or "}" before it, "`" or "${" after it. */
+/**
+ * Whitespace in markup text as in JSX: lines are trimmed and joined with a space, and lines with
+ * only whitespace disappear. Text without line breaks is kept as it is.
+ */
+export function cleanJsxText(text) {
+    const lines = text.split(/\r?\n/);
+    const kept = [];
+    lines.forEach((line, i) => {
+        let part = line.replace(/\t/g, ' ');
+        if (i > 0)
+            part = part.trimStart();
+        if (i < lines.length - 1)
+            part = part.trimEnd();
+        if (part !== '')
+            kept.push(part);
+    });
+    return kept.join(' ');
+}
+/** In `on*` attributes, these are the handler itself rather than code to run. */
+export function isHandlerReference(node) {
+    if (node.kind === 'Identifier' ||
+        node.kind === 'ArrowFunction' ||
+        node.kind === 'FuncExpression') {
+        return true;
+    }
+    return node.kind === 'MemberExpression' && !node.optional && isHandlerReference(node.object);
+}
+export function templateElement(token) {
+    const text = token.text;
+    const end = text.endsWith('${') ? -2 : text.length > 1 && text.endsWith('`') ? -1 : text.length;
+    return {
+        kind: 'TemplateElement',
+        value: token.value,
+        raw: text.slice(1, end),
+        start: token.start,
+        end: token.end,
+    };
+}

package/dist/parser/types.d.ts

@@ -0,0 +1,23 @@
+import type * as ast from '../ast.ts';
+import { ClassParser } from './classes.ts';
+export declare abstract class TypeParser extends ClassParser {
+    /** `<number, string>` after the name of a generic type. */
+    protected parseTypeArgs(): ast.TypeNode[];
+    protected canStartType(): boolean;
+    /** A type, possibly a union: `string | number`. */
+    protected parseType(): ast.TypeNode;
+    protected parsePrimaryType(): ast.TypeNode;
+    /**
+     * Grouping, `[](string | number)`, or a function type written as an arrow,
+     * `(paths []string) => Shape`, the same as `func([]string) Shape`. Its parameters may have
+     * names, which only document them.
+     */
+    protected parseParenthesizedType(): ast.TypeNode;
+    /** The type of a parameter of a function type, after its name if it has one, kept in `names`. */
+    private parseParamType;
+    /** `paths []string` in `(paths []string) => Shape`: a name before the type of a parameter. */
+    private startsNamedParam;
+    /** `{ name string; x, y number; area() number }`, separated by newlines, `;` or `,`. */
+    protected parseTypeMembers(): ast.TypeMember[];
+    protected parseTypeMember(): ast.TypeMember[];
+}