[r6rs-discuss] Issues with section 8.2. Port I/O, a.k.a. (rnrs io ports (6))

From: Abdulaziz Ghuloum <aghuloum>
Date: Sat, 25 Aug 2007 15:27:18 -0400

Greetings,

This is a very long and late message that I should've broken
down and sent a few months earlier. The issues I'm raising
range from simple typos to stylistic issues to slightly more
serious problems (mostly misunderstanding from my part). I
don't know about how people feel about changing anything in
the document at this stage in the game.

Thanks,

Aziz,,,


************************************************************


Section 8.2.2. File options:

It is hard for me to understand the listed file options
(no-create, no-fail, and no-truncate) and how the options
interact. Some of the sentences have double and tripple
negations like ``no-fail: If the file [...], the exception
&foo is not raised even if no-create is not included''.

Is it possible that the description (and possibly the option
names) be worded in a more positive tone (e.g. making the
options additive rather than subtractive)?

I tried to summarize my understanding of the options in the
following table of possible outcomes.

(file-options)
  If file exists: raise &file-already-exists
  If does not exist: create new file
(file-options no-create)
  If file exists: truncate
  If does not exist: raise &file-does-not-exist
(file-options no-fail)
  If file exists: truncate
  If does not exist: create new file
(file-options no-truncate)
  If file exists: raise &file-already-exists
  If does not exist: create new file
(file-options no-create no-fail)
  If file exists: truncate
  If does not exist: ???
(file-options no-fail no-truncate)
  If file exists: set port position to 0 (overwriting)
  If does not exist: create new file
(file-options no-create no-truncate)
  If file exists: set port position to 0 (overwriting)
  If does not exist: raise &file-does-not-exist
(file-options no-create no-fail no-truncate)
  If file exists: set port position to 0 (overwriting)
  If does not exist: ???

Would someone please verify the table. Also, what happens
when both no-create and no-fail are listed?



8.2.3. Buffer modes.

The three listed buffer modes are none, line, and block. I
understand two modes: buffered IO (maintain a buffer and
flush/load/ when it's full/empty) and unbuffered IO
(write/read the bytes/chars one at a time as they come). I
don't understand what line buffering means. First, the option
does not make sense for binary ports. Second, what
constitutes a line depends on what character(s) constitute an
end-of-line marker, but this is unknown unless the bytes of a
file are actually decoded. For input-ports, the bytes have to
be read and decoded one at a time until an end-of-line marker
is found. But this is more or less what unbuffered IO is.
For output-ports, and in the case of multibyte eol marker, the
situation is just as bad since the port has to maintain additional
state (e.g. have I seen a <cr> and this is a <lf> or not).

So, a question for implementors: How would you implement line
buffering?

A related question: what's the rationale for including the
"buffer-mode?" predicate? I don't see any other predicate in
this category: there are no file-option?, codec?, eol-style?,
error-handling-mode?, or transcoder? predicates.



8.2.4. Transcoders.

Codecs:
What's the endianness of the codec returned by (utf-16-codec)?
Was the UTF-32 codec dropped unintentionally?

Eol-style:
Which procedures are affected by the eol-style of a port's
transcoder? Does it only affect (get-line <textual-input-port>)
or does it perform translation on other operations?

Does bytevector->string and string->bytevector use the
eol-style of the given transcoder argument? If not, wouldn't
it be more appropriate to pass a codec and an optional
error-handling-mode instead?



8.2.6. Input and output ports.

Typo: port-has-set-port-position? is missing a bang. Should
be port-has-set-port-position!?



8.2.7. Input ports

Why does open-file-input-port take a file-option argument?
 From 8.2.2. File options: "These options have no effect when a
file is opened only for input."
In 8.2.7, "The file-options argument, which may determine the
various aspects of the returned port (see section 8.2.2),
defaults to the value of (file-options)".

Maybe-transcoders:

The procedures open-file-input-port,
open-bytevector-input-port, open-file-output-port,
open-bytevector-output-port, call-with-bytevector-output-port
(and possibly others) all take an optional maybe-transcoder
as the last argument. For example,

(open-bytevector-input-port bytevector)
(open-bytevector-input-port maybe-transcoder)
where maybe-transcoder is #f or a transcoder.

Why are there two ways of specifying the optional argument
(dropping it, and adding #f). Is it possible that all
maybe-transcoder arguments to such procedures be named simply
"transcoder" and the #f option be removed?



8.2.9. Textual input.

This section mentions the get-line procedure. Is there a
similar put-line procedure that I'm missing somewhere?



8.2.13. Input/output ports.

The description of input/output ports does not explain how the
read and write operations interact. I can come up with at
least two possibilities:

1. Shared source/sink:
   The input/output port has a single buffer that's both the
   source of the input direction and the sink of the output
   direction. Bytes/chars written to the input direction of
   the port can be subsequently read from the output direction
   of the same port.

2. Disjoint source/sink:
   In essense, these are two ports in one: an output file is
   opened first, obtaining an output port, and the same file is
   opened for input, obtaining an input port and the two are
   squashed together to make an input/output port. The
   programmer must ensure that bytes written to the port are
   flushed before they are read back from the same port.

There might be other possibilities but the document, as it
stands, does not say much about how input/output ports work.
Received on Sat Aug 25 2007 - 15:27:18 UTC