docs/manual/guide/10-tables.org
574 lines · 32192 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
145The iOS editor narrows columns the same way, with =#+STARTUP: shrink= and the three
146commands, which are in Commands when the caret is in a table. The iOS reader shows
147tables at full width.
148
149* Importing and exporting
150
151| Command | Org command |
152|----------------------------------------+--------------------|
153| Import Table from File… (command palette) | =org-table-import= |
154| Export Table to File… (command palette) | =org-table-export= |
155
156Open the command palette with =⇧⌘P= (=M-x= in the Emacs preset, =SPC := in Doom).
157
158Import asks for a CSV, TSV or plain text file, inserts its contents at the caret on a
159line of its own, and converts them to a table with the separator guessed as for a
160region (see /Creating a table/).
161
162Export writes the table at the caret. A file name ending in =.csv= gets CSV: fields
163separated by commas, with fields that contain a comma or a double quote quoted and
164inner quotes doubled. Any other name gets TSV. Rules are left out.
165
166Import and export are Mac only.
167
168* Formulas
169
170Orgstar evaluates Org's spreadsheet formulas, =org-table-recalculate= and
171=org-table-eval-formula=, natively: Calc expressions in a reimplementation of the part
172of Emacs Calc that tables use, and Lisp formulas in a small Emacs Lisp evaluator. What
173falls outside them is handed to Emacs on the Mac (see /When Emacs is needed/).
174
175Formulas live in a =#+TBLFM:= line right after the table, separated by =::=:
176
177#+BEGIN_SRC org
178| Item | Qty | Price | Total |
179|-------+-----+-------+-------|
180| Apple | 3 | 0.50 | 1.50 |
181| Pear | 12 | 0.75 | 9.00 |
182|-------+-----+-------+-------|
183| Sum | | | 10.50 |
184,#+TBLFM: $4=$2*$3;%.2f::@>$4=vsum(@I..@II);%.2f
185#+END_SRC
186
187Blank lines between the table and =#+TBLFM:= are allowed. If there are several
188=#+TBLFM:= lines, recalculating the table uses the first; =C-c C-c= on another applies
189that line instead (=org-table-calc-current-TBLFM=).
190
191** Kinds of formula
192
193| Left side | Kind | Applies to |
194|-------------------------+----------------------+------------------------------------------------------------------|
195| =$3= | Column formula | Every data row of column 3, except rows marked =!=, =^=, =_=, =$= or =/= in the first column. |
196| =$<=, =$>= | Column formula | The first or last column. |
197| =@2$3=, =@>$3= | Field formula | One field. Field formulas override column formulas. |
198| =@2$2..@4$3= | Range formula | Every field in the rectangle. |
199| =@4= | Row formula | Every field of data row 4. |
200| =$name= | Named field formula | The field named by a =^= or =_= row (see /Names, parameters and constants/). |
201
202A left side relative to the current row, such as =@-1$2=, is an error
203(=Unknown field=), and so is one relative to a rule, such as =@I$2=, as in Org. Two
204formulas for the same field are an error.
205
206** References
207
208Rows count data lines from 1; rules don't count. Columns count from 1.
209
210| Reference | Meaning |
211|----------------------+----------------------------------------------------------------------|
212| =$2= | Column 2 in the current row. |
213| =$-1=, =$+1= | The column before or after the current one. |
214| =$<=, =$>=, =$>>= | The first column, the last, the one before last. |
215| =@3= | Row 3 in the current column. |
216| =@-1=, =@+1= | The row above or below. |
217| =@<=, =@>= | The first or last data row. |
218| =@I=, =@II=, =@III= | The first, second, third rule; as a row, the line after it. |
219| =@-I= | The rule above the current row. |
220| =@I+2= | Two data rows after the first rule. |
221| =@2$3= | Row 2, column 3. |
222| =$0= | The current column. |
223| =@0= | The current row: =@0$2= is =$2=. |
224| =@#=, =$#= | The current row's or column's number, as a value. |
225| =@2$1..@4$3= | A range: the fields of the rectangle, as a vector. |
226| =$1..$3= | Columns 1 to 3 of the current row. |
227| =@I..@II= | The current column from the first rule to the second. |
228
229In a Calc formula a single field becomes a number in parentheses, and a range becomes
230a vector such as =[1,2,3]=. Without the =E= flag, empty fields count as 0 on their own
231and are left out of ranges.
232
233Fields in a Calc formula must hold numbers, timestamps or =nan=, unless the =N= flag
234reads every field as a number. A reference to a field with other text needs Emacs,
235because Calc would treat the text as a symbol.
236
237** Names, parameters and constants
238
239The first column can mark special rows, as in Org's spreadsheet:
240
241| Mark | Row |
242|-------+---------------------------------------------------------------------------------------|
243| =!= | Column names: =$qty= in a formula means the column whose =!= row field is =qty=. |
244| =^= | Names for the fields in the row above, usable as =$name=. |
245| =_= | Names for the fields in the row below. |
246| =$= | Parameters: fields like ~rate=0.2~, usable as =$rate=. |
247| =#= | Marked for recalculation. |
248| =*= | Marked for recalculation. |
249| =/= | Not recalculated. |
250
251When any row's first field is one of =!=, =^=, =_=, =$=, =#= or =*=, column formulas
252in a whole-table recalculation apply only to the rows marked =#= or =*=, as
253=org-table-calculate-mark-regexp= decides in Org. So a table with a =!= names row and
254no =#= rows gets no column formulas applied; mark the rows to calculate. Field
255formulas apply either way. Rows marked =!=, =^=, =_=, =$= or =/= are never changed by
256column formulas.
257
258#+BEGIN_SRC org
259| ! | qty | price | total |
260|---+-----+-------+-------|
261| # | 2 | 3 | 6 |
262| # | 4 | 0.5 | 2 |
263,#+TBLFM: $4=$qty*$price
264#+END_SRC
265
266A =$name= that isn't a column name, parameter or named field is looked up as
267=org-table-get-constant= does:
268
269- in =#+CONSTANTS:= lines of the file or its setup file, written ~name=value~ and
270 separated by spaces (~#+CONSTANTS: c=299792458 g=9.81~);
271- =$PROP_xyz= reads the =xyz= property of the entry holding the table, with
272 inheritance.
273
274A name that isn't found becomes =#UNDEFINED_NAME=. A parameter named =%= in a =$= row,
275for example ~%=%.2f~, is put in front of the flags of every formula that has a =;=,
276so ~$3=$2/3;~ is formatted with =%.2f=.
277
278** Remote references
279
280=remote(NAME, REF)= reads a field or range from another table:
281
282#+BEGIN_SRC org
283,#+NAME: rates
284| item | rate |
285|------+------|
286| a | 2 |
287| b | 3 |
288
289| x | y | z |
290|---+---+---|
291| 4 | 8 | 5 |
292,#+TBLFM: $2=$1*remote(rates,@2$2)::$3=vsum(remote(rates,@2$2..@>$2))
293#+END_SRC
294
295=NAME= is found in this order:
296
2971. a table after =#+NAME: NAME= or =#+TBLNAME: NAME= in the same file;
2982. the first table in the entry whose =ID= property is =NAME=, in the same file;
2993. the first table in the entry with that =ID= in any indexed file in your sidebar
300 folders, read from the file on disk.
301
302=REF= may use spreadsheet-style references such as =B3= (column B, row 3), which
303become =@3$2=. A =REF= without a row, such as =$1..$2=, reads the row of the other
304table that has the current row's number. =NAME= can itself be a reference: in
305=remote($1,@1$1)=, the current row's first field holds the table's name.
306
307** Calc expressions
308
309Calc formulas use Calc's number rules: integers are exact, and decimal numbers are
310rounded to 12 significant digits after every operation. Results are shown with up to
3118 significant digits unless a format flag says otherwise (=org-calc-default-modes=).
312
313Operators, from lowest to highest precedence (the lowest, ~||~, is logical or, giving
3141 or 0):
315
316| Operator | Meaning |
317|------------------------------------+-----------------------------------------------------------|
318| =&&= | Logical and. |
319| =!= | Logical not. |
320| ~==~, ~!=~, =<=, =>=, ~<=~, ~>=~ | Comparisons, giving 1 or 0. They can't be chained. |
321| =+=, =-= | Addition and subtraction. |
322| =/=, =%=, =\= | Division, modulo (sign of the divisor), integer division rounding down. |
323| =*= | Multiplication. |
324| unary =-= | Negation. |
325| =^= | Power. |
326
327Parentheses group, =[a, b, c]= writes a vector, =<2026-10-05 Mon>= writes a date, and
328=nan= is "not a number".
329
330Functions:
331
332| Function | Result |
333|--------------------------------------------+---------------------------------------------------------------|
334| =vsum=, =vprod= | Sum or product of a vector. |
335| =vcount= | Number of elements. |
336| =vmean=, =vmedian= | Mean, median. |
337| =vmax=, =vmin= | Largest, smallest element. |
338| =vvar=, =vsdev= | Sample variance, sample standard deviation. |
339| =vpvar=, =vpsdev= | Population variance, population standard deviation. |
340| =max(a, b, …)=, =min(a, b, …)= | Largest, smallest argument. |
341| =if(c, a, b)= | =a= if =c= is nonzero, else =b=. |
342| =abs= | Absolute value. |
343| =floor=, =ceil=, =trunc= | Round down, up, toward zero, to an integer. |
344| =round(x)=, =round(x, n)= | Round to an integer, or to /n/ decimal places. |
345| =mod(a, b)=, =idiv(a, b)= | As =%= and =\=. |
346| =fact= | Factorial of a non-negative integer. |
347| =sqrt=, =exp=, =ln=, =log10= | Square root, exponential, natural and base-10 logarithm. |
348| =sin=, =cos=, =tan= | Trigonometry, in degrees unless the =R= flag is set. |
349| =arcsin=, =arccos=, =arctan= | Inverse trigonometry, in degrees unless =R=. |
350
351Other Calc functions, variables such as =pi= or =e=, symbolic results, complex results
352and division by zero need Emacs.
353
354** Mode flags and formats
355
356After the formula, a =;= starts its flags, as in ~$3=$1/$2;%.2f~ or ~$4=$1*2;f2~:
357
358| Flag | Meaning |
359|-----------+-------------------------------------------------------------------------------------------|
360| =nN= | Float format with /N/ significant digits. |
361| =fN= | Fixed format with /N/ decimal places. |
362| =sN= | Scientific format with /N/ digits. |
363| =eN= | Engineering format with /N/ digits. |
364| =pN= | Calc precision. Only =p12=, the default, is evaluated natively; others need Emacs. |
365| =D=, =R= | Angles in degrees (the default) or radians. |
366| =F= | Prefer fractions: =1/3= stays =1:3=. |
367| =N= | Treat every field as a number; text counts as 0. |
368| =E= | Keep empty fields: in ranges they stay in, and count as =nan= in Calc. |
369| =L= | Literal: in Lisp formulas, insert fields as they are written. |
370| =T= | Durations: read =H:MM= and =H:MM:SS= fields as times, show the result as =HH:MM:SS=. |
371| =U= | As =T=, showing =HH:MM=. |
372| =t= | As =T=, showing decimal hours with two places, such as =1.50=. |
373
374The flags =S= (symbolic) and =u= need Emacs. Any other text after the flags is a
375=format= string applied to the result, such as =%.2f= or =%d=; =format= supports
376=%s=, =%S=, =%d=, =%o=, =%x=, =%X=, =%c=, =%e=, =%f= and =%g=.
377
378** Durations
379
380With =T=, =U= or =t=, fields like =1:30= or =10:00:30= are read as hours, minutes and
381seconds:
382
383#+BEGIN_SRC org
384| start | end | sum | diff | hours |
385|----------+---------+----------+-------+-------|
386| 1:30 | 0:45 | 02:15:00 | 00:45 | 3.00 |
387| 10:00:30 | 2:15:10 | 12:15:40 | 07:45 | 20.02 |
388,#+TBLFM: $3=$1+$2;T::$4=$1-$2;U::$5=$1*2;t
389#+END_SRC
390
391** Dates
392
393Timestamps in fields, active or inactive, take part in Calc arithmetic as dates. The
394difference of two dates is a number of days, with a fraction when the timestamps have
395times. A date plus a number is a date, written back as an inactive timestamp:
396
397#+BEGIN_SRC org
398| start | end | days | later |
399|------------------+------------------+------+------------------|
400| <2026-10-05 Mon> | <2026-10-12 Mon> | 7 | [2026-10-12 Mon] |
401,#+TBLFM: $3=$2-$1::$4=$1+7
402#+END_SRC
403
404** Lisp formulas
405
406A formula that starts with ='(= is Emacs Lisp. Each reference becomes a Lisp string,
407or a number with =N=, or the field's text inserted as is with =L=. A range becomes the
408values separated by spaces, so wrap it in a quoted list:
409
410#+BEGIN_SRC org
411| name | greeting |
412|-------+----------|
413| Ada | Ada! |
414| Grace | Grace! |
415,#+TBLFM: $2='(concat $1 "!")
416
417| n |
418|---|
419| 1 |
420| 2 |
421|---|
422| 3 |
423,#+TBLFM: @>$1='(apply '+ '(@I..@II));N
424#+END_SRC
425
426The evaluator supports:
427
428- special forms: =quote=, =function=, =lambda=, =progn=, =prog1=, =if=, =when=,
429 =unless=, =cond=, =and=, =or=, =let=, =let*=, =setq=, =push=, =pop=, =while=,
430 =dolist=, =dotimes=, =with-output-to-string=, =ignore-errors=, =condition-case=;
431- arithmetic: =+=, =-=, =*=, =/=, =%=, =mod=, =1+=, =1-=, =abs=, =max=, =min=, =float=,
432 =floor=, =ceiling=, =round=, =truncate=, ~=~, =<=, =>=, ~<=~, ~>=~, ~/=~, =zerop=;
433- predicates: =not=, =null=, =eq=, =eql=, =equal=, =numberp=, =integerp=, =floatp=,
434 =stringp=, =listp=, =consp=, =symbolp=;
435- lists: =car=, =cdr=, =cadr=, =cddr=, =cons=, =list=, =nth=, =nthcdr=, =elt=, =aref=,
436 =append=, =length=, =reverse=, =number-sequence=, =memq=, =member=, =memql=, =assoc=,
437 =assq=, =delq=, =delete=, =mapcar=, =mapc=, =mapconcat=, =funcall=, =apply=,
438 =identity=, =ignore=;
439- strings: =concat=, =format=, =format-message=, ~string=~, =string-equal=, =string<=,
440 =string-lessp=, =upcase=, =downcase=, =capitalize=, =substring=, =string-to-number=,
441 =number-to-string=, =int-to-string=, =string-prefix-p=, =string-suffix-p=,
442 =string-empty-p=, =string-trim=, =split-string=, =prin1-to-string=;
443- output and errors: =princ=, =prin1=, =print=, =terpri=, =message=, =error=,
444 =user-error=;
445- Org's lookup functions =org-lookup-first=, =org-lookup-last= and =org-lookup-all=.
446
447Any other function needs Emacs. An error inside a Lisp formula writes =#ERROR= in the
448field, as does a Calc error.
449
450* Entering formulas
451
452There are three ways to set a formula.
453
454*In the field.* Type ~=expr~ in a field and press =TAB= or =RET=: Orgstar stores
455~$N=expr~ as the column's formula and evaluates it, as
456=org-table-maybe-eval-formula= does. Type ~:=expr~ instead to store a field formula
457~@R$C=expr~.
458
459*With a prompt.* =org-table-eval-formula= asks for the formula (~Column formula $N=~
460or ~Field formula @R$C=~) with the stored one filled in, stores it and evaluates it in
461the current field. Clearing the prompt and pressing =Return= removes the stored
462formula, as in Emacs, and the echo area shows =Formula removed=. You can also delete a
463formula in the formula editor below or from the =#+TBLFM:= line.
464
465| Command | Emacs | Mac | Doom |
466|-------------------------------+----------+-----------------------------+----------|
467| Org ▸ Set Column Formula | ~C-c =~ | Org ▸ Set Column Formula | ~C-c =~ |
468| Org ▸ Set Field Formula | none | Org ▸ Set Field Formula | none |
469
470Org's ~C-u C-c =~ for field formulas has no equivalent key, because Orgstar has no
471prefix argument; use the menu item or type ~:=~ in the field.
472
473*In the formula editor.* =C-c '= in a table or on its =#+TBLFM:= line
474(=org-table-edit-formulas=) opens the formulas in an editor of their own, one per line,
475grouped under =# Column Formulas=, =# Field and Range Formulas= and
476=# Named Field Formulas=. A formula can continue on indented lines. =C-c '= or
477=⌘Return= installs the formulas; =Escape= or =C-c C-k= leaves them unchanged.
478Installing doesn't recalculate. The echo area says so and points to Recalculate Table:
479=C-c C-c= on the =#+TBLFM:= line, or =⌃⌘X= there in the Mac preset.
480
481The formulas are stored sorted the way =org-table-formula-less-p= sorts them.
482
483* Recalculating
484
485| Command | Org command | Emacs | Mac | Doom |
486|----------------------------------+-----------------------------------+-------------------------------+-----------------------------+-------------------------------------|
487| 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:= |
488| Recalculate Table Row | =org-table-recalculate= | =C-c *= | =⌃⌘*= (=⌃⇧⌘8= on a US keyboard) | =C-c *= |
489
490In Doom's normal state, =RET= in a table recalculates it when it has a =#+TBLFM:=
491line and aligns it otherwise; on a =#+TBLFM:= line it recalculates.
492
493When the table has a rule below its first data row, recalculating the whole table
494leaves the rows above that rule, the header, alone. With marked rows, the marks decide
495instead (see /Names, parameters and constants/). Each
496command evaluates the column formulas row by row, then the field formulas, then aligns
497the table. Formulas are evaluated once; Org's iterate-until-stable recalculation
498(=C-u C-u C-c *=) isn't available.
499
500Tables are not recalculated automatically. Rows marked =#= are not recalculated when
501you press =TAB= or =RET= in them, as =org-table-maybe-recalculate-line= would do in
502Emacs; recalculate with one of the commands above, or with =C-c C-c= (Mac =⌃⌘X=) in the row.
503
504* When Emacs is needed
505
506When a formula uses something the native evaluator doesn't have, the command reports
507what it was and the Mac recalculates the table in Emacs instead. This happens for:
508
509- references to fields holding text in a Calc formula, and symbolic results;
510- Calc functions and variables not listed above, precision other than =p12=, and the
511 =S= and =u= flags;
512- division by zero, complex results, vector results, and numbers too large for
513 64-bit integers;
514- Lisp functions not listed above.
515
516The echo area shows =Recalculating in Emacs (reason)…=, then =Recalculated in Emacs=.
517Orgstar runs =emacs -Q --batch= on a copy of the file, so your Emacs init file,
518packages and customizations are not loaded, then replaces the table with Emacs's
519result. It looks for Emacs at the path in the =ORGSTAR_EMACS= environment variable,
520then =/opt/homebrew/bin/emacs=, =/usr/local/bin/emacs=,
521=/Applications/Emacs.app/Contents/MacOS/Emacs=, =/run/current-system/sw/bin/emacs= and
522=/usr/bin/emacs=. If none is found, the echo area says Emacs isn't installed and the
523table is unchanged. Emacs gets your =PATH= with =/opt/homebrew/bin=, =/usr/local/bin=,
524=/Library/TeX/texbin=, =/usr/bin= and =/bin= added, as code blocks and export do, so
525programs a formula starts are found when Orgstar was opened from the Dock. The run
526stops after 60 seconds. If you edit the table while Emacs is working, its result is
527discarded.
528
529Edit ▸ Cancel Running Task (=⌘.=) stops the recalculation; the echo area shows
530=Recalculation canceled= and the table is unchanged. Starting another recalculation or
531export in Emacs cancels the one that is running.
532
533If the table's formulas contain Lisp, Orgstar asks first:
534=This table's formulas run Lisp. Run them? (yes, no, always)=. =always= trusts this
535table's text in this file, so the question isn't asked again until the text changes.
536
537Entering a formula that needs Emacs with ~C-c =~, Set Field Formula or ~=~ in a field
538is not handed to Emacs. The formula is stored in the =#+TBLFM:= line and the field is
539left as it was; the echo area shows =The formula was stored; recalculating it needs
540Emacs= and the reason. =TAB= and =RET= still move to the next field. Recalculate the
541table to run the formula in Emacs.
542
543For how Orgstar and Emacs share files, see
544[[file:15-alongside-emacs.org][Using Orgstar alongside Emacs]].
545
546* table.el tables
547
548Tables drawn with =+= corners and =-= and =|= borders, as the =table.el= package makes
549them, are recognized and kept as written:
550
551#+BEGIN_SRC org
552+-------+-------+
553| Name | Value |
554+-------+-------+
555| a | 1 |
556+-------+-------+
557#+END_SRC
558
559Orgstar doesn't edit them as tables: =TAB=, alignment and formulas don't apply. HTML
560export renders them as tables, with cells that span rows and columns, and Markdown
561export writes them as a code block. See [[file:12-export.org][Export]].
562
563* Plotting
564
565=#+PLOT:= lines are recognized and completed as keywords, but Orgstar doesn't draw
566plots (=org-plot/gnuplot= is not available).
567
568* On iOS
569
570The iOS app evaluates formulas natively with the same engine. Tables that need Emacs
571are not recalculated there; the app reports =This table needs Emacs, which runs on the
572Mac= with the reason. Table import and export are Mac only. Narrow columns work in the
573editor, as described under /Narrow columns/. See
574[[file:14-ios.org][iOS]].