From 35566ea585d6ebb0e97a83956de6a39ae2a0c2d5 Mon Sep 17 00:00:00 2001 From: Daniel Llorens Date: Tue, 24 Jan 2023 11:26:44 +0100 Subject: 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. (Fluids and Dynamic States): Use 'body' in the syntax description of 'with-fluids'. --- doc/ref/api-binding.texi | 11 +++++++--- doc/ref/api-control.texi | 55 +++++++++++++++++++++++------------------------- 2 files changed, 34 insertions(+), 32 deletions(-) diff --git a/doc/ref/api-binding.texi b/doc/ref/api-binding.texi index 60f034a0e..32170f978 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..8b4bd45d5 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}), @@ -1950,8 +1947,8 @@ set/restored when control enter or leaves the established dynamic extent. @end deffn -@deffn {Scheme Macro} with-fluids ((fluid value) @dots{}) body1 body2 @dots{} -Execute body @var{body1} @var{body2} @dots{} while each @var{fluid} is +@deffn {Scheme Macro} with-fluids ((fluid value) @dots{}) body +Execute @var{body} (@pxref{Local Bindings}) while each @var{fluid} is set to the corresponding @var{value}. Both @var{fluid} and @var{value} are evaluated and @var{fluid} must yield a fluid. The body is executed inside a @code{dynamic-wind} and the fluids are set/restored when -- cgit v1.2.1