implementation of custom ports and high-performance @acronym{I/O}.
@menu
-* Ports::
-* File Ports::
-* String Ports::
-* Input Procedures::
-* Output Procedures::
-* Format::
-* Custom Output::
-* Prompting::
-* Port Primitives::
-* Parser Buffers::
-* Parser Language::
-* XML Support::
+* Ports::
+* File Ports::
+* String Ports::
+* Bytevector Ports::
+* Input Procedures::
+* Output Procedures::
+* Blocking Mode::
+* Terminal Mode::
+* Format::
+* Custom Output::
+* Prompting::
+* Textual Port Primitives::
+* Parser Buffers::
+* Parser Language::
+* XML Support::
@end menu
@node Ports, File Ports, Input/Output, Input/Output
@section Ports
@cindex port (defn)
-@findex console-i/o-port
-Scheme uses ports for @acronym{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 @acronym{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)
-@cindex port, current
+@cindex input port (defn)
+@cindex output port (defn)
+Ports represent input and output devices. To Scheme, an @dfn{input
+port} is a Scheme object that can deliver data upon command, while an
+@dfn{output port} is a Scheme object that can accept data. Whether
+the input and output port types are disjoint is
+implementation-dependent. (In MIT/GNU Scheme, there are input ports,
+output ports, and input/output ports.)
+
+Different port types operate on different data. Scheme
+implementations are required to support textual ports and binary
+ports, but may also provide other port types.
+
+@cindex textual port (defn)
@findex read-char
-@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 @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 write-char
-@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
-@code{console-i/o-port}, but Scheme provides procedures that let you
-change the current output port to be a file or string.
-
-Nearly all ports read or write Unicode characters; the exceptions are
-those for which non-Unicode character coding has been specified.
-
-Every port is either an input port, an output port, or both. The
-following predicates distinguish all of the possible cases.
+@findex read
+@findex write
+A @dfn{textual port} supports reading or writing of individual
+characters from or to a backing store containing characters using
+@code{read-char} and @code{write-char} below, and it supports
+operations defined in terms of characters, such as @code{read} and
+@code{write}.
+
+@cindex binary port (defn)
+@findex read-u8
+@findex write-u8
+A @dfn{binary port} supports reading or writing of individual bytes
+from or to a backing store containing bytes using @code{read-u8} and
+@code{write-u8} below, as well as operations defined in terms of
+bytes. Whether the textual and binary port types are disjoint is
+implementation-dependent. (In MIT/GNU Scheme, textual ports and
+binary ports are distinct.)
+
+Ports can be used to access files, devices, and similar things on the
+host system on which the Scheme program is running.
+
+@deffn procedure call-with-port port procedure
+It is an error if @var{procedure} does not accept one argument.
+
+The @code{call-with-port} procedure calls @var{procedure} with
+@var{port} as an argument. If @var{procedure} returns, then the port
+is closed automatically and the values yielded by @var{procedure} are
+returned. If @var{procedure} does not return, then the port must not
+be closed automatically unless it is possible to prove that the port
+will never again be used for a read or write operation.
+
+@emph{Rationale}: Because Scheme’s escape procedures have unlimited
+extent, it is possible to escape from the current continuation but
+later to resume it. If implementations were permitted to close the
+port on any escape from the current continuation, then it would be
+impossible to write portable code using both
+@code{call-with-current-continuation} and @code{call-with-port}.
+@end deffn
+
+@deffn procedure call-with-truncated-output-port limit output-port procedure
+The @var{limit} argument must be a nonnegative integer. It is an
+error if @var{procedure} does not accept one argument.
+
+This procedure uses a continuation to escape from @var{procedure} if
+it tries to write more than @var{limit} characters.
+
+It calls @var{procedure} with a special output port as an argument.
+Up to @var{limit} characters may be written to that output port, and
+those characters are transparently written through to
+@var{output-port}.
+
+If the number of characters written to that port exceeds @var{limit},
+then the escape continuation is invoked and @code{#t} is returned.
+Otherwise, @var{procedure} returns normally and @code{#f} is returned.
+
+Note that if @var{procedure} writes exactly @var{limit} characters,
+then the escape continuation is @emph{not} invoked, and @code{#f} is
+returned.
-@deffn procedure port? object
-@cindex type predicate, for port
-Returns @code{#t} if @var{object} is a port, otherwise returns
-@code{#f}.
+In no case does @code{call-with-truncated-output-port} close
+@var{output-port}.
@end deffn
@deffn procedure input-port? object
-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?}.
+@deffnx procedure output-port? object
+@deffnx procedure i/o-port? object
+@deffnx procedure textual-port? object
+@deffnx procedure binary-port? object
+@deffnx procedure port? object
+@cindex type predicate, for port
+These procedures return @code{#t} if @var{object} is an input port,
+output port, input/output port, textual port, binary port, or any kind
+of port, respectively. Otherwise they return @code{#f}.
@end deffn
-@deffn procedure guarantee-port object
-@deffnx procedure guarantee-input-port object
-@deffnx procedure guarantee-output-port object
-@deffnx procedure guarantee-i/o-port object
-These procedures check the type of @var{object}, signalling an error
-of type@* @code{condition-type:wrong-type-argument} if it is not a
-port, input port, output port, or @acronym{I/O} port, respectively.
-Otherwise they return @var{object}.
-@findex condition-type:wrong-type-argument
+@deffn {obsolete procedure} guarantee-port object
+@deffnx {obsolete procedure} guarantee-input-port object
+@deffnx {obsolete procedure} guarantee-output-port object
+@deffnx {obsolete procedure} guarantee-i/o-port object
+@findex guarantee
+These procedures are @strong{deprecated}. Instead use
+@code{guarantee} with the appropriate predicate.
@end deffn
-@cindex standard ports
-The next five procedures return the runtime system's @dfn{standard
-ports}. All of the standard ports are dynamically bound by the
-@acronym{REP} loop; this means that when a new @acronym{REP} loop is
-started, for example by an error, each of these ports is dynamically
-bound to the @acronym{I/O} port of the @acronym{REP} loop. When the
-@acronym{REP} loop exits, the ports revert to their original values.
-
-@deffn parameter current-input-port
-Returns the current input port, which is the default port used by many
-input procedures.
-
-This parameter may be called with an argument to set its value.
+@deffn procedure input-port-open? port
+@deffnx procedure output-port-open? port
+Returns @code{#t} if @var{port} is still open and capable of
+performing input or output, respectively, and @code{#f} otherwise.
@end deffn
-@deffn parameter current-output-port
-Returns the current output port, which is the default port used by
-many output procedures.
-
-This parameter may be called with an argument to set its value.
+@deffn parameter current-input-port [input-port]
+@deffnx parameter current-output-port [output-port]
+@deffnx parameter current-error-port [output-port]
+@cindex current input port (defn)
+@cindex input port, current (defn)
+@cindex current output port (defn)
+@cindex output port, current (defn)
+@cindex current error port (defn)
+@cindex error port, current (defn)
+@cindex port, current
+Returns the current default input port, output port, or error port (an
+output port), respectively. These procedures are parameter objects,
+which can be overridden with @code{parameterize}. The initial
+bindings for these are implementation-defined textual ports.
@end deffn
-@deffn parameter notification-output-port
+@deffn parameter notification-output-port [output-port]
+@cindex current notification port (defn)
+@cindex notification port, current (defn)
Returns an output port suitable for generating ``notifications'', that
is, messages to the user that supply interesting information about the
execution of a program. For example, the @code{load} procedure writes
messages to this port informing the user that a file is being loaded.
-This parameter may be called with an argument to set its value.
+This procedure is a parameter object, which can be overridden with
+@code{parameterize}.
@end deffn
-@deffn parameter trace-output-port
+@deffn parameter trace-output-port [output-port]
+@cindex current tracing output port (defn)
+@cindex tracing output port, current (defn)
Returns an output port suitable for generating ``tracing'' information
about a program's execution. The output generated by the @code{trace}
procedure is sent to this port.
-This parameter may be called with an argument to set its value.
+This procedure is a parameter object, which can be overridden with
+@code{parameterize}.
@end deffn
-@deffn parameter interaction-i/o-port
+@deffn parameter interaction-i/o-port [i/o-port]
+@cindex current interaction port (defn)
+@cindex interaction port, current (defn)
Returns an @acronym{I/O} port suitable for querying or prompting the
user. The standard prompting procedures use this port by default
(@pxref{Prompting}).
-This parameter may be called with an argument to set its value.
-@end deffn
-
-@deffn procedure with-input-from-port input-port thunk
-@deffnx procedure with-output-to-port output-port thunk
-@deffnx procedure with-notification-output-port output-port thunk
-@deffnx procedure with-trace-output-port output-port thunk
-@deffnx procedure with-interaction-i/o-port i/o-port thunk
-These procedures are @strong{deprecated}; instead use
-@code{parameterize} on the corresponding parameters.
-
-@var{Thunk} must be a procedure of no arguments. Each of these
-procedures binds one of the standard ports to its first argument, calls
-@var{thunk} with no arguments, restores the port to its original value,
-and returns the result that was yielded by @var{thunk}. This temporary
-binding is performed the same way as dynamic binding of a variable,
-including the behavior in the presence of continuations (@pxref{Dynamic
-Binding}).
-
-@code{with-input-from-port} binds the current input port,
-@code{with-output-to-port} binds the current output port,
-@code{with-notification-output-port} binds the ``notification'' output
-port, @code{with-trace-output-port} binds the ``trace'' output port,
-and @code{with-interaction-i/o-port} binds the ``interaction''
-@acronym{I/O} port.
+This procedure is a parameter object, which can be overridden with
+@code{parameterize}.
@end deffn
-@deffn procedure set-current-input-port! input-port
-@deffnx procedure set-current-output-port! output-port
-@deffnx procedure set-notification-output-port! output-port
-@deffnx procedure set-trace-output-port! output-port
-@deffnx procedure set-interaction-i/o-port! i/o-port
+@deffn procedure close-port port
+@deffnx procedure close-input-port port
+@deffnx procedure close-output-port port
+@cindex closing, of port
+Closes the resource associated with @var{port}, rendering the port
+incapable of delivering or accepting data. It is an error to apply
+the last two procedures to a port which is not an input or output
+port, respectively. Scheme implementations may provide ports which
+are simultaneously input and output ports, such as sockets; the
+close-input-port and close-output-port procedures can then be used to
+close the input and output sides of the port independently.
+
+These routines have no effect if the port has already been closed.
+@end deffn
+
+@deffn {obsolete procedure} set-current-input-port! input-port
+@deffnx {obsolete procedure} set-current-output-port! output-port
+@deffnx {obsolete procedure} set-notification-output-port! output-port
+@deffnx {obsolete procedure} set-trace-output-port! output-port
+@deffnx {obsolete procedure} set-interaction-i/o-port! i/o-port
These procedures are @strong{deprecated}; instead call the
corresponding parameters with an argument.
+@end deffn
-Each of these procedures alters the binding of one of the standard ports
-and returns an unspecified value. The binding that is modified
-corresponds to the name of the procedure.
+@deffn {obsolete procedure} with-input-from-port input-port thunk
+@deffnx {obsolete procedure} with-output-to-port output-port thunk
+@deffnx {obsolete procedure} with-notification-output-port output-port thunk
+@deffnx {obsolete procedure} with-trace-output-port output-port thunk
+@deffnx {obsolete procedure} with-interaction-i/o-port i/o-port thunk
+@findex parameterize
+These procedures are @strong{deprecated}; instead use
+@code{parameterize} on the corresponding parameters.
@end deffn
@defvr variable console-i/o-port
standard ports defined above. This variable should not be modified.
@end defvr
-@deffn procedure close-port port
-@cindex closing, of port
-Closes @var{port} and returns an unspecified value. If @var{port} is a
-file port, the file is closed.
-@end deffn
-
-@deffn procedure close-input-port port
-Closes @var{port} and returns an unspecified value. @var{Port} must
-be an input port or an @acronym{I/O} port; if it is an @acronym{I/O}
-port, then only the input side of the port is closed.
-@end deffn
-
-@deffn procedure close-output-port port
-Closes @var{port} and returns an unspecified value. @var{Port} must
-be an output port or an @acronym{I/O} port; if it is an @acronym{I/O}
-port, then only the output side of the port is closed.
-@end deffn
-
@node File Ports, String Ports, Ports, Input/Output
@section File Ports
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 one of two modes, @dfn{normal} or
-@dfn{binary}. Normal mode is for accessing text files, and binary
-mode is for accessing other files. Unix does not distinguish these
-modes, but Windows do: in normal mode, their file ports perform
-@dfn{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, such ports do not perform newline translation. Unless otherwise
-mentioned, the procedures in this section open files in normal mode.
+@deffn procedure call-with-input-file filename procedure
+@deffnx procedure call-with-output-file filename procedure
+It is an error if @var{procedure} does not accept one argument.
+
+@findex open-input-file
+@findex open-output-file
+@findex call-with-port
+These procedures obtain a textual port obtained by opening the named
+file for input or output as if by @code{open-input-file} or
+@code{open-output-file}. The port and @var{procedure} are then passed
+to a procedure equivalent to @code{call-with-port}.
+@end deffn
+
+@deffn procedure call-with-binary-input-file filename procedure
+@deffnx procedure call-with-binary-output-file filename procedure
+It is an error if @var{procedure} does not accept one argument.
+
+@findex open-binary-input-file
+@findex open-binary-output-file
+@findex call-with-port
+These procedures obtain a binary port obtained by opening the named
+file for input or output as if by @code{open-binary-input-file} or
+@code{open-binary-output-file}. The port and @var{procedure} are then
+passed to a procedure equivalent to @code{call-with-port}.
+@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
+@findex current-input-port
+@findex current-output-port
+@findex parameterize
+The file named by @var{filename} is opened for input or output as if
+by @code{open-input-file} or @code{open-output-file}, and the new port
+is made to be the value returned by @code{current-input-port} or
+@code{current-output-port} (as used by @code{(read)}, @code{(write
+obj)}, and so forth). The @var{thunk} is then called with no
+arguments. When the @var{thunk} returns, the port is closed and the
+previous default is restored. It is an error if @var{thunk} does not
+accept zero arguments. Both procedures return the values yielded by
+@var{thunk}. If an escape procedure is used to escape from the
+continuation of these procedures, they behave exactly as if the
+current input or output port had been bound dynamically with
+@code{parameterize}.
+@end deffn
+
+@deffn {obsolete procedure} with-input-from-binary-file filename thunk
+@deffnx{obsolete procedure} with-output-to-binary-file filename thunk
+@findex parameterize
+@findex call-with-binary-input-file
+@findex call-with-binary-output-file
+These procedures are @strong{deprecated}; instead use
+@code{parameterize} along with @code{call-with-binary-input-file} or
+@code{call-with-binary-output-file}.
+@end deffn
@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 of type @code{condition-type:file-operation-error} is
-signalled.
+@deffnx procedure open-binary-input-file filename
@findex condition-type:file-operation-error
+Takes a @var{filename} for an existing file and returns a textual
+input port or binary input port that is capable of delivering data
+from the file. If the file does not exist or cannot be opened, an
+error an error of type @code{condition-type:file-operation-error} is
+signaled.
@end deffn
@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 of type
-@code{condition-type:file-operation-error} is signalled.
+@deffnx procedure open-binary-output-file filename [append?]
@findex condition-type:file-operation-error
+Takes a @var{filename} naming an output file to be created and returns
+a textual output port or binary output port that is capable of writing
+data to a new file by that name. If a file with the given name
+already exists, the effect is unspecified. (In that case, MIT/GNU
+Scheme overwrites an existing file.) If the file cannot be opened, an
+error of type @code{condition-type:file-operation-error} is signalled.
@cindex appending, to output file
The optional argument @var{append?} is an MIT/GNU Scheme extension. If
@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
-@acronym{I/O} port capable of both reading and writing the file. If
-the file cannot be opened, an error of type
-@code{condition-type:file-operation-error} is signalled.
+@deffnx procedure open-binary-i/o-file filename
@findex condition-type:file-operation-error
+Takes a @var{filename} referring to an existing file and returns an
+@acronym{I/O} port that is capable of both reading from and writing to
+the file. If the file cannot be opened, an error of type
+@code{condition-type:file-operation-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 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
-These procedures call @var{procedure} with one argument: the port
-obtained by opening the named file for input or output, respectively.
-If the file cannot be opened, an error of type
-@code{condition-type:file-operation-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 unlimited extent, it is possible to escape from the
-current continuation but later to escape back in. If implementations
-were permitted to close the port on any escape from the current
-continuation, then it would be impossible to write portable code using
-both @code{call-with-current-continuation} and
-@code{call-with-input-file} or @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
-@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
-@var{thunk} is called with no arguments. When the @var{thunk} returns,
-the port is closed and the previous default is restored.
-@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/GNU 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
+@node String Ports, Bytevector Ports, File Ports, Input/Output
@section String Ports
@cindex string, input and output ports
@cindex input port, string
@cindex output port, string
@cindex I/O, to strings
-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, which can limit the length of the resulting
-string to a given value.
+This section describes textual input ports that read their input from
+given strings, and textual output ports that accumulate their output
+and return it as a string.
@deffn procedure open-input-string 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}.
+Takes a string and returns a textual input port that delivers
+characters from the string. If the string is modified, the effect is
+unspecified.
+
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
-@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}.
+@deffn procedure open-output-string
+Returns a textual output port that will accumulate characters for
+retrieval by @code{get-output-string}.
+@end deffn
-@example
-(with-input-from-string "(a b c) (d e f)" read) @result{} (a b c)
-@end example
+@deffn procedure get-output-string port
+It is an error if @var{port} was not created with @var{open-output-string}.
-Note: this procedure is equivalent to:
+Returns a string consisting of the characters that have been output to
+the port so far in the order they were output. If the result string
+is modified, the effect is unspecified.
@example
-(with-input-from-port (open-input-string @var{string}) @var{thunk})
+@group
+(parameterize ((current-output-port (open-output-string)))
+ (display "piece")
+ (display " by piece ")
+ (display "by piece.")
+ (newline)
+ (get-output-string (current-output-port)))
+
+ @result{} "piece by piece by piece.\n"
+@end group
@end example
@end deffn
-@deffn procedure open-output-string
-@deffnx procedure get-output-string
-@code{open-output-string} returns a new output port that accumulates in
-a buffer everything that is written to it. The accumulated output can
-subsequently be obtained by calling @code{get-output-string} on the
-port.
-@end deffn
-
@deffn procedure call-with-output-string procedure
-@var{Procedure} is called with one argument, an output port. The value
-yielded by @var{procedure} is ignored. When @var{procedure} returns,
-@code{call-with-output-string} returns the port's accumulated output as
-a newly allocated string. This is equivalent to:
-
+The @var{procedure} is called with one argument, a textual output
+port. The values yielded by @var{procedure} are ignored. When
+@var{procedure} returns, @code{call-with-output-string} returns the
+port's accumulated output as a string. If the result string is
+modified, the effect is unspecified.
+
+This procedure could have been defined as follows:
+@findex open-output-string
+@findex get-output-string
@example
@group
(define (call-with-output-string procedure)
@end example
@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.
-@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.
-
-@example
-@group
-(with-output-to-string
- (lambda ()
- (write 'abc))) @result{} "abc"
-@end group
-@end example
-
-Note: this procedure is equivalent to:
+@deffn procedure call-with-truncated-output-string limit procedure
+Similar to @code{call-with-output-string}, except that the output is
+limited to at most @var{limit} characters. The returned value is a
+pair; the car of the pair is @code{#t} if @var{procedure} attempted to
+write more than @var{limit} characters, and @code{#f} otherwise. The
+cdr of the pair is a newly allocated string containing the accumulated
+output.
+This procedure could have been defined as follows:
+@findex open-output-string
+@findex call-with-truncated-output-port
@example
@group
-(call-with-output-string
- (lambda (port)
- (with-output-to-port port @var{thunk})))
+(define (call-with-truncated-output-string limit procedure)
+ (let ((port (open-output-string)))
+ (let ((truncated?
+ (call-with-truncated-output-port limit port
+ procedure)))
+ (cons truncated? (get-output-string port)))))
@end group
@end example
-@end deffn
-
-@deffn procedure with-output-to-truncated-string k thunk
-Similar to @code{with-output-to-string}, except that the output is
-limited to @var{k} characters. If @var{thunk} attempts to write more
-than @var{k} characters, it will be aborted by invoking an escape
-procedure that returns from @code{with-output-to-truncated-string}.
-
-The value of this procedure is a pair; the car of the pair is @code{#t}
-if @var{thunk} attempted to write more than @var{k} characters, and
-@code{#f} otherwise. The cdr of the pair is a newly allocated string
-containing the accumulated output.
This procedure is helpful for displaying circular lists, as shown in this
example:
-
+@findex list
+@findex call-with-truncated-output-string
+@findex write
+@findex set-cdr!
@example
@group
(define inf (list 'inf))
-(with-output-to-truncated-string 40
- (lambda ()
- (write inf))) @result{} (#f . "(inf)")
+(call-with-truncated-output-string 40
+ (lambda (port)
+ (write inf port))) @result{} (#f . "(inf)")
(set-cdr! inf inf)
-(with-output-to-truncated-string 40
- (lambda ()
- (write inf)))
+(call-with-truncated-output-string 40
+ (lambda (port)
+ (write inf port)))
@result{} (#t . "(inf inf inf inf inf inf inf inf inf inf")
@end group
@end example
@end deffn
-@deffn procedure write-to-string object [k]
+@deffn procedure write-to-string object [limit]
Writes @var{object} to a string output port, and returns the resulting
-newly allocated string. If @var{k} is supplied and not @code{#f}, this
-procedure is equivalent to
+string.
+If @var{limit} is supplied and not @code{#f}, then this procedure is
+equivalent to the following and returns a pair instead of just a string:
+@findex call-with-truncated-output-string
+@findex write
@example
@group
-(with-output-to-truncated-string @var{k}
- (lambda ()
- (write @var{object})))
+(call-with-truncated-output-string limit
+ (lambda (port)
+ (write object port)))
@end group
@end example
+@end deffn
-otherwise it is equivalent to
+@deffn {obsolete procedure} with-input-from-string string thunk
+@deffnx {obsolete procedure} with-output-to-string thunk
+@deffnx {obsolete procedure} with-output-to-truncated-string limit thunk
+These procedures are @strong{deprecated}; instead use
+@code{open-input-string}, @code{call-with-output-string}, or
+@code{call-with-truncated-output-string} along with
+@code{parameterize}.
+@end deffn
+
+@node Bytevector Ports, Input Procedures, String Ports, Input/Output
+@section Bytevector Ports
+@cindex bytevector, input and output ports
+@cindex port, bytevector
+@cindex input port, bytevector
+@cindex output port, bytevector
+@cindex I/O, to bytevectors
+This section describes binary input ports that read their input from
+given bytevectors, and binary output ports that accumulate their
+output and return it as a bytevector.
+
+@deffn procedure open-input-bytevector bytevector [start [end]]
+Takes a bytevector and returns a binary input port that delivers
+bytes from the bytevector. If the bytevector is modified, the effect is
+unspecified.
+
+The optional arguments @var{start} and @var{end} may be used to
+specify that the bytevector port delivers bytes from a portion of
+@var{bytevector}; if not given, @var{start} defaults to @code{0} and
+@var{end} defaults to @code{(bytevector-length @var{bytevector})}.
+@end deffn
+
+@deffn procedure open-output-bytevector
+Returns a binary output port that will accumulate bytes for retrieval
+by @code{get-output-bytevector}.
+@end deffn
+
+@deffn procedure get-output-bytevector port
+It is an error if @var{port} was not created with @var{open-output-bytevector}.
+
+Returns a bytevector consisting of the bytes that have been output to
+the port so far in the order they were output. If the result bytevector
+is modified, the effect is unspecified.
+@end deffn
+
+@deffn procedure call-with-output-bytevector procedure
+The @var{procedure} is called with one argument, a binary output port.
+The values yielded by @var{procedure} are ignored. When
+@var{procedure} returns, @code{call-with-output-bytevector} returns
+the port's accumulated output as a newly allocated bytevector.
+
+This procedure could have been defined as follows:
+@findex open-output-bytevector
+@findex get-output-bytevector
@example
@group
-(with-output-to-string
- (lambda ()
- (write @var{object})))
+(define (call-with-output-bytevector procedure)
+ (let ((port (open-output-bytevector)))
+ (procedure port)
+ (get-output-bytevector port)))
@end group
@end example
@end deffn
-@node Input Procedures, Output Procedures, String Ports, Input/Output
+@node Input Procedures, Output Procedures, Bytevector Ports, Input/Output
@section Input Procedures
@cindex input operations
environment and assigning new parameters to them.
@defvr parameter param:parser-radix
+@defvrx {obsolete variable} *parser-radix*
This parameter defines the radix used by the reader when it parses
numbers. This is similar to passing a radix argument to
@code{string->number}. The value of the parameter must be one of
The default value of this parameter is @code{10}.
@end defvr
-@defvr variable *parser-radix*
-This variable is @strong{deprecated}; use @code{param:parser-radix}
-instead.
-@end defvr
-
@defvr parameter param:parser-canonicalize-symbols?
+@defvrx {obsolete variable} *parser-canonicalize-symbols?*
This parameter controls how the parser handles case-sensitivity of
symbols. If it is bound to its default value of @code{#t}, symbols read
by the parser are converted to lower case before being interned.
Scheme runtime that depend on case-insensitive symbols.
@end defvr
-@defvr variable *parser-canonicalize-symbols?*
-This variable is @strong{deprecated}; use
-@code{param:parser-canonicalize-symbols?} instead.
-@end defvr
-
-@node Output Procedures, Format, Input Procedures, Input/Output
+@node Output Procedures, Blocking Mode, Input Procedures, Input/Output
@section Output Procedures
@cindex output procedures
of the @code{write} and @code{display} procedures.
@defvr parameter param:unparser-radix
+@defvrx {obsolete variable} *unparser-radix*
This parameter specifies the default radix used to print numbers. Its
value must be one of the exact integers @code{2}, @code{8}, @code{10},
or @code{16}; the default is @code{10}. For values other than
@code{10}, numbers are prefixed to indicate their radix.
@end defvr
-@defvr variable *unparser-radix*
-This variable is @strong{deprecated}; use @code{param:unparser-radix}
-instead.
-@end defvr
-
@defvr parameter param:unparser-list-breadth-limit
+@defvrx {obsolete variable} *unparser-list-breadth-limit*
This parameter specifies a limit on the length of the printed
representation of a list or vector; for example, if the limit is
@code{4}, only the first four elements of any list are printed, followed
@end example
@end defvr
-@defvr variable *unparser-list-breadth-limit*
-This variable is @strong{deprecated}; use
-@code{param:unparser-list-breadth-limit} instead.
-@end defvr
-
@defvr parameter param:unparser-list-depth-limit
+@defvrx {obsolete variable} *unparser-list-depth-limit*
This parameter specifies a limit on the nesting of lists and vectors in
the printed representation. If lists (or vectors) are more deeply
nested than the limit, the part of the representation that exceeds the
@end example
@end defvr
-@defvr variable *unparser-list-depth-limit*
-This variable is @strong{deprecated}; use
-@code{param:unparser-list-depth-limit} instead.
-@end defvr
-
@defvr parameter param:unparser-string-length-limit
+@defvrx {obsolete variable} *unparser-string-length-limit*
This parameter specifies a limit on the length of the printed
representation of strings. If a string's length exceeds this limit, the
part of the printed representation for the characters exceeding the
@end example
@end defvr
-@defvr variable *unparser-string-length-limit*
-This variable is @strong{deprecated}; use
-@code{param:unparser-string-length-limit} instead.
-@end defvr
-
@defvr parameter param:unparse-with-maximum-readability?
+@defvrx {obsolete variable} *unparse-with-maximum-readability?*
This parameter, which takes a boolean value, tells the printer to use a
special printed representation for objects that normally print in a form
that cannot be recognized by @code{read}. These objects are printed
these hash numbers are different for each invocation of Scheme.
@end defvr
-@defvr variable *unparse-with-maximum-readability?*
-This variable is @strong{deprecated}; use
-@code{param:unparse-with-maximum-readability?} instead.
-@end defvr
+@node Blocking Mode, Terminal Mode, Output Procedures, Input/Output
+@section 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 independently of the other. Furthermore, if it is
+an interactive @acronym{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.
-@node Format, Custom Output, Output Procedures, Input/Output
+@deffn procedure input-port-blocking-mode input-port
+@deffnx {obsolete procedure} port/input-blocking-mode input-port
+Returns the input blocking mode of @var{input-port}, or @code{#f} if
+@var{input-port} doesn't support blocking mode.
+@end deffn
+
+@deffn procedure set-input-port-blocking-mode! input-port mode
+@deffnx {obsolete procedure} port/set-input-blocking-mode input-port mode
+Changes the input blocking mode of @var{input-port} to be @var{mode}.
+Returns an unspecified value.
+@end deffn
+
+@deffn procedure with-input-port-blocking-mode input-port mode thunk
+@deffnx {obsolete procedure} port/with-input-blocking-mode input-port mode thunk
+@var{Thunk} must be a procedure of no arguments.
+@code{with-input-port-blocking-mode} binds the input blocking mode of
+@var{input-port} to be @var{mode}, executes @var{thunk}, restores the
+input blocking mode of @var{input-port} to what it was when
+@code{with-input-port-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 output-port-blocking-mode output-port
+@deffnx {obsolete procedure} port/output-blocking-mode output-port
+Returns the output blocking mode of @var{output-port}, or @code{#f} if
+@var{output-port} doesn't support blocking mode.
+@end deffn
+
+@deffn procedure set-output-port-blocking-mode output-port mode
+@deffnx {obsolete procedure} port/set-output-blocking-mode output-port mode
+Changes the output blocking mode of @var{output-port} to be
+@var{mode}. Returns an unspecified value.
+@end deffn
+
+@deffn procedure with-output-port-blocking-mode output-port mode thunk
+@deffnx {obsolete procedure} port/with-output-blocking-mode output-port mode @
+ thunk
+@var{Thunk} must be a procedure of no arguments.
+@code{with-output-port-blocking-mode} binds the output blocking mode
+of @var{output-port} to be @var{mode}, executes @var{thunk}, restores
+the output blocking mode of @var{output-port} to what it was when
+@code{with-output-port-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, Format, Blocking Mode, Input/Output
+@section 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 independently of
+the other. Furthermore, a terminal @acronym{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
+editing 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}. Additionally, the value
+@code{#f} represents ``no mode''; it is the terminal mode of a port
+that is not a terminal. An argument called @var{mode} must be one of
+these three values. A 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 input-port-terminal-mode input-port
+@deffnx {obsolete procedure} port/input-terminal-mode input-port
+Returns the input terminal mode of @var{input-port}, or @code{#f} if
+@var{input-port} is not a terminal port.
+@end deffn
+
+@deffn procedure set-input-port-terminal-mode! input-port mode
+@deffnx {obsolete procedure} port/set-input-terminal-mode input-port mode
+Changes the input terminal mode of @var{input-port} to be @var{mode}.
+Returns an unspecified value.
+@end deffn
+
+@deffn procedure with-input-port-terminal-mode input-port mode thunk
+@deffnx {obsolete procedure} port/with-input-terminal-mode input-port mode thunk
+@var{Thunk} must be a procedure of no arguments.
+@code{with-input-port-terminal-mode} binds the input terminal mode of
+@var{port} to be @var{mode}, executes @var{thunk}, restores the input
+terminal mode of @var{input-port} to what it was when
+@code{with-input-port-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 output-port-terminal-mode output-port
+@deffnx {obsolete procedure} port/output-terminal-mode output-port
+Returns the output terminal mode of @var{output-port}, or @code{#f} if
+@var{output-port} is not a terminal port.
+@end deffn
+
+@deffn procedure set-output-port-terminal-mode! output-port mode
+@deffnx {obsolete procedure} port/set-output-terminal-mode output-port mode
+Changes the output terminal mode of @var{output-port} to be @var{mode}.
+Returns an unspecified value.
+@end deffn
+
+@deffn procedure with-output-port-terminal-mode output-port mode thunk
+@deffnx {obsolete procedure} port/with-output-terminal-mode output-port mode @
+ thunk
+@var{Thunk} must be a procedure of no arguments.
+@code{with-output-port-terminal-mode} binds the output terminal mode
+of @var{output-port} to be @var{mode}, executes @var{thunk}, restores
+the output terminal mode of @var{output-port} to what it was when
+@code{with-output-port-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
+
+@node Format, Custom Output, Terminal Mode, Input/Output
@section Format
@comment **** begin CLTL ****
dynamic extent of @var{procedure}.
@end deffn
-@node Prompting, Port Primitives, Custom Output, Input/Output
+@node Prompting, Textual Port Primitives, Custom Output, Input/Output
@section Prompting
@cindex prompting
Under Edwin or Emacs, the confirmation is read in the minibuffer.
@end deffn
-@node Port Primitives, Parser Buffers, Prompting, Input/Output
-@section Port Primitives
-@cindex port primitives
+@node Textual Port Primitives, Parser Buffers, Prompting, Input/Output
+@section Textual Port Primitives
+@cindex textual port primitives
This section describes the low-level operations that can be used to
-build and manipulate @acronym{I/O} ports.
-
-The purpose of these operations is twofold: to allow programmers to
-construct new kinds of @acronym{I/O} ports, and to provide faster
-@acronym{I/O} operations than those supplied by the standard high
-level procedures. The latter is useful because the standard
-@acronym{I/O} operations provide defaulting and error checking, and
-sometimes other features, which are often unnecessary. This interface
-provides the means to bypass such features, thus improving
-performance.
-
-The abstract model of an @acronym{I/O} port, as implemented here, is a
-combination of a set of named operations and a state. The state is an
-arbitrary object, the meaning of which is determined by the
-operations. The operations are defined by a mapping from names to
+build and manipulate textual @acronym{I/O} ports. The purpose of
+these operations is to allow programmers to construct new kinds of
+textual @acronym{I/O} ports.
+
+The mechanisms described in this section are exclusively for textual
+ports; binary ports can't be customized. In this section, any
+reference to a ``port'' that isn't modified by ``textual'' or
+``binary'' is assumed to be a textual port.
+
+The abstract model of a textual @acronym{I/O} port, as implemented
+here, is a combination of a set of named operations and a state. The
+state is an arbitrary object, the meaning of which is determined by
+the operations. The operations are defined by a mapping from names to
procedures.
-@cindex port type
+@cindex textual port type
The set of named operations is represented by an object called a
-@dfn{port type}. A port type is constructed from a set of named
+@dfn{textual port type}. A port type is constructed from a set of named
operations, and is subsequently used to construct a port. The port type
completely specifies the behavior of the port. Port types also support
a simple form of inheritance, allowing you to create new ports that are
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
+@cindex standard operations, on textual port
@item Custom operations
Some ports support additional operations. For example, ports that
Because only some ports will implement these operations, programs that
use custom operations must test each port for their existence, and be
prepared to deal with ports that do not implement them.
-@cindex custom operations, on port
+@cindex custom operations, on textual port
@findex y-size
@end table
@menu
-* Port Types::
-* Constructors and Accessors for Ports::
-* Input Port Operations::
-* Output Port Operations::
-* Blocking Mode::
-* Terminal Mode::
+* Textual Port Types::
+* Constructors and Accessors for Textual Ports::
+* Textual Input Port Operations::
+* Textual Output Port Operations::
@end menu
-@node Port Types, Constructors and Accessors for Ports, Port Primitives, Port Primitives
-@subsection Port Types
+@node Textual Port Types, Constructors and Accessors for Textual Ports, Textual Port Primitives, Textual Port Primitives
+@subsection Textual Port Types
The procedures in this section provide means for constructing port types
with standard and custom operations, and accessing their operations.
-@deffn procedure make-port-type operations port-type
-@cindex construction, of port type
+@deffn procedure make-textual-port-type operations port-type
+@deffnx {obsolete procedure} make-port-type operations port-type
+@cindex construction, of textual port type
Creates and returns a new port type.
@var{Operations} must be a list; each element is a list of two elements,
the name of the operation (a symbol) and the procedure that implements
standard operations without having to enumerate them.
@end deffn
-@deffn procedure port-type? object
-@deffnx procedure input-port-type? object
-@deffnx procedure output-port-type? object
-@deffnx procedure i/o-port-type? object
+@deffn procedure textual-port-type? object
+@deffnx {obsolete procedure} port-type? object
+@deffnx procedure textual-input-port-type? object
+@deffnx {obsolete procedure} input-port-type? object
+@deffnx procedure textual-output-port-type? object
+@deffnx {obsolete procedure} output-port-type? object
+@deffnx procedure textual-i/o-port-type? object
+@deffnx {obsolete procedure} i/o-port-type? object
These predicates return @code{#t} if @var{object} is a port type,
input-port type, output-port type, or @acronym{I/O}-port type,
respectively. Otherwise, they return @code{#f}.
@end deffn
-@deffn procedure port-type/operations port-type
-Returns a newly allocated list containing all of the operations
-implemented by @var{port-type}. Each element of the list is a list of
-two elements --- the name and its associated operation.
-@end deffn
-
-@deffn procedure port-type/operation-names port-type
-Returns a newly allocated list whose elements are the names of the
-operations implemented by @var{port-type}.
-@end deffn
-
-@deffn procedure port-type/operation port-type symbol
-Returns the operation named @var{symbol} in @var{port-type}. If
-@var{port-type} has no such operation, returns @code{#f}.
+@deffn {obsolete procedure} port-type/operations port-type
+@deffnx {obsolete procedure} port-type/operation-names port-type
+@deffnx {obsolete procedure} port-type/operation port-type symbol
+These procedures are @strong{deprecated} and will be removed in the
+near future. There are no replacements planned.
@end deffn
-@node Constructors and Accessors for Ports, Input Port Operations, Port Types, Port Primitives
-@subsection Constructors and Accessors for Ports
+@node Constructors and Accessors for Textual Ports, Textual Input Port Operations, Textual Port Types, Textual Port Primitives
+@subsection Constructors and Accessors for Textual Ports
The procedures in this section provide means for constructing ports,
accessing the type of a port, and manipulating the state of a port.
-@deffn procedure make-port port-type state
+@deffn procedure make-textual-port port-type state
+@deffnx {obsolete procedure} make-port port-type state
Returns a new port with type @var{port-type} and the given
@var{state}. The port will be an input, output, or @acronym{I/O} port
according to @var{port-type}.
@end deffn
-@deffn procedure port/type port
-Returns the port type of @var{port}.
+@deffn procedure textual-port-type textual-port
+@deffnx {obsolete procedure} port/type textual-port
+Returns the port type of @var{textual-port}.
@end deffn
-@deffn procedure port/state port
-Returns the state component of @var{port}.
+@deffn procedure textual-port-state textual-port
+@deffnx {obsolete procedure} port/state textual-port
+Returns the state component of @var{textual-port}.
@end deffn
-@deffn procedure set-port/state! port object
-Changes the state component of @var{port} to be @var{object}.
+@deffn procedure set-textual-port-state! textual-port object
+@deffnx {obsolete procedure} set-port/state! textual-port object
+Changes the state component of @var{textual-port} to be @var{object}.
Returns an unspecified value.
@end deffn
-@deffn procedure port/operation port symbol
-Equivalent to
-
-@example
-(port-type/operation (port/type @var{port}) @var{symbol})
-@end example
+@deffn procedure textual-port-operation textual-port symbol
+@deffnx {obsolete procedure} port/operation textual-port symbol
+Returns the operation named @var{symbol} for @var{textual-port}. If
+@var{textual-port} has no such operation, returns @code{#f}.
@end deffn
-@deffn procedure port/operation-names port
-Equivalent to
-
-@example
-(port-type/operation-names (port/type @var{port}))
-@end example
+@deffn procedure textual-port-operation-names textual-port
+@deffnx {obsolete procedure} port/operation-names port
+Returns a newly allocated list whose elements are the names of the
+operations implemented by @var{textual-port}.
@end deffn
@deffn procedure make-eof-object input-port
is sometimes useful when building input ports.
@end deffn
-@node Input Port Operations, Output Port Operations, Constructors and Accessors for Ports, Port Primitives
-@subsection Input Port Operations
-@cindex input port operations
+@node Textual Input Port Operations, Textual Output Port Operations, Constructors and Accessors for Textual Ports, Textual Port Primitives
+@subsection Textual Input Port Operations
+@cindex textual input port operations
-This section describes the standard operations on input ports.
+This section describes the standard operations on textual input ports.
Following that, some useful custom operations are described.
-@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;
-otherwise the operation hangs until input is available.
+@defop operation {textual input port} read-char port
+@cindex character, input from textual port
+Removes the next character available from @var{port} and returns it.
+If @var{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{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; otherwise the
+operation hangs until input is available.
@end defop
-@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}.
+@defop operation {textual input port} peek-char port
+Reads the next character available from @var{port} and returns it.
+The character is @emph{not} removed from @var{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} char-ready? input-port k
+@defop operation {textual input port} char-ready? 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
-returning @code{#f}, returning immediately if any characters become
-available while it is waiting.
+available to be read from @var{port}. If no characters are available,
+the operation waits up to @var{k} milliseconds before returning
+@code{#f}, returning immediately if any characters become 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
-@cindex string, input from port
+@defop operation {textual input port} read-string port char-set
+@defopx operation {textual input port} discard-chars port char-set
+@cindex string, input from textual port
These operations are like @code{read-char}, except that they read or
discard multiple characters at once. All characters up to, but
excluding, the first character in @var{char-set} (or end of file) are
-read from @var{input-port}. @code{read-string} returns these characters
-as a newly allocated string, while @code{discard-chars} discards them
-and returns an unspecified value. These operations hang until
-sufficient input is available, even if @var{input-port} is in
-non-blocking mode. If end of file is encountered before any input
-characters, @code{read-string} returns an end-of-file object.
+read from @var{port}. @code{read-string} returns these characters as
+a newly allocated string, while @code{discard-chars} discards them and
+returns an unspecified value. These operations hang until sufficient
+input is available, even if @var{port} is in non-blocking mode. If
+end of file is encountered before any input characters,
+@code{read-string} returns an end-of-file object.
@end defop
-@defop operation {input port} read-substring input-port string start end
-Reads characters from @var{input-port} into the substring defined by
-@var{string}, @var{start}, and @var{end} until either the substring has
-been filled or there are no more characters available. Returns the
-number of characters written to the substring.
+@defop operation {textual input port} read-substring port string start end
+Reads characters from @var{port} into the substring defined by
+@var{string}, @var{start}, and @var{end} until either the substring
+has been filled or there are no more characters available. Returns
+the number of characters written to the substring.
-If @var{input-port} is an interactive port, and at least one character
-is immediately available, the available characters are written to the
-substring and this operation returns immediately. If no characters are
-available, and @var{input-port} is in blocking mode, the operation
+If @var{port} is an interactive port, and at least one character is
+immediately available, the available characters are written to the
+substring and this operation returns immediately. If no characters
+are available, and @var{port} is in blocking mode, the operation
blocks until at least one character is available. Otherwise, the
operation returns @code{#f} immediately.
This is an extremely fast way to read characters from a port.
@end defop
-@deffn procedure input-port/read-char input-port
-@deffnx procedure input-port/peek-char input-port
-@deffnx procedure input-port/char-ready? input-port k
-@deffnx procedure input-port/read-string input-port char-set
-@deffnx procedure input-port/discard-chars input-port char-set
-@deffnx procedure input-port/read-substring input-port string start end
+@deffn procedure input-port/read-char textual-input-port
+@deffnx procedure input-port/peek-char textual-input-port
+@deffnx procedure input-port/char-ready? textual-input-port k
+@deffnx procedure input-port/read-string textual-input-port char-set
+@deffnx procedure input-port/discard-chars textual-input-port char-set
+@deffnx procedure input-port/read-substring textual-input-port string start end
Each of these procedures invokes the respective operation on
-@var{input-port}. For example, the following are equivalent:
+@var{textual-input-port}. For example, the following are equivalent:
@example
@group
-(input-port/read-char @var{input-port})
-((port/operation @var{input-port} 'read-char) @var{input-port})
+(input-port/read-char @var{textual-input-port})
+((textual-port-operation @var{textual-input-port} 'read-char)
+ @var{textual-input-port})
@end group
@end example
@end deffn
The following custom operations are implemented for input ports to
files, and will also work with some other kinds of input ports:
-@defop operation {input port} eof? input-port
-Returns @code{#t} if @var{input-port} is known to be at end of file,
+@defop operation {textual input port} eof? port
+Returns @code{#t} if @var{port} is known to be at end of file,
otherwise it returns @code{#f}.
@end defop
-@defop operation {input port} chars-remaining input-port
+@defop operation {textual input port} chars-remaining port
Returns an estimate of the number of characters remaining to be read
-from @var{input-port}. This is useful only when @var{input-port} is a
-file port in binary mode; in other cases, it returns @code{#f}.
+from @var{port}. This is useful only when
+@var{port} is a file port in binary mode; in other
+cases, it returns @code{#f}.
@end defop
-@defop operation {input port} buffered-input-chars input-port
+@defop operation {textual input port} buffered-input-chars port
Returns the number of unread characters that are stored in
-@var{input-port}'s buffer. This will always be less than or equal to
+@var{port}'s buffer. This will always be less than or equal to
the buffer's size.
@end defop
-@defop operation {input port} input-buffer-size input-port
-Returns the maximum number of characters that @var{input-port}'s buffer
+@defop operation {textual input port} input-buffer-size port
+Returns the maximum number of characters that @var{port}'s buffer
can hold.
@end defop
-@defop operation {input port} set-input-buffer-size input-port size
-Resizes @var{input-port}'s buffer so that it can hold at most @var{size}
+@defop operation {textual input port} set-input-buffer-size port size
+Resizes @var{port}'s buffer so that it can hold at most @var{size}
characters. Characters in the buffer are discarded. @var{Size} must be
an exact non-negative integer.
@end defop
-@node Output Port Operations, Blocking Mode, Input Port Operations, Port Primitives
-@subsection Output Port Operations
-@cindex output port operations
+@node Textual Output Port Operations, , Textual Input Port Operations, Textual Port Primitives
+@subsection Textual Output Port Operations
+@cindex textual output port operations
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
-@cindex character, output to port
-Writes @var{char} to @var{output-port} and returns an unspecified value.
+@defop operation {textual output port} write-char port char
+@cindex character, output to textual port
+Writes @var{char} to @var{port} and returns an unspecified value.
@end defop
-@defop operation {output port} write-substring output-port string start end
-@cindex substring, output to port
+@defop operation {textual output port} write-substring port string start end
+@cindex substring, output to textual 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 implemented very efficiently.
+@var{end} to @var{port} and returns an unspecified value. Equivalent
+to writing the characters of the substring, one by one, to @var{port},
+but is implemented very efficiently.
@end defop
-@defop operation {output port} fresh-line output-port
+@defop operation {textual output port} fresh-line port
Most output ports are able to tell whether or not they are at the
-beginning of a line of output. If @var{output-port} is such a port,
+beginning of a line of output. If @var{port} is such a port,
end-of-line is written 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, an
+the beginning of a line. If @var{port} is not such a port, an
end-of-line is unconditionally written to the port. Returns an
unspecified value.
@end defop
-@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.
+@defop operation {textual output port} flush-output port
+If @var{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
+@defop operation {textual output port} discretionary-flush-output port
Normally, this operation does nothing. However, ports that support
-discretionary output flushing implement this operation identically to @code{flush-output}.
+discretionary output flushing implement this operation identically to
+@code{flush-output}.
@end defop
-@deffn procedure output-port/write-char output-port char
-@deffnx procedure output-port/write-substring output-port string start end
-@deffnx procedure output-port/fresh-line output-port
-@deffnx procedure output-port/flush-output output-port
-@deffnx procedure output-port/discretionary-flush-output output-port
+@deffn procedure output-port/write-char textual-output-port char
+@deffnx procedure output-port/write-substring textual-output-port string @
+ start end
+@deffnx procedure output-port/fresh-line textual-output-port
+@deffnx procedure output-port/flush-output textual-output-port
+@deffnx procedure output-port/discretionary-flush-output textual-output-port
Each of these procedures invokes the respective operation on
-@var{output-port}. For example, the following are equivalent:
+@var{textual-output-port}. For example, the following are equivalent:
@example
@group
-(output-port/write-char @var{output-port} @var{char})
-((port/operation @var{output-port} 'write-char)
- @var{output-port} @var{char})
+(output-port/write-char @var{textual-output-port} @var{char})
+((textual-port-operation @var{textual-output-port} 'write-char)
+ @var{textual-output-port} @var{char})
@end group
@end example
@end deffn
-@deffn procedure output-port/write-string output-port string
-Writes @var{string} to @var{output-port}. Equivalent to
+@deffn procedure output-port/write-string textual-output-port string
+Writes @var{string} to @var{textual-output-port}. Equivalent to
@example
@group
-(output-port/write-substring @var{output-port}
+(output-port/write-substring @var{textual-output-port}
@var{string}
0
(string-length @var{string}))
The following custom operations are generally useful.
-@defop operation {output port} buffered-output-chars output-port
+@defop operation {textual output port} buffered-output-chars port
Returns the number of unwritten characters that are stored in
-@var{output-port}'s buffer. This will always be less than or equal to
-the buffer's size.
+@var{port}'s buffer. This will always be less than or equal to the
+buffer's size.
@end defop
-@defop operation {output port} output-buffer-size output-port
-Returns the maximum number of characters that @var{output-port}'s buffer
-can hold.
+@defop operation {textual output port} output-buffer-size port
+Returns the maximum number of characters that @var{port}'s buffer can
+hold.
@end defop
-@defop operation {output port} set-output-buffer-size output-port size
-Resizes @var{output-port}'s buffer so that it can hold at most @var{size}
-characters. Characters in the buffer are discarded. @var{Size} must be
-an exact non-negative integer.
+@defop operation {textual output port} set-output-buffer-size port size
+Resizes @var{port}'s buffer so that it can hold at most @var{size}
+characters. Characters in the buffer are discarded. @var{Size} must
+be an exact non-negative integer.
@end defop
-@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.
+@defop operation {textual output port} x-size port
+Returns an exact positive integer that is the width of @var{port} in
+characters. If @var{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.
+@defop operation {textual output port} y-size port
+Returns an exact positive integer that is the height of @var{port} in
+characters. If @var{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
+@deffn procedure output-port/x-size textual-output-port
This procedure invokes the custom operation whose name is the symbol
@code{x-size}, if it exists. If the @code{x-size} operation is both
defined and returns a value other than @code{#f}, that value is returned
exactly that.
@end deffn
-@deffn procedure output-port/y-size output-port
+@deffn procedure output-port/y-size textual-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.
@end deffn
-@node Blocking Mode, Terminal Mode, Output Port Operations, 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 @acronym{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, , 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 @acronym{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}. Additionally, the value @code{#f}
-represents ``no mode''; it is the terminal mode of a port that is not a
-terminal. An argument called @var{mode} must be one of these three
-values. 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
-
-@node Parser Buffers, Parser Language, Port Primitives, Input/Output
+@node Parser Buffers, Parser Language, Textual Port Primitives, Input/Output
@section Parser Buffers
@cindex Parser buffer
There are several constructors for parser buffers:
-@deffn procedure input-port->parser-buffer port
-Returns a parser buffer that buffers characters read from @var{port}.
+@deffn procedure textual-input-port->parser-buffer textual-input-port
+@deffnx {obsolete procedure} input-port->parser-buffer textual-input-port
+Returns a parser buffer that buffers characters read from
+@var{textual-input-port}.
@end deffn
@deffn procedure substring->parser-buffer string start end
Returns a parser buffer that buffers the characters in the argument
substring. This is equivalent to creating a string input port and
-calling @code{input-port->parser-buffer}, but it runs faster and uses
-less memory.
+calling @code{textual-input-port->parser-buffer}, but it runs faster
+and uses less memory.
@end deffn
@deffn procedure string->parser-buffer string
@deffn procedure match-parser-buffer-substring buffer string start end
@deffnx procedure match-parser-buffer-substring-ci buffer string start end
-@deffnx procedure match-parser-buffer-substring-no-advance buffer string start end
-@deffnx procedure match-parser-buffer-substring-ci-no-advance buffer string start end
+@deffnx procedure match-parser-buffer-substring-no-advance buffer string @
+ start end
+@deffnx procedure match-parser-buffer-substring-ci-no-advance buffer string @
+ start end
These procedures match the specified substring against @var{buffer}'s
contents. The @samp{-ci} procedures do case-insensitive matching.
@end deffn
once before compiling any code that uses the language.
@menu
-* *Matcher::
-* *Parser::
-* Parser-language Macros::
+* *Matcher::
+* *Parser::
+* Parser-language Macros::
@end menu
@node *Matcher, *Parser, Parser Language, Parser Language
once before running any code that uses it.
@menu
-* XML Input::
-* XML Output::
-* XML Names::
-* XML Structure::
+* XML Input::
+* XML Output::
+* XML Names::
+* XML Structure::
@end menu
projects / mit-scheme.git / commitdiff