dmbcs/guile
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

* scheme-io.texi (Block Reading and Writing): added

Browse source 
write-string/partial, updated read-string!/partial.
This commit is contained in:
Gary Houston 2001-06-04 21:51:01 +00:00
commit 1fb9789efd
1 changed files with 0 additions and 777 deletions
Download patch file Download diff file Expand all files Collapse all files

777
doc/scheme-io.texi
View file

@ -1,777 +0,0 @@
@page
@node Input and Output
@chapter Input and Output
@menu
* Ports:: The idea of the port abstraction.
* Reading:: Procedures for reading from a port.
* Writing:: Procedures for writing to a port.
* Closing:: Procedures to close a port.
* Random Access:: Moving around a random access port.
* Line/Delimited:: Read and write lines or delimited text.
* Block Reading and Writing:: Reading and writing blocks of text.
* Default Ports:: Defaults for input, output and errors.
* Port Types:: Types of port and how to make them.
@end menu
@node Ports
@section Ports
[Concept of the port abstraction.]
Sequential input/output in Scheme is represented by operations on a
@dfn{port}. Characters can be read from an input port and
written to an output port. This chapter explains the operations
that Guile provides for working with ports.
The formal definition of a port is very generic: an input port is
simply ``an object which can deliver characters on command,'' and
an output port is ``an object which can accept characters.''
Because this definition is so loose, it is easy to write functions
that simulate ports in software. @dfn{Soft ports} and @dfn{string
ports} are two interesting and powerful examples of this technique.
@rnindex input-port?
@deffn primitive input-port? x
Return @code{#t} if @var{x} is an input port, otherwise return
@code{#f}. Any object satisfying this predicate also satisfies
@code{port?}.
@end deffn
@rnindex output-port?
@deffn primitive output-port? x
Return @code{#t} if @var{x} is an output port, otherwise return
@code{#f}. Any object satisfying this predicate also satisfies
@code{port?}.
@end deffn
@deffn primitive port? x
Return a boolean indicating whether @var{x} is a port.
Equivalent to @code{(or (input-port? @var{x}) (output-port?
@var{x}))}.
@end deffn
@node Reading
@section Reading
[Generic procedures for reading from ports.]
@rnindex eof-object?
@deffn primitive eof-object? x
Return @code{#t} if @var{x} is an end-of-file object; otherwise
return @code{#f}.
@end deffn
@rnindex char-ready?
@deffn primitive char-ready? [port]
Return @code{#t} if a character is ready on input @var{port}
and return @code{#f} otherwise. If @code{char-ready?} returns
@code{#t} then the next @code{read-char} operation on
@var{port} is guaranteed not to hang. If @var{port} is a file
port at end of file then @code{char-ready?} returns @code{#t}.
@footnote{@code{char-ready?} exists to make it possible for a
program to accept characters from interactive ports without
getting stuck waiting for input. Any input editors associated
with such ports must make sure that characters whose existence
has been asserted by @code{char-ready?} cannot be rubbed out.
If @code{char-ready?} were to return @code{#f} at end of file,
a port at end of file would be indistinguishable from an
interactive port that has no ready characters.}
@end deffn
@rnindex read-char?
@deffn primitive read-char [port]
Return the next character available from @var{port}, updating
@var{port} to point to the following character. If no more
characters are available, the end-of-file object is returned.
@end deffn
@rnindex peek-char?
@deffn primitive peek-char [port]
Return the next character available from @var{port},
@emph{without} updating @var{port} to point to the following
character. If no more characters are available, the
end-of-file object is returned.@footnote{The value returned by
a call to @code{peek-char} is the same as the value that would
have been returned by a call to @code{read-char} on the same
port. The only difference is that the very next call to
@code{read-char} or @code{peek-char} on that @var{port} will
return the value returned by the preceding call to
@code{peek-char}. In particular, a call to @code{peek-char} on
an interactive port will hang waiting for input whenever a call
to @code{read-char} would have hung.}
@end deffn
@deffn primitive unread-char cobj port
Place @var{char} in @var{port} so that it will be read by the
next read operation. If called multiple times, the unread characters
will be read again in last-in first-out order. If @var{port} is
not supplied, the current input port is used.
@end deffn
@deffn primitive unread-string str port
Place the string @var{str} in @var{port} so that its characters will be
read in subsequent read operations. If called multiple times, the
unread characters will be read again in last-in first-out order. If
@var{port} is not supplied, the current-input-port is used.
@end deffn
@deffn primitive drain-input port
Drain @var{port}'s read buffers (including any pushed-back
characters) and return the content as a single string.
@end deffn
@deffn primitive port-column port
@deffnx primitive port-line port
Return the current column number or line number of @var{port},
using the current input port if none is specified. If the number is
unknown, the result is #f. Otherwise, the result is a 0-origin integer
- i.e. the first character of the first line is line 0, column 0.
(However, when you display a file position, for example in an error
message, we recommend you add 1 to get 1-origin integers. This is
because lines and column numbers traditionally start with 1, and that is
what non-programmers will find most natural.)
@end deffn
@deffn primitive set-port-column! port column
@deffnx primitive set-port-line! port line
Set the current column or line number of @var{port}, using the
current input port if none is specified.
@end deffn
@node Writing
@section Writing
[Generic procedures for writing to ports.]
@deffn primitive get-print-state port
Return the print state of the port @var{port}. If @var{port}
has no associated print state, @code{#f} is returned.
@end deffn
@rnindex newline
@deffn primitive newline [port]
Send a newline to @var{port}.
@end deffn
@deffn primitive port-with-print-state port pstate
Create a new port which behaves like @var{port}, but with an
included print state @var{pstate}.
@end deffn
@deffn primitive print-options-interface [setting]
Option interface for the print options. Instead of using
this procedure directly, use the procedures
@code{print-enable}, @code{print-disable}, @code{print-set!}
and @code{print-options}.
@end deffn
@deffn primitive simple-format destination message . args
Write @var{message} to @var{destination}, defaulting to
the current output port.
@var{message} can contain @code{~A} (was @code{%s}) and
@code{~S} (was @code{%S}) escapes. When printed,
the escapes are replaced with corresponding members of
@var{ARGS}:
@code{~A} formats using @code{display} and @code{~S} formats
using @code{write}.
If @var{destination} is @code{#t}, then use the current output
port, if @var{destination} is @code{#f}, then return a string
containing the formatted text. Does not add a trailing newline.
@end deffn
@rnindex write-char
@deffn primitive write-char chr [port]
Send character @var{chr} to @var{port}.
@end deffn
@findex fflush
@deffn primitive force-output [port]
Flush the specified output port, or the current output port if @var{port}
is omitted. The current output buffer contents are passed to the
underlying port implementation (e.g., in the case of fports, the
data will be written to the file and the output buffer will be cleared.)
It has no effect on an unbuffered port.
The return value is unspecified.
@end deffn
@deffn primitive flush-all-ports
Equivalent to calling @code{force-output} on
all open output ports. The return value is unspecified.
@end deffn
@node Closing
@section Closing
@deffn primitive close-port port
Close the specified port object. Return @code{#t} if it
successfully closes a port or @code{#f} if it was already
closed. An exception may be raised if an error occurs, for
example when flushing buffered output. See also @ref{Ports and
File Descriptors, close}, for a procedure which can close file
descriptors.
@end deffn
@rnindex close-input-port
@deffn primitive 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 primitive 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.
See also @ref{Ports and File Descriptors, close}, for a procedure
which can close file descriptors.
@end deffn
@deffn primitive port-closed? port
Return @code{#t} if @var{port} is closed or @code{#f} if it is
open.
@end deffn
@node Random Access
@section Random Access
@deffn primitive seek fd_port offset whence
Sets the current position of @var{fd/port} to the integer
@var{offset}, which is interpreted according to the value of
@var{whence}.
One of the following variables should be supplied for
@var{whence}:
@defvar SEEK_SET
Seek from the beginning of the file.
@end defvar
@defvar SEEK_CUR
Seek from the current position.
@end defvar
@defvar SEEK_END
Seek from the end of the file.
@end defvar
If @var{fd/port} is a file descriptor, the underlying system
call is @code{lseek}. @var{port} may be a string port.
The value returned is the new position in the file. This means
that the current position of a port can be obtained using:
@lisp
(seek port 0 SEEK_CUR)
@end lisp
@end deffn
@deffn primitive ftell fd_port
Return an integer representing the current position of
@var{fd/port}, measured from the beginning. Equivalent to:
@lisp
(seek port 0 SEEK_CUR)
@end lisp
@end deffn
@findex truncate
@findex ftruncate
@deffn primitive truncate-file object [length]
Truncates the object referred to by @var{object} to at most
@var{length} bytes. @var{object} can be a string containing a
file name or an integer file descriptor or a port.
@var{length} may be omitted if @var{object} is not a file name,
in which case the truncation occurs at the current port.
position. The return value is unspecified.
@end deffn
@node Line/Delimited
@section Line Oriented and Delimited Text
The delimited-I/O module can be accessed with:
@smalllisp
(use-modules (ice-9 rdelim))
@end smalllisp
It can be used to read or write lines of text, or read text delimited by
a specified set of characters. It's similar to the @code{(scsh rdelim)}
module from guile-scsh, but does not use multiple values or character
sets and has an extra procedure @code{write-line}.
@c begin (scm-doc-string "rdelim.scm" "read-line")
@deffn procedure read-line [port] [handle-delim]
Return a line of text from @var{port} if specified, otherwise from the
value returned by @code{(current-input-port)}. Under Unix, a line of text
is terminated by the first end-of-line character or by end-of-file.
If @var{handle-delim} is specified, it should be one of the following
symbols:
@table @code
@item trim
Discard the terminating delimiter. This is the default, but it will
be impossible to tell whether the read terminated with a delimiter or
end-of-file.
@item concat
Append the terminating delimiter (if any) to the returned string.
@item peek
Push the terminating delimiter (if any) back on to the port.
@item split
Return a pair containing the string read from the port and the
terminating delimiter or end-of-file object.
@end table
@end deffn
@c begin (scm-doc-string "rdelim.scm" "read-line!")
@deffn procedure read-line! buf [port]
Read a line of text into the supplied string @var{buf} and return the
number of characters added to @var{buf}. If @var{buf} is filled, then
@code{#f} is returned.
Read from @var{port} if
specified, otherwise from the value returned by @code{(current-input-port)}.
@end deffn
@c begin (scm-doc-string "rdelim.scm" "read-delimited")
@deffn procedure read-delimited delims [port] [handle-delim]
Read text until one of the characters in the string @var{delims} is found
or end-of-file is reached. Read from @var{port} if supplied, otherwise
from the value returned by @code{(current-input-port)}.
@var{handle-delim} takes the same values as described for @code{read-line}.
@end deffn
@c begin (scm-doc-string "rdelim.scm" "read-delimited!")
@deffn procedure read-delimited! delims buf [port] [handle-delim] [start] [end]
Read text into the supplied string @var{buf} and return the number of
characters added to @var{buf} (subject to @var{handle-delim}, which takes
the same values specified for @code{read-line}. If @var{buf} is filled,
@code{#f} is returned for both the number of characters read and the
delimiter. Also terminates if one of the characters in the string
@var{delims} is found
or end-of-file is reached. Read from @var{port} if supplied, otherwise
from the value returned by @code{(current-input-port)}.
@end deffn
@deffn primitive write-line obj [port]
Display @var{obj} and a newline character to @var{port}. If
@var{port} is not specified, @code{(current-output-port)} is
used. This function is equivalent to:
@lisp
(display obj [port])
(newline [port])
@end lisp
@end deffn
Some of the abovementioned I/O functions rely on the following C
primitives. These will mainly be of interest to people hacking Guile
internals.
@deffn primitive %read-delimited! delims str gobble [port [start [end]]]
Read characters from @var{port} into @var{str} until one of the
characters in the @var{delims} string is encountered. If
@var{gobble} is true, discard the delimiter character;
otherwise, leave it in the input stream for the next read. If
@var{port} is not specified, use the value of
@code{(current-input-port)}. If @var{start} or @var{end} are
specified, store data only into the substring of @var{str}
bounded by @var{start} and @var{end} (which default to the
beginning and end of the string, respectively).
Return a pair consisting of the delimiter that terminated the
string and the number of characters read. If reading stopped
at the end of file, the delimiter returned is the
@var{eof-object}; if the string was filled without encountering
a delimiter, this value is @code{#f}.
@end deffn
@deffn primitive %read-line [port]
Read a newline-terminated line from @var{port}, allocating storage as
necessary. The newline terminator (if any) is removed from the string,
and a pair consisting of the line and its delimiter is returned. The
delimiter may be either a newline or the @var{eof-object}; if
@code{%read-line} is called at the end of file, it returns the pair
@code{(#<eof> . #<eof>)}.
@end deffn
@node Block Reading and Writing
@section Block reading and writing
The Block-string-I/O module can be accessed with:
@smalllisp
(use-modules (ice-9 rw))
@end smalllisp
It currently contains a single procedure which helps implement
the @code{(scsh rw)} module in guile-scsh.
@deffn primitive read-string!/partial str [port_or_fdes] [start] [end]
Read characters from an fport or file descriptor into a
string @var{str}. This procedure is scsh-compatible
and can efficiently read large strings. It will:
@itemize @bullet
@item
attempt to fill the entire string, unless the @var{start}
and/or @var{end} arguments are supplied. i.e., @var{start}
defaults to 0 and @var{end} defaults to
@code{(string-length str)}
@item
use the current input port if @var{port_or_fdes} is not
supplied.
@item
read any characters that are currently available,
without waiting for the rest (short reads are possible).
@item
wait for as long as it needs to for the first character to
become available, unless the port is in non-blocking mode
@item
return @code{#f} if end-of-file is encountered before reading
any characters, otherwise return the number of characters
read.
@item
return 0 if the port is in non-blocking mode and no characters
are immediately available.
@item
return 0 if the request is for 0 bytes, with no
end-of-file check
@end itemize
@end deffn
@node Default Ports
@section Default Ports for Input, Output and Errors
@rnindex current-input-port
@deffn primitive current-input-port
Return the current input port. This is the default port used
by many input procedures. Initially, @code{current-input-port}
returns the @dfn{standard input} in Unix and C terminology.
@end deffn
@rnindex current-output-port
@deffn primitive current-output-port
Return the current output port. This is the default port used
by many output procedures. Initially,
@code{current-output-port} returns the @dfn{standard output} in
Unix and C terminology.
@end deffn
@deffn primitive current-error-port
Return the port to which errors and warnings should be sent (the
@dfn{standard error} in Unix and C terminology).
@end deffn
@deffn primitive set-current-input-port port
@deffnx primitive set-current-output-port port
@deffnx primitive set-current-error-port port
Change the ports returned by @code{current-input-port},
@code{current-output-port} and @code{current-error-port}, respectively,
so that they use the supplied @var{port} for input or output.
@end deffn
@deffn primitive set-current-output-port port
Set the current default output port to PORT.
@end deffn
@deffn primitive set-current-error-port port
Set the current default error port to PORT.
@end deffn
@node Port Types
@section Types of Port
[Types of port; how to make them.]
@menu
* File Ports:: Ports on an operating system file.
* String Ports:: Ports on a Scheme string.
* Soft Ports:: Ports on arbitrary Scheme procedures.
* Void Ports:: Ports on nothing at all.
@end menu
@node File Ports
@subsection File Ports
The following procedures are used to open file ports.
See also @ref{Ports and File Descriptors, open}, for an interface
to the Unix @code{open} system call.
@deffn primitive open-file filename mode
Open the file whose name is @var{filename}, and return a port
representing that file. The attributes of the port are
determined by the @var{mode} string. The way in which this is
interpreted is similar to C stdio. The first character must be
one of the following:
@table @samp
@item r
Open an existing file for input.
@item w
Open a file for output, creating it if it doesn't already exist
or removing its contents if it does.
@item a
Open a file for output, creating it if it doesn't already
exist. All writes to the port will go to the end of the file.
The "append mode" can be turned off while the port is in use
@pxref{Ports and File Descriptors, fcntl}
@end table
The following additional characters can be appended:
@table @samp
@item +
Open the port for both input and output. E.g., @code{r+}: open
an existing file for both input and output.
@item 0
Create an "unbuffered" port. In this case input and output
operations are passed directly to the underlying port
implementation without additional buffering. This is likely to
slow down I/O operations. The buffering mode can be changed
while a port is in use @pxref{Ports and File Descriptors,
setvbuf}
@item l
Add line-buffering to the port. The port output buffer will be
automatically flushed whenever a newline character is written.
@end table
In theory we could create read/write ports which were buffered
in one direction only. However this isn't included in the
current interfaces. If a file cannot be opened with the access
requested, @code{open-file} throws an exception.
@end deffn
@rnindex open-input-file
@deffn procedure open-input-file filename
Open @var{filename} for input. Equivalent to
@smalllisp
(open-file @var{filename} "r")
@end smalllisp
@end deffn
@rnindex open-output-file
@deffn procedure open-output-file filename
Open @var{filename} for output. Equivalent to
@smalllisp
(open-file @var{filename} "w")
@end smalllisp
@end deffn
@rnindex call-with-input-file
@deffn 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 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
@rnindex with-input-from-file
@deffn 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 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 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.
@end deffn
@deffn primitive port-mode port
Returns the port modes associated with the open port @var{port}. These
will not necessarily be identical to the modes used when the port was
opened, since modes such as "append" which are used only during
port creation are not retained.
@end deffn
@deffn primitive port-filename port
Return the filename associated with @var{port}. This function returns
the strings "standard input", "standard output" and "standard error"
when called on the current input, output and error ports respectively.
@end deffn
@deffn primitive set-port-filename! port filename
Change the filename associated with @var{port}, using the current input
port if none is specified. Note that this does not change the port's
source of data, but only the value that is returned by
@code{port-filename} and reported in diagnostic output.
@end deffn
@deffn primitive file-port? obj
Determine whether @var{obj} is a port that is related to a file.
@end deffn
@node String Ports
@subsection String Ports
The following allow string ports to be opened by analogy to R4R*
file port facilities:
@deffn primitive call-with-output-string proc
Calls the one-argument procedure @var{proc} with a newly created output
port. When the function returns, the string composed of the characters
written into the port is returned.
@end deffn
@deffn primitive call-with-input-string string proc
Calls the one-argument procedure @var{proc} with a newly
created input port from which @var{string}'s contents may be
read. The value yielded by the @var{proc} is returned.
@end deffn
@deffn procedure with-output-to-string thunk
Calls the zero-argument procedure @var{thunk} with the current output
port set temporarily to a new string port. It returns a string
composed of the characters written to the current output.
@end deffn
@deffn procedure with-input-from-string string thunk
Calls the zero-argument procedure @var{thunk} with the current input
port set temporarily to a string port opened on the specified
@var{string}. The value yielded by @var{thunk} is returned.
@end deffn
@deffn primitive open-input-string str
Take a string and return an input port that delivers characters
from the string. The port can be closed by
@code{close-input-port}, though its storage will be reclaimed
by the garbage collector if it becomes inaccessible.
@end deffn
@deffn primitive open-output-string
Return an output port that will accumulate characters for
retrieval by @code{get-output-string}. The port can be closed
by the procedure @code{close-output-port}, though its storage
will be reclaimed by the garbage collector if it becomes
inaccessible.
@end deffn
@deffn primitive get-output-string port
Given an output port created by @code{open-output-string},
return a string consisting of the characters that have been
output to the port so far.
@end deffn
A string port can be used in many procedures which accept a port
but which are not dependent on implementation details of fports.
E.g., seeking and truncating will work on a string port,
but trying to extract the file descriptor number will fail.
@node Soft Ports
@subsection Soft Ports
A @dfn{soft-port} is a port based on a vector of procedures capable of
accepting or delivering characters. It allows emulation of I/O ports.
@deffn primitive make-soft-port pv modes
Return a port capable of receiving or delivering characters as
specified by the @var{modes} string (@pxref{File Ports,
open-file}). @var{pv} must be a vector of length 5. Its
components are as follows:
@enumerate 0
@item
procedure accepting one character for output
@item
procedure accepting a string for output
@item
thunk for flushing output
@item
thunk for getting one character
@item
thunk for closing port (not by garbage collection)
@end enumerate
For an output-only port only elements 0, 1, 2, and 4 need be
procedures. For an input-only port only elements 3 and 4 need
be procedures. Thunks 2 and 4 can instead be @code{#f} if
there is no useful operation for them to perform.
If thunk 3 returns @code{#f} or an @code{eof-object}
(@pxref{Input, eof-object?, ,r5rs, The Revised^5 Report on
Scheme}) it indicates that the port has reached end-of-file.
For example:
@lisp
(define stdout (current-output-port))
(define p (make-soft-port
(vector
(lambda (c) (write c stdout))
(lambda (s) (display s stdout))
(lambda () (display "." stdout))
(lambda () (char-upcase (read-char)))
(lambda () (display "@@" stdout)))
"rw"))
(write p p) @result{} #<input-output: soft 8081e20>
@end lisp
@end deffn
@node Void Ports
@subsection Void Ports
This kind of port causes any data to be discarded when written to, and
always returns the end-of-file object when read from.
@deffn primitive %make-void-port mode
Create and return a new void port. A void port acts like
@code{/dev/null}. The @var{mode} argument specifies the input/output
modes for this port: see the documentation for @code{open-file} in
@ref{File Ports}.
@end deffn
@c Local Variables:
@c TeX-master: "guile.texi"
@c End: