linked-rolls 0.53.0 → 0.54.0

package/lib/Feature.d.ts

@@ -109,15 +109,6 @@ export type FeatureConditionAssignment = ObjectAssumption<ConditionState<Feature
  * @see reo:Hole
  */
 export interface Hole extends RollFeature<'Hole', typeof conditions.Hole[number]> {
-    /**
-     * The punching pattern of the hole. Regular holes have evenly-spaced
-     * bridges, accelerating holes have decreasing bridge widths, and
-     * staggering holes do not align in rows across the tracks, the mark
-     * of an asynchronous perforator with a separate driver for each
-     * punch (Phillips 2016, p. 112).
-     * @see reo:pattern
-     */
-    pattern?: 'regular' | 'accelerating' | 'staggering';
 }
 /**
  * Something that lies on a face of the paper rather than through it. A

package/lib/Perforator.d.ts

@@ -1,7 +1,7 @@
 import { ObjectAssumption } from "./Assumption.js";
 import { ConditionState } from "./ConditionState.js";
 import { Measure, Millimeters } from "./Quantity.js";
-import { WithId } from "./utils.js";
+import { WithId, WithType } from "./utils.js";
 /**
  * The pitch in the engineering sense: the distance along the roll from
  * one punch of a chain to the next, which is the slot one firing cut
@@ -75,13 +75,44 @@ export interface PerforatorSetting extends ConditionState<'setting'> {
      */
     advance?: ObjectAssumption<Advance>;
 }
+/**
+ * How the punches of a perforator were driven, after Phillips (2016,
+ * pp. 112 f.): all at once by one ram head, or each by a driver of its
+ * own. `ontology/types.ttl` defines them, and a test holds this list
+ * against it.
+ * @see crm:E55 Type
+ */
+export declare const drives: readonly [{
+    readonly id: 'https://w3id.org/reo/type/drive/ram-head';
+    readonly name: 'ram head';
+}, {
+    readonly id: 'https://w3id.org/reo/type/drive/asynchronous';
+    readonly name: 'asynchronous';
+}];
+export type DriveId = typeof drives[number]['id'];
+/**
+ * A drive, named by its IRI alone.
+ * @see crm:E55 Type
+ */
+export interface Drive {
+    /** The IRI the type vocabulary gives the drive. */
+    readonly id: DriveId;
+}
 /**
  * The machine that punched the copy. It stands for this production
  * alone. Whether it is the one another copy was punched on is left to a
  * statement of identity made about it elsewhere, which its id allows.
  * @see crm:E22 Human-Made Object
  */
-export interface Perforator extends WithId {
+export interface Perforator extends WithType<'Perforator'>, WithId {
+    /**
+     * How its punches were driven, as the rows of its chains show it:
+     * in line across the tracks where one ram head drove them all, and
+     * staggered where each punch had a driver of its own. It is part of
+     * how the machine was built and so no part of its setting.
+     * @see reo:drive
+     */
+    drive?: ObjectAssumption<Drive>;
     /**
      * @see crm:P44 has condition
      */

package/lib/Perforator.js

@@ -1 +1,11 @@
-export {};
+/**
+ * How the punches of a perforator were driven, after Phillips (2016,
+ * pp. 112 f.): all at once by one ram head, or each by a driver of its
+ * own. `ontology/types.ttl` defines them, and a test holds this list
+ * against it.
+ * @see crm:E55 Type
+ */
+export const drives = [
+    { id: 'https://w3id.org/reo/type/drive/ram-head', name: 'ram head' },
+    { id: 'https://w3id.org/reo/type/drive/asynchronous', name: 'asynchronous' }
+];

package/lib/RollCopy.d.ts

@@ -116,8 +116,8 @@ export interface ProductionEvent {
      */
     speed?: ObjectAssumption<PaperSpeed>;
     /**
-     * The perforator the copy was punched on, with the setting its
-     * perforations show.
+     * The perforator the copy was punched on, with the drive and the
+     * setting its perforations show.
      * @see crm:P16 used specific object
      */
     perforator?: Perforator;

package/lib/migrate.js

@@ -119,11 +119,15 @@ const withScale = (node) => {
 };
 /** A copy's id without the `copy/` that documents of earlier releases put before it. */
 export const plainCopyId = (id) => id.replace(/^copy\//, '');
+/**
+ * The perforator the copy states, or a new one named after the copy, so
+ * that a file migrated twice names it the same way.
+ */
+const perforatorOf = (copy) => copy.production?.perforator ?? { '@type': 'Perforator', '@id': `perforator_${plainCopyId(copy['@id'])}` };
 /**
  * The punch diameter was a measurement of the copy before it was stated
  * as the setting of the perforator that cut it. A diameter of -1 stood
- * for one nobody had measured and is left out. The perforator is named
- * after the copy, so that a file migrated twice names it the same way.
+ * for one nobody had measured and is left out.
  */
 const withPerforator = (node) => {
     const diameter = node.measurements?.punchDiameter;
@@ -132,7 +136,7 @@ const withPerforator = (node) => {
     const { punchDiameter: _moved, ...measurements } = node.measurements;
     if (!(diameter?.value > 0))
         return { ...node, measurements };
-    const perforator = node.production?.perforator ?? { '@id': `perforator_${plainCopyId(node['@id'])}` };
+    const perforator = perforatorOf(node);
     return {
         ...node,
         measurements,
@@ -150,6 +154,37 @@ const withPerforator = (node) => {
         }
     };
 };
+/** A perforator was first written without a type. */
+const withTypedPerforator = (node) => {
+    const perforator = node.perforator;
+    if (!perforator || typeof perforator !== 'object' || perforator['@type'])
+        return node;
+    return { ...node, perforator: { '@type': 'Perforator', ...perforator } };
+};
+const asynchronous = 'https://w3id.org/reo/type/drive/asynchronous';
+/**
+ * Each hole once stated its punching pattern. A staggering hole the copy
+ * was punched with shows that its perforator drove each punch on its
+ * own; one a later act made shows nothing about the machine. Regular
+ * and accelerating bridges are not carried over: the chain pitch states
+ * the one, and for the other no source was found. The features are in
+ * their acts here, since a node is migrated before its children are.
+ */
+const withDriveOfStaggering = (node) => {
+    const produced = node.production?.produced;
+    if (!Array.isArray(produced) || !produced.some((feature) => feature?.pattern === 'staggering'))
+        return node;
+    const perforator = perforatorOf(node);
+    if (perforator.drive)
+        return node;
+    return { ...node, production: { ...node.production, perforator: { ...perforator, drive: { '@id': asynchronous } } } };
+};
+const withoutPattern = (node) => {
+    if (node['@type'] !== 'Hole' || !Object.hasOwn(node, 'pattern'))
+        return node;
+    const { pattern: _moved, ...rest } = node;
+    return rest;
+};
 /** A derivation written as a single one, before a version could name several. */
 const isSingleDerivation = (basedOn) => basedOn !== null && typeof basedOn === 'object' && !Array.isArray(basedOn);
 const withDerivationList = (node) => isSingleDerivation(node.basedOn) ? { ...node, basedOn: [node.basedOn] } : node;
@@ -266,8 +301,8 @@ const withTimeSpanDates = (node) => {
     return { ...rest, within };
 };
 const migrateNode = (node) => [withRenamedKeys, withTypology, withoutVersionType, withoutVersionSiglum, withLowerCaseTerms, withSplitMethod, withReferences, withKeeper, withoutEmptyKeeper,
-    withPerforator, withProductionNodes, withScale, withDerivationList, withReadingKind, withTimeSpanDates, withoutFeatureKind,
-    withBorneFeaturesNamed, withFeaturesInActs]
+    withPerforator, withProductionNodes, withTypedPerforator, withScale, withDerivationList, withReadingKind, withTimeSpanDates,
+    withoutFeatureKind, withBorneFeaturesNamed, withFeaturesInActs, withDriveOfStaggering, withoutPattern]
     .reduce((result, step) => step(result), node);
 /** The items each walked, or the very same list where the walk changed none. */
 const walked = (items) => {

package/lib/readers/stanfordAton.js

@@ -161,6 +161,7 @@ export function readFromStanfordAton(atonString, { trackShift, system = welteT10
             system: systemOf(system),
             ...(punchDiameter !== undefined && {
                 perforator: {
+                    type: 'Perforator',
                     id: `perforator_${v4()}`,
                     condition: {
                         type: 'ConditionState',

package/lib/schema.json

@@ -436,6 +436,13 @@
             "type": "object",
             "ontology": "lrmoo:R76 is derivative of"
         },
+        "DriveId": {
+            "enum": [
+                "https://w3id.org/reo/type/drive/ram-head",
+                "https://w3id.org/reo/type/drive/asynchronous"
+            ],
+            "type": "string"
+        },
         "Edit": {
             "description": "A set of edits transforms a version of a roll into another version. Edits insert or delete symbols, or both (= replace). Edits may be motivated by a given set of reasons, e.g. to add an additional accent or to correct an error. If an edit is the interpretation of a metamark, such as a pencil mark, this should be made explicit using a meaning comprehension on the `@annotation` field.",
             "properties": {
@@ -895,16 +902,6 @@
                     "description": "Horizontal span of the feature on the roll.",
                     "ontology": "crm:P43 has dimension"
                 },
-                "pattern": {
-                    "description": "The punching pattern of the hole. Regular holes have evenly-spaced bridges, accelerating holes have decreasing bridge widths, and staggering holes do not align in rows across the tracks, the mark of an asynchronous perforator with a separate driver for each punch (Phillips 2016, p. 112).",
-                    "enum": [
-                        "regular",
-                        "accelerating",
-                        "staggering"
-                    ],
-                    "type": "string",
-                    "ontology": "reo:pattern"
-                },
                 "vertical": {
                     "$ref": "#/definitions/VerticalSpan",
                     "description": "Vertical span of the feature on the roll.",
@@ -1448,16 +1445,6 @@
                             "description": "Horizontal span of the feature on the roll. Left out by a feature a patch bears.",
                             "ontology": "crm:P43 has dimension"
                         },
-                        "pattern": {
-                            "description": "The punching pattern of the hole. Regular holes have evenly-spaced bridges, accelerating holes have decreasing bridge widths, and staggering holes do not align in rows across the tracks, the mark of an asynchronous perforator with a separate driver for each punch (Phillips 2016, p. 112).",
-                            "enum": [
-                                "regular",
-                                "accelerating",
-                                "staggering"
-                            ],
-                            "type": "string",
-                            "ontology": "reo:pattern"
-                        },
                         "vertical": {
                             "$ref": "#/definitions/VerticalSpan",
                             "description": "Vertical span of the feature on the roll. Left out by a feature a patch bears.",
@@ -2294,6 +2281,38 @@
             ],
             "type": "object"
         },
+        "ObjectAssumption<Drive>": {
+            "description": "An object assumption wraps a complex object with an optional annotation. Used for structured values (e.g. persons, conditions) whose properties may be uncertain.",
+            "properties": {
+                "@annotation": {
+                    "description": "An optional annotation expressing a belief about this assumption. Uses the JSON-LD-star `@annotation` mechanism to attach epistemic metadata (certainty and reasons) to any triple.",
+                    "properties": {
+                        "belief": {
+                            "$ref": "#/definitions/Belief",
+                            "description": "The belief held about the annotated statement.",
+                            "ontology": "crminf:J4i is subject of"
+                        },
+                        "@id": {
+                            "description": "A unique identifier for this object.",
+                            "type": "string"
+                        }
+                    },
+                    "required": [
+                        "belief",
+                        "@id"
+                    ],
+                    "type": "object"
+                },
+                "@id": {
+                    "$ref": "#/definitions/DriveId",
+                    "description": "The IRI the type vocabulary gives the drive."
+                }
+            },
+            "required": [
+                "@id"
+            ],
+            "type": "object"
+        },
         "ObjectAssumption<Instrument>": {
             "description": "An object assumption wraps a complex object with an optional annotation. Used for structured values (e.g. persons, conditions) whose properties may be uncertain.",
             "properties": {
@@ -2666,13 +2685,25 @@
                     "$ref": "#/definitions/PerforatorSetting",
                     "ontology": "crm:P44 has condition"
                 },
+                "drive": {
+                    "$ref": "#/definitions/ObjectAssumption%3CDrive%3E",
+                    "description": "How its punches were driven, as the rows of its chains show it: in line across the tracks where one ram head drove them all, and staggered where each punch had a driver of its own. It is part of how the machine was built and so no part of its setting.",
+                    "ontology": "reo:drive"
+                },
                 "@id": {
                     "description": "A unique identifier for this object.",
                     "type": "string"
+                },
+                "@type": {
+                    "const": "Perforator",
+                    "description": "The type discriminator for this object.",
+                    "type": "string",
+                    "ontology": "rdf:type"
                 }
             },
             "required": [
-                "@id"
+                "@id",
+                "@type"
             ],
             "type": "object",
             "ontology": "crm:E22 Human-Made Object"
@@ -2773,7 +2804,7 @@
                 },
                 "perforator": {
                     "$ref": "#/definitions/Perforator",
-                    "description": "The perforator the copy was punched on, with the setting its perforations show.",
+                    "description": "The perforator the copy was punched on, with the drive and the setting its perforations show.",
                     "ontology": "crm:P16 used specific object"
                 },
                 "produced": {

package/lib/spec/context.json

@@ -21,6 +21,7 @@
         "Attachment": "crm:E79_Part_Addition",
         "Removal": "crm:E80_Part_Removal",
         "Alteration": "crm:E12_Production",
+        "Perforator": "crm:E22_Human-Made_Object",
         "ConditionState": "crm:E3_Condition_State",
         "note": "reo:Note",
         "expression": "reo:Expression",
@@ -192,6 +193,7 @@
                 }
             }
         },
+        "drive": "reo:drive",
         "company": "crm:P14_carried_out_by",
         "paper": "crm:P126_employed",
         "conditions": "crm:P44_has_condition",
@@ -249,11 +251,6 @@
             "@type": "@vocab",
             "@context": { "@vocab": "https://w3id.org/reo/type/" }
         },
-        "pattern": {
-            "@id": "reo:pattern",
-            "@type": "@vocab",
-            "@context": { "@vocab": "https://w3id.org/reo/type/" }
-        },
         "technique": {
             "@id": "reo:technique",
             "@type": "@vocab",

package/lib/vocabulary.d.ts

@@ -1,8 +1,8 @@
 import { Concept } from "./Agent.js";
 /**
  * The concepts the type vocabulary declares, whatever kind they are:
- * the reproducing systems and the procedures. An edition names one of
- * them by its IRI alone.
+ * the reproducing systems, the procedures and the drives of a
+ * perforator. An edition names one of them by its IRI alone.
  */
 export declare const vocabulary: readonly Concept[];
 /** The concept of that IRI, where the vocabulary declares one. */

package/lib/vocabulary.js

@@ -1,14 +1,16 @@
+import { drives } from "./Perforator.js";
 import { procedures } from "./procedures.js";
 import { systemOf } from "./TrackerBar.js";
 import { trackerBars } from "./systems/index.js";
 /**
  * The concepts the type vocabulary declares, whatever kind they are:
- * the reproducing systems and the procedures. An edition names one of
- * them by its IRI alone.
+ * the reproducing systems, the procedures and the drives of a
+ * perforator. An edition names one of them by its IRI alone.
  */
 export const vocabulary = [
     ...trackerBars.map(systemOf),
-    ...procedures
+    ...procedures,
+    ...drives
 ];
 /** The concept of that IRI, where the vocabulary declares one. */
 export const conceptOf = (id) => id === undefined ? undefined : vocabulary.find(concept => concept.id === id);

package/package.json

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