org: Built-in table editor
3.1 The built-in table editor
=============================
Org makes it easy to format tables in plain ASCII. Any line with ‘|’ as
the first non-whitespace character is considered part of a table. ‘|’
is also the column separator(1). A table might look like this:
| Name | Phone | Age |
|-------+-------+-----|
| Peter | 1234 | 17 |
| Anna | 4321 | 25 |
A table is re-aligned automatically each time you press <TAB> or
<RET> or ‘C-c C-c’ inside the table. <TAB> also moves to the next field
(<RET> to the next row) and creates new table rows at the end of the
table or before horizontal lines. The indentation of the table is set
by the first line. Any line starting with ‘|-’ is considered as a
horizontal separator line and will be expanded on the next re-align to
span the whole table width. So, to create the above table, you would
only type
|Name|Phone|Age|
|-
and then press <TAB> to align the table and start filling in fields.
Even faster would be to type ‘|Name|Phone|Age’ followed by ‘C-c <RET>’.
When typing text into a field, Org treats <DEL>, <Backspace>, and all
character keys in a special way, so that inserting and deleting avoids
shifting other fields. Also, when typing _immediately after the cursor
was moved into a new field with ‘<TAB>’, ‘S-<TAB>’ or ‘<RET>’_, the
field is automatically made blank. If this behavior is too
unpredictable for you, configure the options ‘org-enable-table-editor’
and ‘org-table-auto-blank-field’.
Creation and conversion
.......................
‘C-c | (org-table-create-or-convert-from-region)’
Convert the active region to table. If every line contains at
least one TAB character, the function assumes that the material is
tab separated. If every line contains a comma, comma-separated
values (CSV) are assumed. If not, lines are split at whitespace
into fields. You can use a prefix argument to force a specific
separator: ‘C-u’ forces CSV, ‘C-u C-u’ forces TAB, and a numeric
argument N indicates that at least N consecutive spaces, or
alternatively a TAB will be the separator.
If there is no active region, this command creates an empty Org
table. But it is easier just to start typing, like
‘|Name|Phone|Age <RET> |- <TAB>’.
Re-aligning and field motion
............................
‘C-c C-c (org-table-align)’
Re-align the table and don’t move to another field.
‘<TAB> (org-table-next-field)’
Re-align the table, move to the next field. Creates a new row if
necessary.
‘S-<TAB> (org-table-previous-field)’
Re-align, move to previous field.
‘<RET> (org-table-next-row)’
Re-align the table and move down to next row. Creates a new row if
necessary. At the beginning or end of a line, <RET> still does
NEWLINE, so it can be used to split a table.
‘M-a (org-table-beginning-of-field)’
Move to beginning of the current table field, or on to the previous
field.
‘M-e (org-table-end-of-field)’
Move to end of the current table field, or on to the next field.
Column and row editing
......................
‘M-<left> (org-table-move-column-left)’
‘M-<right> (org-table-move-column-right)’
Move the current column left/right.
‘M-S-<left> (org-table-delete-column)’
Kill the current column.
‘M-S-<right> (org-table-insert-column)’
Insert a new column to the left of the cursor position.
‘M-<up> (org-table-move-row-up)’
‘M-<down> (org-table-move-row-down)’
Move the current row up/down.
‘M-S-<up> (org-table-kill-row)’
Kill the current row or horizontal line.
‘M-S-<down> (org-table-insert-row)’
Insert a new row above the current row. With a prefix argument,
the line is created below the current one.
‘C-c - (org-table-insert-hline)’
Insert a horizontal line below current row. With a prefix
argument, the line is created above the current line.
‘C-c <RET> (org-table-hline-and-move)’
Insert a horizontal line below current row, and move the cursor
into the row below that line.
‘C-c ^ (org-table-sort-lines)’
Sort the table lines in the region. The position of point
indicates the column to be used for sorting, and the range of lines
is the range between the nearest horizontal separator lines, or the
entire table. If point is before the first column, you will be
prompted for the sorting column. If there is an active region, the
mark specifies the first line and the sorting column, while point
should be in the last line to be included into the sorting. The
command prompts for the sorting type (alphabetically, numerically,
or by time). When called with a prefix argument, alphabetic
sorting will be case-sensitive.
Regions
.......
‘C-c C-x M-w (org-table-copy-region)’
Copy a rectangular region from a table to a special clipboard.
Point and mark determine edge fields of the rectangle. If there is
no active region, copy just the current field. The process ignores
horizontal separator lines.
‘C-c C-x C-w (org-table-cut-region)’
Copy a rectangular region from a table to a special clipboard, and
blank all fields in the rectangle. So this is the “cut” operation.
‘C-c C-x C-y (org-table-paste-rectangle)’
Paste a rectangular region into a table. The upper left corner
ends up in the current field. All involved fields will be
overwritten. If the rectangle does not fit into the present table,
the table is enlarged as needed. The process ignores horizontal
separator lines.
‘M-<RET> (org-table-wrap-region)’
Split the current field at the cursor position and move the rest to
the line below. If there is an active region, and both point and
mark are in the same column, the text in the column is wrapped to
minimum width for the given number of lines. A numeric prefix
argument may be used to change the number of desired lines. If
there is no region, but you specify a prefix argument, the current
field is made blank, and the content is appended to the field
above.
Calculations
............
‘C-c + (org-table-sum)’
Sum the numbers in the current column, or in the rectangle defined
by the active region. The result is shown in the echo area and can
be inserted with ‘C-y’.
‘S-<RET> (org-table-copy-down)’
When current field is empty, copy from first non-empty field above.
When not empty, copy current field down to next row and move cursor
along with it. Depending on the option ‘org-table-copy-increment’,
integer field values will be incremented during copy. Integers
that are too large will not be incremented. Also, a ‘0’ prefix
argument temporarily disables the increment. This key is also used
by shift-selection and related modes (
Conflicts).
Miscellaneous
.............
‘C-c ` (org-table-edit-field)’
Edit the current field in a separate window. This is useful for
fields that are not fully visible (Column width and
alignment). When called with a ‘C-u’ prefix, just make the full
field visible, so that it can be edited in place. When called with
two ‘C-u’ prefixes, make the editor window follow the cursor
through the table and always show the current field. The follow
mode exits automatically when the cursor leaves the table, or when
you repeat this command with ‘C-u C-u C-c `’.
‘M-x org-table-import RET’
Import a file as a table. The table should be TAB or whitespace
separated. Use, for example, to import a spreadsheet table or data
from a database, because these programs generally can write
TAB-separated text files. This command works by inserting the file
into the buffer and then converting the region to a table. Any
prefix argument is passed on to the converter, which uses it to
determine the separator.
‘C-c | (org-table-create-or-convert-from-region)’
Tables can also be imported by pasting tabular text into the Org
buffer, selecting the pasted text with ‘C-x C-x’ and then using the
‘C-c |’ command (see above under Creation and conversion).
‘M-x org-table-export RET’
Export the table, by default as a TAB-separated file. Use for data
exchange with, for example, spreadsheet or database programs. The
format used to export the file can be configured in the option
‘org-table-export-default-format’. You may also use properties
‘TABLE_EXPORT_FILE’ and ‘TABLE_EXPORT_FORMAT’ to specify the file
name and the format for table export in a subtree. Org supports
quite general formats for exported tables. The exporter format is
the same as the format used by Orgtbl radio tables, see
Translator functions, for a detailed description.
If you don’t like the automatic table editor because it gets in your
way on lines which you would like to start with ‘|’, you can turn it off
with
(setq org-enable-table-editor nil)
Then the only table command that still works is ‘C-c C-c’ to do a manual
re-align.
---------- Footnotes ----------
(1) To insert a vertical bar into a table field, use ‘\vert’ or,
inside a word ‘abc\vert{}def’.
Info Catalog
org: Tables
org: Tables
org: Column width and alignment