Adding spreadsheet formula documentation

js/markdown.js

@@ -3224,6 +3224,7 @@ class MDState {
 			this.#parent.defineAbbreviation(abbreviation, definition);
 			return;
 		}
+		// FIXME: Escape abbreviation
 		this.#abbreviations[abbreviation] = definition;
 		const regex = new RegExp("\\b(" + abbreviation + ")\\b", "ig");
 		this.#abbreviationRegexes[abbreviation] = regex;
@@ -3280,7 +3281,7 @@ class MDState {
 	 * is not provided it will be relative to `this.p`.
 	 * 
 	 * @param {number} minCount - minimum number of lines
-	 * @param {number|null} p - line pointer
+	 * @param {number|null} p - line pointer, or `null` to use `this.p`
 	 * @returns {boolean} whether at least the given number of lines is available
 	 */
 	hasLines(minCount, p=null) {
@@ -3332,8 +3333,14 @@ class MDState {
 		}
 		if (!this.hasLines(1)) return null;
 		for (const reader of this.blockReadersByPriority) {
+			const startP = this.p;
 			const block = reader.readBlock(this);
-			if (block) return block;
+			if (block) {
+				if (this.p == startP) {
+					throw new Error(`${reader.constructor.name} returned an ${block.constructor.name} without incrementing MDState.p. This could lead to an infinite loop.`);
+				}
+				return block;
+			}
 		}
 		const fallback = this.#readFallbackBlock();
 		return fallback;
@@ -3396,6 +3403,9 @@ class MDState {
 				if (token === null) continue;
 				endText();
 				tokens.push(token);
+				if (token.original == null || token.original.length == 0) {
+					throw new Error(`${reader.constructor.name} returned a token with an empty .original. This would cause an infinite loop.`);
+				}
 				p += token.original.length - 1;
 				found = true;
 				break;

markdown.md

@@ -160,6 +160,8 @@ Columns can be right, center, or left aligned with colons in the divider line.
 | 1 | 2 | 3 |
 ```
 
+Tables can optionally support simple [spreadsheet expressions](spreadsheet.md) by adding the spreadsheet block reader when configuring a parser.
+
 ### Definition List
 
 Definition lists show terms with definitions below them. Useful for glossaries.

spreadsheet.md

@@ -0,0 +1,95 @@
+# Spreadsheet Expressions
+
+Spreadsheet expressions are an optional feature not enabled in the default parser configurations. To enable it, include `spreadsheet.js` and create a `Markdown` instance with a `SpreadsheetBlockReader`.
+
+## Expressions
+
+As with many spreadsheet applications, a cell that begins with `=` is treated as a formula.
+
+## Cell References
+
+Values in other cells can be referenced with addresses. It consists of a column letter and an optional row number. When the row number is omitted the row is assumed to be the same as where the expression is located.
+
+Only body rows of a table are included in calculations and can be referenced. Header rows are entirely ignored.
+
+| Address | Description |
+| -- | -- |
+| `=A1` | Value from the leftmost column on the first row |
+| `=C2` | Value from the third column from the left on the second row |
+| `=A` | Value from the leftmost column on the same row as the expression |
+| `=AB1` | Value from the 28th column from the left. Letters proceed A to Z for columns 1 to 26, then AA, AB, AC... for 27, 28, 29.... Limited to 2 letters (676 columns), which is way more than could ever reasonably fit in a markdown table. |
+
+Rows or column references can be fixed for autofilled formulas (discussed below) by using a `$` before the column letters or row number.
+
+| Address | Description |
+| -- | -- |
+| `=$A1` | First column and row. If transposed, the row may change but the column will not. |
+| `=A$1` | First column and row. If transposed, the column may change but the row will not. |
+| `=$A$1` | First column and row even if transposed. |
+
+## Operators
+
+| Operator | Description |
+| -- | -- |
+| _x_ `+` _y_ | Addition |
+| _x_ `-` _y_ | Subtraction |
+| _x_ `*` _y_ | Multiplication |
+| _x_ `/` _y_ | Division |
+| `-`_x_ | Unary minus. Negates an argument. |
+| _x_ `&` _y_ | Concatenate. Produces a text value. |
+| _x_ `<` _y_ | Less than. Produces a Boolean value. |
+| _x_ `<=` _y_ | Less than or equal. Produces a Boolean value. |
+| _x_ `>` _y_ | Greater than. Produces a Boolean value. |
+| _x_ `>=` _y_ | Greater than or equal. Produces a Boolean value. |
+| _x_ `==` _y_ | Equal. Produces a Boolean value. |
+| _x_ `!=` _y_ | Not equal. Produces a Boolean value. |
+| `!`_x_ | Logical not. Produces a Boolean value. |
+
+## Parentheses
+
+Calculations can be grouped in parentheses to affect evaluation order.
+
+| Example | Evaluation order |
+| -- | -- |
+| `=3*4+1*2` | 1. `=12+1*2` (multiply 3 and 4)<br>2. `=12+2` (multiply 1 and 2)<br>3. `=14` (add 12 and 2) |
+| `=3*(4+1)*2` | 1. `=3*5*2` (add 4 and 1)<br>2. `=15*2` (multiply 3 and 5)<br>3. `=30` (multiply 15 and 2) |
+
+## Functions
+
+| Function | Description |
+| -- | -- |
+| `ABS(`_x_`)` | Absolute value |
+| `AND(`_x_`,` _y_`,` ... `,` _z_`)` | Boolean AND of 1 or more arguments |
+| `AVERAGE(`_x_`,` _y_`,` ... `,` _z_`)` | Statistical mean of 1 or more arguments. Non-numeric values are ignored. |
+| `CEILING(`_x_`)` | Rounds a value up |
+| `EXP(`_x_`)` | Raises _e_ to the power of _x_ |
+| `FLOOR(`_x_`)` | Rounds a value down |
+| `IF(`_test_`,` _trueval_`,` _falseval_`)` | Returns _trueval_ if _test_ evaluates to `TRUE`, otherwise returns _falseval_.
+| `IFS(`_test1_`,` _val1_`,` _test2_`,` _val2_`,` ... `,` _fallbackval_`)` | Performs multiple if tests. If _test1_ is `TRUE`, returns _val1_. If _test2_ is `TRUE`, returns _val2_. Etc. If no tests are `TRUE`, the final _fallbackval_ is returned. Takes an odd number of arguments of 3 or more. |
+| `LN(`_x_`)` | Natural logarithm |
+| `LOG(`_x_`,[` _base_`])` | Logarithm with a given _base_, or 10 if _base_ omitted |
+| `LOWER(`_x_`)` | Lowercase of a text value |
+| `MAX(`_x_`,` _y_`,` ... `,` _z_`)` | Maximum of 1 or more values |
+| `MIN(`_x_`,` _y_`,` ... `,` _z_`)` | Minimum of 1 or more values |
+| `MOD(`_x_`,` _y_`)` | Modulo division |
+| `NOT(`_x_`)` | Boolean NOT |
+| `OR(`_x_`,` _y_`,` ... `,` _z_`)` | Boolean OR of 1 or more arguments |
+| `POWER(`_x_`,` _y_`)` | Raises _x_ to the _y_ exponent |
+| `ROUND(`_x_`, [`_digits_`])` | Rounds a number to the nearest integer. If _digits_ is provided, rounds to that number of digits after the decimal place. Negative _digits_ will round to the nearest 10, 100, etc. |
+| `SQRT(`_x_`)` | Square root |
+| `SUBSTITUTE(`_text_`,` _pattern_`,` _replacement_`)` | Replaces all occurrences of _pattern_ in _text_ with _replacement_ |
+| `SUM(`_x_`,` _y_`,` ... `,` _z_`)` | Sum of 1 or more numeric arguments. Non-numeric values are ignored. |
+| `UPPER(`_x_`)` | Upercase of a text value |
+| `XOR(`_x_`,` _y_`,` ... `,` _z_`)` | Boolean XOR of 1 or more arguments |
+
+## Non-Formula Values
+
+Values that are not formulas with recognized values (e.g. numbers, dollar amounts) will be interpreted and reformatted.
+
+## Literal Text
+
+To force a value to behave like text, prefix it with a `'`. E.g. `'0001` will be treated as regular text, not a number, and will not be reformatted. A text value beginning with an equal sign can be prevented from being interpreted as a formula in the same way. `'=A`. The leading apostrophe will be stripped when rendering the table cell. For a literal leading apostrophe, prefix with two apostrophes. `''Kay`
+
+## Errors
+
+If an expression cannot be evaluated, the cell will show an error symbol, such as `#REF`, `#SYNTAX`, or `#ERROR`. A more detailed message is in the `title` attribute and can be seen in a tooltip by mousing over it.