Math and formulas

Operators and numbers

Use +, -, *, /, and ^, plus parentheses. ^ is power and groups from right to left. The constants pi ande are built in. Function names are case-insensitive.

Number punctuation follows the vault’s math input convention. The default uses . for decimals and accepts either, or ; between function arguments. A comma-decimal vault uses , for decimals and requires; between arguments. Grouping separators are rejected.; works under either convention when the numbers do not contain a decimal separator.

Units and conversions

Physical units follow a number. Compatible quantities can be added and subtracted, and the result uses the left value’s unit. A bare number can join a quantity and adopts its unit. Multiplying two unit-bearing values or raising one to a power is an error. A same-kind quantity divided by another returns a bare number.

Use to at the top level to convert between compatible units. Chained conversions run from right to left. A bare number has no source unit, so = 5 to km is an error.

Currency uses the prefixes $, €,£, and ¥. Each symbol is its own unit. The symbol may touch the number or be followed by a space.$5 + $3 returns $8. Mixing currencies, as in $5 + €3, is an incompatible-units error. Mudlark does not apply exchange rates or convert one currency to another.

Day and week durations accept d, day,days, w, week, andweeks. They convert like other duration units and display as days or weeks.

Variables

Assign a variable with name = expression inside a math block. Later lines in that block can reuse it. Evaluation runs from top to bottom, and variable names ignore case.

Variables belong to one block. Other math blocks, standalone math lines, inline math, and table formulas cannot read them. Function names and the constants pi and e are reserved and cannot be assigned.

Aggregate hints

Glue a function name to the opener to add a result footer. The block’s plain, successful expression lines become the function arguments. Assignment lines and lines with errors are left out.

Functions that summarize lists include sum,avg, mean, average,stdev, percentile, min,max, count, median,product, and range. Their argument counts still apply. For example, stdev needs at least two values and percentile takes exactly two arguments.

Conditional aggregates and row functions need table context, so they cannot reduce a math block. An unknown hint leaves the body visible, adds an unknown-function label, and omits the footer.

Column aggregates

Pass a column name to an aggregate to use every parsed value in that column. The full column roster is sum,avg, mean, average,stdev, percentile, min,max, count, median,product, and range.

stdev requires at least two values and uses the sample formula. percentile(column, p) takes a percentile from 0 through 100 and uses inclusive linear interpolation. Ordinary aggregates skip blank and prose cells. A formula excludes its own cell when it aggregates the column that contains it.

Row formulas

A bare column name outside an aggregate reads the same row. This is how {=Qty * Price} computes a line total. Row formulas can also mix a current-row value with an aggregate, as in {=Price - avg(Price)}.

A same-row reference must resolve to a number, quantity, or date. A blank or prose cell produces a visible not-a-number error.

Column names and errors

Column references match the resolved header text exactly after ignoring case and surrounding whitespace. Put a multi-word name in quotes, as in {="Unit Price" * Qty} or{=sum("Unit Price")}. Quotes identify a name. They do not create text values or text arithmetic.

An unknown name renders an error in that cell. Mudlark may suggest a close header or tell you to quote a multi-word name, but it never uses that suggestion as the value. Formula matching has no fuzzy fallback. A function name used as a header cannot be referenced. A header containing a quote should be renamed.

Keyed lookups

Price[Widget] reads the Price cell from the row whose first column says Widget. To look through another column, put its name before a colon. Price[SKU: W7] finds the row whose SKU cell says W7.

Value columns, key columns, and keys match their resolved display text exactly after ignoring case and surrounding whitespace. A missing key shows an unknown-row error. A duplicate key shows an ambiguous-row error when referenced. A missing named key column shows an unknown-column error. The header row cannot be a keyed target. A self-reference or a keyed dependency cycle shows a circular error.

Running values and row numbers

running(column) sums from the first data row through the formula’s current row, including that row. Use the same formula in every row. Blank and prose cells are skipped, and the first compatible unit is retained.

sequential() returns the current data row’s 1-based position. Reordering rows renumbers it. above() reads the computed cell directly above in the same column. The first data row has no data cell above, so it errors. A prose value above produces a not-a-number error. Use running(column)for a running total that works unchanged in the first row.

Formula guarantees

Formulas never rewrite source text. The editor keeps the expression verbatim, and the right pane shows its computed projection. Errors also render in place without changing the formula or stopping the rest of the table from resolving.

Header and row matching is exact. Suggestions never change which cell is read. Direct and keyed dependency cycles render a circular error in the cells that take part.

Exports that render values, like plain text, Notion, Apple Notes, and HTML, get the computed value. Round-trip formats, like Mudlark files, Markdown folder exports, and Obsidian, keep the original formula.

Editor help

Typing {= in a table cell opens autocomplete for column names and functions. After a keyed reference’s[, autocomplete suggests row keys. Multi-word names are inserted with quotes.

The command palette has two table actions. Insert Total Row appends sum formulas for unique, referenceable numeric columns and skips date columns. Fill Down copies the current cell’s trimmed source into each later row that has a cell in that column when the source contains a formula.

List and table functions

Single-value functions