@graphty/graph-io 0.3.39 → 0.3.40

package/src/formats/csv/records.ts

@@ -739,125 +739,169 @@ class RecordScanner {
      * @returns the position after the last character consumed
      */
     scan(chunk: string, from: number): number {
-        const { quoteCode, delimiterCode } = this;
+        const { delimiterCode } = this;
         const n = chunk.length;
         let i = from;
         this.segment = from;
         while (i < n) {
             const c = chunk.charCodeAt(i);
-            if (this.state === COMMENT) {
-                if (c === LF || c === CR) {
-                    this.comment = this.grow(this.comment, chunk.slice(this.segment, i));
-                    this.reader.leadingComments.push(this.comment);
-                    this.reader.leadingCommentLines.push(this.line);
-                    this.comment = "";
-                    this.state = START;
-                    this.endLine(c);
-                    this.segment = i + 1;
-                }
+            const { state } = this;
+            if (state === COMMENT) {
+                this.commentChar(chunk, i, c);
                 i++;
                 continue;
             }
-            if (this.state === QUOTED) {
-                // jump to the next quote; the run in between is field text whose line breaks are counted
-                const q = chunk.indexOf(this.quoteText, i);
-                const end = q < 0 ? n : q;
-                if (end > i) {
-                    this.countLineBreaks(chunk, i, end);
-                }
-                if (q < 0) {
-                    i = n;
-                    break;
-                }
-                this.field = this.grow(this.field, chunk.slice(this.segment, q));
-                this.state = CLOSING;
-                this.lastWasCr = false;
-                i = q + 1;
+            if (state === QUOTED) {
+                i = this.quotedRun(chunk, i);
                 continue;
             }
             const isDelimiter = c === delimiterCode || (this.collapse && c === TAB);
-            if (this.state === CLOSING) {
-                if (c === quoteCode) {
-                    this.field = this.grow(this.field, this.quoteText);
-                    this.segment = i + 1;
-                    this.state = QUOTED;
-                    this.lastWasCr = false;
-                    i++;
-                    continue;
-                }
-                if (!isDelimiter && c !== LF && c !== CR) {
-                    this.reader.badQuote(this.startLine, this.count + 1);
-                }
-                this.state = AFTER_QUOTED;
-                this.segment = i;
-                // fall through to the delimiter / line-end handling below without consuming c
-            }
-            if (isDelimiter || c === LF || c === CR) {
-                if (c === LF && this.lastWasCr) {
-                    // the second half of a CRLF already ended the record
-                    this.lastWasCr = false;
-                    this.segment = i + 1;
-                    i++;
-                    continue;
-                }
-                if (this.state === UNQUOTED) {
-                    this.field = this.grow(this.field, chunk.slice(this.segment, i));
-                }
-                if (isDelimiter && this.collapse && this.state === START) {
-                    // a run of whitespace, or indentation: one separator
-                    this.lastWasCr = false;
-                    this.segment = i + 1;
-                    i++;
-                    continue;
-                }
-                if (isDelimiter) {
-                    this.push();
-                    this.state = START;
-                    this.lastWasCr = false;
-                    this.segment = i + 1;
-                    i++;
-                    continue;
-                }
-                // a line ending right after a whitespace run in the whitespace dialect ends no field
-                if (!(this.state === START && (this.count === 0 || this.collapse))) {
-                    this.push();
-                }
-                if (this.count > 0) {
-                    this.ready = true;
-                    this.recordLine = this.startLine;
-                }
-                this.state = START;
-                this.endLine(c);
-                this.segment = i + 1;
-                i++;
+            if (state === CLOSING || isDelimiter || c === LF || c === CR) {
+                i = this.boundary(chunk, i, c, isDelimiter);
                 if (this.ready) {
                     return i;
                 }
                 continue;
             }
+            this.fieldChar(c, i);
+            i++;
+        }
+        return i;
+    }
+
+    /**
+     * One character of a leading comment line: a line break ends the comment.
+     * @param chunk - the chunk
+     * @param i - the character's index
+     * @param c - the character's code
+     */
+    private commentChar(chunk: string, i: number, c: number): void {
+        if (c !== LF && c !== CR) {
+            return;
+        }
+        this.comment = this.grow(this.comment, chunk.slice(this.segment, i));
+        this.reader.leadingComments.push(this.comment);
+        this.reader.leadingCommentLines.push(this.line);
+        this.comment = "";
+        this.state = START;
+        this.endLine(c);
+        this.segment = i + 1;
+    }
+
+    /**
+     * Inside a quoted field: jump to the next quote; the run in between is field text whose line
+     * breaks are counted.
+     * @param chunk - the chunk
+     * @param i - where the run starts
+     * @returns the position after the quote, or the chunk end when there is none
+     */
+    private quotedRun(chunk: string, i: number): number {
+        const q = chunk.indexOf(this.quoteText, i);
+        const end = q < 0 ? chunk.length : q;
+        if (end > i) {
+            this.countLineBreaks(chunk, i, end);
+        }
+        if (q < 0) {
+            return chunk.length;
+        }
+        this.field = this.grow(this.field, chunk.slice(this.segment, q));
+        this.state = CLOSING;
+        this.lastWasCr = false;
+        return q + 1;
+    }
+
+    /**
+     * The character after a quote inside a quoted field, a delimiter or a line break: a doubled
+     * quote, the end of a field, or the end of a record.
+     * @param chunk - the chunk
+     * @param i - the character's index
+     * @param c - the character's code
+     * @param isDelimiter - whether it separates fields
+     * @returns the position after the character
+     */
+    private boundary(chunk: string, i: number, c: number, isDelimiter: boolean): number {
+        if (this.state === CLOSING) {
+            if (c === this.quoteCode) {
+                this.field = this.grow(this.field, this.quoteText);
+                this.segment = i + 1;
+                this.state = QUOTED;
+                this.lastWasCr = false;
+                return i + 1;
+            }
+            if (!isDelimiter && c !== LF && c !== CR) {
+                this.reader.badQuote(this.startLine, this.count + 1);
+            }
+            this.state = AFTER_QUOTED;
+            this.segment = i;
+        }
+        if (c === LF && this.lastWasCr) {
+            // the second half of a CRLF already ended the record
             this.lastWasCr = false;
-            if (this.state === START) {
-                if (this.leading && this.count === 0 && this.commentCodes.includes(c)) {
-                    this.state = COMMENT;
-                    this.segment = i;
-                    i++;
-                    continue;
-                }
-                this.leading = false;
-                if (c === quoteCode) {
-                    this.state = QUOTED;
-                    this.fieldQuoted = true;
-                    this.segment = i + 1;
-                } else {
-                    this.state = UNQUOTED;
-                    this.segment = i;
-                }
-            } else if (c === quoteCode && this.state === UNQUOTED && this.reader.strayQuoteLine === 0) {
+            this.segment = i + 1;
+            return i + 1;
+        }
+        if (this.state === UNQUOTED) {
+            this.field = this.grow(this.field, chunk.slice(this.segment, i));
+        }
+        if (isDelimiter) {
+            // in the whitespace dialect a run of whitespace, or indentation, is one separator
+            if (!(this.collapse && this.state === START)) {
+                this.push();
+                this.state = START;
+            }
+            this.lastWasCr = false;
+            this.segment = i + 1;
+            return i + 1;
+        }
+        this.lineEnd(c);
+        this.segment = i + 1;
+        return i + 1;
+    }
+
+    /**
+     * A line break that ends a record (or a blank line).
+     * @param c - the LF or CR
+     */
+    private lineEnd(c: number): void {
+        // a line ending right after a whitespace run in the whitespace dialect ends no field
+        if (!(this.state === START && (this.count === 0 || this.collapse))) {
+            this.push();
+        }
+        if (this.count > 0) {
+            this.ready = true;
+            this.recordLine = this.startLine;
+        }
+        this.state = START;
+        this.endLine(c);
+    }
+
+    /**
+     * Any other character outside a quoted field: the start of a field or a comment, or field text.
+     * @param c - the character's code
+     * @param i - its index
+     */
+    private fieldChar(c: number, i: number): void {
+        this.lastWasCr = false;
+        if (this.state !== START) {
+            if (c === this.quoteCode && this.state === UNQUOTED && this.reader.strayQuoteLine === 0) {
                 this.reader.strayQuoteLine = this.startLine;
             }
-            i++;
+            return;
+        }
+        if (this.leading && this.count === 0 && this.commentCodes.includes(c)) {
+            this.state = COMMENT;
+            this.segment = i;
+            return;
+        }
+        this.leading = false;
+        if (c === this.quoteCode) {
+            this.state = QUOTED;
+            this.fieldQuoted = true;
+            this.segment = i + 1;
+        } else {
+            this.state = UNQUOTED;
+            this.segment = i;
         }
-        return i;
     }
 
     /**

package/src/formats/cx/importer.ts

@@ -773,12 +773,13 @@ function checkNumberVerification(value: unknown, count: number, report: ImportRe
     const raw = isRecord(value) ? value.longNumber : undefined;
     const digits = raw instanceof ExactInteger ? raw.digits : String(raw);
     if (count > 1 || !NUMBER_VERIFICATION_VALUES.has(digits)) {
+        const held = raw === undefined ? null : digits;
         report.warning(
             "validation-error",
             CX_ISSUE.NUMBER_VERIFICATION,
             count > 1
                 ? "a second numberVerification element; ignored"
-                : `numberVerification holds ${shown(raw === undefined ? null : digits)}, not 281474976710655`,
+                : `numberVerification holds ${shown(held)}, not 281474976710655`,
             { line, element: "numberVerification" },
         );
     }
@@ -993,10 +994,12 @@ async function readDocument(
                         break;
                     }
                     countMember(event.block, null);
+                    const what =
+                        keys.length > 1 ? `an object with ${keys.length} keys (${keys.join(", ")})` : shown(value);
                     report.error(
                         "parse-error",
                         BAD_ASPECT_BLOCK_CODE,
-                        `a member of the document is ${keys.length > 1 ? `an object with ${keys.length} keys (${keys.join(", ")})` : shown(value)}, not a one-key aspect fragment; skipped`,
+                        `a member of the document is ${what}, not a one-key aspect fragment; skipped`,
                         { line: event.line, element: keys[0] ?? null },
                     );
                     break;
@@ -1361,6 +1364,26 @@ function memberCount(members: ReadonlySet<NodeId> | null, total: number): number
 
 // ============================================================ the build
 
+/** The cyVisualProperties of a graph's view, gathered before they are written. */
+interface VisualCollection {
+    /** per domain, per property: the [row, text] cells */
+    columns: Record<"node" | "edge", Map<string, [number, string][]>>;
+    /** the network values by property */
+    network: Map<string, string>;
+    defaults: number;
+    mappings: number;
+    dependencies: number;
+}
+
+/**
+ * A visual property value as text: a string as it is, anything else as JSON.
+ * @param raw - the value
+ * @returns its text
+ */
+function visualText(raw: unknown): string {
+    return typeof raw === "string" ? raw : JSON.stringify(raw);
+}
+
 /** One attribute column of the graph being built. */
 interface AttributeColumn {
     readonly name: string;
@@ -2849,57 +2872,99 @@ class CxReader {
      * applied.
      */
     private readVisualProperties(): void {
-        const entries = aspect(this.doc, "cyVisualProperties");
         // Cytoscape's table-cell styles: a visual property aspect graph-io keeps but does not read
         const tableStyles = TABLE_STYLE_ASPECTS.reduce((n, name) => n + (this.doc.kept.get(name)?.length ?? 0), 0);
         // the graph's own view (its first): the one its positions come from; the others stay in meta.extra.cx
         const views = new Set(this.plan.views.slice(0, 1));
-        const columns = { node: new Map<string, [number, string][]>(), edge: new Map<string, [number, string][]>() };
-        const network = new Map<string, string>();
-        let defaults = 0;
-        let mappings = 0;
-        let dependencies = 0;
-        for (const { value } of entries) {
-            if (!isRecord(value)) {
-                continue;
-            }
-            const view = value.view === undefined || value.view === null ? null : refId(value.view);
-            if (view !== null && views.size > 0 && !views.has(view)) {
-                continue;
+        const visual: VisualCollection = {
+            columns: { node: new Map(), edge: new Map() },
+            network: new Map(),
+            defaults: 0,
+            mappings: 0,
+            dependencies: 0,
+        };
+        for (const { value } of aspect(this.doc, "cyVisualProperties")) {
+            if (isRecord(value)) {
+                this.collectVisualEntry(value, views, visual);
             }
-            const properties = isRecord(value.properties) ? value.properties : {};
-            mappings += isRecord(value.mappings) ? Object.keys(value.mappings).length : 0;
-            dependencies += isRecord(value.dependencies) ? Object.keys(value.dependencies).length : 0;
-            switch (value.properties_of) {
-                case "nodes":
-                case "edges": {
-                    const domain = value.properties_of === "nodes" ? "node" : "edge";
-                    const target = refId(value.applies_to);
-                    const rows = domain === "node" ? this.nodeRows : this.edgeRows;
-                    const row = target === null ? undefined : rows.get(target);
-                    if (row === undefined) {
-                        if (target === null || !(domain === "node" ? this.rootNodes : this.rootEdges).has(target)) {
-                            this.dangle(`${domain} visual property entry`);
-                        }
-                        continue;
-                    }
-                    for (const [property, raw] of Object.entries(properties)) {
-                        const list = columns[domain].get(property) ?? [];
-                        list.push([row, typeof raw === "string" ? raw : JSON.stringify(raw)]);
-                        columns[domain].set(property, list);
-                    }
-                    break;
+        }
+        this.writeBypassColumns(visual.columns);
+        this.writeBypassNetwork(visual.network);
+        this.reportStyleRules(visual, tableStyles);
+    }
+
+    /**
+     * File one cyVisualProperties element of this graph's view into the collection: per-element and
+     * network values by property, defaults, mappings and dependencies counted.
+     * @param value - the element
+     * @param views - the views read (empty: every view)
+     * @param visual - the collection to add to
+     */
+    private collectVisualEntry(
+        value: Record<string, unknown>,
+        views: ReadonlySet<NodeId>,
+        visual: VisualCollection,
+    ): void {
+        const view = value.view === undefined || value.view === null ? null : refId(value.view);
+        if (view !== null && views.size > 0 && !views.has(view)) {
+            return;
+        }
+        const properties = isRecord(value.properties) ? value.properties : {};
+        visual.mappings += isRecord(value.mappings) ? Object.keys(value.mappings).length : 0;
+        visual.dependencies += isRecord(value.dependencies) ? Object.keys(value.dependencies).length : 0;
+        switch (value.properties_of) {
+            case "nodes":
+                this.collectElementProperties("node", value.applies_to, properties, visual.columns);
+                break;
+            case "edges":
+                this.collectElementProperties("edge", value.applies_to, properties, visual.columns);
+                break;
+            case "network":
+                for (const [property, raw] of Object.entries(properties)) {
+                    visual.network.set(property, visualText(raw));
                 }
-                case "network":
-                    for (const [property, raw] of Object.entries(properties)) {
-                        network.set(property, typeof raw === "string" ? raw : JSON.stringify(raw));
-                    }
-                    break;
-                default:
-                    defaults += Object.keys(properties).length;
-                    break;
+                break;
+            default:
+                visual.defaults += Object.keys(properties).length;
+                break;
+        }
+    }
+
+    /**
+     * File the visual values of one node or edge under its row; an element not in this graph is
+     * skipped, and reported dangling when it is in no graph of the file.
+     * @param domain - node or edge
+     * @param appliesTo - the element's applies_to
+     * @param properties - its visual properties
+     * @param columns - the per-property cells to add to
+     */
+    private collectElementProperties(
+        domain: "node" | "edge",
+        appliesTo: unknown,
+        properties: Record<string, unknown>,
+        columns: VisualCollection["columns"],
+    ): void {
+        const target = refId(appliesTo);
+        const rows = domain === "node" ? this.nodeRows : this.edgeRows;
+        const row = target === null ? undefined : rows.get(target);
+        if (row === undefined) {
+            if (target === null || !(domain === "node" ? this.rootNodes : this.rootEdges).has(target)) {
+                this.dangle(`${domain} visual property entry`);
             }
+            return;
         }
+        for (const [property, raw] of Object.entries(properties)) {
+            const list = columns[domain].get(property) ?? [];
+            list.push([row, visualText(raw)]);
+            columns[domain].set(property, list);
+        }
+    }
+
+    /**
+     * Write the collected per-element visual values as string columns in the cx.bypass namespace.
+     * @param columns - the per-property cells of each domain
+     */
+    private writeBypassColumns(columns: VisualCollection["columns"]): void {
         for (const domain of ["node", "edge"] as const) {
             for (const [property, cells] of columns[domain]) {
                 const handle = declareFresh(
@@ -2922,6 +2987,13 @@ class CxReader {
                 }
             }
         }
+    }
+
+    /**
+     * Write the network visual values as graph values in the cx.bypass namespace.
+     * @param network - the value of each property
+     */
+    private writeBypassNetwork(network: ReadonlyMap<string, string>): void {
         for (const [property, text] of network) {
             try {
                 this.sink.setGraphValue(property, text, {
@@ -2932,20 +3004,30 @@ class CxReader {
                 this.report.recordError(err, { element: property });
             }
         }
-        if (defaults + mappings + dependencies + tableStyles > 0) {
-            const parts = [
-                `cyVisualProperties: ${defaults} default${plural(defaults)}, ${mappings} mapping${plural(mappings)}, ${dependencies} dependenc(ies)`,
-            ];
-            if (tableStyles > 0) {
-                parts.push(`${tableStyles} table style element${plural(tableStyles)}`);
-            }
-            this.report.warning(
-                "unsupported",
-                STYLES_NOT_IMPORTED_CODE,
-                `the file's style rules are not applied (${parts.join("; ")}); they are kept in meta.extra.cx`,
-                { element: "cyVisualProperties" },
-            );
+    }
+
+    /**
+     * Warn that the style rules (defaults, mappings, dependencies, table styles) are kept, not applied.
+     * @param visual - the counted rules
+     * @param tableStyles - the number of table style elements
+     */
+    private reportStyleRules(visual: VisualCollection, tableStyles: number): void {
+        const { defaults, mappings, dependencies } = visual;
+        if (defaults + mappings + dependencies + tableStyles === 0) {
+            return;
         }
+        const parts = [
+            `cyVisualProperties: ${defaults} default${plural(defaults)}, ${mappings} mapping${plural(mappings)}, ${dependencies} dependenc(ies)`,
+        ];
+        if (tableStyles > 0) {
+            parts.push(`${tableStyles} table style element${plural(tableStyles)}`);
+        }
+        this.report.warning(
+            "unsupported",
+            STYLES_NOT_IMPORTED_CODE,
+            `the file's style rules are not applied (${parts.join("; ")}); they are kept in meta.extra.cx`,
+            { element: "cyVisualProperties" },
+        );
     }
 
     /**

package/src/formats/cx2/exporter.ts

@@ -304,9 +304,10 @@ function capabilityNotes(
             continue;
         }
         if (gen.code === LOSS.JSON) {
+            const what = gen.column === null ? "a column" : `column "${gen.column}"`;
             note(
                 CX2_LOSS.JSON_AS_STRING,
-                `${gen.column === null ? "a column" : `column "${gen.column}"`} holds nested values; written as a string attribute holding their JSON text`,
+                `${what} holds nested values; written as a string attribute holding their JSON text`,
                 gen.column,
                 gen.count,
             );

package/src/formats/cx2/importer.ts

@@ -688,6 +688,25 @@ async function readDocument(
     return doc;
 }
 
+/**
+ * Fail the import: the first member of the array is not a descriptor.
+ * @param value - the member
+ * @param line - its line
+ * @param report - the report
+ * @returns never: the import fails
+ */
+function failNoDescriptor(value: unknown, line: number, report: ImportReportBuilder): never {
+    const keys = isRecord(value) ? Object.keys(value) : [];
+    const keyList = keys.length > 0 ? ` (keys: ${keys.join(", ")})` : "";
+    return report.fail(
+        CX2_ISSUE.NO_DESCRIPTOR,
+        `the first member of the array is not a descriptor with CXVersion${keyList}`,
+        {
+            line,
+        },
+    );
+}
+
 /**
  * Check the descriptor, the first member of the array.
  * @param value - the member
@@ -697,12 +716,7 @@ async function readDocument(
  */
 function readDescriptor(value: unknown, line: number, doc: Cx2Document, report: ImportReportBuilder): void {
     if (!isRecord(value) || !("CXVersion" in value)) {
-        const keys = isRecord(value) ? Object.keys(value) : [];
-        report.fail(
-            CX2_ISSUE.NO_DESCRIPTOR,
-            `the first member of the array is not a descriptor with CXVersion${keys.length > 0 ? ` (keys: ${keys.join(", ")})` : ""}`,
-            { line },
-        );
+        failNoDescriptor(value, line, report);
     }
     const raw = value.CXVersion;
     const text = typeof raw === "string" || typeof raw === "number" ? String(raw) : "";
@@ -779,10 +793,11 @@ function memberAspect(
         collect(keys[0], value[keys[0]]);
         return;
     }
+    const what = keys.length > 1 ? `an object with ${keys.length} keys (${keys.join(", ")})` : shown(value);
     report.error(
         "parse-error",
         BAD_ASPECT_BLOCK_CODE,
-        `a member of the document is ${keys.length > 1 ? `an object with ${keys.length} keys (${keys.join(", ")})` : shown(value)}, not a one-key aspect block; skipped`,
+        `a member of the document is ${what}, not a one-key aspect block; skipped`,
         { line, element: keys[0] ?? null },
     );
 }
@@ -1325,10 +1340,11 @@ class Cx2Reader {
             }
             const other = table.byName.get(alias) ?? table.byAlias.get(alias);
             if (other !== undefined) {
+                const clash = other.name === alias ? "an attribute's name" : `the alias of "${other.name}"`;
                 this.report.error(
                     "validation-error",
                     CX2_ISSUE.ALIAS_CONFLICT,
-                    `the alias "${alias}" of the ${domain} attribute "${decl.name}" is also ${other.name === alias ? "an attribute's name" : `the alias of "${other.name}"`}; the alias is ignored`,
+                    `the alias "${alias}" of the ${domain} attribute "${decl.name}" is also ${clash}; the alias is ignored`,
                     { element: decl.name },
                 );
                 decl.alias = null;
@@ -2259,6 +2275,14 @@ class Cx2Reader {
                 }
             }
         }
+        this.checkStatus();
+        structure.checkCounts();
+    }
+
+    /** The status block: present, and exactly one well-formed element. */
+    private checkStatus(): void {
+        const { report } = this;
+        const { structure } = this.doc;
         if (!structure.hasStatus) {
             report.error("validation-error", CX2_ISSUE.NO_STATUS, "the document ends without a status block", {
                 element: "status",
@@ -2266,14 +2290,14 @@ class Cx2Reader {
         } else if (!structure.statusWellFormed() || structure.counts.get("status") !== 1) {
             // the specification: exactly one status aspect holding exactly one element
             const count = structure.counts.get("status") ?? 0;
+            const found = count === 1 ? shown(structure.status) : `${count} elements`;
             report.error(
                 "validation-error",
                 CX2_ISSUE.NO_STATUS,
-                `the status is malformed (${count === 1 ? shown(structure.status) : `${count} elements`}): a document ends with one status block holding one object with a boolean success`,
+                `the status is malformed (${found}): a document ends with one status block holding one object with a boolean success`,
                 { element: "status" },
             );
         }
-        structure.checkCounts();
     }
 
     /** Record the metadata: source format and version, name, description, id type, the kept aspects. */

package/src/formats/gexf/exporter.ts

@@ -1225,7 +1225,8 @@ function lifetimeAttrs(roles: RoleColumns, row: number, plan: ExportPlan): strin
         const text = timeText(column, roles.companions.get(column.meta.name) ?? null, row, timeFormat);
         // GEXF 1.2: `startopen` / `endopen` hold the time of a non-inclusive bound (dynamics.xsd
         // time-type) and replace `start` / `end`
-        out += ` ${open ? `${name}open` : name}="${escapeXmlAttribute(text)}"`;
+        const attribute = open ? `${name}open` : name;
+        out += ` ${attribute}="${escapeXmlAttribute(text)}"`;
     };
     if (roles.timestamp?.isSet(row)) {
         if (version === "1.3" && plan.timeRepresentation === "timestamp") {
@@ -1240,7 +1241,8 @@ function lifetimeAttrs(roles: RoleColumns, row: number, plan: ExportPlan): strin
     }
     if (version === "1.3" && roles.timestamps?.isSet(row)) {
         const items = listItems(roles.timestamps, row).map((t) => formatTimeValue(t as number, timeFormat));
-        out += ` timestamps="${escapeXmlAttribute(`<[${items.join(", ")}]>`)}"`;
+        const stamps = `<[${items.join(", ")}]>`;
+        out += ` timestamps="${escapeXmlAttribute(stamps)}"`;
     }
     return out;
 }