Skip to main content

read-char-no-hang

read-char-no-hang Function Syntax:

read-char-no-hang &optional input-stream eof-error-p eof-value recursive-p

Arguments and Values:

→ char

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

eof-error-p—a generalized boolean. The default is true.

eof-value—an object. The default is nil.

recursive-p—a generalized boolean. The default is false.

char—a character or nil or the eof-value.

Description:

read-char-no-hang returns a character from input-stream if such a character is available. If no character is available, read-char-no-hang returns nil.

If recursive-p is true, this call is expected to be embedded in a higher-level call to read or a similar function used by the Lisp reader .

If an end of file2 occurs and eof-error-p is false, eof-value is returned.

Examples:

;; This code assumes an implementation in which a newline is not 
;; required to terminate input from the console. 
(defun test-it () 
  (unread-char (read-char)) 
  (list (read-char-no-hang) 
	(read-char-no-hang) 
	(read-char-no-hang))) 
→ TEST-IT 
;; Implementation A, where a Newline is not required to terminate 
;; interactive input on the console. 
(test-it) 
▷ a 
→ (#\a NIL NIL) 
;; Implementation B, where a Newline is required to terminate 
;; interactive input on the console, and where that Newline remains 
;; on the input stream. 
(test-it) 
▷ a← 
→ (#\a #\Newline NIL)

Affected By:

*standard-input*, *terminal-io*.

Exceptional Situations:

If an end of file2 occurs when eof-error-p is true, an error of type end-of-file is signaled . See Also:

listen

Notes:

read-char-no-hang is exactly like read-char, except that if it would be necessary to wait in order to get a character (as from a keyboard), nil is immediately returned without waiting.

terpri, fresh-line

Expanded Reference: read-char-no-hang​

Basic Usage​

read-char-no-hang is like read-char except that it returns NIL immediately if no character is available (rather than waiting). On non-interactive streams like string streams, it behaves identically to read-char.

(with-input-from-string (s "abc")
  (list (read-char-no-hang s)
        (read-char-no-hang s)
        (read-char-no-hang s)))
=> (#\a #\b #\c)

End of File Handling​

When the stream is exhausted and eof-error-p is false, returns the eof-value.

(with-input-from-string (s "x")
  (list (read-char-no-hang s nil :eof)
        (read-char-no-hang s nil :eof)))
=> (#\x :EOF)

Returns NIL When No Input Available​

On interactive streams, read-char-no-hang returns NIL rather than blocking when no input has been typed. On string streams (non-interactive), it only returns NIL at end of file with eof-error-p false and eof-value being NIL.

;; On a string stream this behaves the same as read-char:
(with-input-from-string (s "")
  (read-char-no-hang s nil nil))
=> NIL

Difference from read-char​

The difference is observable only on interactive streams. On non-interactive streams such as string streams or file streams, read-char-no-hang and read-char behave identically.