read

Type:	-	function (subr)
Source:	-	xlfio.c, xlread.c

Syntax

(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
returns - the expression read

Description

The 'read' function reads an expression from the specified 'source'. The expression read is a normal XLISP expression, not necessarily a line. This means that white space is removed, where 'white space' is blanks, empty lines and comment lines. Read-macro expansions will occur. 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 the read-line or read-char functions.

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 , 'read' does not expect itself to be at a 'top-level', but recursively executing within another 'read' that is in progress.

Examples

(setq fp (open "f" :direction :output))  ; set up file
(print "hello" fp)                       ; and fill it with stuff
(print 12.34 fp)
(princ "'(a b" fp) (terpri fp)
(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 the macro expansion of QUOTE
                                         ;   note that "; comment" is gone
(read fp "done")                         ; returns "done"
(close fp)

Common Lisp: 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 additional 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' function. 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: 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* which is not defined in XLISP by default. XLISP does not allow  T  as a valid argument for 'source'.

See the read function in the XLISP 2.0 manual.

  Back to Top