@goplayerjuggler/abc-tools 1.0.11 → 1.0.12

package/package.json

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

package/src/incipit.js

@@ -308,7 +308,7 @@ function getIncipit(data) {
 
 function getIncipitForContourGeneration(
 	abc,
-	{ numBars = new Fraction(3, 2) } = {}
+	{ numBars = new Fraction(2, 1) } = {}
 ) {
 	return getIncipit({
 		abc,

package/src/index.js

@@ -4,6 +4,7 @@
  */
 
 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 contourToSvg = require("./sort/contour-svg.js");
@@ -12,10 +13,12 @@ const displayContour = require("./sort/display-contour.js");
 const incipit = require("./incipit.js");
 const javascriptify = require("./javascriptify.js");
 const getContour = require("./sort/get-contour.js");
+const math = require("./math.js");
 
 module.exports = {
 	// Parser functions
 	...parser,
+	...miscParser,
 
 	// Manipulator functions
 	...manipulator,
@@ -29,6 +32,7 @@ module.exports = {
 	// Incipit functions
 	...incipit,
 
-	//
+	// other
 	javascriptify,
+	...math,
 };

package/src/manipulator.js

@@ -156,7 +156,7 @@ function hasAnacrucis(abc) {
  * @param {Array<number>} smallMeter - The smaller meter signature [numerator, denominator]
  * @param {Array<number>} largeMeter - The larger meter signature [numerator, denominator]
  * @returns {string} ABC notation with toggled meter
- * @throws {Error} If the current meter doesn't match either smallMeter or largeMeter
+ * @throws {Error} If the current meter doesn’t match either smallMeter or largeMeter
  */
 function toggleMeterDoubling(abc, smallMeter, largeMeter) {
 	const currentMeter = getMeter(abc);
@@ -307,7 +307,7 @@ function toggleMeterDoubling(abc, smallMeter, largeMeter) {
 					decision.action === "remove" &&
 					!decision.variantToken
 				) {
-					// Remove bar line and ensure there's a space
+					// Remove bar line and ensure there’s a space
 					// Check if we already added a space (last char in newMusic)
 					const needsSpace =
 						newMusic.length === 0 || newMusic[newMusic.length - 1] !== " ";
@@ -393,7 +393,7 @@ function getFirstBars(
 	countAnacrucisInTotal = false,
 	headersToStrip
 ) {
-	// Convert numBars to Fraction if it's a number
+	// Convert numBars to Fraction if it’s a number
 	const numBarsFraction =
 		typeof numBars === "number" ? new Fraction(numBars) : numBars;
 
@@ -423,7 +423,7 @@ function getFirstBars(
 
 	const enrichedBarLines = barInfo.barLines;
 
-	// Detect if there's an anacrusis
+	// Detect if there’s an anacrusis
 	const firstNumberedBarLine = enrichedBarLines.find(
 		(bl) => bl.barNumber !== null
 	);
@@ -439,10 +439,10 @@ function getFirstBars(
 	const expectedBarDuration = new Fraction(meter[0], meter[1]);
 	const targetDuration = expectedBarDuration.multiply(numBarsFraction);
 
-	// Determine starting position
+	// Determine starting position and how much duration we need to accumulate
 	let startPos = 0;
-	let targetBarNumber = 0;
-	let durationToAccumulate = targetDuration.clone();
+	let remainingDurationNeeded = targetDuration.clone();
+	let countingFromBarNumber = 0;
 
 	if (hasPickup) {
 		if (withAnacrucis) {
@@ -456,13 +456,13 @@ function getFirstBars(
 				if (anacrusisBarLine && anacrusisBarLine.cumulativeDuration) {
 					const anacrusisDuration =
 						anacrusisBarLine.cumulativeDuration.sinceLastBarLine;
-					durationToAccumulate =
-						durationToAccumulate.subtract(anacrusisDuration);
+					remainingDurationNeeded =
+						remainingDurationNeeded.subtract(anacrusisDuration);
 				}
-				targetBarNumber = 1; // Start counting from first complete bar
+				countingFromBarNumber = 1; // Start counting from first complete bar
 			} else {
-				// Don't count anacrusis - we want full numBars after it
-				targetBarNumber = 1;
+				// Don’t count anacrusis - we want full numBars after it
+				countingFromBarNumber = 1;
 			}
 		} else {
 			// Skip anacrusis - start after its bar line
@@ -473,42 +473,43 @@ function getFirstBars(
 				const anacrusisBarLine = enrichedBarLines[anacrusisBarLineIdx];
 				startPos = anacrusisBarLine.sourceIndex + anacrusisBarLine.sourceLength;
 			}
-			targetBarNumber = 1;
+			countingFromBarNumber = 1;
 		}
 	} else {
 		// No anacrusis
 		startPos = 0;
-		targetBarNumber = 0;
+		countingFromBarNumber = 0;
 	}
 
-	// Find the target bar number we need to reach
-	const isWholeBars = numBarsFraction.den === 1;
-	let finalTargetBarNumber;
+	// Determine which bar numbers we need based on remaining duration
+	const wholeBarsInRemaining = Math.floor(
+		remainingDurationNeeded.divide(expectedBarDuration).toNumber()
+	);
+	const fractionalPart = remainingDurationNeeded.subtract(
+		expectedBarDuration.multiply(new Fraction(wholeBarsInRemaining, 1))
+	);
 
-	if (isWholeBars) {
-		// For whole bars, we want bars numbered targetBarNumber through targetBarNumber + numBars - 1
-		finalTargetBarNumber = targetBarNumber + numBarsFraction.num - 1;
-	} else {
-		// For fractional bars, we need to go into the next bar
-		finalTargetBarNumber =
-			targetBarNumber + Math.floor(numBarsFraction.toNumber());
-	}
+	const needsFractionalBar = fractionalPart.compare(new Fraction(0, 1)) > 0;
+	const finalTargetBarNumber =
+		countingFromBarNumber +
+		wholeBarsInRemaining +
+		(needsFractionalBar ? 0 : -1);
 
 	// Find end position
 	let endPos = startPos;
 	let foundEnd = false;
 
-	// First, find all bar lines with our target bar numbers
-	const targetBarLines = enrichedBarLines.filter(
+	// Find all bar lines with our target bar numbers
+	const relevantBarLines = enrichedBarLines.filter(
 		(bl) =>
 			bl.barNumber !== null &&
-			bl.barNumber >= targetBarNumber &&
+			bl.barNumber >= countingFromBarNumber &&
 			bl.barNumber <= finalTargetBarNumber
 	);
 
-	if (isWholeBars) {
+	if (!needsFractionalBar) {
 		// For whole bars, find the bar line at finalTargetBarNumber
-		const finalBarLine = targetBarLines.find(
+		const finalBarLine = relevantBarLines.find(
 			(bl) => bl.barNumber === finalTargetBarNumber
 		);
 		if (finalBarLine) {
@@ -516,58 +517,60 @@ function getFirstBars(
 			foundEnd = true;
 		}
 	} else {
-		// For fractional bars, we need to do duration counting within the final bar
-		const fractionalPart = numBarsFraction.subtract(
-			new Fraction(Math.floor(numBarsFraction.toNumber()), 1)
-		);
-		const fractionalDuration = expectedBarDuration.multiply(fractionalPart);
+		// For fractional bars, we need to do duration counting within bars with finalTargetBarNumber
+		// Note: there may be multiple segments with the same barNumber (partial bars)
 
-		// Find all bars with finalTargetBarNumber
-		const finalBarIndex = bars.findIndex((bar, idx) => {
-			const correspondingBarLineIdx = enrichedBarLines.findIndex(
-				(bl) => bl.sourceIndex > (bar[0]?.sourceIndex || 0)
-			);
-			if (correspondingBarLineIdx >= 0) {
-				return (
-					enrichedBarLines[correspondingBarLineIdx].barNumber ===
-					finalTargetBarNumber
-				);
-			}
-			return false;
-		});
+		let accumulated = new Fraction(0, 1);
 
-		if (finalBarIndex >= 0) {
-			const finalBar = bars[finalBarIndex];
-			let accumulated = new Fraction(0, 1);
+		// Iterate through bars and accumulate duration for bars with finalTargetBarNumber
+		for (let i = 0; i < bars.length; i++) {
+			const bar = bars[i];
+			if (bar.length === 0) continue;
 
-			for (const token of finalBar) {
-				if (!token.duration) {
-					continue;
-				}
+			// Find the bar line that follows this bar to get its barNumber
+			const barLineIdx = enrichedBarLines.findIndex(
+				(bl) => bl.sourceIndex >= bar[bar.length - 1].sourceIndex
+			);
 
-				accumulated = accumulated.add(token.duration);
+			if (barLineIdx < 0) continue;
 
-				if (accumulated.compare(fractionalDuration) >= 0) {
-					// Found the position
-					endPos = token.sourceIndex + token.sourceLength;
+			const barLine = enrichedBarLines[barLineIdx];
 
-					// Skip trailing space if present
-					if (
-						token.spacing &&
-						token.spacing.whitespace &&
-						endPos < musicText.length &&
-						musicText[endPos] === " "
-					) {
-						endPos++;
+			if (barLine.barNumber === finalTargetBarNumber) {
+				// This bar segment is part of our target bar number
+				for (const token of bar) {
+					if (!token.duration) {
+						continue;
 					}
-					foundEnd = true;
-					break;
+
+					const newAccumulated = accumulated.add(token.duration);
+
+					if (newAccumulated.compare(fractionalPart) >= 0) {
+						// Found the position - include this token
+						endPos = token.sourceIndex + token.sourceLength;
+
+						// Skip trailing space if present
+						if (
+							token.spacing &&
+							token.spacing.whitespace &&
+							endPos < musicText.length &&
+							musicText[endPos] === " "
+						) {
+							endPos++;
+						}
+						foundEnd = true;
+						break;
+					}
+
+					accumulated = newAccumulated;
 				}
+
+				if (foundEnd) break;
 			}
 		}
 	}
 
-	// Fallback: if we didn't find an end, use the last available position
+	// Fallback: if we didn’t find an end, use the last available position
 	if (!foundEnd || endPos === startPos) {
 		endPos = musicText.length;
 	}

package/src/parse/getBarInfo.js

@@ -24,6 +24,10 @@ const { Fraction } = require("../math.js");
  * All bars at the same position across different variant endings share the same barNumber
  * but have different variantId values (0 for first ending, 1 for second, etc.).
  *
+ * Meter and unit length changes: When a barline has newMeter or newUnitLength fields (from inline
+ * field changes), the new meter/length is applied to the following bar. The fullBarDuration is
+ * recalculated accordingly. Partial bar accumulation continues under the new meter.
+ *
  * IMPORTANT: The music segment associated with a bar line is the segment PRECEDING the bar line.
  * Example: In `A4|B4||c2d2|]`, the segment for `|` is `A4`, for `||` is `B4`, and for `|]` is `c2d2`.
  *
@@ -47,7 +51,12 @@ const { Fraction } = require("../math.js");
  *   - After [1D2: isPartial: true, completesMusicBar: undefined (only 2 beats)
  *   - After [2DF: isPartial: true, completesMusicBar: undefined (only 2 beats)
  *
- * Not handled: Change of meter (inline M: fields).
+ * Example 4: `C4|[M:3/4]D3|E3|` (M:4/4 → 3/4, L:1/4)
+ *   - After C4: barNumber: 0 (complete 4/4 bar)
+ *   - After D3: barNumber: 1 (complete 3/4 bar under new meter)
+ *   - After E3: barNumber: 2 (complete 3/4 bar)
+ *
+ * Not handled: Change of meter or unit length mid-bar (inline M: or L: fields within a bar).
  *
  * @param {Array<Array<Object>>} bars - Array of bar arrays from parseAbc
  * @param {Array<Object>} barLines - Array of barLine objects from parseAbc
@@ -72,13 +81,10 @@ function getBarInfo(bars, barLines, meter, options = {}) {
 	if (divideBarsBy !== null && divideBarsBy !== 2) {
 		throw new Error("divideBarsBy currently only supports value 2");
 	}
-	if (!barLines || barLines.length < bars.length) {
-		throw new Error(
-			"currently not handling bars without a bar line at the end"
-		);
-	}
 
-	const fullBarDuration = new Fraction(meter[0], meter[1]);
+	// Track current meter (can change via inline fields)
+	let currentMeter = [...meter];
+	let fullBarDuration = new Fraction(currentMeter[0], currentMeter[1]);
 	const midpoints = [];
 
 	let currentBarNumber = 0;
@@ -112,6 +118,19 @@ function getBarInfo(bars, barLines, meter, options = {}) {
 		const bar = bars[barIdx];
 		const barLineIdx = barIdx + barLineOffset;
 
+		// Check if the previous barline had a meter or unit length change
+		if (barLineIdx > 0) {
+			const prevBarLine = barLines[barLineIdx - 1];
+
+			if (prevBarLine.newMeter) {
+				currentMeter = [...prevBarLine.newMeter];
+				fullBarDuration = new Fraction(currentMeter[0], currentMeter[1]);
+			}
+
+			// Note: newUnitLength doesn't directly affect fullBarDuration
+			// (token durations are already calculated in the correct units)
+		}
+
 		// Calculate duration of this bar segment
 		// Process tokens and handle variant endings during traversal
 		let barDuration = new Fraction(0, 1);
@@ -130,15 +149,16 @@ function getBarInfo(bars, barLines, meter, options = {}) {
 				if (!inVariantGroup) {
 					// Starting a new variant group - store state including duration accumulated up to this point
 					// Add current barDuration to get the state before this variant token
-					const durationBeforeVariant = durationSinceLastComplete.add(
-						barDuration.subtract(token.duration || new Fraction(0, 1))
-					);
+					const durationBeforeVariant =
+						durationSinceLastComplete.add(barDuration);
 
 					inVariantGroup = true;
 					variantBranchPoint = {
 						barNumber: currentBarNumber,
 						durationSinceLastComplete: durationBeforeVariant.clone(),
 						lastCompleteBarLineIdx: lastCompleteBarLineIdx,
+						meter: [...currentMeter],
+						fullBarDuration: fullBarDuration.clone(),
 					};
 					variantCounter = 0;
 					currentVariantId = variantCounter;
@@ -151,6 +171,8 @@ function getBarInfo(bars, barLines, meter, options = {}) {
 					durationSinceLastComplete =
 						variantBranchPoint.durationSinceLastComplete.clone();
 					lastCompleteBarLineIdx = variantBranchPoint.lastCompleteBarLineIdx;
+					currentMeter = [...variantBranchPoint.meter];
+					fullBarDuration = variantBranchPoint.fullBarDuration.clone();
 					// Discard barDuration accumulated so far (it's from the wrong variant path)
 					barDuration = token.duration
 						? token.duration.clone()
@@ -291,9 +313,25 @@ function getBarInfo(bars, barLines, meter, options = {}) {
 
 	// Calculate midpoints if requested
 	if (divideBarsBy === 2) {
-		const halfBarDuration = fullBarDuration.divide(new Fraction(2, 1));
+		// Track meter for midpoint calculation
+		let midpointMeter = [...meter];
+		let halfBarDuration = new Fraction(
+			midpointMeter[0],
+			midpointMeter[1]
+		).divide(new Fraction(2, 1));
 
 		for (let barIdx = 0; barIdx < bars.length; barIdx++) {
+			const barLineIdx = barIdx + barLineOffset;
+
+			// Update meter if previous barline had a change
+			if (barLineIdx > 0 && barLines[barLineIdx - 1].newMeter) {
+				midpointMeter = [...barLines[barLineIdx - 1].newMeter];
+				halfBarDuration = new Fraction(
+					midpointMeter[0],
+					midpointMeter[1]
+				).divide(new Fraction(2, 1));
+			}
+
 			const bar = bars[barIdx];
 			let accumulated = new Fraction(0, 1);
 

package/src/parse/header-parser.js

@@ -28,10 +28,10 @@ function getTonalBase(abc) {
 }
 
 /**
- * Extract key signature from ABC header
+ * Extract full key signature from ABC header
  *
  * @param {string} abc - ABC notation string
- * @returns {string} - Tonic note (e.g., 'C', 'D', 'G')
+ * @returns {string} - Key (e.g., 'C dorian', 'D mixo', 'G')
  * @throws {Error} - If no key signature found
  */
 function getKey(abc) {

package/src/parse/misc-parser.js

@@ -0,0 +1,118 @@
+/**
+ * Analyze whitespace and back quotes after a token
+ * Returns object describing the spacing/beaming context
+ * Back quotes (`) are ignored for beaming but preserved for reconstruction
+ *
+ * @param {string} segment - The music segment to analyze
+ * @param {number} tokenEndPos - Position where the token ends
+ * @returns {object} - Spacing analysis object
+ *
+ * Return object structure:
+ * {
+ *   whitespace: string,     // Actual whitespace characters (back quotes removed)
+ *   backquotes: number,     // Number of ` characters for reconstruction
+ *   beamBreak: boolean,     // True if beam should break (multiple spaces/newline)
+ *   lineBreak: boolean      // True if there was a newline after this token
+ * }
+ */
+function analyzeSpacing(segment, tokenEndPos) {
+	if (tokenEndPos >= segment.length) {
+		return {
+			whitespace: "",
+			backquotes: 0,
+			beamBreak: false,
+			lineBreak: false,
+		};
+	}
+
+	const remaining = segment.substring(tokenEndPos);
+
+	// Match whitespace and/or back quotes
+	const spacingMatch = remaining.match(/^([\s`]+)/);
+
+	if (!spacingMatch) {
+		return {
+			whitespace: "",
+			backquotes: 0,
+			beamBreak: false,
+			lineBreak: false,
+		};
+	}
+
+	const fullSpacing = spacingMatch[1];
+
+	// Count back quotes
+	const backquotes = (fullSpacing.match(/`/g) || []).length;
+
+	// Extract just whitespace (no back quotes)
+	const whitespace = fullSpacing.replace(/`/g, "");
+
+	return {
+		whitespace,
+		backquotes,
+		beamBreak: whitespace.length > 1 || whitespace.includes("\n"), // Multiple spaces or newline breaks beam
+		lineBreak: whitespace.includes("\n"),
+	};
+}
+
+/**
+ * Parse tuplet notation from a token
+ *
+ * @param {string} token - Tuplet token (e.g., '(3', '(3:2', '(3:2:4')
+ * @param {boolean} isCompoundTimeSignature - Whether current time signature is compound (affects default q value)
+ * @returns {object|null} - { isTuple: true, p, q, r } or null if not a valid tuplet
+ */
+function parseTuplet(token, isCompoundTimeSignature) {
+	const tupleMatch = token.match(/^\(([2-9])(?::(\d)?)?(?::(\d)?)?$/);
+	if (tupleMatch) {
+		const pqr = {
+			p: parseInt(tupleMatch[1]),
+			q: tupleMatch[2],
+			r: tupleMatch[3],
+		};
+		const { p } = pqr;
+		let { q, r } = pqr;
+		if (q) {
+			q = parseInt(q);
+		} else {
+			switch (p) {
+				case 2:
+					q = 3;
+					break;
+				case 3:
+					q = 2;
+					break;
+				case 4:
+					q = 3;
+					break;
+				case 5:
+				case 7:
+				case 9:
+					q = isCompoundTimeSignature ? 3 : 2;
+					break;
+				case 6:
+					q = 2;
+					break;
+				case 8:
+					q = 3;
+					break;
+			}
+		}
+		if (r) {
+			r = parseInt(r);
+		} else {
+			r = p;
+		}
+		return {
+			isTuple: true,
+			p,
+			q,
+			r,
+		};
+	}
+	return null;
+}
+module.exports = {
+	analyzeSpacing,
+	parseTuplet,
+};