reladraw 0.18.0 → 0.19.1

package/README.md

@@ -2,7 +2,9 @@
 
 reladraw is a text language for diagrams where you say where things go.
 
-**[Try it in your browser →](https://reladraw.github.io/reladraw/)**
+> The language is changing frequently. The playground always runs the newest syntax, so a diagram that draws there today may need a small edit later. An installed copy from npm changes only when you upgrade it.
+
+**[Try it in your browser in the reladraw playground →](https://reladraw.github.io/reladraw/)**
 
 I wanted to be able to create custom, expressive diagrams where I decided how to arrange the diagram, but without the inefficiency of manually drawing in draw.io. For example, this is a diagram drawn in draw.io:
 
@@ -43,7 +45,7 @@ npm install -g reladraw
 reladraw render diagram.reladraw -o diagram.svg
 ```
 
-`reladraw check diagram.reladraw` prints the warnings without writing a picture.
+`reladraw check diagram.reladraw` prints the warnings without writing a picture, and `reladraw format diagram.reladraw` lines its statements up in columns.
 
 Or from a clone, which also gets you the examples:
 
@@ -86,9 +88,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.18.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, and an element that does the same inside a web page.
-
-The language isn't stable yet, so expect the syntax to change.
+Version 0.19.1. 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, and an element that does the same inside a web page.
 
 ## License
 

package/SYNTAX.md

@@ -1,4 +1,4 @@
-# Syntax reference — 0.18.0
+# Syntax reference — 0.19.1
 
 What the language accepts. The changelog at the end lists what changed in each published version; 0.17.0's changes are large, and its entry has a table of every old spelling and what to write instead.
 
@@ -55,7 +55,7 @@ What every statement of a kind has is positional; what is optional is a key. A w
 
 **A value ends when its own shape is complete.** `height: 0.5 group height  right of a` reads a size, then a placement. `to: top, right of z` keeps `right of z` inside `to:`, because it is part of that value. So word order stays free and nothing is ambiguous.
 
-**A bracket modifies the one thing it follows.** A setting that belongs to one part of a statement is written in brackets right after that part: a placement's `(gap: wide)`, a text's `(size: small, wrap: 30)`, a line's `line: (path: square)`, a layout's `layout: column (gap: none)`, a waypoint's `b top (gap: wide)`. The scope is visible instead of inferred. Inside a bracket the comma is optional.
+**A bracket modifies the one thing it follows.** A setting that belongs to one part of a statement is written in brackets right after that part: a placement's `(gap: wide)`, a text's `(size: small, wrap: 30)`, a line's `line: (path: square)`, a layout's `layout: column (gap: none)`, a waypoint's `b top (gap: wide)`. The scope is visible instead of inferred. Inside a bracket the comma is optional, and spaces around it don't matter: `(corners: rounded,path: square)` and `(corners: rounded , path: square)` are both `(corners: rounded, path: square)`.
 
 ### Names and words
 
@@ -842,7 +842,7 @@ A line named `req` has parts. `req start` and `req end` are where it was written
 
 ### Copies fan out
 
-Copies are lines with the same two boxes on the same sides, in either direction, with nothing stated about their path. Texts and colors don't count, so a request and its response are copies. Copies are drawn as one shape, each shifted sideways from it by a fixed step like lanes on a road, so they never cross. Straight copies with no side named run parallel, a `tight` gap apart, each end landing where its lane meets the border. A line whose landing is stated, such as `to: top, right of z`, is no longer a copy, which is how to override the fan.
+Copies are lines with the same two boxes on the same sides, in either direction, with nothing stated about their path. Texts and colors don't count, so a request and its response are copies. Copies are drawn as one shape, each shifted sideways from it by a fixed step like lanes on a road, so they never cross. Straight copies with no side named run parallel, a `tight` gap apart, each end landing where its lane meets the border. A line that says anything about where it goes is no longer a copy, and is drawn as written: a stated landing (`to: top, right of z`), a place in a side's `right-edge-order:` list, or a `step-out:` or `turn:` in its own bracket. That is how to override the fan. A `step-out:` or `turn:` from `default edge` or a style says the same for every line, so copies sharing it still fan, each taking it from the first.
 
 ```
 node client
@@ -1162,6 +1162,59 @@ reladraw check diagram.reladraw
 
 The output is a standalone SVG: every picture is drawn into it as path data, never from a font or a linked file. A web page can draw a diagram in place with `<reladraw-diagram>`; see "In a web page" in the README.
 
+### Formatting
+
+```
+reladraw format diagram.reladraw other.reladraw
+reladraw format --check diagram.reladraw
+reladraw format - < diagram.reladraw
+reladraw format --init
+```
+
+`format` lays each file out again in place. By default every statement is on one line, and neighboring statements with the same keyword line their clauses up in columns, each as wide as its longest clause plus two spaces; a blank line or a new keyword starts a new set of columns, and a comment line between them doesn't. A comment at the end of a line lines up with the others in its set. A statement written over several lines with a comment among them keeps its lines, with the indent tidied. Blank lines stay as written, and so do Windows line endings.
+
+Inside a clause, spacing comes out as these pages write it, whatever was typed: one space after a key's colon and between words, none just inside a bracket, and a comma against the word before it, so `line:( corners:rounded , path:square )` becomes `line: (corners: rounded, path: square)`.
+
+Only whitespace changes, and the order of clauses when `clause-order` asks: every word is copied as it was written, and the result is checked to draw exactly what the original did. A file that doesn't parse is reported and left alone, and the other files still run. `--check` changes nothing, prints each file that would change, and fails if there is one, for a pre-commit hook or CI. A shell expands `*.reladraw` into the files; folders aren't searched.
+
+`-` in place of the files reads the diagram from standard input and prints it formatted, touching no file. That is how an editor formats a buffer, saved or not: Vim's `:%!reladraw format -`, or the command a format-on-save package runs. Its settings come from the nearest `.reladraw-format` to the current folder.
+
+The settings are in the nearest `.reladraw-format`, in the file's folder or a folder above it; with none, the defaults. A project that puts one at its top keeps everyone's formatting the same. `reladraw format --init` writes one in the current folder with every setting at its default and a comment on what each value does, and refuses if one is there already. One setting a line, as in a diagram:
+
+```
+// keep each clause straight after the last
+columns: off
+clause-gap: 2
+```
+
+| setting | values, default first |
+|---|---|
+| `wrap-at` | `off`, or a number of characters: past it, a statement wraps onto as few lines as fit |
+| `clause-per-line-at` | `off`, a number of characters, or `always`: past it, every clause gets its own line |
+| `first-line` | `text` (keyword, name and texts), `name`: where a broken statement's first line ends |
+| `clause-order` | `as-written`, or a list of kinds: `placement`, and keys by name, such as `style, placement, fill` |
+| `columns` | `aligned`, `off` |
+| `columns-shared-by` | `same-keyword-neighbors`, `neighbors`, `same-keyword` (across blank lines), `file` |
+| `clause-gap` | a number of spaces, `2`; or `tab`, with `columns: off` only |
+| `trailing-comments` | `shared-column`, `after-statement` |
+| `comments-inside` | `keep-lines`, `move-above` (joined, comments above it), `refuse` (left alone, comment named) |
+| `continued-lines-indent` | where a broken or kept statement's later lines start: `4` or another number, `tab`, `under-name`, `under-name + 2`, `under-text` (under the name when there's no text) |
+| `blank-lines` | `as-written`, `exactly 2`, `at-most 3` |
+| `edge-name-and-ends` | `one-column`, `own-columns` (name, each end and the arrow a column each) |
+
+An unknown setting, one written twice, or a value it doesn't take is an error naming it.
+
+**Breaking a long statement.** With both at a number, a statement up to `wrap-at` stays on one line, one up to `clause-per-line-at` wraps, and a longer one goes one clause to a line. Its length is measured on its own, before columns, so whether it breaks never depends on its neighbors; its first line still lines up with theirs. A break falls only between clauses, never inside one or inside a bracket, so a clause longer than the width stands alone on its line, past it. A statement broken by hand is broken again by these rules, or joined when they leave it short enough; one kept on its lines for a comment among them is left as it is. A comment at the end of a broken statement follows its last line.
+
+```
+// wrap-at: 60
+node  confirm  "Confirm"
+    below accept (gap: tight)  left of accept (gap: wide)
+    style: plain
+```
+
+**Ordering clauses.** `clause-order` lists the kinds of clause in the order they are written: `placement` for every relation, and a key by its name (`style`, `fill`, `via`). Kinds it leaves out follow, in the order written, and clauses of one kind keep theirs. A node's or edge's texts never move, since the language takes them only straight after the name; `text` in the list means a style's `text:` key. A clause never moves where moving it would change what the statement says.
+
 ## Attributes
 
 Every attribute, and what takes one. A node's kind is what its body is: a box (`shape:`), a picture (`icon:`) or bare text (`shape: none`).
@@ -1228,6 +1281,20 @@ Designed and absent from the code.
 
 Pre-1.0, so the minor number is where a breaking change goes. Every removal 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.19.1**
+
+- **A copy that states its own `step-out:` or `turn:` keeps it.** Lines between the same two sides of the same two boxes fan into lanes, and each used to be drawn as the first one's shape shifted over, so a `step-out:` or `turn:` written on any later line was ignored. A line naming either is now drawn as written and leaves the fan, and so does a line named in its side's `right-edge-order:` list. Where that puts two lines on one run, it is reported as `edge-overlap`. Prompted by #19.
+- **Errors and findings name a named line by its name**, as written: `line e2 b.1 -- b.2 runs on line e1 b.1 -- b.2`. Two lines between the same boxes used to read identically.
+
+**0.19.0**
+
+- **`reladraw format`** lays a file out again: each statement on one line, neighboring statements with the same keyword lined up in columns, comments kept beside what they are about. No word is respelled, and the result is checked to draw what the original did. `--check` fails on a file that would change, and `.reladraw-format` holds a project's settings; `reladraw format --init` writes one with every setting explained. `reladraw format -` reads standard input and prints the result, for editors. A long statement can wrap past a width (`wrap-at`) or go one clause to a line (`clause-per-line-at`), and `clause-order` puts placements and keys in a chosen order. The playground has a Format button (Shift+Alt+F, undone with Ctrl+Z) and a panel for its settings, which can copy them as a `.reladraw-format`. Spacing inside a clause is evened out too: `gap:tight` becomes `gap: tight`, `( gap: tight )` becomes `(gap: tight)`. Prompted by #14, where a long statement was hard to read in a plain editor.
+- **A comma may touch the next word or stand apart from both.** `(corners: rounded,path: square)` used to be refused with "`corners` has no value", and `(at: start , above edge)` was refused in a text's bracket; both now read as `rounded, path:` and `start, above` do.
+- **The playground opens and saves `.reladraw` files**, with Open… and Save… above the source. Save suggests the name of the file last opened or saved; Chrome and Edge ask where to put it, other browsers save it with the downloads. Opening a file over edits that haven't been saved to one asks first.
+- **The playground's error message can be copied**, with a Copy button beside it or by selecting it. Only the underlined line number jumps to the line now; a click anywhere on the message used to, which took a selection away.
+- **The playground no longer fails on some diagrams with 0.18.0's shapes**, which stopped with "insidePolygon is not defined". The command line was unaffected.
+- **The agent skill checks it matches the installed tool.** It compares its own version with `reladraw --version` and tells the user which of the two to update.
+
 **0.18.0**
 
 - **More shapes, for flowcharts and the rest** (#18): `diamond`, `pill`, `parallelogram`, `hexagon`, `trapezoid`, `triangle` and `cylinder`, named for how they look, and the flowchart standard's shapes that have no geometric name as `flow-` and what they mean, from `flow-subprocess` and `flow-delay` to `flow-collate`. A shape's settings go in a bracket after its name: `shape: parallelogram (slant: 2, lean: left)`, `shape: cylinder (lying)`, `shape: document (fold: 1.5)`.

package/dist/cli.js

@@ -4,17 +4,32 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, resolve as resolvePath } from 'node:path';
 import { nearMatch, readChecks } from './checks.js';
 import { SourceError } from './errors.js';
+import { format } from './format.js';
+import { DEFAULT_FORMAT, readFormatSettings, SETTINGS_FILE, settingsFileText } from './format-settings.js';
 import { draw } from './index.js';
 import { THEME_NAMES, THEMES } from './themes.js';
 const USAGE = `reladraw — draw a diagram from stated placement
 
   reladraw render <input.reladraw> [-o <output.svg>] [options]
   reladraw check <input.reladraw> [options]
+  reladraw format <input.reladraw>... [--check]
+  reladraw format - [--check]
+  reladraw format --init
 
   render      draw the diagram to an SVG, and print any findings: places
               where the picture, drawn as written, may not read as meant.
   check       lay the diagram out and print only the findings. No SVG is
               written, so a good one is left alone while you iterate.
+  format      lay each file out again in place: spacing, columns, comments
+              and blank lines. No word is respelled, and a file that
+              doesn't parse is left alone. The nearest .reladraw-format, in
+              the file's folder or one above it, holds the settings.
+              --check changes nothing, and fails if a file would change.
+              - reads the diagram from standard input and prints it
+              formatted, for an editor; settings come from the current
+              folder up.
+              --init writes a .reladraw-format here, every setting at its
+              default with what it does.
 
   -o, --out   where render writes the SVG. Defaults to the input path with
               its extension replaced by .svg. Use - for standard output.
@@ -29,7 +44,7 @@ const USAGE = `reladraw — draw a diagram from stated placement
               print the version.
   -h, --help  print this.
 `;
-const COMMANDS = ['render', 'check'];
+const COMMANDS = ['render', 'check', 'format'];
 async function main(argv) {
     if (argv.length === 0 || argv.includes('-h') || argv.includes('--help')) {
         process.stdout.write(USAGE);
@@ -56,6 +71,8 @@ async function main(argv) {
         return 1;
     }
     const command = verb;
+    if (command === 'format')
+        return formatFiles(argv.slice(1));
     let input;
     let out;
     let theme;
@@ -172,6 +189,176 @@ async function main(argv) {
     process.stderr.write(`${target}\n`);
     return 0;
 }
+/**
+ * `reladraw format`: each file laid out again in place, by the settings in
+ * the nearest `.reladraw-format`. A file that fails is reported and the rest
+ * still run, so one broken file doesn't hide the state of the others.
+ */
+async function formatFiles(args) {
+    const files = [];
+    let check = false;
+    let init = false;
+    for (const arg of args) {
+        if (arg === '--check')
+            check = true;
+        else if (arg === '--init')
+            init = true;
+        else if (arg.startsWith('-') && arg !== '-') {
+            process.stderr.write(`reladraw: format takes --check and --init, not ${arg}\n`);
+            return 1;
+        }
+        else
+            files.push(arg);
+    }
+    if (init) {
+        if (check || files.length > 0) {
+            process.stderr.write('reladraw: --init writes a settings file and formats nothing — run reladraw format --init on its own\n');
+            return 1;
+        }
+        if (existsSync(SETTINGS_FILE)) {
+            process.stderr.write(`reladraw: there is already a ${SETTINGS_FILE} here — delete it first to write a fresh one\n`);
+            return 1;
+        }
+        await writeFile(SETTINGS_FILE, settingsFileText(), 'utf8');
+        process.stderr.write(`${resolvePath(SETTINGS_FILE)}\n`);
+        return 0;
+    }
+    if (files.length === 0) {
+        process.stderr.write('reladraw: no input file — reladraw format <input.reladraw>..., or - to read standard input\n');
+        return 1;
+    }
+    if (files.includes('-'))
+        return formatStandardInput(files, check);
+    let status = 0;
+    const found = new Map();
+    for (const file of files) {
+        let settings = DEFAULT_FORMAT;
+        try {
+            const nearest = nearestSettings(dirname(resolvePath(file)), found);
+            if (nearest)
+                settings = nearest.settings;
+        }
+        catch (error) {
+            if (!(error instanceof SettingsError))
+                throw error;
+            process.stderr.write(`${error.cause.format(error.path)}\n`);
+            status = 1;
+            continue;
+        }
+        let source;
+        try {
+            source = await readFile(file, 'utf8');
+        }
+        catch {
+            process.stderr.write(`reladraw: can't read ${file}\n`);
+            status = 1;
+            continue;
+        }
+        let laid;
+        try {
+            laid = format(source, settings);
+        }
+        catch (error) {
+            process.stderr.write(error instanceof SourceError ? `${error.format(file)}\n` : `reladraw: ${file}: ${error.message}\n`);
+            status = 1;
+            continue;
+        }
+        if (laid === source)
+            continue;
+        if (check) {
+            process.stderr.write(`${file}: not formatted — reladraw format ${file} lays it out\n`);
+            status = 1;
+            continue;
+        }
+        await writeFile(file, laid, 'utf8');
+        process.stderr.write(`formatted ${file}\n`);
+    }
+    return status;
+}
+/**
+ * `reladraw format -`: the diagram read from standard input and printed
+ * formatted, which is how an editor formats a buffer it hasn't saved. The
+ * settings are the nearest `.reladraw-format` from the current folder. With
+ * `--check` nothing is printed, and it fails if the text would change.
+ */
+async function formatStandardInput(files, check) {
+    if (files.length > 1) {
+        process.stderr.write('reladraw: - reads standard input, so it goes on its own — reladraw format -\n');
+        return 1;
+    }
+    if (process.stdin.isTTY) {
+        process.stderr.write('reladraw: format - reads a diagram from standard input — pipe one in: reladraw format - < diagram.reladraw\n');
+        return 1;
+    }
+    let settings = DEFAULT_FORMAT;
+    try {
+        settings = nearestSettings(process.cwd(), new Map())?.settings ?? DEFAULT_FORMAT;
+    }
+    catch (error) {
+        if (!(error instanceof SettingsError))
+            throw error;
+        process.stderr.write(`${error.cause.format(error.path)}\n`);
+        return 1;
+    }
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    const source = Buffer.concat(chunks).toString('utf8');
+    let laid;
+    try {
+        laid = format(source, settings);
+    }
+    catch (error) {
+        process.stderr.write(error instanceof SourceError ? `${error.format('<stdin>')}\n` : `reladraw: <stdin>: ${error.message}\n`);
+        return 1;
+    }
+    if (check) {
+        if (laid === source)
+            return 0;
+        process.stderr.write('<stdin>: not formatted\n');
+        return 1;
+    }
+    process.stdout.write(laid);
+    return 0;
+}
+/** A `.reladraw-format` that doesn't read, and where it is. */
+class SettingsError extends Error {
+    path;
+    cause;
+    constructor(path, cause) {
+        super(cause.message);
+        this.path = path;
+        this.cause = cause;
+    }
+}
+/**
+ * The settings in the nearest `.reladraw-format`, looking in `folder` and
+ * then each folder above it, or nothing when there is none. Each folder is
+ * looked in once however many files share it.
+ */
+function nearestSettings(folder, found) {
+    const known = found.get(folder);
+    if (known !== undefined)
+        return known;
+    const path = resolvePath(folder, SETTINGS_FILE);
+    let result;
+    if (existsSync(path)) {
+        try {
+            result = { path, settings: readFormatSettings(readFileSync(path, 'utf8')) };
+        }
+        catch (error) {
+            if (error instanceof SourceError)
+                throw new SettingsError(path, error);
+            throw error;
+        }
+    }
+    else {
+        const parent = dirname(folder);
+        result = parent === folder ? null : nearestSettings(parent, found);
+    }
+    found.set(folder, result);
+    return result;
+}
 main(process.argv.slice(2)).then((code) => process.exit(code), (error) => {
     process.stderr.write(`reladraw: ${error instanceof Error ? error.message : String(error)}\n`);
     process.exit(1);

package/dist/format-settings.d.ts

@@ -0,0 +1,60 @@
+/**
+ * How `reladraw format` lays a file out. Each key is a setting as it is
+ * written in a `.reladraw-format` file, so an error, the generated file and
+ * the code all use one name for each.
+ */
+export interface FormatSettings {
+    'wrap-at': 'off' | number;
+    'clause-per-line-at': 'off' | 'always' | number;
+    'first-line': 'text' | 'name';
+    'continued-lines-indent': number | 'tab' | 'under-name' | 'under-text' | {
+        underName: number;
+    };
+    'clause-order': 'as-written' | string[];
+    'clause-gap': number | 'tab';
+    columns: 'aligned' | 'off';
+    'columns-shared-by': 'same-keyword-neighbors' | 'neighbors' | 'same-keyword' | 'file';
+    'comments-inside': 'keep-lines' | 'move-above' | 'refuse';
+    'trailing-comments': 'shared-column' | 'after-statement';
+    'blank-lines': 'as-written' | {
+        exactly: number;
+    } | {
+        atMost: number;
+    };
+    'edge-name-and-ends': 'one-column' | 'own-columns';
+}
+/** One setting: what it controls, its values in words, and how to read one. */
+interface Setting {
+    name: keyof FormatSettings;
+    /** One sentence for the generated file: what the setting controls. */
+    about: string;
+    /** Each value as written, and what it means. The first is the default. */
+    values: [string, string][];
+    /** The default, as written. */
+    written: string;
+    /** The value as written, read; a string thrown is the reason it is refused. */
+    read: (value: string) => FormatSettings[keyof FormatSettings];
+}
+/**
+ * The kinds of clause `clause-order` can list: a statement's texts, its
+ * placements, and each key by its own name. `text` is also a style's `text:`
+ * key, which is a style's way of saying what a text says.
+ */
+export declare const CLAUSE_KINDS: readonly string[];
+export declare const SETTINGS: Setting[];
+export declare const DEFAULT_FORMAT: FormatSettings;
+/** The file a project's settings are written in. */
+export declare const SETTINGS_FILE = ".reladraw-format";
+/**
+ * Read a `.reladraw-format` file: one `key: value` setting a line, `//`
+ * comments, blank lines. An unknown setting, one written twice, or a value it
+ * doesn't take is refused by name, with the line.
+ */
+export declare function readFormatSettings(text: string): FormatSettings;
+/**
+ * The `.reladraw-format` that `reladraw format --init` writes: every setting
+ * at its default, each under a comment saying what it controls and what each
+ * of its values means.
+ */
+export declare function settingsFileText(): string;
+export {};