summaryrefslogtreecommitdiff
path: root/doc/ref
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ref')
-rw-r--r--doc/ref/api-control.texi18
-rw-r--r--doc/ref/api-data.texi17
-rw-r--r--doc/ref/api-evaluation.texi9
-rw-r--r--doc/ref/api-io.texi29
-rw-r--r--doc/ref/r6rs.texi7
-rw-r--r--doc/ref/scheme-scripts.texi5
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