docs/manual/guide/10-tables.org
569 lines · 31918 bytes
1#+TITLE: Tables
2#+DESCRIPTION: Creating and editing Org tables, column widths, import and export, and spreadsheet formulas.
3#+LEDE: Org tables are plain text that Orgstar keeps aligned, edits by row and column, and recalculates with the same formulas Emacs uses.
4
5* Tables in Org
6
7A table is a run of lines that start with =|=. Fields are separated by =|=, and a line
8that starts with =|-= is a horizontal rule:
9
10#+BEGIN_SRC org
11| Name | Qty | Price |
12|-------+-----+-------|
13| Apple | 3 | 0.50 |
14| Pear | 12 | 0.75 |
15#+END_SRC
16
17Orgstar follows =org-table.el= from Org 9.8.7, with =org-table-automatic-realign= on,
18=org-table-tab-jumps-over-hlines= on, and formulas adjusted without asking when rows
19and columns move (=org-table-fix-formulas-confirm= nil). Tables inside dynamic blocks
20count as tables; tables inside other blocks don't.
21
22* Creating a table
23
24Type =|=, a few field names separated by =|=, and press =TAB=: Orgstar aligns the line
25as a table and moves to the next field, adding a row after the last one. Type =|-= on
26the line below a row and press =TAB= to turn it into a full-width rule.
27
28=org-table-create-or-convert-from-region= builds one for you: ~C-c |~ in the Emacs
29and Doom presets, =⌃⌘\= in the Mac preset.
30
31With no selection it asks =Table size Columns x Rows [e.g. 5x2]:=. An empty answer
32makes a 5 × 2 table. When there is more than one row, a rule follows the first row.
33
34With text selected, the command converts the selected lines to a table instead
35(=org-table-convert-region=). The separator is guessed:
36
37- tabs, when every line has a tab;
38- otherwise commas, when every line has a comma, read as CSV: a field in double quotes
39 can hold commas, and a line break in it becomes a space;
40- otherwise runs of spaces.
41
42* Moving around and alignment
43
44| Key | Org command | Action |
45|---------+----------------------------+----------------------------------------------------------------------------|
46| =TAB= | =org-table-next-field= | Aligns the table and moves to the next field, skipping rules. In the last field it adds a row. |
47| =S-TAB= | =org-table-previous-field= | Aligns the table and moves to the previous field. |
48| =RET= | =org-table-next-row= | Aligns the table and moves down a row in the same column. Before a rule or at the end of the table it inserts a row. |
49
50These keys work the same in the Emacs and Mac presets. In Doom they apply in insert
51state; in normal state =RET= is Doom's "act at point" (see /Recalculating/).
52
53Alignment (=org-table-align=) pads every field to its column's width and redraws
54rules to match. A column is right-aligned when at least half of its non-empty fields
55are numbers, and left-aligned otherwise. A field that holds only a cookie =<l>=, =<c>=
56or =<r>= (optionally with a width, such as =<r10>=) fixes the column's alignment.
57Widths count display columns, so wide characters and hidden link markup are measured
58as they appear.
59
60Alignment happens when you press =TAB=, =S-TAB= or =RET= in a table and after every
61table command, not while you type. To align without moving, use Org ▸ Align Table:
62
63| Preset | Key |
64|--------+------------------------------|
65| Emacs | =C-c C-c= in a table |
66| Mac | =⌃⌘X= in a table |
67| Doom | =C-c C-c=, or =SPC m b a= |
68
69=C-c C-c= (Mac =⌃⌘X=) in a table is =org-ctrl-c-ctrl-c=, as in Emacs. It first evaluates a formula
70typed in the current field (see /Entering formulas/). Then, in a row marked =#= (see
71/Names, parameters and constants/), it recalculates that row, which also aligns the
72table; in any other row it aligns the table. With the caret at the table's very first
73character, it recalculates the whole table instead.
74
75To align every table when a file opens, set =org-startup-align-all-tables= to =true=
76in the config file (default =false=), or put =#+STARTUP: align= in the file;
77=#+STARTUP: noalign= turns it off for that file. See
78[[file:13-configuration.org][Configuration]].
79
80* Editing rows and columns
81
82| Action | Org command | Emacs | Mac | Doom |
83|-----------------------------------+----------------------------+----------------+-------------+-------------------------------|
84| Move row up | =org-table-move-row-up= | =M-<up>= | =⌃⌘↑= | =M-<up>=, =M-k= |
85| Move row down | =org-table-move-row-down= | =M-<down>= | =⌃⌘↓= | =M-<down>=, =M-j= |
86| Move column left | =org-table-move-column-left= | =M-<left>= | =⌃⌘←= | =M-<left>=, =M-h= |
87| Move column right | =org-table-move-column-right= | =M-<right>= | =⌃⌘→= | =M-<right>=, =M-l= |
88| Insert column | =org-table-insert-column= | =M-S-<right>= | =⌃⌥⌘→= | =M-S-<right>=, =SPC m b i c= |
89| Delete column | =org-table-delete-column= | =M-S-<left>= | =⌃⌥⌘←= | =M-S-<left>=, =SPC m b d c= |
90| Insert row above | =org-table-insert-row= | =M-S-<down>= | =⌃⌥⌘↓= | =M-S-<down>=, =SPC m b i r= |
91| Delete row | =org-table-kill-row= | =M-S-<up>= | =⌃⌥⌘↑= | =M-S-<up>=, =SPC m b d r= |
92| Insert rule below | =org-table-insert-hline= | =C-c -= | =⌃⌘-= | =C-c -=, =SPC m b -=, =SPC m b i h= |
93| Sort rows | =org-table-sort-lines= | =C-c ^= | =⌃⇧⌘S= | =C-c ^= |
94| Transpose | =org-table-transpose-table-at-point= | Org ▸ Transpose Table | Org ▸ Transpose Table | Org ▸ Transpose Table |
95| Edit field in its own editor | =org-table-edit-field= | =C-c `= | Org ▸ Edit Table Field | =C-c `= |
96
97The new column goes to the left of the caret's column, empty. Deleting a row deletes
98the line; it doesn't go to the clipboard. When rows and columns move, are inserted or
99are deleted, the =#+TBLFM= line is updated to match: references are renumbered, and
100formulas for a deleted row or column are removed.
101
102The Mac preset uses the same keys for headings and list items; in a table they act on
103the table.
104
105** Sorting
106
107=C-c ^= in a table asks =Sort Table: [a]lphabetic, [n]umeric, [t]ime. A/N/T means
108reversed:= and sorts the rows between the rules around the caret by the caret's
109column. If the caret isn't in a field, it asks for the column first. Sorting is stable.
110
111- *a* compares text without case.
112- *n* compares the number at the start of each field.
113- *t* compares a timestamp in the field, else a duration such as =1:30= or =2h 15min=,
114 else a clock time =H:MM=. Fields with none of these sort as 0.
115
116** Transposing
117
118Org ▸ Transpose Table swaps rows and columns. Rules are dropped.
119
120** The field editor
121
122=C-c `= opens the field at the caret in an editor of its own, which is easier for long
123text. =C-c '= or =⌘Return= puts it back; =Escape= or =C-c C-k= leaves it unchanged.
124Line breaks become single spaces and lines that start with =#= are dropped, as
125=org-table-finish-edit-field= does.
126
127* Narrow columns
128
129A field that holds a width cookie =<N>=, optionally with an alignment letter
130(=<l10>=, =<c8>=, =<r12>=), marks the column for narrowing. Narrowed fields show their
131first /N/ display columns followed by =…=. The text itself is unchanged.
132
133| Command | Org command | Keys |
134|------------------------------------------+-----------------------------------+------------------------------------------|
135| Org ▸ Shrink or Expand Table Column | =org-table-toggle-column-width= | Emacs and Doom =C-c TAB= |
136| Org ▸ Shrink Table Columns with Widths | =org-table-shrink= | No default key |
137| Org ▸ Expand Table Columns | =org-table-expand= | No default key |
138
139=C-c TAB= in a field toggles that column. Outside a column, for example on the leading
140=|=, it asks for =Column ranges (e.g. 2-4 6-):=, where =6-= means column 6 to the end.
141A column without a width cookie shrinks to a bare =…= when toggled. Typing in a narrowed
142field widens its column again, as editing Org's overlays does. =#+STARTUP: shrink=
143narrows every column with a width cookie when the file opens.
144
145* Importing and exporting
146
147| Command | Org command |
148|----------------------------------------+--------------------|
149| Import Table from File… (command palette) | =org-table-import= |
150| Export Table to File… (command palette) | =org-table-export= |
151
152Open the command palette with =⇧⌘P= (=M-x= in the Emacs preset, =SPC := in Doom).
153
154Import asks for a CSV, TSV or plain text file, inserts its contents at the caret on a
155line of its own, and converts them to a table with the separator guessed as for a
156region (see /Creating a table/).
157
158Export writes the table at the caret. A file name ending in =.csv= gets CSV: fields
159separated by commas, with fields that contain a comma or a double quote quoted and
160inner quotes doubled. Any other name gets TSV. Rules are left out.
161
162Import and export are Mac only.
163
164* Formulas
165
166Orgstar evaluates Org's spreadsheet formulas, =org-table-recalculate= and
167=org-table-eval-formula=, natively: Calc expressions in a reimplementation of the part
168of Emacs Calc that tables use, and Lisp formulas in a small Emacs Lisp evaluator. What
169falls outside them is handed to Emacs on the Mac (see /When Emacs is needed/).
170
171Formulas live in a =#+TBLFM:= line right after the table, separated by =::=:
172
173#+BEGIN_SRC org
174| Item | Qty | Price | Total |
175|-------+-----+-------+-------|
176| Apple | 3 | 0.50 | 1.50 |
177| Pear | 12 | 0.75 | 9.00 |
178|-------+-----+-------+-------|
179| Sum | | | 10.50 |
180,#+TBLFM: $4=$2*$3;%.2f::@>$4=vsum(@I..@II);%.2f
181#+END_SRC
182
183Blank lines between the table and =#+TBLFM:= are allowed. If there are several
184=#+TBLFM:= lines, recalculating the table uses the first; =C-c C-c= on another applies
185that line instead (=org-table-calc-current-TBLFM=).
186
187** Kinds of formula
188
189| Left side | Kind | Applies to |
190|-------------------------+----------------------+------------------------------------------------------------------|
191| =$3= | Column formula | Every data row of column 3, except rows marked =!=, =^=, =_=, =$= or =/= in the first column. |
192| =$<=, =$>= | Column formula | The first or last column. |
193| =@2$3=, =@>$3= | Field formula | One field. Field formulas override column formulas. |
194| =@2$2..@4$3= | Range formula | Every field in the rectangle. |
195| =@4= | Row formula | Every field of data row 4. |
196| =$name= | Named field formula | The field named by a =^= or =_= row (see /Names, parameters and constants/). |
197
198A left side relative to the current row, such as =@-1$2=, is an error
199(=Unknown field=), and so is one relative to a rule, such as =@I$2=, as in Org. Two
200formulas for the same field are an error.
201
202** References
203
204Rows count data lines from 1; rules don't count. Columns count from 1.
205
206| Reference | Meaning |
207|----------------------+----------------------------------------------------------------------|
208| =$2= | Column 2 in the current row. |
209| =$-1=, =$+1= | The column before or after the current one. |
210| =$<=, =$>=, =$>>= | The first column, the last, the one before last. |
211| =@3= | Row 3 in the current column. |
212| =@-1=, =@+1= | The row above or below. |
213| =@<=, =@>= | The first or last data row. |
214| =@I=, =@II=, =@III= | The first, second, third rule; as a row, the line after it. |
215| =@-I= | The rule above the current row. |
216| =@I+2= | Two data rows after the first rule. |
217| =@2$3= | Row 2, column 3. |
218| =$0= | The current column. |
219| =@0= | The current row: =@0$2= is =$2=. |
220| =@#=, =$#= | The current row's or column's number, as a value. |
221| =@2$1..@4$3= | A range: the fields of the rectangle, as a vector. |
222| =$1..$3= | Columns 1 to 3 of the current row. |
223| =@I..@II= | The current column from the first rule to the second. |
224
225In a Calc formula a single field becomes a number in parentheses, and a range becomes
226a vector such as =[1,2,3]=. Without the =E= flag, empty fields count as 0 on their own
227and are left out of ranges.
228
229Fields in a Calc formula must hold numbers, timestamps or =nan=, unless the =N= flag
230reads every field as a number. A reference to a field with other text needs Emacs,
231because Calc would treat the text as a symbol.
232
233** Names, parameters and constants
234
235The first column can mark special rows, as in Org's spreadsheet:
236
237| Mark | Row |
238|-------+---------------------------------------------------------------------------------------|
239| =!= | Column names: =$qty= in a formula means the column whose =!= row field is =qty=. |
240| =^= | Names for the fields in the row above, usable as =$name=. |
241| =_= | Names for the fields in the row below. |
242| =$= | Parameters: fields like ~rate=0.2~, usable as =$rate=. |
243| =#= | Marked for recalculation. |
244| =*= | Marked for recalculation. |
245| =/= | Not recalculated. |
246
247When any row's first field is one of =!=, =^=, =_=, =$=, =#= or =*=, column formulas
248in a whole-table recalculation apply only to the rows marked =#= or =*=, as
249=org-table-calculate-mark-regexp= decides in Org. So a table with a =!= names row and
250no =#= rows gets no column formulas applied; mark the rows to calculate. Field
251formulas apply either way. Rows marked =!=, =^=, =_=, =$= or =/= are never changed by
252column formulas.
253
254#+BEGIN_SRC org
255| ! | qty | price | total |
256|---+-----+-------+-------|
257| # | 2 | 3 | 6 |
258| # | 4 | 0.5 | 2 |
259,#+TBLFM: $4=$qty*$price
260#+END_SRC
261
262A =$name= that isn't a column name, parameter or named field is looked up as
263=org-table-get-constant= does:
264
265- in =#+CONSTANTS:= lines of the file or its setup file, written ~name=value~ and
266 separated by spaces (~#+CONSTANTS: c=299792458 g=9.81~);
267- =$PROP_xyz= reads the =xyz= property of the entry holding the table, with
268 inheritance.
269
270A name that isn't found becomes =#UNDEFINED_NAME=. A parameter named =%= in a =$= row,
271for example ~%=%.2f~, is put in front of the flags of every formula that has a =;=,
272so ~$3=$2/3;~ is formatted with =%.2f=.
273
274** Remote references
275
276=remote(NAME, REF)= reads a field or range from another table:
277
278#+BEGIN_SRC org
279,#+NAME: rates
280| item | rate |
281|------+------|
282| a | 2 |
283| b | 3 |
284
285| x | y | z |
286|---+---+---|
287| 4 | 8 | 5 |
288,#+TBLFM: $2=$1*remote(rates,@2$2)::$3=vsum(remote(rates,@2$2..@>$2))
289#+END_SRC
290
291=NAME= is found in this order:
292
2931. a table after =#+NAME: NAME= or =#+TBLNAME: NAME= in the same file;
2942. the first table in the entry whose =ID= property is =NAME=, in the same file;
2953. the first table in the entry with that =ID= in any indexed file in your sidebar
296 folders, read from the file on disk.
297
298=REF= may use spreadsheet-style references such as =B3= (column B, row 3), which
299become =@3$2=. A =REF= without a row, such as =$1..$2=, reads the row of the other
300table that has the current row's number. =NAME= can itself be a reference: in
301=remote($1,@1$1)=, the current row's first field holds the table's name.
302
303** Calc expressions
304
305Calc formulas use Calc's number rules: integers are exact, and decimal numbers are
306rounded to 12 significant digits after every operation. Results are shown with up to
3078 significant digits unless a format flag says otherwise (=org-calc-default-modes=).
308
309Operators, from lowest to highest precedence (the lowest, ~||~, is logical or, giving
3101 or 0):
311
312| Operator | Meaning |
313|------------------------------------+-----------------------------------------------------------|
314| =&&= | Logical and. |
315| =!= | Logical not. |
316| ~==~, ~!=~, =<=, =>=, ~<=~, ~>=~ | Comparisons, giving 1 or 0. They can't be chained. |
317| =+=, =-= | Addition and subtraction. |
318| =/=, =%=, =\= | Division, modulo (sign of the divisor), integer division rounding down. |
319| =*= | Multiplication. |
320| unary =-= | Negation. |
321| =^= | Power. |
322
323Parentheses group, =[a, b, c]= writes a vector, =<2026-10-05 Mon>= writes a date, and
324=nan= is "not a number".
325
326Functions:
327
328| Function | Result |
329|--------------------------------------------+---------------------------------------------------------------|
330| =vsum=, =vprod= | Sum or product of a vector. |
331| =vcount= | Number of elements. |
332| =vmean=, =vmedian= | Mean, median. |
333| =vmax=, =vmin= | Largest, smallest element. |
334| =vvar=, =vsdev= | Sample variance, sample standard deviation. |
335| =vpvar=, =vpsdev= | Population variance, population standard deviation. |
336| =max(a, b, …)=, =min(a, b, …)= | Largest, smallest argument. |
337| =if(c, a, b)= | =a= if =c= is nonzero, else =b=. |
338| =abs= | Absolute value. |
339| =floor=, =ceil=, =trunc= | Round down, up, toward zero, to an integer. |
340| =round(x)=, =round(x, n)= | Round to an integer, or to /n/ decimal places. |
341| =mod(a, b)=, =idiv(a, b)= | As =%= and =\=. |
342| =fact= | Factorial of a non-negative integer. |
343| =sqrt=, =exp=, =ln=, =log10= | Square root, exponential, natural and base-10 logarithm. |
344| =sin=, =cos=, =tan= | Trigonometry, in degrees unless the =R= flag is set. |
345| =arcsin=, =arccos=, =arctan= | Inverse trigonometry, in degrees unless =R=. |
346
347Other Calc functions, variables such as =pi= or =e=, symbolic results, complex results
348and division by zero need Emacs.
349
350** Mode flags and formats
351
352After the formula, a =;= starts its flags, as in ~$3=$1/$2;%.2f~ or ~$4=$1*2;f2~:
353
354| Flag | Meaning |
355|-----------+-------------------------------------------------------------------------------------------|
356| =nN= | Float format with /N/ significant digits. |
357| =fN= | Fixed format with /N/ decimal places. |
358| =sN= | Scientific format with /N/ digits. |
359| =eN= | Engineering format with /N/ digits. |
360| =pN= | Calc precision. Only =p12=, the default, is evaluated natively; others need Emacs. |
361| =D=, =R= | Angles in degrees (the default) or radians. |
362| =F= | Prefer fractions: =1/3= stays =1:3=. |
363| =N= | Treat every field as a number; text counts as 0. |
364| =E= | Keep empty fields: in ranges they stay in, and count as =nan= in Calc. |
365| =L= | Literal: in Lisp formulas, insert fields as they are written. |
366| =T= | Durations: read =H:MM= and =H:MM:SS= fields as times, show the result as =HH:MM:SS=. |
367| =U= | As =T=, showing =HH:MM=. |
368| =t= | As =T=, showing decimal hours with two places, such as =1.50=. |
369
370The flags =S= (symbolic) and =u= need Emacs. Any other text after the flags is a
371=format= string applied to the result, such as =%.2f= or =%d=; =format= supports
372=%s=, =%S=, =%d=, =%o=, =%x=, =%X=, =%c=, =%e=, =%f= and =%g=.
373
374** Durations
375
376With =T=, =U= or =t=, fields like =1:30= or =10:00:30= are read as hours, minutes and
377seconds:
378
379#+BEGIN_SRC org
380| start | end | sum | diff | hours |
381|----------+---------+----------+-------+-------|
382| 1:30 | 0:45 | 02:15:00 | 00:45 | 3.00 |
383| 10:00:30 | 2:15:10 | 12:15:40 | 07:45 | 20.02 |
384,#+TBLFM: $3=$1+$2;T::$4=$1-$2;U::$5=$1*2;t
385#+END_SRC
386
387** Dates
388
389Timestamps in fields, active or inactive, take part in Calc arithmetic as dates. The
390difference of two dates is a number of days, with a fraction when the timestamps have
391times. A date plus a number is a date, written back as an inactive timestamp:
392
393#+BEGIN_SRC org
394| start | end | days | later |
395|------------------+------------------+------+------------------|
396| <2026-10-05 Mon> | <2026-10-12 Mon> | 7 | [2026-10-12 Mon] |
397,#+TBLFM: $3=$2-$1::$4=$1+7
398#+END_SRC
399
400** Lisp formulas
401
402A formula that starts with ='(= is Emacs Lisp. Each reference becomes a Lisp string,
403or a number with =N=, or the field's text inserted as is with =L=. A range becomes the
404values separated by spaces, so wrap it in a quoted list:
405
406#+BEGIN_SRC org
407| name | greeting |
408|-------+----------|
409| Ada | Ada! |
410| Grace | Grace! |
411,#+TBLFM: $2='(concat $1 "!")
412
413| n |
414|---|
415| 1 |
416| 2 |
417|---|
418| 3 |
419,#+TBLFM: @>$1='(apply '+ '(@I..@II));N
420#+END_SRC
421
422The evaluator supports:
423
424- special forms: =quote=, =function=, =lambda=, =progn=, =prog1=, =if=, =when=,
425 =unless=, =cond=, =and=, =or=, =let=, =let*=, =setq=, =push=, =pop=, =while=,
426 =dolist=, =dotimes=, =with-output-to-string=, =ignore-errors=, =condition-case=;
427- arithmetic: =+=, =-=, =*=, =/=, =%=, =mod=, =1+=, =1-=, =abs=, =max=, =min=, =float=,
428 =floor=, =ceiling=, =round=, =truncate=, ~=~, =<=, =>=, ~<=~, ~>=~, ~/=~, =zerop=;
429- predicates: =not=, =null=, =eq=, =eql=, =equal=, =numberp=, =integerp=, =floatp=,
430 =stringp=, =listp=, =consp=, =symbolp=;
431- lists: =car=, =cdr=, =cadr=, =cddr=, =cons=, =list=, =nth=, =nthcdr=, =elt=, =aref=,
432 =append=, =length=, =reverse=, =number-sequence=, =memq=, =member=, =memql=, =assoc=,
433 =assq=, =delq=, =delete=, =mapcar=, =mapc=, =mapconcat=, =funcall=, =apply=,
434 =identity=, =ignore=;
435- strings: =concat=, =format=, =format-message=, ~string=~, =string-equal=, =string<=,
436 =string-lessp=, =upcase=, =downcase=, =capitalize=, =substring=, =string-to-number=,
437 =number-to-string=, =int-to-string=, =string-prefix-p=, =string-suffix-p=,
438 =string-empty-p=, =string-trim=, =split-string=, =prin1-to-string=;
439- output and errors: =princ=, =prin1=, =print=, =terpri=, =message=, =error=,
440 =user-error=;
441- Org's lookup functions =org-lookup-first=, =org-lookup-last= and =org-lookup-all=.
442
443Any other function needs Emacs. An error inside a Lisp formula writes =#ERROR= in the
444field, as does a Calc error.
445
446* Entering formulas
447
448There are three ways to set a formula.
449
450*In the field.* Type ~=expr~ in a field and press =TAB= or =RET=: Orgstar stores
451~$N=expr~ as the column's formula and evaluates it, as
452=org-table-maybe-eval-formula= does. Type ~:=expr~ instead to store a field formula
453~@R$C=expr~.
454
455*With a prompt.* =org-table-eval-formula= asks for the formula (~Column formula $N=~
456or ~Field formula @R$C=~) with the stored one filled in, stores it and evaluates it in
457the current field. Clearing the prompt and pressing =Return= removes the stored
458formula, as in Emacs, and the echo area shows =Formula removed=. You can also delete a
459formula in the formula editor below or from the =#+TBLFM:= line.
460
461| Command | Emacs | Mac | Doom |
462|-------------------------------+----------+-----------------------------+----------|
463| Org ▸ Set Column Formula | ~C-c =~ | Org ▸ Set Column Formula | ~C-c =~ |
464| Org ▸ Set Field Formula | none | Org ▸ Set Field Formula | none |
465
466Org's ~C-u C-c =~ for field formulas has no equivalent key, because Orgstar has no
467prefix argument; use the menu item or type ~:=~ in the field.
468
469*In the formula editor.* =C-c '= in a table or on its =#+TBLFM:= line
470(=org-table-edit-formulas=) opens the formulas in an editor of their own, one per line,
471grouped under =# Column Formulas=, =# Field and Range Formulas= and
472=# Named Field Formulas=. A formula can continue on indented lines. =C-c '= or
473=⌘Return= installs the formulas; =Escape= or =C-c C-k= leaves them unchanged.
474Installing doesn't recalculate. The echo area says so and points to Recalculate Table:
475=C-c C-c= on the =#+TBLFM:= line, or =⌃⌘X= there in the Mac preset.
476
477The formulas are stored sorted the way =org-table-formula-less-p= sorts them.
478
479* Recalculating
480
481| Command | Org command | Emacs | Mac | Doom |
482|----------------------------------+-----------------------------------+-------------------------------+-----------------------------+-------------------------------------|
483| Recalculate Table | =org-table-recalculate= with =C-u= | =C-c C-c= on =#+TBLFM:= | =⌃⌘X= on =#+TBLFM:= | =SPC m b r=, =C-c C-c= on =#+TBLFM:= |
484| Recalculate Table Row | =org-table-recalculate= | =C-c *= | Org ▸ Recalculate Table Row | =C-c *= |
485
486In Doom's normal state, =RET= in a table recalculates it when it has a =#+TBLFM:=
487line and aligns it otherwise; on a =#+TBLFM:= line it recalculates.
488
489When the table has a rule below its first data row, recalculating the whole table
490leaves the rows above that rule, the header, alone. With marked rows, the marks decide
491instead (see /Names, parameters and constants/). Each
492command evaluates the column formulas row by row, then the field formulas, then aligns
493the table. Formulas are evaluated once; Org's iterate-until-stable recalculation
494(=C-u C-u C-c *=) isn't available.
495
496Tables are not recalculated automatically. Rows marked =#= are not recalculated when
497you press =TAB= or =RET= in them, as =org-table-maybe-recalculate-line= would do in
498Emacs; recalculate with one of the commands above, or with =C-c C-c= (Mac =⌃⌘X=) in the row.
499
500* When Emacs is needed
501
502When a formula uses something the native evaluator doesn't have, the command reports
503what it was and the Mac recalculates the table in Emacs instead. This happens for:
504
505- references to fields holding text in a Calc formula, and symbolic results;
506- Calc functions and variables not listed above, precision other than =p12=, and the
507 =S= and =u= flags;
508- division by zero, complex results, vector results, and numbers too large for
509 64-bit integers;
510- Lisp functions not listed above.
511
512The echo area shows =Recalculating in Emacs (reason)…=, then =Recalculated in Emacs=.
513Orgstar runs =emacs -Q --batch= on a copy of the file, so your Emacs init file,
514packages and customizations are not loaded, then replaces the table with Emacs's
515result. It looks for Emacs at the path in the =ORGSTAR_EMACS= environment variable,
516then =/opt/homebrew/bin/emacs=, =/usr/local/bin/emacs=,
517=/Applications/Emacs.app/Contents/MacOS/Emacs=, =/run/current-system/sw/bin/emacs= and
518=/usr/bin/emacs=. If none is found, the echo area says Emacs isn't installed and the
519table is unchanged. Emacs gets your =PATH= with =/opt/homebrew/bin=, =/usr/local/bin=,
520=/Library/TeX/texbin=, =/usr/bin= and =/bin= added, as code blocks and export do, so
521programs a formula starts are found when Orgstar was opened from the Dock. The run
522stops after 60 seconds. If you edit the table while Emacs is working, its result is
523discarded.
524
525Edit ▸ Cancel Running Task (=⌘.=) stops the recalculation; the echo area shows
526=Recalculation canceled= and the table is unchanged. Starting another recalculation or
527export in Emacs cancels the one that is running.
528
529If the table's formulas contain Lisp, Orgstar asks first:
530=This table's formulas run Lisp. Run them? (yes, no, always)=. =always= trusts this
531table's text in this file, so the question isn't asked again until the text changes.
532
533Entering a formula that needs Emacs with ~C-c =~, Set Field Formula or ~=~ in a field
534is not handed to Emacs. The formula is stored in the =#+TBLFM:= line and the field is
535left as it was; the echo area shows =The formula was stored; recalculating it needs
536Emacs= and the reason. =TAB= and =RET= still move to the next field. Recalculate the
537table to run the formula in Emacs.
538
539For how Orgstar and Emacs share files, see
540[[file:15-alongside-emacs.org][Using Orgstar alongside Emacs]].
541
542* table.el tables
543
544Tables drawn with =+= corners and =-= and =|= borders, as the =table.el= package makes
545them, are recognized and kept as written:
546
547#+BEGIN_SRC org
548+-------+-------+
549| Name | Value |
550+-------+-------+
551| a | 1 |
552+-------+-------+
553#+END_SRC
554
555Orgstar doesn't edit them as tables: =TAB=, alignment and formulas don't apply. HTML
556export renders them as tables, with cells that span rows and columns, and Markdown
557export writes them as a code block. See [[file:12-export.org][Export]].
558
559* Plotting
560
561=#+PLOT:= lines are recognized and completed as keywords, but Orgstar doesn't draw
562plots (=org-plot/gnuplot= is not available).
563
564* On iOS
565
566The iOS app evaluates formulas natively with the same engine. Tables that need Emacs
567are not recalculated there; the app reports =This table needs Emacs, which runs on the
568Mac= with the reason. Table import and export are Mac only. See
569[[file:14-ios.org][iOS]].