REF IO Titch Le Bek, Rob Duncan, 1986 COPYRIGHT University of Sussex 1993. All Rights Reserved. >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< LISP INPUT AND OUTPUT >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< PROCEDURES >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<< >>>>>>>>>>>>>>>>>>>>>> <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< This file briefly describes the functions, variables and constants documented in Chapter 22 of the standard Common Lisp guide, which is: Common Lisp: The Language (Guy L. Steele, Digital Press, 1984). ------------------------------------------------- 1 A Listing of Functions Variables and Constants ------------------------------------------------- *print-array* [variable] Controls the printing of array values. If nil, then the contents of arrays other than strings are never printed; if non-nil, then all arrays are fully displayed. Initial value: t *print-base* [variable] The value of *print-base*, which must be an integer from 2 to 36 inclusive, determines in what radix the printer will display rationals. For radices above 10, the letters A to Z are used to represent digits above 9. Initial value: 10 *print-case* [variable] Controls the case in which upper-case characters in the internal print names of symbols are displayed. Its value must be one of :upcase, :downcase or :capitalize, and any upper-case characters are accordingly displayed in upper-case, lower-case or in mixed case so as to capitalize words. Initial value: :upcase. *print-circle* [variable] If nil, the printer will not attempt to spot cycles in structures being printed and will fail to terminate on circular structures. If non-nil, cycles will be detected and displayed using the `#n=' and `#n#' syntax. Initial value: nil. *print-escape* [variable] Controls the printing of escape characters in symbols. If nil, then escape characters are not printed at all; if non-nil, the output is such that a subsequent read would return an equal structure. The function princ effectively binds *print-escape* to nil; prin1 binds it to t. Initial value: t *print-gensym* [variable] Controls the printing of symbols which have no home package: if the value is non-nil, such symbols are printed with the prefix `#:'. Initial value: t. *print-length* [variable] If this variable is set to an integer value, then the printer will display at most that number of elements from each structure printed; extra elements are indicated by three dots. If set to nil then all elements are displayed. Initial value: nil. *print-level* [variable] If this variable is set to an integer value, then the printer will display at most that number of levels of each nested structure printed, where the initial structure counts as level 0, each of its components as level 1 and so on. Any object which occurs at a level greater than or equal to *print-level* and which itself has components is printed as `#'. If *print-level* is nil then all structures are completely displayed. Initial value: nil. *print-lines* [variable] When given a value other than its initial value of nil, *print-lines* limits the number of output lines produced when something is pretty printed. If an attempt is made to go beyond *print-lines* lines, ` ..' (a space and two periods) is printed at the end of the last line followed by all of the suffixes (closing delimiters) that are pending to be printed. *print-miser-width* [variable] If *print-miser-width* is not nil, the pretty printer switches to a compact style of output (called miser style) whenever the width available for printing a substructure is less than or equal to *print-miser-width*. *print-pprint-dispatch* [variable] When *print-pretty* is not nil, printing is controlled by the `pprint dispatch table' stored in *print-pprint-dispatch*. The initial-value is implementation-dependent and causes traditional pretty printing of Lisp code. *print-pretty* [variable] If this variable is nil, then only the minimum amount of whitespace is output when an expression is printed. If set to a non-nil value, the n the printer will use extra whitespace (and make some other minor changes) to make the expression more readable. Initial value: t. *print-radix* [variable] If this variable is non-nil, the printer will indicate against each rational number displayed, the radix which it has used. For a number n printed with radix r, the general output format is `#rrn'; for binary, octal and hex numbers this is shortened to `#bn', `#on' and `#xn' as appropriate. Integers printed in base 10 are indicated simply by a trailing decimal point. Initial value: nil. *print-readably* [variable] The initial value of *print-readably* is nil. If it is true, then printing any object must either produce a printed representation that the reader will accept or signal an error (of type print-not-readable). *print-right-margin* [variable] When *print-right-margin* is not nil, it specifies the right margin to use when making layout decisions. When *print-right-margin* is nil (the initial value), the right margin is set at the maximum line length that can be displayed by the output stream without wraparound or truncation. If this cannot be determined, the right margin is set to an implementation-dependent value. *read-base* [variable] The value of this variable controls the interpretation of tokens by read as being integers or ratios. It may take any integer value between 2 and 36 inclusive, and the value is the radix in which integers and ratios are to be read. It does not change the interpretation of floating-point numbers, which are always read as decimals, nor does it affect numbers which are entered with an explicit radix specifier (#O, #X, #B, #nR or a trailing decimal point). For radices greater than 10, the letters A to Z are used to stand for digits greater than 9; this means that tokens which would normally be read as symbols can be read as numbers. Initial value: 10. *read-default-float-format* [variable] Must be set to a type specifier symbol for floating point numbers. It indicates the format in which the reader should interpret floating-point numbers without exponent markers or with the e or E marker; numbers which have other exponent markers are always read in the format specified by the marker. The printer also uses this variable to guide the printing of exponent markers on floating-point numbers. Initial value: single-float. *read-eval* [variable] If nil, the read macro `#.' does not evaluate the following form, but signals an error instead. Initial value: t. *read-suppress* [variable] If this variable is set to a non-nil value, most of the features of the reader are suppressed; input characters are parsed, but much of what is read is not interpreted. Its primary function is to support the constructs `#+' and `#-' which may want to skip over portions of input text which are not strictly legal. Initial value: nil. *readtable* [variable] The value of *readtable* is the current readtable. Its initial value is a table set up for the standard Common Lisp syntax; rebinding it will change the readtable being used. (clear-input &optional stream) [function] Clears any buffered input associated with stream and returns nil. (clear-output &optional stream) [function] Attempts to ensure that all output sent to stream has reached its destination and only then returns nil. (copy-readtable &optional from-readtable to-readtable) [function] A copy is made of from-readtable. If it is nil then a copy of a standard Common Lisp readtable is made. If to-readtable is unsupplied or nil, a new readtable is made. Otherwise to-readtable must be a readtable which is destructively copied into. (finish-output &optional stream) [function] Returns nil when all output sent to stream has reached its destination. (force-output &optional stream) [function] Initiates the emptying of any internal buffers in the output stream stream (which defaults to *standard-output*) but returns nil without waiting for completion. (format destination string &rest args) [function] Formats string and sends it to destination. The printed representation of args may occur in the result. (fresh-line &optional stream) [function] Outputs a new line unless the output stream stream is at the start of a line. (get-dispatch-macro-character disp-character sub-character [function] function &optional readtable) Returns the macro-character function for sub-character under disp-character or nil if there is no such function associated with sub-character. (get-macro-character character &optional readtable) [function] Returns the function associated with character and the non-terminating-p flag. Returns nil if character does not have macro-character status. Readtable defaults to the current readtable. (listen &optional stream) [function] Returns true if there is a character immediately available from the input stream stream and false if not. It is particularly useful when stream obtains characters from an interactive device such as a keyboard. (make-dispatch-macro-character character &optional [function] non-terminating-p readtable) This causes character to be a dispatching macro character in readtable. If non-terminating-p is not nil then it will be a non-terminating macro character. make-dispatch-macro-character returns t. (parse-integer string &key :start :end :radix :junk-allowed) [function] Examines the substring of string delimited by :start and :end. It skips over whitespace characters and then attempts to parse an integer. :radix defaults to 10 and must be an integer between 2 and 36. If :junk-allowed is not nil then the first value returned is the value of the number parsed as an integer or nil if no syntactically correct integer was seen. If :junk-allowed is nil then the entire substring is scanned. The value of the substring parsed as an integer is returned. An error is signaled if the substring does not consist entirely of the representation of an integer. In either case the second value returned is the index into string of the delimiter that terminated the parse, or it is the index beyond the substring if the parse terminated at the end of the substring. (peek-char &optional type stream error value recursive-p) [function] If the peek type type is nil, peek-char returns the next character to be read from the input stream stream. The next time input is done from stream the character will still be there. If type is t then peek-char skips over whitespace characters and performs the peeking operation on the next character. It is useful for finding the beginning of the next printed representation of a Lisp object. If type is a character object then peek-char skips over input characters until a character that is char= to that object is found; that character is left in stream. (pprint object &optional stream) [function] Like print except that the trailing space is omitted and object is printed with the *print-pretty* flag non-nil to produce "pretty" output. pprint returns no values. (prin1 object &optional stream) [function] prin1 outputs the printed representation of object to the output stream stream. (prin1-to-string object) [function] object is printed as if by prin1 but the characters that would be output are made into a string which is returned. (princ object &optional stream) [function] Like prin1 except that the output has no escape characters. A symbol is printed as simply the characters of its print name; a string is printed without surrounding double quotes. The output looks good to people whereas the output from prin1 is intended to be acceptable to the function read. princ returns object. (princ-to-string object) [function] object is printed as if by princ but the characters that would be output are made into a string which is returned. (print object &optional stream) [function] Like prin1 except that the printed representation of object is preceded by a new line and followed by a space. print returns object. (print-unreadable-object (object stream &key :type identity) [macro] {declaration}* {form}*) This macro is used to output a terse non-readable representation of object to stream. print-unreadable-object first writes #< to stream, then executes {form}*, and finally writes a closing > to stream. If :type is true, the body output is preceded by a brief description of object's type, and a space character. If :identity is true, the body output is followed by a space character and then an indication of the objects unique identity (typically an integer derived from its storage address). If *print-readably* is true, print-unreadable-object signals an error of type print-not-readable. (read &optional stream error value recursive) [function] read reads in the printed representation of a Lisp object from the input stream stream, builds a corresponding Lisp object, and returns the object. error controls what happens if input is from a file and the end of the file is reached. If it is true an error is signaled at end of file, otherwise value is returned. recursive, if not nil, specifies that this is not a top-level call to read but an embedded call, typically from the function for a macro character. (readtable-case readtable) [function] Returns a keyword symbol that indicates how readtable processes unescaped upper or lower case characters. There are four possible values: :upcase, :downcase, :preserve, and :invert. (read-byte stream &optional error value) [function] Reads one byte from the binary input stream stream and returns it in the form of an integer. error controls what happens if input is from a file and the end of the file is reached. If the value of error is true then an error is signaled at end of file, otherwise value is returned. (read-char &optional stream error value recursive) [function] read-char inputs one character from the input stream stream and returns it as a character object. The corresponding output function is write-char. error controls what happens if input is from a file and the end of the file is reached. If error is true an error is signaled at end-of-file, otherwise value is returned. recursive, if not nil, specifies that this is not a top-level call to read but an embedded call, typically from the function for a macro character. (read-char-no-hang &optional stream error value recursive) [function] read-char-no-hang is exactly like read-char except that if it is necessary to wait in order to get a character, nil is immediately returned without waiting. This allows for efficient checking for input availability. If error is true an error is signaled at end of file, otherwise value is returned. recursive, if not nil, specifies that this is not a top-level call to read but an embedded call, typically from the function for a macro character. (read-delimited-list character &optional stream recursive) [function] Reads objects from stream until the next character after an object's representation is character. A list of the objects read is returned. recursive, if not nil, specifies that this is not a top-level call to read but an embedded call, typically from the function for a macro character. (read-from-string string &optional error value [function] &key :start :end :preserve-whitespace) The characters of string are given successively to the Lisp reader, and the Lisp object built by the reader is returned. The second value returned is the index of the first character in the string not read. error and value control the action if the end of the (sub)string is reached before the operation is completed. (read-line &optional stream error value recursive) [function] read-line reads in a line of text terminated by a newline. It returns the line as a character string. It is usually used to get a line of input from the user. A second returned value is a flag that is false if the line was terminated normally, or true if end-of-file terminated the line. If end-of-file is encountered immediately then end-of-file processing is controlled by error and value. (read-preserving-whitespace &optional stream error value [function] recursive) This function is provided for some specialized situations where it is desireable to determine precisely what character terminated the extended token. The distinction between it and read is established only by calls with recursive equal to nil or omitted. (readtablep object) [function] Returns t if object is a readtable; nil otherwise. (set-dispatch-macro-character disp-character sub-character [function] function &optional readtable) Modifies readtable so that function is called whenever disp-character followed by sub-character is read. readtable defaults to the current readtable. Returns t. (set-macro-character character function [function] &optional non-terminating-p readtable) Causes character to be a macro character that when seen by read causes function to be called. If non-terminating-p is not nil then it will be a non-terminating macro character. Returns t. (set-syntax-from-char to-character from-character [function] &optional to-readtable from-readtable) Converts the syntax of to-character in to-readtable to be the same as from-character in from-readtable. to-readtable defaults to the current readtable, and from-readtable defaults to nil which means use the syntaxes for the standard Lisp readtable. (stream-element-type stream) [function] Returns a type specifier for the objects that can be read from, or written to, stream. (terpri &optional stream) [function] Outputs a new line to the output stream stream. (unread-char character &optional stream) [function] unread-char puts character onto the front of the input stream stream. character must be the most recently read character from stream. Returns nil. (with-standard-io-syntax {form}*) [macro] Executes the body {form}* as an implicit progn with the "*print-xxx" variables described above locally bound their standard initial values. (write object &key :stream :escape :radix :base [function] :circle :pretty :level :length :case :gensym :array) Returns a printed representation of object written to the output stream. Returns object. (write-byte integer stream) [function] Writes one byte, the value of integer. It is an error if integer is not of the type specified as the element-type argument to open when the binary output stream stream was created. The value integer is returned. (write-char character &optional stream) [function] Outputs character to the output stream stream and returns character. (write-line string &optional stream &key :start :end) [function] Writes the characters of the specified substring of string to the output stream stream and prints a new line. (write-string string &optional stream &key :start :end) [function] Writes characters of the specified substring of string to the output stream stream. (write-to-string object &key :escape :radix :base [function] :circle :pretty :level :length :case :gensym :array) object is printed as if by write but the characters that are output are made into a string which is returned. (y-or-n-p &optional format-string &rest args) [function] This predicate is for asking the user a question whose answer is either "yes" or "no". It prints out a message, reads an answer, and returns t if the answer was "yes", or nil if the answer was "no". If format-string is not nil, then a fresh-line operation is performed and format-string is printed as if it and args were given to format. Otherwise it is assumed that any message has already been printed by other means. (yes-or-no-p &optional format-string &rest args) [function] This predicate is like y-or-n-p. It is intended that the reply require the user to take more action than just a single keystroke, such as typing the full word "yes" or "no". It should therefore be used for unanticipated or important questions that need to attract the users attention. --- C.all/lisp/ref/io --- Copyright University of Sussex 1993. All rights reserved.