On 25/11/2020 05:37, Kyle Meyer wrote: > Daniele Nicolodi writes: > >> Hello, >> >> I always found the description of Lisp forms in Org table formulas not >> extremely clear, especially in regard to the use of mode flags. The >> attached patch tries to clarify the manual a bit. > > Thanks.
Thank you for the review, Kyle. An updated patch is attached. >> Would it be worth to mention org-sbe in the same section of the manual? > > Yeah, it looks like there's no mention of org-sbe in the manual, so I > think so (as a separate patch). After playing a bit with org-sbe, I came to the conclusion that it is broken beyond repair, at least without breaking it for the people that managed to make it work for them. I think that adding mention of it in the manual and explain all the quirks of the macro is much more work than replace it with something better. I tried to write a better macro, please have a look here: https://orgmode.org/list/d429d29b-42fa-7d7b-6f3a-9fe692fd6...@grinta.net/ and the parent message for an explanation of what I think is broken in org-sbe. Would you support adding org-sbx (for a lack of a better name) to ob-table.el and mention it in the manual instead of org-sbe? I would not go as far as deprecating org-sbe, just yet, but maybe soon... Cheers, Dan
From d39ec4465605f56d5f53a36faf4e419ae1b862f0 Mon Sep 17 00:00:00 2001 From: Daniele Nicolodi <dani...@grinta.net> Date: Sat, 14 Nov 2020 18:33:41 +0100 Subject: [PATCH] doc/org-manual.org: Extend table formulas Lisp form documentation doc/org-manual.org (Emacs Lisp forms as formulas): Be more explicit about how fields are interpolated into the Lisp forms, clarify the use of mode flags, and add a couple more examples. --- doc/org-manual.org | 64 +++++++++++++++++++++++++++++----------------- 1 file changed, 40 insertions(+), 24 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index 2f7f5f847..97018d075 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -2178,38 +2178,54 @@ It is also possible to write a formula in Emacs Lisp. This can be useful for string manipulation and control structures, if Calc's functionality is not enough. -If a formula starts with a single-quote followed by an opening -parenthesis, then it is evaluated as a Lisp form. The evaluation -should return either a string or a number. Just as with Calc -formulas, you can specify modes and a ~printf~ format after -a semicolon. +A formula is evaluated as a Lisp form when it starts with a +single-quote followed by an opening parenthesis. Cell table +references are interpolated into the Lisp form before execution. The +evaluation should return either a string or a number. Evaluation +modes and a ~printf~ format used to render the returned values can be +specified after a semicolon. -With Emacs Lisp forms, you need to be conscious about the way field -references are interpolated into the form. By default, a reference is -interpolated as a Lisp string (in double-quotes) containing the field. -If you provide the =N= mode switch, all referenced elements are -numbers---non-number fields will be zero---and interpolated as Lisp -numbers, without quotes. If you provide the =L= flag, all fields are -interpolated literally, without quotes. For example, if you want a -reference to be interpreted as a string by the Lisp form, enclose the -reference operator itself in double-quotes, like ="$3"=. Ranges are -inserted as space-separated fields, so you can embed them in list or -vector syntax. +By default, references are interpolated as literal Lisp strings: the +field content is replaced in the Lisp form stripped of leading and +trailing white space and surrounded in double-quotes. For example: -Here are a few examples---note how the =N= mode is used when we do -computations in Lisp: +: '(concat $1 $2) -- ='(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))= :: +#+texinfo: @noindent +concatenates the content of columns 1 and column 2. + +When the =N= flag is used, all referenced elements are parsed as +numbers and interpolated as Lisp numbers, without quotes. Fields that +cannot be parsed as numbers are interpolated as zeros. For example: + +: '(+ $1 $2);N + +#+texinfo: @noindent +adds columns 1 and 2, equivalent to Calc's =$1+$2=. Ranges are +inserted as space-separated fields, so they can be embedded in list or +vector syntax. For example: - Swap the first two characters of the content of column 1. +: '(apply '+ '($1..$4));N -- ='(+ $1 $2);N= :: +#+texinfo: @noindent +computes the sum of columns 1 to 4, like Calc's =vsum($1..$4)=. + +When the =L= flag is used, all fields are interpolated literally: the +cell content is replaced in the Lisp form stripped of leading and +trailing white space and without quotes. If a reference is intended +to be interpreted as a string by the Lisp form, the reference operator +itself should be enclosed in double-quotes, like ="$3"=. The =L= flag +is useful when strings and numbers are used in the same Lisp form. For +example: - Add columns 1 and 2, equivalent to Calc's =$1+$2=. +: '(substring "$1" $2 $3);L -- ='(apply '+ '($1..$4));N= :: +#+texinfo: @noindent +extracts the part of the string in column 1 between the character +positions specified in the integers in column 2 and 3 and it is easier +to read than the equivalent: - Compute the sum of columns 1 to 4, like Calc's =vsum($1..$4)=. +: '(substring $1 (string-to-number $2) (string-to-number $3)) *** Durations and time values :PROPERTIES: -- 2.29.2
