Cleanup of comments, organization

custom.md

@@ -142,7 +142,7 @@ recursively visit every node in the tree and call a callback function with each
 one. The node tree cannot be restructured, but each node can be inspected or
 altered.
 
-To perform substitution, `MDUtils.replaceNodes` can be called. It will call a
+To perform substitution, `MDNode.replaceNodes` can be called. It will call a
 replacer function with every node in the tree recursively. If the function
 returns `null`, no change is made. If the function returns a new `MDNode`
 instance it will replace that node in the tree. When a replacement is made,

js/spreadsheet.js

@@ -996,38 +996,45 @@ class CellExpression {
 	 * @type {CellExpressionOperation}
 	 */
 	op;
+
 	/**
 	 * Mixed array of `CellValue`, `CellAddress`, `CellAddressRange`,
 	 * `CellExpression`, perhaps more.
 	 * @type {Array}
 	 */
 	arguments;
+
 	/**
 	 * For `Function`, the function name.
 	 * @type {string|null}
 	 */
 	qualifier;
+
 	/**
 	 * Optional format override. One of `number`, `currency`, `percent`.
 	 * @type {string|null}
 	 */
 	outputType = null;
+
 	/**
 	 * Optional decimal place formatting override.
 	 * @type {number|null}
 	 */
 	outputDecimals = null;
+
 	/**
 	 * Address ranges to copy this expression into for any blank cells. Used
 	 * by formulas with the `FILL` modifier.
 	 * @type {CellAddressRange[]|null} fillRanges
 	 */
 	fillRanges = null;
+
 	/**
 	 * Source address of the formula.
 	 * @type {CellAddress|null}
 	 */
 	location = null;
+
 	/**
 	 * @param {CellExpressionOperation} op
 	 * @param {Array} args
@@ -1451,10 +1458,13 @@ class CellExpression {
 	/**
 	 * Tries to parse a format suffix after a semicolon. Examples:
 	 *
-	 *     ; number
-	 *     ; number 3
-	 *     ; currency 2
-	 *     ; percent 0
+	 * ```
+	 * ; number
+	 * ; number 3
+	 * ; currency 2
+	 * ; percent 0
+	 * ```
+	 *
 	 * @param {CellExpressionToken[]} tokens
 	 * @param {number} start
 	 * @param {number} end
@@ -1663,6 +1673,21 @@ class CellExpression {
 		return new CellExpression(CellExpressionOperation.Reference, [ refAddress ]);
 	}
 
+	static #infixPriority = {};
+	static {
+		this.#infixPriority[CellExpressionTokenType.Minus.name] = 1;
+		this.#infixPriority[CellExpressionTokenType.Plus.name] = 2;
+		this.#infixPriority[CellExpressionTokenType.Divide.name] = 3;
+		this.#infixPriority[CellExpressionTokenType.Multiply.name] = 4;
+		this.#infixPriority[CellExpressionTokenType.Ampersand.name] = 10;
+		this.#infixPriority[CellExpressionTokenType.GreaterThan.name] = 20;
+		this.#infixPriority[CellExpressionTokenType.GreaterThanEqual.name] = 20;
+		this.#infixPriority[CellExpressionTokenType.LessThan.name] = 20;
+		this.#infixPriority[CellExpressionTokenType.LessThanEqual.name] = 20;
+		this.#infixPriority[CellExpressionTokenType.Equal.name] = 20;
+		this.#infixPriority[CellExpressionTokenType.Unequal.name] = 20;
+	}
+
 	/**
 	 * @param {CellExpressionToken[]} tokens
 	 * @param {number} start
@@ -1673,18 +1698,6 @@ class CellExpression {
 	static #tryInfix(tokens, start, end, address) {
 		const count = end - start + 1;
 		if (count < 3) return null;
-		const opPriorities = {}
-		opPriorities[CellExpressionTokenType.Multiply.name] = 4;
-		opPriorities[CellExpressionTokenType.Divide.name] = 3;
-		opPriorities[CellExpressionTokenType.Plus.name] = 2;
-		opPriorities[CellExpressionTokenType.Minus.name] = 1;
-		opPriorities[CellExpressionTokenType.Ampersand.name] = 10;
-		opPriorities[CellExpressionTokenType.GreaterThan.name] = 20;
-		opPriorities[CellExpressionTokenType.GreaterThanEqual.name] = 20;
-		opPriorities[CellExpressionTokenType.LessThan.name] = 20;
-		opPriorities[CellExpressionTokenType.LessThanEqual.name] = 20;
-		opPriorities[CellExpressionTokenType.Equal.name] = 20;
-		opPriorities[CellExpressionTokenType.Unequal.name] = 20;
 		var candidates = [];
 		var parenLevel = 0;
 		var i;
@@ -1695,9 +1708,8 @@ class CellExpression {
 				parenLevel--;
 			} else if (parenLevel == 0 && i > start && i < end) {
 				const op = tokens[i].type.name;
-				const priority = opPriorities[op] ?? false;
+				const priority = this.#infixPriority[op] ?? false;
 				if (priority === false) continue;
-				//console.info(`Found infix candidate at ${i} for ${op} priority ${priority}`);
 				candidates.push({ priority: priority, i: i });
 			}
 		}
@@ -1720,11 +1732,9 @@ class CellExpression {
 			}
 		}
 		if (bestCandidate === null) {
-			//console.info("No best candidate found");
 			return null;
 		}
 		i = bestCandidate.i;
-		//console.info(`Best candidate at token ${i}, priority ${bestCandidate.priority}`);
 		switch (tokens[bestCandidate.i].type) {
 			case CellExpressionTokenType.Plus:
 				return new CellExpression(CellExpressionOperation.Add, [ operand1, operand2 ]);
@@ -1800,26 +1810,26 @@ class CellExpressionToken {
  * uniquely identify a cell.
  */
 class CellAddress {
-	#name;
 	/**
 	 * @type {string}
 	 */
 	get name() { return this.#name; }
+	#name;
 
-	#isColumnFixed = false;
 	/** 
 	 * Whether the column should remain unchanged when transposed. This is
 	 * symbolized by prefixing the column name with a `$` (e.g. `$C3`).
 	 * @type {boolean}
 	 */
 	get isColumnFixed() { return this.#isColumnFixed; }
+	#isColumnFixed = false;
 
-	#columnIndex = -1;
 	/**
 	 * Zero-based column index.
 	 * @type {number}
 	 */
 	get columnIndex() { return this.#columnIndex; };
+	#columnIndex = -1;
 
 	/**
 	 * Letter code for the column.
@@ -1827,20 +1837,20 @@ class CellAddress {
 	 */
 	get columnLetter() { return CellAddress.#columnIndexToLetters(this.#columnIndex); }
 
-	#isRowFixed = false;
 	/**
 	 * Whether the row should remain unchanged when transposed. This is
 	 * symbolized by prefixing the row number with a `$` (e.g. `C$3`).
 	 * @type {boolean}
 	 */
 	get isRowFixed() { return this.#isRowFixed; }
+	#isRowFixed = false;
 
-	#rowIndex = -1;
 	/**
 	 * Zero-based row index.
 	 * @type {number}
 	 */
 	get rowIndex() { return this.#rowIndex; }
+	#rowIndex = -1;
 
 	/**
 	 * One-based row number. This is the human-facing row number.
@@ -1877,6 +1887,7 @@ class CellAddress {
 
 	/**
 	 * Tests if a string is formatted like an address.
+	 *
 	 * @param {string} text
 	 * @returns {boolean}
 	 */
@@ -1894,15 +1905,19 @@ class CellAddress {
 	 *
 	 * Examples:
 	 * - C6.transpose(A5, A9) = C10  (A9-A5 = +4 rows, C6 + 4 rows = C10)
-	 * - C6.transpose(A5, B9) = D10  (B9-A5 = +4 rows +1 cols, C6 + 4 rows + 1 col = D10)
-	 * - C$6.transpose(A5, A9) = C6  (A9-A5 = +4 rows, but row is fixed, so still C6)
-	 * - B.transpose(A5, A9) = B9  (A9-A4 = +4 rows, B has no row so last row used = B9)
+	 * - C6.transpose(A5, B9) = D10  (B9-A5 = +4 rows +1 cols, C6 + 4 rows + 1
+	 *   col = D10)
+	 * - C$6.transpose(A5, A9) = C6  (A9-A5 = +4 rows, but row is fixed, so
+	 *   still C6)
+	 * - B.transpose(A5, A9) = B9  (A9-A4 = +4 rows, B has no row so last row
+	 *   used = B9)
 	 * - A1.transpose(C3, A1) = null (out of bounds)
 	 * 
 	 * @param {CellAddress} relativeFrom - original address of the formula
-	 * @param {CellAddress} relativeTo - address where the formula is being repeated
-	 * @param {boolean} resolveToRow - whether to fill in a row number if this address
-	 *   doesn't have one
+	 * @param {CellAddress} relativeTo - address where the formula is being
+	 *   repeated
+	 * @param {boolean} resolveToRow - whether to fill in a row number if this
+	 *   address doesn't have one
 	 * @returns {CellAddress|null} - resolved address, or `null` if out of bounds
 	 */
 	transpose(relativeFrom, relativeTo, resolveToRow = true) {
@@ -1989,11 +2004,13 @@ class CellAddress {
 	 * Attempts to convert a cell address string to a `CellAddress`.
 	 *
 	 * @param {string} address - cell address string
-	 * @param {CellAddress|null} relativeTo - address to resolve relative addresses against
-	 * @param {boolean} throwIfInvalid - whether to throw an error if address is invalid
+	 * @param {CellAddress|null} relativeTo - address to resolve relative
+	 *   addresses against
+	 * @param {boolean} throwIfInvalid - whether to throw an error if address
+	 *   is invalid
 	 * @returns {CellAddress|null} address, if parsable
-	 * @throws {CellEvaluationException} if the address is invalid and `throwIfInvalid`
-	 *   is `true`
+	 * @throws {CellEvaluationException} if the address is invalid and
+	 *   `throwIfInvalid` is `true`
 	 */
 	static fromString(address, relativeTo=null, throwIfInvalid=false) {
 		const groups = /^(\$?)([A-Z]{1,2}?)((?:\$(?=[0-9]))?)([0-9]*)$/i.exec(address);
@@ -2069,9 +2086,11 @@ class CellAddressRange {
 	 */
 	cellsIn(grid) {
 		const minCol = this.minColumnIndex < 0 ? 0 : this.minColumnIndex;
-		const maxCol = this.maxColumnIndex < 0 ? grid.columnCount - 1 : Math.min(this.maxColumnIndex, grid.columnCount - 1);
+		const maxCol = this.maxColumnIndex < 0 ? grid.columnCount - 1
+			: Math.min(this.maxColumnIndex, grid.columnCount - 1);
 		const minRow = this.minRowIndex < 0 ? 0 : this.minRowIndex;
-		const maxRow = this.maxRowIndex < 0 ? grid.rowCount - 1 : Math.min(this.maxRowIndex, grid.rowCount - 1);
+		const maxRow = this.maxRowIndex < 0 ? grid.rowCount - 1
+			: Math.min(this.maxRowIndex, grid.rowCount - 1);
 		const iterable = {};
 		iterable[Symbol.iterator] = function() {
 			var currentCol = minCol;
@@ -2133,7 +2152,7 @@ class CellValue {
 	 */
 	static TYPE_FORMULA = 'formula';
 
-		// -- Properties -----
+	// -- Properties -----
 
 	/**
 	 * A blank value.
@@ -2187,6 +2206,7 @@ class CellValue {
 
 	/**
 	 * Returns whether this value is a numeric type.
+	 *
 	 * @returns {boolean}
 	 */
 	isNumeric() {
@@ -2356,6 +2376,7 @@ class CellValue {
 
 	/**
 	 * Returns the boolean equivalent of this value if possible.
+	 *
 	 * @returns {boolean|null}
 	 */
 	booleanValue() {
@@ -2377,6 +2398,7 @@ class CellValue {
 
 	/**
 	 * Returns the numeric value of this value if possible.
+	 *
 	 * @returns {number|null}
 	 */
 	numericValue() {
@@ -2398,6 +2420,7 @@ class CellValue {
 
 	/**
 	 * Returns the string value of this value if possible.
+	 *
 	 * @param {boolean} formatted
 	 * @returns {string|null}
 	 */
@@ -2428,7 +2451,8 @@ class CellValue {
 	 * @returns {CellValue} sum
 	 */
 	add(b) {
-		return CellValue.#binaryNumericOperation(this, b, '+', (aVal, bVal) => aVal + bVal);
+		return CellValue.#binaryNumericOperation(this, b, '+',
+			(aVal, bVal) => aVal + bVal);
 	}
 
 	/**
@@ -2438,7 +2462,8 @@ class CellValue {
 	 * @returns {CellValue} difference
 	 */
 	subtract(b) {
-		return CellValue.#binaryNumericOperation(this, b, '-', (aVal, bVal) => aVal - bVal);
+		return CellValue.#binaryNumericOperation(this, b, '-',
+			(aVal, bVal) => aVal - bVal);
 	}
 
 	/**
@@ -2448,7 +2473,8 @@ class CellValue {
 	 * @returns {CellValue} product
 	 */
 	multiply(b) {
-		return CellValue.#binaryNumericOperation(this, b, '*', (aVal, bVal) => aVal * bVal);
+		return CellValue.#binaryNumericOperation(this, b, '*',
+			(aVal, bVal) => aVal * bVal);
 	}
 
 	/**
@@ -2541,6 +2567,7 @@ class CellValue {
 
 	/**
 	 * Returns the boolean not of this value.
+	 *
 	 * @returns {CellValue}
 	 */
 	not() {
@@ -2563,6 +2590,9 @@ class CellValue {
 	}
 
 	/**
+	 * Returns the string representation of a value concatenated to the string
+	 * representation of this value.
+	 *
 	 * @param {CellValue} b
 	 * @returns {CellValue}
 	 */
@@ -2576,11 +2606,13 @@ class CellValue {
 	}
 
 	/**
-	 * @param {CellValue} a
-	 * @param {CellValue} b
-	 * @param {string} op
+	 * Helper to resolve two numeric arguments and perform an operation on them.
+	 *
+	 * @param {CellValue} a - operand A
+	 * @param {CellValue} b - operand B
+	 * @param {string} op - operator
 	 * @param {function} fn - takes two `number` arguments and returns a `number` result
-	 * @returns {CellValue}
+	 * @returns {CellValue} result
 	 * @throws {CellEvaluationException}
 	 */
 	static #binaryNumericOperation(a, b, op, fn) {
@@ -2654,9 +2686,11 @@ class CellValue {
 	}
 
 	/**
+	 * Performs a comparison of two values.
+	 *
 	 * @param {CellValue} a
 	 * @param {CellValue} b
-	 * @returns {number}
+	 * @returns {number} `-1`, `0`, or `1` if a < b, a == b, or a > b, respectively
 	 */
 	static #compare(a, b) {
 		const args = CellValue.#resolveComparableArguments(a, b);
@@ -2712,10 +2746,11 @@ class CellValue {
 	/**
 	 * Returns a formatted string for the given raw value, value type, and
 	 * decimal places.
+	 *
 	 * @param {any} value
 	 * @param {string} type
 	 * @param {number} decimals
-	 * @returns {string}
+	 * @returns {string} formatted value
 	 */
 	static formatType(value, type, decimals) {
 		switch (type) {
@@ -2763,9 +2798,10 @@ class CellValue {
 
 	/**
 	 * Determines a good number of decimal places to format a value to.
+	 *
 	 * @param {any} value
 	 * @param {number} maxDigits
-	 * @returns {number}
+	 * @returns {number} digit count
 	 */
 	static #autodecimals(value, maxDigits = 6) {
 		if (value instanceof CellValue) {
@@ -2781,6 +2817,8 @@ class CellValue {
 	}
 
 	/**
+	 * Tests if a type is numeric.
+	 *
 	 * @param {string} type
 	 * @returns {boolean}
 	 */
@@ -2874,7 +2912,10 @@ class SpreadsheetCell {
 	 */
 	outputValue = null;
 
-	/** @type {boolean} */
+	/**
+	 * Whether `outputValue` is the result of a formula evaluation.
+	 * @type {boolean}
+	 */
 	isCalculated = false;
 
 	/** @type {CellExpression|null} */

testjs.html

@@ -645,43 +645,43 @@
 
 				test_tokenizeLabel() {
 					// Escapes are preserved
-					this.assertEqual(MDUtils.tokenizeLabel('[foo] bar'), [ '[foo]', 'foo' ]);
-					this.assertEqual(MDUtils.tokenizeLabel('[foo\\[] bar'), [ '[foo\\[]', 'foo\\[' ]);
-					this.assertEqual(MDUtils.tokenizeLabel('[foo\\]] bar'), [ '[foo\\]]', 'foo\\]' ]);
-					this.assertEqual(MDUtils.tokenizeLabel('[foo[]] bar'), [ '[foo[]]', 'foo[]' ]);
-					this.assertEqual(MDUtils.tokenizeLabel('[foo\\(] bar'), [ '[foo\\(]', 'foo\\(' ]);
-					this.assertEqual(MDUtils.tokenizeLabel('[foo\\)] bar'), [ '[foo\\)]', 'foo\\)' ]);
-					this.assertEqual(MDUtils.tokenizeLabel('[foo()] bar'), [ '[foo()]', 'foo()' ]);
+					this.assertEqual(MDToken.tokenizeLabel('[foo] bar'), [ '[foo]', 'foo' ]);
+					this.assertEqual(MDToken.tokenizeLabel('[foo\\[] bar'), [ '[foo\\[]', 'foo\\[' ]);
+					this.assertEqual(MDToken.tokenizeLabel('[foo\\]] bar'), [ '[foo\\]]', 'foo\\]' ]);
+					this.assertEqual(MDToken.tokenizeLabel('[foo[]] bar'), [ '[foo[]]', 'foo[]' ]);
+					this.assertEqual(MDToken.tokenizeLabel('[foo\\(] bar'), [ '[foo\\(]', 'foo\\(' ]);
+					this.assertEqual(MDToken.tokenizeLabel('[foo\\)] bar'), [ '[foo\\)]', 'foo\\)' ]);
+					this.assertEqual(MDToken.tokenizeLabel('[foo()] bar'), [ '[foo()]', 'foo()' ]);
 
-					this.assertEqual(MDUtils.tokenizeLabel('foo bar'), null);
-					this.assertEqual(MDUtils.tokenizeLabel('[foo\\] bar'), null);
-					this.assertEqual(MDUtils.tokenizeLabel('[foo bar'), null);
-					this.assertEqual(MDUtils.tokenizeLabel('[foo[] bar'), null);
+					this.assertEqual(MDToken.tokenizeLabel('foo bar'), null);
+					this.assertEqual(MDToken.tokenizeLabel('[foo\\] bar'), null);
+					this.assertEqual(MDToken.tokenizeLabel('[foo bar'), null);
+					this.assertEqual(MDToken.tokenizeLabel('[foo[] bar'), null);
 				}
 
 				test_tokenizeURL() {
-					this.assertEqual(MDUtils.tokenizeURL('(page.html) foo'), [ '(page.html)', 'page.html', null ]);
-					this.assertEqual(MDUtils.tokenizeURL('(page.html "link title") foo'), [ '(page.html "link title")', 'page.html', 'link title' ]);
-					this.assertEqual(MDUtils.tokenizeURL('(https://example.com/path/page.html?query=foo&bar=baz#fragment) foo'), [ '(https://example.com/path/page.html?query=foo&bar=baz#fragment)', 'https://example.com/path/page.html?query=foo&bar=baz#fragment', null ]);
+					this.assertEqual(MDToken.tokenizeURL('(page.html) foo'), [ '(page.html)', 'page.html', null ]);
+					this.assertEqual(MDToken.tokenizeURL('(page.html "link title") foo'), [ '(page.html "link title")', 'page.html', 'link title' ]);
+					this.assertEqual(MDToken.tokenizeURL('(https://example.com/path/page.html?query=foo&bar=baz#fragment) foo'), [ '(https://example.com/path/page.html?query=foo&bar=baz#fragment)', 'https://example.com/path/page.html?query=foo&bar=baz#fragment', null ]);
 
-					this.assertEqual(MDUtils.tokenizeURL('page.html foo'), null);
-					this.assertEqual(MDUtils.tokenizeURL('(page.html foo'), null);
-					this.assertEqual(MDUtils.tokenizeURL('page.html) foo'), null);
-					this.assertEqual(MDUtils.tokenizeURL('(page.html "title) foo'), null);
-					this.assertEqual(MDUtils.tokenizeURL('(page .html) foo'), null);
-					this.assertEqual(MDUtils.tokenizeURL('(user@example.com) foo'), null);
-					this.assertEqual(MDUtils.tokenizeURL('(user@example.com "title") foo'), null);
+					this.assertEqual(MDToken.tokenizeURL('page.html foo'), null);
+					this.assertEqual(MDToken.tokenizeURL('(page.html foo'), null);
+					this.assertEqual(MDToken.tokenizeURL('page.html) foo'), null);
+					this.assertEqual(MDToken.tokenizeURL('(page.html "title) foo'), null);
+					this.assertEqual(MDToken.tokenizeURL('(page .html) foo'), null);
+					this.assertEqual(MDToken.tokenizeURL('(user@example.com) foo'), null);
+					this.assertEqual(MDToken.tokenizeURL('(user@example.com "title") foo'), null);
 				}
 
 				test_tokenizeEmail() {
-					this.assertEqual(MDUtils.tokenizeEmail('(user@example.com)'), [ '(user@example.com)', 'user@example.com', null ]);
-					this.assertEqual(MDUtils.tokenizeEmail('(user@example.com "link title")'), [ '(user@example.com "link title")', 'user@example.com', 'link title' ]);
-
-					this.assertEqual(MDUtils.tokenizeEmail('(https://example.com) foo'), null);
-					this.assertEqual(MDUtils.tokenizeEmail('(https://example.com "link title") foo'), null);
-					this.assertEqual(MDUtils.tokenizeEmail('(user@example.com "link title) foo'), null);
-					this.assertEqual(MDUtils.tokenizeEmail('(user@example.com foo'), null);
-					this.assertEqual(MDUtils.tokenizeEmail('user@example.com) foo'), null);
+					this.assertEqual(MDToken.tokenizeEmail('(user@example.com)'), [ '(user@example.com)', 'user@example.com', null ]);
+					this.assertEqual(MDToken.tokenizeEmail('(user@example.com "link title")'), [ '(user@example.com "link title")', 'user@example.com', 'link title' ]);
+
+					this.assertEqual(MDToken.tokenizeEmail('(https://example.com) foo'), null);
+					this.assertEqual(MDToken.tokenizeEmail('(https://example.com "link title") foo'), null);
+					this.assertEqual(MDToken.tokenizeEmail('(user@example.com "link title) foo'), null);
+					this.assertEqual(MDToken.tokenizeEmail('(user@example.com foo'), null);
+					this.assertEqual(MDToken.tokenizeEmail('user@example.com) foo'), null);
 				}
 			}