@graphty/graph-io 0.3.40 → 0.3.42

package/src/formats/pajek/exporter.ts

@@ -177,129 +177,192 @@ interface PlannedColumn {
  */
 function plan(table: Iterable<Column>, domain: "node" | "edge", notes: LossNote[] | null): PlannedColumn[] {
     const planned: PlannedColumn[] = [];
-    const rows = (column: Column): number => column.length - column.nullCount;
     for (const column of table) {
-        const { meta } = column;
-        const { role, name, dtype } = meta;
-        if (role === "label" && domain === "node") {
-            if (dtype !== "string" && dtype !== "dict" && notes !== null) {
-                notes.push(
-                    note(
-                        PAJEK_LOSS.LABEL_AS_TEXT,
-                        `node column "${name}" (label) is ${dtype}; labels are text and re-import as string`,
-                        name,
-                        rows(column),
-                    ),
-                );
-            }
-            planned.push({ column, slot: "label" });
-            continue;
-        }
-        if (role === "position") {
-            if (domain === "node" && (meta.components === 2 || meta.components === 3)) {
-                planned.push({ column, slot: "position" });
-            } else if (notes !== null && domain === "node") {
-                notes.push(
-                    note(
-                        PAJEK_LOSS.POSITION_STRIDE,
-                        `node column "${name}" (position) has ${meta.components} components; Pajek coordinates are x y [z]`,
-                        name,
-                        rows(column),
-                    ),
-                );
-            } else if (notes !== null) {
-                notes.push(
-                    note(LOSS.POSITIONS, `edge column "${name}" (position) cannot be written`, name, rows(column)),
-                );
-            }
-            continue;
-        }
-        if (role === "spells") {
-            if (
-                dtype === "list" &&
-                (meta.itemDtype === "f64" || meta.itemDtype === "i32" || meta.itemDtype === "f32")
-            ) {
-                planned.push({ column, slot: "spells" });
-                continue;
-            }
-            if (notes !== null) {
-                notes.push(
-                    note(
-                        LOSS.SPELLS,
-                        `${domain} column "${name}" (spells) is not a list of number pairs; it cannot be written`,
-                        name,
-                        rows(column),
-                    ),
-                );
-            }
-            continue;
+        const slot = columnSlot(column, domain, notes);
+        if (slot !== null) {
+            planned.push({ column, slot });
         }
-        if (role !== null && DROPPED_TEMPORAL_ROLES.has(role)) {
-            if (notes !== null) {
-                notes.push(
-                    note(
-                        PAJEK_LOSS.TEMPORAL_DROPPED,
-                        `${domain} column "${name}" (${role}) cannot be written; Pajek intervals come from the spells role`,
-                        name,
-                        rows(column),
-                    ),
-                );
-            }
-            continue;
-        }
-        if (role !== null && (STRUCTURAL_ROLES.has(role) || CHECKED_ROLES.has(role))) {
-            // structural columns are folded into the topology; viz and hierarchy roles are reported by the generic checker
-            continue;
-        }
-        if (domain === "edge" && role === "id") {
-            continue;
-        }
-        if (dtype === "list" || dtype === "json") {
-            // reported by the generic checker (lists: false, json: false)
-            continue;
-        }
-        if (domain === "node" && name === SHAPE_COLUMN && (dtype === "dict" || dtype === "string")) {
-            if (allShapeKeywords(column)) {
-                planned.push({ column, slot: "shape" });
-                continue;
-            }
-            // a value outside the keywords: the whole column is a `shape "<text>"` parameter, which the
-            // importer reads back as one string column (a change for a dict column only)
-            if (notes !== null && dtype === "dict") {
-                notes.push(
-                    note(
-                        PAJEK_LOSS.SHAPE_AS_PARAMETER,
-                        `node column "${name}" holds values outside the Pajek shape keywords; it is written as a parameter and reads back as string`,
-                        name,
-                        rows(column),
-                    ),
-                );
-            }
-            planned.push({ column, slot: "param" });
-            continue;
-        }
-        if (domain === "edge" && name === RELATION_COLUMN && (dtype === "dict" || dtype === "string")) {
-            planned.push({ column, slot: "relation" });
-            continue;
-        }
-        if (!isParameterKey(name)) {
-            if (notes !== null) {
-                notes.push(
-                    note(
-                        PAJEK_LOSS.KEY_DROPPED,
-                        `${domain} column "${name}" cannot be a Pajek parameter key; it is not written`,
-                        name,
-                        rows(column),
-                    ),
-                );
-            }
-            continue;
-        }
-        planned.push({ column, slot: "param" });
     }
     return planned;
 }
 
+/**
+ * Record a note about a whole column, counting its set values; nothing when writing.
+ * @param notes - the note list check() fills; null when writing
+ * @param code - the code
+ * @param message - the message
+ * @param column - the column the note is about
+ */
+function columnNote(notes: LossNote[] | null, code: string, message: string, column: Column): void {
+    notes?.push(note(code, message, column.meta.name, column.length - column.nullCount));
+}
+
+/**
+ * The slot of one column, recording a note for a column that is not written as it is.
+ * @param column - the column
+ * @param domain - node or edge
+ * @param notes - the note list check() fills; null when writing
+ * @returns the slot, or null when the column is not written
+ */
+function columnSlot(column: Column, domain: "node" | "edge", notes: LossNote[] | null): Slot | null {
+    const { role, name } = column.meta;
+    if (role === "label" && domain === "node") {
+        return labelSlot(column, notes);
+    }
+    if (role === "position") {
+        return positionSlot(column, domain, notes);
+    }
+    if (role === "spells") {
+        return spellsSlot(column, domain, notes);
+    }
+    if (role !== null && DROPPED_TEMPORAL_ROLES.has(role)) {
+        columnNote(
+            notes,
+            PAJEK_LOSS.TEMPORAL_DROPPED,
+            `${domain} column "${name}" (${role}) cannot be written; Pajek intervals come from the spells role`,
+            column,
+        );
+        return null;
+    }
+    if (writtenElsewhere(column, domain)) {
+        return null;
+    }
+    return namedSlot(column, domain, notes);
+}
+
+/**
+ * The node label column: the label slot, noting a label that is not text.
+ * @param column - the label role column
+ * @param notes - the note list check() fills; null when writing
+ * @returns the label slot
+ */
+function labelSlot(column: Column, notes: LossNote[] | null): Slot {
+    const { name, dtype } = column.meta;
+    if (dtype !== "string" && dtype !== "dict") {
+        columnNote(
+            notes,
+            PAJEK_LOSS.LABEL_AS_TEXT,
+            `node column "${name}" (label) is ${dtype}; labels are text and re-import as string`,
+            column,
+        );
+    }
+    return "label";
+}
+
+/**
+ * A position role column: the coordinates of a node with 2 or 3 components, else not written.
+ * @param column - the position role column
+ * @param domain - node or edge
+ * @param notes - the note list check() fills; null when writing
+ * @returns the position slot, or null
+ */
+function positionSlot(column: Column, domain: "node" | "edge", notes: LossNote[] | null): Slot | null {
+    const { name, components } = column.meta;
+    if (domain === "edge") {
+        columnNote(notes, LOSS.POSITIONS, `edge column "${name}" (position) cannot be written`, column);
+        return null;
+    }
+    if (components === 2 || components === 3) {
+        return "position";
+    }
+    columnNote(
+        notes,
+        PAJEK_LOSS.POSITION_STRIDE,
+        `node column "${name}" (position) has ${components} components; Pajek coordinates are x y [z]`,
+        column,
+    );
+    return null;
+}
+
+/**
+ * A spells role column: the interval slot for a list of numbers, else not written.
+ * @param column - the spells role column
+ * @param domain - node or edge
+ * @param notes - the note list check() fills; null when writing
+ * @returns the spells slot, or null
+ */
+function spellsSlot(column: Column, domain: "node" | "edge", notes: LossNote[] | null): Slot | null {
+    const { name, dtype, itemDtype } = column.meta;
+    if (dtype === "list" && (itemDtype === "f64" || itemDtype === "i32" || itemDtype === "f32")) {
+        return "spells";
+    }
+    columnNote(
+        notes,
+        LOSS.SPELLS,
+        `${domain} column "${name}" (spells) is not a list of number pairs; it cannot be written`,
+        column,
+    );
+    return null;
+}
+
+/**
+ * Whether a column is folded into the topology, reported by the generic checker, or an edge id,
+ * so it is never a parameter.
+ * @param column - the column
+ * @param domain - node or edge
+ * @returns true when the column has no slot of its own
+ */
+function writtenElsewhere(column: Column, domain: "node" | "edge"): boolean {
+    const { role, dtype } = column.meta;
+    // structural columns are folded into the topology; viz and hierarchy roles, lists and json are
+    // reported by the generic checker (lists: false, json: false)
+    if (role !== null && (STRUCTURAL_ROLES.has(role) || CHECKED_ROLES.has(role))) {
+        return true;
+    }
+    return (domain === "edge" && role === "id") || dtype === "list" || dtype === "json";
+}
+
+/**
+ * The slot of a column written by its name: the shape keyword, the relation name, or a parameter.
+ * @param column - the column
+ * @param domain - node or edge
+ * @param notes - the note list check() fills; null when writing
+ * @returns the slot, or null when the name cannot be a parameter key
+ */
+function namedSlot(column: Column, domain: "node" | "edge", notes: LossNote[] | null): Slot | null {
+    const { name, dtype } = column.meta;
+    const text = dtype === "dict" || dtype === "string";
+    if (text && domain === "node" && name === SHAPE_COLUMN) {
+        return shapeSlot(column, notes);
+    }
+    if (text && domain === "edge" && name === RELATION_COLUMN) {
+        return "relation";
+    }
+    if (!isParameterKey(name)) {
+        columnNote(
+            notes,
+            PAJEK_LOSS.KEY_DROPPED,
+            `${domain} column "${name}" cannot be a Pajek parameter key; it is not written`,
+            column,
+        );
+        return null;
+    }
+    return "param";
+}
+
+/**
+ * A text node column named `shape`: the shape slot when every value is a keyword, else the whole
+ * column is a `shape "<text>"` parameter, which the importer reads back as one string column (a
+ * change for a dict column only).
+ * @param column - the shape column (string or dict)
+ * @param notes - the note list check() fills; null when writing
+ * @returns the shape or param slot
+ */
+function shapeSlot(column: Column, notes: LossNote[] | null): Slot {
+    if (allShapeKeywords(column)) {
+        return "shape";
+    }
+    if (column.meta.dtype === "dict") {
+        columnNote(
+            notes,
+            PAJEK_LOSS.SHAPE_AS_PARAMETER,
+            `node column "${column.meta.name}" holds values outside the Pajek shape keywords; it is written as a parameter and reads back as string`,
+            column,
+        );
+    }
+    return "param";
+}
+
 /**
  * The notes about vertex labels: Pajek's grammar puts the label second, so a vertex line that
  * carries coordinates, a shape, parameters or an interval needs one, and a node without a label

package/src/formats/pajek/importer.ts

@@ -686,21 +686,7 @@ class PajekParser {
                 this.section = "none";
                 return;
             case "vertices":
-                if (afterObjectHeader) {
-                    // the `*Vertices N` line of a project object (*Partition, *Vector, a skipped
-                    // section), wherever it stands: never the network's own
-                    this.section = previous;
-                    if (previous === "object") {
-                        this.objects[this.objects.length - 1].count = h.count;
-                    }
-                    return;
-                }
-                if (this.vertexCount >= 0) {
-                    // a second `*Vertices` without a `*Network` header starts the next network
-                    this.ended = true;
-                    return;
-                }
-                this.verticesHeader(h, line);
+                this.verticesSectionLine(h, line, previous, afterObjectHeader);
                 return;
             case "arcs":
             case "edges":
@@ -739,6 +725,32 @@ class PajekParser {
         }
     }
 
+    /**
+     * A `*Vertices` line: a project object's own count, the start of the next network, or the
+     * network's vertices header.
+     * @param h - the header
+     * @param line - the line number
+     * @param previous - the section before this header
+     * @param afterObjectHeader - the previous line was a `*Partition`, `*Vector` or skipped section header
+     */
+    private verticesSectionLine(h: SectionHeader, line: number, previous: Section, afterObjectHeader: boolean): void {
+        if (afterObjectHeader) {
+            // the `*Vertices N` line of a project object (*Partition, *Vector, a skipped
+            // section), wherever it stands: never the network's own
+            this.section = previous;
+            if (previous === "object") {
+                this.objects[this.objects.length - 1].count = h.count;
+            }
+            return;
+        }
+        if (this.vertexCount >= 0) {
+            // a second `*Vertices` without a `*Network` header starts the next network
+            this.ended = true;
+            return;
+        }
+        this.verticesHeader(h, line);
+    }
+
     /**
      * `*Vertices N [N1]`.
      * @param h - the header

package/src/formats/pajek/syntax.ts

@@ -350,57 +350,88 @@ export function parseSectionHeader(line: string): SectionHeader | null {
     }
     const keyword = tokens[0];
     const kind = SECTION_KINDS.get(keyword.toLowerCase()) ?? "unsupported";
-    let count: number | null = null;
-    let secondCount: number | null = null;
-    let relation: number | null = null;
-    let name: string | null = null;
-    const extra: string[] = [];
-    let i = 1;
+    let args: HeaderArgs;
     switch (kind) {
         case "vertices":
-            if (i < tokens.length && INTEGER_TEXT.test(tokens[i])) {
-                count = Number(tokens[i]);
-                i++;
-                if (i < tokens.length && INTEGER_TEXT.test(tokens[i])) {
-                    secondCount = Number(tokens[i]);
-                    i++;
-                }
-            }
+            args = verticesArgs(tokens);
             break;
         case "arcs":
         case "edges":
         case "arcslist":
         case "edgeslist":
         case "matrix":
-            if (i < tokens.length && tokens[i].startsWith(":") && INTEGER_TEXT.test(tokens[i].slice(1))) {
-                relation = Number(tokens[i].slice(1));
-                i++;
-                if (i < tokens.length) {
-                    name = tokens[i];
-                    i++;
-                }
-            }
+            args = relationArgs(tokens);
             break;
         case "network":
         case "partition":
         case "vector":
-            if (i < tokens.length) {
-                name = tokens.slice(i).join(" ");
-                i = tokens.length;
-            }
+            args = nameArgs(tokens);
             break;
         case "unsupported":
-            i = tokens.length;
+            args = { ...NO_ARGS, next: tokens.length };
             break;
         default: {
             const unknown: string = kind;
             throw new Error(`unknown section kind ${unknown}`);
         }
     }
-    for (; i < tokens.length; i++) {
-        extra.push(tokens[i]);
+    const { count, secondCount, relation, name, next } = args;
+    return { kind, keyword, count, secondCount, relation, name, extra: tokens.slice(next) };
+}
+
+/** The arguments a section header's keyword takes, and the index of the first token after them. */
+interface HeaderArgs {
+    readonly count: number | null;
+    readonly secondCount: number | null;
+    readonly relation: number | null;
+    readonly name: string | null;
+    readonly next: number;
+}
+
+const NO_ARGS: HeaderArgs = { count: null, secondCount: null, relation: null, name: null, next: 1 };
+
+/**
+ * `*Vertices N [N1]`: the vertex count and the optional first-mode count.
+ * @param tokens - the header tokens, the keyword first
+ * @returns the arguments
+ */
+function verticesArgs(tokens: readonly string[]): HeaderArgs {
+    if (tokens.length < 2 || !INTEGER_TEXT.test(tokens[1])) {
+        return NO_ARGS;
+    }
+    const count = Number(tokens[1]);
+    if (tokens.length < 3 || !INTEGER_TEXT.test(tokens[2])) {
+        return { ...NO_ARGS, count, next: 2 };
     }
-    return { kind, keyword, count, secondCount, relation, name, extra };
+    return { ...NO_ARGS, count, secondCount: Number(tokens[2]), next: 3 };
+}
+
+/**
+ * `*Arcs [:k ["name"]]` and the other line sections: the relation number and its name.
+ * @param tokens - the header tokens, the keyword first
+ * @returns the arguments
+ */
+function relationArgs(tokens: readonly string[]): HeaderArgs {
+    if (tokens.length < 2 || !tokens[1].startsWith(":") || !INTEGER_TEXT.test(tokens[1].slice(1))) {
+        return NO_ARGS;
+    }
+    const relation = Number(tokens[1].slice(1));
+    if (tokens.length < 3) {
+        return { ...NO_ARGS, relation, next: 2 };
+    }
+    return { ...NO_ARGS, relation, name: tokens[2], next: 3 };
+}
+
+/**
+ * `*Network name`, `*Partition name`, `*Vector name`: every token after the keyword is the name.
+ * @param tokens - the header tokens, the keyword first
+ * @returns the arguments
+ */
+function nameArgs(tokens: readonly string[]): HeaderArgs {
+    if (tokens.length < 2) {
+        return NO_ARGS;
+    }
+    return { ...NO_ARGS, name: tokens.slice(1).join(" "), next: tokens.length };
 }
 
 /**
@@ -447,38 +478,48 @@ export function parseIntervals(token: string): [number, number][] {
     }
     const spells: [number, number][] = [];
     for (const part of body.split(",")) {
-        const match = TIME_POINT.exec(part.replaceAll(/\s+/g, ""));
-        if (match === null) {
-            throw new Error(`malformed time interval ${token}: "${part}" is not a-b, a-* or a`);
-        }
-        const [, startText, endText] = match;
-        if (startText === "*" && endText === undefined) {
-            throw new Error(`malformed time interval ${token}: "*" alone is not a time point`);
-        }
-        const start = startText === "*" ? -Infinity : Number(startText);
-        let end: number;
-        if (endText === undefined) {
-            end = start;
-        } else if (endText === "*") {
-            end = Infinity;
-        } else {
-            end = Number(endText);
-        }
-        // only `*` means an open end: a numeral beyond the f64 range is not a time
-        if (
-            (startText !== "*" && !Number.isFinite(start)) ||
-            (endText !== undefined && endText !== "*" && !Number.isFinite(end))
-        ) {
-            throw new Error(`malformed time interval ${token}: "${part}" is beyond the number range`);
-        }
-        if (start > end) {
-            throw new Error(`malformed time interval ${token}: ${startText} is after ${endText ?? ""}`);
-        }
-        spells.push([start, end]);
+        spells.push(parseSpell(token, part));
     }
     return spells;
 }
 
+/**
+ * One part of a Pajek time interval token: `a-b`, `a-*`, `*-b` or a single time point `a`.
+ * @param token - the whole token, for the error message
+ * @param part - the part between commas
+ * @returns the spell as a [start, end] pair
+ */
+function parseSpell(token: string, part: string): [number, number] {
+    const match = TIME_POINT.exec(part.replaceAll(/\s+/g, ""));
+    if (match === null) {
+        throw new Error(`malformed time interval ${token}: "${part}" is not a-b, a-* or a`);
+    }
+    const [, startText, endText] = match;
+    if (startText === "*" && endText === undefined) {
+        throw new Error(`malformed time interval ${token}: "*" alone is not a time point`);
+    }
+    const start = startText === "*" ? -Infinity : Number(startText);
+    let end: number;
+    if (endText === undefined) {
+        end = start;
+    } else if (endText === "*") {
+        end = Infinity;
+    } else {
+        end = Number(endText);
+    }
+    // only `*` means an open end: a numeral beyond the f64 range is not a time
+    if (
+        (startText !== "*" && !Number.isFinite(start)) ||
+        (endText !== undefined && endText !== "*" && !Number.isFinite(end))
+    ) {
+        throw new Error(`malformed time interval ${token}: "${part}" is beyond the number range`);
+    }
+    if (start > end) {
+        throw new Error(`malformed time interval ${token}: ${startText} is after ${endText ?? ""}`);
+    }
+    return [start, end];
+}
+
 // any length, so a reference beyond U+10FFFF is seen (and kept as written with a warning)
 const CHARACTER_REFERENCE = /&#(?:[xX]([\da-fA-F]+)|(\d+));/g;