@apertura/formula
The Excel formula language: lexer, parser, evaluator and function library
69 exported symbols · 69 declared here · 0 re-exported
Classes
An Excel error value. Interned, so identity comparison works.
A reference. Kept as a value in its own right rather than resolved to numbers on sight, because a dozen functions care *where* their argument is and not only what is in it: `ROW`, `COLUMN`, `OFFSET`, `INDEX` (which returns a reference), `CELL`, `ISREF`, and every function whose criteria argument is a range. More than one area happens through the union operator: `SUM((A1:A5,C1:C5))`.
Functions
Builds a matrix of the given shape.
The format code of a built-in id, or `undefined` when the id is not reserved.
Compares two scalars the way `<` and `MATCH` do. Returns a negative number, zero or a positive number. Blanks are compared as the zero or empty text of whatever they meet, which is why `A1=0` and `A1=""` are both true when A1 is empty.
Compiles a `COUNTIF`-style criterion. The grammar: an optional comparison operator, then a value. Without an operator it is equality — and equality against text applies wildcards, which is why `COUNTIF(A:A,"a*")` counts everything beginning with an `a`.
Compiles a format code, or returns the cached compilation.
A constant node's value, for the few places that only accept constants.
The inverse: a `Date` as the serial number Excel would store for it.
A workbook context with nothing in it, for evaluating a bare expression.
The first error anywhere in a value, which is what propagates.
Excel's `General`. Not "the number as JavaScript prints it": Excel keeps about eleven significant digits and falls back to scientific notation outside a fixed range, which is why `0.1 + 0.2` shows as `0.3` in a spreadsheet and as something longer in a console.
A number as `General` renders it. Fifteen significant digits, which is the precision Excel keeps and the reason a spreadsheet shows `0.3` where a console shows the rounding error.
Formats a value the way Excel would with the given code. `code` is the format string, not the id: resolving an id through the workbook's `numFmts` and the built-in table happens in the style layer, which is the only place that knows both.
Looks up an indexed colour, falling back to the default palette.
Whether a format code shows a date or a time rather than a number.
Whether the code contains a text section, which is what makes it apply to strings.
Reads a matrix with Excel's broadcast rules: a single row or column repeats.
Strips the `_xlfn.` prefix. Functions added after 2007 are stored with it so that older versions fail predictably instead of silently. `_xlfn.IFS` and `IFS` are the same function and the library should only have to know one name. The `_xlws.` prefix, for worksheet-only functions, works the same way.
Text that Excel accepts as a number. Deliberately stricter than `Number()`: `"1e5"` and `"0x10"` are numbers to JavaScript and text to Excel, and `""` is zero to `Number()` and an error here. Percentages, leading currency symbols and thousands separators are accepted, because Excel accepts them.
Rounds the way a spreadsheet does: half away from zero, at a decimal place.
Converts a serial number to a JavaScript `Date` in UTC.
Converts a serial number to calendar parts. Returns `undefined` for values Excel itself refuses to show as a date: negative serials in the 1900 system produce `#####`, not a date before the epoch.
The single value a cell shows for a computed result.
Coerces to a number, as an arithmetic operator would.
Coerces to text. A number becomes what `General` would show, not what JavaScript prints: concatenating 0.1 + 0.2 must produce `0.3`, not `0.30000000000000004`.
Excel's wildcards: `*` any run, `?` one character, `~` escapes either. Returns `undefined` when the text holds no wildcard at all, so the caller can take the cheaper equality path.
Interfaces
One rectangular area of a sheet, zero-based and inclusive.
One argument of a function call, evaluated on demand.
Where a formula lives. Every relative reference is resolved against it.
Whole and fractional parts of a serial number, in calendar terms.
The result of formatting a value with a format code.
A reference as written, before it is resolved against a workbook.
A table, for structured references.
Type aliases
Everything a formula can evaluate to.
A rectangular block of values, row-major. Arrays in Excel are always 2D.
A single value: a number, text, a logical, an error, or a blank.
Values
How many modules the library is built from. Reading it keeps them alive.
The function library. Modules add to it as they are imported.
Automatic colour: whatever the window text colour is.
The window background colour.
The legacy indexed colour palette. Before themes, a workbook referred to colours by index into a 56-entry table that lived in the file (`<indexedColors>`) and, when it did not, was assumed to be this one. Files still arrive with `indexed="10"` on a font, and number format codes still say `[Color 10]`, so the default table has to be here even though nothing has written it deliberately in twenty years. Indices 0-7 repeat as 8-15: the first eight are the "system" colours and the second eight are the same colours in the user-editable part of the palette. Index 64 is "automatic" — the window text colour — and 65 the window background; both are resolved by the renderer rather than by a table.