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.