mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-05-23 21:10:29 +02:00
Code Activity

(File Ports): Describe call-with-input-file and

Browse source 
call-with-output-file together.  Describe with-input-from-file,
with-output-to-file and with-error-to-file together, and add that they
use dynamic-wind on the current port setting and keep the port open in
support of captured continuations.
(Closing): Describe close-input-port and close-output-port together,
tweak the wording slightly.
This commit is contained in:
Kevin Ryde 2003-06-19 00:38:49 +00:00
parent ea8ac9ace0
commit 2288712b6c
1 changed files with 40 additions and 69 deletions
Download patch file Download diff file Expand all files Collapse all files

109
doc/ref/scheme-io.texi
View file

@ -301,23 +301,15 @@ File Descriptors, close}, for a procedure which can close file
descriptors. descriptors.
@end deffn @end deffn
@rnindex close-input-port
@deffn {Scheme Procedure} close-input-port port @deffn {Scheme Procedure} close-input-port port
@deffnx {Scheme Procedure} close-output-port port
@deffnx {C Function} scm_close_input_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) @deffnx {C Function} scm_close_output_port (port)
Close the specified output port object. The routine has no effect if @rnindex close-input-port
the file has already been closed. An exception may be raised if an @rnindex close-output-port
error occurs. The value returned is unspecified. 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 See also @ref{Ports and File Descriptors, close}, for a procedure
which can close file descriptors. which can close file descriptors.
@ -709,68 +701,47 @@ Open @var{filename} for output. Equivalent to
@end smalllisp @end smalllisp
@end deffn @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 @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 @rnindex call-with-output-file
@deffn {Scheme Procedure} call-with-output-file file proc Open @var{filename} for input or output, and call @code{(@var{proc}
@var{proc} should be a procedure of one argument, and @var{file} should port)} with the resulting port. Return the value returned by
be a string naming a file. The behaviour is unspecified if the file @var{proc}. @var{filename} is opened as per @code{open-input-file} or
already exists. These procedures call @var{proc} with one argument: the @code{open-output-file} respectively, and an error is signalled if it
port obtained by opening the named file for input or output. If the cannot be opened.
file cannot be opened, an error is signalled. If the procedure returns,
then the port is closed automatically and the value yielded by the When @var{proc} returns, the port is closed. If @var{proc} does not
procedure is returned. If the procedure does not return, then the port return (eg.@: if it throws an error), then the port might not be
will not be closed automatically unless it is possible to prove that the closed automatically, though it will be garbage collected in the usual
port will never again be used for a read or write operation. way if not otherwise referenced.
@end deffn @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 @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 @rnindex with-output-to-file
@deffn {Scheme Procedure} with-output-to-file file thunk Open @var{filename} and call @code{(@var{thunk})} with the new port
@var{thunk} must be a procedure of no arguments, and @var{file} must be setup as respectively the @code{current-input-port},
a string naming a file. The effect is unspecified if the file already @code{current-output-port}, or @code{current-error-port}. Return the
exists. The file is opened for output, an output port connected to it value returned by @var{thunk}. @var{filename} is opened as per
is made the default value returned by @code{current-output-port}, and @code{open-input-file} or @code{open-output-file} respectively, and an
the @var{thunk} is called with no arguments. When the @var{thunk} error is signalled if it cannot be opened.
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 When @var{thunk} returns, the port is closed and the previous setting
@var{thunk} must be a procedure of no arguments, and @var{file} must be of the respective current port is restored.
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 The current port setting is managed with @code{dynamic-wind}, so the
is made the default value returned by @code{current-error-port}, and the previous value is restored no matter how @var{thunk} exits (eg.@: an
@var{thunk} is called with no arguments. When the @var{thunk} returns, exception), and if @var{thunk} is re-entered (via a captured
the port is closed and the previous default is restored. Returns the continuation) then it's set again to the @var{FILENAME} port.
value yielded by @var{thunk}. If an escape procedure is used to escape
from the continuation of these procedures, their behavior is The port is closed when @var{thunk} returns normally, but not when
implementation dependent. exited via an exception or new continuation. This ensures it's still
ready for use if @var{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.
@end deffn @end deffn
@deffn {Scheme Procedure} port-mode port @deffn {Scheme Procedure} port-mode port