d0b405ac8b
- added invoke-library
syntax.ss, primdata.ss,
8.ms, root-experr*,
libraries.stex, release_notes.stex
- updated the date
release_notes.stex
- libraries contained within a whole program or library are now
marked pending before their invoke code is run so that invoke
cycles are reported as such rather than as attempts to invoke
while still loading.
compile.ss, syntax.ss, primdata.ss,
7.ms, root-experr*
- the library manager now protects against unbound references
from separately compiled libraries or programs to identifiers
ostensibly but not actually exported by (invisible) libraries
that exist only locally within a whole program. this is done by
marking the invisibility of the library in the library-info and
propagating it to libdesc records; the latter is checked upon
library import, visit, and invoke as well as by verify-loadability.
the import and visit code of each invisible no longer complains
about invisibility since it shouldn't be reachable.
syntax.ss, compile.ss, expand-lang.ss,
7.ms, 8.ms, root-experr*, patch*
- documented that compile-whole-xxx's linearization of the
library initialization code based on static dependencies might
not work for dynamic dependencies.
system.stex
- optimized bignum right shifts so the code (1) doesn't look at
shifted-off bigits if the bignum is positive, since it doesn't
need to know in that case if any bits are set; (2) doesn't look
at shifted-off bigits if the bignum is negative if it determines
that at least one bit is set in the bits shifted off the low-order
partially retained bigit; (3) quits looking, if it must look, for
one bits as soon as it finds one; (4) looks from both ends under
the assumption that set bits, if any, are most likely to be found
toward the high or low end of the bignum rather than just in the
middle; and (5) doesn't copy the retained bigits and then shift;
rather shifts as it copies. This leads to dramatic improvements
when the shift count is large and often significant improvements
otherwise.
number.c,
5_3.ms,
release_notes.stex
- threaded tc argument through to all calls to S_bignum and
S_trunc_rem so they don't have to call get_thread_context()
when it might already have been called.
alloc.c, number.c, fasl.c, print.c, prim5.c, externs.h
- added an expand-primitive handler to partially inline integer?.
cpnanopass.ss
- added some special cases for basic arithmetic operations (+, -, *,
/, quotient, remainder, and the div/div0/mod/mod0 operations) to
avoid doing unnecessary work for large bignums when the result
will be zero (e.g,. multiplying by 0), the same as one of the
inputs (e.g., adding 0 or multiplying by 1), or the additive
inverse of one of the inputs (e.g., subtracting from 0, dividing
by -1). This can have a major beneficial affect when operating
on large bignums in the cases handled. also converted some uses
of / into integer/ where going through the former would just add
overhead without the possibility of optimization.
5_3.ss,
number.c, externs.h, prim5.c,
5_3.ms, root-experr, patch*,
release_notes.stex
- added a queue to hold pending signals for which handlers have
been registered via register-signal-handler so up to 63 (configurable
in the source code) unhandled signals are buffered before the
handler has to start dropping them.
cmacros.ss, library.ss, prims.ss, primdata.ss,
schsig.c, externs.h, prim5.c, thread.c, gc.c,
unix.ms,
system.stex, release_notes.stex
- bytevector-compress now selects the level of compression based
on the compress-level parameter. Prior to this it always used a
default setting for compression. the compress-level parameter
can now take on the new minimum in addition to low, medium, high,
and maximum. minimum is presently treated the same as low
except in the case of lz4 bytevector compression, where it
results in the use of LZ4_compress_default rather than the
slower but more effective LZ4_compress_HC.
cmacros,ss, back.ss,
compress_io.c, new_io.c, externs.h,
bytevector.ms, mats/Mf-base, root-experr*
io.stex, objects.stex, release_notes.stex
original commit: 72d90e4c67849908da900d0b6249a1dedb5f8c7f
4305 lines
174 KiB
Plaintext
4305 lines
174 KiB
Plaintext
% Copyright 2005-2018 Cisco Systems, Inc.
|
|
%
|
|
% Licensed under the Apache License, Version 2.0 (the "License");
|
|
% you may not use this file except in compliance with the License.
|
|
% You may obtain a copy of the License at
|
|
%
|
|
% http://www.apache.org/licenses/LICENSE-2.0
|
|
%
|
|
% Unless required by applicable law or agreed to in writing, software
|
|
% distributed under the License is distributed on an "AS IS" BASIS,
|
|
% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
% See the License for the specific language governing permissions and
|
|
% limitations under the License.
|
|
\chapter{Input/Output Operations\label{CHPTIO}}
|
|
|
|
This chapter describes {\ChezScheme}'s generic port facility,
|
|
operations on ports, and various {\ChezScheme} extensions to the
|
|
standard set of input/output operations.
|
|
See Chapter~\ref{TSPL:CHPTIO} of {\TSPLFOUR} or the Revised$^6$ Report
|
|
on Scheme for a description of standard input/output operations.
|
|
Definitions of a few sample generic ports are given in
|
|
Section~\ref{SECTPORTEXAMPLES}.
|
|
|
|
{\ChezScheme} closes file ports automatically after they become
|
|
inaccessible to the program or when the Scheme program exits, but it is
|
|
best to close ports explicitly whenever possible.
|
|
|
|
|
|
\section{Generic Ports}
|
|
|
|
{\ChezScheme}'s ``\index{generic port}generic port'' facility
|
|
allows the programmer to add new types of textual ports with
|
|
arbitrary input/output semantics.
|
|
It may be used, for example, to define any of the built-in
|
|
Common Lisp~\cite{Steele:common} stream types, i.e.,
|
|
\index{synonym streams}synonym streams,
|
|
\index{broadcast streams}broadcast streams,
|
|
\index{concatenated streams}concatenated streams,
|
|
\index{two-way streams}two-way streams,
|
|
\index{echo streams}echo streams, and
|
|
\index{string streams}string streams.
|
|
It may also be used to define more exotic ports, such as ports that
|
|
represent windows on a bit-mapped display or ports that represent
|
|
processes connected to the current process via pipes or sockets.
|
|
|
|
Each port has an associated \emph{port handler}.
|
|
A port handler is a procedure that accepts messages in an
|
|
object-oriented style.
|
|
Each message corresponds to one of the low-level Scheme operations
|
|
on ports, such as \scheme{read-char} and \scheme{close-input-port} (but not
|
|
\scheme{read}, which is defined in terms of the lower-level operations).
|
|
Most of these operations simply call the handler immediately with
|
|
the corresponding message.
|
|
|
|
Standard messages adhere to the following conventions: the message name is
|
|
the first argument to the handler.
|
|
It is always a symbol, and it is always the name of a primitive
|
|
Scheme operation on ports.
|
|
The additional arguments are the same as the arguments to the
|
|
primitive procedure and occur in the same order.
|
|
(The port argument to some of the primitive procedures is optional;
|
|
in the case of the messages passed to a handler, the port argument
|
|
is always supplied.)
|
|
The following messages are defined for built-in ports:
|
|
|
|
\schemedisplay
|
|
block-read \var{port} \var{string} \var{count}
|
|
block-write \var{port} \var{string} \var{count}
|
|
char-ready? \var{port}
|
|
clear-input-port \var{port}
|
|
clear-output-port \var{port}
|
|
close-port \var{port}
|
|
file-position \var{port}
|
|
file-position \var{port} \var{position}
|
|
file-length \var{port}
|
|
flush-output-port \var{port}
|
|
peek-char \var{port}
|
|
port-name \var{port}
|
|
read-char \var{port}
|
|
unread-char \var{char} \var{port}
|
|
write-char \var{char} \var{port}
|
|
\endschemedisplay
|
|
|
|
\noindent
|
|
Additional messages may be accepted by user-defined ports.
|
|
|
|
{\ChezScheme} input and output is normally buffered for efficiency.
|
|
To support buffering, each input port contains an input buffer and
|
|
each output port contains an output buffer.
|
|
Bidirectional ports, ports that are both input ports and output
|
|
ports, contain both input and output buffers.
|
|
Input is not buffered if the input buffer is the empty string,
|
|
and output is not buffered if the output buffer is the empty
|
|
string.
|
|
In the case of unbuffered input and output, calls to \scheme{read-char},
|
|
\scheme{write-char}, and similar messages cause the handler to be invoked
|
|
immediately with the corresponding message.
|
|
For buffered input and output, calls to these procedures cause the
|
|
buffer to be updated, and the handler is not called under normal
|
|
circumstances until the buffer becomes empty (for input) or full (for
|
|
output).
|
|
Handlers for buffered ports must \var{not} count
|
|
on the buffer being empty or full when \scheme{read-char}, \scheme{write-char}, and
|
|
similar messages are received, however, due to the possibility that (a)
|
|
the handler is invoked through some other mechanism, or (b) the
|
|
call to the handler is interrupted.
|
|
|
|
In the presence of keyboard, timer, and other interrupts, it is
|
|
possible for a call to a port handler to be interrupted or for the
|
|
handler itself to be interrupted.
|
|
If the port is accessible outside of the interrupted code, there
|
|
is a possibility that the interrupt handler will cause input or
|
|
output to be performed on the port.
|
|
This is one reason, as stated above, that port handlers must not count
|
|
on the input buffer being empty or output buffer being full when a
|
|
\scheme{read-char}, \scheme{write-char}, or similar message is received.
|
|
In addition, port handlers may need to manipulate the buffers only
|
|
with interrupts disabled (using \scheme{with-interrupts-disabled}).
|
|
|
|
Generic ports are created via one of the port construction
|
|
procedures \scheme{make-input-port},
|
|
\scheme{make-output-port}, and \scheme{make-input/output-port} defined
|
|
later in this chapter.
|
|
Ports have seven accessible fields:
|
|
|
|
\begin{description}
|
|
\item[\var{handler},] accessed with \scheme{port-handler};
|
|
\item[\var{output-buffer},] accessed with \scheme{port-output-buffer},
|
|
\item[\var{output-size},] accessed with \scheme{port-output-size},
|
|
\item[\var{output-index},] accessed with \scheme{port-output-index},
|
|
\item[\var{input-buffer},] accessed with \scheme{port-input-buffer},
|
|
\item[\var{input-size},] accessed with \scheme{port-input-size}, and
|
|
\item[\var{input-index},] accessed with \scheme{port-input-index}.
|
|
\end{description}
|
|
|
|
\noindent
|
|
The output-size and output-index fields are valid only for output
|
|
ports, and the input-size and input-index fields are valid only for
|
|
input ports.
|
|
The output and input size and index fields may be updated as well
|
|
using the corresponding ``\scheme{set-\var{field}!}'' procedure.
|
|
|
|
A port's output size determines how much of the port's output buffer is
|
|
actually available for writing by \scheme{write-char}.
|
|
The output size is often the same as the string length of the port's
|
|
output buffer, but it can be set to less (but no less than zero) at the
|
|
discretion of the programmer.
|
|
The output index determines to which position in the port's
|
|
buffer the next character will be written.
|
|
The output index should be between $0$ and the output size,
|
|
inclusive.
|
|
If no output has occurred since the buffer was last flushed, the
|
|
output index should be $0$.
|
|
If the index is less than the size, \scheme{write-char}
|
|
stores its character argument into the specified character
|
|
position within the buffer and increments the index.
|
|
If the index is equal to the size, \scheme{write-char} leaves the fields of
|
|
the port unchanged and invokes the handler.
|
|
|
|
A port's input size determines how much of the port's input buffer is
|
|
actually available for reading by \scheme{read-char}.
|
|
A port's input size and input index are constrained in the same manner
|
|
as output size and index, i.e., the input size must be between
|
|
$0$ and the string length of the input buffer (inclusive), and the input
|
|
index must be between $0$ and the input size (inclusive).
|
|
Often, the input size is less than the length of the input buffer
|
|
because there are fewer characters available to read than would fit
|
|
in the buffer.
|
|
The input index determines from which position in the input buffer the
|
|
next character will be read.
|
|
If the index is less than the size, \scheme{read-char} extracts the character
|
|
in this position, increments the index, and returns the character.
|
|
If the index is equal to the size, \scheme{read-char} leaves the fields of
|
|
the port unchanged and invokes the handler.
|
|
|
|
The operation of \scheme{peek-char} is similar to that of \scheme{read-char}, except
|
|
that it does not increment the input index.
|
|
\scheme{unread-char} decrements the input index if it is greater than $0$,
|
|
otherwise it invokes the handler.
|
|
\scheme{char-ready?} returns \scheme{#t} if the input index is less than the input
|
|
size, otherwise it invokes the handler.
|
|
|
|
Although the fields shown and discussed above are logically present in
|
|
a port, actual implementation details may differ.
|
|
The current {\ChezScheme} implementation uses a different representation
|
|
that allows \scheme{read-char}, \scheme{write-char}, and similar operations to be
|
|
open-coded with minimal overhead.
|
|
The access and assignment operators perform the conversion between the
|
|
actual representation and the one shown above.
|
|
|
|
Port handlers receiving a message must return a value appropriate for
|
|
the corresponding operation.
|
|
For example, a handler receiving a \scheme{read-char} message must return a
|
|
character or eof object (if it returns).
|
|
For operations that return unspecified values, such as \scheme{close-port},
|
|
the handler is not required to return any particular value.
|
|
|
|
\section{File Options\label{SECTFILEOPTIONS}}
|
|
|
|
The Revised$^6$ Report requires that the universe of a file-options
|
|
enumeration set must include \scheme{no-create}, \scheme{no-fail},
|
|
and \scheme{no-truncate}, whose meanings are described within the
|
|
description of the \scheme{file-options} syntax in
|
|
Section~\ref{TSPL:SECTOPENINGFILES} of {\TSPLFOUR}.
|
|
{\ChezScheme} defines a number of additional file options:
|
|
|
|
\begin{description}
|
|
\item[\var{compressed}:]
|
|
An output file should be compressed when written; and a compressed input
|
|
file should be decompressed when read. The compression format for output
|
|
is determined by the \index{\scheme{compress-format}}\scheme{compress-format}
|
|
parameter, while the compression format on input is inferred.
|
|
The compression level, which is relevant only for output, is determined
|
|
by the \index{\scheme{compress-level}}\scheme{compress-level} parameter.
|
|
|
|
\item[\var{replace}:]
|
|
For output files only, replace (remove and recreate) the existing file if
|
|
it exists.
|
|
|
|
\item[\var{exclusive}:]
|
|
For output files only, lock the file for exclusive access.
|
|
On some systems the lock is advisory, i.e., it inhibits access by
|
|
other processes only if they also attempt to open exclusively.
|
|
|
|
\item[\var{append}:]
|
|
For output files only, position the output port at the end of the file
|
|
before each write so that output to the port is always appended to the
|
|
file.
|
|
|
|
\item[\var{perm-set-user-id}:]
|
|
For newly created output files under Unix-based systems only, set
|
|
user-id bit.
|
|
|
|
\item[\var{perm-set-group-id}:]
|
|
For newly created output files under Unix-based systems only, set
|
|
group-id bit.
|
|
|
|
\item[\var{perm-sticky}:]
|
|
For newly created output files under Unix-based systems only, set
|
|
sticky bit.
|
|
|
|
\item[\var{perm-no-user-read}:]
|
|
For newly created output files under Unix-based systems only,
|
|
do not set user read bit.
|
|
(User read bit is set by default, unless masked by the process umask.)
|
|
|
|
\item[\var{perm-no-user-write}:]
|
|
For newly created output files under Unix-based systems only,
|
|
do not set user write bit.
|
|
(User write bit is set by default, unless masked by the process umask.)
|
|
|
|
\item[\var{perm-user-execute}:]
|
|
For newly created output files under Unix-based systems only,
|
|
set user execute bit unless masked by process umask.
|
|
(User execute bit is not set by default.)
|
|
|
|
\item[\var{perm-no-group-read}:]
|
|
For newly created output files under Unix-based systems only,
|
|
do not set group read bit.
|
|
(Group read bit is set by default, unless masked by the process umask.)
|
|
|
|
\item[\var{perm-no-group-write}:]
|
|
For newly created output files under Unix-based systems only,
|
|
do not set group write bit.
|
|
(Group write bit is set by default, unless masked by the process umask.)
|
|
|
|
\item[\var{perm-group-execute}:]
|
|
For newly created output files under Unix-based systems only,
|
|
set group execute bit unless masked by process umask.
|
|
(Group execute bit is not set by default.)
|
|
|
|
\item[\var{perm-no-other-read}:]
|
|
For newly created output files under Unix-based systems only,
|
|
do not set other read bit.
|
|
(Other read bit is set by default, unless masked by the process umask.)
|
|
|
|
\item[\var{perm-no-other-write}:]
|
|
For newly created output files under Unix-based systems only,
|
|
do not set other write bit.
|
|
(Other write bit is set by default, unless masked by the process umask.)
|
|
|
|
\item[\var{perm-other-execute}:]
|
|
For newly created output files under Unix-based systems only,
|
|
set other execute bit unless masked by process umask.
|
|
(Other execute bit is not set by default.)
|
|
\end{description}
|
|
|
|
\section{Transcoders\label{SECTTRANSCODERS}}
|
|
|
|
The language of the Revised$^6$ Report provides three built-in codecs:
|
|
a latin-1 codec, a utf-8 codec, and a utf-16 codec.
|
|
{\ChezScheme} provides three additional codecs: a utf-16le codec,
|
|
utf-16be codec, and an ``iconv'' codec for non-Unicode character sets.
|
|
It also provides an alternative to the standard utf-16 codec that
|
|
defaults to little-endian format rather than the default big-endian
|
|
format.
|
|
This section describes these codecs, plus a \scheme{current-transcoder}
|
|
parameter that allows the programmer to determine the transcoder
|
|
used for a textual port whenever the transcoder is implicit, as for
|
|
\scheme{open-input-file} or \scheme{load}, along with the
|
|
predicate \scheme{transcoder?}, which should be standard but is not.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{utf-16-codec}{\categoryprocedure}{(utf-16-codec)}
|
|
\formdef{utf-16-codec}{\categoryprocedure}{(utf-16-codec \var{endianness})}
|
|
\formdef{utf-16le-codec}{\categoryprocedure}{(utf-16le-codec)}
|
|
\formdef{utf-16be-codec}{\categoryprocedure}{(utf-16be-codec)}
|
|
\returns a codec
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\var{endianness} must be the symbol \scheme{big} or the symbol
|
|
\scheme{little}.
|
|
|
|
The codec returned by \scheme{utf-16-codec} can be used to create and
|
|
process data written UTF-16 format.
|
|
When called without the \var{endianness} argument or with \var{endianness}
|
|
\scheme{big}, \scheme{utf-16-codec} returns a codec for standard UTF-16
|
|
data, i.e., one that defaults to big-endian format if no byte-order mark
|
|
(BOM) is found.
|
|
|
|
When output is transcoded with a transcoder based on this codec, a BOM is
|
|
emitted just before the first character written, and each character is
|
|
written as a UTF-16 character in big-endian format.
|
|
For input, a BOM is looked for at the start of the
|
|
input and, if present, controls the byte order of the remaining
|
|
UTF-16 characters.
|
|
If no BOM is present, big-endian order is assumed.
|
|
For input-output ports, the BOM is not emitted if the file is
|
|
read before written, and a BOM is not looked for if the file is written
|
|
before read.
|
|
|
|
For textual ports created via \scheme{transcoded-port}, a BOM written or
|
|
read via the transcoder appears at the beginning of the underlying data
|
|
stream or file only if the binary port passed to \scheme{transcoded-port}
|
|
is positioned at the start of the data stream or file.
|
|
When the transcoder can determine this is the case, it sets a flag that
|
|
causes \scheme{set-port-position!}) to position the port beyond the BOM if
|
|
an attempt is made to reposition the port to the start of the data stream
|
|
or file, so that the BOM is preserved.
|
|
|
|
When called with \var{endianness} \scheme{little}, \scheme{utf-16-codec}
|
|
returns a codec that defaults to the little-endian format both for reading
|
|
and for writing.
|
|
For output-only streams or input/output streams that are written before read,
|
|
the result is standard UTF-16, with a BOM that specifies little-endian
|
|
format followed by characters in little-endian byte order.
|
|
For input-only streams or input/output streams that are read before written,
|
|
this codec allows programs to read from input streams that either
|
|
begin with a BOM or are encoded in UTF-16LE format.
|
|
This is particularly useful for handling files that might have been
|
|
produced by older Windows applications that claim to produce UTF-16 files
|
|
but actually produce UTF-16LE files.
|
|
|
|
The Revised$^6$ Report version of \scheme{utf-16-codec} lacks the
|
|
optional \var{endianness} argument.
|
|
|
|
The codecs returned by \scheme{utf-16le-codec} and \scheme{utf-16be-codec}
|
|
are used to read and write data in the UTF-16LE and UTF-16BE formats,
|
|
i.e., UTF-16 with little-endian or big-endian byte order and no BOM.
|
|
For output, these codecs are useful for controlling whether and where
|
|
the BOM is emitted, since no BOM is emitted implicitly and a BOM
|
|
can be emitted explicitly as an ordinary character.
|
|
For input, these codecs are useful for processing files known to be
|
|
in little-endian or big-endian format with no BOM.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{iconv-codec}{\categoryprocedure}{(iconv-codec \var{code-page})}
|
|
\returns a codec
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\var{code-page} must be a string and should identify a codec accepted by
|
|
the \scheme{iconv} library installed on the target machine.
|
|
The codec returned by this procedure can be used to convert from the
|
|
non-Unicode single- and multiple-byte character sets supported by
|
|
\scheme{iconv}.
|
|
When used in the input direction, the codec converts byte sequences
|
|
into Scheme strings, and when used in the output direction, it converts
|
|
Scheme strings to byte sequences.
|
|
|
|
The set of supported code pages depends on the version of
|
|
\scheme{iconv} available; consult the \scheme{iconv} documentation
|
|
or use the shell command \scheme{iconv --list} to obtain a list
|
|
of supported code pages.
|
|
|
|
While the Windows operating system does not supply an \scheme{iconv}
|
|
library, it is possible to use \scheme{iconv-codec} on Windows systems by
|
|
supplying an \scheme{iconv} dynamic-link library (named \scheme{iconv.dll},
|
|
\scheme{libiconv.dll}, or \scheme{libiconv-2.dll}) that provides
|
|
Posix-conformant \scheme{iconv_open}, \scheme{iconv}, and
|
|
\scheme{iconv_close} entry points either under those names or under the
|
|
alternative names \scheme{libiconv_open}, \scheme{libiconv}, and
|
|
\scheme{libiconv_close}.
|
|
The dll must be located in a standard location for dlls or in the
|
|
current directory of the process the first time \scheme{iconv-codec}
|
|
is called.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{current-transcoder}{\categorythreadparameter}{current-transcoder}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
The transcoder value of the \scheme{current-transcoder} parameter is used
|
|
whenever a textual file is opened with an implicit transcoder, e.g., by
|
|
\scheme{open-input-file} and other convenience I/O procedures,
|
|
\scheme{compile-file} \scheme{include}, \scheme{load}, and
|
|
\scheme{pretty-file}.
|
|
Its initial value is the value of the \scheme{native-transcoder} procedure.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{transcoder?}{\categoryprocedure}{(transcoder? \var{obj})}
|
|
\returns \scheme{#t} if \var{obj} is a transcoder, \scheme{#f} otherwise
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
|
|
\section{Port Operations\label{SECTPORTOPERATIONS}}
|
|
|
|
The procedures used to create, access, and alter ports directly
|
|
are described in this section.
|
|
Also described are several nonstandard operations on ports.
|
|
|
|
Unless otherwise specified, procedures requiring either input ports or
|
|
output ports as arguments accept input/output ports as well, i.e., an
|
|
input/output port is both an input port and an output port.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{make-input-port}{\categoryprocedure}{(make-input-port \var{handler} \var{input-buffer})}
|
|
\formdef{make-output-port}{\categoryprocedure}{(make-output-port \var{handler} \var{output-buffer})}
|
|
\formdef{make-input/output-port}{\categoryprocedure}{(make-input/output-port \var{handler} \var{input-buffer} \var{output-buffer})}
|
|
\returns a new textual port
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{handler} must be a procedure, and
|
|
\var{input-buffer} and \var{output-buffer} must be strings.
|
|
Each procedure creates a \index{generic port}generic port.
|
|
The handler associated with the port is \var{handler}, the
|
|
input buffer is \var{input-buffer}, and the
|
|
output buffer is \var{output-buffer}.
|
|
For \scheme{make-input-port}, the output buffer is undefined, and for
|
|
\scheme{make-output-port}, the input buffer is undefined.
|
|
|
|
The input size of an input or input/output port is initialized to the
|
|
string length of the input buffer, and the input index is set to $0$.
|
|
The output size and index of an output or input/output port are
|
|
initialized similarly.
|
|
|
|
The length of an input or output buffer may be zero, in which case
|
|
buffering is effectively disabled.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{port-handler}{\categoryprocedure}{(port-handler \var{port})}
|
|
\returns a procedure
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
For generic ports, \scheme{port-handler} returns the handler passed to one
|
|
of the generic port creation procedures described above.
|
|
For ports created by \scheme{open-input-file} and similar procedures,
|
|
\scheme{port-handler} returns an internal handler that may be invoked in
|
|
the same manner as any other handler.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{port-input-buffer}{\categoryprocedure}{(port-input-buffer \var{input-port})}
|
|
\formdef{port-input-size}{\categoryprocedure}{(port-input-size \var{input-port})}
|
|
\formdef{port-input-index}{\categoryprocedure}{(port-input-index \var{input-port})}
|
|
\formdef{textual-port-input-buffer}{\categoryprocedure}{(textual-port-input-buffer \var{textual-input-port})}
|
|
\formdef{textual-port-input-size}{\categoryprocedure}{(textual-port-input-size \var{textual-input-port})}
|
|
\formdef{textual-port-input-index}{\categoryprocedure}{(textual-port-input-index \var{textual-input-port})}
|
|
\formdef{binary-port-input-buffer}{\categoryprocedure}{(binary-port-input-buffer \var{binary-input-port})}
|
|
\formdef{binary-port-input-size}{\categoryprocedure}{(binary-port-input-size \var{binary-input-port})}
|
|
\formdef{binary-port-input-index}{\categoryprocedure}{(binary-port-input-index \var{binary-input-port})}
|
|
\returns see below
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
These procedures return the input buffer, size, or index
|
|
of the input port.
|
|
The variants specialized to textual or binary ports are slightly
|
|
more efficient than their generic counterparts.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{set-port-input-index!}{\categoryprocedure}{(set-port-input-index! \var{input-port} \var{n})}
|
|
\formdef{set-port-input-size!}{\categoryprocedure}{(set-port-input-size! \var{input-port} \var{n})}
|
|
\formdef{set-port-input-buffer!}{\categoryprocedure}{(set-port-input-buffer! \var{input-port} \var{x})}
|
|
\formdef{set-textual-port-input-index!}{\categoryprocedure}{(set-textual-port-input-index! \var{textual-input-port} \var{n})}
|
|
\formdef{set-textual-port-input-size!}{\categoryprocedure}{(set-textual-port-input-size! \var{textual-input-port} \var{n})}
|
|
\formdef{set-textual-port-input-buffer!}{\categoryprocedure}{(set-textual-port-input-buffer! \var{textual-input-port} \var{string})}
|
|
\formdef{set-binary-port-input-index!}{\categoryprocedure}{(set-binary-port-input-index! \var{binary-input-port} \var{n})}
|
|
\formdef{set-binary-port-input-size!}{\categoryprocedure}{(set-binary-port-input-size! \var{binary-input-port} \var{n})}
|
|
\formdef{set-binary-port-input-buffer!}{\categoryprocedure}{(set-binary-port-input-buffer! \var{binary-input-port} \var{bytevector})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
The procedure \scheme{set-port-input-index!} sets the input index field of
|
|
\var{input-port} to $n$, which must be a nonnegative integer less than
|
|
or equal to the port's input size.
|
|
|
|
The procedure \scheme{set-port-input-size!} sets the input size field of
|
|
\var{input-port} to $n$, which must be a nonnegative integer less than
|
|
or equal to the string length of the port's input buffer.
|
|
It also sets the input index to $0$.
|
|
|
|
The procedure \scheme{set-port-input-buffer!} sets the input buffer field of
|
|
\var{input-port} to $x$, which must be a string for textual ports and a
|
|
bytevector for binary ports.
|
|
It also sets the input size to the length of the string or bytevector
|
|
and the input index to $0$.
|
|
|
|
The variants specialized to textual or binary ports are slightly
|
|
more efficient than their generic counterparts.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{port-input-count}{\categoryprocedure}{(port-input-count \var{input-port})}
|
|
\formdef{textual-port-input-count}{\categoryprocedure}{(textual-port-input-count \var{textual-input-port})}
|
|
\formdef{binary-port-input-count}{\categoryprocedure}{(binary-port-input-count \var{binary-input-port})}
|
|
\returns see below
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
These procedures return an exact integer representing the number of
|
|
characters or bytes left to be read from the port's input buffer, i.e.,
|
|
the difference between the buffer size and index.
|
|
|
|
The variants specialized to textual or binary ports are slightly
|
|
more efficient than their generic counterpart.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{port-input-empty?}{\categoryprocedure}{(port-input-empty? \var{input-port})}
|
|
\returns \scheme{#t} if the port's input buffer contains no more data, otherwise \scheme{#f}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
This procedure determines whether the port's input count is zero without
|
|
computing or returning the actual count.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{port-output-buffer}{\categoryprocedure}{(port-output-buffer \var{output-port})}
|
|
\formdef{port-output-size}{\categoryprocedure}{(port-output-size \var{output-port})}
|
|
\formdef{port-output-index}{\categoryprocedure}{(port-output-index \var{output-port})}
|
|
\formdef{textual-port-output-buffer}{\categoryprocedure}{(textual-port-output-buffer \var{output-port})}
|
|
\formdef{textual-port-output-size}{\categoryprocedure}{(textual-port-output-size \var{output-port})}
|
|
\formdef{textual-port-output-index}{\categoryprocedure}{(textual-port-output-index \var{output-port})}
|
|
\formdef{binary-port-output-buffer}{\categoryprocedure}{(binary-port-output-buffer \var{output-port})}
|
|
\formdef{binary-port-output-size}{\categoryprocedure}{(binary-port-output-size \var{output-port})}
|
|
\formdef{binary-port-output-index}{\categoryprocedure}{(binary-port-output-index \var{output-port})}
|
|
\returns see below
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
These procedures return the output buffer, size, or index
|
|
of the output port.
|
|
The variants specialized to textual or binary ports are slightly
|
|
more efficient than their generic counterparts.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{set-port-output-index!}{\categoryprocedure}{(set-port-output-index! \var{output-port} \var{n})}
|
|
\formdef{set-port-output-size!}{\categoryprocedure}{(set-port-output-size! \var{output-port} \var{n})}
|
|
\formdef{set-port-output-buffer!}{\categoryprocedure}{(set-port-output-buffer! \var{output-port} \var{x})}
|
|
\formdef{set-textual-port-output-index!}{\categoryprocedure}{(set-textual-port-output-index! \var{textual-output-port} \var{n})}
|
|
\formdef{set-textual-port-output-size!}{\categoryprocedure}{(set-textual-port-output-size! \var{textual-output-port} \var{n})}
|
|
\formdef{set-textual-port-output-buffer!}{\categoryprocedure}{(set-textual-port-output-buffer! \var{textual-output-port} \var{string})}
|
|
\formdef{set-binary-port-output-index!}{\categoryprocedure}{(set-binary-port-output-index! \var{output-port} \var{n})}
|
|
\formdef{set-binary-port-output-size!}{\categoryprocedure}{(set-binary-port-output-size! \var{output-port} \var{n})}
|
|
\formdef{set-binary-port-output-buffer!}{\categoryprocedure}{(set-binary-port-output-buffer! \var{binary-output-port} \var{bytevector})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
The procedure \scheme{set-port-output-index!} sets the output index field of
|
|
the output port to $n$, which must be a nonnegative integer less than
|
|
or equal to the port's output size.
|
|
|
|
The procedure \scheme{set-port-output-size!} sets the output size field of
|
|
the output port to $n$, which must be a nonnegative integer less than
|
|
or equal to the string length of the port's output buffer.
|
|
It also sets the output index to $0$.
|
|
|
|
The procedure \scheme{set-port-output-buffer!} sets the output buffer field of
|
|
\var{output-port} to $x$, which must be a string for textual ports and a
|
|
bytevector for binary ports.
|
|
It also sets the output size to the length of the string or bytevector
|
|
and the output index to $0$.
|
|
|
|
The variants specialized to textual or binary ports are slightly
|
|
more efficient than their generic counterparts.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{port-output-count}{\categoryprocedure}{(port-output-count \var{output-port})}
|
|
\formdef{textual-port-output-count}{\categoryprocedure}{(textual-port-output-count \var{textual-output-port})}
|
|
\formdef{binary-port-output-count}{\categoryprocedure}{(binary-port-output-count \var{binary-output-port})}
|
|
\returns see below
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
These procedures return an exact integer representing the amount of
|
|
space in characters or bytes available to be written in the
|
|
port's output buffer, i.e., the difference between the buffer size
|
|
and index.
|
|
|
|
The variants specialized to textual or binary ports are slightly
|
|
more efficient than their generic counterpart.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{port-output-full?}{\categoryprocedure}{(port-output-full? \var{output-port})}
|
|
\returns \scheme{#t} if the port's input buffer has no more room, otherwise \scheme{#f}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
This procedure determines whether the port's output count is zero without
|
|
computing or returning the actual count.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{mark-port-closed!}{\categoryprocedure}{(mark-port-closed! \var{port})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
This procedure directly marks the port closed so that no further
|
|
input or output operations are allowed on it.
|
|
It is typically used by handlers upon receipt of a \scheme{close-port}
|
|
message.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{port-closed?}{\categoryprocedure}{(port-closed? \var{port})}
|
|
\returns \scheme{#t} if \var{port} is closed, \scheme{#f} otherwise
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\schemedisplay
|
|
(let ([p (open-output-string)])
|
|
(port-closed? p)) ;=> #f
|
|
|
|
(let ([p (open-output-string)])
|
|
(close-port p)
|
|
(port-closed? p)) ;=> #t
|
|
\endschemedisplay
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader\label{desc:set-port-bol}
|
|
\formdef{set-port-bol!}{\categoryprocedure}{(set-port-bol! \var{output-port} \var{obj})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
When \var{obj} is \scheme{#f}, the port's beginning-of-line (BOL)
|
|
flag is cleared; otherwise, the port's BOL flag is set.
|
|
|
|
The BOL flag is consulted by \scheme{fresh-line}
|
|
(page~\pageref{desc:fresh-line}) to determine if it needs to emit a
|
|
newline.
|
|
This flag is maintained automatically for file output ports, string output
|
|
ports, and transcript ports.
|
|
The flag is set for newly created file and string output ports, except
|
|
for file output ports created with the \scheme{append} option, for which
|
|
the flag is reset.
|
|
The BOL flag is clear for newly created generic ports and never set
|
|
automatically, but may be set explicitly using \scheme{set-port-bol!}.
|
|
The port is always flushed immediately before the flag is consulted, so it
|
|
need not be maintained on a per-character basis for buffered ports.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{port-bol?}{\categoryprocedure}{(port-bol? \var{port})}
|
|
\returns \scheme{#t} if \var{port}'s BOL flag is set, \scheme{#f} otherwise
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{set-port-eof!}{\categoryprocedure}{(set-port-eof! \var{input-port} \var{obj})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
When \var{obj} is not \scheme{#f}, \scheme{set-port-eof!} marks \var{input-port}
|
|
so that, once its buffer is empty, the port is treated as if it were at
|
|
eof even if more data is available in the underlying byte or character
|
|
stream.
|
|
Once this artificial eof has been read, the eof mark is cleared, making
|
|
any additional data in the stream available beyond the eof.
|
|
This feature can be used by a generic port to simulate a stream consisting
|
|
of multiple input files.
|
|
|
|
When \var{obj} is \scheme{#f}, the eof mark is cleared.
|
|
|
|
The following example assumes /dev/zero provides an infinite stream of
|
|
zero bytes.
|
|
|
|
\schemedisplay
|
|
(define p
|
|
(parameterize ([file-buffer-size 3])
|
|
(open-file-input-port "/dev/zero")))
|
|
(set-port-eof! p #t)
|
|
(get-u8 p) ;=> #!eof
|
|
(get-u8 p) ;=> 0
|
|
(set-port-eof! p #t)
|
|
(get-u8 p) ;=> 0
|
|
(get-u8 p) ;=> 0
|
|
(get-u8 p) ;=> #!eof
|
|
(get-u8 p) ;=> 0
|
|
\endschemedisplay
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{port-name}{\categoryprocedure}{(port-name \var{port})}
|
|
\returns the name associated with \var{port}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
The name may be any object but is usually a string or \scheme{#f}
|
|
(denoting no name).
|
|
For file ports, the name is typically a string naming the file.
|
|
|
|
\schemedisplay
|
|
(let ([p (open-input-file "myfile.ss")])
|
|
(port-name p)) ;=> "myfile.ss"
|
|
|
|
(let ([p (open-output-string)])
|
|
(port-name p)) ;=> "string"
|
|
\endschemedisplay
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{set-port-name!}{\categoryprocedure}{(set-port-name! \var{port} \var{obj})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
This procedure sets \var{port}'s name to \var{obj}, which should be
|
|
a string or \scheme{#f} (denoting no name).
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{port-length}{\categoryprocedure}{(port-length \var{port})}
|
|
\formdef{file-length}{\categoryprocedure}{(file-length \var{port})}
|
|
\returns the length of the file or other object to which \var{port} refers
|
|
\formdef{port-has-port-length?}{\categoryprocedure}{(port-has-port-length? \var{port})}
|
|
\returns \scheme{#t} if the port supports \scheme{port-length}, \scheme{#f} otherwise
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
A port may allow the length of the underlying stream of characters or bytes
|
|
to be determined.
|
|
If so, the procedure \scheme{port-has-port-length?} returns
|
|
\scheme{#t} and \scheme{port-length} returns the current length.
|
|
For binary ports, the length is always an exact nonnegative integer byte
|
|
count.
|
|
For textual ports, the representation of a length is unspecified; it
|
|
may not be an exact nonnegative integer and, even if it is, it may not
|
|
represent either a byte or character count.
|
|
The length may be used at some later time to reset the length if the
|
|
port supports \scheme{set-port-length!}.
|
|
If \scheme{port-length} is called on a port that does not support it,
|
|
an exception with condition type \scheme{&assertion} is raised.
|
|
|
|
File lengths beyond $2^{32}$ might not be reported property
|
|
for compressed files on 32-bit versions of the system.
|
|
|
|
\scheme{file-length} is identical to \scheme{port-length}.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{set-port-length!}{\categoryprocedure}{(set-port-length! \var{port} \var{len})}
|
|
\returns unspecified
|
|
\formdef{port-has-set-port-length!?}{\categoryprocedure}{(port-has-set-port-length!? \var{port})}
|
|
\returns \scheme{#t} if the port supports \scheme{set-port-length!}, \scheme{#f} otherwise
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
A port may allow the length of the underlying stream of characters or bytes
|
|
to be set, i.e., extended or truncated.
|
|
If so, the procedure \scheme{port-has-set-port-length!?} returns
|
|
\scheme{#t} and \scheme{set-port-length!} changes the length.
|
|
For binary ports, the length \var{len} must be an exact nonnegative integer byte
|
|
count.
|
|
For textual ports, the representation of a length is unspecified, as
|
|
described in the entry for \scheme{port-length} above, but \var{len} must be
|
|
an appropriate length for the textual port, which is usually guaranteed
|
|
to be the case only if it was obtained from a call to \scheme{port-length}
|
|
on the same port.
|
|
If \scheme{set-port-length!} is called on a port that does not support it,
|
|
an exception with condition type \scheme{&assertion} is raised.
|
|
|
|
It is not possible to set the length of a port opened with compression
|
|
to an arbitrary position, and the result of an attempt to set the length
|
|
of a compressed file beyond $2^{32}$ on 32-bit versions of the system is
|
|
undefined.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{port-nonblocking?}{\categoryprocedure}{(port-nonblocking? \var{port})}
|
|
\returns \scheme{#t} if the port is in nonblocking mode, \scheme{#f} otherwise
|
|
\formdef{port-has-port-nonblocking??}{\categoryprocedure}{(port-has-port-nonblocking?? \var{port})}
|
|
\returns \scheme{#t} if the port supports \scheme{port-nonblocking?}, \scheme{#f} otherwise
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
A port may allow the nonblocking status of the port to be determined.
|
|
If so, the procedure \scheme{port-has-port-nonblocking??} returns
|
|
\scheme{#t} and \scheme{port-nonblocking?} returns a boolean value
|
|
reflecting whether the port is in nonblocking mode.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{set-port-nonblocking!}{\categoryprocedure}{(set-port-nonblocking! \var{port} \var{obj})}
|
|
\returns unspecified
|
|
\formdef{port-has-set-port-nonblocking!?}{\categoryprocedure}{(port-has-set-port-nonblocking!? \var{port})}
|
|
\returns \scheme{#t} if the port supports \scheme{set-port-nonblocking!}, \scheme{#f} otherwise
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
A port may allow reads or writes to be performed in a ``nonblocking'' fashion.
|
|
If so, the procedure \scheme{port-has-set-port-nonblocking!?} returns
|
|
\scheme{#t} and \scheme{set-port-nonblocking!} sets the port to nonblocking
|
|
mode (if \var{obj} is a true value) or blocking mode (if \var{obj} is \scheme{#f}).
|
|
If \scheme{set-port-nonblocking!} is called on a port that does not support it,
|
|
an exception with condition type \scheme{&assertion} is raised.
|
|
|
|
Ports created by the standard Revised$^6$ port opening procedures are
|
|
initially set in blocking mode by default.
|
|
The same is true for most of the procedures described in this document.
|
|
A generic port based on a nonblocking source may be nonblocking
|
|
initially.
|
|
A port returned by \scheme{open-fd-input-port},
|
|
\scheme{open-fd-output-port}, or \scheme{open-fd-input/output-port}
|
|
is initially in nonblocking mode if the file-descriptor passed in is in
|
|
nonblocking mode.
|
|
Similarly, a port returned by \scheme{standard-input-port},
|
|
\scheme{standard-output-port}, or \scheme{standard-error-port} is
|
|
initially in nonblocking mode if the underlying stdin, stdout,
|
|
or stderr file descriptor is in nonblocking mode.
|
|
|
|
Although \scheme{get-bytevector-some} and \scheme{get-string-some} normally
|
|
cannot return an empty bytevector or empty string, they can if the port
|
|
is in nonblocking mode and no input is available.
|
|
Also, \scheme{get-bytevector-some!} and \scheme{get-string-some!}
|
|
may not read any data if the port is in nonblocking mode and
|
|
no data is available.
|
|
Similarly, \scheme{put-bytevector-some} and \scheme{put-string-some}
|
|
may not write any data if the port is in nonblocking mode and
|
|
no room is available.
|
|
|
|
Nonblocking mode is not supported under Windows.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{file-position}{\categoryprocedure}{(file-position \var{port})}
|
|
\formdef{file-position}{\categoryprocedure}{(file-position \var{port} \var{pos})}
|
|
\returns see below
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
When the second argument is omitted, this procedure behaves like the R6RS
|
|
\scheme{port-position} procedure, and when present, like the R6RS
|
|
\scheme{set-port-position!} procedure.
|
|
|
|
For compressed files opened with the \scheme{compressed} flag,
|
|
\scheme{file-position} returns the position in the
|
|
uncompressed stream of data.
|
|
Changing the position of a compressed input file opened with the
|
|
\scheme{compressed} flag generally requires rewinding and rereading the
|
|
file and might thus be slow.
|
|
The position of a compressed output file opened with the
|
|
\scheme{compressed} flag can be moved forward only; this is
|
|
accomplished by writing a (compressed) sequence of zeros.
|
|
File positions beyond $2^{32}$ might not be reported property
|
|
for compressed files on 32-bit versions of the system.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{clear-input-port}{\categoryprocedure}{(clear-input-port)}
|
|
\formdef{clear-input-port}{\categoryprocedure}{(clear-input-port \var{input-port})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
If \var{input-port} is not supplied, it defaults to the current input port.
|
|
This procedure discards any data in the buffer associated
|
|
with \var{input-port}.
|
|
This may be necessary, for example, to clear any type-ahead from the keyboard
|
|
in preparation for an urgent query.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{clear-output-port}{\categoryprocedure}{(clear-output-port)}
|
|
\formdef{clear-output-port}{\categoryprocedure}{(clear-output-port \var{output-port})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
If \var{output-port} is not supplied, it defaults to the current output port.
|
|
This procedure discards any data in the buffer associated
|
|
with \var{output-port}.
|
|
This may be necessary, for example, to clear any pending output on an
|
|
interactive port in preparation for an urgent message.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{flush-output-port}{\categoryprocedure}{(flush-output-port)}
|
|
\formdef{flush-output-port}{\categoryprocedure}{(flush-output-port \var{output-port})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
If \var{output-port} is not supplied, it defaults to the current output port.
|
|
This procedure forces any data in the buffer associated
|
|
with \var{output-port} to be printed immediately.
|
|
The console output port is automatically flushed after a newline and before
|
|
input from the console input port; all ports are automatically flushed when
|
|
they are closed.
|
|
\scheme{flush-output-port} may be necessary, however, to force a message
|
|
without a newline to be sent to the console output port or to force output
|
|
to appear on a file without delay.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{port-file-compressed!}{\categoryprocedure}{(port-file-compressed! \var{port})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\var{port} must be an input or an output port, but not an input/output port.
|
|
It must be a file port pointing to a regular file, i.e., a file on disk rather
|
|
than, e.g., a socket.
|
|
The port can be a binary or textual port.
|
|
If the port is an output port, subsequent output sent to the port
|
|
will be compressed.
|
|
If the port is an input port, subsequent input will be decompressed
|
|
if and only if the port is currently pointing at compressed data.
|
|
The compression format for output
|
|
is determined by the \index{\scheme{compress-format}}\scheme{compress-format}
|
|
parameter, while the compression format on input is inferred.
|
|
The compression level, which is relevant only for output, is determined
|
|
by the \index{\scheme{compress-level}}\scheme{compress-level} parameter.
|
|
This procedure has no effect if the port is already set for compression.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{compress-format}{\categorythreadparameter}{compress-format}
|
|
\listlibraries
|
|
\endnoskipentryheader
|
|
|
|
\noindent
|
|
\scheme{compress-format} determines the
|
|
compression algorithm and format used for output. Currently,
|
|
the possible values of the parameter are the symbols \scheme{lz4} (the default)
|
|
and \scheme{gzip}.
|
|
|
|
The \scheme{lz4} format uses the LZ4 compression library developed by
|
|
Yann Collet.
|
|
It is therefore compatible with the \scheme{lz4} program, which
|
|
means that \scheme{lz4} may be used to uncompress files produced
|
|
by {\ChezScheme} and visa versa.
|
|
|
|
The \scheme{gzip} format uses the zlib compression library developed by
|
|
Jean-loup Gailly and Mark Adler.
|
|
It is therefore compatible with the \scheme{gzip} program, which
|
|
means that \scheme{gzip} may be used to uncompress files produced
|
|
by {\ChezScheme} and visa versa.
|
|
|
|
Reading \scheme{lz4}-compressed data tends to be much faster than reading
|
|
\scheme{gzip}-compressed data, while \scheme{gzip}-compressed data tends to
|
|
be significantly smaller.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{compress-level}{\categorythreadparameter}{compress-level}
|
|
\listlibraries
|
|
\endnoskipentryheader
|
|
|
|
\noindent
|
|
\scheme{compress-level} determines the amount of effort spent on
|
|
compression and is thus relevant only for output.
|
|
It can be set to one of the symbols \scheme{minimum}, \scheme{low},
|
|
\scheme{medium}, \scheme{high}, or \scheme{maximum}, which are
|
|
listed in order from shortest to longest expected compression time
|
|
and least to greatest expected effectiveness.
|
|
Its default value is \scheme{medium}.
|
|
|
|
\section{String Ports\label{SECTIOSTRINGPORTS}}
|
|
|
|
String ports allow the creation and manipulation of strings via port
|
|
operations.
|
|
The procedure
|
|
\scheme{open-input-string} converts a string into a textual input port,
|
|
allowing the characters in the string to be read in sequence via input
|
|
operations such as \scheme{read-char} or \scheme{read}.
|
|
The procedure
|
|
\scheme{open-output-string} allows new strings to be built up with
|
|
output operations such as \scheme{write-char} and \scheme{write}.
|
|
|
|
While string ports could be defined as generic ports, they are instead
|
|
supported as primitive by the implementation.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{open-input-string}{\categoryprocedure}{(open-input-string \var{string})}
|
|
\returns a new string input port
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
A \index{string input port}string input port is similar to a file input port, except that
|
|
characters and objects drawn from the port come from \var{string}
|
|
rather than from a file.
|
|
|
|
A string port is at ``end of file'' when the port reaches the end of the
|
|
string.
|
|
It is not necessary to close a string port, although it is okay to do so.
|
|
|
|
\schemedisplay
|
|
(let ([p (open-input-string "hi mom!")])
|
|
(let ([x (read p)])
|
|
(list x (read p)))) ;=> (hi mom!)
|
|
\endschemedisplay
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{with-input-from-string}{\categoryprocedure}{(with-input-from-string \var{string} \var{thunk})}
|
|
\returns the values returned by \var{thunk}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{thunk} must be a procedure and should accept zero arguments.
|
|
\scheme{with-input-from-string} parameterizes the current input port to be the
|
|
result of opening \var{string} for input during the
|
|
application of \var{thunk}.
|
|
|
|
\schemedisplay
|
|
(with-input-from-string "(cons 3 4)"
|
|
(lambda ()
|
|
(eval (read)))) ;=> (3 . 4)
|
|
\endschemedisplay
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{open-output-string}{\categoryprocedure}{(open-output-string)}
|
|
\returns a new string output port
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
A \index{string output port}string output port is similar to a file output port, except that
|
|
characters and objects written to the port are placed in a string
|
|
(which grows as needed) rather than to a file.
|
|
The string built by writing to a string output port may be obtained
|
|
with \scheme{get-output-string}.
|
|
See the example given for \scheme{get-output-string} below.
|
|
It is not necessary to close a string port, although it is okay to do so.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{get-output-string}{\categoryprocedure}{(get-output-string \var{string-output-port})}
|
|
\returns the string associated with \var{string-output-port}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{string-output-port} must be an port returned by \scheme{open-output-string}.
|
|
|
|
As a side effect, \scheme{get-output-string} resets \var{string-output-port}
|
|
so that subsequent output to \var{string-output-port} is placed
|
|
into a fresh string.
|
|
|
|
\schemedisplay
|
|
(let ([p (open-output-string)])
|
|
(write 'hi p)
|
|
(write-char #\space p)
|
|
(write 'mom! p)
|
|
(get-output-string p)) ;=> "hi mom!"
|
|
\endschemedisplay
|
|
|
|
\noindent
|
|
An implementation of \scheme{format} (Section~\ref{SECTFORMAT}) might be
|
|
written using string-output ports to produce string output.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{with-output-to-string}{\categoryprocedure}{(with-output-to-string \var{thunk})}
|
|
\returns a string containing the output
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{thunk} must be a procedure and should accept zero arguments.
|
|
\scheme{with-output-to-string} parameterizes the current output port to
|
|
a new string output port during the
|
|
application of \var{thunk}.
|
|
If \var{thunk} returns, the string associated with the new string output
|
|
port is returned, as with \scheme{get-output-string}.
|
|
|
|
\schemedisplay
|
|
(with-output-to-string
|
|
(lambda ()
|
|
(display "Once upon a time ...")
|
|
(newline))) ;=> "Once upon a time ...\n"
|
|
\endschemedisplay
|
|
|
|
|
|
\section{File Ports\label{SECTIOFILEPORTS}}
|
|
|
|
%----------------------------------------------------------------------------
|
|
\noskipentryheader
|
|
\formdef{file-buffer-size}{\categorythreadparameter}{file-buffer-size}
|
|
\listlibraries
|
|
\endnoskipentryheader
|
|
|
|
\noindent
|
|
\scheme{file-buffer-size} is a parameter that determines the size of each
|
|
buffer created when the buffer mode is not \scheme{none} for a port
|
|
created by one of the file open operations, e.g., \scheme{open-input-file}
|
|
or \scheme{open-file-output-port}.
|
|
When called with no arguments, the parameter returns the
|
|
current buffer size.
|
|
When called with a positive fixnum \var{k},
|
|
it sets the current buffer size to \var{k}.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{file-port?}{\categoryprocedure}{(file-port? \var{port})}
|
|
\returns \scheme{#t} if \var{port} is a file port, \scheme{#f} otherwise
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
A file port is any port based directly
|
|
on an O/S file descriptor, e.g., one created by \scheme{open-file-input-port},
|
|
\scheme{open-output-port}, \scheme{open-fd-input-port}, etc., but not
|
|
a string, bytevector, or custom port.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{port-file-descriptor}{\categoryprocedure}{(port-file-descriptor \var{port})}
|
|
\returns the file descriptor associated with \var{port}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\var{port} must be a file port, i.e., a port for which \var{file-port?}
|
|
returns \scheme{#t}.
|
|
|
|
|
|
\section{Custom Ports\label{SECTIOCUSTOMPORTS}}
|
|
|
|
%----------------------------------------------------------------------------
|
|
\noskipentryheader
|
|
\formdef{custom-port-buffer-size}{\categorythreadparameter}{custom-port-buffer-size}
|
|
\listlibraries
|
|
\endnoskipentryheader
|
|
|
|
\noindent
|
|
\scheme{custom-port-buffer-size} is a parameter that determines the sizes
|
|
of the buffers associated with newly created custom ports.
|
|
When called with no arguments, the parameter returns the
|
|
current buffer size.
|
|
When called with a positive fixnum \var{k},
|
|
it sets the current buffer size to \var{k}.
|
|
|
|
\section{Input Operations\label{SECTIOINPUT}}
|
|
|
|
%----------------------------------------------------------------------------
|
|
\noskipentryheader
|
|
\formdef{console-input-port}{\categoryglobalparameter}{console-input-port}
|
|
\listlibraries
|
|
\endnoskipentryheader
|
|
|
|
\noindent
|
|
\scheme{console-input-port} is a parameter that determines the
|
|
input port used by the waiter and interactive debugger.
|
|
When called with no arguments, it returns the
|
|
console input port.
|
|
When called with one argument, which must be a textual input port,
|
|
it changes the value of the console
|
|
input port.
|
|
The initial value of this parameter is a port tied to the standard
|
|
input (stdin) stream of the Scheme process.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{current-input-port}{\categorythreadparameter}{current-input-port}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\scheme{current-input-port} is a parameter that determines the
|
|
default port argument for most input procedures, including
|
|
\scheme{read-char}, \scheme{peek-char}, and \scheme{read},
|
|
When called with no arguments, \scheme{current-input-port} returns the
|
|
current input port.
|
|
When called with one argument, which must be a textual input port,
|
|
it changes the value of the current
|
|
input port.
|
|
The Revised$^6$ Report version of \scheme{current-input-port} accepts
|
|
only zero arguments, i.e., it cannot be used to change the current input
|
|
port.
|
|
The initial value of this parameter is the same port as the initial
|
|
value of \scheme{console-input-port}.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{open-input-file}{\categoryprocedure}{(open-input-file \var{path})}
|
|
\formdef{open-input-file}{\categoryprocedure}{(open-input-file \var{path} \var{options})}
|
|
\returns a new input port
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{path} must be a string.
|
|
\scheme{open-input-file} opens a textual input port for the file named by
|
|
\var{path}.
|
|
An exception is raised with condition type
|
|
\scheme{&i/o-filename} if the file does not exist or cannot be
|
|
opened for input.
|
|
|
|
\var{options}, if present, is a symbolic option name or option list.
|
|
Possible symbolic option names are
|
|
\scheme{compressed}, \scheme{uncompressed}, \scheme{buffered},
|
|
and \scheme{unbuffered}.
|
|
An option list is a list containing zero or more symbolic option names.
|
|
|
|
The mutually exclusive \scheme{compressed} and
|
|
\scheme{uncompressed} options determine whether the input file
|
|
should be decompressed if it is compressed (where the compression
|
|
format is inferred).
|
|
(See \scheme{open-output-file}.)
|
|
The default is \scheme{uncompressed}, so the \scheme{uncompressed}
|
|
option is useful only as documentation.
|
|
|
|
The mutually exclusive \scheme{buffered} and \scheme{unbuffered}
|
|
options determine whether input is buffered.
|
|
When input is buffered, it is read in large blocks and buffered internally
|
|
for efficiency to reduce the number of operating system requests.
|
|
When the \scheme{unbuffered} option is specified, input is unbuffered,
|
|
but not fully, since one character of buffering is required to support
|
|
\scheme{peek-char} and \scheme{unread-char}.
|
|
Input is buffered by default, so the \scheme{buffered} option is useful
|
|
only as documentation.
|
|
|
|
% flushed this: posix lockf works only on file descriptors open for writing
|
|
%The mutually exclusive \scheme{exclusive} and \scheme{nonexclusive}
|
|
%options determine whether access to the file is ``exclusive.''
|
|
%When the exclusive option is specified, the file is locked until
|
|
%the port is closed to prevent access by other processes.
|
|
%On some systems the lock is advisory, i.e., it inhibits access by
|
|
%other processes only if they also attempt to open exclusively.
|
|
%Nonexclusive access is the default, so the \scheme{nonexclusive} option
|
|
%is useful only as documentation.
|
|
|
|
For example, the call
|
|
|
|
\schemedisplay
|
|
(open-input-file "frob" '(compressed))
|
|
\endschemedisplay
|
|
|
|
opens the file frob with decompression enabled.
|
|
|
|
The Revised$^6$ Report version of \scheme{open-input-file} does not
|
|
support the optional \var{options} argument.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{call-with-input-file}{\categoryprocedure}{(call-with-input-file \var{path} \var{procedure})}
|
|
\formdef{call-with-input-file}{\categoryprocedure}{(call-with-input-file \var{path} \var{procedure} \var{options})}
|
|
\returns the values returned by \var{procedure}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{path} must be a string.
|
|
\var{procedure} should accept one argument.
|
|
|
|
\scheme{call-with-input-file} creates a new input port for the file named
|
|
by \var{path}, as if with \scheme{open-input-file}, and passes this port to \var{procedure}.
|
|
If \var{procedure} returns normally, \scheme{call-with-input-file} closes the input port
|
|
and returns the values returned by \var{procedure}.
|
|
|
|
\scheme{call-with-input-file} does not automatically close the input
|
|
port if a continuation created outside of \var{procedure} is invoked, since it
|
|
is possible that another continuation created inside of \var{procedure} will be
|
|
invoked at a later time, returning control to \var{procedure}.
|
|
If \var{procedure} does not return, an implementation is free to close the
|
|
input port only if it can prove that the input port is no longer accessible.
|
|
As shown in Section~\ref{TSPL:SECTCONTINUATIONS} of {\TSPLFOUR}, \scheme{dynamic-wind} may be used to
|
|
ensure that the port is closed if a continuation created outside of
|
|
\var{procedure} is invoked.
|
|
|
|
See \scheme{open-input-file} above for a description of the optional
|
|
\var{options} argument.
|
|
|
|
The Revised$^6$ Report version of \scheme{call-with-input-file} does not
|
|
support the optional \var{input} argument.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{with-input-from-file}{\categoryprocedure}{(with-input-from-file \var{path} \var{thunk})}
|
|
\formdef{with-input-from-file}{\categoryprocedure}{(with-input-from-file \var{path} \var{thunk} \var{options})}
|
|
\returns the values returned by \var{thunk}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{path} must be a string.
|
|
\var{thunk} must be a procedure and should accept zero arguments.
|
|
|
|
\scheme{with-input-from-file} temporarily changes the current input port to be the
|
|
result of opening the file named by \var{path}, as if with \scheme{open-input-file}, during the
|
|
application of \var{thunk}.
|
|
If \var{thunk} returns, the port is closed and the current input port
|
|
is restored to its old value.
|
|
|
|
The behavior of \scheme{with-input-from-file} is unspecified
|
|
if a continuation created outside
|
|
of \var{thunk} is invoked before \var{thunk} returns.
|
|
An implementation may close the port and restore the current input
|
|
port to its old value---but it may not.
|
|
|
|
See \scheme{open-input-file} above for a description of the optional
|
|
\var{options} argument.
|
|
|
|
The Revised$^6$ Report version of \scheme{with-input-from-file} does not
|
|
support the optional \var{options} argument.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{open-fd-input-port}{\categoryprocedure}{(open-fd-input-port \var{fd})}
|
|
\formdef{open-fd-input-port}{\categoryprocedure}{(open-fd-input-port \var{fd} \var{b-mode})}
|
|
\formdef{open-fd-input-port}{\categoryprocedure}{(open-fd-input-port \var{fd} \var{b-mode} \var{?transcoder})}
|
|
\returns a new input port for the file descriptor \var{fd}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{fd} must be a nonnegative exact integer and should be a valid
|
|
open file descriptor.
|
|
If \var{?transcoder} is present and not \scheme{#f}, it must be a
|
|
transcoder, and this procedure returns a textual input port
|
|
whose transcoder is \var{?transcoder}.
|
|
Otherwise, this procedure returns a binary input port.
|
|
See the lead-in to Section~\ref{TSPL:SECTOPENINGFILES} of {\TSPLFOUR}
|
|
for a description of the constraints on and effects of the other
|
|
arguments.
|
|
|
|
The file descriptor is closed when the port is closed.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{standard-input-port}{\categoryprocedure}{(standard-input-port)}
|
|
\formdef{standard-input-port}{\categoryprocedure}{(standard-input-port \var{b-mode})}
|
|
\formdef{standard-input-port}{\categoryprocedure}{(standard-input-port \var{b-mode} \var{?transcoder})}
|
|
\returns a new input port connected to the process's standard input
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
If \var{?transcoder} is present and not \scheme{#f}, it must be a
|
|
transcoder, and this procedure returns a textual input port
|
|
whose transcoder is \var{?transcoder}.
|
|
Otherwise, this procedure returns a binary input port.
|
|
The buffer mode \var{b-mode} defaults to \scheme{block}.
|
|
|
|
The Revised$^6$ Report version of this procedure does not accept the
|
|
optional \var{b-mode} and \var{?transcoder} arguments, which limits
|
|
it to an implementation-dependent buffering mode (\scheme{block} in
|
|
{\ChezScheme}) and binary output.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{get-string-some}{\categoryprocedure}{(get-string-some \var{textual-input-port})}
|
|
\returns a nonempty string or the eof object
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
If \var{textual-input-port} is at end of file, the eof object is returned.
|
|
Otherwise, \scheme{get-string-some} reads (as if with \scheme{get-u8})
|
|
at least one character and possibly more, and returns a string containing
|
|
these characters.
|
|
The port's position is advanced past the characters read.
|
|
The maximum number of characters read by this operation is implementation-dependent.
|
|
|
|
An exception to the ``at least one character'' guarantee occurs
|
|
if the port is in nonblocking mode (see \scheme{set-port-nonblocking!})
|
|
and no input is ready.
|
|
In this case, an empty string is returned.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{get-string-some!}{\categoryprocedure}{(get-string-some! \var{textual-input-port} \var{string} \var{start} \var{n})}
|
|
\returns the count of characters read, as an exact nonnegative integer, or the eof object
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{start} and \var{n} must be exact nonnegative integers, and the sum of
|
|
\var{start} and \var{n} must not exceed the length of \var{string}.
|
|
|
|
If \var{n} is 0, this procedure returns zero without attempting to
|
|
read from \var{textual-input-port} and without modifying \var{string}.
|
|
|
|
Otherwise, if \var{textual-input-port} is at end of file, this procedure
|
|
returns the eof object, except it returns zero when the port is in nonblocking mode
|
|
(see \scheme{set-port-nonblocking!}) and the port cannot be determined
|
|
to be at end of file without blocking.
|
|
In either case, \var{string} is not modified.
|
|
|
|
Otherwise, this procedure reads (as if with \scheme{get-char})
|
|
up to \var{n} characters from the port, stores the characters in consecutive locations of \var{string}
|
|
starting at \var{start}, advances the port's position just past the characters read, and
|
|
returns the count of characters read.
|
|
|
|
If the port is in nonblocking mode, this procedure reads no more
|
|
than it can without blocking and thus might read zero characters;
|
|
otherwise, it reads at least one character but no more than are available
|
|
when the first character becomes available.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{get-bytevector-some!}{\categoryprocedure}{(get-bytevector-some! \var{binary-input-port} \var{bytevector} \var{start} \var{n})}
|
|
\returns the count of bytes read, as an exact nonnegative integer, or the eof object
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{start} and \var{n} must be exact nonnegative integers, and the sum of
|
|
\var{start} and \var{n} must not exceed the length of \var{bytevector}.
|
|
|
|
If \var{n} is 0, this procedure returns zero without attempting to
|
|
read from \var{binary-input-port} and without modifying \var{bytevector}.
|
|
|
|
Otherwise, if \var{binary-input-port} is at end of file, this procedure
|
|
returns the eof object, except it returns zero when the port is in nonblocking mode
|
|
(see \scheme{set-port-nonblocking!}) and the port cannot be determined
|
|
to be at end of file without blocking.
|
|
In either case, \var{bytevector} is not modified.
|
|
|
|
Otherwise, this procedure reads (as if with \scheme{get-u8})
|
|
up to \var{n} bytes from the port, stores the bytes in consecutive locations of \var{bytevector}
|
|
starting at \var{start}, advances the port's position just past the bytes read, and
|
|
returns the count of bytes read.
|
|
|
|
If the port is in nonblocking mode, this procedure reads no more
|
|
than it can without blocking and thus might read zero bytes;
|
|
otherwise, it reads at least one byte but no more than are available
|
|
when the first byte becomes available.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{unread-char}{\categoryprocedure}{(unread-char \var{char})}
|
|
\formdef{unread-char}{\categoryprocedure}{(unread-char \var{char} \var{textual-input-port})}
|
|
\formdef{unget-char}{\categoryprocedure}{(unget-char \var{textual-input-port} \var{char})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
For \scheme{unread-char}, if \var{textual-input-port} is not supplied, it
|
|
defaults to the current input port.
|
|
These procedures ``unread'' the last character read from
|
|
\scheme{textual-input-port}.
|
|
\var{char} may or may not be ignored, depending upon the implementation.
|
|
In any case, \var{char} should be last character read from the port.
|
|
A character should not be unread twice on the same port
|
|
without an intervening call to \scheme{read-char} or \scheme{get-char}.
|
|
|
|
\scheme{unread-char} and \scheme{unget-char} are provided for applications
|
|
requiring one character of lookahead and may be used in place of, or even
|
|
in combination with, \scheme{peek-char} or \scheme{lookahead-char}.
|
|
One character of lookahead is required in the procedure
|
|
\scheme{read-word}, which is defined below in terms of \scheme{unread-char}.
|
|
\scheme{read-word} returns the next word from a textual input port as a string, where
|
|
a word is defined to be a sequence of alphabetic characters.
|
|
Since it does not know until it reads one character too many that it has
|
|
read the entire word, \scheme{read-word} uses \scheme{unread-char} to
|
|
return the character to the input port.
|
|
|
|
\schemedisplay
|
|
(define read-word
|
|
(lambda (p)
|
|
(list->string
|
|
(let f ([c (read-char p)])
|
|
(cond
|
|
[(eof-object? c) '()]
|
|
[(char-alphabetic? c)
|
|
(cons c (f (read-char p)))]
|
|
[else
|
|
(unread-char c p)
|
|
'()])))))
|
|
\endschemedisplay
|
|
|
|
\noindent
|
|
In the alternate version below, \scheme{peek-char} is used instead of
|
|
\scheme{unread-char}.
|
|
|
|
\schemedisplay
|
|
(define read-word
|
|
(lambda (p)
|
|
(list->string
|
|
(let f ([c (peek-char p)])
|
|
(cond
|
|
[(eof-object? c) '()]
|
|
[(char-alphabetic? c)
|
|
(read-char p)
|
|
(cons c (f (peek-char p)))]
|
|
[else '()])))))
|
|
\endschemedisplay
|
|
|
|
\noindent
|
|
The advantage of \scheme{unread-char} in this situation is that only
|
|
one call to \scheme{unread-char} per word is required, whereas one
|
|
call to \scheme{peek-char} is required for each character in the word
|
|
plus the first character beyond.
|
|
In many cases, \scheme{unread-char} and \scheme{unget-char} do not enjoy
|
|
this advantage, and \scheme{peek-char} or \scheme{lookahead-char}
|
|
should be used instead.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{unget-u8}{\categoryprocedure}{(unget-u8 \var{binary-input-port} \var{octet})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
This procedures ``unreads'' the last byte read from
|
|
\scheme{binary-input-port}.
|
|
\var{octet} may or may not be ignored, depending upon the implementation.
|
|
In any case, \var{octet} should be last byte read from the port.
|
|
A byte should not be unread twice on the same port
|
|
without an intervening call to \scheme{get-u8}.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{input-port-ready?}{\categoryprocedure}{(input-port-ready? \var{input-port})}
|
|
\returns \scheme{#t} if data is available on \var{input-port}, \scheme{#f} otherwise
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\scheme{input-port-ready?} allows a program to check to see if input is
|
|
available on a textual or binary input port without hanging.
|
|
If input is available or the port is at end of file,
|
|
\scheme{input-port-ready?} returns \scheme{#t}.
|
|
If it cannot determine from the port whether input is ready,
|
|
\scheme{input-port-ready?} raises an exception with condition type
|
|
\scheme{&i/o-read-error}.
|
|
Otherwise, it returns \scheme{#f}.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{char-ready?}{\categoryprocedure}{(char-ready?)}
|
|
\formdef{char-ready?}{\categoryprocedure}{(char-ready? \var{textual-input-port})}
|
|
\returns \scheme{#t} if a character is available on \var{textual-input-port}, \scheme{#f} otherwise
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
If \var{textual-input-port} is not supplied, it defaults to the current input port.
|
|
\scheme{char-ready?} is like \scheme{input-port-ready?} except it is
|
|
restricted to textual input ports.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{block-read}{\categoryprocedure}{(block-read \var{textual-input-port} \var{string})}
|
|
\formdef{block-read}{\categoryprocedure}{(block-read \var{textual-input-port} \var{string} \var{count})}
|
|
\returns see below
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{count} must be a nonnegative fixnum less than or equal to the
|
|
length of \var{string}.
|
|
If not provided, it defaults to the length of \var{string}.
|
|
|
|
If \var{textual-input-port} is at end-of-file, an eof object is returned.
|
|
Otherwise, \var{string} is filled with as many characters as are
|
|
available for reading from \var{textual-input-port} up to \var{count},
|
|
and the number of characters placed in the string is returned.
|
|
|
|
If \var{textual-input-port} is buffered and the buffer is nonempty,
|
|
the buffered input or a portion thereof is returned; otherwise
|
|
\scheme{block-read} bypasses the buffer entirely.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{read-token}{\categoryprocedure}{(read-token)}
|
|
\formdef{read-token}{\categoryprocedure}{(read-token \var{textual-input-port})}
|
|
\formdef{read-token}{\categoryprocedure}{(read-token \var{textual-input-port} \var{sfd} \var{bfp})}
|
|
\returns see below
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{sfd} must be a source-file descriptor.
|
|
\var{bfp} must be an exact nonnegative integer and should be the
|
|
character position of the next character to be read from
|
|
\var{textual-input-port}.
|
|
|
|
Parsing of a Scheme datum is conceptually performed in two steps.
|
|
First, the sequence of characters that form the datum are grouped into
|
|
\scheme{tokens}, such as symbols, numbers, left parentheses, and
|
|
double quotes.
|
|
During this first step, whitespace and comments are discarded.
|
|
Second, these tokens are grouped into data.
|
|
|
|
\scheme{read} performs both of these steps and creates an internal
|
|
representation of each datum it parses.
|
|
\scheme{read-token} may be used to perform the first step only, one
|
|
token at a time.
|
|
\scheme{read-token} is intended to be used by editors and program
|
|
formatters that must be able to parse a program or datum without
|
|
actually reading it.
|
|
|
|
If \var{textual-input-port} is not supplied, it defaults to the current input port.
|
|
One token is read from the input port and returned as four values:
|
|
|
|
\begin{description}
|
|
\item[\var{type}:] a symbol describing the type of token read,
|
|
|
|
\item[\var{value}:] the token value,
|
|
|
|
\item[\var{start}:] the position of the first character of the token,
|
|
relative to the starting position of the input port (or \scheme{#f},
|
|
if the position cannot be determined), and
|
|
|
|
\item[\var{end}:] the first position beyond the token,
|
|
relative to the starting position of the input port (or \scheme{#f},
|
|
if the position cannot be determined).
|
|
\end{description}
|
|
|
|
\noindent
|
|
The input port is left pointing to the first character position beyond
|
|
the token.
|
|
|
|
When the token type fully specifies the token,
|
|
\scheme{read-token} returns \scheme{#f} for the value.
|
|
The token types are listed below with the corresponding \var{value}
|
|
in parentheses.
|
|
|
|
\begin{description}
|
|
\item[\scheme{atomic}] (\var{atom}) an atomic value, i.e.,
|
|
a symbol, boolean, number, character, \scheme{#!eof},
|
|
or \scheme{#!bwp}
|
|
\item[\scheme{box}] (\scheme{#f}) box prefix, i.e., \scheme{#&}
|
|
\item[\scheme{dot}] (\scheme{#f}) dotted pair separator, i.e., \scheme{.}
|
|
\item[\scheme{eof}] (\scheme{#!eof}) end of file
|
|
\item[\scheme{fasl}] (\scheme{#f}) fasl prefix, i.e., \scheme{#@}
|
|
\item[\scheme{insert}] (\var{n}) graph reference, i.e., \scheme{#\var{n}#}
|
|
\item[\scheme{lbrack}] (\scheme{#f}) open square bracket
|
|
\item[\scheme{lparen}] (\scheme{#f}) open parenthesis
|
|
\item[\scheme{mark}] (\var{n}) graph mark, i.e., \scheme{#\var{n}=}
|
|
\item[\scheme{quote}] (\scheme{quote}, \scheme{quasiquote},
|
|
\scheme{syntax}, \scheme{unquote}, \scheme{unquote-splicing},
|
|
or \scheme{datum-comment})
|
|
an abbreviation mark, e.g., \scheme{'} or \scheme{,@} or
|
|
datum-comment prefix
|
|
\item[\scheme{rbrack}] (\scheme{#f}) close square bracket
|
|
\item[\scheme{record-brack}] (\scheme{#f}) record open bracket, i.e., \scheme{#[}
|
|
\item[\scheme{rparen}] (\scheme{#f}) close parenthesis
|
|
\item[\scheme{vfxnparen}] (\var{n}) fxvector prefix, i.e., \scheme{#\var{n}vfx(}
|
|
\item[\scheme{vfxparen}] (\scheme{#f}) fxvector prefix, i.e., \scheme{#vfx(}
|
|
\item[\scheme{vnparen}] (\var{n}) vector prefix, i.e., \scheme{#\var{n}(}
|
|
\item[\scheme{vparen}] (\scheme{#f}) vector prefix, i.e., \scheme{#(}
|
|
\item[\scheme{vu8nparen}] (\var{n}) bytevector prefix, i.e., \scheme{#\var{n}vu8(}
|
|
\item[\scheme{vu8paren}] (\scheme{#f}) bytevector prefix, i.e., \scheme{#vu8(}
|
|
\end{description}
|
|
|
|
\noindent
|
|
The set of token types is likely to change in future releases of the
|
|
system; check the release notes for details on such changes.
|
|
|
|
Specifying \var{sfd} and \var{bfp} improves the quality of error messages,
|
|
guarantees \var{start} and \var{end} can be determined,
|
|
and eliminates the overhead of asking for a file position on each call
|
|
to \scheme{read-token}.
|
|
In most cases, \var{bfp} should be 0 for the first call
|
|
to \scheme{read-token} at the start of a file,
|
|
and it should be the fourth return value (\var{end}) of the preceding
|
|
call to \scheme{read-token} for each subsequent
|
|
call.
|
|
This protocol is necessary to handle files containing multiple-byte
|
|
characters, since file positions do not necessarily correspond
|
|
to character positions.
|
|
|
|
\schemedisplay
|
|
(define s (open-input-string "(a b c)"))
|
|
(read-token s) ;=> lparen
|
|
#f
|
|
0
|
|
1
|
|
(define s (open-input-string "abc 123"))
|
|
(read-token s) ;=> atomic
|
|
abc
|
|
0
|
|
3
|
|
(define s (open-input-string ""))
|
|
(read-token s) ;=> eof
|
|
#!eof
|
|
0
|
|
0
|
|
(define s (open-input-string "#7=#7#"))
|
|
(read-token s) ;=> mark
|
|
7
|
|
0
|
|
3
|
|
(read-token s) ;=> insert
|
|
7
|
|
3
|
|
6
|
|
\endschemedisplay
|
|
|
|
The information \scheme{read-token} returns is not always
|
|
sufficient for reconstituting the exact sequence of characters that
|
|
make up a token.
|
|
For example, \scheme{1.0} and \scheme{1e0} both return
|
|
\var{type} \scheme{atomic} with \var{value} \scheme{1.0}.
|
|
The exact sequence of characters may be obtained only by repositioning
|
|
the port and reading a block of characters of the appropriate length,
|
|
using the relative positions given by \var{start} and \var{end}.
|
|
|
|
|
|
\section{Output Operations\label{SECTIOOUTPUT}}
|
|
|
|
%----------------------------------------------------------------------------
|
|
\noskipentryheader
|
|
\formdef{console-output-port}{\categoryglobalparameter}{console-output-port}
|
|
\listlibraries
|
|
\endnoskipentryheader
|
|
|
|
\noindent
|
|
\scheme{console-output-port} is a parameter that determines the
|
|
output port used by the waiter and interactive debugger.
|
|
When called with no arguments, it returns the
|
|
console output port.
|
|
When called with one argument, which must be a textual output port,
|
|
it changes the value of the console
|
|
output port.
|
|
The initial value of this parameter is a port tied to the standard
|
|
output (stdout) stream of the Scheme process.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{current-output-port}{\categorythreadparameter}{current-output-port}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\scheme{current-output-port} is a parameter that determines the
|
|
default port argument for most output procedures,
|
|
including \scheme{write-char}, \scheme{newline}, \scheme{write},
|
|
\scheme{display}, and \scheme{pretty-print}.
|
|
When called with no arguments, \scheme{current-output-port} returns the
|
|
current output port.
|
|
When called with one argument, which must be a textual output port,
|
|
it changes the value of the current
|
|
output port.
|
|
The Revised$^6$ Report version of \scheme{current-output-port} accepts
|
|
only zero arguments, i.e., it cannot be used to change the current output
|
|
port.
|
|
The initial value of this parameter is the same port as the initial
|
|
value of \scheme{console-output-port}.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{console-error-port}{\categorythreadparameter}{console-error-port}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\scheme{console-error-port} is a parameter that can be used to set
|
|
or obtain the console error port, which determines the port to which
|
|
conditions and other messages are printed by the default exception
|
|
handler.
|
|
When called with no arguments, \scheme{console-error-port} returns the
|
|
console error port.
|
|
When called with one argument, which must be a textual output port,
|
|
it changes the value of the console
|
|
error port.
|
|
|
|
If the system determines that the standard output (stdout) and standard
|
|
error (stderr) streams refer to the same file, socket, pipe, virtual
|
|
terminal, device, etc., this parameter is initially set to the same value
|
|
as the parameter \scheme{console-output-port}.
|
|
Otherwise, this parameter is initially set to a different port tied to the
|
|
standard error (stderr) stream of the Scheme process.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{current-error-port}{\categorythreadparameter}{current-error-port}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\scheme{current-error-port} is a parameter that can be used to set
|
|
or obtain the current error port.
|
|
When called with no arguments, \scheme{current-error-port} returns the
|
|
current error port.
|
|
When called with one argument, which must be a textual output port,
|
|
it changes the value of the current error port.
|
|
The Revised$^6$ Report version of \scheme{current-error-port} accepts
|
|
only zero arguments, i.e., it cannot be used to change the current error
|
|
port.
|
|
The initial value of this parameter is the same port as the initial
|
|
value of \scheme{console-error-port}.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{open-output-file}{\categoryprocedure}{(open-output-file \var{path})}
|
|
\formdef{open-output-file}{\categoryprocedure}{(open-output-file \var{path} \var{options})}
|
|
\returns a new output port
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{path} must be a string.
|
|
\scheme{open-output-file} opens a textual output port for the file named by
|
|
\var{path}.
|
|
|
|
\var{options}, if present, is a symbolic option name or option list.
|
|
Possible symbolic option names are
|
|
\scheme{error}, \scheme{truncate}, \scheme{replace}, \scheme{append},
|
|
\scheme{compressed}, \scheme{uncompressed}, \scheme{buffered},
|
|
\scheme{unbuffered}, \scheme{exclusive}, and \scheme{nonexclusive}.
|
|
An option list is a list containing zero or more symbolic option names
|
|
and possibly the two-element
|
|
option \scheme{mode \var{mode}}.
|
|
|
|
The mutually exclusive \scheme{error}, \scheme{truncate},
|
|
\scheme{replace}, and \scheme{append} options are used to direct what happens when
|
|
the file to be opened already exists.
|
|
\begin{description}
|
|
\item[\scheme{error}:] An exception is raised with condition-type \scheme{&i/o-filename}.
|
|
\item[\scheme{replace}:] The existing file is deleted before the new file
|
|
is opened.
|
|
\item[\scheme{truncate}:] The existing file is opened
|
|
and truncated to zero length.
|
|
\item[\scheme{append}:]
|
|
The existing file is opened
|
|
and the output port is positioned at the end of the file before each write
|
|
so that output to the port is always appended to the file.
|
|
\end{description}
|
|
The default behavior is to raise an exception.
|
|
|
|
The mutually exclusive \scheme{compressed} and
|
|
\scheme{uncompressed} options determine whether the output file is to
|
|
be compressed.
|
|
The compression format and level are determined by the
|
|
\index{\scheme{compress-format}}\scheme{compress-format}
|
|
and
|
|
\index{\scheme{compress-level}}\scheme{compress-level}
|
|
parameters.
|
|
Files are uncompressed by default, so the \scheme{uncompressed}
|
|
option is useful only as documentation.
|
|
|
|
The mutually exclusive \scheme{buffered} and \scheme{unbuffered}
|
|
options determine whether output is buffered.
|
|
Unbuffered output is sent immediately to the file, whereas buffered
|
|
output not written until the port's output buffer is filled or the
|
|
port is flushed (via \scheme{flush-output-port}) or closed (via
|
|
\scheme{flush-output-port} or by the storage management system when
|
|
the port becomes inaccessible).
|
|
Output is buffered by default for efficiency, so the
|
|
\scheme{buffered} option is useful only as documentation.
|
|
|
|
The mutually exclusive \scheme{exclusive} and \scheme{nonexclusive}
|
|
options determine whether access to the file is ``exclusive.''
|
|
When the exclusive option is specified, the file is locked until
|
|
the port is closed to prevent access by other processes.
|
|
On some systems the lock is advisory, i.e., it inhibits access by
|
|
other processes only if they also attempt to open exclusively.
|
|
Nonexclusive access is the default, so the \scheme{nonexclusive} option
|
|
is useful only as documentation.
|
|
|
|
The \scheme{mode} option determines the permission bits
|
|
on Unix systems when the file is created by the operation, subject
|
|
to the process umask.
|
|
The subsequent element in the options list must be an exact integer
|
|
specifying the permissions in the manner of the Unix \scheme{open}
|
|
function.
|
|
The mode option is ignored under Windows.
|
|
|
|
For example, the call
|
|
|
|
\schemedisplay
|
|
(open-output-file "frob" '(compressed truncate mode #o644))
|
|
\endschemedisplay
|
|
|
|
opens the file frob with compression enabled.
|
|
If frob already exists it is truncated.
|
|
On Unix-based systems, if frob does not already exist, the permission
|
|
bits on the newly created file are set to logical and of \scheme{#o644} and the
|
|
process's umask.
|
|
|
|
The Revised$^6$ Report version of \scheme{open-output-file} does not
|
|
support the optional \var{options} argument.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{call-with-output-file}{\categoryprocedure}{(call-with-output-file \var{path} \var{procedure})}
|
|
\formdef{call-with-output-file}{\categoryprocedure}{(call-with-output-file \var{path} \var{procedure} \var{options})}
|
|
\returns the values returned by \var{procedure}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{path} must be a string.
|
|
\var{procedure} should accept one argument.
|
|
|
|
\scheme{call-with-output-file} creates a new output port for the file named
|
|
by \var{path}, as if with \scheme{open-output-file}, and passes this port to \var{procedure}.
|
|
If \var{procedure} returns, \scheme{call-with-output-file} closes the output port
|
|
and returns the values returned by \var{procedure}.
|
|
|
|
\scheme{call-with-output-file} does not automatically close the output
|
|
port if a continuation created outside of \var{procedure} is invoked, since it
|
|
is possible that another continuation created inside of \var{procedure} will be
|
|
invoked at a later time, returning control to \var{procedure}.
|
|
If \var{procedure} does not return, an implementation is free to close the
|
|
output port only if it can prove that the output port is no longer accessible.
|
|
As shown in Section~\ref{TSPL:SECTCONTINUATIONS} of {\TSPLFOUR}, \scheme{dynamic-wind} may be used to
|
|
ensure that the port is closed if a continuation created outside of
|
|
\var{procedure} is invoked.
|
|
|
|
See \scheme{open-output-file} above for a description of the optional
|
|
\var{options} argument.
|
|
|
|
The Revised$^6$ Report version of \scheme{call-with-output-file} does not
|
|
support the optional \var{options} argument.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{with-output-to-file}{\categoryprocedure}{(with-output-to-file \var{path} \var{thunk})}
|
|
\formdef{with-output-to-file}{\categoryprocedure}{(with-output-to-file \var{path} \var{thunk} \var{options})}
|
|
\returns the value returned by \var{thunk}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{path} must be a string.
|
|
\var{thunk} must be a procedure and should accept zero arguments.
|
|
|
|
\scheme{with-output-to-file} temporarily rebinds the current output port to be the
|
|
result of opening the file named by \var{path}, as if with \scheme{open-output-file},
|
|
during the application of \var{thunk}.
|
|
If \var{thunk} returns, the port is closed and the current output port
|
|
is restored to its old value.
|
|
|
|
The behavior of \scheme{with-output-to-file} is unspecified if a
|
|
continuation created outside of \var{thunk} is invoked before
|
|
\var{thunk} returns.
|
|
An implementation may close the port and restore the current output
|
|
port to its old value---but it may not.
|
|
|
|
See \scheme{open-output-file} above for a description of the optional
|
|
\var{options} argument.
|
|
|
|
The Revised$^6$ Report version of \scheme{with-output-to-file} does not
|
|
support the optional \var{options} argument.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{open-fd-output-port}{\categoryprocedure}{(open-fd-output-port \var{fd})}
|
|
\formdef{open-fd-output-port}{\categoryprocedure}{(open-fd-output-port \var{fd} \var{b-mode})}
|
|
\formdef{open-fd-output-port}{\categoryprocedure}{(open-fd-output-port \var{fd} \var{b-mode} \var{?transcoder})}
|
|
\returns a new output port for the file descriptor \var{fd}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{fd} must be a nonnegative exact integer and should be a valid
|
|
open file descriptor.
|
|
If \var{?transcoder} is present and not \scheme{#f}, it must be a
|
|
transcoder, and this procedure returns a textual output port
|
|
whose transcoder is \var{?transcoder}.
|
|
Otherwise, this procedure returns a binary output port.
|
|
See the lead-in to Section~\ref{TSPL:SECTOPENINGFILES} of {\TSPLFOUR}
|
|
for a description of the constraints on and effects of the other
|
|
arguments.
|
|
|
|
The file descriptor is closed when the port is closed.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{standard-output-port}{\categoryprocedure}{(standard-output-port)}
|
|
\formdef{standard-output-port}{\categoryprocedure}{(standard-output-port \var{b-mode})}
|
|
\formdef{standard-output-port}{\categoryprocedure}{(standard-output-port \var{b-mode} \var{?transcoder})}
|
|
\returns a new output port connected to the process's standard output
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
If \var{?transcoder} is present and not \scheme{#f}, it must be a
|
|
transcoder, and this procedure returns a textual output port
|
|
whose transcoder is \var{?transcoder}.
|
|
Otherwise, this procedure returns a binary output port.
|
|
The buffer mode \var{b-mode} defaults to \scheme{line}, which differs from
|
|
\scheme{block} in {\ChezScheme} only for textual output ports.
|
|
|
|
The Revised$^6$ Report version of this procedure does not accept the
|
|
optional \var{b-mode} and \var{?transcoder} arguments, which limits
|
|
it to an implementation-dependent buffering mode (\scheme{line} in
|
|
{\ChezScheme}) and binary output.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{standard-error-port}{\categoryprocedure}{(standard-error-port)}
|
|
\formdef{standard-error-port}{\categoryprocedure}{(standard-error-port \var{b-mode})}
|
|
\formdef{standard-error-port}{\categoryprocedure}{(standard-error-port \var{b-mode} \var{?transcoder})}
|
|
\returns a new output port connected to the process's standard error
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
If \var{?transcoder} is present and not \scheme{#f}, it must be a
|
|
transcoder, and this procedure returns a textual output port
|
|
whose transcoder is \var{?transcoder}.
|
|
Otherwise, this procedure returns a binary output port.
|
|
The buffer mode \var{b-mode} defaults to \scheme{none}.
|
|
See the lead-in to Section~\ref{TSPL:SECTOPENINGFILES} of {\TSPLFOUR}
|
|
for a description of the constraints on and effects of the other
|
|
arguments.
|
|
|
|
The Revised$^6$ Report version of this procedure does not accept the
|
|
optional \var{b-mode} and \var{?transcoder} arguments, which limits
|
|
it to an implementation-dependent buffering mode (\scheme{none} in
|
|
{\ChezScheme}) and binary output.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{put-bytevector-some}{\categoryprocedure}{(put-bytevector-some \var{binary-output-port} \var{bytevector})}
|
|
\formdef{put-bytevector-some}{\categoryprocedure}{(put-bytevector-some \var{binary-output-port} \var{bytevector} \var{start})}
|
|
\formdef{put-bytevector-some}{\categoryprocedure}{(put-bytevector-some \var{binary-output-port} \var{bytevector} \var{start} \var{n})}
|
|
\returns the number of bytes written
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{start} and \var{n} must be nonnegative exact integers, and the sum of
|
|
\var{start} and \var{n} must not exceed the length of \var{bytevector}.
|
|
If not supplied, \var{start} defaults to zero and \var{n} defaults to
|
|
the difference between the length of \var{bytevector} and \var{start}.
|
|
|
|
This procedure normally writes the \var{n} bytes of \var{bytevector}
|
|
starting at \var{start} to the port and advances the its position past the
|
|
end of the bytes written.
|
|
If the port is in nonblocking mode (see \scheme{set-port-nonblocking!}),
|
|
however, the number of bytes written may be less than \var{n}, if
|
|
the system would have to block to write more bytes.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{put-string-some}{\categoryprocedure}{(put-string-some \var{textual-output-port} \var{string})}
|
|
\formdef{put-string-some}{\categoryprocedure}{(put-string-some \var{textual-output-port} \var{string} \var{start})}
|
|
\formdef{put-string-some}{\categoryprocedure}{(put-string-some \var{textual-output-port} \var{string} \var{start} \var{n})}
|
|
\returns the number of characters written
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{start} and \var{n} must be nonnegative exact integers, and the sum of
|
|
\var{start} and \var{n} must not exceed the length of \var{string}.
|
|
If not supplied, \var{start} defaults to zero and \var{n} defaults to
|
|
the difference between the length of \var{string} and \var{start}.
|
|
|
|
This procedure normally writes the \var{n} characters of \var{string}
|
|
starting at \var{start} to the port and advances the its position past the
|
|
end of the characters written.
|
|
If the port is in nonblocking mode (see \scheme{set-port-nonblocking!}),
|
|
however, the number of characters written may be less than \var{n}, if
|
|
the system would have to block to write more characters.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{display-string}{\categoryprocedure}{(display-string \var{string})}
|
|
\formdef{display-string}{\categoryprocedure}{(display-string \var{string} \var{textual-output-port})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\scheme{display-string} writes the characters contained within
|
|
\var{string} to \var{textual-output-port} or to the current-output port
|
|
if \scheme{textual-output-port} is not specified.
|
|
The enclosing string quotes are not printed, and special characters
|
|
within the string are not escaped.
|
|
\scheme{display-string} is a more efficient alternative to
|
|
\scheme{display} for displaying strings.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{block-write}{\categoryprocedure}{(block-write \var{textual-output-port} \var{string})}
|
|
\formdef{block-write}{\categoryprocedure}{(block-write \var{textual-output-port} \var{string} \var{count})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{count} must be a nonnegative fixnum less than or equal to the
|
|
length of \var{string}.
|
|
If not provided, it defaults to the length of \var{string}.
|
|
|
|
\scheme{block-write} writes the first \var{count} characters of \var{string}
|
|
to \var{textual-output-port}.
|
|
If the port is buffered and the buffer is nonempty, the
|
|
buffer is flushed before the contents of \var{string} are written.
|
|
In any case, the contents of \var{string} are written immediately,
|
|
without passing through the buffer.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{truncate-port}{\categoryprocedure}{(truncate-port \var{output-port})}
|
|
\formdef{truncate-port}{\categoryprocedure}{(truncate-port \var{output-port} \var{pos})}
|
|
\formdef{truncate-file}{\categoryprocedure}{(truncate-file \var{output-port})}
|
|
\formdef{truncate-file}{\categoryprocedure}{(truncate-file \var{output-port} \var{pos})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\scheme{truncate-port} and \scheme{truncate-file} are identical.
|
|
|
|
\var{pos} must be an exact nonnegative integer. It defaults to 0.
|
|
|
|
These procedures truncate the file or other object associated with
|
|
\var{output-port} to \var{pos} and repositions the port
|
|
to that position, i.e., it combines the functionality of
|
|
\scheme{set-port-length!} and \scheme{set-port-position!} and
|
|
can be called on a port only if \scheme{port-has-set-port-length!?} and
|
|
\scheme{port-has-set-port-position!?} are both true of the port.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader\label{desc:fresh-line}
|
|
\formdef{fresh-line}{\categoryprocedure}{(fresh-line)}
|
|
\formdef{fresh-line}{\categoryprocedure}{(fresh-line \var{textual-output-port})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
If \var{textual-output-port} is not supplied, it defaults to the current output port.
|
|
|
|
This procedure behaves like \scheme{newline}, i.e., sends a newline
|
|
character to \var{textual-output-port}, unless it can determine that the port
|
|
is already positioned at the start of a line.
|
|
It does this by flushing the port and consulting the
|
|
``beginning-of-line'' (BOL) flag associated with the port.
|
|
(See page~\pageref{desc:set-port-bol}.)
|
|
|
|
|
|
\section{Input/Output Operations\label{SECTIOINPUTOUTPUT}}
|
|
|
|
%----------------------------------------------------------------------------
|
|
\noskipentryheader
|
|
\formdef{open-input-output-file}{\categoryprocedure}{(open-input-output-file \var{path})}
|
|
\formdef{open-input-output-file}{\categoryprocedure}{(open-input-output-file \var{path} \var{options})}
|
|
\returns a new input-output port
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{path} must be a string.
|
|
\scheme{open-input-output-file} opens a textual input-output port for the file named by
|
|
\var{path}.
|
|
|
|
The port may be used to read from or write to the named file.
|
|
The file is created if it does not already exist.
|
|
|
|
\var{options}, if present, is a symbolic option name or option list.
|
|
Possible symbolic option names are
|
|
\scheme{buffered},
|
|
\scheme{unbuffered}, \scheme{exclusive}, and \scheme{nonexclusive}.
|
|
An option list is a list containing zero or more symbolic option names
|
|
and possibly the two-element
|
|
option \scheme{mode \var{mode}}.
|
|
See the description of \scheme{open-output-file} for an explanation
|
|
of these options.
|
|
|
|
Input/output files are usually closed using \scheme{close-port}
|
|
but may also be closed with either
|
|
\scheme{close-input-port} or
|
|
\scheme{close-output-port}.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{open-fd-input/output-port}{\categoryprocedure}{(open-fd-input/output-port \var{fd})}
|
|
\formdef{open-fd-input/output-port}{\categoryprocedure}{(open-fd-input/output-port \var{fd} \var{b-mode})}
|
|
\formdef{open-fd-input/output-port}{\categoryprocedure}{(open-fd-input/output-port \var{fd} \var{b-mode} \var{?transcoder})}
|
|
\returns a new input/output port for the file descriptor \var{fd}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{fd} must be a nonnegative exact integer and should be a valid
|
|
open file descriptor.
|
|
If \var{?transcoder} is present and not \scheme{#f}, it must be a
|
|
transcoder, and this procedure returns a textual input/output port
|
|
whose transcoder is \var{?transcoder}.
|
|
Otherwise, this procedure returns a binary input/output port.
|
|
See the lead-in to Section~\ref{TSPL:SECTOPENINGFILES} of {\TSPLFOUR}
|
|
for a description of the constraints on and effects of the other
|
|
arguments.
|
|
|
|
The file descriptor is closed when the port is closed.
|
|
|
|
|
|
\section{Non-Unicode Bytevector/String Conversions\label{SECTMBCONVS}}
|
|
|
|
The procedures described in this section convert bytevectors containing
|
|
single- and multiple-byte sequences in non-Unicode character sets to and
|
|
from Scheme strings.
|
|
They are available only under Windows.
|
|
Under other operating systems, and when an \scheme{iconv} DLL is
|
|
available under Windows, \scheme{bytevector->string} and
|
|
\scheme{string->bytevector} can be used with a transcoder based
|
|
on a codec constructed via
|
|
\index{\scheme{iconv-codec}}\scheme{iconv-codec}
|
|
to achieve the same results, with more control over the handling
|
|
of invalid characters and line endings.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{multibyte->string}{\categoryprocedure}{(multibyte->string \var{code-page} \var{bytevector})}
|
|
\returns a string containing the characters encoded in \var{bytevector}
|
|
\formdef{string->multibyte}{\categoryprocedure}{(string->multibyte \var{code-page} \var{string})}
|
|
\returns a bytevector containing the encodings of the characters in \var{string}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
These procedures are available only under Windows.
|
|
The procedure \scheme{multibyte->string} is a wrapper for the Windows API
|
|
\scheme{MultiByteToWideChar} function,
|
|
and \scheme{string->multibyte} is a wrapper for the Windows API
|
|
\scheme{WideCharToMultiByte} function.
|
|
|
|
\var{code-page} declares the encoding of the byte sequences in the input
|
|
or output bytevectors.
|
|
It must be an exact nonnegative integer identifying a code page or one of
|
|
the symbols \scheme{cp-acp}, \scheme{cp-maccp}, \scheme{cp-oemcp},
|
|
\scheme{cp-symbol}, \scheme{cp-thread-acp}, \scheme{cp-utf7}, or
|
|
\scheme{cp-utf8}, which have the same meanings as the API function
|
|
meanings for the like-named constants.
|
|
|
|
\section{Pretty Printing\label{SECTPRETTY}}
|
|
|
|
The pretty printer is a version of the \scheme{write} procedure that
|
|
produces more human-readable output via introduced whitespace, i.e.,
|
|
line breaks and indentation.
|
|
The pretty printer is the default printer used by the read-eval-print
|
|
loop (waiter) to print the output(s) of each evaluated form.
|
|
The pretty printer may also be invoked explicitly by calling the
|
|
procedure \scheme{pretty-print}.
|
|
|
|
The pretty printer's operation can be controlled via the \scheme{pretty-format}
|
|
procedure described later in this section, which allows the
|
|
programmer to specify how specific forms are to be printed, various
|
|
pretty-printer controls, also described later in this section, and also
|
|
by the generic input/output controls described in Section~\ref{SECTMISCIOCONTROL}.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{pretty-print}{\categoryprocedure}{(pretty-print \var{obj})}
|
|
\formdef{pretty-print}{\categoryprocedure}{(pretty-print \var{obj} \var{textual-output-port})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
If \var{textual-output-port} is not supplied, it defaults to the current output port.
|
|
|
|
\scheme{pretty-print} is similar to \scheme{write} except that it uses
|
|
any number of spaces and newlines in order to print \var{obj} in a
|
|
style that is pleasing to look at and which shows the nesting level via
|
|
indentation.
|
|
For example,
|
|
|
|
\schemedisplay
|
|
(pretty-print '(define factorial (lambda (n) (let fact ((i n) (a 1))
|
|
(if (= i 0) a (fact (- i 1) (* a i)))))))
|
|
\endschemedisplay
|
|
|
|
\noindent
|
|
might produce
|
|
|
|
\schemedisplay
|
|
(define factorial
|
|
(lambda (n)
|
|
(let fact ([i n] [a 1])
|
|
(if (= i 0) a (fact (- i 1) (* a i))))))
|
|
\endschemedisplay
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{pretty-file}{\categoryprocedure}{(pretty-file \var{ifn} \var{ofn})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{ifn} and \var{ofn} must be strings.
|
|
\scheme{pretty-file} reads each object in turn from the file named by
|
|
\var{ifn} and pretty prints the object to the file named by \var{ofn}.
|
|
Comments present in the input are discarded by the reader and so do
|
|
not appear in the output file.
|
|
If the file named by \var{ofn} already exists, it is replaced.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{pretty-format}{\categoryprocedure}{(pretty-format \var{sym})}
|
|
\returns see below
|
|
\formdef{pretty-format}{\categoryprocedure}{(pretty-format \var{sym} \var{fmt})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
By default, the pretty printer uses a generic algorithm for printing
|
|
each form.
|
|
This procedure is used to override this default and guide the
|
|
pretty-printers treatment of specific forms.
|
|
The symbol \var{sym} names a syntactic form or procedure.
|
|
With just one argument, \scheme{pretty-format} returns the current
|
|
format associated with \var{sym}, or \scheme{#f} if no format is
|
|
associated with \var{sym}.
|
|
|
|
In the two-argument case, the format \var{fmt} is associated with
|
|
\var{sym} for future invocations of the pretty printer.
|
|
\var{fmt} must be in the formatting language described below.
|
|
|
|
\begin{grammar}
|
|
\ang{fmt}\longis\scheme{(quote \var{symbol})}\\
|
|
\orbar\scheme{var}\\
|
|
\orbar\scheme{\var{symbol}}\\
|
|
\orbar\scheme{(read-macro \var{string} \var{symbol})}\\
|
|
\orbar\scheme{(meta)}\\
|
|
\orbar\scheme{(bracket . \var{fmt-tail})}\\
|
|
\orbar\scheme{(alt \var{fmt} \var{fmt}*)}\\
|
|
\orbar\scheme{\var{fmt-tail}}\\
|
|
\var{fmt-tail}\longis\scheme{()}\\
|
|
\orbar\scheme{(\var{tab} \var{fmt} ...)}\\
|
|
\orbar\scheme{(\var{fmt} \var{tab} ...)}\\
|
|
\orbar\scheme{(\var{tab} \var{fmt} . \var{fmt-tail})}\\
|
|
\orbar\scheme{(\var{fmt} ...)}\\
|
|
\orbar\scheme{(\var{fmt} . \var{fmt-tail})}\\
|
|
\orbar\scheme{(fill \var{tab} \var{fmt} ...)}\\
|
|
\var{tab}\longis\scheme{\var{int}}\\
|
|
\orbar\scheme{#f}
|
|
\end{grammar}
|
|
|
|
Some of the format forms are used for matching when there are multiple
|
|
alternatives, while others are used for matching and control indentation
|
|
or printing.
|
|
A description of each \var{fmt} is given below.
|
|
|
|
\begin{description}
|
|
\item[\scheme{(quote \var{symbol})}:]
|
|
This matches only the symbol \var{symbol}.
|
|
|
|
\item[\scheme{var}:]
|
|
This matches any symbol.
|
|
|
|
\item[\scheme{\var{symbol}}:]
|
|
This matches any input.
|
|
|
|
\item[\scheme{(read-macro \var{string} \var{symbol})}:]
|
|
This is used for read macros like \scheme{quote} and \var{syntax}.
|
|
It matches any input of the form (\var{symbol} \var{subform}).
|
|
For forms that match, the pretty printer prints
|
|
\var{string} immediately followed by \var{subform}.
|
|
|
|
\item[\scheme{(meta)}:]
|
|
This is a special case used for the \scheme{meta} keyword
|
|
(Section~\ref{SECTSYNTAXMETA}) which is used as a keyword prefix of
|
|
another form.
|
|
|
|
\item[\scheme{(alt \var{fmt} \var{fmt}*)}:]
|
|
This compares the input against the specified formats and uses the
|
|
one that is the closest match.
|
|
Most often, one of the formats will match exactly, but in other
|
|
cases, as when input is malformed or appears in abstract form in the
|
|
template of a syntactic abstraction, none of the formats will match
|
|
exactly.
|
|
|
|
\item[\scheme{(bracket . \var{fmt-tail})}:]
|
|
This matches any list-structured input and prints the input enclosed
|
|
in square brackets, i.e.,
|
|
\index{\scheme{[}}\scheme{[} and \index{\scheme{]}}\scheme{]},
|
|
rather than parentheses.
|
|
|
|
\item[\scheme{\var{fmt-tail}}:]
|
|
This matches any list-structured input.
|
|
\end{description}
|
|
|
|
Indentation of list-structured forms is determined via the
|
|
\var{fmt-tail} specifier used to the last two cases above.
|
|
A description of each \var{fmt-tail} is given below.
|
|
|
|
\begin{description}
|
|
\item[\scheme{()}:]
|
|
This matches an empty list tail.
|
|
|
|
\item[\scheme{(\var{tab} \var{fmt} ...)}:]
|
|
This matches the tail of any proper list; if the tail is nonempty
|
|
and the list does not fit entirely on the current line, a line break is
|
|
inserted before the first subform of the tail and \var{tab} (see
|
|
below) determines the amount by which this and all subsequent subforms
|
|
are indented.
|
|
|
|
\item[\scheme{(\var{fmt} \var{tab} ...)}:]
|
|
This matches the tail of any proper list; if the tail is nonempty
|
|
and the list does not fit entirely on the current line, a line break is
|
|
inserted after the first subform of the tail and \var{tab} (see
|
|
below) determines the amount by which all subsequent subforms are
|
|
indented.
|
|
|
|
\item[\scheme{(\var{tab} \var{fmt} . \var{fmt-tail})}:]
|
|
This matches a nonempty tail if the tail of the tail matches \var{fmt-tail}.
|
|
If the list does not fit entirely on the current line, a line break is
|
|
inserted before the first subform of the tail and \var{tab} (see
|
|
below) determines the amount by which the subform is indented.
|
|
|
|
\item[\scheme{(\var{fmt} ...)}:]
|
|
This matches the tail of any proper list and specified that no
|
|
line breaks are to be inserted before or after the current or
|
|
subsequent subforms.
|
|
|
|
\item[\scheme{(\var{fmt} . \var{fmt-tail})}:]
|
|
This matches a nonempty tail if the tail of the tail matches \var{fmt-tail}
|
|
and specifies that no line break is to be inserted before or after
|
|
the current subform.
|
|
|
|
\item[\scheme{(fill \var{tab} \var{fmt} ...)}:]
|
|
This matches the tail of any proper list and invokes a fill mode in
|
|
which the forms are packed with as many as will fit on each line.
|
|
\end{description}
|
|
|
|
A \var{tab} determines the amount by which a list subform is indented.
|
|
If \var{tab} is a nonnegative exact integer \var{int}, the subform
|
|
is indented \var{int} spaces in from the character position just after
|
|
the opening parenthesis or bracket of the parent form.
|
|
If \var{tab} is \scheme{#f}, the standard indentation is used.
|
|
The standard indentation can be determined or changed via the parameter
|
|
\scheme{pretty-standard-indent}, which is described later in this
|
|
section.
|
|
|
|
In cases where a format is given that doesn't quite match, the pretty
|
|
printer tries to use the given format as far as it can.
|
|
For example, if a format matches a list-structured form with a specific
|
|
number of subforms, but more or fewer subform are given, the pretty
|
|
printer will discard or replicate subform formats as necessary.
|
|
|
|
Here is an example showing the formatting of \var{let} might be specified.
|
|
|
|
\schemedisplay
|
|
(pretty-format 'let
|
|
'(alt (let ([bracket var x] 0 ...) #f e #f e ...)
|
|
(let var ([bracket var x] 0 ...) #f e #f e ...)))
|
|
\endschemedisplay
|
|
|
|
Since \scheme{let} comes in two forms, named and unnamed, two alternatives
|
|
are specified.
|
|
In either case, the \scheme{bracket} \var{fmt} is used to enclose the
|
|
bindings in square brackets, with all bindings after the first appearing
|
|
just below the first (and just after the enclosing opening parenthesis),
|
|
if they don't all fit on one line.
|
|
Each body form is indented by the standard indentation.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{pretty-line-length}{\categorythreadparameter}{pretty-line-length}
|
|
\formdef{pretty-one-line-limit}{\categorythreadparameter}{pretty-one-line-limit}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
The value of each of these parameters must be a positive fixnum.
|
|
|
|
The parameters \scheme{pretty-line-length} and
|
|
\scheme{pretty-one-line-limit} control the output produced by
|
|
\index{\scheme{pretty-print}}\scheme{pretty-print}.
|
|
\scheme{pretty-line-length} determines after which character position (starting
|
|
from the first) on a line the pretty printer attempts to cut off output.
|
|
This is a soft limit only; if necessary, the pretty-printer will go beyond
|
|
\scheme{pretty-line-length}.
|
|
|
|
\scheme{pretty-one-line-limit} is similar to
|
|
\scheme{pretty-line-length}, except that it is relative to the first
|
|
nonblank position on each line of output.
|
|
It is also a soft limit.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{pretty-initial-indent}{\categorythreadparameter}{pretty-initial-indent}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
The value of this parameter must be a nonnegative fixnum.
|
|
|
|
The parameter \scheme{pretty-initial-indent} is used to tell
|
|
\index{\scheme{pretty-print}}\scheme{pretty-print} where on an output
|
|
line it has been called.
|
|
If \scheme{pretty-initial-indent} is zero (the default), \scheme{pretty-print}
|
|
assumes that the first line of output it produces will start at the
|
|
beginning of the line.
|
|
If set to a nonzero value \var{n}, \scheme{pretty-print} assumes that the first
|
|
line will appear at character position \var{n} and will adjust its
|
|
printing of subsequent lines.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{pretty-standard-indent}{\categorythreadparameter}{pretty-standard-indent}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
The value of this parameter must be a nonnegative fixnum.
|
|
|
|
This determines the amount by which
|
|
\scheme{pretty-print} indents subexpressions of most forms, such as \scheme{let}
|
|
expressions, from the form's keyword or first subexpression.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{pretty-maximum-lines}{\categorythreadparameter}{pretty-maximum-lines}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
The parameter \scheme{pretty-maximum-lines} controls how many lines
|
|
\scheme{pretty-print} prints when it is called.
|
|
If set to \scheme{#f} (the default), no limit is imposed; if set to a
|
|
nonnegative fixnum \var{n}, at most \var{n} lines are printed.
|
|
|
|
|
|
\section{Formatted Output\label{SECTFORMAT}}
|
|
|
|
%----------------------------------------------------------------------------
|
|
\noskipentryheader
|
|
\formdef{format}{\categoryprocedure}{(format \var{format-string} \var{obj} \dots)}
|
|
\formdef{format}{\categoryprocedure}{(format #f \var{format-string} \var{obj} \dots)}
|
|
\formdef{format}{\categoryprocedure}{(format #t \var{format-string} \var{obj} \dots)}
|
|
\formdef{format}{\categoryprocedure}{(format \var{textual-output-port} \var{format-string} \var{obj} \dots)}
|
|
\returns see below
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\index{formatted output}%
|
|
When the first argument to format is a string or \scheme{#f} (first and
|
|
second forms above),
|
|
\scheme{format} constructs an output string from \var{format-string} and the
|
|
objects \scheme{\var{obj} \dots}.
|
|
Characters are copied from \var{format-string} to the output string from
|
|
left to right, until \var{format-string} is exhausted.
|
|
The format string may contain one or more \var{format directives}, which are
|
|
multi-character sequences prefixed by a tilde (~\scheme{~}~).
|
|
Each directive is replaced by some other text, often involving one or more
|
|
of the \scheme{\var{obj} \dots} arguments, as determined by the semantics
|
|
of the directive.
|
|
|
|
When the first argument is \scheme{#t}, output is sent to the current output
|
|
port instead, as with \scheme{printf}.
|
|
When the first argument is a port, output is sent to that port, as with
|
|
\scheme{fprintf}.
|
|
\scheme{printf} and \scheme{fprintf} are described later in this section.
|
|
|
|
{\ChezScheme}'s implementation of \scheme{format} supports all of the
|
|
Common Lisp~\cite{Steele:common} format directives except for those specific
|
|
to the Common Lisp pretty printer.
|
|
Please consult a Common Lisp reference or the
|
|
\hyperlink{http://www.lispworks.com/documentation/HyperSpec/Front/index.htm}{Common Lisp Hyperspec},
|
|
for complete documentation.
|
|
A few of the most useful directives are described below.
|
|
|
|
% \begin{itemize}
|
|
% \item \scheme{~s}
|
|
% is replaced by the printed representation of the next \var{obj}, which
|
|
% may be any object, in machine-readable format, as with \scheme{write}.
|
|
% ``s'' is used for compatibility with \index{Common Lisp}Common Lisp, where it stands for
|
|
% ``s-expression,'' the Lisp term for object.
|
|
%
|
|
% \item \scheme{~a}
|
|
% is replaced by the printed representation of the next \var{obj}, which
|
|
% may be any object, in human-readable format, as with \scheme{display}.
|
|
% ``a'' is used for compatibility with \index{Common Lisp}Common Lisp, where it stands for
|
|
% ``ascii.''
|
|
%
|
|
% \item \scheme{~c}
|
|
% is replaced by the next \var{obj}, which must be a character, as with
|
|
% \scheme{write-char}.
|
|
%
|
|
% \item \scheme{~%}
|
|
% is replaced by a newline character, as with \scheme{newline}.
|
|
%
|
|
% \item \scheme{~~}
|
|
% is replaced by a single tilde.
|
|
% \end{itemize}
|
|
%
|
|
% An exception is raised with condition-type \scheme{&assertion}
|
|
% if more or fewer \var{objs} are given than required by
|
|
% a \var{format-string} that requires a fixed number of objects, or if the
|
|
% format string is malformed in any way.
|
|
|
|
Absent any format directives, \scheme{format} simply displays its string
|
|
argument.
|
|
|
|
\schemedisplay
|
|
(format "hi there") ;=> "hi there"
|
|
\endschemedisplay
|
|
|
|
The \scheme{~s} directive is replaced by the printed representation of
|
|
the next \var{obj}, which may be any object, in machine-readable format,
|
|
as with \scheme{write}.
|
|
|
|
\schemedisplay
|
|
(format "hi ~s" 'mom) ;=> "hi mom"
|
|
(format "hi ~s" "mom") ;=> "hi \"mom\""
|
|
(format "hi ~s~s" 'mom #\!) ;=> "hi mom#\\!"
|
|
\endschemedisplay
|
|
|
|
The general form of a \scheme{~s} directive is actually
|
|
\scheme{~\var{mincol},\var{colinc},\var{minpad},\var{padchar}s},
|
|
and the \scheme{s} can be preceded by an at sign (~\scheme{@}~)
|
|
modifier.
|
|
These additional parameters are used to control padding in the
|
|
output, with at least \var{minpad} copies of \var{padchar}
|
|
plus an integer multiple of \var{colinc} copies of \var{padchar}
|
|
to make the total width, including the written object,
|
|
\var{mincol} characters wide.
|
|
The padding is placed on the left if the \var{@} modifier is
|
|
present, otherwise on the right.
|
|
\var{mincol} and \var{minpad} default to 0, \var{colinc} defaults
|
|
to 1, and \var{padchar} defaults to space.
|
|
If specified, \var{padchar} is prefixed by a single quote mark.
|
|
|
|
\schemedisplay
|
|
(format "~10s" 'hello) ;=> "hello "
|
|
(format "~10@s" 'hello) ;=> " hello"
|
|
(format "~10,,,'*@s" 'hello) ;=> "*****hello"
|
|
\endschemedisplay
|
|
|
|
The \scheme{~a} directive is similar, but prints the object as with
|
|
\scheme{display}.
|
|
|
|
\schemedisplay
|
|
(format "hi ~s~s" "mom" #\!) ;=> "hi \"mom\"#\\!"
|
|
(format "hi ~a~a" "mom" #\!) ;=> "hi mom!"
|
|
\endschemedisplay
|
|
|
|
A tilde may be inserted into the output with \scheme{~~}, and a newline
|
|
may be inserted with \scheme{~%} (or embedded in the string with
|
|
\scheme{\n}).
|
|
|
|
\schemedisplay
|
|
(format "~~line one,~%line two.~~") ;=> "~line one,\nline two.~"
|
|
(format "~~line one,\nline two.~~") ;=> "~line one,\nline two.~"
|
|
\endschemedisplay
|
|
|
|
Real numbers may be printed in floating-point notation with \scheme{~f}.
|
|
|
|
\schemedisplay
|
|
(format "~f" 3.14159) ;=> 3.14159
|
|
\endschemedisplay
|
|
|
|
Exact numbers may printed as well as inexact numbers in this manner; they
|
|
are simply converted to inexact first as if with \scheme{exact->inexact}.
|
|
|
|
\schemedisplay
|
|
(format "~f" 1/3) ;=> "0.3333333333333333"
|
|
\endschemedisplay
|
|
|
|
The general form is actually \scheme{~\var{w},\var{d},\var{k},\var{overflowchar},\var{padchar}f}.
|
|
If specified, \var{w} determines the overall width of the output,
|
|
and \var{d} the number of digits to the right of the decimal point.
|
|
\var{padchar}, which defaults to space, is the pad character used
|
|
if padding is needed.
|
|
Padding is always inserted on the left.
|
|
The number is scaled by $10^k$ when printed; \var{k} defaults to zero.
|
|
The entire \var{w}-character field is filled with copies of
|
|
\var{overflowchar} if \var{overflowchar} is specified and the number
|
|
cannot be printed in \var{w} characters.
|
|
\var{k} defaults to 1
|
|
If an \scheme{@} modifier is present, a plus sign is printed before the
|
|
number for nonnegative inputs; otherwise, a sign is printed only if the
|
|
number is negative.
|
|
|
|
\schemedisplay
|
|
(format "~,3f" 3.14159) ;=> "3.142"
|
|
(format "~10f" 3.14159) ;=> " 3.14159"
|
|
(format "~10,,,'#f" 1e20) ;=> "##########"
|
|
\endschemedisplay
|
|
|
|
Real numbers may also be printed with \scheme{~e} for scientific
|
|
notation or with \scheme{~g}, which uses either floating-point or
|
|
scientific notation based on the size of the input.
|
|
|
|
\schemedisplay
|
|
(format "~e" 1e23) ;=> "1.0e+23"
|
|
(format "~g" 1e23) ;=> "1.0e+23"
|
|
\endschemedisplay
|
|
|
|
A real number may also be printed with \scheme{~$}, which uses
|
|
monetary notation defaulting to two digits to the right of the
|
|
decimal point.
|
|
|
|
\schemedisplay
|
|
(format "$~$" (* 39.95 1.06)) ;=> "$42.35"
|
|
(format "~$USD" 1/3) ;=> "0.33USD"
|
|
\endschemedisplay
|
|
|
|
Words can be pluralized automatically using \scheme{p}.
|
|
\schemedisplay
|
|
(format "~s bear~:p in ~s den~:p" 10 1) ;=> "10 bears in 1 den"
|
|
\endschemedisplay
|
|
|
|
Numbers may be printed out in words or roman numerals using variations
|
|
on \scheme{~r}.
|
|
|
|
\schemedisplay
|
|
(format "~r" 2599) ;=> "two thousand five hundred ninety-nine"
|
|
(format "~:r" 99) ;=> "ninety-ninth"
|
|
(format "~@r" 2599) ;=> "MMDXCIX"
|
|
\endschemedisplay
|
|
|
|
Case conversions can be performed by bracketing a portion of the
|
|
format string with the \scheme{~@(} and \scheme{~)} directives.
|
|
|
|
\schemedisplay
|
|
(format "~@(~r~)" 2599) ;=> "Two thousand five hundred ninety-nine"
|
|
(format "~@:(~a~)" "Ouch!") ;=> "OUCH!"
|
|
\endschemedisplay
|
|
|
|
\noindent
|
|
Some of the directives shown above have more options and parameters, and
|
|
there are other directives as well, including directives for conditionals,
|
|
iteration, indirection, and justification.
|
|
Again, please consult a Common Lisp reference for complete documentation.
|
|
|
|
An implementation of a greatly simplified version of \scheme{format}
|
|
appears in Section~\ref{TSPL:SECTEXPRINTF} of {\TSPLFOUR}.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{printf}{\categoryprocedure}{(printf \var{format-string} \var{obj} \dots)}
|
|
\formdef{fprintf}{\categoryprocedure}{(fprintf \var{textual-output-port} \var{format-string} \var{obj} \dots)}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
These procedures are simple wrappers for \scheme{format}.
|
|
\scheme{printf} prints the formatted output to the current output,
|
|
as with a first-argument of \scheme{#t} to \scheme{format}, and
|
|
\scheme{fprintf} prints the formatted output to the \var{textual-output-port},
|
|
as when the first argument to \scheme{format} is a port.
|
|
|
|
\section{Input/Output Control Operations\label{SECTMISCIOCONTROL}}
|
|
|
|
The I/O control operations described in this section are used to
|
|
control how the reader reads and printer writes, displays, or
|
|
pretty-prints
|
|
characters,
|
|
symbols,
|
|
gensyms,
|
|
numbers,
|
|
vectors,
|
|
long or deeply nested lists or vectors,
|
|
and graph-structured objects.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader\label{desc:char-name}
|
|
\formdef{char-name}{\categoryprocedure}{(char-name \var{obj})}
|
|
\returns see below
|
|
\formdef{char-name}{\categoryprocedure}{(char-name \var{name} \var{char})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\scheme{char-name} is used to associate names (symbols) with characters
|
|
or to retrieve the most recently associated name or character for a
|
|
given character or name.
|
|
A name can map to only one character, but more than one name
|
|
can map to the same character.
|
|
The name most recently associated with a character determines
|
|
how that character prints, and each name associated with a character
|
|
may be used after the \scheme{#\} character prefix to name that
|
|
character on input.
|
|
|
|
Character associations created by \scheme{char-name} are ignored by the
|
|
printer unless the parameter \scheme{print-char-name} is set to a true
|
|
value.
|
|
The reader recognizes character names established by \scheme{char-name}
|
|
except after \scheme{#!r6rs}, which is implied within a library or
|
|
R6RS top-level program.
|
|
|
|
In the one-argument form, \var{obj} must be a symbol or character.
|
|
If it is a symbol and a character is associated with the
|
|
symbol, \scheme{char-name} returns that character.
|
|
If it is a symbol and no character is associated with the symbol,
|
|
\scheme{char-name} returns \scheme{#f}.
|
|
Similarly, if \var{obj} is a character, \scheme{char-name} returns the
|
|
most recently associated symbol for the character or \scheme{#f} if
|
|
no name is associated with the character.
|
|
For example, with the default set of character names:
|
|
|
|
\schemedisplay
|
|
(char-name #\space) ;=> space
|
|
(char-name 'space) ;=> #\space
|
|
(char-name 'nochar) ;=> #f
|
|
(char-name #\a) ;=> #f
|
|
\endschemedisplay
|
|
|
|
When passed two arguments, \var{name} is added to the set of names
|
|
associated with \var{char}, and any other association for \var{name}
|
|
is dropped.
|
|
\var{char} may be \scheme{#f}, in which case any other association
|
|
for \var{name} is dropped and no new association is formed.
|
|
In either case, any other names associated with \var{char} remain
|
|
associated with \var{char}.
|
|
|
|
The following interactive session demonstrates the use of
|
|
\scheme{char-name} to establish and remove associations between
|
|
characters and names, including the association of more than
|
|
one name with a character.
|
|
|
|
\schemedisplay
|
|
(print-char-name #t)
|
|
(char-name 'etx) ;=> #f
|
|
(char-name 'etx #\x3)
|
|
(char-name 'etx) ;=> #\etx
|
|
(char-name #\x3) ;=> etx
|
|
#\etx ;=> #\etx
|
|
(eq? #\etx #\x3) ;=> #t
|
|
#!r6rs #\etx ;=> \var{exception: invalid character name etx}
|
|
#!chezscheme #\etx ;=> #\etx
|
|
(char-name 'etx #\space)
|
|
(char-name #\x3) ;=> #f
|
|
(char-name 'etx) ;=> #\etx
|
|
#\space ;=> #\etx
|
|
(char-name 'etx #f)
|
|
#\etx ;=> \var{exception: invalid character name etx}
|
|
#\space ;=> #\space
|
|
\endschemedisplay
|
|
|
|
(When using the expression editor, it is necessary to type Control-J to
|
|
force the editor to read the erroneous \scheme{#\etx} input on the two
|
|
inputs above that result in read errors, since typing Enter
|
|
causes the expression editor to read the input only if the input is
|
|
well-formed.)
|
|
|
|
The reader does not recognize hex scalar value escapes in character names,
|
|
as it does in symbols, so \scheme{#\new\x6c;ine} is not equivalent
|
|
to \scheme{#\newline}.
|
|
In general, programmers should avoid the use of character name symbols
|
|
that cannot be entered without the use of hex scalar value escapes or
|
|
other symbol-name escape mechanisms, since such character names will
|
|
not be readable.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{print-char-name}{\categorythreadparameter}{print-char-name}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
When \scheme{print-char-name} is set to \scheme{#f} (the default), associations
|
|
created by \scheme{char-name} are ignored by \scheme{write},
|
|
\scheme{put-datum}, \scheme{pretty-print}, and the \scheme{format}
|
|
``\scheme{~s}'' directive.
|
|
Otherwise, these procedures use the names established by
|
|
\scheme{char-name} when printing character objects.
|
|
|
|
\schemedisplay
|
|
(char-name 'etx #\x3)
|
|
(format "~s" #\x3) ;=> "#\\x3"
|
|
(parameterize ([print-char-name #t])
|
|
(format "~s" #\x3)) ;=> "#\\etx"
|
|
\endschemedisplay
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{case-sensitive}{\categorythreadparameter}{case-sensitive}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
The \scheme{case-sensitive} parameter determines whether the
|
|
reader is case-sensitive with respect to symbol and character names.
|
|
When set to true (the default, as required by the Revised$^6$ Report)
|
|
the case of alphabetic characters
|
|
within symbol names is significant.
|
|
When set to \scheme{#f}, case is insignificant.
|
|
More precisely, when set to \scheme{#f}, symbol and character names are
|
|
folded (as if by \scheme{string-foldcase}); otherwise, they are left
|
|
as they appear in the input.
|
|
|
|
The value of the \scheme{case-sensitive} matters only
|
|
if neither \scheme{#!fold-case} nor \scheme{#!no-fold-case} has appeared
|
|
previously in the same input stream.
|
|
That is, symbol and character name are folded if \scheme{#!fold-case} has
|
|
been seen.
|
|
They are not folded if \scheme{#!no-fold-case} has been seen.
|
|
If neither has been seen, they are folded if and only if
|
|
\scheme{(case-sensitive)} is \scheme{#f}.
|
|
|
|
\schemedisplay
|
|
(case-sensitive) ;=> #t
|
|
(eq? 'abc 'ABC) ;=> #f
|
|
'ABC ;=> ABC
|
|
(case-sensitive #f)
|
|
'ABC ;=> abc
|
|
(eq? 'abc 'ABC) ;=> #t
|
|
\endschemedisplay
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{print-graph}{\categorythreadparameter}{print-graph}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
When \scheme{print-graph} is set to a true value,
|
|
\scheme{write} and \scheme{pretty-print}
|
|
locate and print objects with shared structure, including
|
|
cycles, in a notation that may be read subsequently with \scheme{read}.
|
|
This notation employs the syntax
|
|
\index{#= (graph mark)@\scheme{#\var{n}=} (graph mark)}``\scheme{#\var{n}=\var{obj}},''
|
|
where \var{n}
|
|
is a nonnegative integer and \var{obj} is the printed representation
|
|
of an object, to label the first occurrence of \var{obj} in the output.
|
|
The syntax
|
|
\index{## (graph reference)@\scheme{#\var{n}#} (graph reference)}``\scheme{#\var{n}#}''
|
|
is used to refer to the object labeled by
|
|
\var{n} thereafter in the output.
|
|
\scheme{print-graph} is set to \scheme{#f} by default.
|
|
|
|
If graph printing is not enabled,
|
|
the settings of \scheme{print-length} and \scheme{print-level}
|
|
are insufficient to force finite output,
|
|
and \scheme{write} or \scheme{pretty-print} detects a cycle in an
|
|
object it is given to print,
|
|
a warning is issued (an exception with condition type \scheme{&warning} is
|
|
raised) and the object is printed as if
|
|
\scheme{print-graph} were enabled.
|
|
|
|
Since objects printed through the \scheme{~s} option in the format control
|
|
strings of \scheme{format}, \scheme{printf}, and \scheme{fprintf} are printed as with
|
|
\scheme{write}, the printing of such objects is also affected by \scheme{print-graph}.
|
|
|
|
\schemedisplay
|
|
(parameterize ([print-graph #t])
|
|
(let ([x (list 'a 'b)])
|
|
(format "~s" (list x x)))) ;=> "(#0=(a b) #0#)"
|
|
|
|
(parameterize ([print-graph #t])
|
|
(let ([x (list 'a 'b)])
|
|
(set-car! x x)
|
|
(set-cdr! x x)
|
|
(format "~s" x))) ;=> "#0=(#0# . #0#)"
|
|
\endschemedisplay
|
|
|
|
\noindent
|
|
The graph syntax is understood by the procedure
|
|
\index{\scheme{read}}\scheme{read}, allowing graph structures
|
|
to be printed and read consistently.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{print-level}{\categorythreadparameter}{print-level}
|
|
\formdef{print-length}{\categorythreadparameter}{print-length}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
These parameters can be used to limit the extent to which nested
|
|
or multiple-element structures are printed.
|
|
When called without arguments, \scheme{print-level} returns the current
|
|
print level and \scheme{print-length} returns the current print length.
|
|
When called with one argument, which must be a nonnegative fixnum or
|
|
\scheme{#f}, \scheme{print-level} sets the current print level and
|
|
\scheme{print-length} sets the current print length to the argument.
|
|
|
|
When \scheme{print-level} is set to a nonnegative integer \var{n},
|
|
\scheme{write} and \scheme{pretty-print}
|
|
traverse only \var{n} levels deep into nested structures.
|
|
If a structure being printed exceeds \var{n} levels of nesting,
|
|
the substructure beyond that point is replaced in the output by an
|
|
\index{\scheme{...}~(ellipses)}\index{ellipses (~\scheme{...}~)}ellipsis
|
|
(~\scheme{...}~).
|
|
\scheme{print-level} is set to \scheme{#f} by default, which places
|
|
no limit on the number of levels printed.
|
|
|
|
When \scheme{print-length} is set to a nonnegative integer \var{n}, the
|
|
procedures \scheme{write} and \scheme{pretty-print}
|
|
print only \var{n} elements of a list or vector,
|
|
replacing the remainder of the list or vector with an
|
|
\index{\scheme{...}~(ellipses)}\index{ellipses (~\scheme{...}~)}ellipsis
|
|
(~\scheme{...}~).
|
|
\scheme{print-length} is set to \scheme{#f} by default, which places
|
|
no limit on the number of elements printed.
|
|
|
|
Since objects printed through the \scheme{~s} option in
|
|
the format control strings of \scheme{format}, \scheme{printf}, and \scheme{fprintf} are
|
|
printed as with \scheme{write},
|
|
the printing of such objects is also affected by \scheme{print-level}
|
|
and \scheme{print-length}.
|
|
|
|
The parameters \scheme{print-level} and \scheme{print-length} are useful for
|
|
controlling the volume of output in contexts where only a small portion
|
|
of the output is needed to identify the object being printed.
|
|
They are also useful in situations where circular structures may be
|
|
printed (see also \scheme{print-graph}).
|
|
|
|
\schemedisplay
|
|
(format "~s" '((((a) b) c) d e f g)) ;=> "((((a) b) c) d e f g)"
|
|
|
|
(parameterize ([print-level 2])
|
|
(format "~s" '((((a) b) c) d e f g))) ;=> "(((...) c) d e f g)"
|
|
|
|
(parameterize ([print-length 3])
|
|
(format "~s" '((((a) b) c) d e f g))) ;=> "((((a) b) c) d e ...)"
|
|
|
|
(parameterize ([print-level 2]
|
|
[print-length 3])
|
|
(format "~s" '((((a) b) c) d e f g))) ;=> "(((...) c) d e ...)"
|
|
\endschemedisplay
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{print-radix}{\categorythreadparameter}{print-radix}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
The \scheme{print-radix} parameter determines the radix in which
|
|
numbers are printed by \scheme{write}, \scheme{pretty-print}, and
|
|
\scheme{display}.
|
|
Its value should be an integer between 2 and 36, inclusive.
|
|
Its default value is 10.
|
|
|
|
When the value of \scheme{print-radix} is not 10, \scheme{write} and
|
|
\scheme{pretty-print} print a radix prefix before the number
|
|
(\scheme{#b} for radix 2, \scheme{#o} for radix 8, \scheme{#x} for
|
|
radix 16, and \scheme{#\var{n}r} for any other radix \var{n}).
|
|
|
|
Since objects printed through the \scheme{~s} and
|
|
\scheme{~a} options in the format control strings of
|
|
\scheme{format}, \scheme{printf}, and \scheme{fprintf} are printed as
|
|
with \scheme{write} and \scheme{display}, the printing of such objects
|
|
is also affected by \scheme{print-radix}.
|
|
|
|
\schemedisplay
|
|
(format "~s" 11242957) ;=> "11242957"
|
|
|
|
(parameterize ([print-radix 16])
|
|
(format "~s" 11242957)) ;=> "#xAB8DCD"
|
|
|
|
(parameterize ([print-radix 16])
|
|
(format "~a" 11242957)) ;=> "AB8DCD"
|
|
\endschemedisplay
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{print-gensym}{\categorythreadparameter}{print-gensym}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\index{\scheme{gensym}}\index{\scheme{#:} (gensym prefix)}When
|
|
\scheme{print-gensym} is set to \scheme{#t} (the default)
|
|
gensyms are printed with an
|
|
extended symbol syntax that includes both the pretty name and the unique
|
|
name of the gensym:
|
|
\index{\scheme{#\schlbrace} (gensym prefix)}\scheme{#\schlbrace\var{pretty-name} \var{unique-name}\schrbrace}.
|
|
When set to \scheme{pretty}, the pretty name only is shown, with the
|
|
prefix \index{\scheme{#:} (gensym prefix)}\scheme{#:}.
|
|
When set to \scheme{pretty/suffix},
|
|
the printer prints the gensym's ``pretty'' name along with a
|
|
suffix based on the gensym's ``unique'' name, separated by a dot (~"."~).
|
|
If the gensym's unique name is generated automatically during the current
|
|
session, the suffix is that portion of the unique name that is not common
|
|
to all gensyms created during the current session.
|
|
Otherwise, the suffix is the entire unique name.
|
|
When set to \scheme{#f}, the pretty name only is shown, with no
|
|
prefix.
|
|
|
|
Since objects printed through the \scheme{~s} option in the
|
|
format control strings of \scheme{format}, \scheme{printf},
|
|
\scheme{errorf}, etc., are printed as with \scheme{write}, the printing of
|
|
such objects is also affected by \scheme{print-gensym}.
|
|
|
|
When printing an object that may contain more than one occurrence of a
|
|
gensym and \scheme{print-graph} is set to \scheme{pretty} or \scheme{#f},
|
|
it is useful to set \scheme{print-graph} to \scheme{#t} so that
|
|
multiple occurrences of the same gensym are marked as identical in
|
|
the output.
|
|
|
|
\schemedisplay
|
|
(let ([g (gensym)])
|
|
(format "~s" g)) ;=> "#{g0 bdids2xl6v49vgwe-a}"
|
|
|
|
(let ([g (gensym)])
|
|
(parameterize ([print-gensym 'pretty])
|
|
(format "~s" g))) ;=> "#:g1
|
|
|
|
(let ([g (gensym)])
|
|
(parameterize ([print-gensym #f])
|
|
(format "~s" g))) ;=> "g2"
|
|
|
|
(let ([g (gensym)])
|
|
(parameterize ([print-graph #t] [print-gensym 'pretty])
|
|
(format "~s" (list g g)))) ;=> "(#0=#:g3 #0#)"
|
|
|
|
(let ([g1 (gensym "x")]
|
|
[g2 (gensym "x")]
|
|
[g3 (gensym "y")])
|
|
(parameterize ([print-gensym 'pretty/suffix])
|
|
(format "~s ~s ~s" g1 g2 g3))) ;=> "x.1 x.2 y.3"
|
|
\endschemedisplay
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{print-brackets}{\categorythreadparameter}{print-brackets}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
When \scheme{print-brackets} is set to a true value, the pretty printer
|
|
(see \index{\scheme{pretty-print}}\scheme{pretty-print}) uses square
|
|
brackets rather than parentheses around certain subexpressions of
|
|
common control structures, e.g., around \scheme{let} bindings and
|
|
\scheme{cond} clauses.
|
|
\scheme{print-brackets} is set to \scheme{#t} by default.
|
|
|
|
\schemedisplay
|
|
(let ([p (open-output-string)])
|
|
(pretty-print '(let ([x 3]) x) p) ;=> "(let ([x 3]) x)
|
|
(get-output-string p)) ;== "
|
|
|
|
(parameterize ([print-brackets #f])
|
|
(let ([p (open-output-string)])
|
|
(pretty-print '(let ([x 3]) x) p) ;=> "(let ((x 3)) x)
|
|
(get-output-string p))) ;== "
|
|
\endschemedisplay
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{print-extended-identifiers}{\categorythreadparameter}{print-extended-identifiers}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
Chez Scheme extends the syntax of identifiers as described in
|
|
Section~\ref{SECTINTROSYNTAX}, except within a set of forms prefixed by
|
|
\scheme{#!r6rs} (which is implied by in a library or top-level program).
|
|
|
|
When this parameter is set to false (the default), identifiers in the
|
|
extended set are printed with hex scalar value escapes as necessary to
|
|
conform to the R6RS syntax for identifiers.
|
|
When this parameter is set to a true value, identifiers in the
|
|
extended set are printed without the escapes.
|
|
Identifiers whose names fall outside of both syntaxes are printed with
|
|
the escapes regardless of the setting of this parameter.
|
|
|
|
For example:
|
|
|
|
\schemedisplay
|
|
(parameterize ([print-extended-identifiers #f])
|
|
(printf "~s\n~s\n"
|
|
'(1+ --- { } .xyz)
|
|
(string->symbol "123")))
|
|
\endschemedisplay
|
|
|
|
prints
|
|
|
|
\schemedisplay
|
|
(\x31;+ \x2D;-- \x7B; \x7D; \x2E;xyz)
|
|
\x31;23
|
|
\endschemedisplay
|
|
|
|
while
|
|
|
|
\schemedisplay
|
|
(parameterize ([print-extended-identifiers #t])
|
|
(printf "~s\n~s\n"
|
|
'(1+ --- { } .xyz)
|
|
(string->symbol "123")))
|
|
\endschemedisplay
|
|
|
|
prints
|
|
|
|
\schemedisplay
|
|
(1+ --- { } .xyz)
|
|
\x31;23
|
|
\endschemedisplay
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{print-vector-length}{\categorythreadparameter}{print-vector-length}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
When \scheme{print-vector-length} is set to a true value,
|
|
\scheme{write}, \scheme{put-datum}, and \scheme{pretty-print} includes the length
|
|
for all vectors between the ``\scheme{#}'' and open parenthesis,
|
|
all bytevectors between the ``\scheme{#vu8}'' and open parenthesis,
|
|
and all fxvectors between the ``\scheme{#vfx}'' and open parenthesis.
|
|
This parameter is set to \scheme{#f} by default.
|
|
|
|
\index{vector printing}When \scheme{print-vector-length} is set to a
|
|
true value, \scheme{write}, \scheme{put-datum}, and \scheme{pretty-print}
|
|
also suppress duplicated trailing elements in the vector to
|
|
reduce the amount of output.
|
|
This form is also recognized by the reader.
|
|
|
|
Since objects printed through the \scheme{~s} option in the
|
|
format control strings of \scheme{format}, \scheme{printf}, and
|
|
\scheme{fprintf} are printed as with \scheme{write}, the printing of
|
|
such objects is also affected by the setting of
|
|
\scheme{print-vector-length}.
|
|
|
|
\schemedisplay
|
|
(format "~s" (vector 'a 'b 'c 'c 'c)) ;=> "#(a b c c c)"
|
|
|
|
(parameterize ([print-vector-length #t])
|
|
(format "~s" (vector 'a 'b 'c 'c 'c))) ;=> "#5(a b c)"
|
|
|
|
(parameterize ([print-vector-length #t])
|
|
(format "~s" (bytevector 1 2 3 4 4 4))) ;=> "#6vu8(1 2 3 4)"
|
|
|
|
(parameterize ([print-vector-length #t])
|
|
(format "~s" (fxvector 1 2 3 4 4 4))) ;=> "#6vfx(1 2 3 4)"
|
|
\endschemedisplay
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{print-precision}{\categorythreadparameter}{print-precision}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
When \scheme{print-precision} is set to \scheme{#f} (the default),
|
|
\scheme{write}, \scheme{put-datum}, \scheme{pretty-print}, and the
|
|
\scheme{format} ``\scheme{~s}'' directive do not include the
|
|
vertical-bar ``mantissa-width'' syntax after each floating-point
|
|
number.
|
|
When set to a nonnegative exact integer, the mantissa width is
|
|
included, as per the precision argument to
|
|
\scheme{number->string}.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{print-unicode}{\categorythreadparameter}{print-unicode}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
When \scheme{print-unicode} is set to \scheme{#f},
|
|
\scheme{write}, \scheme{put-datum}, \scheme{pretty-print}, and the
|
|
\scheme{format} ``\scheme{~s}'' directive display Unicode characters
|
|
with encodings $80_{16}$ (128) and above that appear
|
|
within character objects, symbols, and strings
|
|
using hexadecimal character escapes.
|
|
When set to a true value (the default), they are displayed like
|
|
other printing characters, as if by \scheme{put-char}.
|
|
|
|
\schemedisplay
|
|
(format "~s" #\x3bb) ;=> "#\\\raw{$\lambda$}"
|
|
(parameterize ([print-unicode #f])
|
|
(format "~s" #\x3bb)) ;=> "#\\x3BB"
|
|
\endschemedisplay
|
|
|
|
\section{Fasl Output\label{SECTFASL}}
|
|
|
|
\index{fast loading format}%
|
|
The procedures \scheme{write} and \scheme{pretty-print} print objects in a
|
|
human readable format.
|
|
For objects with external datum representations, the output produced by
|
|
\scheme{write} and \scheme{pretty-print} is also machine-readable with
|
|
\scheme{read}.
|
|
Objects with external datum representations include pairs, symbols,
|
|
vectors, strings, numbers, characters, booleans, and records but not
|
|
procedures and ports.
|
|
|
|
An alternative \emph{fast loading}, or \emph{fasl}, format may be used for
|
|
objects with external datum representations.
|
|
The fasl format is not human readable, but it is machine readable and both
|
|
more compact and more quickly processed by \scheme{read}.
|
|
This format is always used for compiled code generated by
|
|
\scheme{compile-file}, but it may also be used for data that needs to be
|
|
written and read quickly, such as small databases encoded with Scheme data
|
|
structures.
|
|
|
|
Objects are printed in fasl format with \scheme{fasl-write}.
|
|
Because the fasl format is a binary format, fasl output must be written
|
|
to a binary port.
|
|
For this reason, it is not possible to include data written in fasl
|
|
format with textual data in the same file, as was the case in
|
|
earlier versions of {\ChezScheme}.
|
|
Similarly, the (textual) reader does not handle objects written in
|
|
fasl format; the procedure \scheme{fasl-read}, which requires a binary
|
|
input port, must be used instead.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{fasl-write}{\categoryprocedure}{(fasl-write \var{obj} \var{binary-output-port})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\scheme{fasl-write} writes the fasl representation of \var{obj} to
|
|
\var{binary-output-port}.
|
|
An exception is raised with condition-type \scheme{&assertion} if
|
|
\var{obj} or any portion of \var{obj} has no external fasl representation,
|
|
e.g., if \var{obj} is or contains a procedure.
|
|
|
|
\schemedisplay
|
|
(define bop (open-file-output-port "tmp.fsl"))
|
|
(fasl-write '(a b c) bop)
|
|
(close-port bop)
|
|
|
|
(define bip (open-file-input-port "tmp.fsl"))
|
|
(fasl-read bip) ;=> (a b c)
|
|
(fasl-read bip) ;=> #!eof
|
|
(close-port bip)
|
|
\endschemedisplay
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{fasl-read}{\categoryprocedure}{(fasl-read \var{binary-input-port})}
|
|
\formdef{fasl-read}{\categoryprocedure}{(fasl-read \var{binary-input-port \var{situation}})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
If present, \var{situation} must be one of the symbols \scheme{load},
|
|
\scheme{visit}, or \scheme{revisit}.
|
|
It defaults to \scheme{load}.
|
|
|
|
\scheme{fasl-read} reads one object from
|
|
\var{binary-input-port}, which must be positioned at the
|
|
front of an object written in fasl format.
|
|
\scheme{fasl-read} returns the eof object if the file is positioned
|
|
at the end of file.
|
|
If the situation is \scheme{visit}, \scheme{fasl-read} skips over
|
|
any revisit (run-time-only) objects, and
|
|
if the situation is \scheme{revisit}, \scheme{fasl-read} skips over
|
|
any visit (compile-time-only) objects.
|
|
It doesn't skip any if the situation is \scheme{load}.
|
|
Similarly, objects marked as both visit and revisit (e.g., object code
|
|
corresponding to source code within an \scheme{eval-when} form with
|
|
situation \scheme{load} or situations \scheme{visit} and \scheme{revisit})
|
|
are never skipped.
|
|
|
|
\schemedisplay
|
|
(define bop (open-file-output-port "tmp.fsl"))
|
|
(fasl-write '(a b c) bop)
|
|
(close-port bop)
|
|
|
|
(define bip (open-file-input-port "tmp.fsl"))
|
|
(fasl-read bip) ;=> (a b c)
|
|
(fasl-read bip) ;=> #!eof
|
|
(close-port bip)
|
|
\endschemedisplay
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{fasl-file}{\categoryprocedure}{(fasl-file \var{ifn} \var{ofn})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{ifn} and \var{ofn} must be strings.
|
|
\scheme{fasl-file} may be used to convert a file in human-readable
|
|
format into an equivalent
|
|
file written in fasl format.
|
|
\scheme{fasl-file} reads each object in turn from the file named by
|
|
\var{ifn} and writes the fasl format for the object onto the file
|
|
named by \var{ofn}.
|
|
If the file named by \var{ofn} already exists, it is replaced.
|
|
|
|
|
|
\section{File System Interface\label{SECTIOFILESYSTEM}}
|
|
|
|
This section describes operations on files, directories, and pathnames.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{current-directory}{\categoryglobalparameter}{current-directory}
|
|
\formdef{cd}{\categoryglobalparameter}{cd}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
When invoked without arguments, \scheme{current-directory} returns a string
|
|
representing the current working directory.
|
|
Otherwise, the current working directory is changed to the directory
|
|
specified by the argument, which must be a string representing a valid
|
|
directory pathname.
|
|
|
|
\scheme{cd} is bound to the same parameter.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{directory-list}{\categoryprocedure}{(directory-list \var{path})}
|
|
\returns a list of file names
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\var{path} must be a string.
|
|
The return value is a list of strings representing the names of
|
|
files found in the directory named by \var{path}.
|
|
\scheme{directory-list} raises an exception with condition
|
|
type \scheme{&i/o-filename} if \var{path} does not name a directory
|
|
or if the process cannot list the directory.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{file-exists?}{\categoryprocedure}{(file-exists? \var{path})}
|
|
\formdef{file-exists?}{\categoryprocedure}{(file-exists? \var{path} \var{follow?})}
|
|
\returns \scheme{#t} if the file named by \var{path} exists, \scheme{#f} otherwise
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\var{path} must be a string.
|
|
If the optional \var{follow?} argument is true (the default),
|
|
\scheme{file-exists?} follows symbolic links; otherwise it does not.
|
|
Thus, \scheme{file-exists?} will return \scheme{#f} when handed the
|
|
pathname of a broken symbolic link unless \var{follow?} is provided
|
|
and is \scheme{#f}.
|
|
|
|
The Revised$^6$ Report \scheme{file-exists?} does not accept the
|
|
optional \var{follow?} argument.
|
|
Whether it follows symbolic links is unspecified.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{file-regular?}{\categoryprocedure}{(file-regular? \var{path})}
|
|
\formdef{file-regular?}{\categoryprocedure}{(file-regular? \var{path} \var{follow?})}
|
|
\returns \scheme{#t} if the file named by \var{path} is a regular file, \scheme{#f} otherwise
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\var{path} must be a string.
|
|
If the optional \var{follow?} argument is true (the default),
|
|
\scheme{file-regular?} follows symbolic links; otherwise it does not.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{file-directory?}{\categoryprocedure}{(file-directory? \var{path})}
|
|
\formdef{file-directory?}{\categoryprocedure}{(file-directory? \var{path} \var{follow?})}
|
|
\returns \scheme{#t} if the file named by \var{path} is a directory, \scheme{#f} otherwise
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\var{path} must be a string.
|
|
If the optional \var{follow?} argument is true (the default),
|
|
this procedure follows symbolic links; otherwise it does not.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{file-symbolic-link?}{\categoryprocedure}{(file-symbolic-link? \var{path})}
|
|
\returns \scheme{#t} if the file named by \var{path} is a symbolic link, \scheme{#f} otherwise
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\var{path} must be a string.
|
|
\scheme{file-symbolic-link?} never follows symbolic links in making its
|
|
determination.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{file-access-time}{\categoryprocedure}{(file-access-time \var{path/port})}
|
|
\formdef{file-access-time}{\categoryprocedure}{(file-access-time \var{path/port} \var{follow?})}
|
|
\returns the access time of the specified file
|
|
\formdef{file-change-time}{\categoryprocedure}{(file-change-time \var{path/port})}
|
|
\formdef{file-change-time}{\categoryprocedure}{(file-change-time \var{path/port} \var{follow?})}
|
|
\returns the change time of the specified file
|
|
\formdef{file-modification-time}{\categoryprocedure}{(file-modification-time \var{path/port})}
|
|
\formdef{file-modification-time}{\categoryprocedure}{(file-modification-time \var{path/port} \var{follow?})}
|
|
\returns the modification time of the specified file
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\var{path/port} must be a string or port.
|
|
If \var{path/port} is a string, the time returned is for the file named
|
|
by the string, and the optional \var{follow?} argument determines whether
|
|
symbolic links are followed.
|
|
If \var{follow?} is true (the default),
|
|
this procedure follows symbolic links; otherwise it does not.
|
|
If \var{path/port} is a port, it must be a file port, and the time returned
|
|
is for the associated file.
|
|
In this case, \var{follow?} is ignored.
|
|
|
|
The returned times are represented as time objects
|
|
(Section~\ref{SECTSYSTEMTIMESNDATES}).
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{mkdir}{\categoryprocedure}{(mkdir \var{path})}
|
|
\formdef{mkdir}{\categoryprocedure}{(mkdir \var{path} \var{mode})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{path} must be a string.
|
|
\var{mode} must be a fixnum.
|
|
|
|
\scheme{mkdir} creates a directory with the name given by \var{path}.
|
|
All \var{path} path components leading up to the last must already
|
|
exist.
|
|
If the optional \var{mode} argument is present, it overrides the default
|
|
permissions for the new directory.
|
|
Under Windows, the \var{mode} argument is ignored.
|
|
|
|
\scheme{mkdir} raises an exception with condition
|
|
type \scheme{&i/o-filename} if the directory cannot be created.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{delete-file}{\categoryprocedure}{(delete-file \var{path})}
|
|
\formdef{delete-file}{\categoryprocedure}{(delete-file \var{path} \var{error?})}
|
|
\returns see below
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{path} must be a string.
|
|
\scheme{delete-file} removes the file named by \var{path}.
|
|
If the optional \var{error?} argument is \scheme{#f} (the default),
|
|
\scheme{delete-file} returns a boolean value: \scheme{#t} if the
|
|
operation is successful and \scheme{#f} if it is not.
|
|
Otherwise, \scheme{delete-file} returns an unspecified value if the
|
|
operation is successful and raises an exception with condition
|
|
type \scheme{&i/o-filename} if it is not.
|
|
|
|
The Revised$^6$ Report \scheme{delete-file} does not accept the
|
|
optional \var{error?} argument but behaves as if \var{error?}
|
|
is true.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{delete-directory}{\categoryprocedure}{(delete-directory \var{path})}
|
|
\formdef{delete-directory}{\categoryprocedure}{(delete-directory \var{path} \var{error?})}
|
|
\returns see below
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{path} must be a string.
|
|
\scheme{delete-directory} removes the directory named by \var{path}.
|
|
If the optional \var{error?} argument is \scheme{#f} (the default),
|
|
\scheme{delete-directory} returns a boolean value: \scheme{#t} if the
|
|
operation is successful and \scheme{#f} if it is not.
|
|
Otherwise, \scheme{delete-directory} returns an unspecified value if the
|
|
operation is successful and raises an exception with condition
|
|
type \scheme{&i/o-filename} if it is not.
|
|
The behavior is unspecified if the directory is not empty, but on
|
|
most systems the operations will not succeed.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{rename-file}{\categoryprocedure}{(rename-file \var{old-pathname} \var{new-pathname})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{old-pathname} and \var{new-pathname} must be strings.
|
|
\scheme{rename-file} changes the name of the file named by \var{old-pathname}
|
|
to \var{new-pathname}.
|
|
If the file does not exist or cannot be renamed,
|
|
an exception is raised with condition type \scheme{&i/o-filename}.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{chmod}{\categoryprocedure}{(chmod \var{path} \var{mode})}
|
|
\returns unspecified
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{path} must be a string.
|
|
\var{mode} must be a fixnum.
|
|
|
|
\scheme{chmod} sets the permissions on the file named by
|
|
\var{path} to \var{mode}.
|
|
Bits 0, 1, and~2 of \var{mode} are the execute, write, and read permission bits
|
|
for users other than the file's owner who are not in the file's group.
|
|
Bits 3-5 are the execute, write, and read permission bits for users other
|
|
than the file's owner but in the file's group.
|
|
Bits 6-8 are the execute, write, and read permission bits
|
|
for the file's owner.
|
|
Bits 7-9 are the Unix sticky, set-group-id, and set-user-id bits.
|
|
Under Windows, all but the user ``write'' bit are ignored.
|
|
If the file does not exist or the permissions cannot be changed,
|
|
an exception is raised with condition type \scheme{&i/o-filename}.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{get-mode}{\categoryprocedure}{(get-mode \var{path})}
|
|
\formdef{get-mode}{\categoryprocedure}{(get-mode \var{path} \var{follow?})}
|
|
\returns the current permissions mode for \var{path}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\noindent
|
|
\var{path} must be a string.
|
|
\scheme{get-mode} retrieves the permissions on the file named by
|
|
\var{path} and returns them as a fixnum in the same form as the \var{mode}
|
|
argument to \scheme{chmod}.
|
|
If the optional \var{follow?} argument is true (the default),
|
|
this procedure follows symbolic links; otherwise it does not.
|
|
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{directory-separator?}{\categoryprocedure}{(directory-separator? \var{char})}
|
|
\returns \scheme{#t} if \var{char} is a directory separator, \scheme{#f} otherwise
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
The character \scheme{#\/} is a directory separator on all
|
|
current machine types, and \scheme{#\\} is a directory separator
|
|
under Windows.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{directory-separator}{\categoryprocedure}{(directory-separator)}
|
|
\returns the preferred directory separator
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
The preferred directory separator is \scheme{#\\} for Windows and
|
|
\scheme{#\/} for other systems.
|
|
|
|
%----------------------------------------------------------------------------
|
|
\entryheader
|
|
\formdef{path-first}{\categoryprocedure}{(path-first \var{path})}
|
|
\formdef{path-rest}{\categoryprocedure}{(path-rest \var{path})}
|
|
\formdef{path-last}{\categoryprocedure}{(path-last \var{path})}
|
|
\formdef{path-parent}{\categoryprocedure}{(path-parent \var{path})}
|
|
\formdef{path-extension}{\categoryprocedure}{(path-extension \var{path})}
|
|
\formdef{path-root}{\categoryprocedure}{(path-root \var{path})}
|
|
\returns the specified component of \var{path}
|
|
\formdef{path-absolute?}{\categoryprocedure}{(path-absolute? \var{path})}
|
|
\returns \scheme{#t} if \var{path} is absolute, otherwise \scheme{#f}
|
|
\listlibraries
|
|
\endentryheader
|
|
|
|
\var{path} must be a string.
|
|
The return value is also a (possibly empty) string.
|
|
|
|
The path first component is the first directory in the path, or the
|
|
empty string if the path consists only of a single filename.
|
|
The path rest component is the portion of the path that does not
|
|
include the path first component or the directory separator (if
|
|
any) that separates it from the rest of the path.
|
|
The path last component is the last (filename) portion of \var{path}.
|
|
The path parent component is the portion of \var{path} that does not
|
|
include the path last component, if any, or the directory separator that
|
|
separates it from the rest of the path.
|
|
|
|
If the first component of the path names a root directory (including drives
|
|
and shares under Windows), home directory
|
|
(e.g., \scheme{~/abc} or \scheme{~user/abc}),
|
|
the current directory (\scheme{.}), or the parent directory
|
|
(\scheme{..}), \scheme{path-first} returns that component.
|
|
For paths that consist only of such a directory,
|
|
both \scheme{path-first} and \scheme{path-parent} act as
|
|
identity procedures, while \scheme{path-rest} and \scheme{path-last}
|
|
return the empty string.
|
|
|
|
The path extension component is the portion of \var{path} that follows
|
|
the last dot (period) in the last component of a path name.
|
|
The path root component is the portion of \var{path} that does not
|
|
include the extension, if any, or the dot that precedes it.
|
|
|
|
If the first component names a root directory (including drives
|
|
and shares under Windows) or home directory,
|
|
\scheme{path-absolute?} returns \scheme{#t}.
|
|
Otherwise, \scheme{path-absolute?} returns \scheme{#f}.
|
|
|
|
The tables below identify the components for several example paths,
|
|
with underscores representing empty strings.
|
|
|
|
\begin{tabular}{llllllll}
|
|
path & abs & first & rest & parent & last & root & ext \\
|
|
\scheme{a} & \scheme{#f} & \scheme{_} & \scheme{a} & \scheme{_} & \scheme{a} & \scheme{a} & \scheme{_} \\
|
|
\scheme{a/} & \scheme{#f} & \scheme{a} & \scheme{_} & \scheme{a} & \scheme{_} & \scheme{a/} & \scheme{_} \\
|
|
\scheme{a/b} & \scheme{#f} & \scheme{a} & \scheme{b} & \scheme{a} & \scheme{b} & \scheme{a/b} & \scheme{_} \\
|
|
\scheme{a/b.c} & \scheme{#f} & \scheme{a} & \scheme{b.c} & \scheme{a} & \scheme{b.c} & \scheme{a/b} & \scheme{c} \\
|
|
\scheme{/} & \scheme{#t} & \scheme{/} & \scheme{_} & \scheme{/} & \scheme{_} & \scheme{/} & \scheme{_} \\
|
|
\scheme{/a/b.c} & \scheme{#t} & \scheme{/} & \scheme{a/b.c} & \scheme{/a} & \scheme{b.c} & \scheme{/a/b} & \scheme{c} \\
|
|
\scheme{~/a/b.c} & \scheme{#t} & \scheme{~} & \scheme{a/b.c} & \scheme{~/a} & \scheme{b.c} & \scheme{~/a/b} & \scheme{c} \\
|
|
\scheme{~u/a/b.c} & \scheme{#t} & \scheme{~u} & \scheme{a/b.c} & \scheme{~u/a} & \scheme{b.c} & \scheme{~u/a/b} & \scheme{c} \\
|
|
\scheme{../..} & \scheme{#f} & \scheme{..} & \scheme{..} & \scheme{..} & \scheme{..} & \scheme{../..} & \scheme{_} \\
|
|
\end{tabular}
|
|
|
|
The second table shows the components when Windows drives and shares
|
|
are involved.
|
|
|
|
\begin{tabular}{llllllll}
|
|
path & abs & first & rest & parent & last & root & ext \\
|
|
\scheme{c:} & \scheme{#f} & \scheme{c:} & \scheme{_} & \scheme{c:} & \scheme{_} & \scheme{c:} & \scheme{_} \\
|
|
\scheme{c:/} & \scheme{#t} & \scheme{c:/} & \scheme{_} & \scheme{c:/} & \scheme{_} & \scheme{c:/} & \scheme{_} \\
|
|
\scheme{c:a/b} & \scheme{#f} & \scheme{c:} & \scheme{a/b} & \scheme{c:a} & \scheme{b} & \scheme{c:a/b} & \scheme{_} \\
|
|
\scheme{//s/a/b.c} & \scheme{#t} & \scheme{//s} & \scheme{a/b.c} & \scheme{//s/a} & \scheme{b.c} & \scheme{//s/a/b} & \scheme{c} \\
|
|
\scheme{//s.com} & \scheme{#t} & \scheme{//s.com} & \scheme{_} & \scheme{//s.com} & \scheme{_} & \scheme{//s.com} & \scheme{_} \\
|
|
\end{tabular}
|
|
|
|
The following procedure can be used to reproduce the tables above.
|
|
|
|
\schemedisplay
|
|
(define print-table
|
|
(lambda path*
|
|
(define print-row
|
|
(lambda (abs? path first rest parent last root extension)
|
|
(printf "~a~11t~a~17t~a~28t~a~39t~a~50t~a~61t~a~73t~a\n"
|
|
abs? path first rest parent last root extension)))
|
|
(print-row "path" "abs" "first" "rest" "parent" "last" "root" "ext")
|
|
(for-each
|
|
(lambda (path)
|
|
(define uscore (lambda (s) (if (eqv? s "") "_" s)))
|
|
(apply print-row path
|
|
(map (lambda (s) (if (eqv? s "") "_" s))
|
|
(list (path-absolute? path) (path-first path)
|
|
(path-rest path) (path-parent path) (path-last path)
|
|
(path-root path) (path-extension path)))))
|
|
path*)))
|
|
\endschemedisplay
|
|
|
|
For example, the first table can be produced with:
|
|
|
|
\schemedisplay
|
|
(print-table "a" "a/" "a/b" "a/b.c" "/" "/a/b.c" "~/a/b.c"
|
|
"~u/a/b.c" "../..")
|
|
\endschemedisplay
|
|
|
|
while the second can be produced (under Windows) with:
|
|
|
|
\schemedisplay
|
|
(print-table "c:" "c:/" "c:a/b" "//s/a/b.c" "//s.com")
|
|
\endschemedisplay
|
|
|
|
\section{Generic Port Examples\label{SECTPORTEXAMPLES}}
|
|
|
|
This section presents the definitions for three types of generic ports:
|
|
two-way ports, transcript ports, and process ports.
|
|
|
|
\parheader{Two-way ports}
|
|
\index{two-way ports}The first example defines \scheme{make-two-way-port}, which constructs a
|
|
textual input/output port from a given pair of textual input and output ports.
|
|
For example:
|
|
|
|
\schemedisplay
|
|
(define ip (open-input-string "this is the input"))
|
|
(define op (open-output-string))
|
|
(define p (make-two-way-port ip op))
|
|
\endschemedisplay
|
|
|
|
\noindent
|
|
The port returned by \scheme{make-two-way-port} is both an input and an output
|
|
port, and it is also a textual port:
|
|
|
|
\schemedisplay
|
|
(port? p) ;=> #t
|
|
(input-port? p) ;=> #t
|
|
(output-port? p) ;=> #t
|
|
(textual-port? p) ;=> #t
|
|
\endschemedisplay
|
|
|
|
\noindent
|
|
Items read from a two-way port come from the constituent input port,
|
|
and items written to a two-way port go to the constituent output
|
|
port:
|
|
|
|
\schemedisplay
|
|
(read p) ;=> this
|
|
(write 'hello p)
|
|
(get-output-string op) ;=> hello
|
|
\endschemedisplay
|
|
|
|
\noindent
|
|
The definition of \scheme{make-two-way-port} is straightforward.
|
|
To keep the example simple,
|
|
no local buffering is performed,
|
|
although it would be more efficient to do so.
|
|
|
|
\schemedisplay
|
|
(define make-two-way-port
|
|
(lambda (ip op)
|
|
(define handler
|
|
(lambda (msg . args)
|
|
(record-case (cons msg args)
|
|
[block-read (p s n) (block-read ip s n)]
|
|
[block-write (p s n) (block-write op s n)]
|
|
[char-ready? (p) (char-ready? ip)]
|
|
[clear-input-port (p) (clear-input-port ip)]
|
|
[clear-output-port (p) (clear-output-port op)]
|
|
[close-port (p) (mark-port-closed! p)]
|
|
[flush-output-port (p) (flush-output-port op)]
|
|
[file-position (p . pos) (apply file-position ip pos)]
|
|
[file-length (p) (file-length ip)]
|
|
[peek-char (p) (peek-char ip)]
|
|
[port-name (p) "two-way"]
|
|
[read-char (p) (read-char ip)]
|
|
[unread-char (c p) (unread-char c ip)]
|
|
[write-char (c p) (write-char c op)]
|
|
[else (assertion-violationf 'two-way-port
|
|
"operation ~s not handled"
|
|
msg)])))
|
|
(make-input/output-port handler "" "")))
|
|
\endschemedisplay
|
|
|
|
\noindent
|
|
Most of the messages are passed directly to one of the constituent
|
|
ports.
|
|
Exceptions are \scheme{close-port}, which is handled directly by
|
|
marking the port closed, \scheme{port-name}, which is also handled directly.
|
|
\scheme{file-position} and \scheme{file-length} are rather arbitrarily
|
|
passed off to the input port.
|
|
|
|
|
|
\parheader{Transcript ports}
|
|
\index{transcript ports}The next example defines \scheme{make-transcript-port}, which constructs a
|
|
textual input/output port from three ports: a textual input port \var{ip} and two textual
|
|
output ports, \var{op} and \var{tp}.
|
|
Input read from a transcript port comes from \var{ip}, and output
|
|
written to a transcript port goes to \var{op}.
|
|
In this manner, transcript ports are similar to two-way ports.
|
|
Unlike two-way ports, input from \var{ip} and output to \var{op} is
|
|
also written to \var{tp}, so that \var{tp} reflects both input from
|
|
\var{ip} and output to \var{op}.
|
|
|
|
Transcript ports may be used to define the Scheme procedures
|
|
\scheme{transcript-on} and \scheme{transcript-off}, or the {\ChezScheme} procedure
|
|
\scheme{transcript-cafe}.
|
|
For example, here is a definition of \scheme{transcript-cafe}:
|
|
|
|
\schemedisplay
|
|
(define transcript-cafe
|
|
(lambda (pathname)
|
|
(let ([tp (open-output-file pathname 'replace)])
|
|
(let ([p (make-transcript-port
|
|
(console-input-port)
|
|
(console-output-port)
|
|
tp)])
|
|
; set both console and current ports so that
|
|
; the waiter and read/write will be in sync
|
|
(parameterize ([console-input-port p]
|
|
[console-output-port p]
|
|
[current-input-port p]
|
|
[current-output-port p])
|
|
(let-values ([vals (new-cafe)])
|
|
(close-port p)
|
|
(close-port tp)
|
|
(apply values vals)))))))
|
|
\endschemedisplay
|
|
|
|
|
|
The implementation of transcript ports is significantly more complex
|
|
than the implementation of two-way ports defined above, primarily
|
|
because it buffers input and output locally.
|
|
Local buffering is needed to allow the transcript file to reflect
|
|
accurately the actual input and output performed in the presence of
|
|
\scheme{unread-char}, \scheme{clear-output-port}, and \scheme{clear-input-port}.
|
|
Here is the code:
|
|
|
|
% exercise: Try rewriting make-transcript-port without local buffering.
|
|
% Why does this not work satisfactorily?
|
|
|
|
\schemedisplay
|
|
(define make-transcript-port
|
|
(lambda (ip op tp)
|
|
(define (handler msg . args)
|
|
(record-case (cons msg args)
|
|
[block-read (p str cnt)
|
|
(with-interrupts-disabled
|
|
(let ([b (port-input-buffer p)]
|
|
[i (port-input-index p)]
|
|
[s (port-input-size p)])
|
|
(if (< i s)
|
|
(let ([cnt (fxmin cnt (fx- s i))])
|
|
(do ([i i (fx+ i 1)]
|
|
[j 0 (fx+ j 1)])
|
|
((fx= j cnt)
|
|
(set-port-input-index! p i)
|
|
cnt)
|
|
(string-set! str j (string-ref b i))))
|
|
(let ([cnt (block-read ip str cnt)])
|
|
(unless (eof-object? cnt)
|
|
(block-write tp str cnt))
|
|
cnt))))]
|
|
[char-ready? (p)
|
|
(or (< (port-input-index p) (port-input-size p))
|
|
(char-ready? ip))]
|
|
[clear-input-port (p)
|
|
; set size to zero rather than index to size
|
|
; in order to invalidate unread-char
|
|
(set-port-input-size! p 0)]
|
|
[clear-output-port (p)
|
|
(set-port-output-index! p 0)]
|
|
[close-port (p)
|
|
(with-interrupts-disabled
|
|
(flush-output-port p)
|
|
(set-port-output-size! p 0)
|
|
(set-port-input-size! p 0)
|
|
(mark-port-closed! p))]
|
|
[file-position (p . pos)
|
|
(if (null? pos)
|
|
(most-negative-fixnum)
|
|
(assertion-violationf 'transcript-port "cannot reposition"))]
|
|
[flush-output-port (p)
|
|
(with-interrupts-disabled
|
|
(let ([b (port-output-buffer p)]
|
|
[i (port-output-index p)])
|
|
(unless (fx= i 0)
|
|
(block-write op b i)
|
|
(block-write tp b i)
|
|
(set-port-output-index! p 0)
|
|
(set-port-bol! p
|
|
(char=? (string-ref b (fx- i 1)) #\newline))))
|
|
(flush-output-port op)
|
|
(flush-output-port tp))]
|
|
[peek-char (p)
|
|
(with-interrupts-disabled
|
|
(let ([b (port-input-buffer p)]
|
|
[i (port-input-index p)]
|
|
[s (port-input-size p)])
|
|
(if (fx< i s)
|
|
(string-ref b i)
|
|
(begin
|
|
(flush-output-port p)
|
|
(let ([s (block-read ip b)])
|
|
(if (eof-object? s)
|
|
s
|
|
(begin
|
|
(block-write tp b s)
|
|
(set-port-input-size! p s)
|
|
(string-ref b 0))))))))]
|
|
[port-name (p) "transcript"]
|
|
[constituent-ports (p) (values ip op tp)]
|
|
[read-char (p)
|
|
(with-interrupts-disabled
|
|
(let ([c (peek-char p)])
|
|
(unless (eof-object? c)
|
|
(set-port-input-index! p
|
|
(fx+ (port-input-index p) 1)))
|
|
c))]
|
|
[unread-char (c p)
|
|
(with-interrupts-disabled
|
|
(let ([b (port-input-buffer p)]
|
|
[i (port-input-index p)]
|
|
[s (port-input-size p)])
|
|
(when (fx= i 0)
|
|
(assertion-violationf 'unread-char
|
|
"tried to unread too far on ~s"
|
|
p))
|
|
(set-port-input-index! p (fx- i 1))
|
|
; following could be skipped; it's supposed
|
|
; to be the same character anyway
|
|
(string-set! b (fx- i 1) c)))]
|
|
[write-char (c p)
|
|
(with-interrupts-disabled
|
|
(let ([b (port-output-buffer p)]
|
|
[i (port-output-index p)]
|
|
[s (port-output-size p)])
|
|
(string-set! b i c)
|
|
; could check here to be sure that we really
|
|
; need to flush; we may end up here even if
|
|
; the buffer isn't full
|
|
(block-write op b (fx+ i 1))
|
|
(block-write tp b (fx+ i 1))
|
|
(set-port-output-index! p 0)
|
|
(set-port-bol! p (char=? c #\newline))))]
|
|
[block-write (p str cnt)
|
|
(with-interrupts-disabled
|
|
; flush buffered data
|
|
(let ([b (port-output-buffer p)]
|
|
[i (port-output-index p)])
|
|
(unless (fx= i 0)
|
|
(block-write op b i)
|
|
(block-write tp b i)
|
|
(set-port-output-index! p 0)
|
|
(set-port-bol! p (char=? (string-ref b (fx- i 1)) #\newline))))
|
|
; write new data
|
|
(unless (fx= cnt 0)
|
|
(block-write op str cnt)
|
|
(block-write tp str cnt)
|
|
(set-port-bol! p
|
|
(char=? (string-ref str (fx- cnt 1)) #\newline))))]
|
|
[else (assertion-violationf 'transcript-port
|
|
"operation ~s not handled"
|
|
msg)]))
|
|
(let ([ib (make-string 1024)] [ob (make-string 1024)])
|
|
(let ([p (make-input/output-port handler ib ob)])
|
|
(set-port-input-size! p 0)
|
|
(set-port-output-size! p (fx- (string-length ob) 1))
|
|
p))))
|
|
\endschemedisplay
|
|
|
|
\noindent
|
|
The chosen length of both the input and output ports is the same; this
|
|
is not necessary.
|
|
They could have different lengths, or one could be buffered locally and
|
|
the other not buffered locally.
|
|
Local buffering could be disabled effectively by providing zero-length
|
|
buffers.
|
|
|
|
After we create the port, the input size is set to zero since there
|
|
is not yet any data to be read.
|
|
The port output size is set to one less than the length of the buffer.
|
|
This is done so that \scheme{write-char} always has one character position
|
|
left over into which to write its character argument.
|
|
Although this is not necessary, it does simplify the code somewhat
|
|
while allowing the buffer to be flushed as soon as the last character
|
|
is available.
|
|
|
|
Block reads and writes are performed on the constituent ports for
|
|
efficiency and (in the case of writes) to ensure that the operations
|
|
are performed immediately.
|
|
|
|
The call to \scheme{flush-output-port} in the handling of \scheme{read-char} insures
|
|
that all output written to \scheme{op} appears before input is read from
|
|
\scheme{ip}.
|
|
Since \scheme{block-read} is typically used to support higher-level operations
|
|
that are performing their own buffering, or for direct input and output
|
|
in support of I/O-intensive applications, the flush call has been
|
|
omitted from that part of the handler.
|
|
|
|
Critical sections are used whenever the handler manipulates one of the
|
|
buffers, to protect against untimely interrupts that could lead to
|
|
reentry into the handler.
|
|
The critical sections are unnecessary if no such reentry is possible,
|
|
i.e., if only one ``thread'' of the computation can have access to the
|
|
port.
|
|
|
|
\parheader{Process ports}
|
|
\index{process ports}\index{sockets}The final example
|
|
demonstrates how to incorporate the socket interface
|
|
defined in Section~\ref{SECTFOREIGNSOCKETS} into a generic port that
|
|
allows transparent communication with subprocesses via normal Scheme
|
|
input/output operations.
|
|
|
|
A process port is created with \scheme{open-process}, which accepts a
|
|
shell command as a string.
|
|
\scheme{open-process} sets up a socket, forks a child process, sets up
|
|
two-way communication via the socket, and invokes the command in a
|
|
subprocess.
|
|
|
|
The sample session below demonstrates the use of \scheme{open-process},
|
|
running and communicating with another Scheme process started with the
|
|
``\scheme{-q}'' switch to suppress the greeting and prompts.
|
|
|
|
\schemedisplay
|
|
> (define p (open-process "exec scheme -q"))
|
|
> (define s (make-string 1000 #\nul))
|
|
> (pretty-print '(+ 3 4) p)
|
|
> (read p)
|
|
7
|
|
> (pretty-print '(define (f x) (if (= x 0) 1 (* x (f (- x 1))))) p)
|
|
> (pretty-print '(f 10) p)
|
|
> (read p)
|
|
3628800
|
|
> (pretty-print '(exit) p)
|
|
> (read p)
|
|
#!eof
|
|
> (close-port p)
|
|
\endschemedisplay
|
|
|
|
\noindent
|
|
Since process ports, like transcript ports, are two-way, the implementation
|
|
is somewhat similar.
|
|
The main difference is that a transcript port reads from and writes to its
|
|
subordinate ports, whereas a process port reads from and writes to a socket.
|
|
When a process port is opened, the socket is created and subprocess
|
|
invoked, and when the port is closed, the socket is closed and the
|
|
subprocess is terminated.
|
|
|
|
\schemedisplay
|
|
(define open-process
|
|
(lambda (command)
|
|
(define handler
|
|
(lambda (pid socket)
|
|
(define (flush-output who p)
|
|
(let ([i (port-output-index p)])
|
|
(when (fx> i 0)
|
|
(check who (c-write socket (port-output-buffer p) i))
|
|
(set-port-output-index! p 0))))
|
|
(lambda (msg . args)
|
|
(record-case (cons msg args)
|
|
[block-read (p str cnt)
|
|
(with-interrupts-disabled
|
|
(let ([b (port-input-buffer p)]
|
|
[i (port-input-index p)]
|
|
[s (port-input-size p)])
|
|
(if (< i s)
|
|
(let ([cnt (fxmin cnt (fx- s i))])
|
|
(do ([i i (fx+ i 1)]
|
|
[j 0 (fx+ j 1)])
|
|
((fx= j cnt)
|
|
(set-port-input-index! p i)
|
|
cnt)
|
|
(string-set! str j (string-ref b i))))
|
|
(begin
|
|
(flush-output 'block-read p)
|
|
(let ([n (check 'block-read
|
|
(c-read socket str cnt))])
|
|
(if (fx= n 0)
|
|
#!eof
|
|
n))))))]
|
|
[char-ready? (p)
|
|
(or (< (port-input-index p) (port-input-size p))
|
|
(bytes-ready? socket))]
|
|
[clear-input-port (p)
|
|
; set size to zero rather than index to size
|
|
; in order to invalidate unread-char
|
|
(set-port-input-size! p 0)]
|
|
[clear-output-port (p) (set-port-output-index! p 0)]
|
|
[close-port (p)
|
|
(with-interrupts-disabled
|
|
(flush-output 'close-port p)
|
|
(set-port-output-size! p 0)
|
|
(set-port-input-size! p 0)
|
|
(mark-port-closed! p)
|
|
(terminate-process pid))]
|
|
[file-length (p) 0]
|
|
[file-position (p . pos)
|
|
(if (null? pos)
|
|
(most-negative-fixnum)
|
|
(assertion-violationf 'process-port "cannot reposition"))]
|
|
[flush-output-port (p)
|
|
(with-interrupts-disabled
|
|
(flush-output 'flush-output-port p))]
|
|
[peek-char (p)
|
|
(with-interrupts-disabled
|
|
(let ([b (port-input-buffer p)]
|
|
[i (port-input-index p)]
|
|
[s (port-input-size p)])
|
|
(if (fx< i s)
|
|
(string-ref b i)
|
|
(begin
|
|
(flush-output 'peek-char p)
|
|
(let ([s (check 'peek-char
|
|
(c-read socket b (string-length b)))])
|
|
(if (fx= s 0)
|
|
#!eof
|
|
(begin (set-port-input-size! p s)
|
|
(string-ref b 0))))))))]
|
|
[port-name (p) "process"]
|
|
[read-char (p)
|
|
(with-interrupts-disabled
|
|
(let ([b (port-input-buffer p)]
|
|
[i (port-input-index p)]
|
|
[s (port-input-size p)])
|
|
(if (fx< i s)
|
|
(begin
|
|
(set-port-input-index! p (fx+ i 1))
|
|
(string-ref b i))
|
|
(begin
|
|
(flush-output 'peek-char p)
|
|
(let ([s (check 'read-char
|
|
(c-read socket b (string-length b)))])
|
|
(if (fx= s 0)
|
|
#!eof
|
|
(begin (set-port-input-size! p s)
|
|
(set-port-input-index! p 1)
|
|
(string-ref b 0))))))))]
|
|
[unread-char (c p)
|
|
(with-interrupts-disabled
|
|
(let ([b (port-input-buffer p)]
|
|
[i (port-input-index p)]
|
|
[s (port-input-size p)])
|
|
(when (fx= i 0)
|
|
(assertion-violationf 'unread-char
|
|
"tried to unread too far on ~s"
|
|
p))
|
|
(set-port-input-index! p (fx- i 1))
|
|
; following could be skipped; supposed to be
|
|
; same character
|
|
(string-set! b (fx- i 1) c)))]
|
|
[write-char (c p)
|
|
(with-interrupts-disabled
|
|
(let ([b (port-output-buffer p)]
|
|
[i (port-output-index p)]
|
|
[s (port-output-size p)])
|
|
(string-set! b i c)
|
|
(check 'write-char (c-write socket b (fx+ i 1)))
|
|
(set-port-output-index! p 0)))]
|
|
[block-write (p str cnt)
|
|
(with-interrupts-disabled
|
|
; flush buffered data
|
|
(flush-output 'block-write p)
|
|
; write new data
|
|
(check 'block-write (c-write socket str cnt)))]
|
|
[else
|
|
(assertion-violationf 'process-port
|
|
"operation ~s not handled"
|
|
msg)]))))
|
|
(let* ([server-socket-name (tmpnam 0)]
|
|
[server-socket (setup-server-socket server-socket-name)])
|
|
(dofork
|
|
(lambda () ; child
|
|
(check 'close (close server-socket))
|
|
(let ([sock (setup-client-socket server-socket-name)])
|
|
(dodup 0 sock)
|
|
(dodup 1 sock))
|
|
(check 'execl (execl4 "/bin/sh" "/bin/sh" "-c" command))
|
|
(assertion-violationf 'open-process "subprocess exec failed"))
|
|
(lambda (pid) ; parent
|
|
(let ([sock (accept-socket server-socket)])
|
|
(check 'close (close server-socket))
|
|
(let ([ib (make-string 1024)] [ob (make-string 1024)])
|
|
(let ([p (make-input/output-port
|
|
(handler pid sock)
|
|
ib ob)])
|
|
(set-port-input-size! p 0)
|
|
(set-port-output-size! p (fx- (string-length ob) 1))
|
|
p))))))))
|
|
\endschemedisplay
|