From: Daniele Nicolodi <firstname.lastname@example.org> To: Org Mode List <email@example.com> Subject: [PATCH] doc/org-manual.org: Extend table formulas Lisp form documentation Date: Sat, 14 Nov 2020 19:06:45 +0100 [thread overview] Message-ID: <firstname.lastname@example.org> (raw) [-- Attachment #1: Type: text/plain, Size: 283 bytes --] 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. Would it be worth to mention org-sbe in the same section of the manual? Cheers, Dan [-- Attachment #2: 0001-doc-org-manual.org-Extend-table-formulas-Lisp-form-d.patch --] [-- Type: text/plain, Size: 4108 bytes --] From aad5ba2217c30ff219069afbfdd8c65851f899d2 Mon Sep 17 00:00:00 2001 From: Daniele Nicolodi <email@example.com> Date: Sat, 14 Nov 2020 18:33:41 +0100 Subject: [PATCH] doc/org-manual.org: Extend table formulas Lisp form documentation Be more explicit about how fields are interpolated into the Lisp forms, clarify the use of mode flags, and add a cuple more examples. --- doc/org-manual.org | 60 +++++++++++++++++++++++++++------------------- 1 file changed, 36 insertions(+), 24 deletions(-) diff --git a/doc/org-manual.org b/doc/org-manual.org index 040fccc21..208e53023 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -2165,38 +2165,50 @@ 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))= :: +concatenates the content of columns 1 and column 2. - Swap the first two characters of the content of column 1. +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= :: +: '(+ $1 $2);N - Add columns 1 and 2, equivalent to Calc's =$1+$2=. +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: -- ='(apply '+ '($1..$4));N= :: +: '(apply '+ '($1..$4));N - Compute the sum of columns 1 to 4, like Calc's =vsum($1..$4)=. +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: + +: '(substring "$1" $2 $3);L + +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: + +: '(substring $1 (string-to-number $2) (string-to-number $3)) *** Durations and time values :PROPERTIES: -- 2.29.2
next reply other threads:[~2020-11-14 18:07 UTC|newest] Thread overview: 9+ messages / expand[flat|nested] mbox.gz Atom feed top 2020-11-14 18:06 Daniele Nicolodi [this message] 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 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 \ --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).