@graphty/graph-io 0.3.42 → 0.3.44

package/src/formats/cys/tables.ts

@@ -12,7 +12,7 @@ import { ImportReportBuilder } from "../../common/report.js";
 import { ImportError } from "../../types.js";
 import { CsvRecordReader } from "../csv/records.js";
 import { type AttRec } from "../xgmml/document.js";
-import { CYS_ISSUE, FORMAT } from "./constants.js";
+import { CYS_ISSUE, FORMAT, STYLE_COLUMN_PREFIX } from "./constants.js";
 import { entryLabel } from "./session.js";
 
 /** The Cytoscape type names of the Java classes a CyCSV column can hold. */
@@ -52,6 +52,8 @@ export interface CyTable {
     readonly rows: ReadonlyMap<string, readonly string[]>;
     /** The line each row starts on, by key. */
     readonly lines: ReadonlyMap<string, number>;
+    /** The cells of each row that are a quoted empty field (`""`), by key; a row without one is absent. */
+    readonly quotedEmpty?: ReadonlyMap<string, ReadonlySet<number>>;
 }
 
 /** What a table read reports besides its rows. */
@@ -61,6 +63,21 @@ interface RowProblems {
     repeated: number;
 }
 
+/** One CSV record of a table: its cells, its line, and the cells written as a quoted empty string. */
+interface TableRecord {
+    readonly cells: string[];
+    readonly line: number;
+    readonly quotedEmpty?: Set<number>;
+}
+
+/** The rows of a table, by key. */
+interface TableRows {
+    readonly rows: Map<string, readonly string[]>;
+    readonly lines: Map<string, number>;
+    readonly quotedEmpty: Map<string, ReadonlySet<number>>;
+    readonly problems: RowProblems;
+}
+
 /**
  * Read one CyCSV table. A table that cannot be read at all (an unknown CyCSV version or column
  * class, a malformed header, broken CSV) is recorded as E_CYS_TABLE and skipped (null); rows with
@@ -79,76 +96,123 @@ export async function readCyTable(
     report: ImportReportBuilder,
     common: ResolvedImportOptions,
 ): Promise<CyTable | null> {
+    const records = await tableRecords(bytes, common);
+    if (typeof records === "string") {
+        return tableError(report, entry, records);
+    }
+    const header = tableHeader(records);
+    if (typeof header === "string") {
+        return tableError(report, entry, header);
+    }
+    const columns = tableColumns(records[header.at].cells, records[header.at + 1].cells);
+    if (typeof columns === "string") {
+        return tableError(report, entry, columns);
+    }
+    const { rows, lines, quotedEmpty, problems } = tableRows(records.slice(header.at + header.lines), columns.length);
+    if (problems.short + problems.long + problems.repeated > 0) {
+        report.warning(
+            "parse-error",
+            CYS_ISSUE.TABLE_ROW,
+            `${entryLabel(entry)}: ${problems.short} row${plural(problems.short)} with too few cells (the rest are unset), ${problems.long} with too many (the extra cells are ignored), ${problems.repeated} repeating a key (the first row is read)`,
+        );
+    }
+    return { path, entry, columns, rows, lines, quotedEmpty };
+}
+
+/**
+ * A table's CSV records.
+ * @param bytes - the entry's bytes
+ * @param common - cancellation
+ * @returns the records, or why the CSV is broken
+ */
+async function tableRecords(bytes: Uint8Array, common: ResolvedImportOptions): Promise<TableRecord[] | string> {
     const scratch = new ImportReportBuilder(FORMAT, 0);
     const reader = new CsvRecordReader(bytes, scratch, { delimiter: ",", encoding: "utf-8", signal: common.signal });
-    const records: { readonly cells: string[]; readonly line: number }[] = [];
+    const records: TableRecord[] = [];
     try {
         for await (const cells of reader) {
-            records.push({ cells, line: reader.line });
+            const empty = cells.flatMap((cell, i) => (cell.length === 0 && reader.quoted[i] ? [i] : []));
+            records.push({ cells, line: reader.line, quotedEmpty: empty.length === 0 ? undefined : new Set(empty) });
         }
     } catch (err) {
         if (err instanceof ImportError) {
-            return tableError(report, entry, scratch.issues.at(-1)?.message ?? err.message);
+            return scratch.issues.at(-1)?.message ?? err.message;
         }
         throw err;
     }
+    return records;
+}
+
+/**
+ * Where a table's header starts and how many lines it takes.
+ * @param records - the table's records
+ * @returns the header, or why it does not parse
+ */
+function tableHeader(records: readonly TableRecord[]): { readonly at: number; readonly lines: number } | string {
     let at = 0;
     let version = 0;
     if (records[0]?.cells[0] === "CyCSV-Version") {
         const { cells } = records[0];
         if (cells.length !== 2 || !/^\d+$/.test(cells[1].trim())) {
-            return tableError(report, entry, `the version row ${JSON.stringify(cells)} does not parse`);
+            return `the version row ${JSON.stringify(cells)} does not parse`;
         }
         version = Number(cells[1]);
         at = 1;
     }
     if (version !== 0 && version !== 1) {
-        return tableError(report, entry, `CyCSV version "${records[0].cells[1]}" is not 0 or 1`);
+        return `CyCSV version "${records[0].cells[1]}" is not 0 or 1`;
     }
     // version 1: names, types, column options, table title; version 0: names, types, table title
-    let headerLines = version === 1 ? 4 : 3;
-    if (records.length < at + headerLines - 1) {
-        return tableError(report, entry, "the table header is incomplete");
+    const lines = version === 1 ? 4 : 3;
+    if (records.length < at + lines - 1) {
+        return "the table header is incomplete";
     }
     // the reader skips blank lines, so a blank title line (another tool's) shows only as a gap
     // in the line numbers: the record after the row before the title is then the first data row
-    const beforeTitle = records[at + headerLines - 2];
-    const title = records.at(at + headerLines - 1);
-    if (
-        title === undefined ||
-        (title.line > beforeTitle.line + 1 && !beforeTitle.cells.some((c) => /[\r\n]/.test(c)))
-    ) {
-        headerLines--;
-    }
-    const names = records[at].cells;
-    const classes = records[at + 1].cells;
+    const beforeTitle = records[at + lines - 2];
+    const title = records.at(at + lines - 1);
+    const titleBlank =
+        title === undefined || (title.line > beforeTitle.line + 1 && !beforeTitle.cells.some((c) => /[\r\n]/.test(c)));
+    return { at, lines: titleBlank ? lines - 1 : lines };
+}
+
+/**
+ * A table's columns.
+ * @param names - the column names
+ * @param classes - their Java classes
+ * @returns the columns, or why they cannot be read
+ */
+function tableColumns(names: readonly string[], classes: readonly string[]): CyColumn[] | string {
     if (names.length === 0 || classes.length !== names.length) {
-        return tableError(
-            report,
-            entry,
-            `${names.length} column name${plural(names.length)} but ${classes.length} column class(es)`,
-        );
+        return `${names.length} column name${plural(names.length)} but ${classes.length} column class(es)`;
     }
     const columns: CyColumn[] = [];
     for (let i = 0; i < names.length; i++) {
         const column = columnOf(names[i], classes[i]);
         if (column === null) {
-            return tableError(
-                report,
-                entry,
-                `column "${names[i]}" has the class "${classes[i]}", which graph-io cannot read`,
-            );
+            return `column "${names[i]}" has the class "${classes[i]}", which graph-io cannot read`;
         }
         columns.push(column);
     }
+    return columns;
+}
+
+/**
+ * A table's rows by key: the first row of a repeated key is read, and rows of the wrong length are counted.
+ * @param records - the data records
+ * @param width - how many columns the table has
+ * @returns the rows
+ */
+function tableRows(records: readonly TableRecord[], width: number): TableRows {
     const rows = new Map<string, readonly string[]>();
     const lines = new Map<string, number>();
+    const quotedEmpty = new Map<string, ReadonlySet<number>>();
     const problems: RowProblems = { short: 0, long: 0, repeated: 0 };
-    for (const record of records.slice(at + headerLines)) {
+    for (const record of records) {
         const { cells } = record;
-        if (cells.length < columns.length) {
+        if (cells.length < width) {
             problems.short++;
-        } else if (cells.length > columns.length) {
+        } else if (cells.length > width) {
             problems.long++;
         }
         const key = cells[0];
@@ -156,17 +220,13 @@ export async function readCyTable(
             problems.repeated++;
             continue;
         }
-        rows.set(key, cells.slice(0, columns.length));
+        rows.set(key, cells.slice(0, width));
         lines.set(key, record.line);
+        if (record.quotedEmpty !== undefined) {
+            quotedEmpty.set(key, record.quotedEmpty);
+        }
     }
-    if (problems.short + problems.long + problems.repeated > 0) {
-        report.warning(
-            "parse-error",
-            CYS_ISSUE.TABLE_ROW,
-            `${entryLabel(entry)}: ${problems.short} row${plural(problems.short)} with too few cells (the rest are unset), ${problems.long} with too many (the extra cells are ignored), ${problems.repeated} repeating a key (the first row is read)`,
-        );
-    }
-    return { path, entry, columns, rows, lines };
+    return { rows, lines, quotedEmpty, problems };
 }
 
 /**
@@ -199,14 +259,17 @@ function tableError(report: ImportReportBuilder, entry: string, reason: string):
 
 /**
  * The att record of one cell, or null for an unset cell. CyCSV's rules: an empty cell is unset
- * except in a String column, where it is the empty string; a list cell holds its items separated
- * by newlines (Java's `split`, so trailing empty items vanish; an empty String-list cell is one
+ * except in a String column, where it is the empty string (but in a `graphty.style.` column only when quoted,
+ * `""`: graphty writes an element without a style value as an unquoted empty cell); a list cell holds its items separated
+ * by line breaks (`\n`, or `\r` as some Cytoscape versions write them; Java's `split`, so trailing empty items
+ * vanish; an empty String-list cell is one
  * empty item, any other empty list cell unset); a cell starting with `=` is an equation.
  * @param column - the column
  * @param text - the cell text
  * @param line - the row's line
  * @param namespace - the table namespace the column belongs to (null for the network's own table)
  * @param hidden - whether the column is hidden (HIDDEN and app tables)
+ * @param quoted - whether the cell was quoted
  * @returns the att, or null
  * @category Plugin helpers
  */
@@ -216,13 +279,18 @@ export function cellAtt(
     line: number,
     namespace: string | null,
     hidden: boolean,
+    quoted = false,
 ): AttRec | null {
     const cell = { line, namespace, hidden };
     if (text.startsWith("=")) {
         return att(column.name, column.list ? "List" : column.type, null, text, true, cell);
     }
     if (!column.list) {
-        if (text.length === 0 && column.type !== "String") {
+        // graphty writes an unset style value as an unquoted empty cell, and the empty string quoted (`""`)
+        if (
+            text.length === 0 &&
+            (column.type !== "String" || (!quoted && column.name.startsWith(STYLE_COLUMN_PREFIX)))
+        ) {
             return null;
         }
         return att(column.name, column.type, null, text, false, cell);
@@ -241,16 +309,17 @@ export function cellAtt(
 }
 
 /**
- * Java's `String.split("\n")`: trailing empty strings are removed, and a text without a newline
- * is itself (so `""` is one empty item).
+ * Java's `String.split("\n")`, with `\r` and `\r\n` read as line breaks too (Cytoscape has written list cells
+ * with each): trailing empty strings are removed, and a text without a line break is itself (so `""` is one empty
+ * item).
  * @param text - the cell
  * @returns the items
  */
 function javaSplitLines(text: string): string[] {
-    if (!text.includes("\n")) {
+    if (!text.includes("\n") && !text.includes("\r")) {
         return [text];
     }
-    const items = text.split("\n");
+    const items = text.split(/\r\n|\r|\n/);
     while (items.at(-1)?.length === 0) {
         items.pop();
     }