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