@graphty/graph-io 0.3.25 → 0.3.26

package/dist/src/formats/gml/importer.js

@@ -8,7 +8,7 @@
  * every node block first, then every edge block, so node indices follow the file's node order
  * and forward edge references resolve.
  *
- * Conventions honoured: NetworkX's `_networkx_list_start` marker and `"[]"` empty lists, `&#NN;`
+ * Conventions honored: NetworkX's `_networkx_list_start` marker and `"[]"` empty lists, `&#NN;`
  * character references in strings, `Creator` / `Version` top-level metadata, `directed 0|1` and
  * `multigraph 0|1` graph flags, comments, keys and values on one line or split across lines, and
  * a `graphics [ x y z ]` node record mapped to the `position` role (note 07 section 9) with the
@@ -23,49 +23,129 @@
  */
 import { GraphFormatError, INVALID_INDEX, } from "@graphty/graph-format";
 import { declareResolved, DictHeuristic, uniqueColumnName } from "../../common/attributes.js";
-import { COLUMN_RENAMED_CODE, DUPLICATE_NODE_CODE as SHARED_DUPLICATE_NODE_CODE, MISSING_ENDPOINT_CODE as SHARED_MISSING_ENDPOINT_CODE, MISSING_ID_CODE as SHARED_MISSING_ID_CODE, MULTIPLE_GRAPHS_CODE, NO_GRAPH_CODE as SHARED_NO_GRAPH_CODE, PRECISION_CODE as SHARED_PRECISION_CODE, ROLE_TAKEN_CODE as SHARED_ROLE_TAKEN_CODE, } from "../../common/codes.js";
+import { importChosenGraph } from "../../common/choose.js";
+import { COLUMN_RENAMED_CODE, DUPLICATE_NODE_CODE as SHARED_DUPLICATE_NODE_CODE, MISSING_ENDPOINT_CODE as SHARED_MISSING_ENDPOINT_CODE, MISSING_ID_CODE as SHARED_MISSING_ID_CODE, MULTIPLE_GRAPHS_CODE, NO_GRAPH_CODE as SHARED_NO_GRAPH_CODE, PRECISION_CODE as SHARED_PRECISION_CODE, ROLE_TAKEN_CODE as SHARED_ROLE_TAKEN_CODE, WIDENED_CODE as SHARED_WIDENED_CODE, } from "../../common/codes.js";
 import { DirectionResolver } from "../../common/direction.js";
 import { IdCoercer } from "../../common/ids.js";
 import { readText, throwIfAborted } from "../../common/input.js";
-import { reportSinkOptions, reportUnusedOptions, resolveImportOptions, } from "../../common/options.js";
+import { graphChosen, reportSinkOptions, reportUnusedOptions, resolveImportOptions, } from "../../common/options.js";
+import { plural } from "../../common/plural.js";
 import { ImportReportBuilder } from "../../common/report.js";
-import { parseWeightText, weightFromValue } from "../../common/weights.js";
+import { parseWeightText, reportWeightPrecision, weightFromValue } from "../../common/weights.js";
 import { EMPTY_LIST_TEXT, EMPTY_TUPLE_TEXT, GmlSyntaxError, LIST_START_MARKER, numberOfText, ORIGINAL_ID_KEY, parseRecord, scalarOrRecord, TOKEN_INT, TOKEN_OPEN, TOKEN_REAL, TOKEN_STRING, TOKEN_WORD, tokenizeGml, } from "./syntax.js";
-/** Issue code: the text holds no `graph [ ... ]` block. */
+/**
+ * The text holds no `graph [ ... ]` block.
+ * @category Issue and loss codes
+ */
 export const NO_GRAPH_CODE = SHARED_NO_GRAPH_CODE;
-/** Issue code: the text holds more than one `graph [ ... ]` block; import() reads the first, importAll() every one. */
+/**
+ * The text holds more than one `graph [ ... ]` block; import() reads the first, importAll() every one.
+ * @category Issue and loss codes
+ */
 export const SECOND_GRAPH_CODE = MULTIPLE_GRAPHS_CODE;
-/** Issue code: a node block has no `id` key. */
+/**
+ * A node block has no `id` key.
+ * @category Issue and loss codes
+ */
 export const MISSING_ID_CODE = SHARED_MISSING_ID_CODE;
-/** Issue code: a node block has no `label` key under `nodeIdFrom: "label"`. */
+/**
+ * A node block has no `label` key under `nodeIdFrom: "label"`.
+ * @category Issue and loss codes
+ */
 export const MISSING_LABEL_CODE = "E_GML_MISSING_LABEL";
-/** Issue code: an edge block has no `source` or no `target` key. */
+/**
+ * An edge block has no `source` or no `target` key.
+ * @category Issue and loss codes
+ */
 export const MISSING_ENDPOINT_CODE = SHARED_MISSING_ENDPOINT_CODE;
-/** Issue code: an `id`, `source` or `target` value is neither an integer nor a string. */
+/**
+ * An `id`, `source` or `target` value is neither an integer nor a string.
+ * @category Issue and loss codes
+ */
 export const ID_TYPE_CODE = "E_GML_ID_TYPE";
-/** Issue code: string `id`, `source` or `target` values, outside the GML spec's integer ids; warned once per file. */
+/**
+ * Node ids, sources or targets are text, where GML expects integers. They are read under the `ids` option. Reported
+ * once per file.
+ * @category Issue and loss codes
+ */
 export const STRING_ID_CODE = "W_GML_STRING_ID";
-/** Issue code: a node id (or label under `nodeIdFrom: "label"`) is declared twice; later keys overwrite. */
+/**
+ * A node id (or label under `nodeIdFrom: "label"`) is declared twice; later keys overwrite.
+ * @category Issue and loss codes
+ */
 export const DUPLICATE_NODE_CODE = SHARED_DUPLICATE_NODE_CODE;
-/** Issue code: a structural key (`id`, `source`, `target`) appears twice in one block. */
+/**
+ * A structural key (`id`, `source`, `target`) appears twice in one block.
+ * @category Issue and loss codes
+ */
 export const REPEATED_KEY_CODE = "E_GML_REPEATED_KEY";
-/** Issue code: a `node` or `edge` key whose value is not a `[ ... ]` block. */
+/**
+ * A `node` or `edge` key whose value is not a `[ ... ]` block.
+ * @category Issue and loss codes
+ */
 export const ELEMENT_TYPE_CODE = "E_GML_ELEMENT_TYPE";
-/** Issue code: a `directed` or `multigraph` flag that is not an integer. */
+/**
+ * A `directed` or `multigraph` flag that is not an integer.
+ * @category Issue and loss codes
+ */
 export const FLAG_TYPE_CODE = "E_GML_FLAG_TYPE";
-/** Issue code: a `directed` / `multigraph` flag that is not 0 or 1 (read as its truth value), one written as a quoted integer, or one repeated. */
+/**
+ * A `directed` / `multigraph` flag that is not 0 or 1 (read as its truth value), one written as a quoted integer, or
+ * one repeated.
+ * @category Issue and loss codes
+ */
 export const FLAG_VALUE_CODE = "W_GML_FLAG_VALUE";
 /** A flag written as a quoted integer, surrounding spaces allowed. */
 const QUOTED_INT = /^\s*[+-]?[0-9]+\s*$/;
-/** Issue code: a named entity in a string that is neither an XML nor an ISO-8859-1 HTML entity; it is kept as written. */
+/**
+ * A named entity in a string that is neither an XML nor an ISO-8859-1 HTML entity, or a numeric reference beyond
+ * U+10FFFF; it is kept as written.
+ * @category Issue and loss codes
+ */
 export const UNKNOWN_ENTITY_CODE = "W_GML_UNKNOWN_ENTITY";
-/** Issue code: an integer beyond 2^53 stored as the nearest f64 (design section 5.1). */
+/**
+ * A node's `graphics` value cannot give a position as written (not a record, repeated in the node, or with an x / y /
+ * z that is not one number); the value is kept in the graphics json column. Warned once per kind of problem, naming
+ * the first node.
+ * @category Issue and loss codes
+ */
+export const GRAPHICS_CODE = "W_GML_GRAPHICS";
+/**
+ * A `graph`, `node` or `edge` record inside a node or edge; kept as a json column, not read as structure.
+ * @category Issue and loss codes
+ */
+export const NESTED_ELEMENT_CODE = "W_GML_NESTED_ELEMENT";
+/**
+ * YEd's group keys (`isGroup`, `gid`); kept as plain node columns, the hierarchy is not read as containment.
+ * @category Issue and loss codes
+ */
+export const GROUPS_CODE = "W_GML_GROUPS";
+/**
+ * A key whose values mix numbers and strings; the column is string, the numbers kept as written.
+ * @category Issue and loss codes
+ */
+export const WIDENED_CODE = SHARED_WIDENED_CODE;
+/**
+ * An integer above 2^53 was stored as the nearest JavaScript number, so its last digits may differ. Pass `long:
+ * "string"` to keep every digit as text.
+ * @category Issue and loss codes
+ */
 export const PRECISION_CODE = SHARED_PRECISION_CODE;
-/** Issue code: the sink already holds a column of the name with another declaration; renamed `<name>#<key>`. */
+/**
+ * Two attributes would have had the same name, so this one was renamed `<name>#<key>`.
+ * @category Plugin helpers
+ */
 export const COLUMN_RENAMED_CODE_GML = COLUMN_RENAMED_CODE;
-/** Issue code: the sink already holds a column with the role; the column is declared without it. */
+/**
+ * You read into a graph builder that already has an attribute with this role, so this file's attribute is kept without
+ * the role.
+ * @category Issue and loss codes
+ */
 export const ROLE_TAKEN_CODE = SHARED_ROLE_TAKEN_CODE;
-/** Loss code: under `nodeIdFrom` "label" / "index" the integer `id` keys are not kept. */
+/**
+ * Under `nodeIdFrom` "label" / "index" the integer `id` keys are not kept.
+ * @category Issue and loss codes
+ */
 export const ID_DROPPED_CODE = "W_GML_ID_DROPPED";
 const FORMAT_DEFAULTS = { ids: "canonical", defaultDirected: false, weightFrom: "value" };
 const KIND_INT = 1;
@@ -88,6 +168,7 @@ const USED_OPTIONS = new Set([
     "weightFrom",
     "weightDtype",
     "restoreMangledIds",
+    "long",
     "errorLimit",
     "signal",
     "onProgress",
@@ -96,6 +177,23 @@ const USED_OPTIONS = new Set([
 const GRAPH_SEQ = -1;
 /** The element sequence number of the top-level keys. */
 const TOP_SEQ = -2;
+/**
+ * Whether a key is the label of a node or edge (text, never a NetworkX list marker).
+ * @param domain - the table
+ * @param key - the key
+ * @returns true for a node or edge label
+ */
+function isLabel(domain, key) {
+    return roleOf(domain, key) === "label";
+}
+/**
+ * Whether a parsed value is a GML record.
+ * @param value - the value
+ * @returns true for a record object
+ */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 /**
  * Whether a key gets a role in its table (design section 5.6 applied to GML keys).
  * @param domain - the table
@@ -156,6 +254,8 @@ class GmlImport {
         this.elementsSinceCheck = 0;
         /** The sink id every file id maps to when they differ (label / index / restored ids), else null. */
         this.idMap = null;
+        /** The file ids of node blocks that were skipped: an edge naming one is skipped too, never given a new node. */
+        this.skippedIds = new Set();
         /** Node indices declared by a node block of this import, for duplicate detection. */
         this.declared = new Uint32Array(64);
         /** The list plans touched by the current node or edge. */
@@ -178,7 +278,7 @@ class GmlImport {
     run(tokens) {
         this.tokens = tokens;
         tokens.onUnknownEntity = (entity, line) => {
-            this.report.warnOnce("parse-error", UNKNOWN_ENTITY_CODE, `unknown character entity ${entity} is kept as written`, { line, element: entity }, `${UNKNOWN_ENTITY_CODE}:${entity}`);
+            this.report.warnOnce("parse-error", UNKNOWN_ENTITY_CODE, `character entity ${entity} cannot be decoded; it is kept as written`, { line, element: entity }, `${UNKNOWN_ENTITY_CODE}:${entity}`);
         };
         this.scan();
         this.push();
@@ -190,10 +290,14 @@ class GmlImport {
      */
     scan() {
         const t = this.requireTokens();
+        let scalarGraph = -1;
         for (let p = 0; p < t.count; p = t.nextPair(p)) {
             const key = t.textOf(p);
             const v = p + 1;
             const record = t.kind[v] === TOKEN_OPEN;
+            if (key === "graph" && !record && scalarGraph < 0) {
+                scalarGraph = v;
+            }
             if (key === "graph" && record) {
                 if (this.graphCount++ === this.which) {
                     this.graphOpen = v;
@@ -211,6 +315,9 @@ class GmlImport {
             }
         }
         if (this.graphOpen < 0) {
+            if (scalarGraph >= 0) {
+                this.report.fail(NO_GRAPH_CODE, `the graph key at line ${t.line[scalarGraph]} holds ${describeValue(t, scalarGraph)}, not a [ ... ] block; the input contains no graph block`, { line: t.line[scalarGraph] });
+            }
             this.report.fail(NO_GRAPH_CODE, "the input contains no graph [ ... ] block", { line: null });
         }
     }
@@ -297,7 +404,9 @@ class GmlImport {
      */
     observe(schema, domain, key, v, seq) {
         const t = this.requireTokens();
+        this.noteStructure(domain, key, v);
         let entry = schema.get(key);
+        const graphics = domain === "node" && key === "graphics" && this.positions;
         if (entry === undefined) {
             entry = {
                 key,
@@ -314,14 +423,21 @@ class GmlImport {
         }
         else if (entry.lastSeq === seq) {
             entry.list = true;
+            // a repeated graphics record: the extra records go to the json column
+            entry.rest || (entry.rest = graphics);
         }
         else {
             entry.lastSeq = seq;
         }
+        if (graphics && t.kind[v] !== TOKEN_OPEN) {
+            entry.rest = true;
+        }
         switch (t.kind[v]) {
             case TOKEN_STRING: {
                 const raw = t.textOf(v);
-                if (raw === LIST_START_MARKER || raw === EMPTY_LIST_TEXT || raw === EMPTY_TUPLE_TEXT) {
+                // a label is text: "[]" there is a label, never NetworkX's empty list
+                if (raw === LIST_START_MARKER ||
+                    (!isLabel(domain, key) && (raw === EMPTY_LIST_TEXT || raw === EMPTY_TUPLE_TEXT))) {
                     entry.list = true;
                     return;
                 }
@@ -348,8 +464,32 @@ class GmlImport {
                     this.inspectGraphics(entry, v);
                 }
                 return;
-            default:
+            default: {
                 entry.kinds |= KIND_REAL;
+                const text = t.textOf(v);
+                if (/\d/.test(text) && !Number.isFinite(Number(text))) {
+                    this.report.warnOnce("precision", PRECISION_CODE, `${domain} key "${key}" holds the real ${text}, beyond the f64 range; it is stored as ${numberOfText(text) > 0 ? "" : "-"}Infinity`, { line: t.line[v], element: key }, `${PRECISION_CODE}:overflow:${domain}:${key}`);
+                }
+            }
+        }
+    }
+    /**
+     * Warn about keys of a node or edge whose meaning GML readers give but this import does not:
+     * a nested graph / node / edge record, and yEd's group hierarchy.
+     * @param domain - the table
+     * @param key - the key
+     * @param v - the value token
+     */
+    noteStructure(domain, key, v) {
+        const t = this.requireTokens();
+        if (domain === "graph") {
+            return;
+        }
+        if ((key === "graph" || key === "node" || key === "edge") && t.kind[v] === TOKEN_OPEN) {
+            this.report.warnOnce("unsupported", NESTED_ELEMENT_CODE, `a nested ${key} record inside a ${domain} is kept as the json column "${key}"; it is not read as structure`, { line: t.line[v], element: key }, `${NESTED_ELEMENT_CODE}:${domain}:${key}`);
+        }
+        else if (domain === "node" && (key === "isGroup" || key === "gid")) {
+            this.report.warnOnce("unsupported", GROUPS_CODE, "yEd group keys (isGroup, gid) are kept as plain node columns; the group hierarchy is not read as containment", { line: t.line[v], element: key });
         }
     }
     /**
@@ -428,7 +568,9 @@ class GmlImport {
      * @returns the plan
      */
     planOf(domain, entry, top = false) {
-        const kind = kindOf(entry);
+        // long: "string" keeps every digit of an integer key that holds values beyond 2^53, as text
+        const asText = entry.unsafe && this.options.long === "string" && kindOf(entry) === "int";
+        const kind = asText ? "string" : kindOf(entry);
         let scalar = dtypeOfKind(kind, entry);
         if (scalar === "string" &&
             !entry.list &&
@@ -437,8 +579,13 @@ class GmlImport {
             entry.dict.decide() === "dict") {
             scalar = "dict";
         }
-        if (entry.unsafe) {
-            this.report.warnOnce("precision", PRECISION_CODE, `${domain} key "${entry.key}" holds integers beyond 2^53; they are stored as the nearest f64`, { element: entry.key }, `${PRECISION_CODE}:${domain}:${entry.key}`);
+        if ((entry.kinds & KIND_STRING) !== 0 &&
+            (entry.kinds & (KIND_INT | KIND_REAL)) !== 0 &&
+            (entry.kinds & KIND_RECORD) === 0) {
+            this.report.warnOnce("coercion", WIDENED_CODE, `${domain} key "${entry.key}" mixes numbers and strings; the column is string and the numbers are kept as written`, { element: entry.key }, `${WIDENED_CODE}:${domain}:${entry.key}`);
+        }
+        if (entry.unsafe && !asText) {
+            this.report.warnOnce("precision", PRECISION_CODE, `${domain} key "${entry.key}" holds integers beyond 2^53; they are stored as the nearest f64 (pass long: "string" to keep every digit as text)`, { element: entry.key }, `${PRECISION_CODE}:${domain}:${entry.key}`);
         }
         const name = domain === "graph" ? this.uniqueGraphName(entry.key) : entry.key;
         let itemDtype = null;
@@ -461,11 +608,7 @@ class GmlImport {
             items: null,
             seq: Number.NEGATIVE_INFINITY,
         };
-        if (domain === "node" &&
-            entry.key === "graphics" &&
-            entry.position &&
-            entry.kinds === KIND_RECORD &&
-            !entry.list) {
+        if (domain === "node" && entry.key === "graphics" && this.positions && (entry.kinds & KIND_RECORD) !== 0) {
             const taken = (candidate) => this.nodeSchema.has(candidate) || this.sink.nodeColumn(candidate) !== INVALID_INDEX;
             const position = {
                 ...plan,
@@ -473,9 +616,12 @@ class GmlImport {
                 dtype: "f64",
                 itemDtype: null,
                 kind: "real",
+                list: false,
                 role: "position",
             };
-            const rest = entry.rest ? { ...plan } : null;
+            const rest = entry.rest
+                ? { ...plan, dtype: "json", itemDtype: null, kind: "record", list: false }
+                : null;
             return { ...plan, position, rest };
         }
         return plan;
@@ -488,6 +634,9 @@ class GmlImport {
     uniqueGraphName(key) {
         const name = uniqueColumnName(key, key, (candidate) => this.graphNames.has(candidate));
         this.graphNames.add(name);
+        if (name !== key) {
+            this.report.warning("coercion", COLUMN_RENAMED_CODE_GML, `the top-level key "${key}" and a key of the graph block share the graph column name; the top-level value is stored as "${name}"`, { element: key });
+        }
         return name;
     }
     /** Set the graph metadata: source format, creator, version, multigraph flag, weight origin. */
@@ -633,6 +782,7 @@ class GmlImport {
         this.checkAbort();
         let index;
         let sinkId;
+        let fileId;
         try {
             let idTok = -1;
             let labelTok = -1;
@@ -654,7 +804,7 @@ class GmlImport {
             }
             // the file id under the ids rule, so `id 1` and `source "1"` meet in idMap (except under
             // "keep", where the integer 1 and the string "1" are different ids by design)
-            const fileId = this.coerceFileId(idTok, this.fileIdOf(idTok, "id"));
+            fileId = this.coerceFileId(idTok, this.fileIdOf(idTok, "id"));
             if (originalTok >= 0) {
                 sinkId = this.restoredId(originalTok);
             }
@@ -675,14 +825,21 @@ class GmlImport {
                         sinkId = fileId;
                 }
             }
+            index = sink.addNode(sinkId);
             if (this.idMap !== null) {
+                const before = this.idMap.get(fileId);
+                if (before !== undefined && before !== sinkId) {
+                    report.warning("merged", DUPLICATE_NODE_CODE, `file id ${JSON.stringify(fileId)} is declared twice (nodes ${JSON.stringify(before)} and ${JSON.stringify(sinkId)}); edges to it resolve to the later`, { line, element: String(fileId) });
+                }
                 this.idMap.set(fileId, sinkId);
             }
-            index = sink.addNode(sinkId);
         }
         catch (err) {
             this.recordNodeError(err, line);
             report.counts.skippedNodes++;
+            if (fileId !== undefined) {
+                this.skippedIds.add(fileId);
+            }
             return;
         }
         if (this.isDeclared(index)) {
@@ -694,16 +851,28 @@ class GmlImport {
         }
         this.beginElement(this.seq++);
         try {
+            const graphics = [];
+            let graphicsPlan = null;
             for (let p = open + 1; p < close; p = t.nextPair(p)) {
                 const key = t.textOf(p);
                 if (key === "id" || (key === ORIGINAL_ID_KEY && options.restoreMangledIds)) {
                     continue;
                 }
                 const plan = this.nodePlans.get(key);
-                if (plan !== undefined) {
+                if (plan !== undefined && plan.position !== null) {
+                    graphicsPlan = plan;
+                    graphics.push(p + 1);
+                }
+                else if (plan !== undefined) {
                     this.writeNode(plan, index, p + 1);
                 }
             }
+            if (graphicsPlan !== null) {
+                this.writeGraphics(graphicsPlan, index, graphics, {
+                    line: t.line[graphics[0]],
+                    element: String(sinkId),
+                });
+            }
             this.flushLists("node", index);
         }
         catch (err) {
@@ -898,7 +1067,16 @@ class GmlImport {
      */
     endpoint(v, key) {
         const id = this.coerceFileId(v, this.fileIdOf(v, key));
-        return this.idMap?.get(id) ?? id;
+        const mapped = this.idMap?.get(id);
+        if (mapped !== undefined) {
+            return mapped;
+        }
+        if (this.skippedIds.has(id)) {
+            // the node block was skipped: creating the endpoint would bring the node back under
+            // its raw file id (beside label ids under nodeIdFrom "label")
+            throw new GraphFormatError("E_UNKNOWN_NODE", `${key} ${JSON.stringify(id)} names a node block that was skipped after an error`, { reason: "skipped node", id });
+        }
+        return id;
     }
     /**
      * The weight of an edge from its weight token.
@@ -909,11 +1087,17 @@ class GmlImport {
         const t = this.requireTokens();
         switch (t.kind[v]) {
             case TOKEN_STRING:
-                return parseWeightText(t.stringOf(v));
+                return parseWeightText(t.stringOf(v), this.report);
             case TOKEN_OPEN:
                 throw new GraphFormatError("E_INVALID_WEIGHT", "edge weight is a record", { value: "[...]" });
-            default:
-                return weightFromValue(numberOfText(t.textOf(v)));
+            default: {
+                const text = t.textOf(v);
+                const weight = weightFromValue(numberOfText(text));
+                if (weight !== undefined) {
+                    reportWeightPrecision(text, weight, this.report);
+                }
+                return weight;
+            }
         }
     }
     /**
@@ -977,10 +1161,6 @@ class GmlImport {
      * @param v - the value token
      */
     writeNode(plan, index, v) {
-        if (plan.position !== null) {
-            this.writeGraphics(plan, index, v);
-            return;
-        }
         if (plan.list) {
             this.collectItem(plan, v, this.seqNow, this.touched);
             return;
@@ -1011,36 +1191,77 @@ class GmlImport {
             this.collectItem(plan, v, seq, this.graphTouched);
             return;
         }
-        this.sink.setGraphValue(plan.name, this.scalarOf(plan, v), graphDecl(plan));
+        const value = this.scalarOf(plan, v);
+        this.sink.setGraphValue(plan.name, value, graphDecl(plan));
+        if (seq === GRAPH_SEQ && plan.key === "name" && typeof value === "string") {
+            // the graph block's `name` is the graph's name too (snapshot.meta.name, and what graphName matches)
+            this.sink.setMeta({ name: value });
+        }
     }
     /**
-     * Write a node's graphics record: the position column from x / y / z, the remaining keys to
-     * the json column.
+     * Write a node's graphics values: the position column from the x / y / z of the first record,
+     * everything else (the remaining keys, a value that is not a record, a repeated record) to the
+     * json column, with a warning when the value cannot give a position as written.
      * @param plan - the graphics plan
      * @param index - the node index
-     * @param v - the value token (a record)
+     * @param vs - the value tokens of the node's graphics keys, in order
+     * @param where - the line and the node, for issues
      */
-    writeGraphics(plan, index, v) {
+    writeGraphics(plan, index, vs, where) {
         const t = this.requireTokens();
         const { sink } = this;
-        const record = parseRecord(t, v);
-        const { x, y, z } = record;
+        const values = vs.map((v) => (t.kind[v] === TOKEN_OPEN ? parseRecord(t, v) : this.scalarOf(plan, v)));
+        const first = values[0];
         const positionPlan = plan.position;
-        if (positionPlan !== null && typeof x === "number" && typeof y === "number") {
-            sink.setNodeValue(this.handleOf(positionPlan, "node"), index, [x, y, typeof z === "number" ? z : 0]);
+        let rest = first;
+        if (isRecord(first) && positionPlan !== null) {
+            rest = this.writePosition(positionPlan, index, first, where);
+        }
+        else if (!isRecord(first)) {
+            this.graphicsWarning("scalar", `node ${where.element}'s graphics is not a record`, where);
+        }
+        if (values.length > 1) {
+            this.graphicsWarning("repeated", `node ${where.element} has ${values.length} graphics records; the position comes from the first`, where);
+            rest = values;
+        }
+        if (rest !== undefined && plan.rest !== null) {
+            sink.setNodeValue(this.handleOf(plan.rest, "node"), index, rest);
+        }
+    }
+    /**
+     * Write a node's position from the x / y / z of its graphics record, taking them out of it.
+     * @param positionPlan - the position column's plan
+     * @param index - the node index
+     * @param record - the graphics record
+     * @param where - the line and the node, for issues
+     * @returns what is left of the record for the json column, or undefined when nothing is
+     */
+    writePosition(positionPlan, index, record, where) {
+        const { x, y, z } = record;
+        let rest = record;
+        if (typeof x === "number" && typeof y === "number") {
+            const depth = typeof z === "number" ? z : 0;
+            this.sink.setNodeValue(this.handleOf(positionPlan, "node"), index, [x, y, depth]);
             delete record.x;
             delete record.y;
             if (typeof z === "number") {
                 delete record.z;
             }
-            if (plan.rest !== null && Object.keys(record).length > 0) {
-                sink.setNodeValue(this.handleOf(plan.rest, "node"), index, record);
-            }
-            return;
+            rest = Object.keys(record).length > 0 ? record : undefined;
         }
-        if (plan.rest !== null) {
-            sink.setNodeValue(this.handleOf(plan.rest, "node"), index, record);
+        if ("x" in record || "y" in record || "z" in record) {
+            this.graphicsWarning("coordinate", `node ${where.element}'s graphics x / y / z is not one number each`, where);
         }
+        return rest;
+    }
+    /**
+     * Warn once per kind of graphics problem.
+     * @param kind - the problem
+     * @param what - the message start, naming the node
+     * @param where - the line and the node
+     */
+    graphicsWarning(kind, what, where) {
+        this.report.warnOnce("validation-error", GRAPHICS_CODE, `${what}; the value is kept in the graphics json column (warned once for every such node)`, where, `${GRAPHICS_CODE}:${kind}`);
     }
     /**
      * Collect one list item.
@@ -1331,9 +1552,13 @@ function sniffGml(head) {
     }
     return 0;
 }
-/** The GML importer plugin. */
+/**
+ * The GML importer plugin.
+ * @category Built-in formats
+ */
 export const gmlImporter = Object.freeze({
     format: "gml",
+    options: Object.freeze(["dictionaries", "positions"]),
     extensions: Object.freeze([".gml"]),
     mimeTypes: Object.freeze(["text/x-gml", "text/plain"]),
     sniff: sniffGml,
@@ -1345,6 +1570,10 @@ export const gmlImporter = Object.freeze({
      * @returns the report
      */
     async import(input, sink, options) {
+        if (graphChosen(options)) {
+            // the choice is honored here too, not only by the registry
+            return importChosenGraph(gmlImporter, input, sink, options);
+        }
         const resolved = resolveImportOptions(options, FORMAT_DEFAULTS);
         const report = new ImportReportBuilder("gml", resolved.errorLimit);
         reportSinkOptions(sink, options, report);
@@ -1354,7 +1583,7 @@ export const gmlImporter = Object.freeze({
         const gml = new GmlImport(sink, report, resolved, options);
         gml.run(tokens);
         if (gml.graphCount > 1) {
-            report.warning("unsupported", SECOND_GRAPH_CODE, `the input holds ${gml.graphCount - 1} more graph block(s) after the first; import() reads the first, importAll() reads every one`);
+            report.warning("unsupported", SECOND_GRAPH_CODE, `the input holds ${gml.graphCount - 1} more graph block${plural(gml.graphCount - 1)} after the first; the first is read (graphIndex or graphName chooses another; importAllGraphs() reads every one)`);
         }
         // an abort raised during the last few elements (after the last periodic check) still rejects
         throwIfAborted(resolved.signal);