reladraw 0.9.0 → 0.10.0

package/README.md

@@ -66,7 +66,7 @@ That gets you a copy of the skill at the time you run it, so you'll need to re-r
 
 ## Status
 
-Version 0.9.0. Early stage, but works. The parser, layout engine, and SVG renderer are written in TypeScript, with zero runtime dependencies. There is a command-line tool that turns a .reladraw text file into an SVG.
+Version 0.10.0. Early stage, but works. The parser, layout engine, and SVG renderer are written in TypeScript, with zero runtime dependencies. There is a command-line tool that turns a .reladraw text file into an SVG.
 
 The language isn't stable yet, so expect the syntax to change.
 

package/SYNTAX.md

@@ -1,4 +1,4 @@
-# Syntax reference — 0.9.0
+# Syntax reference — 0.10.0
 
 What the language accepts. The parser, resolver and SVG renderer implement all of it; the sections at the end record what is defective, unchecked or undecided.
 
@@ -6,9 +6,19 @@ The worked example is `examples/arch.reladraw`, transcribed from the reference r
 
 ## Shape of the file
 
-One statement per line. No multi-line statements, no line continuations, no blocks.
+A statement starts at the beginning of a line. A long one may continue onto the lines after it by indenting them:
 
-Blank lines and `//` comments are ignored. A comment runs to the end of the line and may trail a statement, so `node a "Docker"  // the one that matters` is fine. Indentation is ignored entirely — a formatter may add it for readability, and stale indentation cannot change what a file means.
+```
+node desktop1 "Desktop 1 / Linux"
+  above-left of hub  gap: tight
+  badge: desktop  style: synced
+```
+
+A line that starts with whitespace continues the statement above it, and a blank line or the next unindented line ends it. How much whitespace makes no difference — one space and a tab mean the same — so nothing can depend on indentation you cannot see. A bracket may stay open across lines, as in `line: (color: red,` with `pattern: dashed)` on the next. There are no blocks: indentation continues a statement, and never puts one thing inside another.
+
+An indented line with no statement to continue — at the top of the file, or after a blank line or an unindented comment — is an error rather than a statement of its own, and so is an indented line starting with a statement keyword such as `node`. Both are almost always a stray indent, and both say to remove it.
+
+Blank lines and `//` comments are ignored. A comment runs to the end of the line and may trail a statement, so `node a "Docker"  // the one that matters` is fine. An indented comment line sits inside the statement it follows; an unindented one ends it.
 
 A lone `/` is an ordinary character rather than the start of a comment, and `#` is ordinary too — it opens a hex color. Comments were spelled `#` in an earlier version and moved to `//` so that `fill: #14532d` could be written the way every other tool writes a color.
 
@@ -1056,6 +1066,11 @@ That one was found by testing the lexer, not by rendering — and it could not h
 
 Pre-1.0, so the minor number is where a breaking change goes. Every removal below is refused by name with the replacement quoted, rather than dropped in silence — an older file stops with an error saying what to write instead.
 
+**0.10.0**
+
+- A statement may continue onto the lines after it by indenting them. See "Shape of the file". An error in such a statement names the line the mistake is on.
+- **Breaking:** indentation used to be ignored, so an indented `node` line was a statement of its own. It now continues the statement above and is refused, with a message saying to remove the indentation.
+
 **0.9.0**
 
 - Theme colors: `theme-page`, `theme-text`, `theme-muted`, `theme-fill`, `theme-border` and `theme-line` name the theme's own color for each part, and `theme-primary` and `theme-secondary`, with `-subtle` and `theme-on-` forms, name its two accents. Any attribute that takes a color takes them, and they follow the theme when it changes, so a diagram colored with them reads in light and dark themes alike. See "Theme colors".

package/dist/grammar.d.ts

@@ -19,9 +19,12 @@
  * The scanner is the JavaScript consumer of the same spec, and the playground is
  * its only caller.
  *
- * Nothing in the language spans lines: `//` runs to the end of one, a string
- * closes on one, and there are no blocks. That is the property those editor
- * formats need and the reason a `.reladraw` grammar is small in all of them.
+ * No token spans lines: `//` runs to the end of one, a string closes on one,
+ * and there are no blocks. A statement may continue onto indented lines, but
+ * each of those is colored by the same rules, and a word that is a keyword at
+ * the start of one is refused by the parser anyway. That is the property those
+ * editor formats need and the reason a `.reladraw` grammar is small in all of
+ * them.
  */
 /** What a span of source is, for coloring. */
 export type TokenKind = 

package/dist/grammar.js

@@ -19,9 +19,12 @@
  * The scanner is the JavaScript consumer of the same spec, and the playground is
  * its only caller.
  *
- * Nothing in the language spans lines: `//` runs to the end of one, a string
- * closes on one, and there are no blocks. That is the property those editor
- * formats need and the reason a `.reladraw` grammar is small in all of them.
+ * No token spans lines: `//` runs to the end of one, a string closes on one,
+ * and there are no blocks. A statement may continue onto indented lines, but
+ * each of those is colored by the same rules, and a word that is a keyword at
+ * the start of one is refused by the parser anyway. That is the property those
+ * editor formats need and the reason a `.reladraw` grammar is small in all of
+ * them.
  */
 import { DIRECTIONS, POSITIONS, SIDES, PASSAGE_AXES } from './ast.js';
 /**

package/dist/index.d.ts

@@ -10,5 +10,9 @@ export { render, type RenderOptions } from './render.js';
 export { DARK_THEME, DEFAULT_THEME, THEMES, THEME_NAMES, type Theme } from './themes.js';
 import { type RenderOptions } from './render.js';
 import { type ResolveOptions } from './resolve.js';
-/** Source text in, SVG out. The whole pipeline in one call. */
+/**
+ * Source text in, SVG out. The whole pipeline in one call. An error in a
+ * statement written over several lines names the line at fault, not the one
+ * the statement starts on; see `blame`.
+ */
 export declare function compile(source: string, options?: ResolveOptions & RenderOptions): string;

package/dist/index.js

@@ -8,10 +8,21 @@ export { parse } from './parser.js';
 export { resolve } from './resolve.js';
 export { render } from './render.js';
 export { DARK_THEME, DEFAULT_THEME, THEMES, THEME_NAMES } from './themes.js';
-import { parse } from './parser.js';
+import { SourceError } from './errors.js';
+import { blame, parse } from './parser.js';
 import { render } from './render.js';
 import { resolve } from './resolve.js';
-/** Source text in, SVG out. The whole pipeline in one call. */
+/**
+ * Source text in, SVG out. The whole pipeline in one call. An error in a
+ * statement written over several lines names the line at fault, not the one
+ * the statement starts on; see `blame`.
+ */
 export function compile(source, options = {}) {
-    return render(resolve(parse(source), options), options);
+    const run = (text) => render(resolve(parse(text), options), options);
+    try {
+        return run(source);
+    }
+    catch (error) {
+        throw error instanceof SourceError ? blame(source, error, run) : error;
+    }
 }

package/dist/lexer.d.ts

@@ -18,8 +18,11 @@ export interface Token {
  * opening bracket counts only where a token starts, and a closing one only
  * while a group is open, so an unquoted `rgb(20,20,20)` stays a single token.
  *
+ * `depth` is how many brackets are still open from the lines before, when a
+ * statement continues onto this one.
+ *
  * Returns an empty array for a blank or comment-only line.
  */
-export declare function tokenizeLine(line: string, lineNumber: number): Token[];
+export declare function tokenizeLine(line: string, lineNumber: number, depth?: number): Token[];
 /** A bare token ending in `:` opens the attribute section of a statement. */
 export declare function isAttrKey(token: Token): boolean;

package/dist/lexer.js

@@ -14,12 +14,14 @@ import { SourceError } from './errors.js';
  * opening bracket counts only where a token starts, and a closing one only
  * while a group is open, so an unquoted `rgb(20,20,20)` stays a single token.
  *
+ * `depth` is how many brackets are still open from the lines before, when a
+ * statement continues onto this one.
+ *
  * Returns an empty array for a blank or comment-only line.
  */
-export function tokenizeLine(line, lineNumber) {
+export function tokenizeLine(line, lineNumber, depth = 0) {
     const tokens = [];
     let i = 0;
-    let depth = 0;
     while (i < line.length) {
         const ch = line[i];
         if (ch === ' ' || ch === '\t') {

package/dist/parser.d.ts

@@ -1,3 +1,28 @@
 import type { Document } from './ast.js';
-/** Parse a whole source file. One statement per line; blanks and comments drop out. */
+import { SourceError } from './errors.js';
+/**
+ * Parse a whole source file. A statement starts on an unindented line and runs
+ * on through any line that starts with whitespace; a blank line or the next
+ * unindented one ends it. How much whitespace never matters, only whether
+ * there is any, so two lines that look alike cannot mean different things.
+ *
+ * An indented comment stays inside the statement and an unindented one ends
+ * it. An indented line with nothing open above it is refused rather than read
+ * as a statement of its own: it is a stray indent or a deleted first line, and
+ * both are worth hearing about.
+ */
 export declare function parse(source: string): Document;
+/**
+ * Find the line at fault for an error reported on the first line of a
+ * continued statement. Everything after the parser reports a statement by the
+ * line it starts on, which for a continued one is often not where the mistake
+ * is, so this asks which line brings the error in: `run` is tried on the
+ * source with the statement cut after each of its lines in turn, and the first
+ * cut that fails with the same message names the line. A cut that fails
+ * differently — a bracket not yet closed, a placement not yet written — is not
+ * the culprit and is passed over. Lines keep their numbers, because what is cut
+ * is blanked rather than removed.
+ *
+ * This costs a few extra runs, and only when there is an error to report.
+ */
+export declare function blame(source: string, error: SourceError, run: (source: string) => unknown): SourceError;

package/dist/parser.js

@@ -1,19 +1,108 @@
 import { COLOR_KEYS, DEFAULT_KEYS, DEFAULT_TARGETS, DIAGRAM_KEYS, DIRECTIONS, describePlacement, SIDE_AXIS, SIDES, PASSAGE_AXES, TEXT_KEYS, LINE_KEYS, LINE_VALUES, CONTENTS_KEYS, PLACEMENT_KEYS, BOUNDARY_PARTS, INWARD, OPPOSITE, isDirection, isPart, isPosition, listTargets, nameTarget, } from './ast.js';
 import { SourceError } from './errors.js';
+import { STATEMENT_KEYWORDS } from './grammar.js';
 import { isAttrKey, tokenizeLine } from './lexer.js';
 import { THEME_COLORS, THEME_NAMES, THEMES } from './themes.js';
-/** Parse a whole source file. One statement per line; blanks and comments drop out. */
+/**
+ * Parse a whole source file. A statement starts on an unindented line and runs
+ * on through any line that starts with whitespace; a blank line or the next
+ * unindented one ends it. How much whitespace never matters, only whether
+ * there is any, so two lines that look alike cannot mean different things.
+ *
+ * An indented comment stays inside the statement and an unindented one ends
+ * it. An indented line with nothing open above it is refused rather than read
+ * as a statement of its own: it is a stray indent or a deleted first line, and
+ * both are worth hearing about.
+ */
 export function parse(source) {
     const statements = [];
+    /** The statement being gathered, and the line it starts on. */
+    let open = null;
+    // Brackets may close on a later line, and the lexer only reads `)` as a
+    // bracket while one is open, so the depth is carried from line to line.
+    let depth = 0;
+    const close = () => {
+        if (open)
+            statements.push(parseStatement(open.tokens, open.line));
+        open = null;
+        depth = 0;
+    };
     source.split(/\r?\n/).forEach((line, index) => {
         const lineNumber = index + 1;
-        const tokens = tokenizeLine(line, lineNumber);
+        if (line.trim() === '') {
+            close();
+            return;
+        }
+        const indented = line[0] === ' ' || line[0] === '\t';
+        if (!indented)
+            close();
+        const tokens = tokenizeLine(line, lineNumber, depth);
         if (tokens.length === 0)
             return;
-        statements.push(parseStatement(tokens, lineNumber));
+        if (!indented) {
+            open = { tokens, line: lineNumber };
+        }
+        else {
+            const first = tokens[0];
+            if (!open) {
+                throw new SourceError('this line is indented, which continues the statement above, but there is none to ' +
+                    'continue — remove the indentation to start a new statement', lineNumber);
+            }
+            if (!first.quoted && STATEMENT_KEYWORDS.includes(first.text)) {
+                throw new SourceError(`\`${first.text}\` cannot continue the statement above — an indented line continues ` +
+                    `the one before it, so remove the indentation to start a new statement`, lineNumber);
+            }
+            open.tokens.push(...tokens);
+        }
+        for (const token of tokens) {
+            if (token.quoted)
+                continue;
+            if (token.text === '(')
+                depth += 1;
+            else if (token.text === ')')
+                depth -= 1;
+        }
     });
+    close();
     return { statements };
 }
+/**
+ * Find the line at fault for an error reported on the first line of a
+ * continued statement. Everything after the parser reports a statement by the
+ * line it starts on, which for a continued one is often not where the mistake
+ * is, so this asks which line brings the error in: `run` is tried on the
+ * source with the statement cut after each of its lines in turn, and the first
+ * cut that fails with the same message names the line. A cut that fails
+ * differently — a bracket not yet closed, a placement not yet written — is not
+ * the culprit and is passed over. Lines keep their numbers, because what is cut
+ * is blanked rather than removed.
+ *
+ * This costs a few extra runs, and only when there is an error to report.
+ */
+export function blame(source, error, run) {
+    const lines = source.split(/\r?\n/);
+    const start = error.line - 1;
+    const first = lines[start];
+    if (first === undefined || first.trim() === '' || first[0] === ' ' || first[0] === '\t')
+        return error;
+    let end = start;
+    while (end + 1 < lines.length && lines[end + 1].trim() !== '' && /^[ \t]/.test(lines[end + 1]))
+        end += 1;
+    if (end === start)
+        return error;
+    for (let last = start; last < end; last++) {
+        const cut = lines.map((line, index) => (index > last && index <= end ? '' : line)).join('\n');
+        try {
+            run(cut);
+        }
+        catch (partial) {
+            if (partial instanceof SourceError && partial.message === error.message) {
+                return last === start ? error : new SourceError(error.message, last + 1);
+            }
+        }
+    }
+    return new SourceError(error.message, end + 1);
+}
 function parseStatement(tokens, line) {
     const keyword = tokens[0];
     if (!keyword || keyword.quoted) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reladraw",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "A diagram language where you say where things go.",
   "type": "module",
   "bin": {