From: lloda <lloda@sarc.name>
To: "Ludovic Courtès" <ludo@gnu.org>
Cc: "guile-devel@gnu.org" <guile-devel@gnu.org>,
"Linus Björnstam" <linus.bjornstam@veryfast.biz>,
"Lassi Kortela" <lassi@lassi.io>
Subject: Re: Add internal definitions to derived forms
Date: Tue, 24 Jan 2023 18:59:12 +0100 [thread overview]
Message-ID: <52FED4FA-CDCD-4DDE-B915-DD9002332D9B@sarc.name> (raw)
In-Reply-To: <87mt68wbip.fsf@gnu.org>
[-- Attachment #1: Type: text/plain, Size: 2171 bytes --]
> On 24 Jan 2023, at 10:02, Ludovic Courtès <ludo@gnu.org> wrote:
>
> Hi!
>
> lloda <lloda@sarc.name> skribis:
>
>>>> @lisp
>>>> -(@var{test} @var{body} @dots{})
>>>> +(@var{test} @var{body})
>>>
>>> I think removing dots is incorrect here because it suggests, according
>>> to the typographic conventions used in the document, that there can only
>>> be a single expression.
>
> [...]
>
>> This was actually the main thing I wanted to fix in this patch. Linus' patch had ‘body ...’ but that clearly means ‘zero or more bodies’, which doesn't work because there's exactly one ‘body’. I.e. ‘body’ isn't an expression that is tagged ‘body’, it's, well, a ‘body’.
>
> Yeah, ‘body’ is a bit confusing here; in the example above, I’d have
> written:
>
> (@var{test} @var{exp} @dots{})
>
> because that’s what the “body” is: one or more expressions.
Hmm, it would seem so, but the way the Scheme reports use ‘expression’, it's not.
I've added an explicit definition of what the let-expression body is in the updated patch, I hope that reads better. Also tried to address your other comments.
Thanks
Daniel
>> The Scheme reports use one ‘<body>’ and no dots in all these definitions. See also the definition of let in the linked section ‘Local Bindings’, which again uses ‘body’ and no dots. I hoped that section would count as definition of ‘body’, and the section on ‘Internal Definitions’ explains precisely what can go into ‘body’, so I linked to that as well. I see that isn't clear enough. Maybe ‘body’ should be explicitly defined in one of these sections?
>
> Damn it, I hadn’t realized this was a widespread convention, but yeah,
> R5RS and parts of the Guile manual follow this convention. So hmm, the
> change you propose makes a lot of sense to me now.
>
> So yeah overall I guess we should always write one of:
>
> (something @var{body})
>
> or:
>
> (something @var{exp} @dots{})
>
> Using @var{body} like you do in this patch is consistent with other
> parts of the manual, so it LGTM.
>
> Thanks,
> Ludo’.
[-- Attachment #2: 0002-Document-multiple-value-returns-in-forms-taking-a-le.patch --]
[-- Type: application/octet-stream, Size: 8146 bytes --]
From 70ce7174a43ba17f2db0c3a6b7eeeb191a332663 Mon Sep 17 00:00:00 2001
From: Daniel Llorens <lloda@sarc.name>
Date: Tue, 24 Jan 2023 11:26:44 +0100
Subject: [PATCH 2/2] Document multiple-value returns in forms taking a
let-expression body
* doc/ref/api-binding.texi (Local Bindings): Document multiple-value
returns for let.
* doc/ref/api-control.texi (begin): Document multiple-value returns for
begin.
(Conditionals): Document multiple-value returns and use 'body' in the
syntax description of when, unless, cond, case.
(Multiple values): Document multiple-value returns and use 'body' in
the syntax description of SRFI-8 receive.
---
doc/ref/api-binding.texi | 11 ++++++---
doc/ref/api-control.texi | 51 +++++++++++++++++++---------------------
2 files changed, 32 insertions(+), 30 deletions(-)
diff --git a/doc/ref/api-binding.texi b/doc/ref/api-binding.texi
index 60f034a0e..a0cf8f0d8 100644
--- a/doc/ref/api-binding.texi
+++ b/doc/ref/api-binding.texi
@@ -138,6 +138,11 @@ The most basic local binding construct is @code{let}.
that is zero or more two-element lists of a variable and an arbitrary
expression each. All @var{variable} names must be distinct.
+@cindex body, of a @code{let} expression
+
+@var{body} is a sequence of expressions and definitions, ending in an
+expression.
+
A @code{let} expression is evaluated as follows.
@itemize @bullet
@@ -151,9 +156,9 @@ New storage is allocated for the @var{variables}.
The values of the @var{init} expressions are stored into the variables.
@item
-The expressions in @var{body} are evaluated in order, and the value of
-the last expression is returned as the value of the @code{let}
-expression.
+The expressions and definitions in @var{body} are evaluated in order
+(@pxref{Internal Definitions}), and the values of the last expression
+are returned as the result of the @code{let} expression.
@end itemize
The @var{init} expressions are not allowed to refer to any of the
diff --git a/doc/ref/api-control.texi b/doc/ref/api-control.texi
index ece6a6020..24356a273 100644
--- a/doc/ref/api-control.texi
+++ b/doc/ref/api-control.texi
@@ -47,8 +47,8 @@ output port, then display a newline. We use @code{begin} to form a
compound expression out of this sequence of sub-expressions.
@deffn syntax begin expr @dots{}
-The expression(s) are evaluated in left-to-right order and the value of
-the last expression is returned as the value of the
+The expression(s) are evaluated in left-to-right order and the values of
+the last expression are returned as the result of the
@code{begin}-expression. This expression type is used when the
expressions before the last one are evaluated for their side effects.
@end deffn
@@ -117,7 +117,7 @@ abuses the @code{begin} form for these two tasks.
Guile provides three syntactic constructs for conditional evaluation.
@code{if} is the normal if-then-else expression (with an optional else
-branch), @code{cond} is a conditional expression with multiple branches
+branch), @code{cond} is a conditional expression with multiple branches,
and @code{case} branches if an expression has one of a set of constant
values.
@@ -141,14 +141,14 @@ expression. (By convention, we use the word @dfn{statement} to refer to
an expression that is evaluated for effect, not for value).
In such a case, it is considered more clear to express these intentions
-with these special forms, @code{when} and @code{unless}. As an added
-bonus, these forms accept multiple statements to evaluate, which are
-implicitly wrapped in a @code{begin}.
+with the special forms @code{when} and @code{unless}. As an added
+bonus, these forms take a @emph{body} like in a @code{let} expression,
+which can contain internal definitions and multiple statements to
+evaluate (@pxref{Local Bindings}).
-@deffn {Scheme Syntax} when test statement1 statement2 ...
-@deffnx {Scheme Syntax} unless test statement1 statement2 ...
-The actual definitions of these forms are in many ways their most clear
-documentation:
+@deffn {Scheme Syntax} when test body
+@deffnx {Scheme Syntax} unless test body
+The actual definitions of these forms may be their most clear documentation:
@example
(define-syntax-rule (when test stmt stmt* ...)
@@ -167,11 +167,10 @@ statements if @var{test} is false.
Each @code{cond}-clause must look like this:
@lisp
-(@var{test} @var{body} @dots{})
+(@var{test} @var{body})
@end lisp
-where @var{test} is an arbitrary expression and @var{body} is a
-lambda-like body, or like this
+where @var{test} is an arbitrary expression, or like this
@lisp
(@var{test} => @var{expression})
@@ -180,9 +179,9 @@ lambda-like body, or like this
where @var{expression} must evaluate to a procedure.
The @var{test}s of the clauses are evaluated in order and as soon as one
-of them evaluates to a true value, the corresponding @var{expression}s
-are evaluated in order and the last value is returned as the value of
-the @code{cond}-expression. For the @code{=>} clause type,
+of them evaluates to a true value, the corresponding @var{body} is
+evaluated to produce the result of the @code{cond}-expression. For the
+@code{=>} clause type,
@var{expression} is evaluated and the resulting procedure is applied to
the value of @var{test}. The result of this procedure application is
then the result of the @code{cond}-expression.
@@ -209,7 +208,7 @@ procedure to the value(s) of @var{test}, in the same manner as the
The @var{test} of the last @var{clause} may be the symbol @code{else}.
Then, if none of the preceding @var{test}s is true, the
-@var{expression}s following the @code{else} are evaluated to produce the
+@var{body} following the @code{else} is evaluated to produce the
result of the @code{cond}-expression.
@end deffn
@@ -217,7 +216,7 @@ result of the @code{cond}-expression.
@var{key} may be any expression, and the @var{clause}s must have the form
@lisp
-((@var{datum1} @dots{}) @var{body} @dots{})
+((@var{datum1} @dots{}) @var{body})
@end lisp
or
@@ -229,7 +228,7 @@ or
and the last @var{clause} may have the form
@lisp
-(else @var{expr1} @var{body} @dots{})
+(else @var{body})
@end lisp
or
@@ -241,14 +240,13 @@ or
All @var{datum}s must be distinct. First, @var{key} is evaluated. The
result of this evaluation is compared against all @var{datum} values
using @code{eqv?}. When this comparison succeeds, the @var{body}
-following the @var{datum} is evaluated like the body of a lambda,
-returning the value of the last expression as the result of the
+following the @var{datum} is evaluated to produce the result of the
@code{case} expression.
If the @var{key} matches no @var{datum} and there is an
@code{else}-clause, the @var{body} following the @code{else} is
-evaluated. If there is no such clause, the result of the expression is
-unspecified.
+evaluated to produce the result of the @code{case} expression. If there
+is no such clause, the result of the expression is unspecified.
For the @code{=>} clause types, @var{expression} is evaluated and the
resulting procedure is applied to the value of @var{key}. The result of
@@ -970,13 +968,12 @@ same as specified by SRFI-8 (@pxref{SRFI-8}).
(use-modules (ice-9 receive))
@end lisp
-@deffn {library syntax} receive formals expr body @dots{}
+@deffn {library syntax} receive formals expr body
Evaluate the expression @var{expr}, and bind the result values (zero
or more) to the formal arguments in @var{formals}. @var{formals} is a
list of symbols, like the argument list in a @code{lambda}
-(@pxref{Lambda}). After binding the variables, the expressions in
-@var{body} @dots{} are evaluated in order, the return value is the
-result from the last expression.
+(@pxref{Lambda}). After binding the variables, the @var{body} is
+evaluated to produce the result of the @code{receive} expression.
For example getting results from @code{partition} in SRFI-1
(@pxref{SRFI-1}),
--
2.30.2
[-- Attachment #3: Type: text/plain, Size: 2 bytes --]
next prev parent reply other threads:[~2023-01-24 17:59 UTC|newest]
Thread overview: 22+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-11-09 15:32 Add internal definitions to derived forms Linus Björnstam
2022-11-09 15:46 ` Damien Mattei
2022-11-17 7:25 ` lloda
2022-11-18 9:04 ` Linus Björnstam
2022-11-18 9:27 ` Lassi Kortela
2022-11-18 9:50 ` Linus Björnstam
2022-11-18 10:22 ` Lassi Kortela
2022-11-18 12:53 ` Linus Björnstam
2022-11-18 13:18 ` Lassi Kortela
2023-01-19 17:54 ` lloda
2023-01-20 17:37 ` lloda
2023-01-23 22:13 ` Ludovic Courtès
2023-01-23 23:28 ` lloda
2023-01-24 7:33 ` Linus Björnstam
2023-01-24 9:02 ` Ludovic Courtès
2023-01-24 17:59 ` lloda [this message]
2023-01-25 10:33 ` Ludovic Courtès
2023-01-25 15:09 ` Ludovic Courtès
2023-01-25 15:38 ` Greg Troxel
2023-01-25 21:38 ` Linus Björnstam
2023-01-25 21:06 ` Linus Björnstam
2023-02-02 11:17 ` lloda
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.gnu.org/software/guile/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=52FED4FA-CDCD-4DDE-B915-DD9002332D9B@sarc.name \
--to=lloda@sarc.name \
--cc=guile-devel@gnu.org \
--cc=lassi@lassi.io \
--cc=linus.bjornstam@veryfast.biz \
--cc=ludo@gnu.org \
/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.
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).