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-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
@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
@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
@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
@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:
@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
HCoop / bpt / guile.git / commitdiff