doco ports verbiage

[Kevin Ryde <user42@zip.com.au>]

[-- Attachment #1: Type: text/plain, Size: 2509 bytes --]

This is in the interests of reducing duplication.  For with- and
call-with- I found it a bit hard to see quite what was going on with
five rather similar chunks of text.

	* scheme-io.texi (File Ports): Describe call-with-input-file and
	call-with-output-file together.  Describe with-input-from-file,
	with-output-to-file and with-error-to-file together.
	(Closing): Describe close-input-port and close-output-port together,
	tweak the wording slightly.

The words are slightly rearranged in support of this, but what's
specified is not changed.



 - 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.

     For input, FILENAME must exist.  For output, if FILENAME already
     exists the behaviour is unspecified.  In both cases if FILENAME
     cannot be opened an error is signalled.

     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 port setup as
     respectively the `current-input-port', `current-output-port', or
     `current-error-port'.  Return the value returned by THUNK.

     For input, FILENAME must exist.  For output and error output, if
     FILENAME already exists the behaviour is unspecified.  In all
     cases if FILENAME cannot be opened, an error is signalled.

     When THUNK returns, the port is closed and the previous setting of
     the respective current port is restored.  If THUNK does not return
     (eg. if it throws an error), then what happens to the ports is
     unspecified.




 - Scheme Procedure: close-input-port port
 - Scheme Procedure: close-output-port port
 - C Function: scm_close_input_port (port)
 - C Function: scm_close_output_port (port)
     Close the specified input or output PORT.  An exception may be
     raised if an error occurs while closing.  If PORT is already
     closed, nothing is done.  The return value is unspecified.

     See also *Note close: Ports and File Descriptors, for a procedure
     which can close file descriptors.




[-- Attachment #2: scheme-io.texi.ports.diff --]
[-- Type: text/plain, Size: 6486 bytes --]

--- scheme-io.texi.~1.12.~	2003-06-01 10:18:51.000000000 +1000
+++ scheme-io.texi	2003-06-12 10:45:48.000000000 +1000
@@ -301,23 +301,15 @@
 descriptors.
 @end deffn
 
-@rnindex close-input-port
 @deffn {Scheme Procedure} close-input-port port
+@deffnx {Scheme Procedure} close-output-port port
 @deffnx {C Function} scm_close_input_port (port)
-Close the specified input port object.  The routine has no effect if
-the file has already been closed.  An exception may be raised if an
-error occurs.  The value returned is unspecified.
-
-See also @ref{Ports and File Descriptors, close}, for a procedure
-which can close file descriptors.
-@end deffn
-
-@rnindex close-output-port
-@deffn {Scheme Procedure} close-output-port port
 @deffnx {C Function} scm_close_output_port (port)
-Close the specified output port object.  The routine has no effect if
-the file has already been closed.  An exception may be raised if an
-error occurs.  The value returned is unspecified.
+@rnindex close-input-port
+@rnindex close-output-port
+Close the specified input or output @var{port}.  An exception may be
+raised if an error occurs while closing.  If @var{port} is already
+closed, nothing is done.  The return value is unspecified.
 
 See also @ref{Ports and File Descriptors, close}, for a procedure
 which can close file descriptors.
@@ -709,68 +701,42 @@
 @end smalllisp
 @end deffn
 
+@deffn {Scheme Procedure} call-with-input-file filename proc
+@deffnx {Scheme Procedure} call-with-output-file filename proc
 @rnindex call-with-input-file
-@deffn {Scheme Procedure} call-with-input-file file proc
-@var{proc} should be a procedure of one argument, and @var{file} should
-be a string naming a file.  The file must already exist. These
-procedures call @var{proc} with one argument: the port obtained by
-opening the named file for input or output.  If the file cannot be
-opened, an error is signalled.  If the procedure returns, then the port
-is closed automatically and the value yielded by the procedure is
-returned.  If the procedure does not return, then the port will not be
-closed automatically unless it is possible to prove that the port will
-never again be used for a read or write operation.
-@end deffn
-
 @rnindex call-with-output-file
-@deffn {Scheme Procedure} call-with-output-file file proc
-@var{proc} should be a procedure of one argument, and @var{file} should
-be a string naming a file.  The behaviour is unspecified if the file
-already exists. These procedures call @var{proc} with one argument: the
-port obtained by opening the named file for input or output.  If the
-file cannot be opened, an error is signalled.  If the procedure returns,
-then the port is closed automatically and the value yielded by the
-procedure is returned.  If the procedure does not return, then the port
-will not be closed automatically unless it is possible to prove that the
-port will never again be used for a read or write operation.
-@end deffn
-
+Open @var{filename} for input or output, and call @code{(@var{proc}
+port)} with the resulting port.  Return the value returned by
+@var{proc}.
+
+For input, @var{filename} must exist.  For output, if @var{filename}
+already exists the behaviour is unspecified.  In both cases if
+@var{filename} cannot be opened an error is signalled.
+
+When @var{proc} returns, the port is closed.  If @var{proc} does not
+return (eg.@: if it throws an error), then the port may not be closed
+automatically, though it will be garbage collected in the usual way if
+not otherwise referenced.
+@end deffn
+
+@deffn {Scheme Procedure} with-input-from-file filename thunk
+@deffnx {Scheme Procedure} with-output-to-file filename thunk
+@deffnx {Scheme Procedure} with-error-to-file filename thunk
 @rnindex with-input-from-file
-@deffn {Scheme Procedure} with-input-from-file file thunk
-@var{thunk} must be a procedure of no arguments, and @var{file} must be
-a string naming a file.  The file must already exist. The file is opened
-for input, an input port connected to it is made the default value
-returned by @code{current-input-port}, and the @var{thunk} is called
-with no arguments.  When the @var{thunk} returns, the port is closed and
-the previous default is restored.  Returns the value yielded by
-@var{thunk}.  If an escape procedure is used to escape from the
-continuation of these procedures, their behavior is implementation
-dependent.
-@end deffn
-
 @rnindex with-output-to-file
-@deffn {Scheme Procedure} with-output-to-file file thunk
-@var{thunk} must be a procedure of no arguments, and @var{file} must be
-a string naming a file.  The effect is unspecified if the file already
-exists.  The file is opened for output, an output port connected to it
-is made the default value returned by @code{current-output-port}, and
-the @var{thunk} is called with no arguments.  When the @var{thunk}
-returns, the port is closed and the previous default is restored.
-Returns the value yielded by @var{thunk}.  If an escape procedure is
-used to escape from the continuation of these procedures, their behavior
-is implementation dependent.
-@end deffn
-
-@deffn {Scheme Procedure} with-error-to-file file thunk
-@var{thunk} must be a procedure of no arguments, and @var{file} must be
-a string naming a file.  The effect is unspecified if the file already
-exists.  The file is opened for output, an output port connected to it
-is made the default value returned by @code{current-error-port}, and the
-@var{thunk} is called with no arguments.  When the @var{thunk} returns,
-the port is closed and the previous default is restored.  Returns the
-value yielded by @var{thunk}.  If an escape procedure is used to escape
-from the continuation of these procedures, their behavior is
-implementation dependent.
+Open @var{filename} and call @code{(@var{thunk})} with the port setup
+as respectively the @code{current-input-port},
+@code{current-output-port}, or @code{current-error-port}.  Return the
+value returned by @var{thunk}.
+
+For input, @var{filename} must exist.  For output and error output, if
+@var{filename} already exists the behaviour is unspecified.  In all
+cases if @var{filename} cannot be opened, an error is signalled.
+
+When @var{thunk} returns, the port is closed and the previous setting
+of the respective current port is restored.  If @var{thunk} does not
+return (eg.@: if it throws an error), then what happens to the ports
+is unspecified.
 @end deffn
 
 @deffn {Scheme Procedure} port-mode port

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel