XLISP read

Nyquist / XLISP 2.0 - Contents | Tutorials | Examples | Reference

# 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

Nyquist / XLISP 2.0 - Contents | Tutorials | Examples | Reference