summaryrefslogtreecommitdiff
path: root/doc/ref/api-io.texi
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2011-02-02 15:52:56 +0100
committerLudovic Courtès <ludo@gnu.org>2011-02-02 18:06:28 +0100
commitc62da8f891569aa717f4f8557c7e87650ec92fb1 (patch)
treeb176c4ccfc858a9e55915da0131901c3fa3e0907 /doc/ref/api-io.texi
parentd6cf96974ea21b2f0deb1908baefb3dd2b704331 (diff)
downloadguile-c62da8f891569aa717f4f8557c7e87650ec92fb1.tar.gz
Have `read-char' & co. throw to `decoding-error'.
* libguile/ports.c (scm_read_char): Mention `decoding-error' in the docstring. (get_codepoint): Change to return an error code; add `codepoint' output parameter. Don't raise an error from here. (scm_getc): Raise an error with `scm_decoding_error' if `get_codepoint' returns an error. (scm_peek_char): Likewise. Update docstring. * libguile/strings.c (scm_decoding_error_key): New variable. (scm_decoding_error): New function. (scm_from_stringn): Use `scm_decoding_error' instead of `scm_encoding_error'. * libguile/strings.h (scm_decoding_error): New declaration. * test-suite/tests/ports.test ("string ports")["read-char, wrong encoding, error"]: Change to expect `decoding-error'. Make sure PORT points past the error. ["read-char, wrong encoding, escape"]: Likewise. ["peek-char, wrong encoding, error"]: New test. * test-suite/tests/r6rs-ports.test ("7.2.11 Binary Output")["put-bytevector with wrong-encoding string port"]: Change to expect `decoding-error'. ("8.2.6 Input and output ports")["transcoded-port [error handling mode = raise]"]: Likewise. * test-suite/tests/rdelim.test ("read-line")["decoding error", "decoding error, substitute"]: New tests. * doc/ref/api-io.texi (Reading): Update documentation of `read-char' and `peek-char'. (Line/Delimited): Update documentation of `read-line'.
Diffstat (limited to 'doc/ref/api-io.texi')
-rw-r--r--doc/ref/api-io.texi16
1 files changed, 14 insertions, 2 deletions
diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi
index 47dc8fc3d..e02daeb93 100644
--- a/doc/ref/api-io.texi
+++ b/doc/ref/api-io.texi
@@ -1,7 +1,7 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2009, 2010
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2009,
+@c 2010, 2011 Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@node Input and Output
@@ -210,6 +210,10 @@ interactive port that has no ready characters.
Return the next character available from @var{port}, updating
@var{port} to point to the following character. If no more
characters are available, the end-of-file object is returned.
+
+When @var{port}'s data cannot be decoded according to its
+character encoding, a @code{decoding-error} is raised and
+@var{port} points past the erroneous byte sequence.
@end deffn
@deftypefn {C Function} size_t scm_c_read (SCM port, void *buffer, size_t size)
@@ -238,6 +242,11 @@ return the value returned by the preceding call to
@code{peek-char}. In particular, a call to @code{peek-char} on
an interactive port will hang waiting for input whenever a call
to @code{read-char} would have hung.
+
+As for @code{read-char}, a @code{decoding-error} may be raised
+if such a situation occurs. However, unlike with @code{read-char},
+@var{port} still points at the beginning of the erroneous byte
+sequence when the error is raised.
@end deffn
@deffn {Scheme Procedure} unread-char cobj [port]
@@ -513,6 +522,9 @@ Push the terminating delimiter (if any) back on to the port.
Return a pair containing the string read from the port and the
terminating delimiter or end-of-file object.
@end table
+
+Like @code{read-char}, this procedure can throw to @code{decoding-error}
+(@pxref{Reading, @code{read-char}}).
@end deffn
@c begin (scm-doc-string "rdelim.scm" "read-line!")