@goplayerjuggler/abc-tools 1.0.24 → 1.1.0

package/README.md

@@ -1,16 +1,20 @@
 # abc-tools
-
 A JavaScript library with utility functions for tunes written in ABC format. Particularly applicable to Irish, and other, traditional music.
+
 # features
 * contour sort algorithm
 Sorts tunes by their contour, independent of key and mode. 
 The algorithm used for sorting is new/original, as far as I know, and is described [here](./docs/contour_sort.md) 
+* contour visualisations as SVGs
 * Extracting initial bars and incipits
 * Doubling/halving bar length - e.g. going from 4/4 to 4/2 and vice versa
-  This is work in progress; still quite buggy.
+  This is work in progress; it has a few small bugs but is still useable.
 
-# about this project
-Writing up the sort algorithm, its implementation along with implementation of other features, and the project setup, were all done with the help of Claude.ai and github copilot.
+# where is it used
+AFAIK at present this is only used by one other repo; a project of mine, [tuneTable](https://github.com/goplayerjuggler/tuneTable), which builds on this repo. There’s a [live demo](https://goplayerjuggler.github.io/tuneTable) featuring the contour sort - it sorts first by rhythm, then by contour.
+
+# AI
+A lot of the implementation was done with the help of AI, notably with Anthropic’s Claude.ai / Sonnet 4.6.
 
 ## license
 
@@ -24,7 +28,6 @@ This means you are free to use, modify, and distribute this software, but any de
 npm i @goplayerjuggler/abc-tools
 ```
 
-
 ## contributing
 
 Issues and pull requests welcome at https://github.com/goplayerjuggler/abc-tools

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@goplayerjuggler/abc-tools",
-  "version": "1.0.24",
-  "description": "sorting algorithm and implementation for ABC tunes; plus other tools for parsing and manipulating ABC tunes",
+  "version": "1.1.0",
+  "description": "contour-sort and other sorting algorithms implementation for ABC tunes; and other tools for parsing and manipulating ABC tunes",
   "main": "src/index.js",
   "scripts": {
     "test": "jest",
@@ -16,8 +16,9 @@
     "LICENSE"
   ],
   "keywords": [
-    "abc",
-    "folk",
+    "abc-notation",
+    "folk-music",
+    "graphical-score",
     "irish",
     "melody",
     "modal",
@@ -25,7 +26,7 @@
     "parsing",
     "sort",
     "sorting",
-    "traditional",
+    "traditional-music",
     "tune"
   ],
   "author": "Malcolm Schonfield",

package/src/incipit.js

@@ -283,34 +283,38 @@ function getIncipit(data) {
 
 	const { withAnacrucis = true } =
 		typeof data === "string" ? { abc: data } : data;
-
+	let countAnacrucisInTotal = false;
 	if (!numBars) {
 		numBars = 2;
 		const currentMeter = getMeter(abc);
 		const unitLength = getUnitLength(abc);
 		if (!currentMeter) numBars = 2;
 		else if (
+			currentMeter[0] === 4 &&
+			currentMeter[1] === 2 &&
+			unitLength.den === 8
+		) {
+			numBars = 1; //hornpipes
+			countAnacrucisInTotal = true; //otherwise it seems a bit too long
+		} else if (
 			(currentMeter[0] === 4 &&
 				currentMeter[1] === 4 &&
 				unitLength.den === 16) ||
-			(currentMeter[0] === 4 &&
-				currentMeter[1] === 2 &&
-				unitLength.den === 8) ||
-			(currentMeter[0] === 12 && currentMeter[1] === 8)
-		) {
+			(currentMeter[0] === 12 && currentMeter[1] === 8) ||
+			(currentMeter[0] >= 12 && currentMeter[0] < 16)
+		)
 			numBars = new Fraction(3, 2);
-		} else if (currentMeter[0] === 3 && currentMeter[1] === 4) {
+		else if (currentMeter[0] === 3 && [4, 8].indexOf(currentMeter[1]) >= 0)
 			numBars = 3;
-		}
+		else if (currentMeter[0] >= 16) numBars = 1;
 	}
 	abc = sanitise(abc);
-	return getFirstBars(abc, numBars, withAnacrucis, false, { all: true });
+	return getFirstBars(abc, numBars, withAnacrucis, countAnacrucisInTotal, {
+		all: true
+	});
 }
 
-function getIncipitForContourGeneration(
-	abc,
-	{ numBars = new Fraction(2, 1) } = {}
-) {
+function getIncipitForContourGeneration(abc, { numBars = null } = {}) {
 	return getIncipit({
 		abc,
 		withAnacrucis: false,

package/src/index.js

@@ -1,12 +1,9 @@
-/**
- * ABC Music Toolkit
- * Main entry point for ABC parsing, manipulation, and sorting
- */
-
 const parser = require("./parse/parser.js");
 const miscParser = require("./parse/misc-parser.js");
 const manipulator = require("./manipulator.js");
-const sort = require("./sort/contour-sort.js");
+const sort = require("./sort/sort.js");
+const sortConstants = require("./sort/sort-constants.js");
+const { compare } = require("./sort/contour-sort.js");
 const contourToSvg = require("./sort/contour-svg.js");
 const displayContour = require("./sort/display-contour.js");
 
@@ -18,18 +15,20 @@ const { getBarInfo } = require("./parse/getBarInfo.js");
 const { getMetadata } = require("./parse/getMetadata.js");
 
 module.exports = {
-	// Parser functions
+	// Get info
 	...parser,
 	...miscParser,
 	getBarInfo,
 	getMetadata,
 	...incipit,
 
-	// Manipulator functions
+	// change things
 	...manipulator,
 
-	// Sort functions
+	// Sort
 	...sort,
+	...sortConstants,
+	compareContour: compare,
 	...displayContour,
 	...contourToSvg,
 	...getContour,

package/src/manipulator.js

@@ -725,6 +725,30 @@ function convertStandardHornpipe(
 	}
 	return result;
 }
+
+/**
+ * Doubles the bar length of an ABC string when the
+ * ABC is eligible (as determined by canDoubleBarLength()).
+ * @param {string} abc
+ * @param {string} rhythm
+ * @returns {string}
+ */
+function maybeConvertStandardTune(abc, rhythm) {
+	if (!canDoubleBarLength(abc, { rhythm })) return abc;
+	switch (rhythm) {
+		case "reel":
+			return convertStandardReel(abc);
+		case "jig":
+			return convertStandardJig(abc);
+		case "polka":
+			return convertStandardPolka(abc);
+		case "hornpipe":
+			return convertStandardHornpipe(abc);
+		default:
+			return abc;
+	}
+}
+
 function doubleBarLength(abc, comment = null) {
 	const meter = getMeter(abc);
 	if (!Array.isArray(meter) || !meter) {
@@ -1061,10 +1085,12 @@ function getFirstBars(
 	)}`;
 }
 
-function canDoubleBarLength(abc) {
-	const meter = getMeter(abc),
+function canDoubleBarLength(abc, info = {}) {
+	const {
+		meter = getMeter(abc),
 		l = getUnitLength(abc),
-		rhythm = getHeaderValue(abc, "R");
+		rhythm = getHeaderValue(abc, "R")
+	} = info;
 	if (
 		!rhythm ||
 		["reel", "hornpipe", "jig", "polka"].indexOf(rhythm.toLowerCase()) < 0
@@ -1125,6 +1151,7 @@ module.exports = {
 	filterHeaders,
 	getFirstBars,
 	hasAnacrucis,
+	maybeConvertStandardTune,
 	normaliseKey,
 	toggleMeter_4_4_to_4_2,
 	toggleMeter_6_8_to_12_8,

package/src/sort/contour-sort.js

@@ -1,4 +1,3 @@
-const { getIncipitForContourGeneration } = require("../incipit.js");
 const { Fraction } = require("../math.js");
 
 const { decodeChar, encodeToChar, silenceChar } = require("./encode.js");
@@ -176,100 +175,6 @@ function canBeCompared(tune1, tune2) {
 	return true;
 }
 
-function getAbcForContour_default(tune) {
-	return getIncipitForContourGeneration(
-		tune.incipit
-			? tune.incipit
-			: Array.isArray(tune.abc)
-				? tune.abc[0]
-				: tune.abc
-	);
-}
-
-/**
- * Sort an array of objects containing ABC notation
- * - based on a contour property
- * - when the contour is missing, attempts to generate it
- * - adds info to each object like the contour, the type of rhythm
- * @param {Array<Object>} arr - array of tune objects to sort
- * @param {Object} [options] - options for the sorting
- * @param {function(Object):string} [options.getAbc] - function returning an abc fragment to be used to calculate the contour.
- */
-function sort(arr, options = {}) {
-	const {
-		comparable = [
-			["jig", "slide", "single jig", "double jig"],
-			["reel", "single reel", "reel (single)", "strathspey", "double reel"],
-			["hornpipe", "barndance", "fling"]
-		],
-		applySwingTransform = ["hornpipe", "barndance", "fling", "mazurka"],
-		getAbc: getAbcForContour = getAbcForContour_default,
-		getContourOptions = () => {
-			return {
-				withSvg: true
-			};
-		}
-	} = options;
-
-	const comparableMap = {};
-	//set up comparableMap s.t. all entries in each list of index i go under i_<first entry of i>
-	//that way we show the jigs with similar rhythms followed by reels etc.
-	for (let i = 0; i < comparable.length; i++) {
-		const list = comparable[i];
-		//map subsequent entries to the first entry
-		for (let j = 0; j < list.length; j++) {
-			comparableMap[list[j]] = `${i}_${list[0]}`;
-		}
-	}
-
-	for (const tune of arr) {
-		if (!tune.contour) {
-			try {
-				const contourOptions = getContourOptions();
-				// if (
-				// 	tune.title?.indexOf("oldrick") >= 0 ||
-				// ) {
-				// 	console.log("debug");
-				// }
-				const withSwingTransform =
-					applySwingTransform.indexOf(tune.rhythm) >= 0;
-				const shortAbc = getAbcForContour(tune);
-
-				if (shortAbc) {
-					contourOptions.withSwingTransform = withSwingTransform;
-					if (Object.hasOwn(tune, "contourShift"))
-						contourOptions.contourShift = tune.contourShift;
-					tune.contour = getContour(shortAbc, contourOptions);
-				}
-			} catch (error) {
-				console.log(error);
-			}
-		}
-		if (!tune.baseRhythm)
-			tune.baseRhythm = comparableMap[tune.rhythm] ?? tune.rhythm;
-	}
-	arr.sort((a, b) => {
-		const comparison =
-			a.baseRhythm !== b.baseRhythm
-				? a.baseRhythm < b.baseRhythm
-					? -1
-					: 1
-				: canBeCompared(a, b)
-					? compare(a.contour, b.contour)
-					: a.contour && !b.contour
-						? -1
-						: b.contour && !a.contour
-							? 1
-							: a.name !== b.name
-								? a.name < b.name
-									? -1
-									: 1
-								: 0;
-		return comparison;
-	});
-	arr.forEach((t) => delete t.baseRhythm);
-}
-
 function simpleSort(arr) {
 	for (const item of arr) {
 		if (!item.contour && item.abc) {
@@ -304,7 +209,7 @@ function simpleSort(arr) {
 
 module.exports = {
 	compare,
-	sort,
+	canBeCompared,
 	simpleSort,
 	decodeChar
 };

package/src/sort/sort-constants.js

@@ -0,0 +1,52 @@
+const DEFAULT_METER_SORT_SPECS = [
+	[
+		{ meters: [[2], [4], [8]] },
+		{
+			meters: [
+				[6, 2],
+				[6, 4]
+			],
+			unitLengths: [
+				[1, 8],
+				[1, 16]
+			]
+		}
+	],
+	[{ meters: [[3]] }],
+	[{ meters: [[6], [12]] }],
+	[{ meters: [[9], [18]] }],
+	[{ meters: [[5], [10]] }],
+	[{ meters: [[7], [14]] }],
+	[{ meters: [[11], [13]] }]
+];
+
+const DEFAULT_RHYTHM_GROUPS = [
+	["jig", "slide", "single jig", "double jig"],
+	["reel", "single reel", "reel (single)", "strathspey", "double reel"],
+	["hornpipe", "barndance", "fling"]
+];
+const DEFAULT_NAME_PREFIXES = [
+	"The ",
+	"A ",
+	"An ",
+	/(?:(?:la )?(?:marche |bourrée |valse )|(?:le )?reel )(?:du |de la |de |à |des )?/i
+];
+
+const DEFAULT_CONTOUR_OPTIONS = {
+	withSvg: true,
+	swingTransform: ["hornpipe", "barndance", "fling", "mazurka"],
+	incipitPart: "A"
+};
+const PREDEFINED_SORT_NAMES = [
+	"rhythmContourName",
+	"meterContourName",
+	"nameContour"
+];
+const sortConstants = {
+	DEFAULT_CONTOUR_OPTIONS,
+	DEFAULT_METER_SORT_SPECS,
+	DEFAULT_NAME_PREFIXES,
+	DEFAULT_RHYTHM_GROUPS,
+	PREDEFINED_SORT_NAMES
+};
+module.exports = { sortConstants };

package/src/sort/sort.js

@@ -0,0 +1,287 @@
+const { compare, canBeCompared } = require("./contour-sort.js");
+const { getContour } = require("./get-contour.js");
+const { getIncipitForContourGeneration } = require("../incipit.js");
+const { getMeter, getUnitLength } = require("../parse/parser.js");
+const { sortConstants } = require("./sort-constants.js");
+
+/// Returns the tune's meter as [n, d], or null. Uses cached _sortAbc.
+function resolveMeter(tune) {
+	if (!tune._sortMeter) {
+		if (tune.meter !== undefined)
+			tune._sortMeter =
+				tune.meter instanceof String
+					? tune.meter?.split("/")
+					: Array.isArray(tune.meter) && tune.meter?.length
+						? tune.meter
+						: null;
+		const abc = tune._sortAbc;
+		if (!abc) tune._sortMeter = null;
+		const m = getMeter(abc);
+		tune._sortMeter = m?.length ? m : null;
+	}
+	return tune._sortMeter;
+}
+
+/// Returns the tune's unit length as a Fraction, or null. Uses cached _sortAbc.
+function resolveUnitLength(tune) {
+	if (tune.unitLength !== undefined) return tune.unitLength;
+	try {
+		return tune._sortAbc ? getUnitLength(tune._sortAbc) : null;
+	} catch {
+		return null;
+	}
+}
+///Returns true if the given meter (and optionally unit length) satisfies one MeterSortSpec entry.
+function meterMatchesSpec(meter, unitLength, spec) {
+	if (!meter) return false;
+	const [n, d] = meter;
+	const meterMatches = spec.meters.some(
+		([sn, sd]) => sn === n && (sd === undefined || sd === d)
+	);
+	if (!meterMatches) return false;
+	if (!spec.unitLengths) return true;
+	if (!unitLength) return false;
+	return spec.unitLengths.some(
+		([un, ud]) => unitLength.num === un && unitLength.den === ud
+	);
+}
+
+///Returns the 0-based index of the first matching group, or meterSortSpecs.length for the fallback group.
+function getMeterGroup(meter, unitLength, meterSortSpecs) {
+	for (let i = 0; i < meterSortSpecs.length; i++) {
+		if (
+			meterSortSpecs[i].some((spec) =>
+				meterMatchesSpec(meter, unitLength, spec)
+			)
+		)
+			return i;
+	}
+	return meterSortSpecs.length;
+}
+
+/// Returns the ABC fragment used for contour / meter resolution.
+function getAbc_default(tune) {
+	return getIncipitForContourGeneration(
+		tune.incipit
+			? tune.incipit
+			: Array.isArray(tune.abc)
+				? tune.abc[0]
+				: tune.abc
+	);
+}
+
+function ensureContour(tune, contourOptions) {
+	if (tune.contour) return;
+	const {
+		swingTransform = sortConstants.DEFAULT_CONTOUR_OPTIONS.swingTransform,
+		incipitPart = "A",
+		...getContourOpts
+	} = contourOptions;
+
+	if (incipitPart !== "A")
+		throw new Error(`incipitPart "${incipitPart}" is not yet implemented`);
+
+	try {
+		const shortAbc = tune._sortAbc;
+		if (!shortAbc) return;
+		getContourOpts.withSwingTransform = swingTransform.includes(tune.rhythm);
+		if (Object.hasOwn(tune, "contourShift"))
+			getContourOpts.contourShift = tune.contourShift;
+		tune.contour = getContour(shortAbc, getContourOpts);
+	} catch (err) {
+		console.error(err);
+	}
+}
+function compareContour(a, b) {
+	if (a.contour && b.contour && canBeCompared(a, b))
+		return compare(a.contour, b.contour);
+	if (a.contour) return -1;
+	if (b.contour) return 1;
+	return 0;
+}
+
+/**
+ * Returns name with any matching prefix stripped, for comparison purposes only.
+ * @param {string} name
+ * @param {(string|RegExp)[]} prefixes
+ */
+function stripPrefix(name, prefixes) {
+	if (!name) return "";
+	for (const p of prefixes) {
+		if (p instanceof RegExp) {
+			const m = name.match(p);
+			if (m && m.index === 0) {
+				return name.slice(m[0].length);
+			}
+		} else {
+			if (name.toLowerCase().startsWith(p.toLowerCase()))
+				return name.slice(p.length);
+		}
+	}
+	return name;
+}
+
+function annotateTunes(tunes, levels) {
+	for (const level of levels) {
+		switch (level.type) {
+			case "rhythm": {
+				const groups =
+					level.rhythmGroups ?? sortConstants.DEFAULT_RHYTHM_GROUPS;
+				const map = {};
+				groups.forEach((g, i) => g.forEach((r) => (map[r] = `${i}_${g[0]}`)));
+				tunes.forEach((t) => (t._sortRhythm = map[t.rhythm] ?? t.rhythm ?? ""));
+				break;
+			}
+
+			case "meter": {
+				const specs =
+					level.meterSortSpecs ?? sortConstants.DEFAULT_METER_SORT_SPECS;
+				const needsUnitLength = specs.some((g) => g.some((s) => s.unitLengths));
+				tunes.forEach((t) => {
+					const meter = resolveMeter(t);
+					const ul = needsUnitLength ? resolveUnitLength(t) : null;
+					t._sortMeterGroup = getMeterGroup(meter, ul, specs);
+					console.log(`${t.name}|${t.meter}|${t._sortMeterGroup}`);
+				});
+				break;
+			}
+
+			case "origin":
+				tunes.forEach((t) => {
+					const raw = t.origin ?? null;
+					t._sortOrigin = raw ? raw.split(";")[0].trim() : null;
+				});
+				break;
+
+			case "name": {
+				const prefixes =
+					level.ignoreNamePrefixes ?? sortConstants.DEFAULT_NAME_PREFIXES;
+				tunes.forEach((t) => {
+					t._sortName = stripPrefix(t.name ?? "", prefixes);
+				});
+				break;
+			}
+
+			case "contour": {
+				const opts =
+					level.contourOptions ?? sortConstants.DEFAULT_CONTOUR_OPTIONS;
+				tunes.forEach((t) => ensureContour(t, opts));
+				break;
+			}
+
+			default:
+				throw new Error(`Unknown sort level type: "${level.type}"`);
+		}
+	}
+}
+
+function makeLevelComparator(level) {
+	const dir = level.order === "desc" ? -1 : 1;
+	const collator =
+		level.type === "name"
+			? new Intl.Collator("en", { sensitivity: "base" })
+			: null;
+	switch (level.type) {
+		case "rhythm":
+			return (a, b) =>
+				a._sortRhythm === b._sortRhythm
+					? 0
+					: dir * (a._sortRhythm < b._sortRhythm ? -1 : 1);
+		case "meter":
+			return (a, b) =>
+				a._sortMeterGroup === b._sortMeterGroup
+					? 0
+					: dir * (a._sortMeterGroup < b._sortMeterGroup ? -1 : 1);
+		case "origin":
+			return (a, b) => {
+				const [oa, ob] = [a._sortOrigin, b._sortOrigin];
+				if (oa === ob) return 0;
+				if (!oa) return 1;
+				if (!ob) return -1;
+				return dir * (oa < ob ? -1 : 1);
+			};
+		case "name":
+			return (a, b) => {
+				const [na, nb] = [a._sortName ?? "", b._sortName ?? ""];
+				return dir * collator.compare(na, nb);
+			};
+		case "contour":
+			return (a, b) => dir * compareContour(a, b);
+		default:
+			throw new Error(`Unknown sort level type: "${level.type}"`);
+	}
+}
+
+function resolveLevels(options) {
+	const {
+		predefinedSort,
+		sortLevels,
+		contourOptions = sortConstants.DEFAULT_CONTOUR_OPTIONS
+	} = options;
+	if (predefinedSort && sortLevels)
+		throw new Error("Cannot specify both predefinedSort and sortLevels");
+	if (sortLevels) return sortLevels;
+
+	const contourLevel = { type: "contour", contourOptions };
+	const nameLevel = { type: "name" };
+
+	switch (predefinedSort ?? "rhythmContourName") {
+		case "rhythmContourName":
+			return [{ type: "rhythm" }, contourLevel, nameLevel];
+		case "meterContourName":
+			return [{ type: "meter" }, contourLevel, nameLevel];
+		case "nameContour":
+			return [nameLevel, contourLevel];
+		default:
+			throw new Error(`Unknown predefinedSort: "${predefinedSort}"`);
+	}
+}
+
+/**
+ * @param {Object[]} tunes - Array of tune objects to sort in-place.
+ * @param {Object}   [options]
+ * @param {function(Object): string} [options.getAbc]
+ *   Returns an ABC fragment for a tune, used for contour generation and for
+ *   resolving meter / unit length when those fields are absent from the tune
+ *   object. Called at most once per tune; result is cached during the sort.
+ *   Defaults to incipit-based extraction.
+ * @param {string}   [options.predefinedSort="rhythmContourName"]
+ *   Name of a predefined sort. One of "rhythmContourName", "meterContourName",
+ *   "nameContour". Mutually exclusive with `sortLevels`.
+ * @param {Object[]} [options.sortLevels]
+ *   Explicit sort-level descriptors. Mutually exclusive with `predefinedSort`.
+ *   Each entry has the shape { type, order?, ...levelOptions } where type is
+ *   one of "rhythm" | "meter" | "origin" | "name" | "contour".
+ * @param {Object}   [options.contourOptions]
+ *   Options forwarded to getContour(). Applied to all contour levels in
+ *   predefined sorts; for custom sortLevels, set contourOptions per level.
+ *   Shape: { withSvg?, swingTransform?, incipitPart?, ...getContourPassthrough }
+ */
+function sort(tunes, options = {}) {
+	const { getAbc = getAbc_default } = options;
+	const levels = resolveLevels(options);
+	const comparators = levels.map(makeLevelComparator);
+
+	tunes.forEach((t) => (t._sortAbc = getAbc(t)));
+	annotateTunes(tunes, levels);
+
+	tunes.sort((a, b) => {
+		for (const cmp of comparators) {
+			const r = cmp(a, b);
+			if (r !== 0) return r;
+		}
+		return 0;
+	});
+
+	const annotationKeys = [
+		"_sortAbc",
+		"_sortRhythm",
+		"_sortMeterGroup",
+		"_sortOrigin",
+		"_sortName",
+		"_sortMeter"
+	];
+	tunes.forEach((t) => annotationKeys.forEach((k) => delete t[k]));
+}
+
+module.exports = { sort };