7.1. Input Operations

7.1. Input Operations

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

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

The last example assumes that the file named by "infile.ss" may be opened for input.

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

Most procedures involving input ports may be called with or without an explicit port argument. If called without an explicit port argument, the current input port is used. For example, (read-char) and (read-char (current-input-port)) both return the next character from the current input port.

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

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

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

close-input-port closes an input port. Once an input port has been closed, no more input 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. 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-input-file and close-input-port in an expression that gathers a list of objects from the file named by "myfile.ss." It is functionally equivalent to the example given for call-with-input-file below.

 (let ((p (open-input-file "myfile.ss")))   (let f ((x (read p)))     (if (eof-object? x)         (begin           (close-input-port p)           '())         (cons x (f (read p)))))) 

(call-with-input-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-input-file creates a new input port for the file named by filename and passes this port to proc. An error is signaled if the file does not exist or cannot be opened for input. If proc returns, call-with-input-file closes the input port and returns the value returned by proc.

call-with-input-file does not automatically close the input 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 input port only if it can prove that the input 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 example shows the use of call-with-input-file in an expression that gathers a list of objects from the file named by "myfile.ss." It is functionally equivalent to the example given for close-input-port above.

 (call-with-input-file "myfile.ss"   (lambda (p)     (let f ((x (read p)))       (if (eof-object? x)           '()           (cons x (f (read p))))))) 

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

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

(with-input-from-file filename thunk)	procedure
returns: the value returned by thunk

filename must be a string.

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

The behavior of with-input-from-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 input port to its old value|but it may not.

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

(read)	procedure
(read input-port)	procedure
returns: the next object from input-port

If input-port is not supplied, it defaults to the current input port. If input-port is at end of file, an eof object is returned. See the examples given for close-input-port and call-with-input-file.

(read-char)	procedure
(read-char input-port)	procedure
returns: the next character from input-port

If input-port is not supplied, it defaults to the current input port. If input-port is at end of file, an eof object is returned. See the examples given for peek-char and write-char.

(peek-char)	procedure
(peek-char input-port)	procedure
returns: the next character from input-port

If input-port is not supplied, it defaults to the current input port. If input-port is at end of file, an eof object is returned.

In contrast to read-char, peek-char does not consume the character it reads from input-port; a subsequent call to peek-char or read-char returns the same character.

peek-char is provided for applications requiring one character of lookahead. The procedure read-word defined below returns the next word from an input port as a string, where a word is defined to be a sequence of alphabetic characters. Since read-word does not know until it sees one character beyond the word that it has read the entire word, it uses peek-char to determine the next character and read-char to consume the character.

 (define read-word   (lambda (p)     (list->string       (let f ()         (let ((c (peek-char p)))           (cond             ((eof-object? c) '())             ((char-alphabetic? c)              (read-char p)              (cons c (f)))             (else '()))))))) 

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

An end-of-file object is returned by read, read-char, or peek-char when an input port has reached the end of input. Although end-of-file objects need not be distinct from other object types, they are unique in the sense that they cannot be confused with objects that may be returned by read, read-char, or peek-char when the input port has not reached the end of input. For example, if (eof-object? x) is #t, (eq? x #\a) must be false but (char? x) may be true or false.

(char-ready?)	procedure
(char-ready? input-port)	procedure
returns: #t if a character is available on input-port, #f otherwise

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

char-ready? allows a program to look for character input on an interactive port without hanging. If char-ready? returns #t, the next peek-char or read-char operation on input-port will not be delayed. If input-port is at end of file, char-ready? returns #t. char-ready? appears in the Revised⁵ Report but not in the ANSI/IEEE standard.