Tables

Org tables are plain text that Orgstar keeps aligned, edits by row and column, and recalculates with the same formulas Emacs uses.

Tables in Org

A table is a run of lines that start with |. Fields are separated by |, and a line that starts with |- is a horizontal rule:

| Name  | Qty | Price |
|-------+-----+-------|
| Apple |   3 |  0.50 |
| Pear  |  12 |  0.75 |

Orgstar follows org-table.el from Org 9.8.7, with org-table-automatic-realign on, org-table-tab-jumps-over-hlines on, and formulas adjusted without asking when rows and columns move (org-table-fix-formulas-confirm nil). Tables inside dynamic blocks count as tables; tables inside other blocks don't.

Creating a table

Type |, a few field names separated by |, and press TAB: Orgstar aligns the line as a table and moves to the next field, adding a row after the last one. Type |- on the line below a row and press TAB to turn it into a full-width rule.

org-table-create-or-convert-from-region builds one for you: C-c | in the Emacs and Doom presets, ⌃⌘\ in the Mac preset.

With no selection it asks Table size Columns x Rows [e.g. 5x2]:. An empty answer makes a 5 × 2 table. When there is more than one row, a rule follows the first row.

With text selected, the command converts the selected lines to a table instead (org-table-convert-region). The separator is guessed:

• tabs, when every line has a tab;
• otherwise commas, when every line has a comma, read as CSV: a field in double quotes can hold commas, and a line break in it becomes a space;
• otherwise runs of spaces.

Moving around and alignment

These keys work the same in the Emacs and Mac presets. In Doom they apply in insert state; in normal state RET is Doom's "act at point" (see Recalculating).

Alignment (org-table-align) pads every field to its column's width and redraws rules to match. A column is right-aligned when at least half of its non-empty fields are numbers, and left-aligned otherwise. A field that holds only a cookie <l>, <c> or <r> (optionally with a width, such as <r10>) fixes the column's alignment. Widths count display columns, so wide characters and hidden link markup are measured as they appear.

Alignment happens when you press TAB, S-TAB or RET in a table and after every table command, not while you type. To align without moving, use Org ▸ Align Table:

C-c C-c (Mac ⌃⌘X) in a table is org-ctrl-c-ctrl-c, as in Emacs. It first evaluates a formula typed in the current field (see Entering formulas). Then, in a row marked # (see Names, parameters and constants), it recalculates that row, which also aligns the table; in any other row it aligns the table. With the caret at the table's very first character, it recalculates the whole table instead.

To align every table when a file opens, set org-startup-align-all-tables to true in the config file (default false), or put #+STARTUP: align in the file; #+STARTUP: noalign turns it off for that file. See Configuration.

Editing rows and columns

The new column goes to the left of the caret's column, empty. Deleting a row deletes the line; it doesn't go to the clipboard. When rows and columns move, are inserted or are deleted, the #+TBLFM line is updated to match: references are renumbered, and formulas for a deleted row or column are removed.

The Mac preset uses the same keys for headings and list items; in a table they act on the table.

Sorting

C-c ^ in a table asks Sort Table: [a]lphabetic, [n]umeric, [t]ime. A/N/T means reversed: and sorts the rows between the rules around the caret by the caret's column. If the caret isn't in a field, it asks for the column first. Sorting is stable.

• a compares text without case.
• n compares the number at the start of each field.
• t compares a timestamp in the field, else a duration such as 1:30 or 2h 15min, else a clock time H:MM. Fields with none of these sort as 0.

Transposing

Org ▸ Transpose Table swaps rows and columns. Rules are dropped.

The field editor

C-c ` opens the field at the caret in an editor of its own, which is easier for long text. C-c ' or ⌘Return puts it back; Escape or C-c C-k leaves it unchanged. Line breaks become single spaces and lines that start with # are dropped, as org-table-finish-edit-field does.

Narrow columns

A field that holds a width cookie <N>, optionally with an alignment letter (<l10>, <c8>, <r12>), marks the column for narrowing. Narrowed fields show their first N display columns followed by …. The text itself is unchanged.

C-c TAB in a field toggles that column. Outside a column, for example on the leading |, it asks for Column ranges (e.g. 2-4 6-):, where 6- means column 6 to the end. A column without a width cookie shrinks to a bare … when toggled. Typing in a narrowed field widens its column again, as editing Org's overlays does. #+STARTUP: shrink narrows every column with a width cookie when the file opens.

Importing and exporting

Open the command palette with ⇧⌘P (M-x in the Emacs preset, SPC : in Doom).

Import asks for a CSV, TSV or plain text file, inserts its contents at the caret on a line of its own, and converts them to a table with the separator guessed as for a region (see Creating a table).

Export writes the table at the caret. A file name ending in .csv gets CSV: fields separated by commas, with fields that contain a comma or a double quote quoted and inner quotes doubled. Any other name gets TSV. Rules are left out.

Import and export are Mac only.

Formulas

Orgstar evaluates Org's spreadsheet formulas, org-table-recalculate and org-table-eval-formula, natively: Calc expressions in a reimplementation of the part of Emacs Calc that tables use, and Lisp formulas in a small Emacs Lisp evaluator. What falls outside them is handed to Emacs on the Mac (see When Emacs is needed).

Formulas live in a #+TBLFM: line right after the table, separated by :::

| Item  | Qty | Price | Total |
|-------+-----+-------+-------|
| Apple |   3 |  0.50 |  1.50 |
| Pear  |  12 |  0.75 |  9.00 |
|-------+-----+-------+-------|
| Sum   |     |       | 10.50 |
#+TBLFM: $4=$2*$3;%.2f::@>$4=vsum(@I..@II);%.2f

Blank lines between the table and #+TBLFM: are allowed. If there are several #+TBLFM: lines, recalculating the table uses the first; C-c C-c on another applies that line instead (org-table-calc-current-TBLFM).

Kinds of formula

A left side relative to the current row, such as @-1$2, is an error (Unknown field), and so is one relative to a rule, such as @I$2, as in Org. Two formulas for the same field are an error.

References

Rows count data lines from 1; rules don't count. Columns count from 1.

In a Calc formula a single field becomes a number in parentheses, and a range becomes a vector such as [1,2,3]. Without the E flag, empty fields count as 0 on their own and are left out of ranges.

Fields in a Calc formula must hold numbers, timestamps or nan, unless the N flag reads every field as a number. A reference to a field with other text needs Emacs, because Calc would treat the text as a symbol.

Names, parameters and constants

The first column can mark special rows, as in Org's spreadsheet:

When any row's first field is one of !, ^, _, $, # or *, column formulas in a whole-table recalculation apply only to the rows marked # or *, as org-table-calculate-mark-regexp decides in Org. So a table with a ! names row and no # rows gets no column formulas applied; mark the rows to calculate. Field formulas apply either way. Rows marked !, ^, _, $ or / are never changed by column formulas.

| ! | qty | price | total |
|---+-----+-------+-------|
| # |   2 |     3 |     6 |
| # |   4 |   0.5 |     2 |
#+TBLFM: $4=$qty*$price

A $name that isn't a column name, parameter or named field is looked up as org-table-get-constant does:

• in #+CONSTANTS: lines of the file or its setup file, written name=value and separated by spaces (#+CONSTANTS: c=299792458 g=9.81);
• $PROP_xyz reads the xyz property of the entry holding the table, with inheritance.

A name that isn't found becomes #UNDEFINED_NAME. A parameter named % in a $ row, for example %=%.2f, is put in front of the flags of every formula that has a ;, so $3=$2/3; is formatted with %.2f.

Remote references

remote(NAME, REF) reads a field or range from another table:

#+NAME: rates
| item | rate |
|------+------|
| a    |    2 |
| b    |    3 |

| x | y | z |
|---+---+---|
| 4 | 8 | 5 |
#+TBLFM: $2=$1*remote(rates,@2$2)::$3=vsum(remote(rates,@2$2..@>$2))

NAME is found in this order:

1. a table after #+NAME: NAME or #+TBLNAME: NAME in the same file;
2. the first table in the entry whose ID property is NAME, in the same file;
3. the first table in the entry with that ID in any indexed file in your sidebar folders, read from the file on disk.

REF may use spreadsheet-style references such as B3 (column B, row 3), which become @3$2. A REF without a row, such as $1..$2, reads the row of the other table that has the current row's number. NAME can itself be a reference: in remote($1,@1$1), the current row's first field holds the table's name.

Calc expressions

Calc formulas use Calc's number rules: integers are exact, and decimal numbers are rounded to 12 significant digits after every operation. Results are shown with up to 8 significant digits unless a format flag says otherwise (org-calc-default-modes).

Operators, from lowest to highest precedence (the lowest, ||, is logical or, giving 1 or 0):

Parentheses group, [a, b, c] writes a vector, <2026-10-05 Mon> writes a date, and nan is "not a number".

Functions:

Other Calc functions, variables such as pi or e, symbolic results, complex results and division by zero need Emacs.

Mode flags and formats

After the formula, a ; starts its flags, as in $3=$1/$2;%.2f or $4=$1*2;f2:

The flags S (symbolic) and u need Emacs. Any other text after the flags is a format string applied to the result, such as %.2f or %d; format supports %s, %S, %d, %o, %x, %X, %c, %e, %f and %g.

Durations

With T, U or t, fields like 1:30 or 10:00:30 are read as hours, minutes and seconds:

| start    | end     | sum      | diff  | hours |
|----------+---------+----------+-------+-------|
| 1:30     | 0:45    | 02:15:00 | 00:45 |  3.00 |
| 10:00:30 | 2:15:10 | 12:15:40 | 07:45 | 20.02 |
#+TBLFM: $3=$1+$2;T::$4=$1-$2;U::$5=$1*2;t

Dates

Timestamps in fields, active or inactive, take part in Calc arithmetic as dates. The difference of two dates is a number of days, with a fraction when the timestamps have times. A date plus a number is a date, written back as an inactive timestamp:

| start            | end              | days | later            |
|------------------+------------------+------+------------------|
| <2026-10-05 Mon> | <2026-10-12 Mon> |    7 | [2026-10-12 Mon] |
#+TBLFM: $3=$2-$1::$4=$1+7

Lisp formulas

A formula that starts with '( is Emacs Lisp. Each reference becomes a Lisp string, or a number with N, or the field's text inserted as is with L. A range becomes the values separated by spaces, so wrap it in a quoted list:

| name  | greeting |
|-------+----------|
| Ada   | Ada!     |
| Grace | Grace!   |
#+TBLFM: $2='(concat $1 "!")

| n |
|---|
| 1 |
| 2 |
|---|
| 3 |
#+TBLFM: @>$1='(apply '+ '(@I..@II));N

The evaluator supports:

• special forms: quote, function, lambda, progn, prog1, if, when, unless, cond, and, or, let, let*, setq, push, pop, while, dolist, dotimes, with-output-to-string, ignore-errors, condition-case;
• arithmetic: +, -, *, /, %, mod, 1+, 1-, abs, max, min, float, floor, ceiling, round, truncate, =, <, >, <=, >=, /=, zerop;
• predicates: not, null, eq, eql, equal, numberp, integerp, floatp, stringp, listp, consp, symbolp;
• lists: car, cdr, cadr, cddr, cons, list, nth, nthcdr, elt, aref, append, length, reverse, number-sequence, memq, member, memql, assoc, assq, delq, delete, mapcar, mapc, mapconcat, funcall, apply, identity, ignore;
• strings: concat, format, format-message, string=, string-equal, string<, string-lessp, upcase, downcase, capitalize, substring, string-to-number, number-to-string, int-to-string, string-prefix-p, string-suffix-p, string-empty-p, string-trim, split-string, prin1-to-string;
• output and errors: princ, prin1, print, terpri, message, error, user-error;
• Org's lookup functions org-lookup-first, org-lookup-last and org-lookup-all.

Any other function needs Emacs. An error inside a Lisp formula writes #ERROR in the field, as does a Calc error.

Entering formulas

There are three ways to set a formula.

In the field. Type =expr in a field and press TAB or RET: Orgstar stores $N=expr as the column's formula and evaluates it, as org-table-maybe-eval-formula does. Type :=expr instead to store a field formula @R$C=expr.

With a prompt. org-table-eval-formula asks for the formula (Column formula $N= or Field formula @R$C=) with the stored one filled in, stores it and evaluates it in the current field. Clearing the prompt and pressing Return removes the stored formula, as in Emacs, and the echo area shows Formula removed. You can also delete a formula in the formula editor below or from the #+TBLFM: line.

Org's C-u C-c = for field formulas has no equivalent key, because Orgstar has no prefix argument; use the menu item or type := in the field.

In the formula editor. C-c ' in a table or on its #+TBLFM: line (org-table-edit-formulas) opens the formulas in an editor of their own, one per line, grouped under # Column Formulas, # Field and Range Formulas and # Named Field Formulas. A formula can continue on indented lines. C-c ' or ⌘Return installs the formulas; Escape or C-c C-k leaves them unchanged. Installing doesn't recalculate. The echo area says so and points to Recalculate Table: C-c C-c on the #+TBLFM: line, or ⌃⌘X there in the Mac preset.

The formulas are stored sorted the way org-table-formula-less-p sorts them.

Recalculating

In Doom's normal state, RET in a table recalculates it when it has a #+TBLFM: line and aligns it otherwise; on a #+TBLFM: line it recalculates.

When the table has a rule below its first data row, recalculating the whole table leaves the rows above that rule, the header, alone. With marked rows, the marks decide instead (see Names, parameters and constants). Each command evaluates the column formulas row by row, then the field formulas, then aligns the table. Formulas are evaluated once; Org's iterate-until-stable recalculation (C-u C-u C-c *) isn't available.

Tables are not recalculated automatically. Rows marked # are not recalculated when you press TAB or RET in them, as org-table-maybe-recalculate-line would do in Emacs; recalculate with one of the commands above, or with C-c C-c (Mac ⌃⌘X) in the row.

When Emacs is needed

When a formula uses something the native evaluator doesn't have, the command reports what it was and the Mac recalculates the table in Emacs instead. This happens for:

• references to fields holding text in a Calc formula, and symbolic results;
• Calc functions and variables not listed above, precision other than p12, and the S and u flags;
• division by zero, complex results, vector results, and numbers too large for 64-bit integers;
• Lisp functions not listed above.

The echo area shows Recalculating in Emacs (reason)…, then Recalculated in Emacs. Orgstar runs emacs -Q --batch on a copy of the file, so your Emacs init file, packages and customizations are not loaded, then replaces the table with Emacs's result. It looks for Emacs at the path in the ORGSTAR_EMACS environment variable, then /opt/homebrew/bin/emacs, /usr/local/bin/emacs, /Applications/Emacs.app/Contents/MacOS/Emacs, /run/current-system/sw/bin/emacs and /usr/bin/emacs. If none is found, the echo area says Emacs isn't installed and the table is unchanged. Emacs gets your PATH with /opt/homebrew/bin, /usr/local/bin, /Library/TeX/texbin, /usr/bin and /bin added, as code blocks and export do, so programs a formula starts are found when Orgstar was opened from the Dock. The run stops after 60 seconds. If you edit the table while Emacs is working, its result is discarded.

Edit ▸ Cancel Running Task (⌘.) stops the recalculation; the echo area shows Recalculation canceled and the table is unchanged. Starting another recalculation or export in Emacs cancels the one that is running.

If the table's formulas contain Lisp, Orgstar asks first: This table's formulas run Lisp. Run them? (yes, no, always). always trusts this table's text in this file, so the question isn't asked again until the text changes.

Entering a formula that needs Emacs with C-c =, Set Field Formula or = in a field is not handed to Emacs. The formula is stored in the #+TBLFM: line and the field is left as it was; the echo area shows The formula was stored; recalculating it needs Emacs and the reason. TAB and RET still move to the next field. Recalculate the table to run the formula in Emacs.

For how Orgstar and Emacs share files, see Using Orgstar alongside Emacs.

table.el tables

Tables drawn with + corners and - and | borders, as the table.el package makes them, are recognized and kept as written:

+-------+-------+
| Name  | Value |
+-------+-------+
| a     | 1     |
+-------+-------+

Orgstar doesn't edit them as tables: TAB, alignment and formulas don't apply. HTML export renders them as tables, with cells that span rows and columns, and Markdown export writes them as a code block. See Export.

Plotting

#+PLOT: lines are recognized and completed as keywords, but Orgstar doesn't draw plots (org-plot/gnuplot is not available).

On iOS

The iOS app evaluates formulas natively with the same engine. Tables that need Emacs are not recalculated there; the app reports This table needs Emacs, which runs on the Mac with the reason. Table import and export are Mac only. See iOS.