@goplayerjuggler/abc-tools 1.0.13 → 1.0.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goplayerjuggler/abc-tools",
-  "version": "1.0.13",
+  "version": "1.0.14",
   "description": "sorting algorithm and implementation for ABC tunes; plus other tools for parsing and manipulating ABC tunes",
   "main": "src/index.js",
   "scripts": {

package/src/index.js

@@ -15,12 +15,15 @@ const javascriptify = require("./javascriptify.js");
 const getContour = require("./sort/get-contour.js");
 const math = require("./math.js");
 const { getBarInfo } = require("./parse/getBarInfo.js");
+const { getMetadata } = require("./parse/getMetadata.js");
 
 module.exports = {
 	// Parser functions
 	...parser,
 	...miscParser,
 	getBarInfo,
+	getMetadata,
+	...incipit,
 
 	// Manipulator functions
 	...manipulator,
@@ -31,8 +34,6 @@ module.exports = {
 	...contourToSvg,
 	...getContour,
 
-	// Incipit functions
-	...incipit,
 
 	// other
 	javascriptify,

package/src/manipulator.js

@@ -1,5 +1,5 @@
 const { Fraction } = require("./math.js");
-const { parseAbc, getMeter } = require("./parse/parser.js");
+const { parseAbc, getMeter, getUnitLength } = require("./parse/parser.js");
 
 const { getBarInfo } = require("./parse/getBarInfo.js");
 
@@ -89,28 +89,31 @@ function filterHeaders(headerLines, headersToStrip) {
 }
 
 /**
- * Detect if ABC notation has an anacrusis (pickup bar) from parsed data
+ * Detect if ABC notation has an anacrusis (pickup bar) from parsed data or from barLines array
  * @param {object} parsed - Parsed ABC data from parseAbc
+ * @param {Array<object>} barLines - enriched barLine array from getBarInfo
  * @returns {boolean} - True if anacrusis is present
  */
-function hasAnacrucisFromParsed(parsed) {
-	const { bars, barLines, meter } = parsed;
+function hasAnacrucisFromParsed(parsed, barLines) {
+	const callParse = !barLines;
+	if (callParse) {
+		const { bars, meter } = parsed;
+		if (bars.length === 0) return false;
+		({ barLines } = parsed);
+		// Use getBarInfo to analyse the first bar
+		getBarInfo(bars, barLines, meter, {
+			barNumbers: true,
+			isPartial: true,
+			cumulativeDuration: false,
+		});
+	}
 
-	if (bars.length === 0 || barLines.length === 0) {
+	if (barLines.length === 0) {
 		return false;
 	}
 
-	// Use getBarInfo to analyse the first bar
-	const barInfo = getBarInfo(bars, barLines, meter, {
-		barNumbers: true,
-		isPartial: true,
-		cumulativeDuration: false,
-	});
-
 	// Find the first bar line with a barNumber (skip initial bar line if present)
-	const firstNumberedBarLine = barInfo.barLines.find(
-		(bl) => bl.barNumber !== null
-	);
+	const firstNumberedBarLine = barLines.find((bl) => bl.barNumber !== null);
 
 	if (!firstNumberedBarLine) {
 		return false;
@@ -155,12 +158,12 @@ function hasAnacrucis(abc) {
  * @param {string} abc - ABC notation string
  * @param {Array<number>} smallMeter - The smaller meter signature [numerator, denominator]
  * @param {Array<number>} largeMeter - The larger meter signature [numerator, denominator]
+ * @param {Array<number>} currentMeter - The current meter signature [numerator, denominator] of the abc tune - may be omitted. (If omitted, it gets fetched from `abc`)
  * @returns {string} ABC notation with toggled meter
  * @throws {Error} If the current meter doesn’t match either smallMeter or largeMeter
  */
-
-function toggleMeterDoubling(abc, smallMeter, largeMeter) {
-	const currentMeter = getMeter(abc);
+function toggleMeterDoubling(abc, smallMeter, largeMeter, currentMeter) {
+	if (!currentMeter) currentMeter = getMeter(abc);
 
 	const isSmall =
 		currentMeter[0] === smallMeter[0] && currentMeter[1] === smallMeter[1];
@@ -175,6 +178,10 @@ function toggleMeterDoubling(abc, smallMeter, largeMeter) {
 
 	const parsed = parseAbc(abc);
 	const { headerLines, barLines, musicText, bars, meter } = parsed;
+	// throw if there's a change of meter or unit length in the tune
+	if (barLines.find((bl) => bl.newMeter || bl.newUnitLength)) {
+		throw new Error("change of meter or unit length not handled");
+	}
 
 	// Change meter in headers
 	const newHeaders = headerLines.map((line) => {
@@ -206,22 +213,28 @@ function toggleMeterDoubling(abc, smallMeter, largeMeter) {
 		const barLineDecisions = new Map();
 		const barLinesToConvert = new Map(); // variant markers to convert from |N to [N
 
-		// Map bar numbers to their sequential index among complete bars
-		// This handles cases where bar numbers skip (due to anacrusis or partials)
-		const completeBarIndexByNumber = new Map();
-		let completeBarIndex = 0;
-
-		for (let i = 0; i < barLines.length; i++) {
-			const barLine = barLines[i];
-			if (barLine.barNumber !== null && !barLine.isSectionBreak) {
-				const isCompleteMusicBar =
-					!barLine.isPartial || barLine.completesMusicBar === true;
-				if (isCompleteMusicBar) {
-					completeBarIndexByNumber.set(barLine.barNumber, completeBarIndex);
-					completeBarIndex++;
-				}
-			}
-		}
+		//Discarded
+		// // Map bar numbers to their sequential index among complete bars
+		// // This handles cases where bar numbers skip (due to anacrusis or partials)
+		// const completeBarIndexByNumber = new Map();
+		// let completeBarIndex = 0;
+
+		// for (let i = 0; i < barLines.length; i++) {
+		// 	const barLine = barLines[i];
+		// 	if (
+		// 		barLine.barNumber !== null
+		// 		//&& !barLine.isSectionBreak
+		// 	) {
+		// 		const isCompleteMusicBar =
+		// 			!barLine.isPartial || barLine.completesMusicBar === true;
+		// 		if (isCompleteMusicBar) {
+		// 			completeBarIndexByNumber.set(barLine.barNumber, completeBarIndex);
+		// 			completeBarIndex++;
+		// 		}
+		// 	}
+		// }
+
+		const hasAnacrucis = hasAnacrucisFromParsed(null, barLines);
 
 		for (let i = 0; i < barLines.length; i++) {
 			const barLine = barLines[i];
@@ -262,11 +275,17 @@ function toggleMeterDoubling(abc, smallMeter, largeMeter) {
 				continue;
 			}
 
-			// This is a complete bar - use its index to decide
-			// Remove even-indexed complete bars (0th, 2nd, 4th...), keep odd-indexed (1st, 3rd, 5th...)
-			const index = completeBarIndexByNumber.get(barLine.barNumber);
-			if (index !== undefined && index % 2 === 0) {
-				// This is 0th, 2nd, 4th... complete bar - remove it
+			// This is a complete bar - use its barNumber to decide
+			// Without anacrucis: Remove complete bars with even barNumber (0, 2, 4, ...), keep odd ones (1, 3, 5, ...)
+			// With anacrucis: the other way round!
+
+			//Discarded
+			// const index = completeBarIndexByNumber.get(barLine.barNumber);
+			// if (index !== undefined && index % 2 === 0) {
+			const remove = hasAnacrucis
+				? barLine.barNumber % 2 !== 0
+				: barLine.barNumber % 2 === 0;
+			if (remove) {
 				const nextBarIdx = i + 1;
 				if (nextBarIdx < bars.length && barStartsWithVariant.has(nextBarIdx)) {
 					const variantToken = barStartsWithVariant.get(nextBarIdx);
@@ -358,8 +377,84 @@ function toggleMeterDoubling(abc, smallMeter, largeMeter) {
  * This is a true inverse operation - going there and back preserves the ABC exactly
  * Handles anacrusis correctly and preserves line breaks
  */
-function toggleMeter_4_4_to_4_2(abc) {
-	return toggleMeterDoubling(abc, [4, 4], [4, 2]);
+function toggleMeter_4_4_to_4_2(abc, currentMeter) {
+	return toggleMeterDoubling(abc, [4, 4], [4, 2], currentMeter);
+}
+
+const defaultCommentForReelConversion =
+	"*abc-tools: convert reel to M:4/4 & L:1/16*";
+/**
+ * Adjusts bar lengths and L field to convert a
+ * reel written in the normal way (M:4/4 L:1/8) to the same reel
+ * written with M:4/4 L:1/16.
+ * Bars are twice as long, and the quick notes are semiquavers
+ * rather than quavers.
+ * @param {string} reel
+ * @param {string} comment - when non falsey, the comment will be injected as an N: header
+ * @param {bool} withSemiquavers - when unflagged, the L stays at 1/8, and the M is 4/2
+
+ * @returns
+ */
+function convertStandardReel(
+	reel,
+	comment = defaultCommentForReelConversion,
+	withSemiquavers = true
+) {
+	const meter = getMeter(reel);
+	if (!Array.isArray(meter) || !meter || !meter[0] === 4 || !meter[1] === 4) {
+		throw new Error("invalid meter");
+	}
+	const unitLength = getUnitLength(reel);
+	if (unitLength.den !== 8) {
+		throw new Error("invalid L header");
+	}
+
+	let result = //toggleMeter_4_4_to_4_2(reel, meter);
+		toggleMeterDoubling(reel, [4, 4], [4, 2], meter);
+	if (comment) {
+		result = result.replace(/(\nK:)/, `\nN:${comment}$1`);
+	}
+	if (withSemiquavers) {
+		result = result.replace("M:4/2", "M:4/4").replace("L:1/8", "L:1/16");
+	}
+	return result;
+}
+
+/**
+ * Adjusts bar lengths and L field to convert a
+ * reel written in the abnormal way (M:4/4 L:1/16) to the same reel
+ * written with M:4/4 L:1/8, the normal or standard way.
+ * Bars are half as long, and the quick notes are quavers
+ * rather than semiquavers. Inverse operation to convertStandardReel
+ * @param {string} reel
+ * @param {string} comment - when non falsey, the comment (as an N:) will removed from the header
+ * @param {bool} withSemiquavers - when unflagged, the original reel was written in M:4/2 L:1/8
+ * @returns
+ */
+function convertToStandardReel(
+	reel,
+	comment = defaultCommentForReelConversion,
+	withSemiquavers = true
+) {
+	if (withSemiquavers) {
+		reel = reel.replace("M:4/4", "M:4/2").reel("L:1/16", "L:1/8");
+	}
+
+	const unitLength = getUnitLength(reel);
+	if (unitLength.den !== 8) {
+		throw new Error("invalid L header");
+	}
+	const meter = getMeter(reel);
+	if (!Array.isArray(meter) || !meter || !meter[0] === 4 || !meter[1] === 4) {
+		throw new Error("invalid meter");
+	}
+
+	let result = // toggleMeter_4_4_to_4_2(reel, meter);
+		toggleMeterDoubling(reel, [4, 4], [4, 2], meter);
+	if (comment) {
+		result = result.replace(`\nN:${comment}`, "");
+	}
+	return result;
 }
 
 /**
@@ -578,10 +673,14 @@ function getFirstBars(
 }
 
 module.exports = {
+	convertStandardReel,
+	convertToStandardReel,
+	defaultCommentForReelConversion,
+	filterHeaders,
 	getFirstBars,
 	hasAnacrucis,
+	normaliseKey,
 	toggleMeter_4_4_to_4_2,
 	toggleMeter_6_8_to_12_8,
-	filterHeaders,
-	normaliseKey,
+	toggleMeterDoubling,
 };

package/src/parse/getBarInfo.js

@@ -1,10 +1,24 @@
 const { Fraction } = require("../math.js");
 
+/**
+ * Enriches skipped barLines with information from the preceding barLine
+ *
+ * When consecutive barLines occur with no notes between them (e.g., `:|` followed by `|:`),
+ * the intermediate barLines are skipped during processing. This function copies relevant
+ * properties (barNumber, isPartial, cumulativeDuration, etc.) from the preceding barLine
+ * to ensure skipped barLines have complete information.
+ *
+ * Properties in the skipped barLine (like text, sourceIndex, isSectionBreak) are preserved,
+ * while missing properties are filled in from the preceding barLine.
+ *
+ * @param {Array<Object>} barLines - Array of barLine objects
+ * @param {Array<number>} skippedBarLineIndexes - Indices of barLines that were skipped
+ */
 function processSkippedBarLines(barLines, skippedBarLineIndexes) {
 	for (let i = 0; i < skippedBarLineIndexes.length; i++) {
 		const skippedIndex = skippedBarLineIndexes[i];
-		if (skippedIndex === 0) continue; //don't see how this can happen, but seems best to check
-		//copy any properties in the preceding barLine not in the skipped barLine over to the skipped barLine
+		if (skippedIndex === 0) continue; // Initial barLine can’t inherit from predecessor
+		// Copy any properties from the preceding barLine not already in the skipped barLine
 		barLines[skippedIndex] = {
 			...barLines[skippedIndex - 1],
 			...barLines[skippedIndex],

package/src/parse/getMetadata.js

@@ -0,0 +1,50 @@
+const { normaliseKey } = require("../manipulator");
+
+/**
+ * Extracts data in the ABC header T R C M K S F D N fields
+ * and returns it in a object with properties: title, rhythm, composer, meter, key,
+ * source, url, recording, and comments.
+ * Minimal parsing, but a few features:
+ * - only extracts the first T title; subsequent T entries are ignored
+ * - the key is normalised, so C, Cmaj, C maj, C major will all map to key:"C major"
+ * - the comments go in an array, with one array entry per N: line.
+ * @param {*} abc
+ * @returns {object} - The header info
+ */
+function getMetadata(abc) {
+	const lines = abc.split("\n"),
+		metadata = {},
+		comments = [];
+
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (trimmed.startsWith("T:") && !metadata.title) {
+			metadata.title = trimmed.substring(2).trim();
+		} else if (trimmed.startsWith("R:")) {
+			metadata.rhythm = trimmed.substring(2).trim().toLowerCase();
+		} else if (trimmed.startsWith("C:")) {
+			metadata.composer = trimmed.substring(2).trim().toLowerCase();
+		} else if (trimmed.startsWith("M:")) {
+			metadata.meter = trimmed.substring(2).trim();
+		} else if (trimmed.startsWith("K:")) {
+			metadata.key = normaliseKey(trimmed.substring(2).trim()).join(" ");
+			// metadata.indexOfKey = i
+			break;
+		} else if (trimmed.startsWith("S:")) {
+			metadata.source = trimmed.substring(2).trim();
+		} else if (trimmed.startsWith("F:")) {
+			metadata.url = trimmed.substring(2).trim();
+		} else if (trimmed.startsWith("D:")) {
+			metadata.recording = trimmed.substring(2).trim();
+		} else if (trimmed.startsWith("N:")) {
+			comments.push(trimmed.substring(2).trim());
+		}
+	}
+	if (comments.length > 0) {
+		metadata.comments = comments;
+	}
+
+	return metadata;
+}
+
+module.exports = { getMetadata };