6.4 KiB
Workbook ↔ Gnumeric parity notes
Imported documents use Gnumeric's installed native library, loaded through
src/gnumeric.zi. The native document remains alive for calculation, edits,
structural operations and saves. Undo clones it through an in-memory native
save and load, so document metadata is part of the undo state too.
tests/gnumeric_test.zi covers shared expressions, string time arithmetic,
named expressions, date and decimal formats, literal strings, booleans,
arrays and their edit boundaries, coordinates beyond 256 columns and 65,536
rows, UTF-16 XML, edits, row changes, independent undo snapshots and native
round trips. The source URI is retained for relative workbook links.
Its synthetic tests/document.gnumeric lives outside the CSV fixture folder
because its large coordinates would produce millions of empty CSV fields.
Compare imported files against ssconvert from the same installed Gnumeric
version. A newer reference can have functions or plugins missing from the
runtime library. For the distribution installation:
GNUMERIC_SSCONVERT=/usr/bin/ssconvert make parity
The basic grid displays Gnumeric's formatted cell values. Native document support does not imply complete UI parity: the grid retains its own layout and styling. Cell fonts, fills, borders, sizes, merged regions, charts, drawing objects and print layout are retained on save; drawing objects and print layout are not rendered or edited by the grid. Gnumeric canonicalizes function names to lowercase and exposes a leading apostrophe in entered text for literal strings that resemble formulas. Unknown features from versions newer than the installed Gnumeric are subject to that Gnumeric version's own import limitations.
The notes below describe the file format and Workbook's independent Ziran engine, which still serves new workbooks and CSV. They do not define the native document library's feature inventory.
The .gnumeric container
A .gnumeric file is XML in the http://www.gnumeric.org/v10.dtd namespace,
either plain or gzip-compressed. Gnumeric itself writes gzip; it accepts both
on read. Workbook reads both. Imported documents are saved by Gnumeric in its native
compressed format; new workbooks use the Ziran writer and plain XML.
Minimal document Gnumeric 1.12.57 accepts:
<?xml version="1.0" encoding="UTF-8"?>
<gnm:Workbook xmlns:gnm="http://www.gnumeric.org/v10.dtd">
<gnm:Version Epoch="1" Major="12" Minor="57" Full="1.12.57"/>
<gnm:SheetNameIndex><gnm:SheetName gnm:Cols="256" gnm:Rows="65536">Data</gnm:SheetName></gnm:SheetNameIndex>
<gnm:Sheets>
<gnm:Sheet>
<gnm:Name>Data</gnm:Name>
<gnm:MaxCol>0</gnm:MaxCol><gnm:MaxRow>0</gnm:MaxRow>
<gnm:Cells>
<gnm:Cell Row="0" Col="0" ValueType="40">3.1415899999999999</gnm:Cell>
<gnm:Cell Row="1" Col="0">=A1*2</gnm:Cell>
</gnm:Cells>
<gnm:SheetLayout TopLeft="A1"/>
</gnm:Sheet>
</gnm:Sheets>
<gnm:UIData SelectedTab="0"/>
</gnm:Workbook>
Full document order observed from Gnumeric output:
Version, Attributes, office:document-meta, Calculation, SheetNameIndex, Sheets, UIData. Sheet children order: Name, MaxCol, MaxRow, Zoom, Names, PrintInformation, Styles, Cols, Rows, Selections, Cells, SheetLayout, Solver,
plus optional MergedRegions, Filters, Objects, SheetObjectLayout
blocks. Cell content must be XML-escaped (< > & ").
ValueType attribute
| Code | Meaning | Serialized form |
|---|---|---|
| (none) | formula | text starting with = |
| 20 | boolean | TRUE / FALSE |
| 40 | float | %.17g (e.g. 3.1415899999999999) |
| 50 | error | #DIV/0!, #VALUE!, #REF!, #NAME?, #N/A, #NUM!, #NULL! |
| 60 | string | UTF-8 text |
Integers also serialize as ValueType 40. Empty cells are simply absent.
Styles
gnm:Styles → gnm:StyleRegion startCol/startRow/endCol/endRow →
gnm:Style attributes: HAlign, VAlign, WrapText, ShrinkToFit, Rotation, Shade, Indent, Locked, Hidden, Fore, Back, PatternColor, Format and a
gnm:Font child (Unit, Bold, Italic, Underline, StrikeThrough, Script,
text = font name). Colors are 16-bit-per-channel R:G:B (e.g. FFFF:0:0).
Format is a number-format string (General, 0.00, #$,##0.00, …).
Column widths: gnm:Cols → gnm:ColInfo No="..." Unit="..." Count="..." plus
DefaultSizePts; rows analogous with gnm:RowInfo.
Expression language semantics (verified against 1.12.57)
- Operators by precedence:
:range,intersect, unary-/+,%(÷100),^,*/,+-,&concat, comparisons= <> < > <= >=. &concatenates, coercing numbers to text ("a"&"b"&1→ab1).- Comparisons produce booleans; booleans coerce to 1/0 in arithmetic
(
=(1>2)+(3<>4)→1). - Text operand in arithmetic →
#VALUE!(="x"*2). - Range aggregators (SUM, AVERAGE, …) skip text and empty cells in ranges
but count scalar arguments (
=AVERAGE(A1:A3,10)counts the 10). - References:
A1relative,$A$1absolute, mixed$A1/A$1; sheetsOther!A1; rangesA1:B3,Other!A1:B3, absolute$A$1:$B$3. - Unknown function →
#NAME?; wrong argument domain →#NUM!/#VALUE!; bad reference →#REF!; 0/0 →#DIV/0!; intersection of disjoint ranges →#NULL!. - Booleans render
TRUE/FALSEin CSV export; locale-sensitive rendering is avoided by running underLC_ALL=C.
Function inventory (440 in this install, grouped by Gnumeric plugin)
math 63, stat 103, string 29, financial 40, complex 49, random 34, lookup 20, info 21, date 13, database 13, eng 12, numtheory 9, logical 5, flt 4, christian-date 6, tsa 4, hebrew-date 1, derivatives 1.
The independent Ziran engine implements a subset of the function inventory for new workbooks and CSV. Imported Gnumeric documents use the installed native library's functions and plugins. The current parity suite verifies that document integration, evaluated exports and saved round trips; it is not a separate numerical oracle for the independent evaluator.
1:1 test methodology
Ground truth is the installed Gnumeric itself, never hand-computed:
- Fixture
.gnumericfiles live intests/fixtures/. ssconvert fixture.gnumeric out.csv(LC_ALL=C) → expected values.cell eval fixture.gnumeric→ workbook's own evaluation as CSV.tests/parity_test.zicompares both outputs cell by cell.- Round-trip:
cell copy in out.gnumericwrites a.gnumericthat Gnumeric re-reads with identical evaluated values.