From: Daniele Nicolodi <firstname.lastname@example.org> To: Kyle Meyer <email@example.com> Cc: Org Mode List <firstname.lastname@example.org> Subject: Re: [PATCH] doc/org-manual.org: Extend table formulas Lisp form documentation Date: Wed, 25 Nov 2020 21:44:12 +0100 [thread overview] Message-ID: <email@example.com> (raw) In-Reply-To: <firstname.lastname@example.org> [-- 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: https://email@example.com/ 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 [-- Attachment #2: 0001-doc-org-manual.org-Extend-table-formulas-Lisp-form-d.patch --] [-- Type: text/plain, Size: 4248 bytes --] From d39ec4465605f56d5f53a36faf4e419ae1b862f0 Mon Sep 17 00:00:00 2001 From: Daniele Nicolodi <firstname.lastname@example.org> 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
next prev parent 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: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style List information: https://www.orgmode.org/ * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --subject='Re: [PATCH] doc/org-manual.org: Extend table formulas Lisp form documentation' \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: link
Code repositories for project(s) associated with this inbox: https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).