Skip to main content

listen

listen Function

Syntax:

listen &optional input-stream → generalized-boolean

Arguments and Values:

input-stream—an input stream designator . The default is standard input.

generalized-boolean—a generalized boolean.

Description:

Returns true if there is a character immediately available from input-stream; otherwise, returns false. On a non-interactive input-stream, listen returns true except when at end of file1. If an end of file is encountered, listen returns false. listen is intended to be used when input-stream obtains characters from an interactive device such as a keyboard.

Examples:

(progn (unread-char (read-char)) (list (listen) (read-char))) 
▷ 1 
→ (T #\1) 
(progn (clear-input) (listen)) 
→ NIL ;Unless you’re a very fast typist!

Affected By:

*standard-input*

See Also:

interactive-stream-p, read-char-no-hang

clear-input

Expanded Reference: listen​

Basic Usage​

listen returns true if a character is immediately available from the input stream; otherwise returns false.

;; A string input stream always has characters available until exhausted
(let ((s (make-string-input-stream "abc")))
  (list (listen s)
        (read-char s)
        (read-char s)
        (read-char s)
        (listen s)))
=> (T #\a #\b #\c NIL)

After unread-char​

A character put back with unread-char makes listen return true.

(with-input-from-string (s "x")
  (read-char s)
  (let ((before (listen s)))
    (unread-char #\x s)
    (list before (listen s))))
=> (NIL T)

End of File​

At end of file, listen returns false.

(listen (make-string-input-stream ""))
=> NIL

Intended for Interactive Use​

listen is primarily useful with interactive streams (e.g., keyboards) to check if the user has typed something without blocking. On non-interactive streams, it returns true unless at end of file.