docs/formulas/tracing.md covers showing precedents and dependents, going to one, stepping through them and Evaluate formula; keys.md, building.md, the UX cues, architecture and limits point to it. The tracing tape records the demo the page shows.
- commit
- 0b04451fb700777efbe75520ed74e7cfa6b32e3e
- parent
- b64f7a1dfc217b2c61dd7ae97088011568e1a1eb
- author
- Dami <dami.etoile@gmail.com>
- kind
- docs risk score 0.1 of 3, Jev's estimate
| M | README.md | 4 | +- |
| M | ROADMAP.md | 4 | +- |
| A | demos/ | 54 | ++++++++++++++++++ |
| M | docs/ | 16 | ++++-- |
| M | docs/ | 1 | + |
| M | docs/ | 3 | +- |
| M | docs/ | 3 | +- |
| M | docs/ | 8 | +-- |
| A | docs/ | 88 | ++++++++++++++++++++++++++++++ |
| A | docs/ | bin | |
| M | docs/ | 5 | +- |
@@ -29,7 +29,9 @@ rest: building from a clone, importing files, `012 serve` and settings.
2929 suggestions and argument hints, pointing at cells with the arrows or the3030 mouse, named ranges, references between sheets, arrays that spill3131 (FILTER, SORT, UNIQUE, LAMBDA), optional decimal32- arithmetic for money, and undo for everything32+ arithmetic for money, undo for everything, and33+ [tracing](docs/formulas/tracing.md) that marks what a formula reads34+ and what reads it and steps through it part by part3335 ([formulas](docs/formulas/README.md)); numbers, dates and formulas3436 typed and shown in a [locale](docs/sheets/locale.md) per file.3537 - **Data tools**: freeze, sort, filter, find and replace, conditional@@ -70,7 +70,6 @@ shared editing in section 3.
7070 |---|---|---|7171 | Commands for scripts without the screen: `012 get`, `012 set`, `012 recalc`, `012 export` on a workbook file | 012 in scripts, cron and nushell pipelines | S to M |7272 | `012 diff` cell by cell (values, formulas, formats, regions) and a git diff and merge driver for `.012` | Sheets kept in git review like code | M |73-| Formula tracing: precedents and dependents shown in the grid, a formula evaluated step by step | Finding why a number is wrong | M |7473 | Named tables with structured references (`Sales[Amount]`); notebook regions are tables | Formulas that read by column name | M |7574 | A sheet or chart exported as a static HTML page in 012's look | Sharing a sheet with someone without 012 | S |7675 | Release archives and an install script served from the owner's nzip server | Installing without Go | S |@@ -108,7 +107,8 @@ stream above rather than a design of their own.
108107 109108 - Sheets-structured menus, a command palette and a key for every command: [Keys and mouse](docs/reference/keys.md)110109 - Formula suggestions, argument hints and pointing at cells and sheets: [Building formulas](docs/formulas/building.md)111-- Tracing precedents and dependents, hidden sheets explained: [Building formulas](docs/formulas/building.md)110+- Tracing precedents and dependents, hidden sheets explained: [Tracing formulas](docs/formulas/tracing.md#stepping-through-them)111+- Formula tracing: precedents and dependents marked in the grid as the pointer moves, named ranges, spills, regions and their sources included, listed to go to, and a formula evaluated step by step: [Tracing formulas](docs/formulas/tracing.md)112112 - An optional vim keymap with a `:` command line: [Keys and mouse](docs/reference/keys.md#vim-keys)113113 - Vim `.` repeat, registers, marks, `cc` and `s`, `:` line history and `:w!`: [Keys and mouse](docs/reference/keys.md#vim-keys)114114 @@ -0,0 +1,54 @@
1+# Tracing: with precedents and dependents shown, the pointer on North's2+# revenue marks the regions and revenues it reads and the price per unit3+# that reads it; then Evaluate formula steps through the price, into4+# the revenue it reads and back out.5+Output out/tracing.gif6+Source lib/setup.tape7+8+Hide9+Type "../bin/012 data/sales.csv" Enter10+Sleep 2s11+Ctrl+G12+Type "F1" Enter13+Type "North" Enter14+Type@40ms '=SUMIF(A2:A17,"North",D2:D17)' Enter15+Type "Units" Enter16+Type@40ms '=SUMIF(A2:A17,"North",C2:C17)' Enter17+Type "Per unit" Enter18+Type@40ms "=F2/F4" Enter19+Show20+21+Sleep 800ms22+Ctrl+K23+Type@60ms "show precedents"24+Sleep 800ms25+Enter26+Sleep 3s27+Ctrl+G28+Type "F2" Enter29+Sleep 3s30+Screenshot out/stills/tracing-marks.png31+Down@600ms 232+Sleep 1.5s33+Down@600ms 234+Sleep 2s35+Ctrl+K36+Type@60ms "evaluate formula"37+Sleep 800ms38+Enter39+Sleep 1.5s40+Right41+Sleep 1.5s42+Screenshot out/stills/tracing-into.png43+Enter44+Sleep 1.2s45+Left46+Sleep 1.5s47+Screenshot out/stills/tracing-evaluate.png48+Enter49+Sleep 1.2s50+Enter51+Sleep 2s52+Screenshot out/stills/tracing-value.png53+Escape54+Sleep 1s@@ -41,6 +41,7 @@ internal/ui the Bubble Tea model: modes, menus, overlays, rendering
4141 cmdline the : command line and its completions4242 nbview a notebook tab: its cells, outputs, command and edit modes, the code editor and its language providers4343 findbar find and replace, a bar on the context line44+ evalview Data > Evaluate formula: a formula stepped through part by part4445 themepicker File > Settings > Theme, previewing as it moves4546 rules the conditional formatting and data validation panel4647 sortbar the sort bar: the columns and order to sort a range by@@ -396,8 +397,12 @@ recalculations, so the buffers are made once. See
396397 What stays in the engine is what needs cells or the workbook: the397398 running aggregates' storage and extension (`rangememo.go`), the links a398399 HYPERLINK cell opens (`link.go`), the questions a cell's JEV formulas ask399-(`RemoteCalls`), explaining errors (`explain.go`) and the decimal400-setting (`SetDecimal`, which marks formulas with `functions.Decimalize`).400+(`RemoteCalls`), explaining errors (`explain.go`), tracing precedents401+and dependents through the dependency indexes (`trace.go`,402+`tracedeps.go`), stepping through a formula (`steps.go`, where the403+function library records each part's value where it stands,404+`functions.EvalParts`) and the decimal setting (`SetDecimal`, which405+marks formulas with `functions.Decimalize`).401406 402407 ### Where the engine can grow403408 @@ -473,14 +478,14 @@ draw. The components:
473478 | edit line | `lineedit.Line` | the one-line editor shared by cell entries, prompts and search fields (package `lineedit`) |474479 | cell entry | `entry`, `suggest.List` | typing into a cell, pointing at references, other sheets while pointing (`entry.go`, `assistsheets.go`); formula suggestions and signatures (package `suggest`, with `assist.go`) |475480 | prompt | `prompt` | a question on the context line, typed or pointed at (`prompt.go`) |476-| overlays | `overlay.Overlay` | whatever has taken over input: menus (`menuoverlay.go`), the palette and pickers (package `picker`, with `palette.go`, `names.go`), the command line (package `cmdline`), the theme picker (package `themepicker`), the find bar (package `findbar`), the filter picker (package `filterpick`, with `filter.go`), the sort bar (package `sortbar`, with `sort.go`), choice bars (package `choicebar`, with `dialog.go`), the chart editor and selection (`charteditor.go`, `chartsel.go`), the pivot editor (`pivoteditor.go`, `pivotactions.go`), the rules panel (package `rules`, with `rules.go`), the shortcuts (package `shortcuts`, with `help.go`) |481+| overlays | `overlay.Overlay` | whatever has taken over input: menus (`menuoverlay.go`), the palette and pickers (package `picker`, with `palette.go`, `names.go`), the command line (package `cmdline`), the theme picker (package `themepicker`), the find bar (package `findbar`), the filter picker (package `filterpick`, with `filter.go`), the sort bar (package `sortbar`, with `sort.go`), choice bars (package `choicebar`, with `dialog.go`), the chart editor and selection (`charteditor.go`, `chartsel.go`), the pivot editor (`pivoteditor.go`, `pivotactions.go`), the rules panel (package `rules`, with `rules.go`), the shortcuts (package `shortcuts`, with `help.go`), Evaluate formula (package `evalview`, with `evaluate.go`) |477482 | sheet tabs | `tabstrip.Strip` | where each sheet was left, the tab strip's scroll and layout (package `tabstrip`); what clicks on it do (`tabstrip.go`) |478483 | mouse | `mouseState` | drags, hover, double clicks, the fill handle (`mouse.go`, `fill.go`) |479484 | import | `transfer.Transfer`, `pipeState` | the import in progress, its progress display and cancelling (package `transfer`); choosing and placing imports (`transfer.go`, `importplace.go`); standard input read as a sheet, and what a pipeline gets on quitting (`pipe.go`) |480485 | linked files | `followState` | a source (`live.Source`) for each linked region, polled one poll at a time on a command every `live.Interval` and reconciled with the workbook after every update, so undo, opening a file and unlinking need nothing of their own; trust in files outside a workbook's folder (`follow.go`); Data > Linked file and Import's Follow the file (`linked.go`) |481486 | notebooks | `nbview.View`, `nbState` | a view of each notebook tab, its selection, mode, scroll and editor (package `nbview`); the tab on the screen (`nbscreen.go`); the notebook's commands and keys (`notebook.go`); cells running one at a time in the background, their queue, stale outputs, trust (`nbrun.go`); what a run reads (`nbjob.go`); outputs sent to sheets (`nbsend.go`) |482487 | macros | `recorder`, `macroState` | a recording in progress (`macrorec.go`); a macro running, trust in the file's macros (`macrorun.go`); what scripts act on (`macrohost.go`, `macrohostnav.go`); Data > Macros and the manager (`macro.go`, `macromanage.go`) |483-| others | `clipboard`, `trace`, `chartState`, `jevRunner`, `terminal`, `session` | what Ctrl+V pastes, a trace being shown, chart commands' target, JEV questions in flight, what the terminal supports and the chart images sent to it, what outlasts the file open (the `:` history, whether keys can be held: `keyboard.go`) |488+| others | `clipboard`, `trace`, `traceView`, `chartState`, `jevRunner`, `terminal`, `session` | what Ctrl+V pastes, a trace being stepped through and tracing that stays on (`traceview.go`), chart commands' target, JEV questions in flight, what the terminal supports and the chart images sent to it, what outlasts the file open (the `:` history, whether keys can be held: `keyboard.go`) |484489 485490 Overlays implement `overlay.Overlay` (package `overlay`): an indicator for486491 the mode, `Key` and `Mouse` handlers, a `Layout` of boxes to draw, and@@ -502,6 +507,7 @@ methods off `ui.Model`'s exported API:
502507 | `picker` | `picker.Host` | theme, size, the edit line, close, record the answer to a command's question (5) |503508 | `choicebar` | `choicebar.Host` | theme, close, record the key chosen (3); the choices are closures over the model |504509 | `shortcuts` | `shortcuts.Host` | theme, size, close, the rows, built from the key bindings and the registry (4) |510+| `evalview` | `evalview.Host` | theme, size, close, the locale (4); the formula's steps are the engine's `sheet.Steps` |505511 | `sortbar` | `sortbar.Host` | theme, size, the sheet, close, sort (recorded as the bar's command) (5) |506512 | `filterpick` | `filterpick.Host` | theme, size, the edit line, close, the locale (5); what applying and cancelling do are callbacks, as the sheet's filter and a pivot's differ |507513 | `cmdline` | `cmdline.Host` | theme, size, the edit line, close, the commands to complete, run a line, fail, the session's history (8) |@@ -552,7 +558,7 @@ hints) are what every overlay is drawn with.
552558 **Packages.** `theme`, `rowtext`, `formula`, `overlay` and `lineedit`553559 depend on nothing in `ui`, so they can be tested and measured alone. The554560 components in `picker`, `cmdline`, `nbview`, `themepicker`, `findbar`, `rules`,555-`sortbar`, `filterpick`, `choicebar`, `shortcuts`, `suggest`, `tabstrip`561+`sortbar`, `filterpick`, `choicebar`, `shortcuts`, `evalview`, `suggest`, `tabstrip`556562 and `transfer` build on them and reach the model only through their557563 hosts, with unit tests of their own against fake hosts. A component moves out of package558564 `ui` when its host stays small (about ten methods or fewer); one that@@ -29,6 +29,7 @@ it lags, and past a second it stalls.
2929 | Incremental recalc | A change that makes formulas read under about 500,000 cells in total (fan-out, chains and volatiles of 8192 cells: 1.3 to 1.9 ms); 1000 SUMs over a full column: 0.53 ms; 8192 running totals: 2.7 ms | 60 criteria functions (SUMIF, COUNTIFS, AVERAGEIF) over whole columns of 8192 rows: 29 ms an edit | | About 3 ns per cell read: an index into the column's block |3030 | Full recalc | Any sheet: numbers and text hold their values and cost nothing; 1000 full-column SUMs 0.5 ms; 8192 running totals 1.8 ms | 60 whole-column criteria functions over 8192 rows: 44 ms | | Same as above |3131 | Rendering | Any sheet at up to 200 x 60: 1.3 ms a frame; 400 x 120: 4.2 ms; a color scale on every cell shown adds 0.4 ms at 200 x 60, borders on every cell and wrapped text 0.4 ms | 20 charts at 400 x 120: 6 ms | | View building styled strings, then Bubble Tea parsing and diffing them |32+| Tracing (`BenchmarkTrace`) | An arrow key through to its frame at 200 x 60 with tracing on, on a million cells: a chain of a million formulas 0.66 ms (0.64 off), a million numbers 0.82 ms (0.82 off), a cell read by a million formulas 1.6 ms (0.85 off); off, it costs nothing | | A cell's dependents listed past a thousand: the list says there are more | Finding a cell's links (dependents capped at a thousand), and asking each formula on screen whether it reads the cell |3233 | Selection statistics | Any selection: extending one over all 2.1 M cells of 8192 x 256 costs 0.3 ms a key | | | Per column with data, 1024 or 64 rows at a time from an index on the blocks of filled cells, plus the rows at the selection's ends |3334 | Imports | CSV, SQLite, Parquet: 2 to 4 M cells/s (a million cells in 0.25 to 0.4 s); XLSX numbers or text: 0.8 to 1.4 M cells/s | XLSX with formulas: 0.4 to 0.6 M cells/s | Data past `max-cells` or the grid (dropped, with a note); XLSX files past the reader's limits (refused) | Building cells one at a time; XML decoding; XLSX formula translation |3435 | Undo | One step of any size: undo costs what the edit cost; clearing all ten million cells of a full sheet holds 193 MB | History capped at 100 steps and 256 MB of before-images: 100 whole-column steps hold 15 MB | A step past 1 GB (millions of formulas or long distinct texts at once): asks, and runs without undo if told to | Before-images in the store's form: a slot (20 B) per plain cell, a whole `Cell` per formula |@@ -105,7 +105,8 @@ there.
105105 | Notes | A `▝` in the cell's top-right corner |106106 | Macro recording | `REC` beside the mode indicator |107107 | Mode | The mode indicator's word (`READY`, `ENTER`, `POINT`, `MENU`, and on a notebook `NOTEBOOK`, `EDIT` or `OUTPUT`) |108-| Search matches, traced cells | Reverse video, with a count or the list on the context line |108+| Search matches, traced cells | Reverse video, with a count or the list on the context line; dependents also bold |109+| Evaluate formula | The part computed next underlined and bold, values in its place italic, and `Next` and `Value` in words |109110 | The copied range | A dashed underline |110111 | Dropdowns, checkboxes, active filters | `▾`, or a chip in reverse video between `▐` and `▌`; `[ ]` and `[✓]`; `▼` instead of `▾` |111112 | Data bars, icon sets | Eighth blocks as long as the number, and reverse video under the text they run beneath; the icon's glyph (`↑`, `◑`, `✓`, `▆`) |@@ -72,7 +72,8 @@ numbers as numbers.
7272 | Page | For |7373 |---|---|7474 | [References](references.md) | Cells, ranges, names, other sheets, and a range where one value is wanted |75-| [Building formulas](building.md) | Pointing, suggestions, argument hints, tracing |75+| [Building formulas](building.md) | Pointing, suggestions, argument hints |76+| [Tracing formulas](tracing.md) | Precedents and dependents in the grid, and a formula evaluated step by step |7677 | [Arrays and spills](arrays.md) | FILTER, SORT, UNIQUE, SEQUENCE, ARRAYFORMULA, LET and LAMBDA |7778 | [Decimal arithmetic](decimal.md) | Exact decimal math for money |7879 | [JEV functions](jev.md) | Asking a hosted model from formulas |@@ -15,11 +15,9 @@ sidebar_position: 3
1515 sheets aren't offered, though formulas still read them.1616 - Inside a function's parentheses the context line shows its signature with1717 the current argument marked, e.g. `SUMIF(range, criterion, [sum_range])`.18-- Alt+, and Alt+. trace precedents and dependents: the cells a formula reads19- and the formulas that read a cell. Press again to step through them.20- Cells on hidden sheets are skipped; when that leaves nothing, the21- context line names the hidden sheets ("Reads only Data, a hidden sheet;22- View > Hidden sheets shows it").18+- Alt+; marks what the active cell's formula reads and the formulas that19+ read it, as the pointer moves; Alt+= steps through a formula one part20+ at a time. See [Tracing formulas](tracing.md).2321 - A formula left Automatic shows the format of what it reads: `=B5*2` of2422 a currency cell shows currency, and so does `=SUM(B2:B9)`. A blank cell2523 counts with its column's, row's or sheet's format, and changing those@@ -0,0 +1,88 @@
1+---2+title: "Tracing formulas"3+sidebar_position: 64+---5+6+# Tracing formulas7+8+When a number looks wrong, trace it: the cells its formula reads (its9+precedents), the formulas that read it (its dependents), and what each10+part of the formula computes.11+12+13+14+## Showing precedents and dependents15+16+Data > Formula tracing > Show precedents and dependents (Alt+;) marks them in the grid as17+the pointer moves: the cells the active cell's formula reads in green,18+the formulas that read the active cell in magenta and bold. Without19+color both are in reverse video, dependents bold as well. The context20+line lists them all, those off screen with an arrow toward them and21+those on other sheets with their sheet:22+23+```24+C7 reads B3, Rate, Data!B2:B9; read by D7, A40↓, Summary!B2 +3 more25+```26+27+Alt+; again stops. What counts as a link:28+29+| The active cell | Its precedents | Its dependents |30+|---|---|---|31+| A formula | the cells and ranges it reads, on any sheet; a named range or a region (`nu.sales`) by its name | the formulas that read it through a reference, a range, a named range or a region's name, on any sheet |32+| A formula whose array spills | as any formula | the cells it spills into, and the formulas reading any of them |33+| A value an array spilled | the formula that spilled it | the formulas reading it |34+| A cell of a linked file or of a notebook output sent to the sheet ([regions](../nushell/notebooks.md)) | the file, or the notebook cell | the formulas reading it, `nu.name` included |35+36+Only direct links show; go to one and tracing shows its own, a level37+further. Excel draws arrows between cells; 012 marks the cells and lists38+the rest, which reads the same for a range on another sheet or far off39+screen.40+41+## Going to one42+43+Data > Formula tracing > Go to a precedent or dependent (Alt+') lists44+the active cell's precedents, then its dependents, with what each is45+(`precedent, named range B2:B9`, `dependent, on Summary`). Type to narrow the46+list; Enter goes to one, selecting a range, showing another sheet, or a47+notebook's cell. A cell read by more than a thousand formulas lists the48+first thousand.49+50+## Stepping through them51+52+Alt+, and Alt+. step through the precedents and the dependents, as53+Excel's Ctrl+[ and Ctrl+], which terminals send as Esc: the first press54+marks them all and jumps to the first, each press after to the next,55+and Esc goes back to the cell traced. Cells on hidden sheets are56+skipped; when that leaves nothing, the context line names the hidden57+sheets ("Reads only Data, a hidden sheet; View > Hidden sheets shows58+it").59+60+## Evaluating a formula step by step61+62+Data > Formula tracing > Evaluate formula (Alt+=), after Excel's63+Evaluate Formula, opens a box over the grid with the active cell's64+formula. The part computed next is underlined, and the line under it65+says what it computes:66+67+```68+┌─ Evaluate D1 ────────────────────────────────────────┐69+│ =IF(TRUE,SUM(A2:A3)*2,A3) │70+├──────────────────────────────────────────────────────┤71+│ Next SUM(A2:A3) = 5 │72+└───────────────────────────────────────────── 2 of 5 ─┘73+```74+75+- Enter puts the value in its place, in italic, and underlines the next76+ part, until the formula's value is all that's left; Enter then starts77+ over.78+- → steps into the underlined part when it's a reference to another79+ formula: the box shows that formula, and its title the way in80+ (`Evaluate D1 › B1`). ← or Esc steps back out, the reference's value81+ in its place. Esc at the first formula closes the box.82+83+The values are what the formula computes where each part stands: an84+array where the part is read as one (`SUM(A1:A9*2)` shows the doubled85+column, `{2;4;…}`), names bound inside `LET`, and nothing for the branch86+`IF`, `IFERROR` or `CHOOSE` didn't take, which stays as written. A blank87+cell reads as 0. The formula is written in the88+[locale's](../sheets/locale.md) syntax, spaced as 012 stores it.Binary file.
@@ -94,7 +94,10 @@ The rest of the formats are in the Format menu.
9494 | Ctrl+F, Ctrl+H | Find; find and replace | [Find and replace](../sheets/find-replace.md) |9595 | Alt+Down | Open the active cell's dropdown (type to search, Enter picks); elsewhere, with a filter on (Data > Create a filter), the column's filter (Space checks values, type to search, or pick a condition) | [validation](../sheets/rules.md#data-validation), [filter](../sheets/sort-filter.md#filter) |9696 | Space | Check or uncheck the selected checkboxes (Insert > Checkbox); elsewhere Space starts an entry | [Conditional formatting and data validation](../sheets/rules.md#data-validation) |97-| Alt+, Alt+. | Trace precedents, dependents: highlight the cells a formula reads, or the formulas that read the cell, and jump to the first; again for the next, Esc to go back (Excel's Ctrl+[ and Ctrl+], which terminals send as Esc) | [Building formulas](../formulas/building.md) |97+| Alt+, Alt+. | Trace precedents, dependents: highlight the cells a formula reads, or the formulas that read the cell, and jump to the first; again for the next, Esc to go back (Excel's Ctrl+[ and Ctrl+], which terminals send as Esc) | [Tracing formulas](../formulas/tracing.md#stepping-through-them) |98+| Alt+; | Show precedents and dependents: mark them as the pointer moves and list them on the context line; again to stop | [Tracing formulas](../formulas/tracing.md) |99+| Alt+' | Go to a precedent or dependent, picked from a list | [Tracing formulas](../formulas/tracing.md#going-to-one) |100+| Alt+= | Evaluate formula: step through the active cell's formula one part at a time; Enter evaluates, → steps into a reference, ← steps out | [Tracing formulas](../formulas/tracing.md#evaluating-a-formula-step-by-step) |98101 | Alt+Shift+F | Frequency table of the active column on a new sheet, as VisiData's Shift+F | [Pivot tables](../sheets/pivots.md#frequency-tables) |99102 | Shift+F2 | Add or edit the active cell's note; Alt+Enter or Shift+Enter starts a new line | [Notes and protection](../sheets/notes-protection.md#notes) |100103