emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Daniele Nicolodi <daniele@grinta.net>
To: Kyle Meyer <kyle@kyleam.com>
Cc: Org Mode List <emacs-orgmode@gnu.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: <932e0bdf-4738-ad95-64fd-e7cd6ea660e6@grinta.net> (raw)
In-Reply-To: <87im9u832j.fsf@kyleam.com>

[-- 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://orgmode.org/list/d429d29b-42fa-7d7b-6f3a-9fe692fd6dc7@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

[-- 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 <daniele@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


  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 [PATCH] doc/org-manual.org: Extend table formulas Lisp form documentation 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 \
    --in-reply-to=932e0bdf-4738-ad95-64fd-e7cd6ea660e6@grinta.net \
    --to=daniele@grinta.net \
    --cc=emacs-orgmode@gnu.org \
    --cc=kyle@kyleam.com \
    /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
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public 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).