Re: doco ports verbiage

[Kevin Ryde]

Marius Vollmer <address@hidden> writes:
>
> Or we could stay in Scheme and say it is equivalent to
>
>     (open-file FILENAME "w")

Yes, that sounds like the way to go.  New effort below, referring to
open-input-file and open-output-file, which strike me as natural
counterparts to these `with' functions.

> and make sure that open-file is documented properly.

I guess it already says the contents are removed (truncated) for "w".




 - Scheme Procedure: call-with-input-file filename proc
 - Scheme Procedure: call-with-output-file filename proc
     Open FILENAME for input or output, and call `(PROC port)' with the
     resulting port.  Return the value returned by PROC.  FILENAME is
     opened as per `open-input-file' or `open-output-file'
     respectively, and an error is signalled if it cannot be opened.

     When PROC returns, the port is closed.  If PROC does not return
     (eg. if it throws an error), then the port might not be closed
     automatically, though it will be garbage collected in the usual
     way if not otherwise referenced.

 - Scheme Procedure: with-input-from-file filename thunk
 - Scheme Procedure: with-output-to-file filename thunk
 - Scheme Procedure: with-error-to-file filename thunk
     Open FILENAME and call `(THUNK)' with the new port setup as
     respectively the `current-input-port', `current-output-port', or
     `current-error-port'.  Return the value returned by THUNK.
     FILENAME is opened as per `open-input-file' or `open-output-file'
     respectively, and an error is signalled if it cannot be opened.

     When THUNK returns, the port is closed and the previous setting of
     the respective current port is restored.

     The current port setting is managed with `dynamic-wind', so the
     previous value is restored no matter how THUNK exits (eg. an
     exception), and if THUNK is re-entered (via a captured
     continuation) then it's set again to the FILENAME port.

     The port is closed when THUNK returns normally, but not when
     exited via an exception or new continuation.  This ensures it's
     still ready for use if THUNK is re-entered by a captured
     continuation.  Of course the port is always garbage collected and
     closed in the usual way when no longer referenced anywhere.