From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Kevin Ryde Newsgroups: gmane.lisp.guile.devel Subject: doco ports verbiage Date: Thu, 12 Jun 2003 10:56:29 +1000 Sender: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Message-ID: <877k7sm7uq.fsf@zip.com.au> NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" X-Trace: main.gmane.org 1055379426 1956 80.91.224.249 (12 Jun 2003 00:57:06 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Thu, 12 Jun 2003 00:57:06 +0000 (UTC) Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Thu Jun 12 02:57:04 2003 Return-path: Original-Received: from monty-python.gnu.org ([199.232.76.173]) by main.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 19QGOl-0000VM-00 for ; Thu, 12 Jun 2003 02:57:03 +0200 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.20) id 19QGPc-0003Qp-Rk for guile-devel@m.gmane.org; Wed, 11 Jun 2003 20:57:56 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.20) id 19QGPE-0003Gu-Ue for guile-devel@gnu.org; Wed, 11 Jun 2003 20:57:32 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.20) id 19QGOY-0002JR-VT for guile-devel@gnu.org; Wed, 11 Jun 2003 20:57:01 -0400 Original-Received: from snoopy.pacific.net.au ([61.8.0.36]) by monty-python.gnu.org with esmtp (Exim 4.20) id 19QGOR-0001qG-Gi for guile-devel@gnu.org; Wed, 11 Jun 2003 20:56:43 -0400 Original-Received: from sunny.pacific.net.au (sunny.pacific.net.au [203.2.228.40]) h5C0ueYd018803 for ; Thu, 12 Jun 2003 10:56:40 +1000 Original-Received: from wisma.pacific.net.au (wisma.pacific.net.au [210.23.129.72]) by sunny.pacific.net.au with ESMTP id h5C0ueQg019297 for ; Thu, 12 Jun 2003 10:56:40 +1000 (EST) Original-Received: from localhost (ppp124.dyn228.pacific.net.au [203.143.228.124]) by wisma.pacific.net.au (8.12.9/8.12.9) with ESMTP id h5C0ubYZ011205 for ; Thu, 12 Jun 2003 10:56:38 +1000 (EST) Original-Received: from gg by localhost with local (Exim 3.35 #1 (Debian)) id 19QGOF-0000Et-00; Thu, 12 Jun 2003 10:56:31 +1000 Original-To: guile-devel@gnu.org Mail-Copies-To: never User-Agent: Gnus/5.090019 (Oort Gnus v0.19) Emacs/21.2 (gnu/linux) X-BeenThere: guile-devel@gnu.org X-Mailman-Version: 2.1b5 Precedence: list List-Id: Developers list for Guile, the GNU extensibility library List-Help: List-Post: List-Subscribe: , List-Archive: List-Unsubscribe: , Errors-To: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Xref: main.gmane.org gmane.lisp.guile.devel:2524 X-Report-Spam: http://spam.gmane.org/gmane.lisp.guile.devel:2524 --=-=-= 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. --=-=-= Content-Disposition: attachment; filename=scheme-io.texi.ports.diff --- 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 --=-=-= Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit _______________________________________________ Guile-devel mailing list Guile-devel@gnu.org http://mail.gnu.org/mailman/listinfo/guile-devel --=-=-=--