linked-rolls 0.48.0 → 0.49.0

package/lib/RollCopy.d.ts

@@ -259,16 +259,28 @@ export interface RollCopy extends WithType<'RollCopy'>, WithId {
          */
         scale: number;
         /**
-         * How much longer this copy's reading of a hole ran than the
-         * perforation that caused it, where that was taken off the ends
-         * again. A pneumatic reader reports how long a valve stayed
-         * open, which exceeds the perforation that opened it, so its
-         * holes are overlong by a constant while its onsets agree.
+         * What a pneumatic reader added to this copy's holes, where it
+         * was taken off again. Such a reader reports how long a valve
+         * stayed open, which exceeds the perforation that opened it, so
+         * its holes are overlong by a constant while its onsets agree.
          * Nothing for a copy read by other means, whose holes are the
          * punched slots themselves.
          * Not exported to RDF.
          */
-        readerExtension: Millimeters;
+        readerExtension: {
+            /** How much longer the reading of a hole ran than the perforation that caused it. */
+            length: Millimeters;
+            /**
+             * The holes it was not taken off, by `@id`, being no longer
+             * than it is. The constant reaches its limit there rather
+             * than the copy being wrong, and why they were left is for
+             * the edition to state about the features themselves; this
+             * only records that they stand as the reader gave them, so
+             * that putting the extension back does not lengthen a hole
+             * nothing was taken from.
+             */
+            leaving?: string[];
+        };
         /**
          * The resolution this copy's scan was read at, along the roll.
          * It is what the measurements given in pixels are to be read

package/lib/alignment.d.ts

@@ -44,9 +44,20 @@ export declare const revertScale: (copy: RollCopy) => void;
  * on the feature, a reading of the hole, a smaller extension — and
  * `shortenHoles` throws rather than answer it.
  */
-export declare const tooShortToShorten: (extension: Millimeters, copy: RollCopy) => Readonly<FeatureOrPatch>[];
-export declare const shortenHoles: (extension: Millimeters, copy: RollCopy) => void;
-/** Puts the reader's extension back on the copy's holes, as far as one was taken off. */
+export declare const tooShortToShorten: (extension: Millimeters, copy: RollCopy, leaving?: ReadonlySet<string>) => Readonly<FeatureOrPatch>[];
+/**
+ * Takes the extension off, leaving the named holes as the reader gave
+ * them. Naming a hole is an editorial act and not a repair: it says
+ * this one is where the constant stops applying, and the edition is
+ * what has to say why. The copy records which were left, so that
+ * putting the extension back does not lengthen a hole nothing was
+ * taken from.
+ *
+ * Throws where a hole that was not named is no longer than the
+ * extension, `tooShortToShorten` saying beforehand which those are.
+ */
+export declare const shortenHoles: (extension: Millimeters, copy: RollCopy, leaving?: ReadonlySet<string>) => void;
+/** Puts the reader's extension back on the holes it was taken off, as far as one was taken off. */
 export declare const revertShortening: (copy: RollCopy) => void;
 /**
  * How a copy's places are carried onto another copy's:

package/lib/alignment.js

@@ -90,26 +90,43 @@ const holesOf = (copy) => featuresOf(copy).filter(feature => feature.type === 'H
  * on the feature, a reading of the hole, a smaller extension — and
  * `shortenHoles` throws rather than answer it.
  */
-export const tooShortToShorten = (extension, copy) => holesOf(copy).filter(hole => hole.horizontal.to - hole.horizontal.from <= extension);
-export const shortenHoles = (extension, copy) => {
+export const tooShortToShorten = (extension, copy, leaving = new Set()) => holesOf(copy).filter(hole => !leaving.has(hole.id) && hole.horizontal.to - hole.horizontal.from <= extension);
+/**
+ * Takes the extension off, leaving the named holes as the reader gave
+ * them. Naming a hole is an editorial act and not a repair: it says
+ * this one is where the constant stops applying, and the edition is
+ * what has to say why. The copy records which were left, so that
+ * putting the extension back does not lengthen a hole nothing was
+ * taken from.
+ *
+ * Throws where a hole that was not named is no longer than the
+ * extension, `tooShortToShorten` saying beforehand which those are.
+ */
+export const shortenHoles = (extension, copy, leaving = new Set()) => {
     if (copy.ops.includes('shortened'))
         return;
-    const tooShort = tooShortToShorten(extension, copy);
+    const tooShort = tooShortToShorten(extension, copy, leaving);
     if (tooShort.length > 0) {
         throw new Error(`The extension of ${extension} mm cannot be taken off ${tooShort.length} `
             + `hole(s) of copy ${copy.id}, which are no longer than it: `
             + `${tooShort.map(hole => hole.id).join(', ')}`);
     }
-    holesOf(copy).forEach(hole => { hole.horizontal.to = subtract(hole.horizontal.to, extension); });
+    const left = holesOf(copy).filter(hole => leaving.has(hole.id)).map(hole => hole.id);
+    holesOf(copy)
+        .filter(hole => !leaving.has(hole.id))
+        .forEach(hole => { hole.horizontal.to = subtract(hole.horizontal.to, extension); });
     copy.ops = [...copy.ops, 'shortened'];
-    copy.measurements.readerExtension = extension;
+    copy.measurements.readerExtension = { length: extension, ...(left.length > 0 && { leaving: left }) };
 };
-/** Puts the reader's extension back on the copy's holes, as far as one was taken off. */
+/** Puts the reader's extension back on the holes it was taken off, as far as one was taken off. */
 export const revertShortening = (copy) => {
-    const extension = copy.measurements.readerExtension;
-    if (!copy.ops.includes('shortened') || extension === undefined)
+    const taken = copy.measurements.readerExtension;
+    if (!copy.ops.includes('shortened') || taken === undefined)
         return;
-    holesOf(copy).forEach(hole => { hole.horizontal.to = add(hole.horizontal.to, extension); });
+    const left = new Set(taken.leaving ?? []);
+    holesOf(copy)
+        .filter(hole => !left.has(hole.id))
+        .forEach(hole => { hole.horizontal.to = add(hole.horizontal.to, taken.length); });
     copy.ops = copy.ops.filter(op => op !== 'shortened');
     delete copy.measurements.readerExtension;
 };

package/lib/editionOps.d.ts

@@ -46,7 +46,7 @@ export declare const unalignCopy: (copyId: string) => EditionOp;
  * copy's holes, and records how much was taken, so that its lengths
  * can be compared with a scanned copy's at all.
  */
-export declare const shortenCopy: (copyId: string, extension: Millimeters) => EditionOp;
+export declare const shortenCopy: (copyId: string, extension: Millimeters, leaving?: ReadonlySet<string>) => EditionOp;
 /** Puts the reader's extension back on the copy's holes. */
 export declare const unshortenCopy: (copyId: string) => EditionOp;
 /** States what the copy's features were read from, in place of any earlier statement. */

package/lib/editionOps.js

@@ -141,7 +141,7 @@ export const unalignCopy = (copyId) => onCopy(copyId, copy => {
  * copy's holes, and records how much was taken, so that its lengths
  * can be compared with a scanned copy's at all.
  */
-export const shortenCopy = (copyId, extension) => onCopy(copyId, copy => shortenHoles(extension, copy));
+export const shortenCopy = (copyId, extension, leaving) => onCopy(copyId, copy => shortenHoles(extension, copy, leaving));
 /** Puts the reader's extension back on the copy's holes. */
 export const unshortenCopy = (copyId) => onCopy(copyId, copy => revertShortening(copy));
 /** States what the copy's features were read from, in place of any earlier statement. */

package/lib/schema.json

@@ -2829,8 +2829,24 @@
                             "ontology": "reo:punchDiameter"
                         },
                         "readerExtension": {
-                            "$ref": "#/definitions/Millimeters",
-                            "description": "How much longer this copy's reading of a hole ran than the perforation that caused it, where that was taken off the ends again. A pneumatic reader reports how long a valve stayed open, which exceeds the perforation that opened it, so its holes are overlong by a constant while its onsets agree. Nothing for a copy read by other means, whose holes are the punched slots themselves. Not exported to RDF."
+                            "description": "What a pneumatic reader added to this copy's holes, where it was taken off again. Such a reader reports how long a valve stayed open, which exceeds the perforation that opened it, so its holes are overlong by a constant while its onsets agree. Nothing for a copy read by other means, whose holes are the punched slots themselves. Not exported to RDF.",
+                            "properties": {
+                                "leaving": {
+                                    "description": "The holes it was not taken off, by `@id`, being no longer than it is. The constant reaches its limit there rather than the copy being wrong, and why they were left is for the edition to state about the features themselves; this only records that they stand as the reader gave them, so that putting the extension back does not lengthen a hole nothing was taken from.",
+                                    "items": {
+                                        "type": "string"
+                                    },
+                                    "type": "array"
+                                },
+                                "length": {
+                                    "$ref": "#/definitions/Millimeters",
+                                    "description": "How much longer the reading of a hole ran than the perforation that caused it."
+                                }
+                            },
+                            "required": [
+                                "length"
+                            ],
+                            "type": "object"
                         },
                         "scale": {
                             "description": "The factor this copy's features were scaled by to align them with the others. What it is put down to is stated apart: a paper-stretch condition, or the speed the copy was cut for. Not exported to RDF.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linked-rolls",
-  "version": "0.48.0",
+  "version": "0.49.0",
   "description": "Digital editions of piano rolls: import, collation, editorial assumptions, JSON-LD export, and emulation through a reproducing system",
   "license": "MIT",
   "repository": {