File Format Support
Summary
Read, write, and preserve are separate concepts
Read means Formulon can parse the structure. Write means it can emit it. Preserve means it can carry it through a round-trip. Only evaluated features affect calculation.
| Area | Status |
|---|---|
.xlsx read | Implemented for workbook, sheets, cells, styles, shared strings, relationships, tables, names, comments, threaded comments and people, hyperlinks, merges, typed AutoFilters, validations, conditional formatting, pivot structures, drawing objects, pictures, shapes, sparkline groups, table slicers, protected ranges, What-If data tables, and custom table styles |
.xlsx write | Writes the modeled workbook features listed above, including typed AutoFilter, picture, shape and chart edits, and preserves package parts where supported; verify business-critical structures in the emitted package |
| Data-validation evaluation | validateValue() checks an explicit proposed value and listInvalidCells() checks stored cell values; neither mutates cells or enforces later edits |
.xlsb read/write | Models/emits styles (including gradient fills and dxf font effects), row/column layout, merges, date1904, calculation settings, workbook properties, every workbook window and its sheet views, frozen and split panes, dynamic-array metadata, supported tokenized formulas, conditional formatting (including custom icon sets), data validation, tables with calculated columns, totals and structured references, sparkline groups, What-If data tables, protected ranges, and sheet/workbook protection metadata. AutoFilters loaded from XLSB remain opaque worksheet tails; typed edits are deferred and reported. Classic notes, threaded comments, and OOXML drawings are omitted on XLSB save and reported; see the XLSB boundaries. |
.xlsm macro bytes | Preserve, never execute |
Legacy .xls | Out of scope |
| Password-protected packages | Not decrypted. An encrypted workbook and a legacy .xls are both OLE compound files, and loading either fails with kIoZipEncrypted; decrypt or convert to .xlsx first |
| Chart structure and data | XLSX: typed reading, creation, editing, and series-data resolution. Charts loaded from XLSB are read-only. Saving refreshes chart series caches from the values currently held by the workbook; references follow row, column, and sheet edits. |
| Engine chart/drawing rendering | Out of scope. XLSX picture bytes and anchors can be probed, read, inserted, and removed; drawing objects and shapes can be listed, and shapes can be inserted, updated, and removed, but the calculation engine does not render charts, shapes, or groups. The browser UI in formulon-cell renders supported charts. |
| Pivot cache refresh from worksheet or external source data | Out of scope; supported cached structures can be preserved and projected |
The CLI picks the output container from the -o file extension. Bindings pick it from the explicit WorkbookFormat passed to saveAs(format) / save_as(fmt). Readers inspect package contents, so a file name does not select the input format.
Load limits
Loading caps how much a package may expand, so a crafted file fails with a host status instead of exhausting memory:
| Limit | Value | Status when exceeded |
|---|---|---|
| One package part, uncompressed | 100 MiB, plus a compression-ratio check | kIoZipBomb |
| All parts read during one load, uncompressed | 256 MiB | kIoFileTooLarge |
Stored cells in one .xlsx worksheet | About 2.98 million (each distinct written coordinate counts; .xlsb is not charged) | kIoFileTooLarge |
| Record slots in one pivot cache (records times cache fields) | 33,554,432 (2^25) | kIoFileTooLarge |
Preservation rule
For XLSX, Formulon semantically owns the typed AutoFilter, picture, and chart operations described above. Charts support typed reading, creation, editing, and series-data resolution in XLSX; charts loaded from XLSB are read-only. Shapes and groups are listed and editable as records; rendering belongs to another tool. For XLSB, an AutoFilter read from the package stays opaque and typed edits are deferred. Classic notes, threaded comments, and OOXML drawings are omitted on XLSB save. Page setup, margins, print options, header/footer, and manual breaks of a workbook that did not come from XLSB are also deferred, as are table slicers from an .xlsx source, security descriptors of protected ranges, workbookPr dateCompatibility and allowRefreshQuery, custom table and PivotTable styles, sparkline groups whose references cannot be encoded, and PivotTables from an .xlsx source; see File formats. saveWithDiagnostics() / save_with_diagnostics() expose these deferred features through deferredFeatureCount / deferred_feature_count. Table slicers loaded from an .xlsb file survive an .xlsb resave. Other features that Formulon does not semantically own are preserved as package structure where practical, so another tool can continue to own authoring or rendering.
Calculation rule
Only features represented in the calculation engine affect recalculation. evaluateAutoFilter() and validateValue() are explicit checks; applyAutoFilter() changes row visibility and marks dependent SUBTOTAL / AGGREGATE formulas dirty, so call recalc() before reading updated values, while validateValue() never stores its proposed value. Preserved structures are not automatically interpreted.
See Filters and validation, Comments and images, and Presentation and geometry for the API boundaries behind this matrix.