org: Editing and debugging formulas
3.5.8 Editing and debugging formulas
------------------------------------
You can edit individual formulas in the minibuffer or directly in the
field. Org can also prepare a special buffer with all active formulas
of a table. When offering a formula for editing, Org converts
references to the standard format (like ‘B3’ or ‘D&’) if possible. If
you prefer to only work with the internal format (like ‘@3$2’ or ‘$4’),
configure the option ‘org-table-use-standard-references’.
‘C-c = or C-u C-c = (org-table-eval-formula)’
Edit the formula associated with the current column/field in the
DONTPRINTYET minibuffer. See Column formulas, and *noteField and range
DONTPRINTYET minibuffer. See Column formulas, and Field and range
formulas.
‘C-u C-u C-c = (org-table-eval-formula)’
Re-insert the active formula (either a field formula, or a column
formula) into the current field, so that you can edit it directly
in the field. The advantage over editing in the minibuffer is that
you can use the command ‘C-c ?’.
‘C-c ? (org-table-field-info)’
While editing a formula in a table field, highlight the field(s)
referenced by the reference at the cursor position in the formula.
‘C-c }’
Toggle the display of row and column numbers for a table, using
overlays (‘org-table-toggle-coordinate-overlays’). These are
updated each time the table is aligned; you can force it with ‘C-c
C-c’.
‘C-c {’
Toggle the formula debugger on and off
(‘org-table-toggle-formula-debugger’). See below.
‘C-c ' (org-table-edit-formulas)’
Edit all formulas for the current table in a special buffer, where
the formulas will be displayed one per line. If the current field
has an active formula, the cursor in the formula editor will mark
it. While inside the special buffer, Org will automatically
highlight any field or range reference at the cursor position. You
may edit, remove and add formulas, and use the following commands:
‘C-c C-c or C-x C-s (org-table-fedit-finish)’
Exit the formula editor and store the modified formulas. With
‘C-u’ prefix, also apply the new formulas to the entire table.
‘C-c C-q (org-table-fedit-abort)’
Exit the formula editor without installing changes.
‘C-c C-r (org-table-fedit-toggle-ref-type)’
Toggle all references in the formula editor between standard
(like ‘B3’) and internal (like ‘@3$2’).
‘<TAB> (org-table-fedit-lisp-indent)’
Pretty-print or indent Lisp formula at point. When in a line
containing a Lisp formula, format the formula according to
Emacs Lisp rules. Another <TAB> collapses the formula back
again. In the open formula, <TAB> re-indents just like in
Emacs Lisp mode.
‘M-<TAB> (lisp-complete-symbol)’
Complete Lisp symbols, just like in Emacs Lisp mode.
‘S-<up>/<down>/<left>/<right>’
Shift the reference at point. For example, if the reference
is ‘B3’ and you press ‘S-<right>’, it will become ‘C3’. This
also works for relative references and for hline references.
‘M-S-<up> (org-table-fedit-line-up)’
‘M-S-<down> (org-table-fedit-line-down)’
Move the test line for column formulas in the Org buffer up
and down.
‘M-<up> (org-table-fedit-scroll-down)’
‘M-<down> (org-table-fedit-scroll-up)’
Scroll the window displaying the table.
‘C-c }’
Turn the coordinate grid in the table on and off.
Making a table field blank does not remove the formula associated
with the field, because that is stored in a different line (the
‘#+TBLFM’ line)—during the next recalculation the field will be filled
again. To remove a formula from a field, you have to give an empty
reply when prompted for the formula, or to edit the ‘#+TBLFM’ line.
You may edit the ‘#+TBLFM’ directly and re-apply the changed
equations with ‘C-c C-c’ in that line or with the normal recalculation
commands in the table.
Using multiple #+TBLFM lines
............................
You may apply the formula temporarily. This is useful when you switch
the formula. Place multiple ‘#+TBLFM’ lines right after the table, and
then press ‘C-c C-c’ on the formula to apply. Here is an example:
| x | y |
|---+---|
| 1 | |
| 2 | |
#+TBLFM: $2=$1*1
#+TBLFM: $2=$1*2
Pressing ‘C-c C-c’ in the line of ‘#+TBLFM: $2=$1*2’ yields:
| x | y |
|---+---|
| 1 | 2 |
| 2 | 4 |
#+TBLFM: $2=$1*1
#+TBLFM: $2=$1*2
Note: If you recalculate this table (with ‘C-u C-c *’, for example), you
will get the following result of applying only the first ‘#+TBLFM’ line.
| x | y |
|---+---|
| 1 | 1 |
| 2 | 2 |
#+TBLFM: $2=$1*1
#+TBLFM: $2=$1*2
Debugging formulas
..................
When the evaluation of a formula leads to an error, the field content
becomes the string ‘#ERROR’. If you would like see what is going on
during variable substitution and calculation in order to find a bug,
turn on formula debugging in the ‘Tbl’ menu and repeat the calculation,
for example by pressing ‘C-u C-u C-c = <RET>’ in a field. Detailed
information will be displayed.