7.2. Output Operations

7.2. Output Operations

(output-port? obj)	procedure
returns: #t if obj is an output port, #f otherwise

Ports need not be distinct from other object types.

 (output-port? '(a b c))) ⇒ unspecified (output-port? (current-output-port)) ⇒ #t (output-port? (open-output-file "outfile.ss")) ⇒ #t 

The last example assumes that file named by "outfile.ss" may be opened for output.

(current-output-port)	procedure
returns: the current output port

Most procedures involving output ports may be called with or without an explicit port argument. If called without an explicit port argument, the current output port is used. For example, (write obj ) and (write obj (current-output-port)) both write to the current output port.

(open-output-file filename)	procedure
returns: a new output port

filename must be a string. open-output-file creates a new output port for the file named by filename. An error is signaled if the file cannot be opened for output. See the example given for close-output-port.

(close-output-port output-port)	procedure
returns: unspecified

close-output-port closes an output port. Once an output port has been closed, no more output operations may be performed on that port. Because the operating system may place limits on the number of ports open at one time or restrict access to an open port, it is a good practice to close any port that will no longer be used for input or output. Also, because the system may buffer output for efficiency, some of the output may not appear on the file until the file has been closed. Some Scheme implementations close 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.

It is not an error to close a port that has already been closed; doing so has no effect.

The following shows the use of open-output-file and close-output-port to write a list of objects (the value of list-to-be-printed), separated by newlines, to the file named by "myfile.ss." It is functionally equivalent to the example given for call-with-output-file below.

 (let ((p (open-output-file "myfile.ss")))   (let f ((ls list-to-be-printed))     (if (not (null? ls))         (begin           (write (car ls) p)           (newline p)           (f (cdr ls)))))   (close-output-port p)) 

(call-with-output-file filename proc)	procedure
returns: the result of invoking proc

filename must be a string. proc must be a procedure of one argument.

call-with-output-file creates a new output port for the file named by filename and passes this port to proc. An error is signaled if the file cannot be opened for output. If proc returns, call-with-output-file closes the output port and returns the value returned by proc.

call-with-output-file does not automatically close the output port if a continuation created outside of proc is invoked, since it is possible that another continuation created inside of proc will be invoked at a later time, returning control to proc. If proc 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 5.5, dynamic-wind may be used to ensure that the port is closed if a continuation created outside of proc is invoked.

The following shows the use of call-with-output-file to write a list of objects (the value of list-to-be-printed), separated by newlines, to the file named by "myfile.ss." It is functionally equivalent to the example given for close-output-port above.

 (call-with-output-file "myfile.ss"   (lambda (p)     (let f ((ls list-to-be-printed))       (if (not (null? ls))           (begin             (write (car ls) p)             (newline p)             (f (cdr ls))))))) 

call-with-output-file might be defined as follows.

 (define call-with-output-file   (lambda (filename proc)     (let ((p (open-output-file filename)))       (let ((v (proc p)))         (close-output-port p)         v)))) 

(with-output-to-file filename thunk)	procedure
returns: the value returned by thunk

filename must be a string.

with-output-to-file temporarily rebinds the current output port to be the result of opening the file named by filename for output during the application of thunk. If thunk returns, the port is closed and the current output port is restored to its old value.

The behavior of with-output-to-file is unspecified if a continuation created outside of thunk is invoked before thunk returns. An implementation may close the port and restore the current output port to its old value|but it may not.

with-output-to-file appears in the Revised⁵ Report but not the ANSI/IEEE standard.

(write obj)	procedure
(write obj output-port)	procedure
returns: unspecified

If output-port is not supplied, it defaults to the current output port.

write prints obj to output-port in such a way that it can later be read by the procedure read, unless it contains unprintable objects such as procedures, ports, or symbols containing nonstandard characters. Strings are printed within quote marks, using slashes where necessary, and characters are printed with the #\ notation. See Section 9.5 for an implementation of write and display.

(display obj)	procedure
(display obj output-port)	procedure
returns: unspecified

If output-port is not supplied, it defaults to the current output port.

display is similar to write but prints strings and characters found within obj directly. Strings are printed without quotation marks or slashes, and characters are printed without the #\ notation. For example, both (display "(a b c)") and (display '("a b" c)) would print (a b c). Because of this, display should not be used to print objects that are intended to be read with read. display is useful primarily for printing messages, with obj most often being a string. See Section 9.5 for an implementation of write and display.

(write-char char)	procedure
(write-char char output-port)	procedure
returns: unspecified

If output-port is not supplied, it defaults to the current output port. write-char writes the single character char to output-port, without the #\ notation. The following example copies the contents of one file to another, one character at a time.

 (call-with-input-file "infile"   (lambda (ip)     (call-with-output-file "outfile"       (lambda (op)         (do ((c (read-char ip) (read-char ip)))             ((eof-object? c))             (write-char c op)))))) 

(newline)	procedure
(newline output-port)	procedure
returns: unspecified

If output-port is not supplied, it defaults to the current output port. newline sends a newline character to output-port. It may be defined as follows.

 (define newline   (lambda args     (apply write-char #\newline args)))