marked-extended-variables

This module provides the capability of embedding variable strings in markdown for use elsewhere in the document. There are additional facilities for math operations.

Notes:

* Imperative definition works (i.e. variables can hold different values at different points in the document).
* Double interpolation is not possible (i.e., composing variable names out of other variables).
* Variable assignments inside of other variable assignments is not possible.
* Variables are hoisted if not yet defined when called. Uses the latest possible contents of that variable.

Markdown Usage

$3

|Syntax|Description|
|------------------|-----------------------------------|
|\[var\]:content | Assigns a variable |
|\[var\]\(content\)| Assigns a variable and outputs it |
|\[var\] | Outputs a variable |

$3

|Syntax |Output|
|-------|------|
|[var]: Variable Contents|Assigns "Variable Contents" to var|
|[var]: Variable Contents
on two
or three
or more lines |Assigns "Variable Contents\non two\nor three\nor more lines" to var|
|[var]:
\| h1 \| h2 \|
\|----\|----\|
\| c1 \| c2 \|| Assigns "\| h1 \| h2 \|\n\|----\|----\|\n\| c1 \| c2 \| to var (and can later be rendered as a table)|
|$var| Assigns "Variable Contents" to var and outputs that value|
|$var| Assigns "I love var2 contents and var3 contents" to var and outputs that value|
|\$[var]| Outputs var contents|
|[var]| outputs the variable contents as a link, if formatted as a valid link|
|![var]| outputs as an image, if formatted as a valid image|
|\$[var]: Variable Contents
or
![var]: Variable Contents| Identical to [var]: Variable Contents . Links, images, and variables all share the same global list. The ! or \$ prefix only matters when the variable is being expressed|
|var
or
!var |Identical to assignment via \$var, but outputs as a link or image if contents are a valid link format|
|\$[num1 + num2 (num3 - round(5.5))] |If +, -, ,/,^,(, or ) are found in the variable name, the whole variable is parsed mathematically with correct order of operations. Only parses if every variable is defined (hoisting works), and evaluate to a number, and the expression is valid. Supports round(x).|

$3

Math currently supports the following function names: round(), floor(), ceil().
It also allows for () nesting operations.

So yes, you can do incrementing tables like this:

``
There are $[TableNum] tables in this document. // Final value of $[TableNum] gets hoisted up: //"There are 2 tables in this document."

$[TableNum]: 0 // Initialize to 0

$[TableNum]: $[TableNum + 1] // TableNum = 1

##### $TableRefKnights

...

$[TableNum]: $[TableNum + 1] // TableNum = 2

##### $TableRefDragons
`

#### Math Functions

|Function|Output|
|--------|------|
|abs(n) | returns the absolute value of the content of n|
|sign(n) | returns the sign of n: + for positive numbers (including zero), - for negative numbers|
|signed(n) | returns the value of n with its sign. In this function, 0 is treated as a positive number, returning +0.|

#### Number Conversions

These use the number 4 as an example value.

|Function|Output|
|--------|------|
|toRomans(4) | display the value of 4 in Roman Numerals (IV)|
|toRomansUpper(4) | display the value of 4 in forced uppercase Roman Numerals (IV)|
|toRomansLower(4) | display the value of 4 in forced lowercase Roman Numerals (iv)|
|toChar(4) | display the value of 4 as its position in the English alphabet (D)|
|toCharUpper(4) | display the value of 4 as its forced uppercase position in the English alphabet (D)|
|toCharLower(4) |display the value of 4 as its forced lowercase position in the English alphabet (d) |
|toWords(4) | display the value of 4 as a word (four)|
|toWordsUpper(4) | display the value of 4 as a word in uppercase (FOUR)|
|toWordsLower(4) | display the value of 4 as a word in lowercase (four)|
|toWordsCaps(4) | display the value of 4 as a word in word capitalization (Four)|




$3

JSON variable members be accessed as a flattened object using dot notation between each parent and child. Flattend array children are zero-based.

##### Example:

`md
[TestJson]: {"a": [{"a":"1","b":"B"},{"a":"2","b":"D"}],"b":"hi!"}

$[TestJson.b]

// output: hi!
`
#### Iterating over JSON Arrays

A new extension of the display variable syntax has been added for walking a JSON array member and outputting the results in a formatted string.

To insert a JSON leaf member variable [XX NEED A GOOD TERM HERE!] into the formatted string, add it as $memberName, as you might in a Brew Variable Math expression. If you need to also use a regular Brew variable, reference it as \$[variableName]. Unmatched variables will be left in place to show the error.

The examples below should help make that clear. Math operations functions may also be applied.

`
+[JSONNodeLeaf]:Formatting string
`

`
[TestJson]: {"a": [{"a":"1","b":"B"},{"a":"2","b":"D"}],"b":"hi!"}
|Column 1|Column 2|
|--------|-------|
+[TestJson.a]:| $[$a*2] | $b |
`

Results in:

|Column 1|Column 2|
|--------|-------|
|2|B|
|4|D|

In this example we are walking the array that is found at TestJson.a - [{"a":"1","b":"B"},{"a":"2","b":"D"}]. The formatting string is looking for members a and b in each object of the array, which are present.
On the first array member (0) - \$a corresponds with TestJson.a.0.a (value of 1) and then output as $[1\2]. \$b corresponds with TestJson.a.0.b and outputs 'B'. Finally, the math operations on the .a* members are performed and output.

#### Additional formatting notes
* \n in a formatting string is translated to a CR insertion.

Project Usage

`js
import { marked as Marked } from 'marked';
import { markedVariables,
setMarkedVarPage,
setMarkedVariable,
getMarkedVariable,
clearMarkedVarsQueue } from 'marked-variables';

// We're only going to use one page
// in this example, so we'll hardcode the
// values.

Marked.use(markedVariables());

setMarkedVarPage(0);
clearMarkedVarsQueue();
setMarkedVariable(0, 'pageNumber', 1);

const html = Marked.parse("[varName]:foo\n\nHello, my name is $[varName].\n\n");
console.log(html);
//

Hello, my name is foo.

\n

 

\n
``