@iftex
@finalout
@end iftex
-@comment $Id: scheme.texinfo,v 1.23 1993/10/13 08:53:11 cph Exp $
+@comment $Id: scheme.texinfo,v 1.24 1993/10/14 06:42:03 cph Exp $
@comment %**start of header (This is for running Texinfo on a region.)
@setfilename scheme
@settitle MIT Scheme Reference
@titlepage
@title{MIT Scheme Reference Manual}
-@subtitle Edition 1.23 alpha
+@subtitle Edition 1.24 alpha
@subtitle for Scheme Release 7.2
-@subtitle 13 October 1993
+@subtitle 14 October 1993
@author by Chris Hanson
@author the MIT Scheme Team
@author and a cast of thousands
Port Primitives
-* Input Port Primitives::
-* Output Port Primitives::
+* Constructors and Accessors for Ports::
+* Blocking Mode::
+* Terminal Mode::
+* Input Port Operations::
+* Output Port Operations::
File-System Interface
@example
@group
bit-string? environment? pathname? string?
-boolean? eof-object? port? symbol?
-cell? null? procedure? vector?
-char? number? promise? weak-pair?
-condition? pair?
+boolean? null? port? symbol?
+cell? number? procedure? vector?
+char? pair? promise? weak-pair?
+condition?
@end group
@end example
Returns a newly allocated hash table that accepts arbitrary objects as
keys, and compares those keys with @code{eq?}. The keys are held
weakly.
+
+@findex make-symbol-hash-table
+For compatibility with old code, @code{make-symbol-hash-table} is a
+synonym for this procedure.
@end deffn
@deffn {procedure+} make-eqv-hash-table [initial-size]
Returns a newly allocated hash table that accepts arbitrary objects as
keys, and compares those keys with @code{eqv?}. The keys are held
weakly, except that booleans, characters, and numbers are held strongly.
+
+@findex make-object-hash-table
+For compatibility with old code, @code{make-object-hash-table} is a
+synonym for this procedure.
@end deffn
@deffn {procedure+} make-equal-hash-table [initial-size]
strongly.
@end deffn
-@deffn {procedure+} make-symbol-hash-table [initial-size]
-This procedure is the same as @code{make-eq-hash-table}. It is provided
-only for compatibility with old code.
-@end deffn
-
-@deffn {procedure+} make-object-hash-table [initial-size]
-This procedure is the same as @code{make-eqv-hash-table}. It is
-provided only for compatibility with old code.
-@end deffn
-
The next two procedures are used to create new hash-table constructors.
All of the above hash table constructors, with the exception of
@code{make-eqv-hash-table}, could have been created by calls to these
@section Ports
@cindex port (defn)
+@findex console-i/o-port
Scheme uses ports for @sc{i/o}. A @dfn{port}, which can be treated like
any other Scheme object, serves as a source or sink for data. A port
must be open before it can be read from or written to. The standard
-@sc{i/o} ports, the keyboard and the terminal screen, are opened
-automatically when you start Scheme. When you use a file for input or
-output, you need to explicitly open and close a port to the file (with
-procedures described in this chapter). Additional procedures let you
-open ports to strings.
+@sc{i/o} port, @code{console-i/o-port}, is opened automatically when you
+start Scheme. When you use a file for input or output, you need to
+explicitly open and close a port to the file (with procedures described
+in this chapter). Additional procedures let you open ports to strings.
@cindex current input port (defn)
@cindex input port, current (defn)
@findex read
Many input procedures, such as @code{read-char} and @code{read}, read
data from the current input port by default, or from a port that you
-specify. The current input port is initially the keyboard, but Scheme
-provides procedures that let you change the current input port to be a
-file or string.
+specify. The current input port is initially @code{console-i/o-port},
+but Scheme provides procedures that let you change the current input
+port to be a file or string.
@cindex current output port (defn)
@cindex output port, current (defn)
@findex display
Similarly, many output procedures, such as @code{write-char} and
@code{display}, write data to the current output port by default, or to
-a port that you specify. The current output port is initially the
-terminal screen, but Scheme provides procedures that let you change the
-current output port to be a file or string.
+a port that you specify. The current output port is initially
+@code{console-i/o-port}, but Scheme provides procedures that let you
+change the current output port to be a file or string.
-Most ports read or write only @sc{ascii} characters. However, it is
-possible to create ports that will read and write arbitrary characters.
-The limitation to @sc{ascii} characters is imposed entirely by the port,
-not by the @sc{i/o} operations.
+All standard ports read or write only @sc{ascii} characters. However,
+it is possible to create ports that will read and write arbitrary
+characters. The limitation to @sc{ascii} characters is imposed entirely
+by the port, not by the @sc{i/o} operations.
+
+Every port is either an input port, an output port, or both. The
+following predicates distinguish all of the possible cases.
+
+@deffn {procedure+} port? object
+@cindex type predicate, for port
+Returns @code{#t} if @var{object} is a port, otherwise returns
+@code{#f}.
+@end deffn
@deffn procedure input-port? object
-@deffnx procedure output-port? object
-@cindex type predicate, for input port
-@cindex type predicate, for output port
-Returns @code{#t} if @var{object} is an input port or output port
-respectively, otherwise returns @code{#f}. Any object satisfying one of
-these predicates also satisfies @code{vector?}.
+Returns @code{#t} if @var{object} is an input port, otherwise returns
+@code{#f}. Any object satisfying this predicate also satisfies
+@code{port?}.
+@end deffn
+
+@deffn procedure output-port? object
+Returns @code{#t} if @var{object} is an output port, otherwise returns
+@code{#f}. Any object satisfying this predicate also satisfies
+@code{port?}.
+@end deffn
+
+@deffn {procedure+} i/o-port? object
+Returns @code{#t} if @var{object} is both an input port and an output
+port, otherwise returns @code{#f}. Any object satisfying this predicate
+also satisfies @code{port?}, @code{input-port?}, and
+@code{output-port?}.
@end deffn
@deffn {procedure+} guarantee-input-port object
@deffnx {procedure+} guarantee-output-port object
-These procedures check the type of @var{object}, signalling an error if it
-is not an input port or output port, respectively. Otherwise they return
-@var{object}.
+These procedures check the type of @var{object}, signalling an error of
+type @code{condition-type:wrong-type-argument} if it is not an input
+port or output port, respectively. Otherwise they return @var{object}.
@end deffn
@deffn procedure current-input-port
@findex console-input-port
Returns the current input port. Initially, @code{current-input-port}
-returns the value of @code{console-input-port}.
+returns the value of @code{console-i/o-port}.
@end deffn
@deffn procedure current-output-port
@findex console-output-port
Returns the current output port. Initially, @code{current-output-port}
-returns the value of @code{console-output-port}.
+returns the value of @code{console-i/o-port}.
@end deffn
@deffn {procedure+} with-input-from-port input-port thunk
presence of continuations (@pxref{Fluid Binding}).
@end deffn
-@defvr {variable+} console-input-port
+@deffn {procedure+} set-current-input-port! input-port
+This procedure makes @var{input-port} the current input port and returns
+an unspecified value.
+@end deffn
+
+@deffn {procedure+} set-current-output-port! output-port
+This procedure makes @var{output-port} the current output port and
+returns an unspecified value.
+@end deffn
+
+@defvr {variable+} console-i/o-port
@cindex port, console
+@cindex console, port
@cindex input port, console
-@cindex console, input port
-@code{console-input-port} is an input port that reads from the terminal
-keyboard (in unix, standard input).
-@end defvr
-
-@defvr {variable+} console-output-port
@cindex output port, console
-@cindex console, output port
-@code{console-output-port} is an output port that writes to the terminal
-screen (in unix, standard output).
+@code{console-i/o-port} is an i/o port that communicates with the
+``console''. Under unix, the console is the controlling terminal of the
+Scheme process. Under DOS, the console is the a combination of the
+keyboard and the display. Under Windows, the console is the window that
+is created when Scheme starts up.
+
+@findex console-input-port
+@findex console-output-port
+For compatibility with old code, @code{console-input-port} and
+@code{console-output-port} are synonyms for this variable.
@end defvr
-@deffn procedure close-input-port input-port
+@deffn {procedure+} close-port port
+@deffnx procedure close-input-port port
+@deffnx procedure close-output-port port
@cindex closing, of port
-Closes @var{input-port} and returns an unspecified value. If
-@var{input-port} is a file port, the file is closed.
-@end deffn
-
-@deffn procedure close-output-port output-port
-Closes @var{output-port} and returns an unspecified value. If
-@var{output-port} is a file port, the file is closed.
+Closes @var{port} and returns an unspecified value. If @var{port} is a
+file port, the file is closed. @code{close-input-port} and
+@code{close-output-port} are synonyms for @code{close-port} that are
+defined for compatibility with standard Scheme.
@end deffn
@node File Ports, String Ports, Ports, Input/Output
@cindex input port, file
@cindex output port, file
@cindex I/O, to files
-@findex close-input-port
-@findex close-output-port
Before Scheme can access a file for reading or writing, it is necessary
to open a port to the file. This section describes procedures used to
open ports to files. Such ports are closed (like any other port) by
-@code{close-input-port} or @code{close-output-port}, depending on their
-type.
-
-@findex canonicalize-input-filename
-@findex canonicalize-output-filename
-Before opening an input file, by whatever method, the @var{filename}
-argument is converted to canonical form by the procedure
-@code{canonicalize-input-filename}. Similarly, the @var{filename}
-argument used to open an output file is converted using
-@code{canonicalize-output-filename}. See those procedures' definitions
-for details on the canonicalization process. For naive purposes, the
-following guidelines can be used: @var{filename} is a character string
-that is the name of the file; relative filenames (on unix, those not
-beginning with @samp{/}) are interpreted relative to the directory in
-which MIT Scheme was started.
-
-Implementation notes:
-
-@itemize @bullet
-@item
-On unix systems, opening an output file that already exists causes the
-existing file to be removed and a new one opened in its place. However,
-if the user does not have permission to write in the file's directory,
-the file is truncated to zero length and overwritten.
-
-@item
-File input ports always deliver @sc{ascii} characters, and file
-output ports only accept @sc{ascii} characters. This will change if
-someone ports MIT Scheme to a non-@sc{ascii} operating system.
-@end itemize
-
-Here are the specific operations for file ports:
+@code{close-port}. File ports are automatically closed if they are
+reclaimed by the garbage collector.
+
+@findex merge-pathnames
+Before opening a file for input or output, by whatever method, the
+@var{filename} argument is converted to canonical form by calling the
+procedure @code{merge-pathnames} with @var{filename} as its sole
+argument. Thus, @var{filename} can be either a string or a pathname,
+and it is merged with the current pathname defaults to produce the
+pathname that is then opened.
+
+@cindex binary file ports
+@cindex newline translation
+Any file can be opened in two modes, @dfn{normal} and @dfn{binary}.
+Some operating systems, e.g.@: unix, do not distinguish these modes.
+DOS is an example of an operating system that does distinguish these
+modes: in normal mode, DOS file ports perform @code{newline
+translation}, mapping between the carriage-return/linefeed sequence that
+terminates text lines in files, and the @code{#\newline} that terminates
+lines in Scheme. In binary mode, DOS ports do not perform newline
+translation. Unless otherwise mentioned, the procedures in this section
+open files in normal mode.
@deffn procedure open-input-file filename
@cindex construction, of file input port
Takes a filename referring to an existing file and returns an input port
capable of delivering characters from the file. If the file cannot be
opened, an error is signalled.
-
-@findex close-input-port
-Use the procedure @code{close-input-port} to close the port opened by
-this procedure. If an input port returned by this procedure is
-reclaimed by the garbage collector, it is automatically closed.
@end deffn
-@deffn procedure open-output-file filename
+@deffn procedure open-output-file filename [append?]
@cindex construction, of file output port
Takes a filename referring to an output file to be created and returns
an output port capable of writing characters to a new file by that name.
-If the file cannot be opened, an error is signalled. If a file with the
-given name already exists, if possible it will be deleted and a new file
-opened in its place, or failing that the existing file will be truncated
-and overwritten.
+If the file cannot be opened, an error is signalled.
-@findex close-output-port
-Use the procedure @code{close-output-port} to close the port opened by
-this procedure. If an output port returned by this procedure is
-reclaimed by the garbage collector, it is automatically closed.
+@cindex appending, to output file
+If @var{append?} is given and not @code{#f}, the file is opened in
+@dfn{append} mode. In this mode, the contents of the file are not
+overwritten; instead any characters written to the file are appended to
+the end of the existing contents. If the file does not exist, append
+mode creates the file and writes to it in the normal way. The optional
+argument @var{append?} is an MIT Scheme extension.
+@end deffn
+
+@deffn {procedure+} open-i/o-file filename
+@cindex construction, of file input port
+Takes a filename referring to an existing file and returns an @sc{i/o}
+port capable of reading characters from and writing characters to the
+file. If the file cannot be opened, an error is signalled.
+
+This procedure is often used to open special files. For example, under
+unix this procedure can be used to open terminal device files, @sc{pty}
+device files, and named pipes.
+@end deffn
+
+@deffn {procedure+} open-binary-input-file filename
+@deffnx {procedure+} open-binary-output-file filename [append?]
+@deffnx {procedure+} open-binary-i/o-file filename
+These procedures open files in binary mode. In all other respects they
+are identical to @code{open-input-file}, @code{open-output-file}, and
+@code{open-i/o-file}, respectively.
@end deffn
@deffn {procedure+} close-all-open-files
@cindex closing, of file port
-This procedure closes all file ports (input and output) that are open at
-the time that it is called.
+This procedure closes all file ports that are open at the time that it
+is called, and returns an unspecified value.
@end deffn
@deffn procedure call-with-input-file filename procedure
@deffnx procedure call-with-output-file filename procedure
-@var{Procedure} must be a procedure of one argument. For
-@code{call-with-input-file} the file specified by @var{filename} must
-already exist; for @code{call-with-output-file}, if the file exists, if
-possible it will be deleted and a new file opened in its place, or
-failing that the existing file will be truncated and overwritten.
-
These procedures call @var{procedure} 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 @var{procedure} returns,
-then the port is closed automatically and the value yielded by
+obtained by opening the named file for input or output, respectively.
+If the file cannot be opened, an error is signalled. If @var{procedure}
+returns, then the port is closed automatically and the value yielded by
@var{procedure} is returned. If @var{procedure} does not return, then
the port will not be closed automatically unless it is reclaimed by the
garbage collector.@footnote{Because Scheme's escape procedures have
@code{call-with-output-file}.}
@end deffn
+@deffn {procedure+} call-with-binary-input-file filename procedure
+@deffnx {procedure+} call-with-binary-output-file filename procedure
+These procedures open files in binary mode. In all other respects they
+are identical to @code{call-with-input-file} and
+@code{call-with-output-file}, respectively.
+@end deffn
+
@deffn procedure with-input-from-file filename thunk
@deffnx procedure with-output-to-file filename thunk
@cindex current input port, rebinding
@cindex current output port, rebinding
-@var{Thunk} must be a procedure of no arguments. For
-@code{with-input-from-file} the file specified by @var{filename} must
-already exist; for @code{with-output-to-file}, if the file exists, if
-possible it will be deleted and a new file opened in its place, or
-failing that the existing file will be truncated and overwritten.
-
@findex current-input-port
@findex current-output-port
+@var{Thunk} must be a procedure of no arguments.
The file is opened for input or output, an input or output port
connected to it is made the default value returned by
@code{current-input-port} or @code{current-output-port}, and the
@code{with-input-from-file} and @code{with-output-to-file} return 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; in that situation MIT Scheme closes the port.
+implementation-dependent; in that situation MIT Scheme leaves the files
+open.
+@end deffn
+
+@deffn {procedure+} with-input-from-binary-file filename thunk
+@deffnx {procedure+} with-output-to-binary-file filename thunk
+These procedures open files in binary mode. In all other respects they
+are identical to @code{with-input-from-file} and
+@code{with-output-to-file}, respectively.
@end deffn
@node String Ports, Input Procedures, File Ports, Input/Output
This section describes the simplest kinds of ports: input ports that
read their input from given strings, and output ports that accumulate
their output and return it as a string. It also describes
-``truncating'' output ports, that can limit the length of the resulting
+``truncating'' output ports, which can limit the length of the resulting
string to a given value.
-String input ports always deliver @sc{ascii} characters, and string
-output ports only accept @sc{ascii} characters. This will change if
-someone ports MIT Scheme to a non-@sc{ascii} operating system.
+@deffn {procedure+} string->input-port string [start [end]]
+@cindex string, converting to input port
+@cindex construction, of string input port
+Returns a new string port that delivers characters from @var{string}.
+The optional arguments @var{start} and @var{end} may be used to specify
+that the string port delivers characters from a substring of
+@var{string}; if not given, @var{start} defaults to @code{0} and
+@var{end} defaults to @code{(string-length @var{string})}.
+@end deffn
@deffn {procedure+} with-input-from-string string thunk
@cindex current input port, rebinding
-Creates a new input port that reads from @var{string}, makes that port
-the current input port, and calls @var{thunk}. When @var{thunk}
-returns, @code{with-input-from-string} restores the previous current
-input port and returns the result returned by @var{thunk}.
+@var{Thunk} must be a procedure of no arguments.
+@code{with-input-from-string} creates a new input port that reads from
+@var{string}, makes that port the current input port, and calls
+@var{thunk}. When @var{thunk} returns, @code{with-input-from-string}
+restores the previous current input port and returns the result yielded
+by @var{thunk}.
@example
(with-input-from-string "(a b c) (d e f)" read) @result{} (a b c)
@end example
@end deffn
-@deffn {procedure+} string->input-port string
-@cindex string, converting to input port
-@cindex construction, of string input port
-Returns a new string port that delivers characters from @var{string}.
+@deffn {procedure+} with-string-output-port procedure
+@var{Procedure} is called with one argument, an output port. The value
+yielded by @var{procedure} is ignored. When @var{procedure} returns,
+@code{with-string-output-port} returns the accumulated output to the
+port as a newly allocated string.
@end deffn
@deffn {procedure+} with-output-to-string thunk
@cindex current output port, rebinding
@cindex construction, of string output port
@findex current-output-port
-@var{Thunk} must be a procedure of no arguments. Creates a new output
-port that accumulates output, makes that port the default value returned
-by @code{current-output-port}, and calls @var{thunk} with no arguments.
+@var{Thunk} must be a procedure of no arguments.
+@code{with-output-to-string} creates a new output port that accumulates
+output, makes that port the default value returned by
+@code{current-output-port}, and calls @var{thunk} with no arguments.
When @var{thunk} returns, @code{with-output-to-string} restores the
previous default and returns the accumulated output as a newly allocated
string.
(lambda ()
(write 'abc))) @result{} "abc"
@end example
+
+Note: this procedure is equivalent to:
+
+@example
+(with-string-output-port
+ (lambda (port)
+ (with-output-to-port port @var{thunk})))
+@end example
@end deffn
@deffn {procedure+} with-output-to-truncated-string k thunk
@end deffn
@deffn {procedure+} write-to-string object [k]
-@findex with-output-to-truncated-string
Writes @var{object} to a string output port, and returns the resulting
-newly allocated string. If @var{k} is supplied and not @code{#f}, the
-output is truncated after @var{k} characters. Unlike
-@code{with-output-to-truncated-string}, if @var{k} is specified, this
-procedure always returns a string. There is no sure way to find out
-whether or not the returned string was truncated.
+newly allocated string. If @var{k} is supplied and not @code{#f}, this
+procedure is equivalent to
+
+@example
+@group
+(with-output-to-truncated-string @var{k}
+ (lambda ()
+ (write @var{object})))
+@end group
+@end example
+
+otherwise it is equivalent to
+
+@example
+@group
+(with-output-to-string
+ (lambda ()
+ (write @var{object})))
+@end group
+@end example
@end deffn
@node Input Procedures, Output Procedures, String Ports, Input/Output
@cindex input operations
This section describes the procedures that read input. Input procedures
-can read either from the current input port or from a particular port.
+can read either from the current input port or from a given port.
Remember that to read from a file, you must first open a port to the
-file.@footnote{Previous implementations of MIT Scheme treated
-interactive ports specially: when certain of these procedures were
-called, the input editor was temporarily enabled or disabled or the port
-was temporarily switched between blocking and non-blocking modes. In
-the current implementation, these procedures have no effect on the input
-editor or the blocking mode.}
+file.
+
+@cindex interactive input ports (defn)
+Input ports can be divided into two types, called @dfn{interactive} and
+@dfn{non-interactive}. Interactive input ports are ports that read
+input from a source that is time-dependent; for example, a port that
+reads input from a terminal or from another program. Non-interactive
+input ports read input from a time-independent source, such as an
+ordinary file or a character string.
All optional arguments called @var{input-port}, if not supplied, default
to the current input port.
@section Output Procedures
@cindex output procedures
+@cindex buffering, of output
+@cindex flushing, of buffered output
+Output ports may or may not support @dfn{buffering} of output, in which
+output characters are collected together in a buffer and then sent to
+the output device all at once. (Most of the output ports implemented by
+the runtime system support buffering.) Sending all of the characters in
+the buffer to the output device is called @dfn{flushing} the buffer. In
+general, output procedures do not flush the buffer of an output port
+unless the buffer is full.
+
+@cindex discretionary flushing, of buffered output
+@findex discretionary-output-flush
+However, the standard output procedures described in this section
+perform what is called @dfn{discretionary} flushing of the buffer.
+Discretionary output flushing works as follows. After a procedure
+performs its output (writing characters to the output buffer), it checks
+to see if the port implements an operation called
+@code{discretionary-output-flush}. If so, then that operation is
+invoked to flush the buffer. At present, only the console port defines
+@code{discretionary-output-flush}; this is used to guarantee that output
+to the console appears immediately after it is written, without
+requiring calls to @code{flush-output}.
+
All optional arguments called @var{output-port}, if not supplied,
default to the current output port.
+@deffn {procedure+} flush-output [output-port]
+If @var{output-port} is buffered, this causes the contents of its buffer
+to be written to the output device. Otherwise it has no effect.
+Returns an unspecified value.
+@end deffn
+
@deffn procedure write-char char [output-port]
@cindex character, output to port
Writes @var{char} (the character itself, not a written representation of
-the character) to @var{output-port}, and returns an unspecified
-value.
+the character) to @var{output-port}, performs discretionary output
+flushing, and returns an unspecified value.
@end deffn
@deffn procedure display object [output-port]
that appear in the written representation are not enclosed in
doublequotes, and no characters are escaped within those strings.
Character objects appear in the representation as if written by
-@code{write-char} instead of by @code{write}. @code{display} returns an
-unspecified value.@footnote{@code{write} is intended for producing
-machine-readable output and @code{display} is for producing
-human-readable output.}
+@code{write-char} instead of by @code{write}. @code{display} performs
+discretionary output flushing and returns an unspecified
+value.@footnote{@code{write} is intended for producing machine-readable
+output and @code{display} is for producing human-readable output.}
@end deffn
@deffn procedure write object [output-port]
@code{write} shall be parsable by @code{read} into an equivalent object.
Thus strings that appear in the written representation are enclosed in
doublequotes, and within those strings backslash and doublequote are
-escaped by backslashes. @code{write} returns an unspecified value.
+escaped by backslashes. @code{write} performs discretionary output
+flushing and returns an unspecified value.
@end deffn
@deffn procedure newline [output-port]
@cindex newline character, output to port
-Writes an end of line to @var{output-port} and returns an unspecified
-value. Equivalent to @code{(write-char #\newline @var{output-port})}.
+Writes an end-of-line to @var{output-port}, performs discretionary
+output flushing, and returns an unspecified value. Equivalent to
+@code{(write-char #\newline @var{output-port})}.
+@end deffn
+
+@deffn {procedure+} fresh-line [output-port]
+Some output ports are able to tell whether or not they are at the
+beginning of a line of output (unfortunately the runtime system does not
+implement any such ports). If @var{output-port} is such a port, this
+procedure writes an end-of-line to the port only if the port is not
+already at the beginning of a line. If @var{output-port} is not such a
+port, this procedure is identical to @code{newline}. In either case,
+@code{fresh-line} performs discretionary output flushing and returns an
+unspecified value.
@end deffn
@deffn {procedure+} write-line object [output-port]
-Like @code{write}, except that it writes an end of line to
-@var{output-port} before writing @var{object}'s representation. Returns
-an unspecified value.
+Like @code{write}, except that it writes an end-of-line to
+@var{output-port} before writing @var{object}'s representation. This
+procedure performs discretionary output flushing and returns an
+unspecified value.
@end deffn
@deffn {procedure+} write-string string [output-port]
@cindex string, output to port
-Writes @var{string} to @var{output-port} and returns an unspecified
-value. This is equivalent to writing the contents of string, one
-character at a time using @code{write-char}, except that it is usually
-much faster.
+Writes @var{string} to @var{output-port}, performs discretionary output
+flushing, and returns an unspecified value. This is equivalent to
+writing the contents of string, one character at a time using
+@code{write-char}, except that it is usually much faster.
@code{(write-string @var{string})} is the same as @code{(display
@var{string})} except that it is faster. Use @code{write-string} when you
@cindex console, ringing the bell
@cindex ringing the console bell
@cindex bell, ringing on console
-Performs a ``beep'' operation on @var{output-port} and returns an
-unspecified value. On the console output port, this usually causes the
-terminal bell to beep, but more sophisticated interactive ports may take
-other actions, such as flashing the screen. On most output ports, e.g.@:
-file and string output ports, this does nothing.
+Performs a ``beep'' operation on @var{output-port}, performs
+discretionary output flushing, and returns an unspecified value. On the
+console port, this usually causes the console bell to beep, but more
+sophisticated interactive ports may take other actions, such as flashing
+the screen. On most output ports, e.g.@: file and string output ports,
+this does nothing.
@end deffn
@deffn {procedure+} clear [output-port]
@cindex screen, clearing
@cindex terminal screen, clearing
@cindex clearing the console screen
-``Clears the screen'' of @var{output-port} and returns an unspecified
-value. On a terminal or window, this has a well-defined effect. On
-other output ports, e.g.@: file and string output ports, this is
-equivalent to @code{(write-char #\page @var{output-port})}.
+``Clears the screen'' of @var{output-port}, performs discretionary
+output flushing, and returns an unspecified value. On a terminal or
+window, this has a well-defined effect. On other output ports, e.g.@:
+file and string output ports, this does nothing.
@end deffn
@deffn {procedure+} pp object [output-port [as-code?]]
@code{pp} attempts to print the source text. If the optional argument
@var{as-code?} is true, @code{pp} prints lists as Scheme code, providing
appropriate indentation; by default this argument is false. @code{pp}
-returns an unspecified value.
+performs discretionary output flushing and returns an unspecified value.
@end deffn
@node Format, Custom Output, Output Procedures, Input/Output
@code{#t}, the output is sent to the current output port. Otherwise,
@var{destination} must be an output port, and the output is sent there.
+This procedure performs discretionary output flushing (@pxref{Output
+Procedures}).
+
A @code{format} directive consists of a tilde (@code{~}), optional
prefix parameters separated by commas, optional colon (@code{:}) and
at-sign (@code{@@}) modifiers, and a single character indicating what
@end example
@noindent
-@findex display
-@findex object-hash
+@findex write
+@findex write-string
+@findex hash
Here @var{name} is the external representation of the argument
-@var{name}, as generated by @code{display}, and @var{hash} is the
-external representation of an exact non-negative integer unique to the
-object being printed (specifically, it is the result of calling
-@code{object-hash} on the object). Subsequently, the expression
+@var{name}, as generated by @code{write},@footnote{Except that if the
+argument @var{name} is a string, its external representation is
+generated by @code{write-string}.} and @var{hash} is the external
+representation of an exact non-negative integer unique to the object
+being printed (specifically, it is the result of calling @code{hash} on
+the object). Subsequently, the expression
@example
#@@@var{hash}
@item Standard operations
There is a specific set of standard operations for input ports, and a
different set for output ports. Applications can assume that the
-appropriate set of operations is implemented for every port.
+standard input operations are implemented for all input ports, and
+likewise the standard output operations are implemented for all output
+ports.
@cindex standard operations, on port
@item Custom operations
@end table
@menu
-* Input Port Primitives::
-* Output Port Primitives::
+* Constructors and Accessors for Ports::
+* Blocking Mode::
+* Terminal Mode::
+* Input Port Operations::
+* Output Port Operations::
@end menu
-@node Input Port Primitives, Output Port Primitives, , Port Primitives
-@subsection Input Port Primitives
-@cindex input port primitives
+@node Constructors and Accessors for Ports, Blocking Mode, , Port Primitives
+@subsection Constructors and Accessors for Ports
+
+The procedures in this section provide means for constructing ports with
+custom operations, accessing their operations, and manipulating their
+internal state.
@deffn {procedure+} make-input-port operations object
-@cindex construction, of input port
+@deffnx {procedure+} make-output-port operations object
+@deffnx {procedure+} make-i/o-port operations object
+@cindex construction, of port
Operations must be a list; each element is a list of two elements, the
-name of the operation and the procedure that implements it. A new input
-port is returned with the given operations and a state component of
-@var{object}. @var{Operations} need not contain definitions for all of
-the standard operations. @code{make-input-port} will provide defaults
-for any standard operations that are not defined. At a minimum, the
-operations @code{read-char}, @code{peek-char}, and @code{char-ready?}
-must be defined.
-@end deffn
-
-@deffn {procedure+} input-port/copy input-port object
-@cindex copying, of input port
-Returns a new copy of @var{input-port}, identical to the original except
-that its state component is @var{object}. @var{Input-port} is not
-modified.
+name of the operation and the procedure that implements it. A new port
+is returned with the given operations and a state component of
+@var{object}.
-@code{input-port/copy} is normally used to speed up creation of input
-ports. This is done by creating a template using
-@code{make-input-port}; a dummy state component is supplied for the
-template. Then @code{input-port/copy} is used to make a copy of the
-template, supplying the copy with the correct state. This is useful
-because @code{make-input-port} is somewhat slow, as it must parse the
-@var{operations} list, provide defaulting for missing operations, etc.
+@var{Operations} need not contain definitions for all of the standard
+operations; the procedure will provide defaults for any standard
+operations that are not defined. At a minimum, the following operations
+must be defined: for input ports, @code{read-char}, @code{peek-char},
+and @code{char-ready?}; for output ports, either @code{write-char} or
+@code{write-substring}; @sc{i/o} ports must supply the minimum
+operations for both input and output.
@end deffn
-@deffn {procedure+} input-port/state input-port
-Returns the state component of @var{input-port}.
-@end deffn
+@deffn {procedure+} port/copy port object
+@cindex copying, of port
+Returns a new copy of @var{port}, identical to the original except that
+its state component is @var{object}. @var{Port} is not modified.
-@deffn {procedure+} set-input-port/state! input-port object
-Changes the state component of @var{input-port} to be @var{object}.
-Returns an unspecified value.
+@code{port/copy} is normally used to speed up creation of ports. This
+is done by creating a template using one of the port constructors
+@code{make-input-port}, @code{make-output-port}, or
+@code{make-i/o-port}, as appropriate; a dummy state component is
+supplied for the template. Then @code{port/copy} is used to make a copy
+of the template, supplying the copy with the correct state. This is
+useful because the port constructors are somewhat slow, as they must
+parse the @var{operations} list, provide defaulting for missing
+operations, etc.
+
+@findex input-port/copy
+@findex output-port/copy
+For compatibility with old code, @code{input-port/copy} and
+@code{output-port/copy} are synonyms for this procedure.
@end deffn
-@deffn {procedure+} input-port/operation input-port name
-Returns the procedure that implements the operation called @var{name},
-or @code{#f} if @var{input-port} has no such operation.
+@deffn {procedure+} port/state port
+Returns the state component of @var{port}.
+
+@findex input-port/state
+@findex output-port/state
+For compatibility with old code, @code{input-port/state} and
+@code{output-port/state} are synonyms for this procedure.
@end deffn
-@deffn {procedure+} input-port/custom-operation input-port name
-Returns the procedure that implements the custom operation called
-@var{name}. If @var{name} names a standard operation, or if
-@var{input-port} has no such custom operation, @code{#f} is returned.
-This is faster than @code{input-port/operation} if @var{name} is known
-to be the name of a custom operation.
+@deffn {procedure+} set-port/state! port object
+Changes the state component of @var{port} to be @var{object}.
+Returns an unspecified value.
+
+@findex set-input-port/state!
+@findex set-output-port/state!
+For compatibility with old code, @code{set-input-port/state!} and
+@code{set-output-port/state!} are synonyms for this procedure.
+@end deffn
+
+@deffn {procedure+} port/operation port object
+Returns the operation named @var{object} in @var{port}. If @var{port}
+has no such operation, returns @code{#f}.
+
+@findex input-port/operation
+@findex output-port/operation
+@findex input-port/custom-operation
+@findex output-port/custom-operation
+For compatibility with old code, @code{input-port/operation} and
+@code{output-port/operation} are similar to @code{port/operation}. They
+differ in that they translate certain old operation names to new
+equivalents before calling @code{port/operation}.
+@code{input-port/custom-operation} and
+@code{output-port/custom-operation} are synonyms for
+@code{input-port/operation} and @code{output-port/operation},
+respectively.
+@end deffn
+
+@deffn {procedure+} port/operation-names port
+Returns a list whose elements are the names of the operations supported
+by @code{port}. The list is not newly allocated and must not be
+modified.
+
+@findex input-port/operation-names
+@findex output-port/operation-names
+For compatibility with old code, @code{input-port/operation-names} and
+@code{output-port/operation-names} are synonyms for this procedure.
@end deffn
@deffn {procedure+} make-eof-object input-port
is sometimes useful when building input ports.
@end deffn
-The following are the standard operations on input ports.
+@node Blocking Mode, Terminal Mode, Constructors and Accessors for Ports, Port Primitives
+@subsection Blocking Mode
+
+@cindex blocking mode, of port
+An interactive port is always in one of two modes: @dfn{blocking} or
+@dfn{non-blocking}. This mode is independent of the terminal mode: each
+can be changed independent of the other. Furthermore, if it is an
+interactive @sc{i/o} port, there are separate blocking modes for input
+and for output.
+
+If an input port is in blocking mode, attempting to read from it when no
+input is available will cause Scheme to ``block'', i.e.@: suspend
+itself, until input is available. If an input port is in non-blocking
+mode, attempting to read from it when no input is available will cause
+the reading procedure to return immediately, indicating the lack of
+input in some way (exactly how this situation is indicated is separately
+specified for each procedure or operation).
+
+An output port in blocking mode will block if the output device is not
+ready to accept output. In non-blocking mode it will return immediately
+after performing as much output as the device will allow (again, each
+procedure or operation reports this situation in its own way).
+
+Interactive ports are initially in blocking mode; this can be changed at
+any time with the procedures defined in this section.
+
+These procedures represent blocking mode by the symbol @code{blocking},
+and non-blocking mode by the symbol @code{nonblocking}. An argument
+called @var{mode} must be one of these symbols. A @var{port} argument
+to any of these procedures may be any port, even if that port does not
+support blocking mode; in that case, the port is not modified in any
+way.
+
+@deffn {procedure+} port/input-blocking-mode port
+Returns the input blocking mode of @var{port}.
+@end deffn
+
+@deffn {procedure+} port/set-input-blocking-mode port mode
+Changes the input blocking mode of @var{port} to be @var{mode}. Returns
+an unspecified value.
+@end deffn
+
+@deffn {procedure+} port/with-input-blocking-mode port mode thunk
+@var{Thunk} must be a procedure of no arguments.
+@code{port/with-input-blocking-mode}
+binds the input blocking mode of @var{port} to be @var{mode}, executes
+@var{thunk}, restores the input blocking mode of @var{port} to what it
+was when @code{port/with-input-blocking-mode} was called, and returns
+the value that was yielded by @var{thunk}. This binding is performed
+by @code{dynamic-wind}, which guarantees that the input blocking mode is
+restored if @var{thunk} escapes from its continuation.
+@end deffn
+
+@deffn {procedure+} port/output-blocking-mode port
+Returns the output blocking mode of @var{port}.
+@end deffn
+
+@deffn {procedure+} port/set-output-blocking-mode port mode
+Changes the output blocking mode of @var{port} to be @var{mode}.
+Returns an unspecified value.
+@end deffn
+
+@deffn {procedure+} port/with-output-blocking-mode port mode thunk
+@var{Thunk} must be a procedure of no arguments.
+@code{port/with-output-blocking-mode}
+binds the output blocking mode of @var{port} to be @var{mode}, executes
+@var{thunk}, restores the output blocking mode of @var{port} to what it
+was when @code{port/with-output-blocking-mode} was called, and returns
+the value that was yielded by @var{thunk}. This binding is performed
+by @code{dynamic-wind}, which guarantees that the output blocking mode
+is restored if @var{thunk} escapes from its continuation.
+@end deffn
+
+@node Terminal Mode, Input Port Operations, Blocking Mode, Port Primitives
+@subsection Terminal Mode
+
+@cindex terminal mode, of port
+A port that reads from or writes to a terminal has a @dfn{terminal
+mode}; this is either @dfn{cooked} or @dfn{raw}. This mode is
+independent of the blocking mode: each can be changed independent of the
+other. Furthermore, a terminal @sc{i/o} port has independent terminal
+modes both for input and for output.
+
+@cindex cooked mode, of terminal port
+A terminal port in cooked mode provides some standard processing to make
+the terminal easy to communicate with. For example, under unix, cooked
+mode on input reads from the terminal a line at a time and provides
+rubout processing within the line, while cooked mode on output might
+translate linefeeds to carriage-return/linefeed pairs. In general, the
+precise meaning of cooked mode is operating-system dependent, and
+furthermore might be customizable by means of operating system
+utilities. The basic idea is that cooked mode does whatever is
+necessary to make the terminal handle all of the usual user-interface
+conventions for the operating system, while keeping the program's
+interaction with the port as normal as possible.
+
+@cindex raw mode, of terminal port
+A terminal port in raw mode disables all of that processing. In raw
+mode, characters are directly read from and written to the device
+without any translation or interpretation by the operating system. On
+input, characters are available as soon as they are typed, and are not
+echoed on the terminal by the operating system. In general, programs
+that put ports in raw mode have to know the details of interacting with
+the terminal. In particular, raw mode is used for writing programs such
+as text editors.
+
+Terminal ports are initially in cooked mode; this can be changed at any
+time with the procedures defined in this section.
+
+These procedures represent cooked mode by the symbol @code{cooked}, and
+raw mode by the symbol @code{raw}. An argument called @var{mode} must
+be one of these symbols. A @var{port} argument to any of these
+procedures may be any port, even if that port does not support terminal
+mode; in that case, the port is not modified in any way.
+
+@deffn {procedure+} port/input-terminal-mode port
+Returns the input terminal mode of @var{port}.
+@end deffn
+
+@deffn {procedure+} port/set-input-terminal-mode port mode
+Changes the input terminal mode of @var{port} to be @var{mode}.
+Returns an unspecified value.
+@end deffn
+
+@deffn {procedure+} port/with-input-terminal-mode port mode thunk
+@var{Thunk} must be a procedure of no arguments.
+@code{port/with-input-terminal-mode}
+binds the input terminal mode of @var{port} to be @var{mode}, executes
+@var{thunk}, restores the input terminal mode of @var{port} to what it
+was when @code{port/with-input-terminal-mode} was called, and returns
+the value that was yielded by @var{thunk}. This binding is performed
+by @code{dynamic-wind}, which guarantees that the input terminal mode is
+restored if @var{thunk} escapes from its continuation.
+@end deffn
+
+@deffn {procedure+} port/output-terminal-mode port
+Returns the output terminal mode of @var{port}.
+@end deffn
+
+@deffn {procedure+} port/set-output-terminal-mode port mode
+Changes the output terminal mode of @var{port} to be @var{mode}.
+Returns an unspecified value.
+@end deffn
+
+@deffn {procedure+} port/with-output-terminal-mode port mode thunk
+@var{Thunk} must be a procedure of no arguments.
+@code{port/with-output-terminal-mode}
+binds the output terminal mode of @var{port} to be @var{mode}, executes
+@var{thunk}, restores the output terminal mode of @var{port} to what it
+was when @code{port/with-output-terminal-mode} was called, and returns
+the value that was yielded by @var{thunk}. This binding is performed
+by @code{dynamic-wind}, which guarantees that the output terminal mode is
+restored if @var{thunk} escapes from its continuation.
+@end deffn
-@defop {operation+} input-port read-char input-port
+@node Input Port Operations, Output Port Operations, Terminal Mode, Port Primitives
+@subsection Input Port Operations
+@cindex input port operations
+
+This section describes the standard operations on input ports.
+
+@defop {operation+} {input port} read-char input-port
@cindex character, input from port
Removes the next character available from @var{input-port} and returns
it. If @var{input-port} has no more characters and will never have any
(e.g.@: at the end of an input file), this operation returns an
end-of-file object. If @var{input-port} has no more characters but will
-eventually have some more (e.g.@: a terminal where nothing has been typed
-recently), and it is in non-blocking mode, @code{#f} is returned;
+eventually have some more (e.g.@: a terminal where nothing has been
+typed recently), and it is in non-blocking mode, @code{#f} is returned;
otherwise the operation hangs until input is available.
@end defop
-@defop {operation+} input-port peek-char input-port
+@defop {operation+} {input port} peek-char input-port
Reads the next character available from @var{input-port} and returns it.
The character is @emph{not} removed from @var{input-port}, and a
subsequent attempt to read from the port will get that character again.
In other respects this operation behaves like @code{read-char}.
@end defop
-@defop {operation+} input-port discard-char input-port
+@defop {operation+} {input port} discard-char input-port
Discards the next character available from @var{input-port} and returns
an unspecified value. In other respects this operation behaves like
@code{read-char}.
@end defop
-@defop {operation+} input-port char-ready? input-port k
+@defop {operation+} {input port} char-ready? input-port k
@code{char-ready?} returns @code{#t} if at least one character is
available to be read from @var{input-port}. If no characters are
available, the operation waits up to @var{k} milliseconds before
available while it is waiting.
@end defop
-@defop {operation+} input-port read-string input-port char-set
-@defopx {operation+} input-port discard-chars input-port char-set
+@defop {operation+} {input port} read-string input-port char-set
+@defopx {operation+} {input port} discard-chars input-port char-set
@cindex string, input from port
These operations are like @code{read-char} and @code{discard-char},
except that they read or discard multiple characters at once. This can
@end example
@end deffn
-@node Output Port Primitives, , Input Port Primitives, Port Primitives
-@subsection Output Port Primitives
-@cindex output port primitives
-
-@deffn {procedure+} make-output-port operations object
-@cindex construction, of output port
-Operations must be a list; each element is a list of two elements, the
-name of the operation and the procedure that implements it. A new
-output port is returned with the given operations and a state component
-of @var{object}. @var{Operations} need not contain definitions for all
-of the standard operations. @code{make-output-port} will provide
-defaults for any standard operations that are not defined. At a
-minimum, the operation @code{write-char} must be defined.
-@end deffn
-
-@deffn {procedure+} output-port/copy output-port object
-@cindex copying, of output port
-Returns a new copy of @var{output-port}, identical to the original except
-that its state component is @var{object}. @var{Output-port} is not
-modified.
-
-@code{output-port/copy} is normally used to speed up creation of output
-ports. This is done by creating a template using
-@code{make-output-port}; a dummy state component is supplied for the
-template. Then @code{output-port/copy} is used to make a copy of the
-template, supplying the copy with the correct state. This is useful
-because @code{make-output-port} is somewhat slow, as it must parse the
-@var{operations} list, provide defaulting for missing operations, etc.
-@end deffn
-
-@deffn {procedure+} output-port/state output-port
-Returns the state component of @var{output-port}.
-@end deffn
-
-@deffn {procedure+} set-output-port/state! output-port object
-Changes the state component of @var{output-port} to be @var{object}.
-Returns an unspecified value.
-@end deffn
-
-@deffn {procedure+} output-port/operation output-port name
-Returns the procedure that implements the operation called @var{name},
-or @code{#f} if @var{output-port} has no such operation.
-@end deffn
-
-@deffn {procedure+} output-port/custom-operation output-port name
-Returns the procedure that implements the custom operation called
-@var{name}. If @var{name} names a standard operation, or if
-@var{output-port} has no such custom operation, @code{#f} is returned.
-This is faster than @code{output-port/operation} if @var{name} is known
-to be the name of a custom operation.
-@end deffn
+@node Output Port Operations, , Input Port Operations, Port Primitives
+@subsection Output Port Operations
+@cindex output port operations
-The following are the standard operations on output ports.
+This section describes the standard operations on output ports.
+Following that, some useful custom operations are described.
-@defop {operation+} output-port write-char output-port char
+@defop {operation+} {output port} write-char output-port char
@cindex character, output to port
Writes @var{char} to @var{output-port} and returns an unspecified value.
@end defop
-@defop {operation+} output-port write-string output-port string
+@defop {operation+} {output port} write-substring output-port string start end
+@cindex substring, output to port
+Writes the substring specified by @var{string}, @var{start}, and
+@var{end} to @var{output-port} and returns an unspecified value.
+Equivalent to writing the characters of the substring, one by one, to
+@var{output-port}, but is often implemented more efficiently.
+@end defop
+
+@defop {operation+} {output port} write-string output-port string
@cindex string, output to port
Writes @var{string} to @var{output-port} and returns an unspecified
-value. Equivalent to writing the characters of @var{string}, one by
-one, to @var{output-port}, but is often implemented more efficiently.
+value.
@end defop
-@defop {operation+} output-port flush-output output-port
+@defop {operation+} {output port} flush-output output-port
If @var{output-port} is buffered, this causes its buffer to be written
out. Otherwise it has no effect. Returns an unspecified value.
@end defop
+@defop {operation+} {output port} discretionary-flush-output output-port
+If @var{output-port} is buffered, this causes its buffer to be written
+out. Otherwise it has no effect. Returns an unspecified value.
+
+This operation, if defined, is normally identical to
+@code{flush-output}. However, it is not normally defined, and even when
+it is, it is invoked at different times (@pxref{Output Procedures}).
+@end defop
+
@deffn {procedure+} output-port/operation/write-char output-port
+@deffnx {procedure+} output-port/operation/write-substring output-port
@deffnx {procedure+} output-port/operation/write-string output-port
@deffnx {procedure+} output-port/operation/flush-output output-port
+@deffnx {procedure+} output-port/operation/discretionary-flush-output output-port
Each of these procedures returns the procedure that implements the
respective operation for @var{output-port}. Each is equivalent to, but
faster than, @code{output-port/operation} on the respective operation
@end deffn
@deffn {procedure+} output-port/write-char output-port char
+@deffnx {procedure+} output-port/write-substring output-port string start end
@deffnx {procedure+} output-port/write-string output-port string
@deffnx {procedure+} output-port/flush-output output-port
+@deffnx {procedure+} output-port/discretionary-flush-output output-port
Each of these procedures invokes the respective operation on
@var{output-port}. For example, the following are equivalent:
@end example
@end deffn
-The custom operation @code{x-size} is so useful that we provide a
-procedure to call it:
+The following custom operations are generally useful.
+
+@defop {operation+} {output port} x-size output-port
+Returns an exact positive integer that is the width of @var{output-port}
+in characters. If @var{output-port} has no natural width, e.g.@: if it is
+a file port, @code{#f} is returned.
+@end defop
+
+@defop {operation+} {output port} y-size output-port
+Returns an exact positive integer that is the height of
+@var{output-port} in characters. If @var{output-port} has no natural
+height, e.g.@: if it is a file port, @code{#f} is returned.
+@end defop
@deffn {procedure+} output-port/x-size output-port
This procedure invokes the custom operation whose name is the symbol
exactly that.
@end deffn
-@defop {operation+} output-port x-size output-port
-Returns an exact positive integer that is the width of @var{output-port}
-in characters. If @var{output-port} has no natural width, e.g.@: if it is
-a file port, @code{#f} is returned.
-@end defop
+@deffn {procedure+} output-port/y-size output-port
+This procedure invokes the custom operation whose name is the symbol
+@code{y-size}, if it exists. If the @code{y-size} operation is defined,
+the value it returns is returned as the result of this procedure;
+otherwise, @code{#f} is returned.
+
+@code{output-port/y-size} is useful for programs that tailor their
+output to the height of the display.
+@end deffn
@node File-System Interface, Error System, Input/Output, Top
@chapter File-System Interface
projects / mit-scheme.git / commitdiff