diff options
Diffstat (limited to 'doc/ref')
-rw-r--r-- | doc/ref/api-control.texi | 18 | ||||
-rw-r--r-- | doc/ref/api-data.texi | 17 | ||||
-rw-r--r-- | doc/ref/api-evaluation.texi | 9 | ||||
-rw-r--r-- | doc/ref/api-io.texi | 29 | ||||
-rw-r--r-- | doc/ref/r6rs.texi | 7 | ||||
-rw-r--r-- | doc/ref/scheme-scripts.texi | 5 |
6 files changed, 74 insertions, 11 deletions
diff --git a/doc/ref/api-control.texi b/doc/ref/api-control.texi index 1f33c43b5..1dde8ea9d 100644 --- a/doc/ref/api-control.texi +++ b/doc/ref/api-control.texi @@ -266,13 +266,12 @@ Concept of Closure}). @deffn syntax while cond body @dots{} Run a loop executing the @var{body} forms while @var{cond} is true. @var{cond} is tested at the start of each iteration, so if it's -@code{#f} the first time then @var{body} is not executed at all. The -return value is unspecified. +@code{#f} the first time then @var{body} is not executed at all. Within @code{while}, two extra bindings are provided, they can be used from both @var{cond} and @var{body}. -@deffn {Scheme Procedure} break +@deffn {Scheme Procedure} break break-arg... Break out of the @code{while} form. @end deffn @@ -281,6 +280,19 @@ Abandon the current iteration, go back to the start and test @var{cond} again, etc. @end deffn +If the loop terminates normally, by the @var{cond} evaluating to +@code{#f}, then the @code{while} expression as a whole evaluates to +@code{#f}. If it terminates by a call to @code{break} with some number +of arguments, those arguments are returned from the @code{while} +expression, as multiple values. Otherwise if it terminates by a call to +@code{break} with no arguments, then return value is @code{#t}. + +@example +(while #f (error "not reached")) @result{} #f +(while #t (break)) @result{} #t +(while #f (break 1 2 3)) @result{} 1 2 3 +@end example + Each @code{while} form gets its own @code{break} and @code{continue} procedures, operating on that @code{while}. This means when loops are nested the outer @code{break} can be used to escape all the way out. diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi index 760039a32..9825bef86 100644 --- a/doc/ref/api-data.texi +++ b/doc/ref/api-data.texi @@ -4280,20 +4280,20 @@ strings to Scheme. @deftypefn {C Function} char *scm_to_stringn (SCM str, size_t *lenp, const char *encoding, scm_t_string_failed_conversion_handler handler) This function returns a newly allocated C string from the Guile string -@var{str}. The length of the string will be returned in @var{lenp}. -The character encoding of the C string is passed as the ASCII, +@var{str}. The length of the returned string in bytes will be returned in +@var{lenp}. The character encoding of the C string is passed as the ASCII, null-terminated C string @var{encoding}. The @var{handler} parameter gives a strategy for dealing with characters that cannot be converted into @var{encoding}. -If @var{lenp} is NULL, this function will return a null-terminated C +If @var{lenp} is @code{NULL}, this function will return a null-terminated C string. It will throw an error if the string contains a null character. @end deftypefn @deftypefn {C Function} SCM scm_from_stringn (const char *str, size_t len, const char *encoding, scm_t_string_failed_conversion_handler handler) This function returns a scheme string from the C string @var{str}. The -length of the C string is input as @var{len}. The encoding of the C +length in bytes of the C string is input as @var{len}. The encoding of the C string is passed as the ASCII, null-terminated C string @code{encoding}. The @var{handler} parameters suggests a strategy for dealing with unconvertable characters. @@ -4325,11 +4325,14 @@ in @var{str} in the case of @code{scm_from_utf32_stringn}. @deftypefnx {C function} scm_t_wchar *scm_to_utf32_stringn (SCM str, size_t *lenp) Return a newly allocated, ISO-8859-1-, UTF-8-, or UTF-32-encoded C string from Scheme string @var{str}. An error is thrown when @var{str} -string cannot be converted to the specified encoding. If @var{lenp} is +cannot be converted to the specified encoding. If @var{lenp} is @code{NULL}, the returned C string will be null terminated, and an error will be thrown if the C string would otherwise contain null -characters. If @var{lenp} is not NULL, the length of the string is -returned in @var{lenp}, and the string is not null terminated. +characters. If @var{lenp} is not @code{NULL}, the string is not null terminated, +and the length of the returned string is returned in @var{lenp}. The length +returned is the number of bytes for @code{scm_to_latin1_stringn} and +@code{scm_to_utf8_stringn}; it is the number of elements (code points) +for @code{scm_to_utf32_stringn}. @end deftypefn @node String Internals diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi index 682e84498..9430c744d 100644 --- a/doc/ref/api-evaluation.texi +++ b/doc/ref/api-evaluation.texi @@ -586,6 +586,15 @@ computation are fulfilled by macros and closures. Of course one good counterexample is the REPL itself, or any code that reads expressions from a port.) +Automatic compilation generally works transparently, without any need +for user intervention. However Guile does not yet do proper dependency +tracking, so that if file @file{@var{a}.scm} uses macros from +@file{@var{b}.scm}, and @var{@var{b}.scm} changes, @code{@var{a}.scm} +would not be automatically recompiled. To forcibly invalidate the +auto-compilation cache, pass the @code{--fresh-auto-compile} option to +Guile, or set the @code{GUILE_AUTO_COMPILE} environment variable to +@code{fresh} (instead of to @code{0} or @code{1}). + For more information on the compiler itself, see @ref{Compiling to the Virtual Machine}. For information on the virtual machine, see @ref{A Virtual Machine for Guile}. diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi index 02c184986..e7e91edae 100644 --- a/doc/ref/api-io.texi +++ b/doc/ref/api-io.texi @@ -1164,6 +1164,10 @@ presented above (@pxref{Input and Output}). * R6RS Binary Output:: Binary output. @end menu +A subset of the @code{(rnrs io ports)} module is provided by the +@code{(ice-9 binary-ports)} module. It contains binary input/output +procedures and does not rely on R6RS support. + @node R6RS End-of-File @subsubsection The End-of-File Object @@ -1229,6 +1233,31 @@ Call @var{proc}, passing it @var{port} and closing @var{port} upon exit of @var{proc}. Return the return values of @var{proc}. @end deffn +@deffn {Scheme Procedure} binary-port? port +Return @code{#t} if @var{port} is a @dfn{binary port}, suitable for +binary data input/output. + +Note that internally Guile does not differentiate between binary and +textual ports, unlike the R6RS. Thus, this procedure returns true when +@var{port} does not have an associated encoding---i.e., when +@code{(port-encoding @var{port})} is @code{#f} (@pxref{Ports, +port-encoding}). This is the case for ports returned by R6RS procedures +such as @code{open-bytevector-input-port} and +@code{make-custom-binary-output-port}. + +However, Guile currently does not prevent use of textual I/O procedures +such as @code{display} or @code{read-char} with binary ports. Doing so +``upgrades'' the port from binary to textual, under the ISO-8859-1 +encoding. Likewise, Guile does not prevent use of +@code{set-port-encoding!} on a binary port, which also turns it into a +``textual'' port. +@end deffn + +@deffn {Scheme Procedure} textual-port? port +Always return @var{#t}, as all ports can be used for textual I/O in +Guile. +@end deffn + @node R6RS Binary Input @subsubsection Binary Input diff --git a/doc/ref/r6rs.texi b/doc/ref/r6rs.texi index bc569ed69..2fe8d7b76 100644 --- a/doc/ref/r6rs.texi +++ b/doc/ref/r6rs.texi @@ -93,8 +93,13 @@ implement in a backward-compatible way. Suggestions and/or patches would be appreciated. @item -The @code{(rnrs io ports)} module is mostly unimplemented. Work is +The @code{(rnrs io ports)} module is incomplete. Work is ongoing to fix this. + +@item +Guile does not prevent use of textual I/O procedures on binary ports. +More generally, it does not make a sharp distinction between binary and +textual ports (@pxref{R6RS Port Manipulation, binary-port?}). @end itemize @node R6RS Standard Libraries diff --git a/doc/ref/scheme-scripts.texi b/doc/ref/scheme-scripts.texi index 0ad1becf3..c7d22a4e9 100644 --- a/doc/ref/scheme-scripts.texi +++ b/doc/ref/scheme-scripts.texi @@ -227,6 +227,11 @@ development. @item --auto-compile Compile source files automatically (default behavior). +@vnew{2.0.1} + +@item --fresh-auto-compile +Treat the auto-compilation cache as invalid, forcing recompilation. + @vnew{2.0} @item --no-auto-compile |