Org-mode mailing list
 help / color / mirror / Atom feed
From: Daniele Nicolodi <>
To: Kyle Meyer <>
Cc: Org Mode List <>
Subject: Re: [PATCH] doc/ Extend table formulas Lisp form documentation
Date: Wed, 25 Nov 2020 21:44:12 +0100
Message-ID: <> (raw)
In-Reply-To: <>

[-- Attachment #1: Type: text/plain, Size: 1291 bytes --]

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:

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...


[-- Attachment #2: --]
[-- Type: text/plain, Size: 4248 bytes --]

From d39ec4465605f56d5f53a36faf4e419ae1b862f0 Mon Sep 17 00:00:00 2001
From: Daniele Nicolodi <>
Date: Sat, 14 Nov 2020 18:33:41 +0100
Subject: [PATCH] doc/ Extend table formulas Lisp form

doc/ (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/ | 64 +++++++++++++++++++++++++++++-----------------
 1 file changed, 40 insertions(+), 24 deletions(-)

diff --git a/doc/ b/doc/
index 2f7f5f847..97018d075 100644
--- a/doc/
+++ b/doc/
@@ -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
-  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

  reply	other threads:[~2020-11-25 20:44 UTC|newest]

Thread overview: 9+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-11-14 18:06 Daniele Nicolodi
2020-11-16 10:25 ` Eric S Fraga
2020-11-16 10:51   ` Daniele Nicolodi
2020-11-16 12:35     ` Tim Cross
2020-11-18 19:42       ` TEC
2020-11-18 20:15         ` Charles Millar
2020-11-25  4:37 ` Kyle Meyer
2020-11-25 20:44   ` Daniele Nicolodi [this message]
2020-11-27  6:40     ` Kyle Meyer

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

  List information:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \ \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Org-mode mailing list

This inbox may be cloned and mirrored by anyone:

	git clone --mirror list/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 list list/ \
	public-inbox-index list

Example config snippet for mirrors.
Newsgroups are available over NNTP:

AGPL code for this site: git clone