mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-06-11 22:31:12 +02:00
Code Activity

* scheme-control.texi (Multiple Values): Documented concept of

Browse source 
multiple values, added docs for `receive'.
	(begin): Documented `begin'.
	(if cond case): Documented `if', `cond' and `case'.
	(and or): Documented `and' and `or'.
	(while do): Documented `do' and `while'.

	* scheme-procedures.texi (Optional Arguments): Split the node,
	added introductory text, added menu for subsections.
	(let-optional Reference, let-keywords Reference),
	(lambda* Reference, define* Reference): Added syntax documentation
	for all exported procedures from (ice-9 optargs).
This commit is contained in:
Martin Grabmüller 2001-04-17 19:29:52 +00:00
parent 239d2912a2
commit da54ce854a
4 changed files with 471 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

15
doc/ChangeLog
View file

@ -1,3 +1,18 @@
2001-04-17 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
* scheme-control.texi (Multiple Values): Documented concept of
multiple values, added docs for `receive'.
(begin): Documented `begin'.
(if cond case): Documented `if', `cond' and `case'.
(and or): Documented `and' and `or'.
(while do): Documented `do' and `while'.
* scheme-procedures.texi (Optional Arguments): Split the node,
added introductory text, added menu for subsections.
(let-optional Reference, let-keywords Reference),
(lambda* Reference, define* Reference): Added syntax documentation
for all exported procedures from (ice-9 optargs).
2001-04-17 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
* scheme-utility.texi (General Conversion): New node, added

209
doc/scheme-control.texi
View file

@ -18,18 +18,189 @@
@node begin
@section Evaluating a Sequence of Expressions
@c FIXME::martin: Review me!
@c FIXME::martin: Maybe add examples?
@cindex begin
@cindex sequencing
@cindex expression sequencing
@code{begin} is used for grouping several expression together so that
they syntactically are treated as if they were one expression. This is
particularly important when syntactic expressions are used which only
allow one expression, but the programmer wants to use more than one
expression in that place. As an example, consider the conditional
expression below:
@lisp
(if (> x 0)
(begin (display "greater") (newline)))
@end lisp
If the two calls to @code{display} and @code{newline} were not embedded
in a @code{begin}--statement, the call to @code{newline} would get
misinterpreted as the else--branch of the @code{if}--expression.
@deffn syntax begin expr1 expr2 @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
@code{begin}--expression. This expression type is used when the
expressions before the last one are evaluated for their side effects.
@end deffn
@node if cond case
@section Simple Conditional Evaluation
@c FIXME::martin: Review me!
@c FIXME::martin: Maybe add examples?
@cindex conditional evaluation
@cindex if
@cindex case
@cindex cond
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
and @code{case} branches if an expression has one of a set of constant
values.
@deffn syntax if test consequent [alternate]
All arguments may be arbitrary expressions. First, @var{test} is
evaluated. If it returns a true value, the expression @var{consequent}
is evaluated and @var{alternate} is ignoret. If @var{test} evaluates to
@code{#f}, @var{alternate} is evaluated instead. The value of the
evaluated branch (@var{consequent} or @var{alternate}) is returned as
the value of the @code{if} expression.
When @var{alternate} is omitted and the @var{test} evaluates to
@code{#f}, the value of the expression is not specified.
@end deffn
@deffn syntax cond clause1 clause2 @dots{}
Each @code{cond}-clause must look like this:
@lisp
(@var{test} @var{expression} @dots{})
@end lisp
where @var{test} and @var{expression} are arbitrary expression, or like
this
@lisp
(@var{test} => @var{expression}
@end lisp
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 values, 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,
@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.
The @var{test} of the last @var{clause} may be the keyword @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 result of the @code{cond}--expression.
@end deffn
@deffn syntax case key clause1 clause2 @dots{}
@var{key} may be any expression, the @var{clause}s must have the form
@lisp
((@var{datum1} @dots{}) @var{expr1} @var{expr2} @dots{})
@end lisp
and the last @var{clause} may have the form
@lisp
(else @var{expr1} @var{expr2} @dots{})
@end lisp
All @var{datum}s must be distinct. First, @var{key} is evaluated. The
the result of this evaluation is compared against all @var{datum}s using
@code{eqv?}. When this comparison succeeds, the epression(s) following
the @var{datum} are evaluated from left to right, returning the value of
the last expression as the result of the @code{case} expression.
If the @var{key} matches no @var{datum} and there is an
@code{else}--clause, the expressions following the @code{else} are
evaluated. If there is no such clause, the result of the expression is
unspecified.
@end deffn
@node and or
@section Conditional Evaluation of a Sequence of Expressions
@c FIXME::martin: Review me!
@c FIXME::martin: Maybe add examples?
@code{and} and @code{or} evaluate all their arguments, similar to
@code{begin}, but evaluation stops as soon as one of the expressions
evaluates to false or true, respectively.
@deffn syntax and expr @dots{}
Evaluate the @var{expr}s from left to right and stop evaluation as soon
as one expression evaluates to @code{#f}; the remaining expressions are
not evaluated. The value of the last evaluated expression is returned.
If no expression evaluates to @code{#f}, the value of the last
expression is returned.
If used without expressions, @code{#t} is returned.
@end deffn
@deffn syntax or expr @dots{}
Evaluate the @var{expr}s from left to right and stop evaluation as soon
as one expression evaluates to a true value (that is, a value different
from @code{#f}); the remaining expressions are not evaluated. The value
of the last evaluated expression is returned. If all expressions
evaluate to @code{#f}, @code{#f} is returned.
If used without expressions, @code{#f} is returned.
@end deffn
@node while do
@section Iteration mechanisms
@c FIXME::martin: Review me!
@c FIXME::martin: Maybe add examples?
@cindex iteration
@cindex looping
Scheme has only few iteration mechanisms, mainly because iteration in
Scheme programs is normally expressed using recursion. Nevertheless,
R5RS defines a construct for programming loops, calling @code{do}. In
addition, Guile has an explicit looping syntax called @code{while}.
@deffn syntax do ((variable1 init1 step1) @dots{}) (test expr @dots{}) command @dots{}
The @var{init} expressions are evaluated and the @var{variables} are
bound to their values. Then looping starts with testing the @var{test}
expression. If @var{test} evaluates to a true value, the @var{expr}
following the @var{test} are evaluated and the value of the last
@var{expr} is returned as the value of the @code{do} expression. If
@var{test} evaluates to false, the @var{command}s are evaluated in
order, the @var{step}s are evaluated and stored into the @var{variables}
and the next iteration starts.
Any of the @var{step} expressions may be omitted, so that the
corresponding variable is not changed during looping.
@end deffn
@deffn syntax while cond body @dots{}
Evaluate all expressions in @var{body} in order, as long as @var{cond}
evaluates to a true value. The @var{cond} expression is tested before
every iteration, so that the body is not evaluated at all if @var{cond}
is @code{#f} right from the start.
@end deffn
@node Continuations
@section Continuations
@ -42,8 +213,27 @@
@node Multiple Values
@section Returning and Accepting Multiple Values
@c FIXME::martin: Review me!
@cindex multiple values
@cindex receive
Scheme allows a procedure to return more than one value to its caller.
This is quite different to other languages which only allow
single--value returns. Returning multiple values is different from
returning a list (or pair or vector) of values to the caller, because
conceptionally not @emph{one} compound object is returned, but several
distinct values.
The primitive procedures for handling multiple values are @code{values}
and @code{call-with-values}. @code{values} is used for returning
multiple values from a procedure. This is done by placing a call to
@code{values} with zero or more arguments in tail position in a
procedure body. @code{call-with-values} combines a procedure returning
multiple values with a procedure which accepts these values as
parameters.
@rnindex values
@deffn primitive values . args
@deffn primitive values expr @dots{}
Delivers all of its arguments to its continuation. Except for
continuations created by the @code{call-with-values} procedure,
all continuations take exactly one value. The effect of
@ -70,6 +260,23 @@ of the call to @code{call-with-values}.
@end example
@end deffn
In addition to the fundamental procedures described above, Guile has a
module which exports a syntax called @code{receive}, which is much more
convenient. If you want to use it in your programs, you have to load
the module @code{(ice-9 receive)} with the statement
@lisp
(use-modules (ice-9 receive))
@end lisp
@deffn {library syntax} receive formals expr body @dots{}
Evaluate the expression @var{expr}, and bind the result values (zero or
more) to the formal arguments in the formal argument list @var{formals}.
@var{formals} must have the same syntax like the formal argument list
used in @code{lambda} (@pxref{Lambda}). After binding the variables,
the expressions in @var{body} @dots{} are evaluated in order.
@end deffn
@node Exceptions
@section Exceptions

12
doc/scheme-data.texi
View file

@ -1356,12 +1356,12 @@ called with string containing unusal characters.
@node String Syntax
@subsection String Read Syntax
The read syntax for strings is an arbitrarily long sequence of characters
enclosed in double quotes (@code{"}). @footnote{Actually, the current
implementation restricts strings to a length of 2^24 characters.} If
you want to insert a double quote character into a string literal, it
must be prefixed with a backslash @code{\} character (called an
@emph{escape character}).
The read syntax for strings is an arbitrarily long sequence of
characters enclosed in double quotes (@code{"}). @footnote{Actually, the
current implementation restricts strings to a length of 2^24
characters.} If you want to insert a double quote character into a
string literal, it must be prefixed with a backslash @code{\} character
(called an @emph{escape character}).
The following are examples of string literals:

242
doc/scheme-procedures.texi
View file

@ -81,6 +81,248 @@ order when the procedure is invoked.
@node Optional Arguments
@section Optional Arguments
@c FIXME::martin: Review me!
Scheme procedures, as defined in R5RS, can wither handle a fixed number
of actual arguments, or a fixed number of actual arguments followed by
arbitrarily many additional arguments. Writing procedures of variable
arity can be useful, but unfortunately, the syntactic means for handling
argument lists of varying length is a bit inconvenient. It is possible
to give names to the fixed number of argument, but the remaining
(optional) arguments can be only referenced as a list of values
(@pxref{Lambda}).
Guile comes with the module @code{(ice-9 optargs)}, which makes using
optional arguments much more convenient. In addition, this module
provides syntax for handling keywords in argument lists
(@pxref{Keywords}).
Before using any of the procedures or macros defined in this section,
you have to load the module @code{(ice-9 optargs)} with the statement:
@lisp
(use-modules (ice-9 optargs))
@end lisp
@menu
* let-optional Reference:: Locally binding optional arguments.
* let-keywords Reference:: Locally binding keywords arguments.
* lambda* Reference:: Creating advanced argument handling procedures.
* define* Reference:: Defining procedures and macros.
@end menu
@node let-optional Reference
@subsection let-optional Reference
@c FIXME::martin: Review me!
The syntax @code{let-optional} and @code{let-optional*} are for
destructuring rest argument lists and giving names to the various list
elements. @code{let-optional} binds all variables simultaneously, while
@code{let-optional*} binds them sequentially, consistent with @code{let}
and @code{let*} (REFFIXME).
@deffn {libary syntax} let-optional rest-arg (binding @dots{}) expr @dots{}
@deffnx {library syntax} let-optional* rest-arg (binding @dots{}) expr @dots{}
These two macros give you an optional argument interface that is very
@dfn{Schemey} and introduces no fancy syntax. They are compatible with
the scsh macros of the same name, but are slightly extended. Each of
@var{binding} may be of one of the forms @var{var} or @code{(@var{var}
@var{default-value})}. @var{rest-arg} should be the rest-argument of the
procedures these are used from. The items in @var{rest-arg} are
sequentially bound to the variable names are given. When @var{rest-arg}
runs out, the remaining vars are bound either to the default values or
left unbound if no default value was specified. @var{rest-arg} remains
bound to whatever may have been left of @var{rest-arg}.
After binding the variables, the expressions @var{expr} @dots{} are
evaluated in order.
@end deffn
@node let-keywords Reference
@subsection let-keywords Reference
@c FIXME::martin: Review me!
@code{let-keywords} and @code{let-keywords*} are used for extracting
values from argument lists which use keywords instead of argument
position for binding local variables to argument values.
@code{let-keywords} binds all variables simultaneously, while
@code{let-keywords*} binds them sequentially, consistent with @code{let}
and @code{let*} (REFFIXME).
@deffn {library syntax} let-keywords rest-arg allow-other-keys? (binding @dots{}) expr @dots{}
@deffnx {library syntax} let-keywords rest-arg allow-other-keys? (binding @dots{}) expr @dots{}
These macros pick out keyword arguments from @var{rest-arg}, but do not
modify it. This is consistent at least with Common Lisp, which
duplicates keyword arguments in the rest argument. More explanation of what
keyword arguments in a lambda list look like can be found below in
the documentation for @code{lambda*}
(@pxref{lambda* Reference}). @var{binding}s can have the same form as
for @code{let-optional}. If @var{allow-other-keys?} is false, an error
will be thrown if anything that looks like a keyword argument but does
not match a known keyword parameter will result in an error.
After binding the variables, the expressions @var{expr} @dots{} are
evaluated in order.
@end deffn
@node lambda* Reference
@subsection lambda* Reference
@c FIXME::martin: Review me!
When using optional and keyword argument lists, using @code{lambda} for
creating procedures and using @code{let-optional} or @code{let-keywords}
is a bit lengthy. Therefore, @code{lambda*} is provided, which combines
the features of those macros into a single convenient syntax.
For quick reference, here is the syntax of the formal argument list for
@code{lambda*} (brackets are used to indicate grouping only):
@example
ext-param-list ::= [identifier]* [#:optional [ext-var-decl]+]?
[#:key [ext-var-decl]+ [#:allow-other-keys]?]?
[[#:rest identifier]|[. identifier]]?
ext-var-decl ::= identifier | ( identifier expression )
@end example
The characters `*', `+' and `?' are not to be taken literally; they mean
respectively, zero or more occurences, one or more occurences, and one
or zero occurences.
@deffn {library syntax} lambda* formals body
@code{lambda*} creates a procedure that takes optional arguments. These
are specified by putting them inside brackets at the end of the
paramater list, but before any dotted rest argument. For example,
@lisp
(lambda* (a b #:optional c d . e) '())
@end lisp
creates a procedure with fixed arguments @var{a} and @var{b}, optional
arguments @var{c} and @var{d}, and rest argument @var{e}. If the
optional arguments are omitted in a call, the variables for them are
unbound in the procedure. This can be checked with the @code{bound?}
macro (documented below).
@code{lambda*} can also take keyword arguments. For example, a procedure
defined like this:
@lisp
(lambda* (#:key xyzzy larch) '())
@end lisp
can be called with any of the argument lists @code{(#:xyzzy 11)}
@code{(#:larch 13)} @code{(#:larch 42 #:xyzzy 19)} @code{()}. Whichever
arguments are given as keywords are bound to values.
Optional and keyword arguments can also be given default values
which they take on when they are not present in a call, by giving a
two-item list in place of an optional argument, for example in:
@lisp
(lambda* (foo #:optional (bar 42) #:key (baz 73))
(list foo bar baz))
@end lisp
@var{foo} is a fixed argument, @var{bar} is an optional argument with
default value 42, and baz is a keyword argument with default value 73.
Default value expressions are not evaluated unless they are needed and
until the procedure is called.
@code{lambda*} also supports two more special parameter list keywords.
@code{lambda*}-defined procedures now throw an error by default if a
keyword other than one of those specified is found in the actual
passed arguments. However, specifying @code{#:allow-other-keys}
immediately after the keyword argument declarations restores the
previous behavior of ignoring unknown keywords. @code{lambda*} also now
guarantees that if the same keyword is passed more than once, the
last one passed is the one that takes effect. For example,
@lisp
((lambda* (#:key (heads 0) (tails 0)) (display (list heads tails)))
#:heads 37 #:tails 42 #:heads 99)
@end lisp
would result in (99 47) being displayed.
@code{#:rest} is also now provided as a synonym for the dotted syntax
rest argument. The argument lists @code{(a . b)} and @code{(a #:rest b)}
are equivalent in all respects to @code{lambda*}. This is provided for
more similarity to DSSSL, MIT-Scheme and Kawa among others, as well as
for refugees from other Lisp dialects.
@end deffn
@deffn {library syntax} bound? variable
Check if a variable is bound in the current environment.
The procedure @code{defined?} doesn't quite cut it as it stands, since
it only checks bindings in the top-level environment, not those in local
scope only.
@end deffn
@node define* Reference
@subsection define* Reference
@c FIXME::martin: Review me!
Just like @code{define} has a shorthand notation for defining procedures
(@pxref{Lambda Alternatives}), @code{define*} is provided as an
abbreviation of the combination of @code{define} and @code{lambda*}.
@code{define*-public} is the @code{lambda*} version of
@code{define-public}; @code{defmacro*} and @code{defmacro*-public} exist
for defining macros with the improved argument list handling
possibilities. The @code{-public} versions not only define the
procedures/macros, but also export them from the current module.
@deffn {library syntax} define* formals body
@deffnx {library syntax} define*-public formals body
@code{define*} and @code{define*-public} support optional arguments with
a similar syntax to @code{lambda*}. They also support arbitrary-depth
currying, just like Guile's define. Some examples:
@lisp
(define* (x y #:optional a (z 3) #:key w . u)
(display (list y z u)))
@end lisp
defines a procedure @code{x} with a fixed argument @var{y}, an optional
agument @var{a}, another optional argument @var{z} with default value 3,
a keyword argument @var{w}, and a rest argument @var{u}.
@lisp
(define-public* ((foo #:optional bar) #:optional baz) '())
@end lisp
This illustrates currying. A procedure @code{foo} is defined, which,
when called with an optional argument @var{bar}, returns a procedure
that takes an optional argument @var{baz}.
Of course, @code{define*[-public]} also supports @code{#:rest} and
@code{#:allow-other-keys} in the same way as @code{lambda*}.
@end deffn
@deffn {library syntax} defmacro* name formals body
@deffnx {library syntax} defmacro*-public name formals body
These are just like @code{defmacro} and @code{defmacro-public} except that they
take @code{lambda*}-style extended paramter lists, where @code{#:optional},
@code{#:key}, @code{#:allow-other-keys} and @code{#:rest} are allowed with the usual
semantics. Here is an example of a macro with an optional argument:
@lisp
(defmacro* transmorgify (a #:optional b)
(a 1))
@end lisp
@end deffn
@node Procedure Properties
@section Procedure Properties and Metainformation