@graphty/graph-io 0.3.25 → 0.3.26

package/src/formats/gml/index.ts

@@ -1,14 +1,19 @@
 /**
- * The `@graphty/graph-io/gml` subpath (design section 8.2): the GML importer and exporter, their
+ * The `@graphty/graph-io/gml` subpath: the GML importer and exporter, their
  * option types, and their issue and loss-note codes grouped in two tables.
+ * @module @graphty/graph-io/gml
  */
 
 import {
+    AMBIGUOUS_GRAPH_NAME_CODE,
     COLUMN_RENAMED_CODE,
     DIRECTION_FORCED_CODE,
     DIRECTION_REFUSED_CODE,
+    ELEMENT_ISSUE,
     ENCODING_FALLBACK_CODE,
+    GRAPH_NOT_FOUND_CODE,
     ID_MERGED_CODE,
+    INPUT_ISSUE,
     INVALID_ENCODING_CODE,
     INVALID_UTF8_CODE,
     MIXED_DIRECTION_CODE,
@@ -35,11 +40,14 @@ import {
     ELEMENT_TYPE_CODE,
     FLAG_TYPE_CODE,
     FLAG_VALUE_CODE,
+    GRAPHICS_CODE,
+    GROUPS_CODE,
     ID_DROPPED_CODE,
     ID_TYPE_CODE,
     MISSING_ENDPOINT_CODE,
     MISSING_ID_CODE,
     MISSING_LABEL_CODE,
+    NESTED_ELEMENT_CODE,
     NO_GRAPH_CODE,
     PRECISION_CODE,
     REPEATED_KEY_CODE,
@@ -47,31 +55,45 @@ import {
     SECOND_GRAPH_CODE,
     STRING_ID_CODE,
     UNKNOWN_ENTITY_CODE,
+    WIDENED_CODE,
 } from "./importer.js";
 
 export { gmlExporter, type GmlExportOptions } from "./exporter.js";
 export { gmlImporter, type GmlImportOptions } from "./importer.js";
 
 /**
- * The issue codes the GML importer records (design section 8.6), by name: the codes shared with
- * the other importers (src/common/codes.ts) and the GML-specific ones. A key is the code without
+ * The issue codes the GML importer records, by name: the codes shared with
+ * the other importers and the GML-specific ones. A key is the code without
  * its severity and format prefixes.
+ * @category Built-in formats
  */
 export const GML_ISSUE = Object.freeze({
-    /** A grammar violation: an untokenisable bare token, an unclosed string or `[`, a stray `]`, a key without a value (fatal). */
+    ...INPUT_ISSUE,
+    ...ELEMENT_ISSUE,
+    /**
+     * The text breaks GML's syntax: a word that is not a key or a value, an unclosed string or `[`, a stray `]`, or a
+     * key without a value. The import stops.
+     */
     SYNTAX: SYNTAX_CODE,
-    /** The input holds invalid UTF-8 (fatal). */
+    /** The input is not valid UTF-8. The import stops. */
     INVALID_UTF8: INVALID_UTF8_CODE,
-    /** Invalid bytes in the encoding a BOM, a declaration or the encoding option chose (fatal). */
+    /**
+     * Some bytes are not valid in the encoding that was chosen (by a byte order mark, the file's declaration or the
+     * `encoding` option). The import stops.
+     */
     INVALID_ENCODING: INVALID_ENCODING_CODE,
     /** Bytes that are not UTF-8 and declare no encoding were read as windows-1252. */
     ENCODING_FALLBACK: ENCODING_FALLBACK_CODE,
     /** A declared encoding the platform cannot decode was ignored. */
     UNKNOWN_ENCODING: UNKNOWN_ENCODING_CODE,
-    /** No `graph [` block (fatal). */
+    /** There is no `graph [` block. The import stops. */
     NO_GRAPH: NO_GRAPH_CODE,
-    /** More than one `graph` block (fatal). */
+    /** The file holds more than one `graph` block and only the first was read. It is not added when `graphIndex` or `graphName` chose the graph. */
     MULTIPLE_GRAPHS: SECOND_GRAPH_CODE,
+    /** `graphIndex` or `graphName` names no graph of the file; the message lists the graphs it holds. The import stops. */
+    GRAPH_NOT_FOUND: GRAPH_NOT_FOUND_CODE,
+    /** `graphName` matches more than one graph; pass `graphIndex`. The import stops. */
+    AMBIGUOUS_GRAPH_NAME: AMBIGUOUS_GRAPH_NAME_CODE,
     /** A node without an `id`. */
     MISSING_ID: MISSING_ID_CODE,
     /** A node without a `label` under nodeIdFrom "label". */
@@ -80,7 +102,10 @@ export const GML_ISSUE = Object.freeze({
     MISSING_ENDPOINT: MISSING_ENDPOINT_CODE,
     /** A node id, source or target that is neither an integer nor a string. */
     ID_TYPE: ID_TYPE_CODE,
-    /** String node ids, sources or targets (outside the spec's integers), kept under the ids rule; warned once. */
+    /**
+     * Node ids, sources or targets are text, where GML expects integers. They are read under the `ids` option.
+     * Reported once per file.
+     */
     STRING_ID: STRING_ID_CODE,
     /** A node id declared twice (later keys overwrite). */
     DUPLICATE_NODE: DUPLICATE_NODE_CODE,
@@ -92,43 +117,79 @@ export const GML_ISSUE = Object.freeze({
     FLAG_TYPE: FLAG_TYPE_CODE,
     /** A `directed` / `multigraph` flag outside 0 / 1, or repeated. */
     FLAG_VALUE: FLAG_VALUE_CODE,
-    /** A named entity in a string that no table decodes; kept as written. */
+    /** A named entity no table decodes, or a numeric reference beyond U+10FFFF; kept as written. */
     UNKNOWN_ENTITY: UNKNOWN_ENTITY_CODE,
-    /** An integer beyond 2^53 rounded to f64. */
+    /** An integer beyond 2^53 was stored as the nearest 64-bit float; pass `long: "string"` to keep every digit. */
     PRECISION: PRECISION_CODE,
-    /** A column renamed `<name>#<key>` because the sink held the name with another shape. */
+    /** A node's graphics value that cannot give a position as written; kept in the graphics json column. */
+    GRAPHICS: GRAPHICS_CODE,
+    /** A graph, node or edge record nested in a node or edge; kept as json, not read as structure. */
+    NESTED_ELEMENT: NESTED_ELEMENT_CODE,
+    /** YEd's isGroup / gid keys, kept as plain columns; the hierarchy is not read as containment. */
+    GROUPS: GROUPS_CODE,
+    /**
+     * An attribute's type was widened because a later value did not fit: an integer above 2^31 in an integer column,
+     * or two declared types for one attribute.
+     */
+    WIDENED: WIDENED_CODE,
+    /**
+     * An attribute was renamed `<name>#<suffix>` because another attribute already has its name, for example
+     * two attributes declared with the same name.
+     */
     COLUMN_RENAMED: COLUMN_RENAMED_CODE,
-    /** A column declared without its role because the sink already holds it. */
+    /**
+     * You read into a graph builder that already has an id, label or position attribute, so this file's one is kept as
+     * a plain attribute.
+     */
     ROLE_TAKEN: ROLE_TAKEN_CODE,
-    /** Two id texts merged into one number under ids "number". */
+    /** Two different id texts became the same number because `ids` is "number", so their nodes were merged. */
     ID_MERGED: ID_MERGED_CODE,
-    /** A common option the importer has no use for was given. */
+    /** You set an option this format does not use; it had no effect. The message names the option. */
     OPTION_IGNORED: OPTION_IGNORED_CODE,
-    /** A builder-policy option the sink does not honour. */
+    /**
+     * You read into your own graph builder, which was created with a different `addMissingNodes`, `duplicateEdges`,
+     * `selfLoops` or `weightDtype` than the option you passed; the builder's setting applies.
+     */
     SINK_OPTION: SINK_OPTION_CODE,
-    /** The sink refused the file's direction. */
+    /**
+     * You read into a graph builder whose direction is already set, or which already holds edges, so the file is read
+     * with the builder's direction instead of its own.
+     */
     DIRECTION_REFUSED: DIRECTION_REFUSED_CODE,
-    /** Edges forced to the policy's direction. */
+    /** Edges of the other direction were read with the direction `onMixedDirection` chose. */
     DIRECTION_FORCED: DIRECTION_FORCED_CODE,
-    /** A mixed file under onMixedDirection "error" (fatal). */
+    /**
+     * The graph has both directed and undirected edges and `onMixedDirection` is "error". An import stops; a save to a
+     * format that holds one direction per file fails with E_DIRECTED. Pass "directed" or "undirected" to read or write
+     * it anyway.
+     */
     MIXED_DIRECTION: MIXED_DIRECTION_CODE,
-    /** Under nodeIdFrom "label" / "index" the integer ids are not kept (a loss note). */
+    /**
+     * Under `nodeIdFrom: "label"` or `"index"` the file's integer ids are not kept. It is listed in `report.lossy`, not
+     * in `report.issues`.
+     */
     ID_DROPPED: ID_DROPPED_CODE,
 });
 
-/** The loss-note codes the GML exporter's check() reports beyond the shared LOSS table, by name. */
+/**
+ * The loss-note codes the GML exporter's check() reports beyond the shared LOSS table, by name.
+ * @category Built-in formats
+ */
 export const GML_LOSS = Object.freeze({
-    /** A json column holds numbers; GML records cannot keep int versus real (design section 8.5). */
+    /** A json column holds numbers; GML records cannot keep int versus real. */
     RECORD_NUMBER_TYPE: RECORD_NUMBER_TYPE_CODE,
     /** A json column holds booleans, written 1 / 0. */
     RECORD_BOOLEAN: RECORD_BOOLEAN_CODE,
     /** A json column holds nulls, omitted. */
     RECORD_NULL: RECORD_NULL_CODE,
-    /** An array inside an array; export() throws. */
+    /** An attribute holds an array inside an array, which GML cannot write; the save fails. */
     NESTED_ARRAY: NESTED_ARRAY_CODE,
     /** A json row that is an array, written as repeated keys. */
     JSON_ARRAY: JSON_ARRAY_CODE,
-    /** A column name or record key outside the GML key grammar. */
+    /**
+     * An attribute name GML cannot use as a key (keys are letters and digits, starting with a letter). The save fails
+     * unless `sanitizeKeys` is "mangle".
+     */
     INVALID_KEY: INVALID_KEY_CODE,
     /** A column named like a structural key. */
     RESERVED_KEY: RESERVED_KEY_CODE,

package/src/formats/gml/syntax.ts

@@ -12,46 +12,86 @@
 
 import { SYNTAX_CODE } from "../../common/codes.js";
 import { decodeGmlString } from "../../common/escape.js";
+import { plural } from "../../common/plural.js";
 
-/** A bare word: a key, or `INF` / `NAN` at a value position. */
+/**
+ * A bare word: a key, or `INF` / `NAN` at a value position.
+ * @category Plugin helpers
+ */
 export const TOKEN_WORD = 0;
-/** An integer literal. */
+/**
+ * An integer literal.
+ * @category Plugin helpers
+ */
 export const TOKEN_INT = 1;
-/** A real literal, including the non-finite spellings. */
+/**
+ * A real literal, including the non-finite spellings.
+ * @category Plugin helpers
+ */
 export const TOKEN_REAL = 2;
-/** A double-quoted string; start / end delimit the body between the quotes. */
+/**
+ * A double-quoted string; start / end delimit the body between the quotes.
+ * @category Plugin helpers
+ */
 export const TOKEN_STRING = 3;
-/** `[`. */
+/**
+ * `[`.
+ * @category Plugin helpers
+ */
 export const TOKEN_OPEN = 4;
-/** `]`. */
+/**
+ * `]`.
+ * @category Plugin helpers
+ */
 export const TOKEN_CLOSE = 5;
 
 /** The kind of one token. */
 type TokenKind = 0 | 1 | 2 | 3 | 4 | 5;
 
-/** The NetworkX marker that starts a one-element list written as repeated keys. */
+/**
+ * The NetworkX marker that starts a one-element list written as repeated keys.
+ * @category Plugin helpers
+ */
 export const LIST_START_MARKER = "_networkx_list_start";
 
-/** The string NetworkX writes for an empty list. */
+/**
+ * The string NetworkX writes for an empty list.
+ * @category Plugin helpers
+ */
 export const EMPTY_LIST_TEXT = "[]";
 
-/** The string NetworkX writes for an empty tuple, read as an empty list too. */
+/**
+ * The string NetworkX writes for an empty tuple, read as an empty list too.
+ * @category Plugin helpers
+ */
 export const EMPTY_TUPLE_TEXT = "()";
 
-/** The node key the exporter writes a mangled node's original id into (design section 8.5). */
+/**
+ * The node key the exporter writes a mangled node's original id into (design section 8.5).
+ * @category Plugin helpers
+ */
 export const ORIGINAL_ID_KEY = "graphty_originalId";
 
 /**
- * Issue code of every grammar violation (shared with the other text formats; the message carries
- * the detail): a bare token that is neither a key nor a number, an unclosed string, an unclosed
- * `[`, a `]` with no open `[`, a value without a key or a key without a value.
+ * The text breaks the format's syntax: a word that is not a key or a number, an unclosed string or `[`, a `]` with no
+ * open `[`, or a key without a value. The message says where. The import stops.
+ * @category Issue and loss codes
  */
 export const SYNTAX_STRUCTURE_CODE = SYNTAX_CODE;
-/** The code of an untokenisable bare token (E_SYNTAX). */
+/**
+ * The code of an untokenizable bare token (E_SYNTAX).
+ * @category Issue and loss codes
+ */
 export const SYNTAX_TOKEN_CODE = SYNTAX_CODE;
-/** The code of an unclosed string (E_SYNTAX). */
+/**
+ * The code of an unclosed string (E_SYNTAX).
+ * @category Issue and loss codes
+ */
 export const SYNTAX_STRING_CODE = SYNTAX_CODE;
-/** The code of an unclosed `[` (E_SYNTAX). */
+/**
+ * The code of an unclosed `[` (E_SYNTAX).
+ * @category Issue and loss codes
+ */
 export const SYNTAX_BRACKET_CODE = SYNTAX_CODE;
 
 const KEY_TEXT = /^[A-Za-z_][0-9A-Za-z_]*$/;
@@ -64,6 +104,7 @@ const NON_FINITE_WORD = /^(?:inf|infinity|nan)$/i;
 /**
  * A lexical or structural error of a GML text, with the 1-based line it was found on. The importer
  * turns it into a fatal parse-error issue.
+ * @category Plugin helpers
  */
 export class GmlSyntaxError extends Error {
     /** The issue code. */
@@ -89,6 +130,7 @@ export class GmlSyntaxError extends Error {
 /**
  * The tokens of one GML text, structurally validated: every `[` has its matching `]` recorded and
  * every key is followed by a value, so walkers need no error paths.
+ * @category Plugin helpers
  */
 export class GmlTokens {
     /** The source text the offsets index into. */
@@ -162,12 +204,23 @@ export class GmlTokens {
      * @returns the body with character references decoded
      */
     stringOf(i: number): string {
-        const text = this.textOf(i);
+        let text = this.textOf(i);
+        if (text.includes("\r")) {
+            // a line break inside a string is part of it, as LF whatever the file's line ends
+            text = text.replaceAll(/\r\n?/g, "\n");
+        }
         if (text.indexOf("&") < 0) {
             return text;
         }
         const report = this.onUnknownEntity;
-        return decodeGmlString(text, report === null ? undefined : (entity) => { report(entity, this.line[i]); });
+        return decodeGmlString(
+            text,
+            report === null
+                ? undefined
+                : (entity) => {
+                      report(entity, this.line[i]);
+                  },
+        );
     }
 
     /**
@@ -211,8 +264,9 @@ export class GmlTokens {
  * Lex and structurally validate a whole GML text.
  *
  * Lexical rules (NetworkX): whitespace separates tokens; `#` outside a string starts a comment
- * that runs to the end of the line; a string is delimited by double quotes and must close on its
- * line (there is no escape mechanism; `&#NN;` references are decoded later); `[` and `]` are
+ * that runs to the end of the line; a string is delimited by double quotes and may span lines (a
+ * line break inside is part of it, GML draft 3.2.5; there is no escape mechanism; `&#NN;`
+ * references are decoded later); a U+FEFF between tokens is whitespace; `[` and `]` are
  * single-character tokens; every other run of characters is a key (`[A-Za-z_][0-9A-Za-z_]*`),
  * an integer (`[+-]?[0-9]+`), a real (with a decimal point or an exponent, or `INF` / `NAN` in
  * any case with an optional sign) or an error.
@@ -221,12 +275,15 @@ export class GmlTokens {
  * string, `INF` / `NAN`, or a bracketed sequence of pairs; every `[` has a `]`.
  * @param text - the GML text
  * @returns the validated tokens; GmlSyntaxError with the line of the first problem
+ * @category Plugin helpers
  */
 export function tokenizeGml(text: string): GmlTokens {
     const tokens = new GmlTokens(text, Math.max(1024, text.length >>> 3));
     const n = text.length;
     let i = 0;
     let line = 1;
+    // the opening line of the first string that spans lines: where a missing quote most likely is
+    let spanningLine = 0;
     while (i < n) {
         const c = text.charCodeAt(i);
         if (c === 10) {
@@ -240,6 +297,9 @@ export function tokenizeGml(text: string): GmlTokens {
             }
         } else if (c === 32 || c === 9 || c === 11 || c === 12) {
             i++;
+        } else if (c === 0xfeff) {
+            // a BOM left inside by concatenated files is whitespace; the shared text check reports it
+            i++;
         } else if (c === 35) {
             i = endOfLine(text, i);
         } else if (c === 91) {
@@ -250,11 +310,24 @@ export function tokenizeGml(text: string): GmlTokens {
             i++;
         } else if (c === 34) {
             const close = text.indexOf('"', i + 1);
-            const eol = endOfLine(text, i + 1);
-            if (close < 0 || close > eol) {
-                throw new GmlSyntaxError(SYNTAX_STRING_CODE, `unclosed string at line ${line}`, line);
+            if (close < 0) {
+                const hint =
+                    spanningLine === 0
+                        ? ""
+                        : `; the string opened at line ${spanningLine} spans lines, so a quote may be missing there`;
+                throw new GmlSyntaxError(SYNTAX_STRING_CODE, `unclosed string opened at line ${line}${hint}`, line);
             }
             tokens.push(TOKEN_STRING, i + 1, close, line);
+            const opened = line;
+            for (let k = i + 1; k < close; k++) {
+                const d = text.codePointAt(k);
+                if (d === 10 || (d === 13 && text.codePointAt(k + 1) !== 10)) {
+                    line++;
+                }
+            }
+            if (line !== opened && spanningLine === 0) {
+                spanningLine = opened;
+            }
             i = close + 1;
         } else {
             let j = i + 1;
@@ -325,8 +398,14 @@ function classifyBare(text: string, start: number, end: number, line: number): T
     if (REAL_TEXT.test(token) || NON_FINITE_TEXT.test(token)) {
         return TOKEN_REAL;
     }
-    const shown = token.length > 20 ? `${token.slice(0, 20)}...` : token;
-    throw new GmlSyntaxError(SYNTAX_TOKEN_CODE, `cannot tokenize "${shown}" at line ${line}`, line);
+    // the message is ASCII: a character outside it is shown as \uXXXX and named, since it may look
+    // like something else (a no-break space pasted from a web page looks like a space)
+    const hex = (c: string): string => (c.codePointAt(0) ?? 0).toString(16).toUpperCase().padStart(4, "0");
+    const head = token.length > 20 ? `${token.slice(0, 20)}...` : token;
+    const shown = head.replaceAll(/[^\x20-\x7e]/gu, (c) => String.raw`\u` + hex(c));
+    const odd = /[^\x21-\x7e]/u.exec(token);
+    const note = odd === null ? "" : ` (it holds U+${hex(odd[0])}, which GML allows only inside a string)`;
+    throw new GmlSyntaxError(SYNTAX_TOKEN_CODE, `cannot tokenize "${shown}" at line ${line}${note}`, line);
 }
 
 /**
@@ -384,7 +463,7 @@ function validateStructure(tokens: GmlTokens): void {
         const open = stack[stack.length - 1];
         throw new GmlSyntaxError(
             SYNTAX_BRACKET_CODE,
-            `unexpected end of input: ${stack.length} bracket(s) still open, the last opened at line ${tokens.line[open]}`,
+            `unexpected end of input: ${stack.length} bracket${plural(stack.length)} still open, the last opened at line ${tokens.line[open]}`,
             tokens.line[open],
         );
     }
@@ -414,6 +493,7 @@ function describeToken(tokens: GmlTokens, i: number): string {
  * The numeric value of an INT or REAL token (or a WORD that is `INF` / `NAN` at a value position).
  * @param text - the token text
  * @returns the number; Infinity / -Infinity / NaN for the non-finite spellings
+ * @category Plugin helpers
  */
 export function numberOfText(text: string): number {
     if (NON_FINITE_TEXT.test(text)) {
@@ -431,6 +511,7 @@ export function numberOfText(text: string): number {
  * @param tokens - the tokens
  * @param i - the value token index
  * @returns true when the word is a real
+ * @category Plugin helpers
  */
 export function isNonFiniteWord(tokens: GmlTokens, i: number): boolean {
     return tokens.kind[i] === TOKEN_WORD && NON_FINITE_WORD.test(tokens.textOf(i));
@@ -441,6 +522,7 @@ export function isNonFiniteWord(tokens: GmlTokens, i: number): boolean {
  * writes and reads).
  * @param text - the candidate key
  * @returns true when it can be written as a key
+ * @category Plugin helpers
  */
 export function isGmlKey(text: string): boolean {
     return STRICT_KEY_TEXT.test(text);
@@ -451,6 +533,7 @@ export function isGmlKey(text: string): boolean {
  * non-letter is prefixed with `x` (the exporter's `sanitizeKeys: "mangle"`).
  * @param text - the text
  * @returns a valid key
+ * @category Plugin helpers
  */
 export function mangleGmlKey(text: string): string {
     const body = text.replace(/[^0-9A-Za-z_]/g, "_");
@@ -479,6 +562,7 @@ interface RecordFrame {
  * @param tokens - the validated tokens
  * @param open - the index of the record's `[`
  * @returns a null-prototype object
+ * @category Plugin helpers
  */
 export function parseRecord(tokens: GmlTokens, open: number): Record<string, unknown> {
     const root = Object.create(null) as Record<string, unknown>;
@@ -547,6 +631,7 @@ function storeValue(frame: RecordFrame, key: string, value: unknown): void {
  * @param tokens - the tokens
  * @param v - the value token index (INT, REAL, non-finite WORD or OPEN)
  * @returns the value
+ * @category Plugin helpers
  */
 export function scalarOrRecord(tokens: GmlTokens, v: number): unknown {
     return tokens.kind[v] === TOKEN_OPEN ? parseRecord(tokens, v) : numberOfText(tokens.textOf(v));