@goplayerjuggler/abc-tools 1.0.20 → 1.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goplayerjuggler/abc-tools",
-  "version": "1.0.20",
+  "version": "1.0.22",
   "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

@@ -288,7 +288,8 @@ function getIncipit(data) {
 		numBars = 2;
 		const currentMeter = getMeter(abc);
 		const unitLength = getUnitLength(abc);
-		if (
+		if (!currentMeter) numBars = 2;
+		else if (
 			(currentMeter[0] === 4 &&
 				currentMeter[1] === 4 &&
 				unitLength.den === 16) ||

package/src/manipulator.js

@@ -875,10 +875,13 @@ function getFirstBars(
 
 	// Parse ABC
 	const parsed = parseAbc(abc, { maxBars: estimatedMaxBars });
-	const { bars, headerLines, barLines, musicText, meter } = parsed;
+	const { bars, headerLines, barLines, musicText } = parsed;
+	let { meter } = parsed;
+	if (!meter) meter = [10000, 1]; //hack(?) to handle incipits in meterless music
 
+	let stopAfterDuration = null;
 	if (bars.length === 0 || barLines.length === 0) {
-		throw new Error("No bars found");
+		stopAfterDuration = new Fraction(3, 2);
 	}
 
 	// Determine which bar number to stop after
@@ -910,7 +913,8 @@ function getFirstBars(
 
 	// Calculate the expected duration per musical bar
 	const expectedBarDuration = new Fraction(meter[0], meter[1]);
-	const targetDuration = expectedBarDuration.multiply(numBarsFraction);
+	const targetDuration =
+		stopAfterDuration ?? expectedBarDuration.multiply(numBarsFraction);
 
 	// Determine starting position and how much duration we need to accumulate
 	let startPos = 0;

package/src/parse/accidental-helpers.js

@@ -417,7 +417,7 @@ function reconstructMusicFromTokens(tokens) {
 		const token = tokens[i];
 
 		// Add the token (possibly modified)
-		result += token.token;
+		if (token.token) result += token.token;
 
 		// Add spacing after token (but not after the last token)
 		if (i < tokens.length - 1 && token.spacing && token.spacing.whitespace) {

package/src/parse/decode-abc-text.js

@@ -0,0 +1,201 @@
+/**
+ * Maps 2-char ABC mnemonic sequences (ABC 2.1 §2.3) to Unicode characters.
+ * Keys are the two characters following the backslash.
+ */
+const MNEMONIC_MAP = {
+	// Grave: \`X
+	"`A": "À",
+	"`a": "à",
+	"`E": "È",
+	"`e": "è",
+	"`I": "Ì",
+	"`i": "ì",
+	"`O": "Ò",
+	"`o": "ò",
+	"`U": "Ù",
+	"`u": "ù",
+	// Acute: \'X
+	"'A": "Á",
+	"'a": "á",
+	"'E": "É",
+	"'e": "é",
+	"'I": "Í",
+	"'i": "í",
+	"'O": "Ó",
+	"'o": "ó",
+	"'U": "Ú",
+	"'u": "ú",
+	"'Y": "Ý",
+	"'y": "ý",
+	// Circumflex: \^X
+	"^A": "Â",
+	"^a": "â",
+	"^E": "Ê",
+	"^e": "ê",
+	"^I": "Î",
+	"^i": "î",
+	"^O": "Ô",
+	"^o": "ô",
+	"^U": "Û",
+	"^u": "û",
+	// Tilde: \~X
+	"~A": "Ã",
+	"~a": "ã",
+	"~N": "Ñ",
+	"~n": "ñ",
+	"~O": "Õ",
+	"~o": "õ",
+	// Umlaut: \"X
+	'"A': "Ä",
+	'"a': "ä",
+	'"E': "Ë",
+	'"e': "ë",
+	'"I': "Ï",
+	'"i': "ï",
+	'"O': "Ö",
+	'"o': "ö",
+	'"U': "Ü",
+	'"u': "ü",
+	'"Y': "Ÿ",
+	'"y': "ÿ",
+	// Cedilla, ring, slash
+	cC: "Ç",
+	cc: "ç",
+	AA: "Å",
+	aa: "å",
+	"/O": "Ø",
+	"/o": "ø",
+	// Breve: \uX  (note: \uXXXX hex escapes are resolved before this map is applied)
+	uA: "Ă",
+	ua: "ă",
+	uE: "Ĕ",
+	ue: "ĕ",
+	// Caron, double acute
+	vS: "Š",
+	vs: "š",
+	vZ: "Ž",
+	vz: "ž",
+	HO: "Ő",
+	Ho: "ő",
+	HU: "Ű",
+	Hu: "ű",
+	// Ligatures
+	ss: "ß",
+	AE: "Æ",
+	ae: "æ",
+	oe: "œ"
+};
+
+/** Named HTML entities for common European characters. */
+const HTML_ENTITY_MAP = {
+	amp: "&",
+	lt: "<",
+	gt: ">",
+	quot: '"',
+	apos: "'",
+	nbsp: "\u00A0",
+	Agrave: "À",
+	agrave: "à",
+	Aacute: "Á",
+	aacute: "á",
+	Acirc: "Â",
+	acirc: "â",
+	Atilde: "Ã",
+	atilde: "ã",
+	Auml: "Ä",
+	auml: "ä",
+	Aring: "Å",
+	aring: "å",
+	AElig: "Æ",
+	aelig: "æ",
+	Ccedil: "Ç",
+	ccedil: "ç",
+	Egrave: "È",
+	egrave: "è",
+	Eacute: "É",
+	eacute: "é",
+	Ecirc: "Ê",
+	ecirc: "ê",
+	Euml: "Ë",
+	euml: "ë",
+	Igrave: "Ì",
+	igrave: "ì",
+	Iacute: "Í",
+	iacute: "í",
+	Icirc: "Î",
+	icirc: "î",
+	Iuml: "Ï",
+	iuml: "ï",
+	Ntilde: "Ñ",
+	ntilde: "ñ",
+	Ograve: "Ò",
+	ograve: "ò",
+	Oacute: "Ó",
+	oacute: "ó",
+	Ocirc: "Ô",
+	ocirc: "ô",
+	Otilde: "Õ",
+	otilde: "õ",
+	Ouml: "Ö",
+	ouml: "ö",
+	Oslash: "Ø",
+	oslash: "ø",
+	Ugrave: "Ù",
+	ugrave: "ù",
+	Uacute: "Ú",
+	uacute: "ú",
+	Ucirc: "Û",
+	ucirc: "û",
+	Uuml: "Ü",
+	uuml: "ü",
+	Yacute: "Ý",
+	yacute: "ý",
+	Yuml: "Ÿ",
+	szlig: "ß",
+	OElig: "Œ",
+	oelig: "œ"
+};
+
+/**
+ * Strips an ABC inline % comment (a % not preceded by \) and trims trailing whitespace.
+ * @param {string} str
+ * @returns {string}
+ */
+function stripComment(str) {
+	return str.replace(/(?<!\\)%.*/, "").trimEnd();
+}
+
+/**
+ * Decodes ABC 2.1 text-string escapes (§2.3) into Unicode.
+ * Processing order:
+ *   1. Protect \\ with a placeholder
+ *   2. \uXXXX fixed-width unicode (must precede breve \uX mnemonic)
+ *   3. Protect \% and \& control escapes
+ *   4–6. HTML named / decimal / hex entities
+ *   7. Curly-brace mnemonic variants: {mnem} or {\mnem}
+ *   8. Backslash mnemonics: \XX
+ *   9. Restore placeholders
+ * @param {string} str - Header value, already comment-stripped
+ * @returns {string}
+ */
+function decodeABCText(str) {
+	return str
+		.replace(/\\\\/g, "\x00")
+		.replace(/\\u([0-9a-fA-F]{4})/g, (_, h) =>
+			String.fromCodePoint(parseInt(h, 16))
+		)
+		.replace(/\\%/g, "\x01")
+		.replace(/\\&/g, "\x02")
+		.replace(/&([a-zA-Z]+);/g, (m, n) => HTML_ENTITY_MAP[n] ?? m)
+		.replace(/&#x([0-9a-fA-F]+);/gi, (_, h) =>
+			String.fromCodePoint(parseInt(h, 16))
+		)
+		.replace(/&#([0-9]+);/g, (_, n) => String.fromCodePoint(+n))
+		.replace(/\{\\?([^}{]{2})\}/g, (m, k) => MNEMONIC_MAP[k] ?? m)
+		.replace(/\\(..)/g, (m, k) => MNEMONIC_MAP[k] ?? m)
+		.replaceAll("\x00", "\\")
+		.replaceAll("\x01", "%")
+		.replaceAll("\x02", "&");
+}
+
+module.exports = { decodeABCText, stripComment };

package/src/parse/getMetadata.js

@@ -1,71 +1,75 @@
 const { normaliseKey } = require("../manipulator");
+const { decodeABCText, stripComment } = require("./decode-abc-text");
 
 /**
- * Extracts data in the ABC _header_ T R C M K S F D N H fields
- * and returns it in a object with properties: title, rhythm, composer, meter, key,
- * source, url, recording, comments, and hComments.
- * 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 (i.e. the N / notes) go in an array called `comments`, with one array entry per N: line
- * - the history (H) lines are joined up with spaces into a single line that is returned as `hComments`
- * - the field continuation `+:` is handled only for lines following an initial H (history)
- * - if there’s more than one T (title), then titles after the first one are returned in an array `titles`
- * @param {*} abc
- * @returns {object} - The header info
+ * Extracts data in the ABC _header_ T R C M K S O F D N H fields
+ * and returns it in an object with properties: title, rhythm, composer, meter, key,
+ * source, origin, url, recording, comments, and hComments.
+ * - Only the first T title is stored in `title`; subsequent ones go in `titles`
+ * - The key is normalised: C, Cmaj, C maj, C major all map to "C major"
+ * - N: lines accumulate in a `comments` array
+ * - H: lines (and +: continuations) are joined with spaces into `hComments`
+ * - ABC text escapes (mnemonics, entities, etc.) are decoded by default
+ * @param {string} abc
+ * @param {object}  [options]
+ * @param {boolean} [options.decode=true] - Decode ABC text escapes; pass false for raw speed
+ * @returns {object}
  */
-function getMetadata(abc) {
+function getMetadata(abc, { decode = true } = {}) {
 	const lines = abc.split("\n"),
 		metadata = {},
 		comments = [],
 		hComments = [],
 		titles = [];
 
+	const process = decode
+		? (raw) => decodeABCText(stripComment(raw))
+		: (raw) => stripComment(raw);
+
 	let currentHeader = "";
 
 	for (const line of lines) {
 		const trimmed = line.trim();
-		const trimmed2 = trimmed.substring(2).trim().replace(/%.+/, "");
+		if (!trimmed || trimmed[0] === "%") continue;
+
+		if (trimmed.startsWith("K:")) {
+			metadata.key = normaliseKey(
+				stripComment(trimmed.substring(2).trim())
+			).join(" ");
+			break;
+		}
+
+		const val = process(trimmed.substring(2).trim());
+
 		if (trimmed.startsWith("T:")) {
-			if (!metadata.title) metadata.title = trimmed2;
-			else titles.push(trimmed2);
+			if (!metadata.title) metadata.title = val;
+			else titles.push(val);
 		} else if (trimmed.startsWith("R:")) {
-			metadata.rhythm = trimmed2.toLowerCase();
+			metadata.rhythm = val.toLowerCase();
 		} else if (trimmed.startsWith("C:")) {
-			metadata.composer = trimmed2;
+			metadata.composer = val;
 		} else if (trimmed.startsWith("M:")) {
-			metadata.meter = trimmed2;
-		} else if (trimmed.startsWith("K:")) {
-			metadata.key = normaliseKey(trimmed2).join(" ");
-			// metadata.indexOfKey = i
-			break;
+			metadata.meter = val;
 		} else if (trimmed.startsWith("S:")) {
-			metadata.source = trimmed2;
+			metadata.source = val;
 		} else if (trimmed.startsWith("O:")) {
-			metadata.origin = trimmed2;
+			metadata.origin = val;
 		} else if (trimmed.startsWith("F:")) {
-			metadata.url = trimmed2;
+			metadata.url = val;
 		} else if (trimmed.startsWith("D:")) {
-			metadata.recording = trimmed2;
+			metadata.recording = val;
 		} else if (trimmed.startsWith("N:")) {
-			comments.push(trimmed2);
+			comments.push(val);
 		} else if (trimmed.startsWith("H:")) {
 			currentHeader = "H";
-			hComments.push(trimmed2);
-		} else if (trimmed.startsWith("+:")) {
-			switch (currentHeader) {
-				case "H":
-					hComments.push(trimmed2);
-					break;
-			}
+			hComments.push(val);
+		} else if (trimmed.startsWith("+:") && currentHeader === "H") {
+			hComments.push(val);
 		}
 	}
-	if (comments.length > 0) {
-		metadata.comments = comments;
-	}
-	if (hComments.length > 0) {
-		metadata.hComments = hComments.join(" ");
-	}
+
+	if (comments.length > 0) metadata.comments = comments;
+	if (hComments.length > 0) metadata.hComments = hComments.join(" ");
 	if (titles.length > 0) metadata.titles = titles;
 
 	return metadata;

package/src/parse/header-parser.js

@@ -1,4 +1,5 @@
 const { Fraction } = require("../math.js");
+const { decodeABCText, stripComment } = require("./decode-abc-text");
 
 // ============================================================================
 // ABC HEADER PARSING
@@ -12,6 +13,37 @@ const { Fraction } = require("../math.js");
 //
 // ============================================================================
 
+/**
+ * Returns all values for a given header letter in the ABC string, in document order.
+ * @param {string} abc
+ * @param {string} header - Single header letter, e.g. 'T'
+ * @param {object}  [options]
+ * @param {boolean} [options.decode=true] - Decode ABC text escapes; pass false for raw values
+ * @returns {string[]}
+ */
+function getHeaderValues(abc, header, { decode = true } = {}) {
+	const re = new RegExp(`^${header}:[ \\t]*(.*)$`, "gm");
+	const results = [];
+	for (const m of abc.matchAll(re)) {
+		const val = decode ? decodeABCText(stripComment(m[1])) : stripComment(m[1]);
+		if (val) results.push(val);
+	}
+	return results;
+}
+
+/** @deprecated Use `getHeaderValues(abc, header)[0] ?? null` instead. */
+function getHeaderValue(abc, header, options) {
+	return getHeaderValues(abc, header, options)[0] ?? null;
+}
+
+/**
+ * @deprecated Use `getHeaderValues(abc, 'T')` instead.
+ * Note: unlike the previous implementation, this now returns decoded strings, not match objects.
+ */
+function getTitles(abc) {
+	return getHeaderValues(abc, "T");
+}
+
 /**
  * Extract base note of key signature from ABC header
  *
@@ -70,21 +102,6 @@ function getUnitLength(abc) {
 	}
 	return new Fraction(1, 8); // Default to 1/8
 }
-/**
- * Extract titles - there may be 0..N titles
- *
- * @param {string} abc - ABC notation string
- * @returns {[string]} - array of titles
- */
-function getTitles(abc) {
-	return [...abc.matchAll(/^(?:T:\s*(.+)\n)/gm)];
-}
-
-function getHeaderValue(abc, header) {
-	const r = new RegExp(String.raw`(?:${header}:\s*(.+)\n)`, "m"),
-		m = abc.match(r);
-	return m ? m[1]?.trim() : null;
-}
 
 /**
  * Process ABC lines: extract music lines with metadata
@@ -167,6 +184,7 @@ function getMusicLines(abc) {
 
 module.exports = {
 	getHeaderValue,
+	getHeaderValues,
 	getKey,
 	getMeter,
 	getMusicLines,

package/src/parse/note-parser.js

@@ -294,11 +294,12 @@ function parseGraceNotes(graceStr) {
 function parseBrokenRhythm(token) {
 	const brokenMatch = token.match(/^(<{1,3}|>{1,3})$/);
 	if (brokenMatch) {
-		const symbol = brokenMatch[1];
+		const token = brokenMatch[1];
 		return {
 			isBrokenRhythm: true,
-			direction: symbol[0],
-			dots: symbol.length
+			direction: token[0],
+			token,
+			dots: token.length
 		};
 	}
 	return null;