@graphty/graph-io 0.3.39 → 0.3.41

package/src/formats/xgmml/emit.ts

@@ -207,6 +207,16 @@ function localRef(href: string): string | null {
     return href.startsWith("#") ? href.slice(1) : null;
 }
 
+/**
+ * The id a member names: its own id, else the id its local `#id` reference names.
+ * @param id - the member's id attribute, or null
+ * @param href - the member's xlink:href, or null
+ * @returns the id, or null when neither names one
+ */
+function memberRef(id: string | null, href: string | null): string | null {
+    return id ?? (href === null ? null : localRef(href));
+}
+
 /**
  * The nodes and edges a graph holds: its direct members, references resolved.
  * @param doc - the document
@@ -227,19 +237,7 @@ export function membersOf(
     const edges: EdgeRec[] = [];
     let dangling = 0;
     for (const member of graph.members) {
-        if (member.href === null) {
-            if (member.kind === "node") {
-                nodes.push(member);
-            } else {
-                edges.push(member);
-            }
-            continue;
-        }
-        const id = localRef(member.href);
-        let target: NodeRec | EdgeRec | undefined;
-        if (id !== null) {
-            target = member.kind === "node" ? nodeById.get(id) : edgeById.get(id);
-        }
+        const target = resolveMember(member, nodeById, edgeById);
         if (target === undefined) {
             dangling++;
         } else if (target.kind === "node") {
@@ -251,6 +249,29 @@ export function membersOf(
     return { nodes, edges, dangling };
 }
 
+/**
+ * The record a graph member stands for: itself when declared in place, else the node or edge its
+ * local `#id` reference names.
+ * @param member - the member
+ * @param nodeById - the first node declaration of each id
+ * @param edgeById - the first edge declaration of each id
+ * @returns the record, or undefined for a cross-file, malformed or dangling reference
+ */
+function resolveMember(
+    member: NodeRec | EdgeRec,
+    nodeById: ReadonlyMap<string, NodeRec>,
+    edgeById: ReadonlyMap<string, EdgeRec>,
+): NodeRec | EdgeRec | undefined {
+    if (member.href === null) {
+        return member;
+    }
+    const id = localRef(member.href);
+    if (id === null) {
+        return undefined;
+    }
+    return member.kind === "node" ? nodeById.get(id) : edgeById.get(id);
+}
+
 /**
  * The first declaration of each id.
  * @param records - node or edge records
@@ -266,6 +287,42 @@ function indexById<T extends NodeRec | EdgeRec>(records: readonly T[]): Map<stri
     return out;
 }
 
+/**
+ * Whether an edge repeats one already seen, remembering it otherwise: a repeat has the same id,
+ * or without one the same label and endpoints.
+ * @param seen - the keys seen so far, or null when repeats are kept
+ * @param record - the edge
+ * @returns true for a repeat
+ */
+function isRepeat(seen: Set<string> | null, record: EdgeRec): boolean {
+    if (seen === null) {
+        return false;
+    }
+    const key =
+        record.id ?? (record.label === null ? null : JSON.stringify([record.label, record.source, record.target]));
+    if (key === null) {
+        return false;
+    }
+    if (seen.has(key)) {
+        return true;
+    }
+    seen.add(key);
+    return false;
+}
+
+/**
+ * Whether a graph's att is one of its values: not RDF metadata, not the unnamed holder of a
+ * nested graph.
+ * @param att - the att
+ * @returns true to write it to the graph table
+ */
+function isGraphValueAtt(att: AttRec): boolean {
+    if (att.name !== null && META_ATTS.has(att.name)) {
+        return false;
+    }
+    return !(att.hasGraph && att.name === null);
+}
+
 /** Per-node state while emitting. */
 interface NodeRow {
     readonly id: string;
@@ -584,12 +641,16 @@ export class XgmmlEmitter {
         }
         const lower = t.toLowerCase();
         const readable = lower === "true" || lower === "yes" || lower === "false" || lower === "no";
+        let readAs: string;
+        if (readable) {
+            readAs = lower === "true" || lower === "yes" ? "1" : "0";
+        } else {
+            readAs = fallback ? "directed" : "undirected";
+        }
         this.report.warnOnce(
             "validation-error",
             XGMML_ISSUE.BAD_DIRECTED,
-            readable
-                ? `${this.prefix()}directed="${text}" is not 0 or 1; read as ${lower === "true" || lower === "yes" ? "1" : "0"}`
-                : `${this.prefix()}directed="${text}" is not 0 or 1; read as ${fallback ? "directed" : "undirected"}`,
+            `${this.prefix()}directed="${text}" is not 0 or 1; read as ${readAs}`,
             where,
             `${XGMML_ISSUE.BAD_DIRECTED}:${text}`,
         );
@@ -717,16 +778,7 @@ export class XgmmlEmitter {
             if (graph.owner !== null && isGroup(graph.owner)) {
                 continue;
             }
-            for (const member of graph.members) {
-                if (member.href === null) {
-                    continue;
-                }
-                const id = localRef(member.href);
-                const known = id !== null && (member.kind === "node" ? this.rows.has(id) : edgeIds.has(id));
-                if (!known) {
-                    dangling++;
-                }
-            }
+            dangling += this.danglingReferences(graph, edgeIds);
         }
         if (dangling > 0) {
             this.report.warning(
@@ -737,6 +789,27 @@ export class XgmmlEmitter {
         }
     }
 
+    /**
+     * How many `xlink:href` members of a graph name no node or edge of the document.
+     * @param graph - the graph
+     * @param edgeIds - the id of every edge
+     * @returns the count
+     */
+    private danglingReferences(graph: GraphRec, edgeIds: ReadonlySet<string | null>): number {
+        let dangling = 0;
+        for (const member of graph.members) {
+            if (member.href === null) {
+                continue;
+            }
+            const id = localRef(member.href);
+            const known = id !== null && (member.kind === "node" ? this.rows.has(id) : edgeIds.has(id));
+            if (!known) {
+                dangling++;
+            }
+        }
+        return dangling;
+    }
+
     /**
      * Write the per-node values: label, attributes, XML attributes, graphics, positions, nested
      * network pointers and subgraph memberships.
@@ -887,17 +960,17 @@ export class XgmmlEmitter {
         });
     }
 
-    /** The `xgmml.networks` membership of nodes in root-level subgraphs of a generic document. */
-    private writeNetworks(): void {
-        const { subgraphs } = this.doc.root;
-        if (subgraphs.length === 0) {
-            return;
-        }
+    /**
+     * The names of the subgraphs each node row is a member of.
+     * @param subgraphs - the root-level subgraphs
+     * @returns the subgraph names by node row index
+     */
+    private networkMembership(subgraphs: readonly GraphRec[]): Map<number, string[]> {
         const member = new Map<number, string[]>();
         for (const graph of subgraphs) {
             const name = graph.id ?? graph.label ?? "";
             for (const m of graph.members) {
-                const id = m.kind === "node" ? (m.id ?? (m.href === null ? null : localRef(m.href))) : null;
+                const id = m.kind === "node" ? memberRef(m.id, m.href) : null;
                 const row = id === null ? undefined : this.rows.get(id);
                 if (row !== undefined && row.index >= 0) {
                     const list = member.get(row.index) ?? [];
@@ -906,6 +979,16 @@ export class XgmmlEmitter {
                 }
             }
         }
+        return member;
+    }
+
+    /** The `xgmml.networks` membership of nodes in root-level subgraphs of a generic document. */
+    private writeNetworks(): void {
+        const { subgraphs } = this.doc.root;
+        if (subgraphs.length === 0) {
+            return;
+        }
+        const member = this.networkMembership(subgraphs);
         if (member.size === 0) {
             return;
         }
@@ -942,17 +1025,10 @@ export class XgmmlEmitter {
         this.decideNameLabel("edge", records);
         for (const record of records) {
             const where = { line: record.line, element: record.id ?? record.label };
-            // a repeat has the same id, or without one the same label and endpoints
-            const key =
-                record.id ??
-                (record.label === null ? null : JSON.stringify([record.label, record.source, record.target]));
-            if (dedupe !== null && key !== null) {
-                if (dedupe.has(key)) {
-                    repeats++;
-                    firstRepeat ??= where;
-                    continue;
-                }
-                dedupe.add(key);
+            if (isRepeat(dedupe, record)) {
+                repeats++;
+                firstRepeat ??= where;
+                continue;
             }
             const index = this.addEdge(record, header, ids, where);
             this.checkAbort();
@@ -1220,13 +1296,9 @@ export class XgmmlEmitter {
             }
         }
         for (const att of g.atts) {
-            if (att.name !== null && META_ATTS.has(att.name)) {
-                continue;
-            }
-            if (att.hasGraph && att.name === null) {
-                continue;
+            if (isGraphValueAtt(att)) {
+                this.graphColumns.addAtt(0, att, where);
             }
-            this.graphColumns.addAtt(0, att, where);
         }
         this.graphColumns.write(this.sink, () => 0);
         const json: Record<string, unknown> = { ...this.extras.graphJson };

package/src/formats/xgmml/exporter.ts

@@ -394,6 +394,17 @@ function slotOf(column: Column, domain: "graph" | "node" | "edge", hasLabelRole:
     if (domain !== "node") {
         return "att";
     }
+    return nodeSlotOf(column);
+}
+
+/**
+ * Where a node column goes when it is no XML attribute, label or graphics: one of the node-only
+ * slots, else a typed att.
+ * @param column - the column
+ * @returns the slot
+ */
+function nodeSlotOf(column: Column): ColumnWrite["kind"] {
+    const { meta } = column;
     if (meta.name === Z_COLUMN && meta.dtype === "f64" && meta.role === null) {
         return "z";
     }
@@ -761,6 +772,25 @@ function countNumericIds(snapshot: GraphSnapshot): number {
     return n;
 }
 
+/**
+ * ` name="value"`, or nothing for a null value. The value is written as given, not escaped.
+ * @param name - the attribute name
+ * @param value - the attribute text, or null
+ * @returns the attribute with a leading space, or ""
+ */
+function optionalAttribute(name: string, value: string | null): string {
+    return value === null ? "" : ` ${name}="${value}"`;
+}
+
+/**
+ * ` k="v"` for each entry, each value as text and escaped for an XML attribute.
+ * @param entries - the attribute names and values
+ * @returns the attributes, each with a leading space
+ */
+function attributeList(entries: readonly (readonly [string, unknown])[]): string {
+    return entries.map(([k, v]) => ` ${k}="${escapeXmlAttribute(String(v))}"`).join("");
+}
+
 /**
  * The text of a scalar for an att value.
  * @param value - the value
@@ -846,10 +876,10 @@ function* attsOf(
             continue;
         }
         const name = `${indent}<att name="${escapeXmlAttribute(w.name)}"`;
-        const types = `${w.type === null ? "" : ` type="${w.type}"`}${w.cyType === null ? "" : ` cy:type="${w.cyType}"`}`;
+        const types = optionalAttribute("type", w.type) + optionalAttribute("cy:type", w.cyType);
         const extra = `${column.meta.extra.hidden === true ? ' cy:hidden="1"' : ""}${column.meta.extra.equation === true ? ' cy:equation="1"' : ""}`;
         if (!isSet) {
-            yield `${name}${types}${w.elementType === null ? "" : ` cy:elementType="${w.elementType}"`}${extra}/>\n`;
+            yield `${name}${types}${optionalAttribute("cy:elementType", w.elementType)}${extra}/>\n`;
             continue;
         }
         if (column.dtype === "list") {
@@ -895,7 +925,7 @@ function* graphicsOf(
     if (attrs.length === 0 && nested.length === 0) {
         return;
     }
-    const head = `${indent}<graphics${attrs.map(([k, v]) => ` ${k}="${escapeXmlAttribute(v)}"`).join("")}`;
+    const head = `${indent}<graphics${attributeList(attrs)}`;
     if (nested.length === 0) {
         yield `${head}/>\n`;
         return;
@@ -907,7 +937,7 @@ function* graphicsOf(
             for (const point of value) {
                 const entries =
                     typeof point === "object" && point !== null ? Object.entries(point as Record<string, unknown>) : [];
-                yield `${indent}        <point${entries.map(([k, v]) => ` ${k}="${escapeXmlAttribute(String(v))}"`).join("")}/>\n`;
+                yield `${indent}        <point${attributeList(entries)}/>\n`;
             }
             yield `${indent}    </Line>\n`;
         } else {
@@ -942,7 +972,7 @@ function* jsonAtt(name: string | null, value: unknown, indent: string): Generato
             entries.length <= 3 &&
             entries.every(([k]) => /^[a-z]$/.test(k))
         ) {
-            yield `${indent}<att${nameAttr}${entries.map(([k, v]) => ` ${k}="${escapeXmlAttribute(v as string)}"`).join("")}/>\n`;
+            yield `${indent}<att${nameAttr}${attributeList(entries)}/>\n`;
             return;
         }
         yield `${indent}<att${nameAttr}>\n`;
@@ -985,18 +1015,7 @@ function cellOf(column: Column | null, row: number): unknown {
  * @returns the coordinates as XML attributes
  */
 function coordsOf(plan: Plan, zColumn: Column | null, node: number): [string, string][] {
-    const out: [string, string][] = [];
-    const xyz = cellOf(plan.position, node);
-    if (xyz !== null) {
-        const [x, y, z] = Array.from(xyz as ArrayLike<number>);
-        const fmt = plan.position?.dtype === "f32" ? formatF32 : formatF64;
-        if (Number.isFinite(x) && Number.isFinite(y)) {
-            out.push(["x", fmt(x)], ["y", fmt(y === 0 ? 0 : -y)]);
-            if (zColumn === null && z !== undefined && z !== 0 && Number.isFinite(z)) {
-                out.push(["z", fmt(z)]);
-            }
-        }
-    }
+    const out = positionCoordsOf(plan, zColumn, node);
     const z = cellOf(zColumn, node);
     if (typeof z === "number") {
         out.push(["z", formatF64(z)]);
@@ -1004,6 +1023,65 @@ function coordsOf(plan: Plan, zColumn: Column | null, node: number): [string, st
     return out;
 }
 
+/**
+ * The graphics coordinates a node's position gives: x, y negated back to screen coordinates, and
+ * z when no z column carries it.
+ * @param plan - the plan
+ * @param zColumn - the z column, or null
+ * @param node - the node
+ * @returns the coordinates as XML attributes (none for an unset or non-finite position)
+ */
+function positionCoordsOf(plan: Plan, zColumn: Column | null, node: number): [string, string][] {
+    const xyz = cellOf(plan.position, node);
+    if (xyz === null) {
+        return [];
+    }
+    const [x, y, z] = Array.from(xyz as ArrayLike<number>);
+    if (!Number.isFinite(x) || !Number.isFinite(y)) {
+        return [];
+    }
+    const fmt = plan.position?.dtype === "f32" ? formatF32 : formatF64;
+    const out: [string, string][] = [
+        ["x", fmt(x)],
+        ["y", fmt(y === 0 ? 0 : -y)],
+    ];
+    if (zColumn === null && z !== undefined && z !== 0 && Number.isFinite(z)) {
+        out.push(["z", fmt(z)]);
+    }
+    return out;
+}
+
+/**
+ * The group marker and the nested `<graph>` of a group node: its own id, label and atts, and an
+ * `xlink:href` to each child.
+ * @param snapshot - the snapshot
+ * @param sub - the group's subgraph record (empty when it has none)
+ * @param children - the child node indices
+ * @param inner - the indentation inside the node
+ * @yields the group's att elements
+ * @returns nothing
+ */
+function* groupAttOf(
+    snapshot: GraphSnapshot,
+    sub: Record<string, unknown>,
+    children: ArrayLike<number> & Iterable<number>,
+    inner: string,
+): Generator<string, void, undefined> {
+    yield `${inner}<att name="__isGroup" value="1" type="boolean" cy:type="Boolean" cy:hidden="1"/>\n`;
+    const id = typeof sub.id === "string" ? ` id="${escapeXmlAttribute(sub.id)}"` : "";
+    const lbl = typeof sub.label === "string" ? ` label="${escapeXmlAttribute(sub.label)}"` : "";
+    yield `${inner}<att>\n${inner}    <graph${id}${lbl}>\n`;
+    const atts =
+        typeof sub.atts === "object" && sub.atts !== null ? Object.entries(sub.atts as Record<string, unknown>) : [];
+    for (const [key, value] of atts) {
+        yield* jsonAtt(key, value, `${inner}        `);
+    }
+    for (const child of children) {
+        yield `${inner}        <node xlink:href="#${escapeXmlAttribute(idText(snapshot.ids.idOf(child)))}"/>\n`;
+    }
+    yield `${inner}    </graph>\n${inner}</att>\n`;
+}
+
 /**
  * The XML of one node and its group graph, whose members are `xlink:href` references (every
  * node is declared at the top level, in index order).
@@ -1022,7 +1100,8 @@ function* nodeOf(
 ): Generator<string, void, undefined> {
     const labelCol = slot(plan.nodes, "label");
     const label = cellOf(labelCol, node);
-    yield `${indent}<node id="${escapeXmlAttribute(idText(snapshot.ids.idOf(node)))}"${label === null ? "" : ` label="${escapeXmlAttribute(scalarText(label))}"`}${xmlAttributesOf(plan.nodes, node)}>\n`;
+    const labelAttr = label === null ? "" : ` label="${escapeXmlAttribute(scalarText(label))}"`;
+    yield `${indent}<node id="${escapeXmlAttribute(idText(snapshot.ids.idOf(node)))}"${labelAttr}${xmlAttributesOf(plan.nodes, node)}>\n`;
     const inner = `${indent}    `;
     yield* attsOf(plan.nodes, node, node === 0, plan, inner);
     const children = plan.reachable[node] === 1 ? plan.hierarchy.childrenOf(node) : [];
@@ -1030,22 +1109,7 @@ function* nodeOf(
     const pointer = cellOf(slot(plan.nodes, "pointer"), node);
     const subgraph = cellOf(slot(plan.nodes, "subgraph"), node);
     if (children.length > 0 || subgraph !== null) {
-        const sub = (subgraph ?? {}) as Record<string, unknown>;
-        yield `${inner}<att name="__isGroup" value="1" type="boolean" cy:type="Boolean" cy:hidden="1"/>\n`;
-        const id = typeof sub.id === "string" ? ` id="${escapeXmlAttribute(sub.id)}"` : "";
-        const lbl = typeof sub.label === "string" ? ` label="${escapeXmlAttribute(sub.label)}"` : "";
-        yield `${inner}<att>\n${inner}    <graph${id}${lbl}>\n`;
-        const atts =
-            typeof sub.atts === "object" && sub.atts !== null
-                ? Object.entries(sub.atts as Record<string, unknown>)
-                : [];
-        for (const [key, value] of atts) {
-            yield* jsonAtt(key, value, `${inner}        `);
-        }
-        for (const child of children) {
-            yield `${inner}        <node xlink:href="#${escapeXmlAttribute(idText(snapshot.ids.idOf(child)))}"/>\n`;
-        }
-        yield `${inner}    </graph>\n${inner}</att>\n`;
+        yield* groupAttOf(snapshot, (subgraph ?? {}) as Record<string, unknown>, children, inner);
     } else if (typeof nested === "string") {
         yield `${inner}<att>\n${inner}    <graph label="${escapeXmlAttribute(nested)}"/>\n${inner}</att>\n`;
     } else if (typeof pointer === "string") {
@@ -1171,7 +1235,11 @@ function* edgesOf(snapshot: GraphSnapshot, plan: Plan): Generator<string, void,
         const id = cellOf(plan.edgeId, e);
         const label = cellOf(labelCol, e);
         const weight = weights.text(e);
-        yield `    <edge${id === null ? "" : ` id="${escapeXmlAttribute(scalarText(id))}"`}${label === null ? "" : ` label="${escapeXmlAttribute(scalarText(label))}"`} source="${escapeXmlAttribute(idText(snapshot.ids.idOf(u)))}" target="${escapeXmlAttribute(idText(snapshot.ids.idOf(v)))}" cy:directed="${directed ? "1" : "0"}"${weight === null ? "" : ` weight="${weight}"`}${xmlAttributesOf(plan.edges, e)}>\n`;
+        const idAttr = id === null ? "" : ` id="${escapeXmlAttribute(scalarText(id))}"`;
+        const labelAttr = label === null ? "" : ` label="${escapeXmlAttribute(scalarText(label))}"`;
+        const source = escapeXmlAttribute(idText(snapshot.ids.idOf(u)));
+        const target = escapeXmlAttribute(idText(snapshot.ids.idOf(v)));
+        yield `    <edge${idAttr}${labelAttr} source="${source}" target="${target}" cy:directed="${directed ? "1" : "0"}"${optionalAttribute("weight", weight)}${xmlAttributesOf(plan.edges, e)}>\n`;
         yield* attsOf(plan.edges, e, first, plan, "        ");
         yield* graphicsOf(cellOf(graphicsCol, e) as Record<string, unknown> | null, [], "        ");
         yield "    </edge>\n";

package/src/formats/xgmml/importer.ts

@@ -174,23 +174,7 @@ export async function parseXgmml(
     common: ResolvedImportOptions,
     options: XgmmlImportOptions | undefined,
 ): Promise<XgmmlDocument> {
-    const repairs: XmlRepairs = {
-        bareAmpersand: booleanOption("repairBareAmpersands", options?.repairBareAmpersands, false)
-            ? (line): void => {
-                  report.warning("parse-error", XGMML_ISSUE.AMPERSAND_REPAIRED, "a bare & was read as &amp;", { line });
-              }
-            : undefined,
-        surrogatePair: booleanOption("pairSurrogateReferences", options?.pairSurrogateReferences, false)
-            ? (line): void => {
-                  report.warning(
-                      "parse-error",
-                      XGMML_ISSUE.SURROGATE_PAIRED,
-                      "two surrogate character references were joined into one character",
-                      { line },
-                  );
-              }
-            : undefined,
-    };
+    const repairs = repairsOf(options, report);
     const parser = new XgmmlParser(report);
     const seen = { content: false };
     try {
@@ -200,12 +184,7 @@ export async function parseXgmml(
             repairs,
         );
     } catch (err) {
-        if (err instanceof XmlSyntaxError) {
-            if (!seen.content) {
-                report.fail(XGMML_ISSUE.EMPTY_INPUT, "the input is empty");
-            }
-            report.fail(XGMML_ISSUE.XML_SYNTAX, err.message, { line: err.line });
-        }
+        failOnSyntax(err, seen.content, report);
         throw err;
     }
     const doc = parser.document();
@@ -220,6 +199,49 @@ export async function parseXgmml(
     return doc;
 }
 
+/**
+ * The XML repairs the options switch on, each reporting where it repaired.
+ * @param options - the XGMML options
+ * @param report - the report
+ * @returns the repairs
+ */
+function repairsOf(options: XgmmlImportOptions | undefined, report: ImportReportBuilder): XmlRepairs {
+    return {
+        bareAmpersand: booleanOption("repairBareAmpersands", options?.repairBareAmpersands, false)
+            ? (line): void => {
+                  report.warning("parse-error", XGMML_ISSUE.AMPERSAND_REPAIRED, "a bare & was read as &amp;", { line });
+              }
+            : undefined,
+        surrogatePair: booleanOption("pairSurrogateReferences", options?.pairSurrogateReferences, false)
+            ? (line): void => {
+                  report.warning(
+                      "parse-error",
+                      XGMML_ISSUE.SURROGATE_PAIRED,
+                      "two surrogate character references were joined into one character",
+                      { line },
+                  );
+              }
+            : undefined,
+    };
+}
+
+/**
+ * Fail the report on an XML syntax error: an input with no content is empty, any other is
+ * malformed. Any other error is left to the caller.
+ * @param err - the error the tokenizer threw
+ * @param content - whether non-whitespace text was seen
+ * @param report - the report
+ */
+function failOnSyntax(err: unknown, content: boolean, report: ImportReportBuilder): void {
+    if (!(err instanceof XmlSyntaxError)) {
+        return;
+    }
+    if (!content) {
+        report.fail(XGMML_ISSUE.EMPTY_INPUT, "the input is empty");
+    }
+    report.fail(XGMML_ISSUE.XML_SYNTAX, err.message, { line: err.line });
+}
+
 /**
  * Pass text chunks through while noting non-whitespace content.
  * @param chunks - the chunks