@graphty/graph-io 0.3.19 → 0.3.21

package/dist/src/formats/xgmml/document.js

@@ -0,0 +1,695 @@
+/**
+ * The XGMML document model: one pass of the shared XML tokenizer turns an XGMML document into
+ * plain records (graphs, nodes, edges, atts, graphics) that keep everything the file says, with
+ * forward references (`xlink:href`, an edge before its nodes) left as ids. The importer
+ * (importer.ts) resolves the records into a sink once the outermost `</graph>` has closed, as
+ * Cytoscape does, and the `.cys` importer reuses the same records for the network and view files
+ * of a session.
+ *
+ * It recognises the five shapes of `research-xgmml.md` section 2: the 1.0 draft, the Cytoscape
+ * 2.x export and session, the 3.x export, the 3.x session network file (root `cy:registered="0"`)
+ * and the 3.x session view file (root `cy:view="1"`).
+ */
+import { escapeXmlAttribute, escapeXmlText } from "../../common/escape.js";
+import { isWhitespace, localName } from "../../common/xml.js";
+import { XGMML_ISSUE, XGMML_NAMESPACE } from "./constants.js";
+/** The XML attributes the parser reads on `<node>`. */
+const NODE_READ = new Set(["id", "label", "name", "xlink:href", "cy:nodeId"]);
+/** The XML attributes the parser reads on `<edge>`. */
+const EDGE_READ = new Set([
+    "id",
+    "label",
+    "name",
+    "source",
+    "target",
+    "weight",
+    "cy:directed",
+    "xlink:href",
+    "cy:edgeId",
+]);
+/** The XML attributes an `<att>` uses as its own; any other is kept in `extra`. */
+const ATT_READ = new Set([
+    "name",
+    "label",
+    "type",
+    "value",
+    "cy:type",
+    "cy:elementType",
+    "cy:hidden",
+    "cy:equation",
+    "cy:editable",
+]);
+/** Cytoscape's spellings of true (`1`, `true`, `yes`, any case). */
+const TRUE_TEXT = /^(1|true|yes)$/i;
+/**
+ * Whether a Cytoscape flag text is true.
+ * @param text - the text, or undefined
+ * @returns true for 1, true or yes in any case
+ */
+export function isCyTrue(text) {
+    return text !== null && text !== undefined && TRUE_TEXT.test(text.trim());
+}
+/**
+ * The name an XML attribute is known by, its `xlink` prefix normalised whatever prefix the file
+ * binds XLink to (galFiltered.xgmml uses `ns1`).
+ * @param name - the attribute name as written
+ * @param xlinkPrefixes - the prefixes bound to the XLink namespace
+ * @returns the name with `xlink:` for XLink attributes
+ */
+function normaliseName(name, xlinkPrefixes) {
+    const colon = name.indexOf(":");
+    if (colon > 0 && xlinkPrefixes.has(name.slice(0, colon))) {
+        return `xlink:${name.slice(colon + 1)}`;
+    }
+    return name;
+}
+/**
+ * The tokenizer handler that builds an XgmmlDocument.
+ */
+export class XgmmlParser {
+    /**
+     * Create a parser.
+     * @param report - the report issues are recorded in
+     */
+    constructor(report) {
+        this.frames = [];
+        this.xlinkPrefixes = new Set(["xlink"]);
+        this.rootGraph = null;
+        this.nodes = [];
+        this.edges = [];
+        this.graphs = [];
+        this.cytoscape = false;
+        this.xgmmlNamespace = false;
+        /** The prefix of the root element (`xgmml` in `<xgmml:graph>`), or null when it has none. */
+        this.rootPrefix = null;
+        this.rdf = {};
+        this.rdfXml = null;
+        /** The local name of the RDF element whose text is being read, or null. */
+        this.rdfElement = null;
+        this.report = report;
+    }
+    /**
+     * The parsed document.
+     * @returns the document; E_NO_GRAPH (fatal) when no root graph was read
+     */
+    document() {
+        const root = this.rootGraph;
+        if (root === null) {
+            return this.report.fail(XGMML_ISSUE.NO_GRAPH, "the document has no <graph> element");
+        }
+        return {
+            root,
+            nodes: this.nodes,
+            edges: this.edges,
+            graphs: this.graphs,
+            cytoscape: this.cytoscape,
+            xgmmlNamespace: this.xgmmlNamespace,
+            rdf: this.rdf,
+            rdfXml: this.rdfXml,
+        };
+    }
+    /**
+     * An element starts.
+     * @param rawName - the element name as written
+     * @param rawAttrs - its attributes
+     * @param line - the line
+     */
+    start(rawName, rawAttrs, line) {
+        const top = this.frames.length === 0 ? null : this.frames[this.frames.length - 1];
+        if (top === null) {
+            this.startRoot(rawName, rawAttrs, line);
+            return;
+        }
+        if (top.kind === "skip") {
+            this.frames.push(top);
+            return;
+        }
+        if (top.kind === "capture") {
+            this.capture(top, rawName, rawAttrs);
+            return;
+        }
+        const attrs = this.normalise(rawAttrs);
+        const name = localName(rawName);
+        switch (top.kind) {
+            case "graph":
+                this.startInGraph(top.graph, rawName, name, attrs, line);
+                return;
+            case "node":
+                this.startInElement(top.node, rawName, name, attrs, line);
+                return;
+            case "edge":
+                this.startInElement(top.edge, rawName, name, attrs, line);
+                return;
+            case "att":
+                this.startInAtt(top, rawName, name, attrs, line);
+                return;
+            case "graphics":
+                this.startInGraphics(top.target, rawName, name, attrs, line);
+                return;
+            case "line":
+                if (name === "point") {
+                    top.points.push(Object.fromEntries(attrs));
+                    this.frames.push({ kind: "skip" });
+                    return;
+                }
+                this.unknownElement(rawName, line);
+                return;
+            default: {
+                const kind = top;
+                throw new Error(`unknown XGMML frame ${String(kind)}`);
+            }
+        }
+    }
+    /**
+     * An element ends.
+     * @param name - the element name
+     * @param _line - the line
+     */
+    end(name, _line) {
+        const frame = this.frames.pop();
+        const below = this.frames.length === 0 ? null : this.frames[this.frames.length - 1];
+        switch (frame?.kind) {
+            case "capture":
+                frame.att.xml = `${frame.att.xml ?? ""}</${name}>`;
+                frame.depth--;
+                if (frame.depth > 0) {
+                    this.frames.push(frame);
+                }
+                else if (frame.att.name === "networkMetadata") {
+                    this.rdfXml = frame.att.xml;
+                }
+                this.rdfElement = null;
+                return;
+            case "att":
+                if (below?.kind === "graphics") {
+                    this.graphicsAtt(below.target, frame.att);
+                }
+                return;
+            case "line":
+                if (below?.kind === "graphics") {
+                    below.target.graphics = { ...(below.target.graphics ?? {}), Line: frame.points };
+                }
+                return;
+            default:
+        }
+    }
+    /**
+     * Character data.
+     * @param text - the text
+     * @param line - the line
+     */
+    text(text, line) {
+        const top = this.frames.length === 0 ? null : this.frames[this.frames.length - 1];
+        if (top === null || top.kind === "skip") {
+            return;
+        }
+        if (top.kind === "capture") {
+            top.att.xml = `${top.att.xml ?? ""}${escapeXmlText(text)}`;
+            this.captureRdfText(text);
+            return;
+        }
+        if (isWhitespace(text)) {
+            return;
+        }
+        if (top.kind === "att") {
+            top.att.text += text;
+        }
+        this.report.warnOnce("validation-error", XGMML_ISSUE.STRAY_TEXT, top.kind === "att"
+            ? "text inside <att> is ignored; an XGMML value is the value attribute"
+            : "text where XGMML allows only elements was ignored", { line });
+    }
+    // ------------------------------------------------------------------ structure
+    /**
+     * The XML attribute map with every XLink prefix written `xlink:`.
+     * @param attrs - the attributes as written
+     * @returns the normalised map
+     */
+    normalise(attrs) {
+        const out = new Map();
+        for (const [key, value] of attrs) {
+            out.set(normaliseName(key, this.xlinkPrefixes), value);
+        }
+        return out;
+    }
+    /**
+     * The root element: a `<graph>`, else the document is not XGMML.
+     * @param rawName - the name as written
+     * @param rawAttrs - its attributes
+     * @param line - the line
+     */
+    startRoot(rawName, rawAttrs, line) {
+        const local = localName(rawName);
+        const prefix = rawName.includes(":") ? rawName.slice(0, rawName.indexOf(":")) : null;
+        for (const [key, value] of rawAttrs) {
+            if (key.startsWith("xmlns:") && value === "http://www.w3.org/1999/xlink") {
+                this.xlinkPrefixes.add(key.slice(6));
+            }
+            if (key === "xmlns:cy" || key.startsWith("cy:")) {
+                this.cytoscape = true;
+            }
+        }
+        this.rootPrefix = prefix;
+        const nsKey = prefix === null ? "xmlns" : `xmlns:${prefix}`;
+        this.xgmmlNamespace = rawAttrs.get(nsKey) === XGMML_NAMESPACE;
+        if (local !== "graph") {
+            this.report.fail(XGMML_ISSUE.NO_GRAPH, `the root element is <${rawName}>, not <graph>; an XGMML graph embedded in another document is not read`, { line });
+        }
+        const graph = this.newGraph(this.normalise(rawAttrs), line, null, null);
+        this.rootGraph = graph;
+        this.frames.push({ kind: "graph", graph });
+    }
+    /**
+     * A graph record, registered in the document.
+     * @param attrs - its attributes
+     * @param line - the line
+     * @param owner - the node whose att holds it, or null
+     * @param parent - the graph it is nested in, or null
+     * @returns the record
+     */
+    newGraph(attrs, line, owner, parent) {
+        const graph = {
+            id: attrs.get("id") ?? null,
+            label: attrs.get("label") ?? null,
+            href: attrs.get("xlink:href") ?? null,
+            registered: attrs.get("cy:registered") ?? null,
+            attrs,
+            atts: [],
+            graphics: null,
+            owner,
+            parent,
+            members: [],
+            subgraphs: [],
+            line,
+        };
+        if (!this.cytoscape) {
+            for (const key of attrs.keys()) {
+                if (key.startsWith("cy:")) {
+                    this.cytoscape = true;
+                }
+            }
+        }
+        this.graphs.push(graph);
+        return graph;
+    }
+    /**
+     * A child of `<graph>`.
+     * @param graph - the graph
+     * @param rawName - the name as written
+     * @param name - its local name
+     * @param attrs - its attributes
+     * @param line - the line
+     */
+    startInGraph(graph, rawName, name, attrs, line) {
+        switch (name) {
+            case "node":
+                this.beginNode(graph, attrs, line);
+                return;
+            case "edge":
+                this.beginEdge(graph, attrs, line);
+                return;
+            case "att": {
+                const att = this.newAtt(attrs, line);
+                graph.atts.push(att);
+                this.beginAtt(att, attrs, "graph");
+                return;
+            }
+            case "graphics":
+                this.beginGraphics(graph, attrs);
+                return;
+            default:
+                this.unknownElement(rawName, line);
+        }
+    }
+    /**
+     * A child of `<node>` or `<edge>`.
+     * @param element - the node or edge
+     * @param rawName - the name as written
+     * @param name - its local name
+     * @param attrs - its attributes
+     * @param line - the line
+     */
+    startInElement(element, rawName, name, attrs, line) {
+        switch (name) {
+            case "att": {
+                const att = this.newAtt(attrs, line);
+                element.atts.push(att);
+                this.beginAtt(att, attrs, element.kind);
+                return;
+            }
+            case "graphics":
+                this.beginGraphics(element, attrs);
+                return;
+            default:
+                this.unknownElement(rawName, line);
+        }
+    }
+    /**
+     * A child of `<att>`: a child att, a nested graph, or foreign XML.
+     * @param frame - the att frame
+     * @param rawName - the name as written
+     * @param name - its local name
+     * @param attrs - its attributes
+     * @param line - the line
+     */
+    startInAtt(frame, rawName, name, attrs, line) {
+        const { att } = frame;
+        const xgmml = this.isXgmmlName(rawName);
+        if (name === "att" && xgmml) {
+            const child = this.newAtt(attrs, line);
+            att.children.push(child);
+            this.beginAtt(child, attrs, frame.owner === "graphics" ? "graphics" : "att");
+            return;
+        }
+        if (name === "graph" && xgmml) {
+            att.hasGraph = true;
+            this.beginNestedGraph(frame, attrs, line);
+            return;
+        }
+        // a second foreign element of the same att is appended to the first
+        att.xml ?? (att.xml = "");
+        const capture = { kind: "capture", att, depth: 0 };
+        this.frames.push(capture);
+        this.capture(capture, rawName, attrs);
+    }
+    /**
+     * Whether an element name inside an att is XGMML's own (unprefixed, or with the root's prefix,
+     * as in a document whose root is `<xgmml:graph>`) rather than foreign XML such as `rdf:RDF`.
+     * @param rawName - the name as written
+     * @returns true for an XGMML element name
+     */
+    isXgmmlName(rawName) {
+        const colon = rawName.indexOf(":");
+        return colon < 0 || (this.rootPrefix !== null && rawName.slice(0, colon) === this.rootPrefix);
+    }
+    /**
+     * A `<graph>` inside an `<att>`: a subnetwork of the root, a group or nested-network pointer
+     * of a node, or (in an edge) a graph with no model.
+     * @param frame - the att frame
+     * @param attrs - the graph's attributes
+     * @param line - the line
+     */
+    beginNestedGraph(frame, attrs, line) {
+        const holder = this.attHolder();
+        if (holder === null || holder.kind === "edge" || frame.owner === "graphics") {
+            this.report.warnOnce("unsupported", XGMML_ISSUE.EDGE_NESTED_GRAPH, "a graph nested in an edge's (or a graphics) att has no model and was skipped with its content", { line });
+            this.frames.push({ kind: "skip" });
+            return;
+        }
+        if (holder.kind === "node") {
+            const graph = this.newGraph(attrs, line, holder.node, holder.node.graph);
+            holder.node.nested.push(graph);
+            this.frames.push({ kind: "graph", graph });
+            return;
+        }
+        const graph = this.newGraph(attrs, line, null, holder.graph);
+        holder.graph.subgraphs.push(graph);
+        this.frames.push({ kind: "graph", graph });
+    }
+    /**
+     * The innermost node, edge or graph frame below the open atts.
+     * @returns the frame, or null
+     */
+    attHolder() {
+        for (let i = this.frames.length - 1; i >= 0; i--) {
+            const frame = this.frames[i];
+            if (frame.kind === "graph" || frame.kind === "node" || frame.kind === "edge") {
+                return frame;
+            }
+        }
+        return null;
+    }
+    /**
+     * Report an element XGMML does not define here and skip its subtree.
+     * @param rawName - the name as written
+     * @param line - the line
+     */
+    unknownElement(rawName, line) {
+        this.report.warnOnce("unsupported", XGMML_ISSUE.UNKNOWN_ELEMENT, `element <${rawName}> is not XGMML here and was skipped with its content`, { line, element: rawName }, `${XGMML_ISSUE.UNKNOWN_ELEMENT}:${rawName}`);
+        this.frames.push({ kind: "skip" });
+    }
+    // ------------------------------------------------------------------ nodes and edges
+    /**
+     * Open a `<node>`.
+     * @param graph - the graph it is in
+     * @param attrs - its attributes
+     * @param line - the line
+     */
+    beginNode(graph, attrs, line) {
+        const href = attrs.get("xlink:href") ?? null;
+        let id = attrs.get("id") ?? null;
+        const labelAttr = attrs.get("label") ?? null;
+        const nameAttr = attrs.get("name") ?? null;
+        const label = labelAttr ?? nameAttr;
+        if (href === null && id === null) {
+            if (label === null || label.length === 0) {
+                this.report.counts.skippedNodes++;
+                this.report.error("missing-value", XGMML_ISSUE.MISSING_ID, "<node> without an id or a label", {
+                    line,
+                });
+                this.frames.push({ kind: "skip" });
+                return;
+            }
+            this.report.warning("validation-error", XGMML_ISSUE.ID_FROM_LABEL, `<node> without an id: its label "${label}" is used as the id`, { line, element: label });
+            id = label;
+        }
+        const node = {
+            kind: "node",
+            id: href === null ? id : null,
+            href,
+            label,
+            name: labelAttr !== null ? nameAttr : null,
+            xmlAttrs: otherAttributes(attrs, NODE_READ),
+            atts: [],
+            graphics: null,
+            x: null,
+            y: null,
+            z: null,
+            nested: [],
+            graph,
+            line,
+            viewId: attrs.get("cy:nodeId") ?? null,
+        };
+        graph.members.push(node);
+        if (href === null) {
+            this.nodes.push(node);
+        }
+        this.frames.push({ kind: "node", node });
+    }
+    /**
+     * Open an `<edge>`.
+     * @param graph - the graph it is in
+     * @param attrs - its attributes
+     * @param line - the line
+     */
+    beginEdge(graph, attrs, line) {
+        const href = attrs.get("xlink:href") ?? null;
+        const edge = {
+            kind: "edge",
+            id: href === null ? (attrs.get("id") ?? null) : null,
+            href,
+            source: attrs.get("source") ?? null,
+            target: attrs.get("target") ?? null,
+            label: attrs.get("label") ?? null,
+            name: attrs.get("name") ?? null,
+            weight: attrs.get("weight") ?? null,
+            directed: attrs.get("cy:directed") ?? null,
+            xmlAttrs: otherAttributes(attrs, EDGE_READ),
+            atts: [],
+            graphics: null,
+            graph,
+            line,
+            viewId: attrs.get("cy:edgeId") ?? null,
+        };
+        graph.members.push(edge);
+        if (href === null) {
+            this.edges.push(edge);
+        }
+        this.frames.push({ kind: "edge", edge });
+    }
+    // ------------------------------------------------------------------ atts
+    /**
+     * An att record from its XML attributes.
+     * @param attrs - the attributes
+     * @param line - the line
+     * @returns the record
+     */
+    newAtt(attrs, line) {
+        const extra = {};
+        for (const [key, value] of attrs) {
+            if (!ATT_READ.has(key) && key !== "xmlns" && !key.startsWith("xmlns:")) {
+                extra[key] = value;
+            }
+        }
+        return {
+            name: attrs.get("name") ?? attrs.get("label") ?? null,
+            type: attrs.get("type") ?? null,
+            cyType: attrs.get("cy:type") ?? null,
+            elementType: attrs.get("cy:elementType") ?? null,
+            value: attrs.get("value") ?? null,
+            hidden: isCyTrue(attrs.get("cy:hidden")),
+            equation: isCyTrue(attrs.get("cy:equation")),
+            children: [],
+            extra,
+            xml: null,
+            hasGraph: false,
+            text: "",
+            line,
+        };
+    }
+    /**
+     * Open an `<att>`.
+     * @param att - the record
+     * @param _attrs - its attributes
+     * @param owner - what holds it
+     */
+    beginAtt(att, _attrs, owner) {
+        this.frames.push({ kind: "att", att, owner });
+    }
+    /**
+     * Serialize one start tag of foreign XML into the capturing att.
+     * @param frame - the capture frame
+     * @param rawName - the name as written
+     * @param attrs - its attributes
+     */
+    capture(frame, rawName, attrs) {
+        let tag = `<${rawName}`;
+        for (const [key, value] of attrs) {
+            tag += ` ${key}="${escapeXmlAttribute(value)}"`;
+        }
+        frame.att.xml = `${frame.att.xml ?? ""}${tag}>`;
+        frame.depth++;
+        if (frame.att.name === "networkMetadata") {
+            this.rdfElement = localName(rawName);
+        }
+    }
+    /**
+     * Keep the text of an RDF metadata field.
+     * @param text - the text
+     */
+    captureRdfText(text) {
+        if (this.rdfElement !== null && !isWhitespace(text)) {
+            this.rdf[this.rdfElement] = (this.rdf[this.rdfElement] ?? "") + text;
+        }
+    }
+    // ------------------------------------------------------------------ graphics
+    /**
+     * Open a `<graphics>`: x, y and z (draft and Cytoscape) are read as coordinates; every other
+     * attribute is kept as written, merged key by key with an earlier `<graphics>`.
+     * @param target - the node, edge or graph
+     * @param attrs - its attributes
+     */
+    beginGraphics(target, attrs) {
+        const graphics = { ...(target.graphics ?? {}) };
+        for (const [key, value] of attrs) {
+            if ("x" in target && (key === "x" || key === "y" || key === "z")) {
+                target[key] = value;
+            }
+            else if (key !== "xmlns" && !key.startsWith("xmlns:")) {
+                graphics[key] = value;
+            }
+        }
+        target.graphics = graphics;
+        this.frames.push({ kind: "graphics", target });
+    }
+    /**
+     * A child of `<graphics>`: a visual-property att, a `<center>` or a `<Line>`.
+     * @param target - the graphics target
+     * @param rawName - the name as written
+     * @param name - its local name
+     * @param attrs - its attributes
+     * @param line - the line
+     */
+    startInGraphics(target, rawName, name, attrs, line) {
+        switch (name) {
+            case "att": {
+                this.frames.push({ kind: "att", att: this.newAtt(attrs, line), owner: "graphics" });
+                return;
+            }
+            case "center":
+                if ("x" in target) {
+                    target.x ?? (target.x = attrs.get("x") ?? null);
+                    target.y ?? (target.y = attrs.get("y") ?? null);
+                    target.z ?? (target.z = attrs.get("z") ?? null);
+                }
+                this.frames.push({ kind: "skip" });
+                return;
+            case "Line":
+            case "line":
+                this.frames.push({ kind: "line", points: [] });
+                return;
+            default:
+                this.unknownElement(rawName, line);
+        }
+    }
+    /**
+     * Keep a visual-property att of a `<graphics>` in its record, as written. A session view's
+     * `<att name="z">` repeats z and is read as z when the attributes gave none.
+     * @param target - the graphics target
+     * @param att - the att
+     */
+    graphicsAtt(target, att) {
+        if (att.name === "z" && "z" in target && att.children.length === 0) {
+            target.z ?? (target.z = att.value);
+            return;
+        }
+        if (att.name === null) {
+            this.report.warnOnce("validation-error", XGMML_ISSUE.BAD_ATT, "a graphics <att> without a name was skipped", { line: att.line }, `${XGMML_ISSUE.BAD_ATT}:graphics-name`);
+            return;
+        }
+        target.graphics = { ...(target.graphics ?? {}), [att.name]: attJson(att) };
+    }
+}
+/**
+ * Whether an att's children are list items rather than named fields: they have no names, repeat
+ * the parent's name (Cytoscape 3 lists), or are several that share one name (2.x bend handles).
+ * @param att - the att
+ * @returns true for a list
+ */
+export function isListLike(att) {
+    const names = new Set(att.children.map((c) => c.name));
+    if (names.size !== 1) {
+        return false;
+    }
+    const [only] = names;
+    return only === null || only === att.name || att.children.length > 1;
+}
+/**
+ * A graphics att as plain data, values as written: an att with children is an array when they
+ * are list items (isListLike), else a record by name; a childless att is its value,
+ * else its other XML attributes (a 2.x bend handle's x and y), else null.
+ * @param att - the att
+ * @returns the value
+ */
+export function attJson(att) {
+    if (att.children.length === 0) {
+        if (att.value !== null) {
+            return att.value;
+        }
+        return Object.keys(att.extra).length > 0 ? { ...att.extra } : null;
+    }
+    if (isListLike(att)) {
+        return att.children.map(attJson);
+    }
+    const out = {};
+    for (const child of att.children) {
+        out[child.name ?? ""] = attJson(child);
+    }
+    return out;
+}
+/**
+ * The XML attributes of an element the parser does not read itself, without namespace
+ * declarations.
+ * @param attrs - the attributes
+ * @param read - the names the parser reads
+ * @returns the others, in document order
+ */
+function otherAttributes(attrs, read) {
+    const out = [];
+    for (const [key, value] of attrs) {
+        if (!read.has(key) && key !== "xmlns" && !key.startsWith("xmlns:")) {
+            out.push([key, value]);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=document.js.map