Subject: bug#18520: string ports should not have an encoding

From: [email-masked] (Ludovic Courtès)
Date: Tue, 23 Sep 2014 21:33:29 +0200

David Kastrup <[email-masked]> skribis:

> I stated quite definitely that I am perfectly capable of dealing with
> the mess GUILE made of string ports.

Good to know, this was not my understanding until now.

The intent of the change in 2.2 is to hide the very fact that string
ports “have an encoding.”  So from that viewpoint, that bug is closed.

If the bug is about ‘ftell’, that’s a different story.  I would tend to
suggest that ‘ftell’ and ‘seek’ for string ports operate on an abstract
notion of position within the string port data.

This is in fact the path that the R6RS takes:

  For a binary port, the port-position procedure returns the index of
  the position at which the next byte would be read from or written to
  the port as an exact non-negative integer object.  For a textual port,
  port-position returns a value of some implementation-dependent type
  representing the port's position; this value may be useful only as the
  pos argument to set-port-position!, if the latter is supported on the
  port (see below).

Thus, I would suggest a clarification along these lines:

diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi
index 02d92a2..8331378 100644
--- a/doc/ref/api-io.texi
+++ b/doc/ref/api-io.texi
@@ -443,8 +443,12 @@ open.
 @deffn {Scheme Procedure} seek fd_port offset whence
 @deffnx {C Function} scm_seek (fd_port, offset, whence)
 Sets the current position of @var{fd_port} to the integer
-@var{offset}, which is interpreted according to the value of
-@var{whence}.
+@var{offset}.  For a file port, @var{offset} is expressed
+as a number of bytes; for other types of ports, such as string
+ports, @var{offset} is an abstract representation of the
+position within the port's data, not necessarily expressed
+as a number of bytes.  @var{offset} is interpreted according to
+the value of @var{whence}.
 
 One of the following variables should be supplied for
 @var{whence}:
@@ -460,7 +464,7 @@ Seek from the end of the file.
 If @var{fd_port} is a file descriptor, the underlying system
 call is @code{lseek}.  @var{port} may be a string port.
 
-The value returned is the new position in the file.  This means
+The value returned is the new position in @var{fd_port}.  This means
 that the current position of a port can be obtained using:
 @lisp
 (seek port 0 SEEK_CUR)

Thoughts?

Thanks,
Ludo’.