Files

11 KiB

workbook

Native spreadsheet editor written in Ziran with Kryon. Open a document from your file manager, drop it onto Workbook, or pass its path directly:

workbook /path/to/file.gnumeric

The window title shows the document's filename. Edits save back to that file; when you drop another document, Workbook saves the current edit before opening it. Launching without a file uses the profile described below.

Everything in the repository is Ziran (.zi) apart from the Makefile and configuration. src/app.zi is the desktop application, src/engine.zi is the spreadsheet engine, and src/cell.zi is the headless driver. Imported documents use the installed gnumeric library for loading, calculation and saving. New workbooks and CSV use the independent Ziran engine. Document format, dependencies and rendering limitations are covered in format notes.

build & run

Workbook is a Ziran package. ziran.toml names the dependencies and ziran.lock pins the Ziran toolchain and Kryon to exact commits, so a fresh clone builds the same code. Install the ziran command once with make install-user in a Ziran checkout, and have the SDL2 and Cairo development packages installed.

make              # build ./build/workbook-desktop and ./build/cell
make cell         # build only the headless engine driver
make check        # type-check the application, the driver, and the tests
make run          # open the editor
make test         # source audit, structure and conversion tests, desktop test on a private display, gnumeric parity
make test-ci      # the same without parity, which is what CI runs
make gnumeric-test # native document, edit, undo and round-trip regressions
make hidden-rows-test # row visibility, totals and undo/redo on a private display
make parity       # evaluation and round-trip tests against Gnumeric
make fuzz REFERENCE=PATH   # compare this cell with another on generated inputs
make install      # install workbook, cell, and geld under ~/.local
make deb          # build a Debian package

cell eval FILE    # evaluate a .gnumeric/.csv file and print CSV
geld              # the finance profile: a link to workbook

Update the pinned dependencies with ziran update kryon or ziran update ziran and commit the new ziran.lock. To build against sibling checkouts while developing Kryon or Ziran, put their paths in an ignored ziran.local.toml:

[overrides]
kryon = "../kryon"
ziran = "../../ziranlang/ziran"

make test needs xvfb-run, xdotool, xfwm4, dbus-run-session, xmessage, ImageMagick's import, and gnumeric (for ssconvert). The desktop test (tests/desktop_test.zi) runs the editor only on a private Xvfb display; it never opens a window on your desktop. Parity compares against the ssconvert on your path, or against GNUMERIC_SSCONVERT, or a local master build at ~/Tools/gnumeric-1.12.62; the newest catalog functions exist only in a Gnumeric master build, so an older distribution Gnumeric reports those fixtures as different. For imported documents, use a reference from the same installed version, e.g. GNUMERIC_SSCONVERT=/usr/bin/ssconvert make parity. CI runs make test-ci with Gnumeric installed.

The menu test also runs a private Xfce window manager and D-Bus session. It checks that the first right-click after another window has focus shows the menu, that commands act on the clicked cell, and that menus work after resizing. To verify the installed app, run:

WORKBOOK_TEST_APP="$HOME/.local/bin/workbook" build/desktop_test --menu-only

tests/differential_fuzz.zi checks one build of cell against another. Point REFERENCE at a build whose answers are right, for example cell built from an earlier commit, and make fuzz runs the current build and the reference on the same generated inputs, then reports each one they answer differently: random function calls on a fixed sheet, random CSV files, the fixtures with random damage, and workbooks whose sheets refer to each other. SEED and COUNT choose the inputs, and the program can also be run by hand:

build/differential_fuzz REFERENCE build/cell formulas 1 100
build/differential_fuzz REFERENCE build/cell check 'DAY(-2147483648.5)'

A run that hangs is killed after FUZZ_TIMEOUT seconds (20 by default).

editing

arrows            move the selection
Tab               move right
type              start editing the selected cell (replacing its value)
Enter             edit the selected cell; in the formula bar, commit and move down
Esc               leave the formula bar without changing the cell
Delete            clear the selected cell
double click      edit the clicked cell in the formula bar
right click       open the cell menu, including when activating the window
Ctrl+C/X/V        copy, cut, or paste cells through the system clipboard
Ctrl+Z            undo; while a cell is edited, undo its typing word by word
Ctrl+Y            redo (also Ctrl+Shift+Z)
wheel             scroll rows
Ctrl+S            save
Chart button       create a linked formula chart from a selected label/value range

Formula cells show their calculated value in the grid and their source in the formula bar. The toolbar provides save and row/column insertion and deletion, and the sheet tabs at the bottom switch sheets. Cells accept text, numbers, or formulas in the Gnumeric expression language.

Right-click a row number and choose Hide rows to collapse it to a thin line. Shift-click row numbers to select several rows first. Click a thin line to show its row again; both actions support undo and redo. Hidden rows stay in the document. Use =SUBTOTAL(109,A1:A20) for totals that skip hidden rows; ordinary SUM and SUBTOTAL(9,…) continue to include them.

Changes save automatically, including the cell you are typing, pasted values, and inserted or deleted rows and columns. Clicking another cell or closing the app keeps the latest edit without requiring Enter or Ctrl+S. Escape restores the cell's value from before the edit. A failed save leaves the previous file intact, reports the failure in the status bar, and retries automatically.

Undo and redo cover every change: a finished cell edit, paste, cut, clear, fill, and row or column insertion and deletion, each with the formula references it moved. Undoing a change selects the cells it touched again and shows their sheet. Up to the last 100 changes can be undone.

Select a two-column label/value range, then use Chart in the toolbar or Sheet → Create formula chart from selection. Workbook adds a new sheet whose labels and values link to the selected cells, plus a live text bar chart. This portable chart works in ordinary .gnumeric documents and updates when its source values change.

profiles

workbook is the generic profile. geld is a link to the same program; it opens the finance profile, with an independent data directory, because of the name it is started under (WORKBOOK_PROFILE=geld workbook does the same). WORKBOOK_PROFILE=NAME workbook opens any other profile the same way, with its data in $XDG_DATA_HOME/NAME; a name uses lowercase letters, digits, - and _. Harmony starts its Workbook profiles like this. All of them run the same application:

D = units
E = rate
G = value, e.g. =D1*E1
H = diff, e.g. =(E1-OLD_RATE)*D1

The profiles/*.json files are profile metadata, not source code.

data

A workbook is saved as workbook.gnumeric. The generic profile loads from the first of:

WORKBOOK_DIR      generic workbook directory
workbook.gnumeric in the current directory
~/.local/share/workbook/workbook.gnumeric

Geld always uses GELD_DIR when set, or $XDG_DATA_HOME/geld (default ~/.local/share/geld). A workbook in the directory Geld was launched from does not replace its finance profile. Missing data directories are created automatically. Named profiles and explicit data-directory overrides import legacy workbook.json files when no workbook.gnumeric exists beside them; subsequent changes go to workbook.gnumeric, keeping the original JSON intact. Ordinary Workbook launches leave the former finance JSON untouched and start with an empty sheet when no saved document exists.

workbook.json holds private workbook data and is intentionally ignored by git. workbook.example.json is safe sample data for demos.

Embedded grid

Other Kryon apps embed Workbook's grid with the workbook/grid export: the editor's column letters, row numbers, cell squares, theme colors and sheet tabs, showing a real workbook from workbook/engine. Cells hold numbers, text and formulas such as =SUM(B2:B9); columns can have their own width and a count (1,250,734) or money ($12.85) format. The view is read-only and scrolls with the wheel, three rows a notch or a column with Shift. frozen_rows keeps title rows on top, total_rows styles closing rows like headers, and trim draws only the used cells. Hosts whose windows route the wheel themselves fill in GridInput; others use GridSample. The Workbook editor paints its grid with the same squares.

Engine :: #import "workbook/engine";
using Grid :: #import "workbook/grid";
book := Engine.WorkbookNew()
sheet := GridAddSheet(book, "Usage")
unused GridSet(book, sheet, 0, 0, "Folder"); unused GridSet(book, sheet, 0, 1, "Tokens")
unused GridSet(book, sheet, 1, 0, "aurea"); unused GridSet(book, sheet, 1, 1, "4795296906")
unused GridSet(book, sheet, 2, 0, "Total"); unused GridSet(book, sheet, 2, 1, "=SUM(B2:B2)")
Engine.WorkbookEvaluate(book)
view: GridView
view.key = 5000000; view.widths[0] = 180.0; view.formats[1] = GridCount
GridDraw(session, bounds, book, *view, GridSample(session, bounds))

make grid-test checks it.

Werkzeug app bundle

make bundle builds build/workbook.zib, the spreadsheet editor for a host with the spreadsheet.v1 capability. Werkzeug on Linux includes the native calculation service and keeps Workbook documents in its own private folder. The bundle runs in Werkzeug on Linux, Android and the web, with the same compact grid, bottom sheet tabs and editing commands as the desktop editor. Its File menu imports and exports documents with the system chooser on Linux and Android, or a browser upload and download; imported source files stay unchanged. On narrow screens the toolbar includes arrow controls for navigating cells without a keyboard. Linux and the web also offer File → Download Workbook.zx to save the app bundle.

Android and browser hosts use Workbook's built-in calculation engine and save portable Gnumeric documents containing sheets, cell values and formulas. The Linux host also uses Gnumeric for imported documents, preserving their additional formatting and document features. Charts, styles and other native Gnumeric document metadata are not preserved by the built-in document reader.

The native menu bar contains File, Edit, View, Insert and Sheet. Ctrl+O opens a document, Ctrl+Shift+S saves a copy, and F10 or Alt+F focuses the menus.