mirror of
https://git.savannah.gnu.org/git/guile.git
synced 2025-04-30 03:40:34 +02:00
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'.
This commit is contained in:
parent
764e3614b8
commit
35566ea585
2 changed files with 34 additions and 32 deletions
|
@ -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
|
that is zero or more two-element lists of a variable and an arbitrary
|
||||||
expression each. All @var{variable} names must be distinct.
|
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.
|
A @code{let} expression is evaluated as follows.
|
||||||
|
|
||||||
@itemize @bullet
|
@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.
|
The values of the @var{init} expressions are stored into the variables.
|
||||||
|
|
||||||
@item
|
@item
|
||||||
The expressions in @var{body} are evaluated in order, and the value of
|
The expressions and definitions in @var{body} are evaluated in order
|
||||||
the last expression is returned as the value of the @code{let}
|
(@pxref{Internal Definitions}), and the values of the last expression
|
||||||
expression.
|
are returned as the result of the @code{let} expression.
|
||||||
@end itemize
|
@end itemize
|
||||||
|
|
||||||
The @var{init} expressions are not allowed to refer to any of the
|
The @var{init} expressions are not allowed to refer to any of the
|
||||||
|
|
|
@ -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.
|
compound expression out of this sequence of sub-expressions.
|
||||||
|
|
||||||
@deffn syntax begin expr @dots{}
|
@deffn syntax begin expr @dots{}
|
||||||
The expression(s) are evaluated in left-to-right order and the value of
|
The expression(s) are evaluated in left-to-right order and the values of
|
||||||
the last expression is returned as the value of the
|
the last expression are returned as the result of the
|
||||||
@code{begin}-expression. This expression type is used when the
|
@code{begin}-expression. This expression type is used when the
|
||||||
expressions before the last one are evaluated for their side effects.
|
expressions before the last one are evaluated for their side effects.
|
||||||
@end deffn
|
@end deffn
|
||||||
|
@ -117,7 +117,7 @@ abuses the @code{begin} form for these two tasks.
|
||||||
|
|
||||||
Guile provides three syntactic constructs for conditional evaluation.
|
Guile provides three syntactic constructs for conditional evaluation.
|
||||||
@code{if} is the normal if-then-else expression (with an optional else
|
@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
|
and @code{case} branches if an expression has one of a set of constant
|
||||||
values.
|
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).
|
an expression that is evaluated for effect, not for value).
|
||||||
|
|
||||||
In such a case, it is considered more clear to express these intentions
|
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
|
with the special forms @code{when} and @code{unless}. As an added
|
||||||
bonus, these forms accept multiple statements to evaluate, which are
|
bonus, these forms take a @emph{body} like in a @code{let} expression,
|
||||||
implicitly wrapped in a @code{begin}.
|
which can contain internal definitions and multiple statements to
|
||||||
|
evaluate (@pxref{Local Bindings}).
|
||||||
|
|
||||||
@deffn {Scheme Syntax} when test statement1 statement2 ...
|
@deffn {Scheme Syntax} when test body
|
||||||
@deffnx {Scheme Syntax} unless test statement1 statement2 ...
|
@deffnx {Scheme Syntax} unless test body
|
||||||
The actual definitions of these forms are in many ways their most clear
|
The actual definitions of these forms may be their most clear documentation:
|
||||||
documentation:
|
|
||||||
|
|
||||||
@example
|
@example
|
||||||
(define-syntax-rule (when test stmt stmt* ...)
|
(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:
|
Each @code{cond}-clause must look like this:
|
||||||
|
|
||||||
@lisp
|
@lisp
|
||||||
(@var{test} @var{body} @dots{})
|
(@var{test} @var{body})
|
||||||
@end lisp
|
@end lisp
|
||||||
|
|
||||||
where @var{test} is an arbitrary expression and @var{body} is a
|
where @var{test} is an arbitrary expression, or like this
|
||||||
lambda-like body, or like this
|
|
||||||
|
|
||||||
@lisp
|
@lisp
|
||||||
(@var{test} => @var{expression})
|
(@var{test} => @var{expression})
|
||||||
|
@ -180,9 +179,9 @@ lambda-like body, or like this
|
||||||
where @var{expression} must evaluate to a procedure.
|
where @var{expression} must evaluate to a procedure.
|
||||||
|
|
||||||
The @var{test}s of the clauses are evaluated in order and as soon as one
|
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
|
of them evaluates to a true value, the corresponding @var{body} is
|
||||||
are evaluated in order and the last value is returned as the value of
|
evaluated to produce the result of the @code{cond}-expression. For the
|
||||||
the @code{cond}-expression. For the @code{=>} clause type,
|
@code{=>} clause type,
|
||||||
@var{expression} is evaluated and the resulting procedure is applied to
|
@var{expression} is evaluated and the resulting procedure is applied to
|
||||||
the value of @var{test}. The result of this procedure application is
|
the value of @var{test}. The result of this procedure application is
|
||||||
then the result of the @code{cond}-expression.
|
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}.
|
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
|
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.
|
result of the @code{cond}-expression.
|
||||||
@end deffn
|
@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
|
@var{key} may be any expression, and the @var{clause}s must have the form
|
||||||
|
|
||||||
@lisp
|
@lisp
|
||||||
((@var{datum1} @dots{}) @var{body} @dots{})
|
((@var{datum1} @dots{}) @var{body})
|
||||||
@end lisp
|
@end lisp
|
||||||
|
|
||||||
or
|
or
|
||||||
|
@ -229,7 +228,7 @@ or
|
||||||
and the last @var{clause} may have the form
|
and the last @var{clause} may have the form
|
||||||
|
|
||||||
@lisp
|
@lisp
|
||||||
(else @var{expr1} @var{body} @dots{})
|
(else @var{body})
|
||||||
@end lisp
|
@end lisp
|
||||||
|
|
||||||
or
|
or
|
||||||
|
@ -241,14 +240,13 @@ or
|
||||||
All @var{datum}s must be distinct. First, @var{key} is evaluated. The
|
All @var{datum}s must be distinct. First, @var{key} is evaluated. The
|
||||||
result of this evaluation is compared against all @var{datum} values
|
result of this evaluation is compared against all @var{datum} values
|
||||||
using @code{eqv?}. When this comparison succeeds, the @var{body}
|
using @code{eqv?}. When this comparison succeeds, the @var{body}
|
||||||
following the @var{datum} is evaluated like the body of a lambda,
|
following the @var{datum} is evaluated to produce the result of the
|
||||||
returning the value of the last expression as the result of the
|
|
||||||
@code{case} expression.
|
@code{case} expression.
|
||||||
|
|
||||||
If the @var{key} matches no @var{datum} and there is an
|
If the @var{key} matches no @var{datum} and there is an
|
||||||
@code{else}-clause, the @var{body} following the @code{else} is
|
@code{else}-clause, the @var{body} following the @code{else} is
|
||||||
evaluated. If there is no such clause, the result of the expression is
|
evaluated to produce the result of the @code{case} expression. If there
|
||||||
unspecified.
|
is no such clause, the result of the expression is unspecified.
|
||||||
|
|
||||||
For the @code{=>} clause types, @var{expression} is evaluated and the
|
For the @code{=>} clause types, @var{expression} is evaluated and the
|
||||||
resulting procedure is applied to the value of @var{key}. The result of
|
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))
|
(use-modules (ice-9 receive))
|
||||||
@end lisp
|
@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
|
Evaluate the expression @var{expr}, and bind the result values (zero
|
||||||
or more) to the formal arguments in @var{formals}. @var{formals} is a
|
or more) to the formal arguments in @var{formals}. @var{formals} is a
|
||||||
list of symbols, like the argument list in a @code{lambda}
|
list of symbols, like the argument list in a @code{lambda}
|
||||||
(@pxref{Lambda}). After binding the variables, the expressions in
|
(@pxref{Lambda}). After binding the variables, the @var{body} is
|
||||||
@var{body} @dots{} are evaluated in order, the return value is the
|
evaluated to produce the result of the @code{receive} expression.
|
||||||
result from the last expression.
|
|
||||||
|
|
||||||
For example getting results from @code{partition} in SRFI-1
|
For example getting results from @code{partition} in SRFI-1
|
||||||
(@pxref{SRFI-1}),
|
(@pxref{SRFI-1}),
|
||||||
|
@ -1950,8 +1947,8 @@ set/restored when control enter or leaves the established dynamic
|
||||||
extent.
|
extent.
|
||||||
@end deffn
|
@end deffn
|
||||||
|
|
||||||
@deffn {Scheme Macro} with-fluids ((fluid value) @dots{}) body1 body2 @dots{}
|
@deffn {Scheme Macro} with-fluids ((fluid value) @dots{}) body
|
||||||
Execute body @var{body1} @var{body2} @dots{} while each @var{fluid} is
|
Execute @var{body} (@pxref{Local Bindings}) while each @var{fluid} is
|
||||||
set to the corresponding @var{value}. Both @var{fluid} and @var{value}
|
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
|
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
|
inside a @code{dynamic-wind} and the fluids are set/restored when
|
||||||
|
|
Loading…
Add table
Add a link
Reference in a new issue