discombobulator 1.0.0

package/src/note.mjs

@@ -0,0 +1,155 @@
+// Note.
+//
+// A note is a tuple of an instrument and a set of articulations that affect how it's played.
+
+import util from "util";
+
+import { Element } from "./element.mjs";
+import { Instrument } from "./instrument.mjs";
+import { Articulation } from "./articulation.mjs";
+import { ArticulationSet } from "./articulationset.mjs";
+
+export class Note extends Element {
+  #instrument = undefined;
+  #articulations = undefined;
+
+  constructor(options = {}) {
+    options = { add: [ undefined, undefined ], ...options };
+    const add = options.add;
+    const instrument = Array.isArray(add) ? (add.length >= 1 ? add[0] : undefined) : add;
+    let articulations = Array.isArray(add) && add.length > 1 ? add[1] : undefined;
+
+    if (!(instrument === undefined || instrument instanceof Instrument)) {
+      throw new Error("InvalidArgumentExpression: instrument must be undefined or a valid Instrument");
+    }
+
+    if (
+      !(articulations === undefined || articulations instanceof ArticulationSet)
+    ) {
+      // As a last resort, see if an ArticulationSet can be constructed by promoting whatever was passed.
+      articulations = new ArticulationSet({ add: articulations });
+
+      if (articulations === undefined) {
+        throw new Error("InvalidArgumentExpression: articulations must be undefined or a valid Articulation or ArticulationSet");
+      }
+    }
+
+    super();
+
+    this.#instrument = instrument;
+    this.#articulations = articulations;
+  }
+
+  // Return a clone of this note.
+  //
+  // If deep is true, the notes articulation set is also cloned, if it exists,
+  // otherwise the articulation set is copied by reference.
+  clone(deep = false) {
+    let articulations = this.#articulations;
+
+    if (deep && !!articulations && articulations.clone !== undefined) {
+      articulations = articulations.clone(deep);
+    }
+    return new this.constructor({ add: [ this.#instrument, articulations ]});
+  }
+
+  get [Symbol.toStringTag]() {
+    return "Note";
+  }
+
+  // Pseudo-implementation to allow Note to act like a set of two elements.
+  elementAt(index = 0) {
+    if (index === 0) return this.#instrument;
+    if (index === 1) return this.#articulations;
+
+    throw new Error("Invalid index");
+  }
+
+  promote(element) {
+    if (this.constructor === element.constructor) {
+      return element;
+    }
+    
+    if (element instanceof Instrument) {
+      this.#instrument = element;
+      this.#articulations = undefined;
+    } else if (element instanceof ArticulationSet) {
+      this.#instrument = undefined;
+      this.#articulations = element;
+    } else if (element instanceof Articulation) {
+      this.#instrument = undefined;
+      this.#articulations = new ArticulationSet();
+      this.articulations.add(element);
+    } else {
+      return undefined;
+    }
+
+    return this;
+  }
+
+  [util.inspect.custom](depth, opts) {
+    return `${this[Symbol.toStringTag]} {${
+      !!this.#instrument ? util.inspect(this.#instrument) : "undefined"
+    }, {${
+      !!this.#articulations ? util.inspect(this.#articulations) : "undefined"
+    }}}`;
+  }
+
+  get instrument() {
+    return this.#instrument;
+  }
+
+  get articulations() {
+    return this.#articulations;
+  }
+  
+  get isRest() {
+    return this.instrument === undefined;
+  }
+
+  // Equality operator overide.
+  //
+  // Two notes are equal if they have the same instrument and, if strict is true, the same
+  // articulations. If strict is false the articulation set is ignored.
+  //
+  // Note: When a Note is added to a Chord that contains a Note with the same instrument
+  // (ie. equal Notes), the note already in the Chord has its articulation set changed to be
+  // the union of its existing articulation set and the articulation set of the other Note.
+  isEqual(other, strict = false) {
+    const typesMatch = super.isEqual(other);
+    
+    const bothAreRests = this.isRest && other.isRest;
+    const sameInstruments = !this.isRest && this.instrument.isEqual(other.instrument);
+    
+    const instrumentsMatch = bothAreRests || sameInstruments;
+
+    const neitherHasArticulations = this.ariticulations === undefined && other.articulations === undefined;
+    const sameArticulations = this.articulations !== undefined && this.articulations.isEqual(other.articulations);
+
+    const articulationsMatch = neitherHasArticulations || sameArticulations;
+
+    let result = typesMatch && instrumentsMatch && (!strict || articulationsMatch);
+
+    return result;
+  }
+
+  // Merge two Notes. Note identity is determined by the Instrument. So an exception is thrown
+  // if the other Note does not have the same Instrument as this one. Merging makes the ArticulationSet
+  // of this Note be the union of it's existing ArticulationSet and that of the other Note.
+  merge(other) {
+    if (!(other instanceof Note)) {
+      throw new Error("A note can only be merged with another note");
+    }
+
+    if (this.#instrument !== other.#instrument)
+      throw new Error("Attempt to merge Notes with differing instruments");
+
+    if (this.#articulations === undefined) {
+      this.#articulations = other.#articulations;
+    } else if (other.articulations !== undefined) {
+      this.#articulations = this.#articulations.union(other.#articulations);
+    }
+
+    return this;
+  }
+}

package/src/noteset.mjs

@@ -0,0 +1,21 @@
+// NoteSet.
+//
+// A set of notes. Unlike a Chord, which merges equivalent notes, 
+// a note set behaves like a normal set and treats notes as independent.
+
+import { PatternSource } from "./patternsource.mjs";
+import { Chord } from "./chord.mjs";
+
+export class NoteSet extends PatternSource {
+  constructor(options = {}) {
+    super(options);
+  }
+
+  get [Symbol.toStringTag]() {
+    return "NoteSet";
+  }
+
+  toChord() {
+    return new Chord({add: this});
+  }
+}

package/src/pattern.mjs

@@ -0,0 +1,52 @@
+// Pattern.
+//
+// A pattern is a sequence of chords.
+
+import { Set } from "./set.mjs";
+import { PatternSource } from "./patternsource.mjs";
+
+export class Pattern extends Set {
+  constructor(options = {}) {
+    super({ allowDuplicates: true, ...options });
+  }
+
+  get allowedElements() {
+    return [PatternSource];
+  }
+
+  get [Symbol.toStringTag]() {
+    return "Pattern";
+  }
+
+  // Equality operator overide.
+  //
+  // Two Patterns are equal if they contain all of the same Chords in the same order.
+  isEqual(other) {
+    if (!super.isEqual(other)) return false;
+
+    if (this.size != other.size) return false;
+
+    let a = this[Symbol.iterator]();
+    let b = other[Symbol.iterator]();
+
+    let element = a.next();
+
+    while (!element.done) {
+      if (!element.value.isEqual(b.next().value)) {
+        return false;
+      }
+
+      element = a.next();
+    }
+
+    return true;
+  }
+
+  // rotate(options = {}) {
+  //   return new Set.Rotation({
+  //     ...options,
+  //     setClass: this.constructor,
+  //     set: this,
+  //   });
+  // }
+}

package/src/patternset.mjs

@@ -0,0 +1,20 @@
+// PatternSet.
+//
+// A pattern set is a set of patterns. Duh!
+
+import { Set } from "./set.mjs";
+import { Pattern } from "./pattern.mjs";
+
+export class PatternSet extends Set {
+  constructor(options = {}) {
+    super(options);
+  }
+
+  get allowedElements() {
+    return [Pattern];
+  }
+
+  get [Symbol.toStringTag]() {
+    return "PatternSet";
+  }
+}

package/src/patternsource.mjs

@@ -0,0 +1,21 @@
+// PatternSource.
+//
+// Base class for set classes that may be used as sources to a Pattern.
+// Specifically, NoteSet and Chord are pattern sources.
+
+import { Set } from "./set.mjs";
+import { Note } from "./note.mjs";
+
+export class PatternSource extends Set {
+  constructor(options = {}) {
+    super(options);
+  }
+
+  get allowedElements() {
+    return [ Note ];
+  }
+
+  get [Symbol.toStringTag]() {
+    return "PatternSource";
+  }
+}

package/src/permute.mjs

@@ -0,0 +1,63 @@
+// Permutation helper functions.
+
+import { factorial } from './util.mjs'
+
+function productRange(a, b) {
+  var prd = a;
+  var i = a;
+
+  while (i++ < b) {
+    prd *= i;
+  }
+  return prd;
+}
+
+export function combinations(n, r) {
+  if (n == r || r == 0) {
+    return 1;
+  } else {
+    r = r < n - r ? n - r : r;
+    return productRange(r + 1, n) / productRange(1, n - r);
+  }
+}
+
+export function permutations(n, r) {
+  return factorial(n) / factorial(n -r );
+}
+
+export function ithBinaryCombination(n, r, i) {
+    const mask = 1 << n - 1;
+
+    let ibc = 0;
+    let ones = combinations(n, r);
+
+    if (0 > i || i >= ones) return undefined;
+
+    while (n-- > 0) {
+        ibc >>= 1;
+        ones = combinations(n, r-1);
+        
+        if (r > 0 && i < ones) {
+            ibc |= mask;
+            r--;
+        } else {
+            i -= ones;
+        }
+    }
+
+    return ibc;
+}
+
+// Generator function to generate the permutations of r indexes where 
+// each index value must be in the range [ 0, n - 1 ].
+export function* permutationIndexGenerator(r = 1, n = 1, allowRepeats = true, indices = []) {
+  for (let index = 0; index < n; ++index) {
+    if (allowRepeats || !indices.includes(index)) {
+      if (indices.length + 1 < r) {
+        yield* permutationIndexGenerator(r, n, allowRepeats, [ ...indices, index ]);
+      } else {
+        yield [ ...indices, index ];
+      }
+    }
+  }
+}

package/src/regulargroupset.mjs

@@ -0,0 +1,120 @@
+// RegularGroupGenerator is a Group generator that generates fully active
+// groups in a range determined by boundaries and a step rate.
+
+import util from "util";
+
+import { bitCount } from "./util.mjs";
+import { Group } from "./group.mjs";
+import { GroupSet } from "./groupset.mjs";
+
+export class RegularGroupSet extends GroupSet {
+  #start = 1;
+  #end = 1;
+  #step = 1;
+
+  // Construct a RegularGroupSet with args:
+  //  start   The minimum number of chords in the generated groups. Default is 1.
+  //  end     The maximum number of chords in the generated groups. Must be >= start.
+  //          If undefined then uses start. Default is undefined.
+  //  step    Step rate to increase group size by. Must be > 0. Default is 1.
+  constructor(options) {
+    super({ isAbstract: true });
+
+    const defaults = { start: 1, end: undefined, step: 1 };
+    options = { ...defaults, ...options };
+    let { start, end, step } = options;
+
+    if (end === undefined) end = start;
+
+    if (1 > start || start > Group.MAX_LENGTH)
+      throw new Error(
+        `Invalid group minimum length - must be from 1 to ${Group.MAX_LENGTH}`
+      );
+    if (1 > end || end > Group.MAX_LENGTH)
+      throw new Error(
+        `Invalid group maximum length - must be from 1 to ${Group.MAX_LENGTH}`
+      );
+    if (end < start)
+      throw new Error(
+        "Invalid group maximum length - can't be less than the minimum length"
+      );
+    if (1 > step || step > Group.MAX_LENGTH)
+      throw new Error(
+        `Invalid step size - must be from 1 to ${Group.MAX_LENGTH - 1}`
+      );
+
+    this.#start = start;
+    this.#end = end;
+    this.#step = step;
+  }
+
+  // Overide Set.clone.
+  clone() {
+    let clone = new this.constructor(
+      { 
+        start: this.#start, 
+        end: this.#end, 
+        step: this.#step 
+      }
+    );
+
+    return clone;
+  }
+
+  get start() {
+    return this.#start;
+  }
+
+  get end() {
+    return this.#end;
+  }
+
+  get step() {
+    return this.#step;
+  }
+
+  get [Symbol.toStringTag]() {
+    return "RegularGroupSet";
+  }
+
+  [util.inspect.custom](depth, opts) {
+    let groups = "";
+
+    for (const group of this) {
+      groups += (groups.length == 0 ? "" : ", ") + util.inspect(group);
+    }
+
+    return `${this[Symbol.toStringTag]} {[${groups}]}`;
+  }
+
+  *[Symbol.iterator]() {
+    for (let length = this.#start; length <= this.#end; length += this.#step) {
+      yield new Group(0xffffffff, length);
+    }
+  }
+
+  elementAt(index = 0) {
+    if (index >= 0 && index < this.size) {
+      return new Group(0xffffffff, this.#start + this.#step * index);
+    }
+
+    throw new Error("Invalid index");
+  }
+
+  get size() {
+    return Math.floor((this.end - this.start) / this.step + 1);
+  }
+
+  // Returns whether the given element exists in this Set.
+  has(element) {
+    if (element === undefined || !(element instanceof Group)) {
+      throw new Error("Argument must be a Group");
+    }
+
+    const length = element.length;
+
+    if (length < this.start || this.end < length) return false;
+
+    return (length === this.start) || ((length - this.start) % this.step === 0);
+  }
+}

package/src/schedule.mjs

@@ -0,0 +1,88 @@
+// Schedule.
+//
+// A schedule is a set of patterns and/or pattern sets and an associated duration.
+// A schedule may be enumerated so that each pattern it contains is returned, with
+// PatternSets being- expanded into the Patterns they contain.
+//
+// The duration is used by Schema to calculate the duration of each chord in each
+// pattern.
+
+import util from "util";
+import Fraction from "fraction.js"
+
+import { Set } from "./set.mjs";
+import { Pattern } from "./pattern.mjs";
+import { PatternSet } from "./patternset.mjs";
+
+export class Schedule extends Set {
+  #duration;
+
+  // Construct a Schedule.
+  //
+  // options may contain the usual Set options, as well as:
+  //  duration    A Fraction specifying the duration of the schedule.
+  constructor(options = {}) {
+    const defaults = { duration: new Fraction(1, 4), patterns: undefined };
+    options = { ...defaults, ...options, allowDuplicates: true, isAbstract: false };
+
+    super(options);
+
+    this.#duration = options.duration;
+  }
+
+  get allowedElements() {
+    return [ Pattern, PatternSet ];
+  }
+
+  get [Symbol.toStringTag]() {
+    return "Schedule";
+  }
+
+  #describe() {
+    let description = "";
+
+    for (let patterns of this) {
+      description += util.inspect(patterns);
+    }
+
+    return description;
+  }
+
+  [util.inspect.custom](depth, opts) {
+    return `${this[Symbol.toStringTag]} {${this.#duration.toString()}, {${this.#describe()}}}`;
+  }
+
+  get duration() {
+    return this.#duration;
+  }
+
+  // Returns the total number of Patterns in the Schedule (PatternSets are expanded).
+  // NOTE: size still returns the number of elements (Pattens and PatternSets) in
+  // the Schedule.
+  get length() {
+    let length = 0;
+
+    for (let pattern of this) {
+      if (pattern instanceof Pattern) {
+        length++;
+      } else {
+        length += pattern.size
+      }
+    }
+
+    return length;
+  }
+
+  // Iterate over each element, yielding each Pattern (PatternSets are expanded).
+  *#patternGenerator() {
+    for (let pattern of this) {
+      if (pattern instanceof Pattern) {
+        yield pattern;
+      } else {
+        yield* pattern;
+      }
+    }
+  }
+
+  get patterns() { return this.#patternGenerator(); }
+}

package/src/schema.mjs

@@ -0,0 +1,108 @@
+// Schema.
+//
+// A schema is a sequence of schedules to be played in order. It allows each permutation
+// of the sequence to be enumerated, and each such generator to be iterated to obtain the 
+// resultant sequece of chord/duration that expresses the permutation.
+
+import { Set } from "./set.mjs";
+import { Schedule } from "./schedule.mjs";
+
+export class Schema extends Set {
+  #timeSignature;   // Fraction indicating the time signature of the piece.
+
+  constructor(options = {}) {
+    const defaults = { timeSignature: [ 4, 4 ] };
+    options = { ...defaults, ...options, allowDuplicates: true, isAbstract: false };
+
+    super(options);
+
+    this.#timeSignature = options.timeSignature;
+  }
+
+  get allowedElements() {
+    return [ Schedule ];
+  }
+
+  get [Symbol.toStringTag]() {
+    return "Schema";
+  }
+
+  get timeSignature() {
+    return this.#timeSignature;
+  }
+
+  // Returns the total number of expressions in the Schema.
+  get length() {
+    let length = 0;
+    let scheduleLength = 0;
+
+    for (let schedule of this) {
+      scheduleLength = schedule.length;
+
+      if (scheduleLength > 0) {
+        length = length === 0 ? scheduleLength : length * scheduleLength;
+      }
+    }
+
+    return length;
+  }
+
+  // Return a generator that yields each chord and its duration for the patterns in an 
+  // expression instance, as an object of the form:
+  //
+  // {
+  //   chord: <chord>
+  //   duration: <duration>
+  // }
+  *#patternGenerator(patterns) {
+    for (let schedule of patterns) {
+      const duration = schedule.duration;
+      const pattern = schedule.patterns.next().value;
+      const numChords = pattern.size;
+
+      if (numChords > 0) {
+        const chordDuration = duration.div(numChords);
+
+        for (let chord of pattern) {
+          yield { chord: chord, duration: chordDuration };
+        }
+      }
+    }
+  }
+
+  // Recursively returns a generator that yields each expression of the schedules in the schema.
+  *#expressionGenerator(schedules, index, patterns) {
+    const schedule = schedules[index];
+
+    let nextPatterns;
+
+    for (let pattern of schedule.patterns) {
+      nextPatterns = [ ...patterns, (new Schedule({duration: schedule.duration})).add(pattern)];
+
+      if (index == schedules.length - 1) {
+        yield this.#patternGenerator(nextPatterns)
+      } else {
+        yield* this.#expressionGenerator(schedules, index + 1, nextPatterns);
+      }
+    }
+  }
+
+   // Returns a generator that yields each expression of the schedules in the schema.
+   *#expressionsGenerator() {
+    let schedules = [];
+
+    for (let schedule of this) {
+      let length = schedule.length;
+
+      if (length > 0) {
+        schedules.push(schedule);
+      }
+    }
+
+    if (schedules.length > 0) {
+      yield* this.#expressionGenerator(schedules, 0, []);
+    }
+  }
+
+  get expressions() { return this.#expressionsGenerator(); }
+}