reladraw 0.18.0 → 0.19.0

package/README.md

@@ -43,7 +43,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,7 +86,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.
+Version 0.19.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.
 

package/SYNTAX.md

@@ -1,4 +1,4 @@
-# Syntax reference — 0.18.0
+# Syntax reference — 0.19.0
 
 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
 
@@ -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,15 @@ 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.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 {};

package/dist/format-settings.js

@@ -0,0 +1,250 @@
+import { ALL_ATTR_KEYS } from './ast.js';
+import { nearMatch } from './checks.js';
+import { SourceError } from './errors.js';
+const SETTING_COUNT = /^[1-9]\d*$/;
+/**
+ * A setting whose values are words, one of them the default. Anything else is
+ * refused with the list.
+ */
+function wordSetting(name, about, values) {
+    return {
+        name,
+        about,
+        values,
+        written: values[0][0],
+        read: (value) => {
+            if (values.some(([word]) => word === value))
+                return value;
+            const near = nearMatch(value, values.map(([word]) => word));
+            throw `${name}: "${value}" is not one of its values${near ? ` — did you mean ${near}?` : ''} — it takes ${orList(values.map(([word]) => word))}`;
+        },
+    };
+}
+/**
+ * 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 const CLAUSE_KINDS = [...new Set(['text', 'placement', ...ALL_ATTR_KEYS])];
+export const SETTINGS = [
+    {
+        name: 'wrap-at',
+        about: 'Past this many characters, a statement wraps onto more lines, as few as fit.',
+        values: [
+            ['off', 'never wrap'],
+            ['a number', 'wrap past that many characters, such as 80'],
+        ],
+        written: 'off',
+        read: (value) => {
+            if (value === 'off')
+                return value;
+            if (SETTING_COUNT.test(value))
+                return Number(value);
+            throw `wrap-at: "${value}" is not one of its values — it takes off, or a number of characters such as 80`;
+        },
+    },
+    {
+        name: 'clause-per-line-at',
+        about: 'Past this many characters, each clause goes on its own line instead.',
+        values: [
+            ['off', 'never'],
+            ['a number', 'past that many characters, such as 120'],
+            ['always', 'every statement, whatever its length'],
+        ],
+        written: 'off',
+        read: (value) => {
+            if (value === 'off' || value === 'always')
+                return value;
+            if (SETTING_COUNT.test(value))
+                return Number(value);
+            throw `clause-per-line-at: "${value}" is not one of its values — it takes off, always, or a number of characters such as 120`;
+        },
+    },
+    wordSetting('first-line', 'When a statement breaks onto more lines, where its first line ends.', [
+        ['text', 'after the text: keyword, name and text stay together'],
+        ['name', 'after the name'],
+    ]),
+    {
+        name: 'continued-lines-indent',
+        about: 'Where the lines after a statement\'s first one start.',
+        values: [
+            ['4', 'that many spaces in, such as 4'],
+            ['tab', 'one tab in'],
+            ['under-name', 'under the statement\'s name'],
+            ['under-name + 2', 'that many characters past the start of the name'],
+            ['under-text', 'under the statement\'s text, or what comes after the name'],
+        ],
+        written: '4',
+        read: (value) => {
+            if (SETTING_COUNT.test(value))
+                return Number(value);
+            if (value === 'tab' || value === 'under-name' || value === 'under-text')
+                return value;
+            const shifted = /^under-name \+ ([1-9]\d*)$/.exec(value);
+            if (shifted)
+                return { underName: Number(shifted[1]) };
+            throw `continued-lines-indent: "${value}" is not one of its values — it takes a number of spaces, tab, under-name, under-name + 2 or under-text`;
+        },
+    },
+    {
+        name: 'clause-order',
+        about: 'The order a statement\'s clauses are written in after its text, which always\ncomes straight after the name. A list names placement and keys such as style;\nwhat it leaves out follows, in the order written.',
+        values: [
+            ['as-written', 'the order the writer chose'],
+            ['a list', 'that order, such as: placement, style, fill'],
+        ],
+        written: 'as-written',
+        read: (value) => {
+            if (value === 'as-written')
+                return value;
+            const kinds = value.split(',').map((kind) => kind.trim());
+            const seen = new Set();
+            for (const kind of kinds) {
+                if (kind === '')
+                    throw `clause-order: "${value}" has an empty place in its list — name a kind of clause between each comma`;
+                if (!CLAUSE_KINDS.includes(kind)) {
+                    const near = nearMatch(kind, CLAUSE_KINDS);
+                    throw `clause-order: "${kind}" is not a kind of clause${near ? ` — did you mean ${near}?` : ''} — it takes text, placement and keys such as style or fill`;
+                }
+                if (seen.has(kind))
+                    throw `clause-order: ${kind} is listed twice — keep one`;
+                seen.add(kind);
+            }
+            return kinds;
+        },
+    },
+    {
+        name: 'clause-gap',
+        about: 'The least space between two clauses on a line.',
+        values: [
+            ['2', 'that many spaces, such as 2'],
+            ['tab', 'one tab, which only works with columns: off'],
+        ],
+        written: '2',
+        read: (value) => {
+            if (SETTING_COUNT.test(value))
+                return Number(value);
+            if (value === 'tab')
+                return 'tab';
+            throw `clause-gap: "${value}" is not one of its values — it takes a number of spaces, or tab`;
+        },
+    },
+    wordSetting('columns', 'Whether statements that belong together line their clauses up in columns.', [
+        ['aligned', 'each column as wide as its longest clause'],
+        ['off', 'each clause straight after the one before, a clause gap apart'],
+    ]),
+    wordSetting('columns-shared-by', 'Which statements line their clauses up in shared columns. A comment line\nbetween them never ends a set.', [
+        ['same-keyword-neighbors', 'adjacent, with the same keyword\n(a blank line or new keyword ends the set)'],
+        ['neighbors', 'adjacent, whatever their keyword'],
+        ['same-keyword', 'the same keyword, across blank lines'],
+        ['file', 'the whole file'],
+    ]),
+    wordSetting('comments-inside', 'What happens to a statement written over several lines, with comments\namong them.', [
+        ['keep-lines', 'it stays on its own lines, with the indent tidied'],
+        ['move-above', 'the comments move above it, and it is joined onto one line'],
+        ['refuse', 'the file is left alone, and the comment in the way is named'],
+    ]),
+    wordSetting('trailing-comments', 'Where a comment at the end of a statement\'s line goes.', [
+        ['shared-column', 'lined up with the other comments in its set'],
+        ['after-statement', 'a clause gap after its own statement'],
+    ]),
+    {
+        name: 'blank-lines',
+        about: 'What happens to runs of blank lines. A run is never removed, since a blank\nline starts a new set of columns.',
+        values: [
+            ['as-written', 'every blank line stays'],
+            ['exactly 2', 'every run becomes that many'],
+            ['at-most 3', 'longer runs shrink to that many; shorter ones stay'],
+        ],
+        written: 'as-written',
+        read: (value) => {
+            if (value === 'as-written')
+                return value;
+            const counted = /^(exactly|at-most) ([1-9]\d*)$/.exec(value);
+            if (counted)
+                return counted[1] === 'exactly' ? { exactly: Number(counted[2]) } : { atMost: Number(counted[2]) };
+            throw `blank-lines: "${value}" is not one of its values — it takes as-written, exactly and a number, or at-most and a number`;
+        },
+    },
+    wordSetting('edge-name-and-ends', 'How an edge\'s name and ends, such as one a -> b, line up.', [
+        ['one-column', 'together, as one column, the way a node\'s name is'],
+        ['own-columns', 'the name, each end and the arrow in a column each'],
+    ]),
+];
+const SETTING_BY_NAME = new Map(SETTINGS.map((setting) => [setting.name, setting]));
+export const DEFAULT_FORMAT = Object.fromEntries(SETTINGS.map((setting) => [setting.name, setting.read(setting.written)]));
+/** The file a project's settings are written in. */
+export 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 function readFormatSettings(text) {
+    const settings = { ...DEFAULT_FORMAT };
+    const seen = new Map();
+    text.split(/\r?\n/).forEach((raw, index) => {
+        const line = index + 1;
+        const written = raw.replace(/\/\/.*$/, '').trim();
+        if (written === '')
+            return;
+        const colon = written.indexOf(':');
+        if (colon === -1)
+            throw new SourceError(`"${written}" is not a setting — write one as name: value, such as columns: aligned`, line);
+        const name = written.slice(0, colon).trim();
+        const value = written.slice(colon + 1).trim().replace(/\s+/g, ' ');
+        const setting = SETTING_BY_NAME.get(name);
+        if (setting === undefined) {
+            const near = nearMatch(name, SETTINGS.map((one) => one.name));
+            throw new SourceError(`there is no setting "${name}"` + (near ? ` — did you mean ${near}?` : ` — the settings are ${orList(SETTINGS.map((one) => one.name))}`), line);
+        }
+        const before = seen.get(name);
+        if (before !== undefined)
+            throw new SourceError(`${name} is set twice, here and on line ${before} — keep one`, line);
+        seen.set(name, line);
+        if (value === '')
+            throw new SourceError(`${name} has no value — it takes ${orList(setting.values.map(([word]) => word))}`, line);
+        try {
+            settings[name] = setting.read(value);
+        }
+        catch (reason) {
+            if (typeof reason === 'string')
+                throw new SourceError(reason, line);
+            throw reason;
+        }
+    });
+    if (settings['clause-gap'] === 'tab' && settings.columns === 'aligned') {
+        throw new SourceError(`clause-gap: tab can't line columns up, since how wide a tab is depends on the editor — use a number of spaces, or columns: off`, seen.get('clause-gap') ?? seen.get('columns') ?? 1);
+    }
+    return settings;
+}
+/**
+ * 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 function settingsFileText() {
+    const blocks = SETTINGS.map((setting) => {
+        const width = Math.max(...setting.values.map(([word]) => word.length));
+        // A meaning written over two lines carries on under where it started.
+        const values = setting.values.flatMap(([word, meaning], index) => {
+            const [first, ...rest] = meaning.split('\n');
+            return [
+                `//   ${word.padEnd(width)}  ${first}${index === 0 ? ' (default)' : ''}`,
+                ...rest.map((more) => `//   ${' '.repeat(width)}  ${more}`),
+            ];
+        });
+        const about = setting.about.split('\n').map((line) => `// ${line}`);
+        return [...about, ...values, `${setting.name}: ${setting.written}`].join('\n');
+    });
+    const header = [
+        '// .reladraw-format: how `reladraw format` lays out the .reladraw files in this',
+        '// folder and every folder below it, unless a nearer one says otherwise.',
+        '// Every setting is written out at its default; change the ones you want, or',
+        '// delete a line to use the default.',
+    ].join('\n');
+    return `${header}\n\n${blocks.join('\n\n')}\n`;
+}
+function orList(words) {
+    return words.length < 2 ? words.join('') : `${words.slice(0, -1).join(', ')} or ${words[words.length - 1]}`;
+}

package/dist/format.d.ts

@@ -0,0 +1,14 @@
+import { type FormatSettings } from './format-settings.js';
+/**
+ * Lay a source file out again: spacing between clauses, columns shared by
+ * statements that belong together, comments and blank lines, as `settings`
+ * say. Only whitespace changes, and the order of clauses when `clause-order`
+ * asks. Every token is copied out of the line it was
+ * written on, so no word is respelled, and the result is parsed again and
+ * compared with the original, so a mistake here can never change what a file
+ * draws: it throws instead.
+ *
+ * Throws the parser's error for a file that does not parse, so a broken file
+ * is never rewritten.
+ */
+export declare function format(source: string, settings?: FormatSettings): string;