@graphty/graph-io 0.3.25 → 0.3.27

package/src/formats/pajek/index.ts

@@ -1,6 +1,7 @@
 /**
- * The `@graphty/graph-io/pajek` subpath (design section 8.2): the Pajek NET importer and exporter
+ * The `@graphty/graph-io/pajek` subpath: the Pajek NET importer and exporter
  * with their option types and issue / loss codes.
+ * @module @graphty/graph-io/pajek
  */
 
 export { PAJEK_LOSS, pajekExporter, type PajekExportOptions } from "./exporter.js";

package/src/formats/pajek/syntax.ts

@@ -8,36 +8,64 @@
  * `&#dddd;` character references of labels, and the column names both sides agree on.
  */
 
-/** The node column holding the vertex label (role label). */
+/**
+ * The node column holding the vertex label (role label).
+ * @category Plugin helpers
+ */
 export const LABEL_COLUMN = "label";
 
-/** The node column holding the vertex coordinates (role position, f32 x 3, units "file"). */
+/**
+ * The node column holding the vertex coordinates (role position, f32 x 3, units "file").
+ * @category Plugin helpers
+ */
 export const POSITION_COLUMN = "position";
 
-/** The node column holding the vertex shape keyword (dict, no role: Pajek has its own keyword set). */
+/**
+ * The node column holding the vertex shape keyword (dict, no role: Pajek has its own keyword set).
+ * @category Plugin helpers
+ */
 export const SHAPE_COLUMN = "shape";
 
-/** The edge column holding the relation name of a `*Arcs :k "name"` section (dict). */
+/**
+ * The edge column holding the relation name of a `*Arcs :k "name"` section (dict).
+ * @category Plugin helpers
+ */
 export const RELATION_COLUMN = "relation";
 
-/** The node or edge column holding Pajek time intervals (list of f64 pairs, role spells). */
+/**
+ * The node or edge column holding Pajek time intervals (list of f64 pairs, role spells).
+ * @category Plugin helpers
+ */
 export const SPELLS_COLUMN = "spells";
 
-/** The edge column holding the line value when `weightFrom` names another field or null. */
+/**
+ * The edge column holding the line value when `weightFrom` names another field or null.
+ * @category Plugin helpers
+ */
 export const VALUE_COLUMN = "value";
 
-/** The `weightFrom` default: Pajek's third column is the line value (design section 8.4). */
+/**
+ * The `weightFrom` default: Pajek's third column is the line value (design section 8.4).
+ * @category Plugin helpers
+ */
 export const VALUE_FIELD = "value";
 
-/** The node column holding the values of a `*Partition` object (i32). */
+/**
+ * The node column holding the values of a `*Partition` object (i32).
+ * @category Plugin helpers
+ */
 export const PARTITION_COLUMN = "partition";
 
-/** The node column holding the values of a `*Vector` object (f64). */
+/**
+ * The node column holding the values of a `*Vector` object (f64).
+ * @category Plugin helpers
+ */
 export const VECTOR_COLUMN = "vector";
 
 /**
  * The vertex shape keywords of the Pajek manual, lower-cased; a file may write them in any case
  * (use isShapeKeyword()).
+ * @category Plugin helpers
  */
 export const SHAPES: ReadonlySet<string> = new Set([
     "ellipse",
@@ -55,6 +83,7 @@ export const SHAPES: ReadonlySet<string> = new Set([
  * Whether a token is a vertex shape keyword, in any case (`Ellipse`, `BOX`).
  * @param token - the token
  * @returns true for a shape keyword
+ * @category Plugin helpers
  */
 export function isShapeKeyword(token: string): boolean {
     return SHAPES.has(token.toLowerCase());
@@ -77,10 +106,14 @@ type SectionKind =
  * The parameter key the exporter writes a node's original id under when `sanitizeIds: "mangle"`
  * renumbers it (design section 8.5: the exporter names the attribute, `restoreMangledIds` reads
  * it back); a user column of that name is reserved under "mangle".
+ * @category Plugin helpers
  */
 export const ORIGINAL_ID_KEY = "graphty_originalId";
 
-/** A parsed section header line. */
+/**
+ * A parsed section header line.
+ * @category Plugin helpers
+ */
 export interface SectionHeader {
     /** The section kind. */
     readonly kind: SectionKind;
@@ -114,60 +147,156 @@ const INTEGER_TEXT = /^[+-]?[0-9]+$/;
 const TIME_POINT =
     /^(\*|[+-]?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?)(?:-(\*|[+-]?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?))?$/;
 
+/**
+ * What tokenize() noticed in a line beyond its tokens, for the importer to report.
+ * @category Plugin helpers
+ */
+export interface TokenNotes {
+    /** A double quote in the middle of a token (`ab"c d"e`, a CSV-style doubled `""`): removed, the parts joined. */
+    oddQuote: boolean;
+}
+
 /**
  * Split one line into tokens: runs of non-whitespace, with double quotes grouping whitespace
  * into one token and removed from it (the shlex rule NetworkX applies; Pajek has no escapes, so a
  * quote never appears inside a token). An empty quoted string `""` is one empty token. A token
  * that starts with `[` runs to the next `]` whatever whitespace it holds (when no other `[` comes
- * first), so a time set written `[ 1, 3 ]` is one token.
+ * first), so a time set written `[ 1, 3 ]` is one token. A `%` mid-line is data (`2 %b` is a
+ * label): Pajek's comments are whole lines, which the caller skips before tokenizing.
  * @param line - the line without its terminator
+ * @param notes - when given, set to what the line held beyond its tokens
  * @returns the tokens, or null when a quote is not closed before the end of the line
+ * @category Plugin helpers
  */
-export function tokenize(line: string): string[] | null {
-    const tokens: string[] = [];
-    let current = "";
-    let started = false;
-    let quoted = false;
-    for (let i = 0; i < line.length; i++) {
-        const c = line.charCodeAt(i);
+export function tokenize(line: string, notes?: TokenNotes): string[] | null {
+    const tokens = new LineTokens(line, notes);
+    let i = 0;
+    while (i < line.length) {
+        i = tokens.step(i);
+    }
+    return tokens.finish();
+}
+
+/** The state of tokenize() along one line. */
+class LineTokens {
+    private readonly tokens: string[] = [];
+
+    private current = "";
+
+    private started = false;
+
+    private quoted = false;
+
+    /**
+     * Start a line.
+     * @param line - the line
+     * @param notes - set to what the line holds beyond its tokens, when given
+     */
+    constructor(
+        private readonly line: string,
+        private readonly notes: TokenNotes | undefined,
+    ) {}
+
+    /**
+     * Read the character at `i`.
+     * @param i - its index
+     * @returns the index of the next character to read
+     */
+    step(i: number): number {
+        const c = this.line.codePointAt(i);
         if (c === 34) {
-            quoted = !quoted;
-            started = true;
-            continue;
+            this.quote(i);
+            return i + 1;
         }
-        if (!quoted && !started && c === 91) {
-            const close = line.indexOf("]", i);
-            if (close > i && line.lastIndexOf("[", close) === i) {
-                current += line.slice(i, close + 1);
-                started = true;
-                i = close;
-                continue;
-            }
+        const close = !this.quoted && !this.started && c === 91 ? this.intervalEnd(i) : -1;
+        if (close > 0) {
+            this.current += this.line.slice(i, close + 1);
+            this.started = true;
+            return close + 1;
         }
-        if (!quoted && (c === 32 || c === 9 || c === 13 || c === 12 || c === 11)) {
-            if (started) {
-                tokens.push(current);
-                current = "";
-                started = false;
-            }
-            continue;
+        if (!this.quoted && isBlank(c)) {
+            this.endToken();
+            return i + 1;
         }
-        current += line[i];
-        started = true;
+        this.current += this.line[i];
+        this.started = true;
+        return i + 1;
     }
-    if (quoted) {
-        return null;
+
+    /**
+     * The tokens of the line.
+     * @returns them, or null when a quote is not closed
+     */
+    finish(): string[] | null {
+        if (this.quoted) {
+            return null;
+        }
+        this.endToken();
+        return this.tokens;
+    }
+
+    /**
+     * Open or close a quote. One that opens inside a token, or closes with more of the token after
+     * it, is noted.
+     * @param i - the quote's index
+     */
+    private quote(i: number): void {
+        const next = this.line.codePointAt(i + 1);
+        const joined = this.quoted ? i + 1 < this.line.length && !isBlank(next) : this.started;
+        if (joined && this.notes !== undefined) {
+            this.notes.oddQuote = true;
+        }
+        this.quoted = !this.quoted;
+        this.started = true;
+    }
+
+    /**
+     * Where a `[` that starts a token is closed, when no other `[` comes first.
+     * @param i - the index of the `[`
+     * @returns the index of its `]`, or -1
+     */
+    private intervalEnd(i: number): number {
+        const close = this.line.indexOf("]", i);
+        return close > i && this.line.lastIndexOf("[", close) === i ? close : -1;
     }
-    if (started) {
-        tokens.push(current);
+
+    /** End the token being read, if any. */
+    private endToken(): void {
+        if (this.started) {
+            this.tokens.push(this.current);
+            this.current = "";
+            this.started = false;
+        }
     }
-    return tokens;
 }
 
+/**
+ * Whether a character code is the whitespace that separates tokens.
+ * @param c - the char code
+ * @returns true for space, tab, CR, form feed or vertical tab
+ */
+function isBlank(c: number | undefined): boolean {
+    return c === 32 || c === 9 || c === 13 || c === 12 || c === 11;
+}
+
+/**
+ * Whether an unsupported section keyword is a project-file object (`*Permutation`, `*Cluster`,
+ * `*Hierarchy`), whose next line is its own `*Vertices N`, never the network's.
+ * @param keyword - the keyword as written
+ * @returns true for a project object
+ * @category Plugin helpers
+ */
+export function isProjectObject(keyword: string): boolean {
+    return PROJECT_OBJECTS.has(keyword.toLowerCase());
+}
+
+const PROJECT_OBJECTS: ReadonlySet<string> = new Set(["permutation", "cluster", "hierarchy"]);
+
 /**
  * Whether a line is a Pajek comment (`%` first) or blank.
  * @param line - the line
  * @returns true when the importer skips it
+ * @category Plugin helpers
  */
 export function isCommentOrBlank(line: string): boolean {
     for (let i = 0; i < line.length; i++) {
@@ -184,6 +313,7 @@ export function isCommentOrBlank(line: string): boolean {
  * Whether a line starts a section (`*` first, after optional whitespace).
  * @param line - the line
  * @returns true for a header line
+ * @category Plugin helpers
  */
 export function isSectionLine(line: string): boolean {
     for (let i = 0; i < line.length; i++) {
@@ -202,6 +332,7 @@ export function isSectionLine(line: string): boolean {
  * lands in `extra` so the importer can report it instead of dropping it.
  * @param line - a line isSectionLine() accepted
  * @returns the header, or null when the line has no keyword or a quote is unbalanced
+ * @category Plugin helpers
  */
 export function parseSectionHeader(line: string): SectionHeader | null {
     const tokens = tokenize(line.trimStart().slice(1));
@@ -267,6 +398,7 @@ export function parseSectionHeader(line: string): SectionHeader | null {
  * Whether a token is a Pajek integer (a vertex number, a count), without sign.
  * @param token - the token
  * @returns true for one or more ASCII digits
+ * @category Plugin helpers
  */
 export function isVertexNumber(token: string): boolean {
     if (token.length === 0) {
@@ -285,6 +417,7 @@ export function isVertexNumber(token: string): boolean {
  * Whether a token is a time interval list `[...]`.
  * @param token - the token
  * @returns true when it starts with `[` and ends with `]`
+ * @category Plugin helpers
  */
 export function isIntervalToken(token: string): boolean {
     return token.length >= 2 && token.startsWith("[") && token.endsWith("]");
@@ -296,6 +429,7 @@ export function isIntervalToken(token: string): boolean {
  * around the parts are ignored and an empty `[]` is no spell at all.
  * @param token - a token isIntervalToken() accepted
  * @returns the spells as [start, end] pairs (empty for `[]`)
+ * @category Plugin helpers
  */
 export function parseIntervals(token: string): [number, number][] {
     const body = token.slice(1, -1);
@@ -304,12 +438,15 @@ export function parseIntervals(token: string): [number, number][] {
     }
     const spells: [number, number][] = [];
     for (const part of body.split(",")) {
-        const match = TIME_POINT.exec(part.replace(/\s+/g, ""));
+        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 start = match[1] === "*" ? -Infinity : Number(match[1]);
-        const endText = match[2];
+        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;
@@ -318,29 +455,43 @@ export function parseIntervals(token: string): [number, number][] {
         } 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}: ${match[1]} is after ${endText ?? ""}`);
+            throw new Error(`malformed time interval ${token}: ${startText} is after ${endText ?? ""}`);
         }
         spells.push([start, end]);
     }
     return spells;
 }
 
-const CHARACTER_REFERENCE = /&#(?:[xX]([0-9a-fA-F]{1,6})|([0-9]{1,7}));/g;
+// 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;
 
 /**
  * Decode the `&#dddd;` and `&#xhhhh;` character references of a label, as Pajek does; a reference
- * outside the Unicode range is left as written.
+ * outside the Unicode range is left as written and handed to `onUnknown`.
  * @param text - the label as written
+ * @param onUnknown - called with each reference left as written, when given
  * @returns the decoded label
+ * @category Plugin helpers
  */
-export function decodeCharacterReferences(text: string): string {
+export function decodeCharacterReferences(text: string, onUnknown?: (reference: string) => void): string {
     if (!text.includes("&#")) {
         return text;
     }
-    return text.replace(CHARACTER_REFERENCE, (whole, hex: string | undefined, dec: string | undefined) => {
+    return text.replaceAll(CHARACTER_REFERENCE, (whole, hex: string | undefined, dec: string | undefined) => {
         const code = hex === undefined ? Number(dec) : Number.parseInt(hex, 16);
-        return code <= 0x10ffff ? String.fromCodePoint(code) : whole;
+        if (code <= 0x10ffff) {
+            return String.fromCodePoint(code);
+        }
+        onUnknown?.(whole);
+        return whole;
     });
 }
 
@@ -349,18 +500,20 @@ export function decodeCharacterReferences(text: string): string {
  * `&#...;` run is written as `&#38;`, the inverse of decodeCharacterReferences().
  * @param text - the label text
  * @returns the text to write
+ * @category Plugin helpers
  */
 export function encodeCharacterReferences(text: string): string {
     if (!text.includes("&#")) {
         return text;
     }
-    return text.replace(CHARACTER_REFERENCE, (whole) => `&#38;${whole.slice(1)}`);
+    return text.replaceAll(CHARACTER_REFERENCE, (whole) => `&#38;${whole.slice(1)}`);
 }
 
 /**
  * Write spells as a Pajek time interval token, the inverse of parseIntervals().
  * @param spells - [start, end] pairs
  * @returns the token, e.g. `[1-5,7-*]`
+ * @category Plugin helpers
  */
 export function formatIntervals(spells: readonly (readonly [number, number])[]): string {
     const parts: string[] = [];
@@ -381,13 +534,21 @@ export function formatIntervals(spells: readonly (readonly [number, number])[]):
  * coordinate, at the third position of a line row the value) and not a shape keyword.
  * @param text - the candidate key (a column name)
  * @returns true when the importer reads it back as a key
+ * @category Plugin helpers
  */
 export function isParameterKey(text: string): boolean {
-    if (text.length === 0 || /[\s"]/.test(text) || text.startsWith("[") || text.startsWith("*")) {
+    if (
+        text.length === 0 ||
+        /[\s"]/.test(text) ||
+        text.startsWith("[") ||
+        text.startsWith("*") ||
+        text.startsWith("%")
+    ) {
         return false;
     }
     if (isShapeKeyword(text)) {
         return false;
     }
-    return !/^[+-]?(\.[0-9]|[0-9])/.test(text);
+    // a number, or a non-finite spelling, at that place reads as a coordinate or the line value
+    return !/^[+-]?(\.\d|\d)/.test(text) && !/^[+-]?(?:nan|inf|infinity)$/i.test(text);
 }

package/src/formats/xgmml/columns.ts

@@ -76,6 +76,7 @@ const DTYPES: Readonly<Record<ScalarKind, ScalarDtype>> = {
 
 /**
  * Collects the attribute values of one table, then declares and writes the columns.
+ * @category Plugin helpers
  */
 export class ColumnSet {
     private readonly domain: Domain;
@@ -326,6 +327,15 @@ export class ColumnSet {
             return jsonCell(names.size > 1 ? recordOf(att) : children.map(jsonOfAtt));
         }
         let itemKind = elementKind(att.elementType);
+        if (itemKind === null && att.elementType !== null && att.elementType.trim().length > 0) {
+            this.report.warnOnce(
+                "unsupported",
+                XGMML_ISSUE.UNKNOWN_ATTR_TYPE,
+                `list element type "${att.elementType}" of "${name}" is not a Cytoscape type; the items are read by their own types`,
+                at,
+                `${XGMML_ISSUE.UNKNOWN_ATTR_TYPE}:${this.domain}:${name}:items`,
+            );
+        }
         if (itemKind === null) {
             const kinds = new Set<ScalarKind>();
             for (const child of children) {