User Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

cl:functions:read-char [2019/09/14 05:00]
cl:functions:read-char [2019/09/20 08:00] (current)
Line 1: Line 1:
 +====== Function READ-CHAR ======
 +
 +====Syntax====
 +  * **read-char** ''&​optional''​ //​input-stream//​ //​eof-error-p//​ //​eof-value//​ //​recursive-p//​ → //char//
 +
 +====Arguments and Values====
 +  * //​input-stream//​ - an //​[[CL:​Glossary:​input]]//​ //​[[CL:​Glossary:​stream designator]]//​. The default is //​[[CL:​Glossary:​standard input]]//.
 +  * //​eof-error-p//​ - a //​[[CL:​Glossary:​generalized boolean]]//​. The default is //​[[CL:​Glossary:​true]]//​.
 +  * //​eof-value//​ - an //​[[CL:​Glossary:​object]]//​. The default is **[[CL:​Constant Variables:​nil]]**.
 +  * //​recursive-p//​ - a //​[[CL:​Glossary:​generalized boolean]]//​. The default is //​[[CL:​Glossary:​false]]//​.
 +  * //char// - a //​[[CL:​Glossary:​character]]//​ or the //​eof-value//​.
 +
 +====Description====
 +**read-char** returns the next //​[[CL:​Glossary:​character]]//​ from //​input-stream//​.
 +
 +When //​input-stream//​ is an //echo stream//, the character is echoed on //​input-stream//​ the first time the character is seen. Characters that are not echoed by **read-char** are those that were put there by **[[CL:​Functions:​unread-char]]** and hence are assumed to have been echoed already by a previous call to **read-char**.
 +
 +If //​recursive-p//​ is //​[[CL:​Glossary:​true]]//,​ this call is expected to be embedded in a higher-level call to **[[CL:​Functions:​read]]** or a similar //​[[CL:​Glossary:​function]]//​ used by the //​[[CL:​Glossary:​Lisp reader]]//.
 +
 +If an //​[[CL:​Glossary:​end of file]]// occurs and //​eof-error-p//​ is //​[[CL:​Glossary:​false]]//,​ //​eof-value//​ is returned.
 +
 +====Examples==== ​
 +<​blockquote> ​
 +([[CL:​Macros:​with-input-from-string]] (is "​0123"​) ​
 +  ([[CL:​Macros:​do]] ((c (read-char is) (read-char is [[CL:​Constant Variables:​nil]] '​the-end))) ​
 +      (([[CL:​Functions:​not]] ([[CL:​Functions:​characterp]] c))) 
 +    ([[CL:​Functions:​format]] [[CL:​Constant Variables:​t]] "~S " c)))
 +<​o>#​\0 #\1 #\2 #\3 </o>
 +<​r>​NIL </r>
 +</​blockquote>​
 +
 +====Affected By====
 +**[[CL:​Variables:​star-standard-input-star|*standard-input*]]**,​ **[[CL:​Variables:​star-terminal-io-star|*terminal-io*]]**.
 +
 +====Exceptional Situations====
 +If an //​[[CL:​Glossary:​end of file]]// occurs before a character can be read, and //​eof-error-p//​ is //​[[CL:​Glossary:​true]]//,​ an error of type **[[CL:​Types:​end-of-file]]** is signaled.
 +
 +====See Also====
 +  * **[[CL:​Functions:​read-byte|Function READ-BYTE]]**
 +  * **[[CL:​Functions:​read-sequence|Function READ-SEQUENCE]]**
 +  * **[[CL:​Functions:​write-char|Function WRITE-CHAR]]**
 +  * **[[CL:​Functions:​read|Function READ]]**
 +
 +====Notes====
 +The corresponding output function is **[[CL:​Functions:​write-char]]**.
 +
 +\issue{ARGUMENTS-UNDERSPECIFIED:​SPECIFY} \issue{PEEK-CHAR-READ-CHAR-ECHO:​FIRST-READ-CHAR} \issue{READ-AND-WRITE-BYTES:​NEW-FUNCTIONS}