type: function (subr) location: built-in source file: xlfio.c and xlread.c Common LISP compatible: similar supported on: all machines
(read [ <source> [ <eof-result> [ <recursive-flag> ] ] ] ) <source> - an optional source - must be a file pointer or stream, the default is *standard-input* <eof-result> - an optional expression (default is NIL) <recursive-flag>- an optional expression ( NIL or non-NIL )
The READ function reads an expression from the specified <source>. The expression read is a 'normal' XLISP expression - not a line. This means that white space is removed - blanks, empty lines and comment lines. Read-macro expansions will occur (like QUOTE instead of '). The expression needs to be an atom (numeric, string or symbol) or a valid list. It can span several lines. The expression read is returned as the result. The <source> may be a file pointer or a stream. If there is no <source>, *STANDARD-INPUT* is the default. If an end-of-file is encountered in the <source>, then the <eof-result> value will be returned as the result.
If you wish to read just lines or characters, refer to READ-LINE or READ-CHAR.
The <recursive-flag> is intended for use with embedded calls to READ. This is useful in read-macro and read-table uses. If <recursive-flag> is non-NIL, the READ does not expect itself to be at a 'top-level', but recursively executing within another READ that is in progress.
(setq fp (open "f" :direction :output)) ; set up file (print "hello" fp) ; (print 12.34 fp) ; (princ "'(a b" fp) (terpri fp) ; fill with stuff (princ "; comment" fp) (terpri fp) ; (princ " c d)" fp ) ; (close fp) ; ; (setq fp (open "f" :direction :input)) ; now read the file (read fp "done") ; returns "hello" (read fp "done") ; returns 12.34 (read fp "done") ; returns (QUOTE (A B C D)) ; note macro expansion of QUOTE ; note that comment is gone (read fp "done") ; returns "done" (close fp)
COMMON LISP COMPATIBILITY: The XLISP and Common LISP READ functions are similar. They both allow for <source>, <eof-result> and <recursive-flag>. However, in Common LISP, there is an addition end-of-file error parameter. This parameter occurs right after <source> and specifies whether or not to flag an error on end-of-file. So, when porting, remember there is one additional argument in Common LISP's READ. You need to be concerned about this if you use more than just a <source> argument - going either from XLISP to Common LISP or vice versa.
COMMON LISP COMPATIBILITY: Common LISP specifies that read operations with a <source> of NIL, will come from *STANDARD-INPUT*. XLISP does not read the input from *STANDARD-INPUT* with a <source> of NIL. Common LISP also specifies that a <source> of T will read from *TERMINAL-IO*. XLISP does not allow T as a valid argument for <source>.