Structural Informatics Group (SIG) logo
Home | Projects | Demos | Downloads | Publications | Local Info | About Us | New site
Go to the first, previous, next, last section, table of contents.

read

read

type: function (subr) 
location: built-in
source file: xlfio.c  and  xlread.c
Common LISP compatible: similar
supported on: all machines

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 )

DESCRIPTION

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.

EXAMPLES

(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>.


Go to the first, previous, next, last section, table of contents.