User Tools


Differences

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

Link to this comparison view

cl:functions:peek-char [2019/06/15 02:00]
cl:functions:peek-char [2019/11/19 12:00] (current)
Line 1: Line 1:
 +====== Function PEEK-CHAR ======
 +
 +====Syntax====
 +  * **peek-char** ''&​optional''​ //​peek-type//​ //​input-stream//​ //​eof-error-p//​ //​eof-value//​ //​recursive-p//​ → //char//
 +
 +====Arguments and Values====
 +  * //​peek-type//​ - a //​[[CL:​Glossary:​character]]//​ or **[[CL:​Constant Variables:​t]]** or **[[CL:​Constant Variables:​nil]]**.
 +  * //​input-stream//​ - //​[[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====
 +**peek-char** obtains the next character in //​input-stream//​ without actually reading it, thus leaving the character to be read at a later time. It can also be used to skip over and discard intervening characters in the //​input-stream//​ until a particular character is found.
 +
 +If //​peek-type//​ is not supplied or **[[CL:​Constant Variables:​nil]]**,​ **peek-char** returns the next character to be read from //​input-stream//,​ without actually removing it from //​input-stream//​. The next time input is done from //​input-stream//,​ the character will still be there.
 +
 +If //​peek-type//​ is **[[CL:​Constant Variables:​t]]**,​ then **peek-char** skips over //​[[CL:​Glossary:​whitespace]]//​ //​[[CL:​Glossary:​character|characters]]//,​ but not comments, and then performs the peeking operation on the next character. The last character examined, the one that starts an //​[[CL:​Glossary:​object]]//,​ is not removed from //​input-stream//​.
 +
 +If //​peek-type//​ is a //​[[CL:​Glossary:​character]]//,​ then **peek-char** skips over input characters until a character that is **[[CL:​Functions:​char=]]** to that //​[[CL:​Glossary:​character]]//​ is found; that character is left in //​input-stream//​.
 +
 +If an //​[[CL:​Glossary:​end of file]]// occurs and //​eof-error-p//​ is //​[[CL:​Glossary:​false]]//,​ //​eof-value//​ is returned.
 +
 +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]]//.
 +
 +When //​input-stream//​ is an //​[[CL:​Glossary:​echo stream]]//, characters that are only peeked at are not echoed. In the case that //​peek-type//​ is not **[[CL:​Constant Variables:​nil]]**,​ the characters that are passed by **peek-char** are treated as if by **[[CL:​Functions:​read-char]]**,​ and so are echoed unless they have been marked otherwise by **[[CL:​Functions:​unread-char]]**.
 +
 +====Examples==== ​
 +<​blockquote> ​
 +([[CL:​Macros:​with-input-from-string]] (input-stream " 1 2 3 4 5"​) ​
 +  ([[CL:​Functions:​format]] [[CL:​Constant Variables:​t]] "~S ~S ~S" ​
 +          (peek-char t input-stream) ​
 +          (peek-char #\4 input-stream) ​
 +          (peek-char nil input-stream)))
 +<​o>#​\1 #\4 #\4 </o>
 +<​r>​NIL </r>
 +</​blockquote>​
 +
 +====Affected By====
 +**[[CL:​Variables:​star-readtable-star|*readtable*]]**,​ **[[CL:​Variables:​star-standard-input-star|*standard-input*]]**, ​
 +**[[CL:​Variables:​star-terminal-io-star|*terminal-io*]]**.
 +
 +====Exceptional Situations====
 +If //​eof-error-p//​ is //​[[CL:​Glossary:​true]]//​ and an //​[[CL:​Glossary:​end of file]]// occurs an error of type **[[CL:​Types:​end-of-file]]** is signaled.
 +
 +If //​peek-type//​ is a //​[[CL:​Glossary:​character]]//,​ an //​[[CL:​Glossary:​end of file]]// occurs, and //​eof-error-p//​ is //​[[CL:​Glossary:​true]]//,​ an error of type **[[CL:​Types:​end-of-file]]** is signaled.
 +
 +If //​recursive-p//​ is //​[[CL:​Glossary:​true]]//​ and an //​[[CL:​Glossary:​end of file]]// occurs, an error of type **[[CL:​Types:​end-of-file]]** is signaled.
 +
 +====See Also====
 +None.
 +
 +====Notes====
 +None.
 +
 +\issue{ARGUMENTS-UNDERSPECIFIED:​SPECIFY} \issue{PEEK-CHAR-READ-CHAR-ECHO:​FIRST-READ-CHAR}