@chilts/weave 0.6.0 → 0.8.0

package/dist/lexer/index.js

@@ -19,8 +19,24 @@ const KEYWORDS = new Set([
     'include',
     'doctype',
     'if',
+    'unless',
     'for',
 ]);
+// Pug's 'block append' / 'block prepend' have no Weave form: a page fills
+// a block by replacing it, so extra content needs a slot of its own.
+const APPEND_HINT = "there is no 'append' or 'prepend'; add a second, empty slot to the layout " +
+    "(e.g. 'block pageScripts' after 'block scripts') and fill that instead";
+// Pug keywords with no Weave equivalent, and what to write instead. Without
+// this they lex as elements and render as e.g. <case> and <when>.
+const PUG_KEYWORDS = new Map([
+    ['case', "use 'if' / 'else if' / 'else' instead of 'case' / 'when'"],
+    ['when', "use 'if' / 'else if' / 'else' instead of 'case' / 'when'"],
+    ['default', "use 'else' instead of 'case' / 'default'"],
+    ['each', "use 'for ( const item of items )' instead of 'each'"],
+    ['while', "iterate with 'for ( const item of items )' instead of 'while'"],
+    ['append', APPEND_HINT],
+    ['prepend', APPEND_HINT],
+]);
 class Lexer {
     lines;
     lineIndex = 0;
@@ -54,7 +70,9 @@ class Lexer {
                     }
                     // Preserve indentation relative to the base
                     const text = rawLine.slice(this.rawBlockBaseIndent);
-                    this.emit('RAW_TEXT', text);
+                    // The cursor still belongs to the previous line, so anchor
+                    // explicitly on this line's first non-space character.
+                    this.emit('RAW_TEXT', text, 0);
                     this.emit('NEWLINE', '');
                     continue;
                 }
@@ -196,6 +214,9 @@ class Lexer {
             case 'if':
                 this.scanIf();
                 break;
+            case 'unless':
+                this.scanUnless();
+                break;
             case 'for':
                 this.scanFor();
                 break;
@@ -225,70 +246,78 @@ class Lexer {
     }
     scanBlock() {
         this.emit('BLOCK', 'block');
-        const name = this.currentLine.slice('block '.length).trim();
-        this.emit('IDENTIFIER', name);
+        const nameStart = this.skipSpacesFrom('block '.length);
+        const name = this.currentLine.slice(nameStart).trim();
+        // A bare 'block' (mixin call-site content) has no name.
+        if (name !== '' && !/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
+            const word = name.split(/\s/)[0];
+            const message = word === 'append' || word === 'prepend'
+                ? `'block ${word}' is not supported; ${APPEND_HINT}`
+                : `Block name '${name}' must be a single identifier`;
+            throw new LexerError(message, this.lineIndex + 1, this.indentWidth + nameStart + 1);
+        }
+        this.emit('IDENTIFIER', name, nameStart);
         this.pos = this.currentLine.length;
     }
     scanInclude() {
         this.emit('INCLUDE', 'include');
-        const path = this.currentLine.slice('include '.length).trim();
-        this.emit('PATH', path);
+        const pathStart = this.skipSpacesFrom('include '.length);
+        const path = this.currentLine.slice(pathStart).trim();
+        this.emit('PATH', path, pathStart);
         this.pos = this.currentLine.length;
     }
     // --- Declaration scanners ---
     scanTemplate() {
+        this.emit('TEMPLATE', 'template', 0);
         this.pos = 'template '.length;
-        this.emit('TEMPLATE', 'template');
+        const nameStart = this.pos;
         const name = this.scanIdentifier();
-        this.emit('IDENTIFIER', name);
-        if (this.pos < this.currentLine.length && this.currentLine[this.pos] === '(') {
-            const params = this.scanBalancedParens();
-            this.emit('PARAMS', params);
-        }
+        this.emit('IDENTIFIER', name, nameStart);
+        this.scanParamsIfPresent();
     }
     scanMixin() {
+        this.emit('MIXIN', 'mixin', 0);
         this.pos = 'mixin '.length;
-        this.emit('MIXIN', 'mixin');
+        const nameStart = this.pos;
         const name = this.scanIdentifier();
-        this.emit('IDENTIFIER', name);
-        if (this.pos < this.currentLine.length && this.currentLine[this.pos] === '(') {
-            const params = this.scanBalancedParens();
-            this.emit('PARAMS', params);
-        }
+        this.emit('IDENTIFIER', name, nameStart);
+        this.scanParamsIfPresent();
     }
     scanExtends() {
+        this.emit('EXTENDS', 'extends', 0);
         this.pos = 'extends '.length;
-        this.emit('EXTENDS', 'extends');
+        const nameStart = this.pos;
         const name = this.scanIdentifier();
-        this.emit('IDENTIFIER', name);
-        if (this.pos < this.currentLine.length && this.currentLine[this.pos] === '(') {
-            const params = this.scanBalancedParens();
-            this.emit('PARAMS', params);
-        }
+        this.emit('IDENTIFIER', name, nameStart);
+        this.scanParamsIfPresent();
     }
     // --- Control flow scanners ---
     scanIf() {
+        this.emit('IF', 'if', 0);
         this.pos = 'if '.length;
-        this.emit('IF', 'if');
+        const expr = this.currentLine.slice(this.pos);
+        this.emit('BUFFERED_CODE', expr);
+        this.pos = this.currentLine.length;
+    }
+    scanUnless() {
+        this.emit('UNLESS', 'unless', 0);
+        this.pos = 'unless '.length;
         const expr = this.currentLine.slice(this.pos);
         this.emit('BUFFERED_CODE', expr);
         this.pos = this.currentLine.length;
     }
     scanElseIf() {
+        this.emit('ELSE_IF', 'else if', 0);
         this.pos = 'else if '.length;
-        this.emit('ELSE_IF', 'else if');
         const expr = this.currentLine.slice(this.pos);
         this.emit('BUFFERED_CODE', expr);
         this.pos = this.currentLine.length;
     }
     scanFor() {
+        this.emit('FOR', 'for', 0);
         this.pos = 'for '.length;
-        this.emit('FOR', 'for');
         this.skipSpaces();
-        if (this.pos < this.currentLine.length && this.currentLine[this.pos] === '(') {
-            const params = this.scanBalancedParens();
-            this.emit('PARAMS', params);
-        }
+        this.scanParamsIfPresent();
     }
     // --- Element scanner ---
     scanElement() {
@@ -301,8 +330,10 @@ class Lexer {
             this.emit('TAG', 'div');
         }
         else {
+            const tagStart = this.pos;
             const tag = this.scanTagName();
-            this.emit('TAG', tag);
+            this.checkTagName(tag, tagStart);
+            this.emit('TAG', tag, tagStart);
         }
         // Classes and IDs
         this.scanClassesAndIds();
@@ -311,11 +342,19 @@ class Lexer {
             this.emit('ATTR_START', '(');
             this.pos++; // skip '('
             this.scanAttributes(elementIndent);
-            this.emit('ATTR_END', ')');
+            this.emit('ATTR_END', ')', this.pos - 1);
         }
         // Raw block: tag!
         if (this.pos < this.currentLine.length && this.currentLine[this.pos] === '!') {
             this.pos++; // skip !
+            // Anything after the '!' used to be dropped without a word, which
+            // silently lost the expression in Pug's unescaped 'p!= html'.
+            const rest = this.currentLine.slice(this.pos);
+            if (rest.trim() !== '') {
+                throw new LexerError(rest.startsWith('=')
+                    ? "Unescaped buffered code ('!=') is not supported; use '= raw(expr)' instead"
+                    : "A raw block 'tag!' takes no content on its own line; put the raw text on indented lines below it", this.lineIndex + 1, this.indentWidth + this.pos);
+            }
             this.rawBlockIndent = elementIndent;
             this.rawBlockBaseIndent = null;
             return;
@@ -336,36 +375,93 @@ class Lexer {
         }
         return this.currentLine.slice(start, this.pos);
     }
+    // Rejects tag names that can't be an element. Pug syntax Weave doesn't
+    // have used to land here and come out as bogus elements: '- const x = 1'
+    // became a '-' element and 'case'/'when' became <case>/<when>.
+    checkTagName(tag, tagStart) {
+        let message = null;
+        if (tag.startsWith('-')) {
+            message =
+                "Unbuffered code ('- ...') is not supported; templates hold no statements. " +
+                    "Compute values in TypeScript before rendering, or use a buffered expression 'tag= expr'";
+        }
+        else if (tag === '') {
+            message = `Unexpected '${this.currentLine[tagStart]}'; expected a tag name, '.class' or '#id'`;
+        }
+        else if (!/^[a-zA-Z]/.test(tag)) {
+            message = `Tag name '${tag}' must start with a letter`;
+        }
+        else if (PUG_KEYWORDS.has(tag)) {
+            message = `'${tag}' is not a Weave keyword; ${PUG_KEYWORDS.get(tag)}`;
+        }
+        if (message !== null) {
+            throw new LexerError(message, this.lineIndex + 1, this.indentWidth + tagStart + 1);
+        }
+    }
     scanClassesAndIds() {
+        let prevClass = null;
         while (this.pos < this.currentLine.length) {
             const ch = this.currentLine[this.pos];
             if (ch === '.') {
+                const dotPos = this.pos;
+                const dotCol = this.indentWidth + dotPos + 1;
                 this.pos++; // skip dot
-                const start = this.pos;
-                while (this.pos < this.currentLine.length) {
-                    const c = this.currentLine[this.pos];
-                    if (c === ' ' || c === '(' || c === '#' || c === '.' || c === '=' || c === '!')
-                        break;
-                    this.pos++;
+                const { name, raw } = this.scanShorthandName();
+                if (name === '') {
+                    // Pug's 'p.' block text emitted class="" and then lexed
+                    // the text lines below it as elements.
+                    throw new LexerError(this.pos >= this.currentLine.length
+                        ? "Block text ('tag.') is not supported; use 'tag!' for raw text, or '|' lines for escaped text"
+                        : "Expected a class name after '.'", this.lineIndex + 1, dotCol);
                 }
-                this.emit('CLASS', this.currentLine.slice(start, this.pos));
+                // A dot is a class separator, so '.gap-1.5' silently became
+                // 'gap-1' plus a stray '5'. A class that is a bare number is
+                // almost certainly that mistake, so reject it and name the fix.
+                if (/^[0-9]+$/.test(name)) {
+                    const example = prevClass === null ? `.gap-1\\.${name}` : `.${prevClass}\\.${name}`;
+                    const split = prevClass === null ? '' : ` ('.${prevClass}.${name}' was split into '${prevClass}' and '${name}')`;
+                    throw new LexerError(`Class '.${name}' is a bare number; a dot inside a class name is read as a separator${split}. ` +
+                        `Escape the dot with a backslash, e.g. '${example}'`, this.lineIndex + 1, dotCol);
+                }
+                prevClass = raw;
+                this.emit('CLASS', name, dotPos);
             }
             else if (ch === '#') {
+                const hashPos = this.pos;
                 this.pos++; // skip hash
-                const start = this.pos;
-                while (this.pos < this.currentLine.length) {
-                    const c = this.currentLine[this.pos];
-                    if (c === ' ' || c === '(' || c === '#' || c === '.' || c === '=' || c === '!')
-                        break;
-                    this.pos++;
+                prevClass = null;
+                const { name } = this.scanShorthandName();
+                if (name === '') {
+                    throw new LexerError("Expected an id after '#'", this.lineIndex + 1, this.indentWidth + hashPos + 1);
                 }
-                this.emit('ID', this.currentLine.slice(start, this.pos));
+                this.emit('ID', name, hashPos);
             }
             else {
                 break;
             }
         }
     }
+    // Scans a class or id name after its '.' or '#'. A backslash-escaped dot
+    // ('\.') is a literal dot rather than the start of the next class, so
+    // Tailwind's 'gap-1\.5' is a single class 'gap-1.5'. Returns the unescaped
+    // name and the source text it came from.
+    scanShorthandName() {
+        const start = this.pos;
+        let name = '';
+        while (this.pos < this.currentLine.length) {
+            const c = this.currentLine[this.pos];
+            if (c === '\\' && this.currentLine[this.pos + 1] === '.') {
+                name += '.';
+                this.pos += 2;
+                continue;
+            }
+            if (c === ' ' || c === '(' || c === '#' || c === '.' || c === '=' || c === '!')
+                break;
+            name += c;
+            this.pos++;
+        }
+        return { name, raw: this.currentLine.slice(start, this.pos) };
+    }
     // Scans an attribute list, with the cursor just past the opening '('.
     // `ownerIndent` is the indent of the element or mixin call that owns the
     // list, which bounds the multi-line form.
@@ -461,6 +557,7 @@ class Lexer {
     // Scans a single `...spread`, `name` or `name=value`, with the cursor on
     // its first character.
     scanAttribute() {
+        const start = this.pos;
         // Spread: ...identifier
         if (this.currentLine[this.pos] === '.' &&
             this.pos + 2 < this.currentLine.length &&
@@ -468,7 +565,7 @@ class Lexer {
             this.currentLine[this.pos + 2] === '.') {
             this.pos += 3; // skip ...
             const name = this.scanIdentifier();
-            this.emit('SPREAD', name);
+            this.emit('SPREAD', name, start);
             return;
         }
         // Attribute name
@@ -480,14 +577,15 @@ class Lexer {
             // Without this guard the caller's loop spins forever emitting
             // empty ATTR_NAME tokens until the process aborts.
             throw new LexerError(`Unexpected '${this.currentLine[this.pos]}' in attribute list; ` +
-                `wrap complex attribute values in (parentheses) or \`backticks\``, this.lineIndex + 1, this.indentWidth + this.pos + 1);
+                'wrap complex attribute values in (parentheses) or `backticks`', this.lineIndex + 1, this.indentWidth + this.pos + 1);
         }
-        this.emit('ATTR_NAME', name);
+        this.emit('ATTR_NAME', name, start);
         // Check for = value
         if (this.pos < this.currentLine.length && this.currentLine[this.pos] === '=') {
             this.pos++; // skip =
+            const valueStart = this.pos;
             const value = this.scanAttrValue();
-            this.emit('ATTR_VALUE', value);
+            this.emit('ATTR_VALUE', value, valueStart);
         }
     }
     scanAttrName() {
@@ -565,25 +663,49 @@ class Lexer {
             this.pos = this.currentLine.length;
             return;
         }
+        // Anything else used to be dropped along with the rest of the line,
+        // e.g. the child in Pug's block expansion 'li: a(href="/") Home'.
+        let message;
+        if (ch === ':') {
+            message =
+                "Block expansion ('tag: child') is not supported; " +
+                    'put the child element on its own indented line';
+        }
+        else if (ch === '/') {
+            message = "Self-closing 'tag/' is not supported; void elements like 'br' and 'img' close themselves";
+        }
+        else {
+            message = `Unexpected '${ch}' after element; separate inline text from the tag with a space`;
+        }
+        throw new LexerError(message, this.lineIndex + 1, this.indentWidth + this.pos + 1);
     }
     // --- Mixin call scanner ---
     scanMixinCall() {
         const elementIndent = this.indentWidth;
         this.pos = 1; // skip +
         const name = this.scanIdentifier();
-        this.emit('MIXIN_CALL', name);
+        // Anchored on the '+', not where the name scan left the cursor.
+        this.emit('MIXIN_CALL', name, 0);
         // Args in first set of parens
-        if (this.pos < this.currentLine.length && this.currentLine[this.pos] === '(') {
-            const args = this.scanBalancedParens();
-            this.emit('PARAMS', args);
-        }
+        this.scanParamsIfPresent();
         // Extra attrs in second set of parens
         if (this.pos < this.currentLine.length && this.currentLine[this.pos] === '(') {
             this.emit('ATTR_START', '(');
             this.pos++; // skip '('
             this.scanAttributes(elementIndent);
-            this.emit('ATTR_END', ')');
+            this.emit('ATTR_END', ')', this.pos - 1);
+        }
+        // One line of call-site content may follow, as for an element:
+        // '+btn("x") Save' or '+btn("x")= label'. Trailing spaces alone are
+        // not content.
+        const rest = this.currentLine.slice(this.pos);
+        if (rest.trim() === '')
+            return;
+        if (rest[0] === ' ' || rest[0] === '=') {
+            this.scanTrailingContent();
+            return;
         }
+        throw new LexerError(`Unexpected '${rest[0]}' after mixin call; separate inline content from the call with a space`, this.lineIndex + 1, this.indentWidth + this.pos + 1);
     }
     // --- Pipe scanner ---
     scanPipe() {
@@ -599,17 +721,31 @@ class Lexer {
         this.pos = this.currentLine.length;
     }
     // --- Text with interpolation ---
+    // `text` is the rest of the current line from the cursor, so an offset
+    // into it plus the cursor is that character's position on the line.
     scanTextWithInterpolation(text) {
         let i = 0;
         let buf = '';
+        let bufStart = 0;
         while (i < text.length) {
+            // Pug's tag interpolation '#[strong x]' and unescaped '!{html}'
+            // used to pass through as literal text, so the markup characters
+            // rendered (escaped) on the page.
+            if ((text[i] === '#' && text[i + 1] === '[') || (text[i] === '!' && text[i + 1] === '{')) {
+                throw new LexerError((text[i] === '#'
+                    ? "Tag interpolation ('#[tag ...]') is not supported; put the element on its own " +
+                        "indented line, with '|' lines for the text around it"
+                    : "Unescaped interpolation ('!{...}') is not supported; use '#{raw(expr)}' instead") +
+                    `. For literal '${text.slice(i, i + 2)}' text, use a string expression: 'tag= "..."'`, this.lineIndex + 1, this.indentWidth + this.pos + i + 1);
+            }
             // Check for interpolation #{...}
             if (text[i] === '#' && i + 1 < text.length && text[i + 1] === '{') {
                 // Emit accumulated text
                 if (buf.length > 0) {
-                    this.emit('TEXT', buf);
+                    this.emit('TEXT', buf, this.pos + bufStart);
                     buf = '';
                 }
+                const interpStart = i;
                 i += 2; // skip #{
                 // Scan balanced braces to find closing }
                 let depth = 1;
@@ -641,10 +777,11 @@ class Lexer {
                     i++;
                 }
                 if (depth !== 0) {
-                    throw new LexerError('Unterminated interpolation', this.lineIndex + 1, this.indentWidth + this.pos + 1);
+                    throw new LexerError('Unterminated interpolation', this.lineIndex + 1, this.indentWidth + this.pos + interpStart + 1);
                 }
-                this.emit('INTERPOLATION', text.slice(start, i));
+                this.emit('INTERPOLATION', text.slice(start, i), this.pos + interpStart);
                 i++; // skip closing }
+                bufStart = i;
             }
             else {
                 buf += text[i];
@@ -653,42 +790,125 @@ class Lexer {
         }
         // Emit remaining text
         if (buf.length > 0) {
-            this.emit('TEXT', buf);
+            this.emit('TEXT', buf, this.pos + bufStart);
         }
     }
     // --- Balanced scanning helpers ---
+    // Scans a '(...)' group whose contents are captured verbatim (params, for
+    // headers, mixin call args), with the cursor on the '('. Returns the text
+    // between the parens.
+    //
+    // The group may span lines: it simply stays open until its parens balance.
+    // Unlike a multi-line attribute list there is no required shape, so the
+    // way TypeScript is usually wrapped works as written:
+    //
+    //   template dashboard({
+    //       title,
+    //   }: DashboardProps)
+    //
+    // Continuation lines are consumed here, so they never reach the main loop
+    // and produce no INDENT/DEDENT/NEWLINE tokens. They keep their indentation
+    // relative to the line that opened the group. `//` comments are dropped:
+    // the captured text is re-emitted inside a single expression, where a
+    // comment would swallow whatever the compiler appends after it.
     scanBalancedParens() {
         if (this.currentLine[this.pos] !== '(') {
             throw new LexerError('Expected opening parenthesis', this.lineIndex + 1, this.indentWidth + this.pos + 1);
         }
+        const ownerIndent = this.indentWidth;
+        const openLine = this.lineIndex + 1;
+        const openCol = this.indentWidth + this.pos + 1;
         this.pos++; // skip opening (
         let depth = 1;
-        const start = this.pos;
-        while (this.pos < this.currentLine.length && depth > 0) {
-            const ch = this.currentLine[this.pos];
-            if (ch === '(') {
-                depth++;
-                this.pos++;
-            }
-            else if (ch === ')') {
-                depth--;
-                if (depth === 0)
-                    break;
-                this.pos++;
+        const pieces = [];
+        const starts = [];
+        let prefix = ''; // this line's indentation relative to the owner
+        for (;;) {
+            const start = this.pos;
+            let end = -1; // where this line's content stops: the closing ')' or a comment
+            while (this.pos < this.currentLine.length) {
+                const ch = this.currentLine[this.pos];
+                if (ch === '(') {
+                    depth++;
+                    this.pos++;
+                }
+                else if (ch === ')') {
+                    depth--;
+                    if (depth === 0) {
+                        end = this.pos;
+                        break;
+                    }
+                    this.pos++;
+                }
+                else if (ch === '"' || ch === "'" || ch === '`') {
+                    const quotePos = this.pos;
+                    if (!this.skipStringInPlace(ch)) {
+                        // A string has to close on its own line; letting it run
+                        // on would throw the paren count off for every line after.
+                        throw new LexerError('Unterminated string', this.lineIndex + 1, this.indentWidth + quotePos + 1);
+                    }
+                }
+                else if (ch === '/' && this.currentLine[this.pos + 1] === '/') {
+                    end = this.pos;
+                    this.pos = this.currentLine.length;
+                }
+                else {
+                    this.pos++;
+                }
             }
-            else if (ch === '"' || ch === "'" || ch === '`') {
-                this.skipStringInPlace(ch);
+            const isComment = end !== -1 && depth > 0;
+            const text = this.currentLine.slice(start, end === -1 ? this.currentLine.length : end).trimEnd();
+            const line = this.lineIndex + 1;
+            if (pieces.length === 0) {
+                const lead = text.length - text.trimStart().length;
+                starts.push({ line, col: this.indentWidth + start + lead + 1 });
+                if (depth === 0) {
+                    // Closed on the line it opened on: the common, single-line case.
+                    this.pos++; // skip closing )
+                    return { value: text.trim(), starts };
+                }
+                pieces.push(text.trimStart());
             }
-            else {
-                this.pos++;
+            else if (text !== '' || !isComment) {
+                // Lines holding nothing but a comment are dropped entirely.
+                // A kept line is `prefix + text`, so it starts at the owner's indent.
+                pieces.push(text === '' ? '' : prefix + text);
+                starts.push({ line, col: ownerIndent + 1 });
             }
+            if (depth === 0)
+                break;
+            this.nextParamsLine(ownerIndent, openLine, openCol);
+            prefix = ' '.repeat(this.indentWidth - ownerIndent);
         }
-        if (depth !== 0) {
-            throw new LexerError('Unterminated parentheses', this.lineIndex + 1, this.indentWidth + this.pos + 1);
-        }
-        const content = this.currentLine.slice(start, this.pos);
         this.pos++; // skip closing )
-        return content.trim();
+        const content = pieces.join('\n');
+        return content.trim() === '' ? { value: '', starts: [] } : { value: content, starts };
+    }
+    // Moves onto the next non-blank line of a multi-line paren group. Lines in
+    // the group must be indented under its owner; the one exception is the
+    // line that closes it (e.g. '}: Props)'), which may sit level with the
+    // owner as long as it starts with a closing bracket. Anything else at or
+    // left of the owner means the ')' was forgotten, so stop there rather
+    // than swallowing the rest of the file.
+    nextParamsLine(ownerIndent, openLine, openCol) {
+        for (;;) {
+            if (this.lineIndex + 1 >= this.lines.length) {
+                throw new LexerError('Unterminated parentheses', openLine, openCol);
+            }
+            this.lineIndex++;
+            const rawLine = this.lines[this.lineIndex];
+            if (rawLine.trim().length === 0)
+                continue;
+            this.indentWidth = this.measureIndent(rawLine);
+            this.currentLine = rawLine.slice(this.indentWidth);
+            this.pos = 0;
+            if (this.indentWidth < ownerIndent ||
+                (this.indentWidth === ownerIndent && !/^[)}\]]/.test(this.currentLine))) {
+                throw new LexerError(`Expected ')' to close the parentheses opened at line ${openLine}; ` +
+                    'continuation lines must be indented under the line that opens them', this.lineIndex + 1, this.indentWidth + 1);
+            }
+            return;
+        }
     }
     scanString(quote) {
         const start = this.pos;
@@ -745,7 +965,10 @@ class Lexer {
         }
         throw new LexerError('Unterminated template literal', this.lineIndex + 1, this.indentWidth + this.pos + 1);
     }
-    /** Skip over a string in-place (used within balanced paren scanning) */
+    /**
+     * Skip over a string in-place (used within balanced paren scanning).
+     * Returns false when the line ends before the string closes.
+     */
     skipStringInPlace(quote) {
         this.pos++; // skip opening quote
         while (this.pos < this.currentLine.length) {
@@ -754,7 +977,7 @@ class Lexer {
             }
             else if (this.currentLine[this.pos] === quote) {
                 this.pos++;
-                return;
+                return true;
             }
             else if (quote === '`' &&
                 this.currentLine[this.pos] === '$' &&
@@ -764,21 +987,27 @@ class Lexer {
                 this.pos += 2;
                 let depth = 1;
                 while (this.pos < this.currentLine.length && depth > 0) {
-                    if (this.currentLine[this.pos] === '{')
+                    if (this.currentLine[this.pos] === '{') {
                         depth++;
-                    else if (this.currentLine[this.pos] === '}')
+                    }
+                    else if (this.currentLine[this.pos] === '}') {
                         depth--;
-                    if (depth > 0)
-                        this.pos++;
+                    }
+                    else if (this.currentLine[this.pos] === '"' ||
+                        this.currentLine[this.pos] === "'" ||
+                        this.currentLine[this.pos] === '`') {
+                        this.skipStringInPlace(this.currentLine[this.pos]);
+                        continue;
+                    }
+                    this.pos++;
                 }
-                if (this.pos < this.currentLine.length)
-                    this.pos++; // skip closing }
-                return;
+                // fall through to keep scanning for the closing backtick
             }
             else {
                 this.pos++;
             }
         }
+        return false;
     }
     // --- Utility methods ---
     scanIdentifier() {
@@ -794,17 +1023,36 @@ class Lexer {
         }
         return this.currentLine.slice(start, this.pos);
     }
+    // Scans a '(...)' group at the cursor, if there is one, as a PARAMS token
+    // anchored on the '('. The group may run onto later lines, so the anchor
+    // is taken before scanning moves the cursor.
+    scanParamsIfPresent() {
+        if (this.pos < this.currentLine.length && this.currentLine[this.pos] === '(') {
+            const line = this.lineIndex + 1;
+            const col = this.indentWidth + this.pos + 1;
+            const { value, starts } = this.scanBalancedParens();
+            this.tokens.push({ type: 'PARAMS', value, line, col, starts });
+        }
+    }
+    // Returns the first non-space position at or after `pos` on the current line.
+    skipSpacesFrom(pos) {
+        while (pos < this.currentLine.length && this.currentLine[pos] === ' ')
+            pos++;
+        return pos;
+    }
     skipSpaces() {
         while (this.pos < this.currentLine.length && this.currentLine[this.pos] === ' ') {
             this.pos++;
         }
     }
-    emit(type, value) {
+    // `start` is the token's position on the current line; it defaults to the
+    // cursor, which for scanned tokens is already past the token itself.
+    emit(type, value, start = this.pos) {
         this.tokens.push({
             type,
             value,
             line: this.lineIndex + 1,
-            col: this.indentWidth + this.pos + 1,
+            col: this.indentWidth + start + 1,
         });
     }
 }