Go to the previous, next section.

Input Procedures

This section describes the procedures that read input. Input procedures 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.

Input ports can be divided into two types, called interactive and 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 input-port, if not supplied, default to the current input port.

procedure: read-char [input-port]

Returns the next character available from input-port, updating input-port to point to the following character. If no more characters are available, an end-of-file object is returned.

In MIT Scheme, if input-port is an interactive input port and no characters are immediately available, read-char will hang waiting for input.

procedure: peek-char [input-port]

Returns the next character available from input-port, without updating input-port to point to the following character. If no more characters are available, an end-of-file object is returned.(17)

In MIT Scheme, if input-port is an interactive input port and no characters are immediately available, peek-char will hang waiting for input.

procedure: char-ready? [input-port]

Returns #t if a character is ready on input-port and returns #f otherwise. If char-ready? returns #t then the next read-char operation on input-port is guaranteed not to hang. If input-port is a file port at end of file then char-ready? returns #t.(18)

procedure: read [input-port]

Converts external representations of Scheme objects into the objects themselves. read returns the next object parsable from input-port, updating input-port to point to the first character past the end of the written representation of the object. If an end of file is encountered in the input before any characters are found that can begin an object, read returns an end-of-file object. The input-port remains open, and further attempts to read will also return an end-of-file object. If an end of file is encountered after the beginning of an object's written representation, but the written representation is incomplete and therefore not parsable, an error is signalled.

procedure: eof-object? object

Returns #t if object is an end-of-file object; otherwise returns #f.

procedure+: read-char-no-hang [input-port]

If input-port can deliver a character without blocking, this procedure acts exactly like read-char, immediately returning that character. Otherwise, #f is returned, unless input-port is a file port at end of file, in which case an end-of-file object is returned. In no case will this procedure block waiting for input.

procedure+: read-string char-set [input-port]

Reads characters from input-port until it finds a terminating character that is a member of char-set (see section Character Sets) or encounters end of file. The port is updated to point to the terminating character, or to end of file if no terminating character was found. read-string returns the characters, up to but excluding the terminating character, as a newly allocated string. However, if end of file was encountered before any characters were read, read-string returns an end-of-file object.

On many input ports, this operation is significantly faster than the following equivalent code using peek-char and read-char:

(define (read-string char-set input-port)
  (let ((char (peek-char input-port)))
    (if (eof-object? char)
        char
        (list->string
         (let loop ((char char))
           (if (or (eof-object? char)
                   (char-set-member? char-set char))
               '()
               (begin
                 (read-char input-port)
                 (cons char (loop (peek-char input-port))))))))))

Go to the previous, next section.