comment conventions.
(Block Comments): Documented multiline comments.
(Case Sensitivity): Documented R5RS and Guile behaviour and how to
switch it off.
* scheme-control.texi (Continuations): Added some documentation
for call/cc.
(Exceptions): Added xref to `Continuations'.
* scheme-binding.texi (Binding Reflection): Typo fix.
+2001-04-20 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
+
+ * scheme-evaluation.texi (Comments): Document normal comments and
+ comment conventions.
+ (Block Comments): Documented multiline comments.
+ (Case Sensitivity): Documented R5RS and Guile behaviour and how to
+ switch it off.
+
+ * scheme-control.texi (Continuations): Added some documentation
+ for call/cc.
+ (Exceptions): Added xref to `Continuations'.
+
+ * scheme-binding.texi (Binding Reflection): Typo fix.
+
2001-04-20 Neil Jerram <neil@ossau.uklinux.net>
* gh.texi (Executing Scheme code): gh_eval_file returns
@section Querying variable bindings
Guile provides a procedure for checking wehther a symbol is bound in the
-top level environment. If you want to whether a symbol is locally bound
-in expression, you can use the @code{bound?} macro from the module
+top level environment. If you want to test whether a symbol is locally
+bound in expression, you can use the @code{bound?} macro from the module
@code{(ice-9 optargs)}, documented in @ref{Optional Arguments}.
@c NJFIXME explain [env]
@end lisp
@end deffn
+
@node Continuations
@section Continuations
+@c FIXME::martin: Review me!
+
+@cindex call/cc
+The possibility to explicitly capture continuation and the use of
+@code{call-with-current-continuation} (also often called @code{call/cc}
+for shortness) is maybe the most powerful control structure known. All
+other control structures like loops or coroutines can be emulated using
+continuation.
+
+@c FIXME::martin: Is this too much of understatement, maybe confusing?
+@c I'm not sure.
+The implementation of continuations in Guile is not as efficient as one
+might except, because it is constrained by the fact that Guile is
+required to be cooperative to programs written in other languages, such
+as C which do not know about continuations. So continuations should be
+used when there is no other possibility to get the needed effect. If
+you find yourself using @code{call/cc} for escape procedures and your
+program is running to slow, you might want to use exceptions (REFFIXME)
+instead.
+
@rnindex call-with-current-continuation
-@c FIXME::martin: Document me!
-@deffn primitive call-with-current-continuation
+@deffn primitive call-with-current-continuation proc
+Capture the current continuation and call @var{proc} with the captured
+continuation as the single argument. This continuation can then be
+called with arbitrarily many arguments. Such a call will work like a
+goto to the invocation location of
+@code{call-with-current-continuation}, passing the arguments in a way
+that they are returned by the call to
+@code{call-with-current-continuation}. Since it is legal to store the
+captured continuation in a variable or to pass it to other procedures,
+it is possible that a procedure returns more than once, even if it is
+called only one time. This can be confusing at times.
@end deffn
+@c FIXME::martin: Better example needed.
+@lisp
+(define kont #f)
+(call-with-current-continuation
+ (lambda (k)
+ (set! kont k)
+ 1))
+@result{}
+1
+
+(kont 2)
+@result{}
+2
+@end lisp
+
+
@node Multiple Values
@section Returning and Accepting Multiple Values
@cindex exception handling
It is traditional in Scheme to implement exception systems using
-@code{call-with-current-continuation}. Guile does not do this, for
-performance reasons. The implementation of
+@code{call-with-current-continuation} (@pxref{Continuations}). Guile
+does not do this, for performance reasons. The implementation of
@code{call-with-current-continuation} is a stack copying implementation.
This allows it to interact well with ordinary C code. Unfortunately, a
stack-copying implementation can be slow -- creating a new continuation
@node Comments
@subsection Comments
+@c FIXME::martin: Review me!
+
+Comments in Scheme source files are written by starting them with a
+semicolon character (@code{;}). The comment then reaches up to the end
+of the line. Comments can begin at any column, and the may be inserted
+on the same line as Scheme code.
+
+@lisp
+; Comment
+;; Comment too
+(define x 1) ; Comment after expression
+(let ((y 1))
+ ;; Display something.
+ (display y)
+;;; Comment at left margin.
+ (display (+ y 1)))
+@end lisp
+
+It is common to use a single semicolon for comments following
+expressions on a line, to use two semicolons for comments which are
+indented like code, and three semicolons for comments which start at
+column 0, even if they are inside an indented code block. This
+convention is used when indenting code in Emacs' Scheme mode.
+
@node Block Comments
@subsection Block Comments
+@c FIXME::martin: Review me!
+
+@cindex multiline comments
+In addition to the standard line comments defined by R5RS, Guile has
+another comment type for multiline comments, called @dfn{block
+comments}. This type of comment begins with the character sequence
+@code{#!} and ends with the characters @code{!#}, which must appear on a
+line of their own. These comments are compatible with the block
+comments in the Scheme Shell @file{scsh} (REFFIXME). The characters
+@code{#!} were chosen because they are the magic characters used in
+shell scripts for indicating that the name of the program for executing
+the script follows on the same line.
+
+Thus a Guile script often starts like this.
+
+@lisp
+#! /usr/local/bin/guile -s
+!#
+@end lisp
+
+More details on Guile scripting can be found in the scripting section
+(REFFIXME).
+
@node Case Sensitivity
@subsection Case Sensitivity
+@c FIXME::martin: Review me!
+
+Scheme as defined in R5RS is not case sensitive when reading symbols.
+Guile, on the contrary is case sensitive by default, so the identifiers
+
+@lisp
+guile-whuzzy
+Guile-Whuzzy
+@end lisp
+
+are the same in R5RS Scheme, but are different in Guile.
+
+It is possible to turn off case sensitivity in Guile by setting the
+reader option @code{case-insensitive}. More on reader options can be
+found at (REFFIXME).
+
+@lisp
+(read-enable 'case-insensitive)
+@end lisp
+
+Note that this is seldom a problem, because Scheme programmers tend not
+to use uppercase letters in their identifiers anyway.
+
@node Keyword Syntax
@subsection Keyword Syntax
HCoop / bpt / guile.git / commitdiff