From 396b2172e49390c329c4a4d74cf457b39c2cf0bd Mon Sep 17 00:00:00 2001 From: Michael Brand Date: Wed, 13 Nov 2013 20:10:56 +0100 Subject: [PATCH] Improve manual and ERT for table formulas * doc/org.texi (Field coordinates in formulas): Rephrase and add an example with a Lisp formula to copy from remote table. * testing/lisp/test-org-table.el (Comments): Adapt comment. (test-org-table/copy-field): Add reference to `test-org-table/remote-reference-access'. (test-org-table/remote-reference-access): Add reference to `test-org-table/copy-field'. Differentiate between Lisp formula to copy and Calc (or Lisp) formula to calculate. --- doc/org.texi | 33 ++++++++++++++++++++------------- testing/lisp/test-org-table.el | 27 ++++++++++++++++----------- 2 files changed, 36 insertions(+), 24 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index 748f3ea24..4aeae70e7 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -2547,21 +2547,28 @@ for Calc}. @cindex row, of field coordinates @cindex column, of field coordinates -For Calc formulas and Lisp formulas @code{@@#} and @code{$#} can be used to -get the row or column number of the field where the formula result goes. -The traditional Lisp formula equivalents are @code{org-table-current-dline} -and @code{org-table-current-column}. Examples: +One of the very first actions during evaluation of Calc formulas and Lisp +formulas is to substitute @code{@@#} and @code{$#} in the formula with the +row or column number of the field where the current result will go to. The +traditional Lisp formula equivalents are @code{org-table-current-dline} and +@code{org-table-current-column}. Examples: -@example -if(@@# % 2, $#, string("")) @r{column number on odd lines only} -$3 = remote(FOO, @@@@#$2) @r{copy column 2 from table FOO into} - @r{column 3 of the current table} -@end example +@table @code +@item if(@@# % 2, $#, string("")) +Insert column number on odd rows, set field to empty on even rows. +@item $2 = '(identity remote(FOO, @@@@#$1)) +Copy text or values of each row of column 1 of the table named @code{FOO} +into column 2 of the current table. +@item @@3 = 2 * remote(FOO, @@1$$#) +Insert the doubled value of each column of row 1 of the table named +@code{FOO} into row 3 of the current table. +@end table -@noindent For the second example, table FOO must have at least as many rows -as the current table. Note that this is inefficient@footnote{The computation time scales as -O(N^2) because table FOO is parsed for each field to be copied.} for large -number of rows. +@noindent For the second/third example, the table named @code{FOO} must have +at least as many rows/columns as the current table. Note that this is +inefficient@footnote{The computation time scales as O(N^2) because the table +named @code{FOO} is parsed for each field to be read.} for large number of +rows/columns. @subsubheading Named references @cindex named references diff --git a/testing/lisp/test-org-table.el b/testing/lisp/test-org-table.el index e78e56ba0..edb51c42d 100644 --- a/testing/lisp/test-org-table.el +++ b/testing/lisp/test-org-table.el @@ -20,10 +20,9 @@ ;;;; Comments: -;; Template test file for Org-mode tests. First the tests that are -;; also a howto example collection as a user documentation, more or -;; less all those using `org-test-table-target-expect'. Then the -;; internal and more abstract tests. See also the doc string of +;; Template test file for Org-mode tests. Many tests are also a howto +;; example collection as a user documentation, more or less all those +;; using `org-test-table-target-expect'. See also the doc string of ;; `org-test-table-target-expect'. ;;; Code: @@ -553,7 +552,8 @@ reference (with row). Mode string N." )) (ert-deftest test-org-table/copy-field () - "Experiments on how to copy one field into another field." + "Experiments on how to copy one field into another field. +See also `test-org-table/remote-reference-access'." (let ((target " | 0 | replace | @@ -772,21 +772,26 @@ reference (with row). Mode string N." ;; (string= "$3 = remote(FOO, @@#$2)" (org-table-convert-refs-to-rc "C& = remote(FOO, @@#B&)")))) (ert-deftest test-org-table/remote-reference-access () - "Access to remote reference." + "Access to remote reference. +See also `test-org-table/copy-field'." (org-test-table-target-expect " #+NAME: table -| | 42 | +| | x 42 | | -| replace | | +| replace | replace | " " #+NAME: table -| | 42 | +| | x 42 | | -| 42 | | +| x 42 | 84 x | " - 1 "#+TBLFM: $1 = remote(table, @1$2)")) + 1 (concat "#+TBLFM: " + ;; Copy text without calculation: Use Lisp formula + "$1 = '(identity remote(table, @1$2)) :: " + ;; Do a calculation: Use Calc (or Lisp ) formula + "$2 = 2 * remote(table, @1$2)"))) (ert-deftest test-org-table/org-at-TBLFM-p () (org-test-with-temp-text-in-file