User Tools


Differences

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

Link to this comparison view

cl:variables:star-debug-io-star [2017/05/01 21:00] (current)
Line 1: Line 1:
 +====== Variable *DEBUG-IO*, *ERROR-OUTPUT*,​ *QUERY-IO*, *STANDARD-INPUT*,​ *STANDARD-OUTPUT*,​ *TRACE-OUTPUT* ======
 +
 +====Value Type====
 +For **<​nowiki>​*standard-input*</​nowiki>​**:​ an //​[[CL:​Glossary:​input]]//​ //​[[CL:​Glossary:​stream]]//​
 +
 +For **<​nowiki>​*error-output*</​nowiki>​**,​ **<​nowiki>​*standard-output*</​nowiki>​**,​ and **<​nowiki>​*trace-output*</​nowiki>​**:​ an //​[[CL:​Glossary:​output]]//​ //​[[CL:​Glossary:​stream]]//​.
 +
 +For **<​nowiki>​*debug-io*</​nowiki>​**,​ **<​nowiki>​*query-io*</​nowiki>​**:​ a //​[[CL:​Glossary:​bidirectional]]//​ //​[[CL:​Glossary:​stream]]//​.
 +
 +====Initial Value====
 +//​[[CL:​Glossary:​implementation-dependent]]//,​ but it must be an //​[[CL:​Glossary:​open]]//​ //​[[CL:​Glossary:​stream]]//​ that is not a //​[[CL:​Glossary:​generalized synonym stream]]// to an //​[[CL:​Glossary:​I/​O customization variables]]//​ but that might be a //​[[CL:​Glossary:​generalized synonym stream]]// to the value of some //​[[CL:​Glossary:​I/​O customization variable]]//​. The initial value might also be a //​[[CL:​Glossary:​generalized synonym stream]]// to either the //​[[CL:​Glossary:​symbol]]//​ **[[CL:​Variables:​star-terminal-io-star|*terminal-io*]]** or to the //​[[CL:​Glossary:​stream]]//​ that is its //​[[CL:​Glossary:​value]]//​.
 +
 +====Description====
 +These //​[[CL:​Glossary:​variables]]//​ are collectively called the //​[[CL:​Glossary:​standardized]]//​ //​[[CL:​Glossary:​I/​O customization variables]]//​. They can be //​[[CL:​Glossary:​bound]]//​ or //​[[CL:​Glossary:​assigned]]//​ in order to change the default destinations for input and/or output used by various //​[[CL:​Glossary:​standardized]]//​ //​[[CL:​Glossary:​operators]]//​ and facilities.
 +
 +The //​[[CL:​Glossary:​value]]//​ of **<​nowiki>​*debug-io*</​nowiki>​**,​ called //​[[CL:​Glossary:​debug I/O]]//, is a //​[[CL:​Glossary:​stream]]//​ to be used for interactive debugging purposes.
 +
 +The //​[[CL:​Glossary:​value]]//​ of **<​nowiki>​*error-output*</​nowiki>​**,​ called //​[[CL:​Glossary:​error output]]//, is a //​[[CL:​Glossary:​stream]]//​ to which warnings and non-interactive error messages should be sent.
 +
 +The //​[[CL:​Glossary:​value]]//​ of **<​nowiki>​*query-io*</​nowiki>​**,​ called //​[[CL:​Glossary:​query I/O]]//, is a //​[[CL:​Glossary:​bidirectional]]//​ //​[[CL:​Glossary:​stream]]//​ to be used when asking questions of the user. The question should be output to this //​[[CL:​Glossary:​stream]]//,​ and the answer read from it.
 +
 +The //​[[CL:​Glossary:​value]]//​ of **<​nowiki>​*standard-input*</​nowiki>​**,​ called //​[[CL:​Glossary:​standard input]]//, is a //​[[CL:​Glossary:​stream]]//​ that is used by many //​[[CL:​Glossary:​operators]]//​ as a default source of input when no specific //​[[CL:​Glossary:​input]]//​ //​[[CL:​Glossary:​stream]]//​ is explicitly supplied.
 +
 +The //​[[CL:​Glossary:​value]]//​ of **<​nowiki>​*standard-output*</​nowiki>​**,​ called //​[[CL:​Glossary:​standard output]]//, is a //​[[CL:​Glossary:​stream]]//​ that is used by many //​[[CL:​Glossary:​operators]]//​ as a default destination for output when no specific //​[[CL:​Glossary:​output]]//​ //​[[CL:​Glossary:​stream]]//​ is explicitly supplied.
 +
 +The //​[[CL:​Glossary:​value]]//​ of **<​nowiki>​*trace-output*</​nowiki>​**,​ called //​[[CL:​Glossary:​trace output]]//, is the //​[[CL:​Glossary:​stream]]//​ on which traced functions (see **[[CL:​Macros:​trace]]**) and the //​[[CL:​Glossary:​macro]]//​ **[[CL:​Macros:​time]]** print their output.
 +
 +====Examples====
 +<​blockquote> ​
 +([[CL:​Macros:​with-output-to-string]] (*error-output*) ​
 +  ([[CL:​Functions:​warn]] "this string is sent to *error-output*"​)) ​
 +→ "​Warning:​ this string is sent to *error-output* " ​
 +</​blockquote> ​
 +
 +The exact format of the above string is //​[[CL:​Glossary:​implementation-dependent]]//​.
 +
 +<​blockquote> ​
 +([[CL:​Macros:​with-input-from-string]] (*standard-input* "​1001"​) ​
 +  (+ 990 (read))) → 1991
 +([[CL:​Macros:​defvar]] *out* 
 +  ([[CL:​Macros:​with-output-to-string]] (*standard-output*) ​
 +    ([[CL:​Functions:​print]] "print and format t send things to"​) ​
 +    ([[CL:​Functions:​format]] [[CL:​Constant Variables:​t]] "​*standard-output* now going to a string"​))) <​r>​*OUT*</​r>​
 +*out* <​r>"​
 +\"​print and format t send things to\" *standard-output* now going to a string"​ </r>
 +</​blockquote> ​
 +
 +The exact format of the resulting //​[[CL:​Glossary:​trace]]//​ //​[[CL:​Glossary:​output]]//​ of the below example is //​[[CL:​Glossary:​implementation-dependent]]//​.
 +
 +<​blockquote> ​
 +([[CL:​Macros:​defun]] fact (n) 
 +  ([[CL:​Special Operators:​if]] ([[CL:​Functions:​math-less|<​]] n 2) 
 +      1 
 +      ([[CL:​Functions:​math-multiply|*]] n (fact ([[CL:​Functions:​math-subtract|-]] n 1))))) → FACT 
 +([[CL:​Macros:​trace]] fact) → (FACT)  ​
 +([[CL:​Functions:​with-output-to-string]] (*trace-output*) ​
 +  (fact 3)) 
 +" 1 Enter FACT 3 
 +  | 2 Enter FACT 2 
 +    | 3 Enter FACT 1 
 +    | 3 Exit FACT 1 
 +  | 2 Exit FACT 2 
 +1 Exit FACT 6"
 +</​blockquote>​
 +
 +====See Also====
 +  * **[[CL:​Variables:​star-terminal-io-star|Variable *TERMINAL-IO*]]**
 +  * **[[CL:​Types:​synonym-stream|System Class SYNONYM-STREAM]]**
 +  * **[[CL:​Macros:​time|Macro TIME]]**
 +  * **[[CL:​Macros:​trace|Macro TRACE]]**
 +  * {\chapref\Conditions}
 +  * {\chapref\Reader}
 +  * {\chapref\Printer}
 +
 +====Notes====
 +The intent of the constraints on the initial //​[[CL:​Glossary:​value]]//​ of the //​[[CL:​Glossary:​I/​O customization variables]]//​ is to ensure that it is always safe to //​[[CL:​Glossary:​bind]]//​ or //​[[CL:​Glossary:​assign]]//​ such a //​[[CL:​Glossary:​variable]]//​ to the //​[[CL:​Glossary:​value]]//​ of another //​[[CL:​Glossary:​I/​O customization variable]]//,​ without unduly restricting //​[[CL:​Glossary:​implementation]]//​ flexibility.
 +
 +It is common for an //​[[CL:​Glossary:​implementation]]//​ to make the initial //​[[CL:​Glossary:​values]]//​ of **<​nowiki>​*debug-io*</​nowiki>​** and **<​nowiki>​*query-io*</​nowiki>​** be the //​[[CL:​Glossary:​same]]//​ //​[[CL:​Glossary:​stream]]//,​ and to make the initial //​[[CL:​Glossary:​values]]//​ of **<​nowiki>​*error-output*</​nowiki>​** and **<​nowiki>​*standard-output*</​nowiki>​** be the //​[[CL:​Glossary:​same]]//​ //​[[CL:​Glossary:​stream]]//​.
 +
 +The functions **[[CL:​Functions:​y-or-n-p]]** and **[[CL:​Functions:​yes-or-no-p]]** use //​[[CL:​Glossary:​query I/O]]// for their input and output.
 +
 +In the normal //​[[CL:​Glossary:​Lisp read-eval-print loop]]//, input is read from //​[[CL:​Glossary:​standard input]]//. Many input functions, including **[[CL:​Functions:​read]]** and **[[CL:​Functions:​read-char]]**,​ take a //​[[CL:​Glossary:​stream]]//​ argument that defaults to //​[[CL:​Glossary:​standard input]]//.
 +
 +In the normal //​[[CL:​Glossary:​Lisp read-eval-print loop]]//, output is sent to //​[[CL:​Glossary:​standard output]]//. Many output functions, including **[[CL:​Functions:​print]]** and **[[CL:​Functions:​write-char]]**,​ take a //​[[CL:​Glossary:​stream]]//​ argument that defaults to //​[[CL:​Glossary:​standard output]]//.
 +
 +A program that wants, for example, to divert output to a file should do so by //​[[CL:​Glossary:​binding]]//​ **<​nowiki>​*standard-output*</​nowiki>​**;​ that way error messages sent to **<​nowiki>​*error-output*</​nowiki>​** can still get to the user by going through **[[CL:​Variables:​star-terminal-io-star|*terminal-io*]]** (if **<​nowiki>​*error-output*</​nowiki>​** is bound to **[[CL:​Variables:​star-terminal-io-star|*terminal-io*]]**),​ which is usually what is desired.
 +
 +\issue{STANDARD-INPUT-INITIAL-BINDING:​DEFINED-CONTRACTS} \issue{STANDARD-INPUT-INITIAL-BINDING:​DEFINED-CONTRACTS}