discombobulator 1.0.0

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "discombobulator",
+  "version": "1.0.0",
+  "description": "Discombobulator core library",
+  "license": "ISC",
+  "author": "Mark Webb",
+  "type": "module",
+  "main": "disco.mjs",
+  "scripts": {
+    "test": "node ./src/test/test.mjs -vs"
+  },
+  "dependencies": {
+    "commander": "^15.0.0",
+    "fraction.js": "^5.3.4"
+  }
+}

package/src/articulation.mjs

@@ -0,0 +1,61 @@
+// articulation.mjs
+//
+// An articulation is a modification to a note, such as an accent or roll.
+
+import util from "util";
+
+import { Element } from "./element.mjs";
+
+export class Articulation extends Element {
+  #symbol = undefined; // Symbol representing the articulation.
+
+  constructor(id) {
+    super();
+
+    if (typeof id === 'string' || id instanceof String) {
+      this.#symbol = Symbol.for(id);
+    }
+  }
+
+  get [Symbol.toStringTag]() {
+    return "Articulation";
+  }
+
+  [util.inspect.custom](depth, opts) {
+    return `${this[Symbol.toStringTag]} {${
+      !!this.#symbol ? this.#symbol.toString() : "undefined"
+    }}`;
+  }
+
+  get symbol() { return this.#symbol; }
+
+  isEqual(other) {
+    return super.isEqual(other) && this.#symbol === other.#symbol;
+  }
+}
+
+// Library of defined articulations.
+export class Articulations {
+  static Accent = new Articulation("accent"); // >
+  static Expressivo = new Articulation("expressivo"); // <>
+  static Marcato = new Articulation("marcato"); // ^
+  static Portato = new Articulation("portato"); // _
+  static Staccatissimo = new Articulation("staccatissimo"); // !
+  static Staccato = new Articulation("staccato"); // .
+  static Tenuto = new Articulation("tenuto"); // -
+  static VeryShortFermata = new Articulation("veryshortfermata");
+  static ShortFermata = new Articulation("shortfermata");
+  static Fermata = new Articulation("fermata");
+  static LongFermata = new Articulation("longfermata");
+  static VeryLongFermata = new Articulation("verylongfermata");
+  static HenzeShortFermata = new Articulation("henzeshortfermata");
+  static HenzeLongFermata = new Articulation("henzelongfermata");
+  static Roll8 = new Articulation("roll8");
+  static Roll16 = new Articulation("roll16");
+  static Roll32 = new Articulation("roll32");
+  static Ghost = new Articulation("ghost");
+  static RimShot = new Articulation("rimshot");
+  static Open = new Articulation("open");
+  static HalfOpen = new Articulation("halfopen");
+  static Stopped = new Articulation("stopped");
+}

package/src/articulationset.mjs

@@ -0,0 +1,20 @@
+// ArticulationSet
+//
+// A set of articulations.
+
+import { Set } from './set.mjs'
+import { Articulation } from './articulation.mjs'
+
+export class ArticulationSet extends Set {
+    constructor(options = {}) {
+        super(options)
+    }
+
+    get allowedElements() {
+        return [ Articulation ];
+    }
+
+    get [Symbol.toStringTag]() {
+        return "ArticulationSet";
+    }
+}

package/src/chord.mjs

@@ -0,0 +1,82 @@
+// Chord.
+//
+// A chord is a set of notes. An empty chord represents a rest.
+
+import { Note } from "./note.mjs";
+import { PatternSource } from "./patternsource.mjs";
+import { NoteSet } from "./noteset.mjs";
+
+export class Chord extends PatternSource {
+  static rest = new Chord();
+
+  constructor(options = {}) {
+    super({ ...options, strict: false });
+  }
+
+  get [Symbol.toStringTag]() {
+    return "Chord";
+  }
+
+  // Utility method to represent a chord for display, diagnostic and comparison purposes.
+  static summarise(chord) {
+    let articulations = [];
+    let instruments = [];
+
+    for (let note of chord) {
+      if (note.instrument) {
+        instruments.push(note.instrument);
+      }
+
+      if (note.articulations) {
+        for (let articulation of note.articulations) {
+          articulations.push(articulation);
+        }
+      }
+    }
+
+    return { instruments: instruments, articulations: articulations };
+  }
+
+  // Equality operator overide.
+  //
+  // Two chords are equal if their Notes result in the same set of Instruments
+  // and the same set of Articulations, exactly.
+  isEqual(other) {
+    if (!super.isEqual(other)) return false;
+
+    let a = Chord.summarise(this);
+    let b = Chord.summarise(other);
+
+    if (
+      a.instruments.length != b.instruments.length ||
+      a.articulations.size != b.articulations.size
+    ) {
+      return false;
+    }
+
+    for (let instrument of a.instruments) {
+      if (!b.instruments.includes(instrument)) return false;
+    }
+
+    for (let articulation of a.articulations) {
+      if (!b.articulations.includes(articulation)) return false;
+    }
+
+    return true;
+  }
+
+  // Overide base implementation to force semantics on Note to copy and merge.
+  internalAdd(element) {
+    let found = super.internalAdd(element, false);
+
+    if (found >= 0) {
+      let existing = this.elements[found];
+      this.elements[found] = new Note({ add: [ existing.instrument, existing.articulations ]});
+      this.elements[found].merge(element);
+    }
+  }
+
+  toNoteSet() {
+    return new NoteSet({add: this});
+  }
+}

package/src/cross.mjs

@@ -0,0 +1,133 @@
+// Factory.
+//
+// TEST factory to create sets dynamically at runtime.
+
+import { Set } from './set.mjs'
+import { InstrumentSet } from './instrumentset.mjs'
+import { ArticulationSet } from './articulationset.mjs'
+import { Note } from './note.mjs'
+import { Chord } from './chord.mjs'
+import { NoteSet } from './noteset.mjs'
+import { Pattern } from './pattern.mjs'
+import { PatternSet } from './patternset.mjs'
+
+// Cross (Cartesian Product): All pairs of elements innerElement2-element setfrom two sets.
+export class Cross extends Set.Operator {
+  // Map cross parameter types (sets) to a resultant set type that Cross acts as
+  // a proxy for. Entries in the map have the following fields:
+  //  a: first set argument type in the cross.
+  //  b: second set argument type in the cross. If a and b are different, and no d
+  //     is provided, the element type of the crossed set will be a.
+  //  c: the set class that the a X b would result in.
+  //  d: [optional] If present, the elements of the resulting set are created as
+  //     this type. This is helpful when the element type needs to be explicit,
+  //     or their is no existing set type that naturally follows from the cross.
+  static crossMap = [
+    { a: InstrumentSet,   b: InstrumentSet,   c: Pattern,   d: NoteSet },
+    { a: ArticulationSet, b: ArticulationSet, c: Pattern,   d: NoteSet },
+    { a: InstrumentSet,   b: ArticulationSet, c: NoteSet,   d: Note },
+    { a: NoteSet,         b: Chord,           c: Pattern },
+    { a: Chord,           b: Chord,           c: Pattern },
+    { a: NoteSet,         b: NoteSet,         c: Pattern },
+    { a: Pattern,         b: Pattern,         c: PatternSet },
+  ];
+
+  #allowed;
+  #proxyfor;
+
+  static checkSetOf(set1SetOf, set2SetOf, a, b) {
+    const aSetOf = (new a()).asSetOf(true);
+    const bSetOf = (new b()).asSetOf(true);
+
+    return set1SetOf.equals(aSetOf) && set2SetOf.equals(bSetOf)
+        || set2SetOf.equals(aSetOf) && set1SetOf.equals(bSetOf);
+  }
+
+  constructor(set1, set2, options = {}) {
+    super(set1, set2, { ...options, skipValidation: true });
+
+    let promotion = Cross.crossMap.find(
+      (e) => set1 instanceof e.a && set2 instanceof e.b 
+          || set2 instanceof e.a && set1 instanceof e.b 
+    );
+
+    if (promotion === undefined) {
+      // Couldn't find a match based on set class type, try using SetOf.
+      const set1SetOf = set1.asSetOf(true);
+      const set2SetOf = set2.asSetOf(true);
+    
+      promotion = Cross.crossMap.find(
+        (e) => Cross.checkSetOf(set1SetOf, set2SetOf, e.a, e.b)
+      );
+    }
+   
+    if (promotion !== undefined) {
+      if (promotion.d === undefined) {
+        this.#allowed = [ promotion.a ];
+        if (promotion.a !== promotion.b) this.#allowed.push(promotion.b);
+      } else {
+        this.#allowed = [ promotion.d ];
+      }
+
+      this.#proxyfor = promotion.c;
+    } else {
+      throw new Error("No valid promotion for Cross");
+    }
+  }
+
+  get allowedElements() {
+    return this.#allowed;
+  }
+
+  get proxyFor() {
+    return this.#proxyfor;
+  }
+
+  get [Symbol.toStringTag]() {
+    return `Cross (${this.#proxyfor.name})`;
+  }
+
+  *[Symbol.iterator]() {
+    let element = this.#allowed[0];
+    let outer = this.elements[0];
+    let inner = this.elements[1];
+
+    for (let outerElement of outer) {
+      for (let innerElement of inner) {
+        yield new element({add: [ outerElement, innerElement ]});
+      }
+    }
+  }
+
+  get size() {
+    return this.elements[0].size * this.elements[1].size;
+  }
+
+  elementAt(index = 0) {
+    let firstSize = this.elements[0].size;
+    let secondSize = this.elements[1].size;
+    let element = this.#allowed[0];
+
+    if (index >= 0 && index < firstSize * secondSize) {
+      let firstIndex = Math.floor(index / secondSize);
+      let secondIndex = index % secondSize;
+
+      return new element(
+        {add: [ 
+          this.elements[0].elementAt(firstIndex), 
+          this.elements[1].elementAt(secondIndex) 
+        ]}
+      );
+    }
+
+    throw new Error("Invalid index");
+  }
+
+  has(element) {
+    if (!this.allowedElements.includes(element.constructor)) {
+      throw new Error("Invalid element - must be a compatible 2-element set");
+    }
+
+    return this.elements[0].has(element.elementAt(0)) && this.elements[1].has(element.elementAt(1));
+  }
+};

package/src/disco.mjs

@@ -0,0 +1,14 @@
+// disco.mjs
+//
+// Startup script to initialise package.
+
+import { Cross } from "./cross.mjs"
+import { Set } from "./set.mjs"
+
+// Inject createCross into Set as a static method to allow runtime creation of 
+// Cross from Set so that Cross can automatically create result sets.
+// Set.createCross = (set1, set2) => { return new Cross(set1, set2) };
+
+export function useDisco() {
+    Set.createCross = (set1, set2) => { return new Cross(set1, set2) };
+}

package/src/element.mjs

@@ -0,0 +1,51 @@
+// Element.
+//
+// Base class for anything that can be contained in a Set.
+
+export class Element {
+  constructor() {}
+
+  get [Symbol.toStringTag]() {
+    return "Element";
+  }
+
+  // Base class equality operator.
+  //
+  // Derived classes should overide this method and call super().isEqual() before
+  // performing type-specific equality testing.
+  //
+  // The base implementation simply checks that the RHS is defined and of the
+  // same class as this one (ie.both LHS and RHS must be the same types).
+  isEqual(other) {
+    if (!!other && this.constructor === other.constructor) return true;
+
+    return false;
+  }
+
+  // If possible and necessary, promotes the given element to the same
+  // type as this element.
+  //
+  // If the given element is already of the same type as this one, then
+  // the given element is returned unchanged.
+  //
+  // If the element can be promoted by the element, then it is used to
+  // initialise or modify this one to reflect the promotion. This is highly
+  // implementation dependant. eg. A set might just add the element to itself.
+  //
+  // If the element cannot be promoted, undefined is returned.
+  promote(element) {
+    if (this.constructor === element.constructor) {
+      return element;
+    }
+
+    return undefined;
+  }
+
+  // Merges the other element with this one.
+  //
+  // By default no merge takes place. ie. The other element is ignored.
+  //
+  // If a derived class, such as Note, has partial identity then it must overide this
+  // method to allow the non-identity parts (ArticulationSet in this case) to be merged.
+  merge(other) {}
+}

package/src/group.mjs

@@ -0,0 +1,70 @@
+// group.mjs
+//
+// A group is a time-axis pattern that specifies how chords may be grouped.
+
+import util from "util";
+
+import { Element } from "./element.mjs";
+
+export class Group extends Element {
+  // A group is represented as a bit pattern beginning at bit 0 and extending
+  // for length bits (inclusive). ie. the bits in the range 0...length-1.
+  // In that range a 1 represents an active chord position, and 0 a rest.
+  #group = 0; // Binary group starting at bit 0.
+  #length = 0; // Length of the group [1...32], where 0 is undefined.
+
+  static MAX_LENGTH = 32;
+
+  constructor(group = 0, length = 0) {
+    super();
+
+    if (1 > length || length > Group.MAX_LENGTH) {
+      throw new Error(
+        `Invalid Group length - must be from 1 to ${Group.MAX_LENGTH}`
+      );
+    }
+
+    this.#group = length < Group.MAX_LENGTH ? group & ((1 << length) - 1) : group;
+    this.#length = length;
+  }
+
+  get [Symbol.toStringTag]() {
+    return "Group";
+  }
+
+  get group() {
+    return this.#group;
+  }
+  get length() {
+    return this.#length;
+  }
+
+  // Describe the group as a string.
+  // Note: the description is in the order LSB...MSB
+  //       (the reverse of standard binary representation)
+  #describe() {
+    if (this.#length == 0) return "!";
+
+    let group = this.#group;
+    let description = "";
+
+    for (let i = 0; i < this.#length; ++i) {
+      description += group & 1 ? "#" : "-";
+      group >>= 1;
+    }
+
+    return description;
+  }
+
+  [util.inspect.custom](depth, opts) {
+    return `${this[Symbol.toStringTag]} {${this.#describe()}}`;
+  }
+
+  isEqual(other) {
+    return (
+      super.isEqual(other) &&
+      this.#length === other.#length &&
+      this.#group === other.#group
+    );
+  }
+}