## Appendix 3: XLISP: An Object-oriented Lisp

> Version 2.0

> February 6, 1988

> by
> David Michael Betz
> 127 Taylor Road
> Peterborough, NH 03458

> (603) 924-6936 (home)

> Copyright (c) 1988, by David Michael Betz
> All Rights Reserved
> Permission is granted for unrestricted non-commercial use

### Introduction

XLISP is an experimental programming language combining some of the features of Common Lisp with an object-oriented extension capability. It was implemented to allow experimentation with object-oriented programming on small computers.

There are currently implementations of XLISP running on the IBM- PC and clones under MS-DOS, on the Macintosh, the Atari-ST and the Amiga. It is completely written in the programming language C and is easily extended with user written built-in functions and classes. It is available in source form to non-commercial users.

Many Common Lisp functions are built into XLISP. In addition, XLISP defines the objects Object and Class as primitives. Object is the only class that has no superclass and hence is the root of the class hierarchy tree. Class is the class of which all classes are instances (it is the only object that is an instance of itself).

This document is a brief description of XLISP. It assumes some knowledge of LISP and some understanding of the concepts of object-oriented programming.

I recommend the book Lisp by Winston and Horn and published by Addison Wesley for learning Lisp. The first edition of this book is based on MacLisp and the second edition is based on Common Lisp. XLISP will continue to migrate towards compatibility with Common Lisp.

You will probably also need a copy of Common Lisp: The Language by Guy L. Steele, Jr., published by Digital Press to use as a reference for some of the Common Lisp functions that are described only briefly in this document.

### A Note From The Author

If you have any problems with XLISP, feel free to contact me [me being David Betz - RBD] for help or advice. Please remember that since XLISP is available in source form in a high level language, many users [e.g. that Dannenberg fellow - RBD] have been making versions available on a variety of machines. If you call to report a problem with a specific version, I may not be able to help you if that version runs on a machine to which I don't have access. Please have the version number of the version that you are running readily accessible before calling me.

If you find a bug in XLISP, first try to fix the bug yourself using the source code provided. If you are successful in fixing the bug, send the bug report along with the fix to me. If you don't have access to a C compiler or are unable to fix a bug, please send the bug report to me and I'll try to fix it.

Any suggestions for improvements will be welcomed. Feel free to extend the language in whatever way suits your needs. However, PLEASE DO NOT RELEASE ENHANCED VERSIONS WITHOUT CHECKING WITH ME FIRST!! I would like to be the clearing house for new features added to XLISP. If you want to add features for your own personal use, go ahead. But, if you want to distribute your enhanced version, contact me first. Please remember that the goal of XLISP is to provide a language to learn and experiment with LISP and object-oriented programming on small computers. I don't want it to get so big that it requires megabytes of memory to run.

### XLISP Command Loop

When XLISP is started, it first tries to load the workspace `xlisp.wks` from the current directory. If that file doesn't exist, XLISP builds an initial workspace, empty except for the built-in functions and symbols.

Then XLISP attempts to load `init.lsp` from the current directory. It then loads any files named as parameters on the command line (after appending `.lsp` to their names).

XLISP then issues the following prompt:

            >

This indicates that XLISP is waiting for an expression to be typed.

When a complete expression has been entered, XLISP attempts to evaluate that expression. If the expression evaluates successfully, XLISP prints the result and then returns to the initial prompt waiting for another expression to be typed.

### Break Command Loop

When XLISP encounters an error while evaluating an expression, it attempts to handle the error in the following way:

If the symbol `*breakenable*` is true, the message corresponding to the error is printed. If the error is correctable, the correction message is printed.

If the symbol `*tracenable*` is true, a trace back is printed. The number of entries printed depends on the value of the symbol `*tracelimit*`. If this symbol is set to something other than a number, the entire trace back stack is printed.

XLISP then enters a read/eval/print loop to allow the user to examine the state of the interpreter in the context of the error. This loop differs from the normal top-level read/eval/print loop in that if the user invokes the function `continue`, XLISP will continue from a correctable error. If the user invokes the function `clean-up`, XLISP will abort the break loop and return to the top level or the next lower numbered break loop. When in a break loop, XLISP prefixes the break level to the normal prompt.

If the symbol `*breakenable*` is `nil`, XLISP looks for a surrounding errset function. If one is found, XLISP examines the value of the print flag. If this flag is true, the error message is printed. In any case, XLISP causes the errset function call to return `nil`.

If there is no surrounding errset function, XLISP prints the error message and returns to the top level.

### Data Types

There are several different data types available to XLISP programmers.

- lists
- symbols
- strings
- integers
- characters
- floats
- objects
- arrays
- streams
- subrs (built-in functions)
- fsubrs (special forms)
- closures (user defined functions)

### The Evaluator

The process of evaluation in XLISP:

- Strings, integers, characters, floats, objects, arrays, streams, subrs, fsubrs and closures evaluate to themselves.
- Symbols act as variables and are evaluated by retrieving the value associated with their current binding.
- Lists are evaluated by examining the first element of the list and then taking one of the following actions:
  - If it is a symbol, the functional binding of the symbol is retrieved.
  - If it is a lambda expression, a closure is constructed for the function described by the lambda expression.
  - If it is a subr, fsubr or closure, it stands for itself.
  - Any other value is an error.
  Then, the value produced by the previous step is examined:
  - If it is a subr or closure, the remaining list elements are evaluated and the subr or closure is called with these evaluated expressions as arguments.
  - If it is an fsubr, the fsubr is called using the remaining list elements as arguments (unevaluated).
  - If it is a macro, the macro is expanded using the remaining list elements as arguments (unevaluated). The macro expansion is then evaluated in place of the original macro call.

### Lexical Conventions

The following conventions must be followed when entering XLISP programs:

Comments in XLISP code begin with a semi-colon character and continue to the end of the line.

Symbol names in XLISP can consist of any sequence of non-blank printable characters except the following:

                    ( ) ' ` , " ;

Uppercase and lowercase characters are not distinguished within symbol names. All lowercase characters are mapped to uppercase on input.

Integer literals consist of a sequence of digits optionally beginning with a `+` or `-`. The range of values an integer can represent is limited by the size of a C `long` on the machine on which XLISP is running.

Floating point literals consist of a sequence of digits optionally beginning with a `+` or `-` and including an embedded decimal point. The range of values a floating point number can represent is limited by the size of a C `float` (`double` on machines with 32 bit addresses) on the machine on which XLISP is running.

Literal strings are sequences of characters surrounded by double quotes. Within quoted strings the ```\`'' character is used to allow non-printable characters to be included. The codes recognized are:

- `\\` means the character ```\`''
- `\n` means newline
- `\t` means tab
- `\r` means return
- `\f` means form feed
- `\nnn` means the character whose octal code is nnn

### Readtables

The behavior of the reader is controlled by a data structure called a readtable. The reader uses the symbol `*readtable*` to locate the current readtable. This table controls the interpretation of input characters. It is an array with 128 entries, one for each of the ASCII character codes. Each entry contains one of the following things:

- `NIL` - Indicating an invalid character
- `:CONSTITUENT` - Indicating a symbol constituent
- `:WHITE-SPACE` - Indicating a whitespace character
- `(:TMACRO . fun)` - Terminating readmacro
- `(:NMACRO . fun)` - Non-terminating readmacro
- `:SESCAPE` - Single escape character ('\')
- `:MESCAPE` - Multiple escape character ('|')

In the case of `:TMACRO` and `:NMACRO`, the fun component is a function. This can either be a built-in readmacro function or a lambda expression. The function should take two parameters. The first is the input stream and the second is the character that caused the invocation of the readmacro. The readmacro function should return `NIL` to indicate that the character should be treated as white space or a value consed with `NIL` to indicate that the readmacro should be treated as an occurence of the specified value. Of course, the readmacro code is free to read additional characters from the input stream.

XLISP defines several useful read macros:

- '<expr> == (quote <expr>)
- #'<expr> == (function <expr>)
- #(<expr>...) == an array of the specified expressions
- #x<hdigits> == a hexadecimal number (0-9,A-F)
- #o<odigits> == an octal number (0-7)
- #b<bdigits> == a binary number (0-1)
- #\<char> == the ASCII code of the character
- #| ... |# == a comment
- #:<symbol> == an uninterned symbol
- `<expr> == (backquote <expr>)
- ,<expr> == (comma <expr>)
- ,@<expr> == (comma-at <expr>)

### Lambda Lists

There are several forms in XLISP that require that a ``lambda list'' be specified. A lambda list is a definition of the arguments accepted by a function. There are four different types of arguments.

The lambda list starts with required arguments. Required arguments must be specified in every call to the function.

The required arguments are followed by the &optional arguments. Optional arguments may be provided or omitted in a call. An initialization expression may be specified to provide a default value for an &optional argument if it is omitted from a call. If no initialization expression is specified, an omitted argument is initialized to `NIL`. It is also possible to provide the name of a `supplied-p` variable that can be used to determine if a call provided a value for the argument or if the initialization expression was used. If specified, the supplied- p variable will be bound to T if a value was specified in the call and `NIL` if the default value was used.

The &optional arguments are followed by the &rest argument. The &rest argument gets bound to the remainder of the argument list after the required and &optional arguments have been removed.

The &rest argument is followed by the &key arguments. When a keyword argument is passed to a function, a pair of values appears in the argument list. The first expression in the pair should evaluate to a keyword symbol (a symbol that begins with a ```:`''). The value of the second expression is the value of the keyword argument. Like &optional arguments, &key arguments can have initialization expressions and supplied-p variables. In addition, it is possible to specify the keyword to be used in a function call. If no keyword is specified, the keyword obtained by adding a ```:`'' to the beginning of the keyword argument symbol is used. In other words, if the keyword argument symbol is `foo`, the keyword will be `':foo`.

The &key arguments are followed by the &aux variables. These are local variables that are bound during the evaluation of the function body. It is possible to have initialization expressions for the &aux variables.

Here is the complete syntax for lambda lists:

> (rarg...
> [&optional [oarg | (oarg [init [svar]])]...]
> [&rest rarg]
> [&key
> [karg | ([karg | (key karg)] [init [svar]])]...
> &allow-other-keys]
> [&aux
> [aux | (aux [init])]...])

> where:

> rarg is a required argument symbol
> oarg is an &optional argument symbol
> rarg is the &rest argument symbol
> karg is a &key argument symbol
> key is a keyword symbol
> aux is an auxiliary variable symbol
> init is an initialization expression
> svar is a supplied-p variable symbol

### Objects

Definitions:

- selector - a symbol used to select an appropriate method
- message - a selector and a list of actual arguments
- method - the code that implements a message

Since XLISP was created to provide a simple basis for experimenting with object-oriented programming, one of the primitive data types included is object. In XLISP, an object consists of a data structure containing a pointer to the object's class as well as an array containing the values of the object's instance variables.

Officially, there is no way to see inside an object (look at the values of its instance variables). The only way to communicate with an object is by sending it a message.

You can send a message to an object using the `send` function. This function takes the object as its first argument, the message selector as its second argument (which must be a symbol) and the message arguments as its remaining arguments.

The `send` function determines the class of the receiving object and attempts to find a method corresponding to the message selector in the set of messages defined for that class. If the message is not found in the object's class and the class has a super-class, the search continues by looking at the messages defined for the super-class. This process continues from one super-class to the next until a method for the message is found. If no method is found, an error occurs.

A message can also be sent from the body of a method by using the current object, but the method lookup starts with the object's superclass rather than its class. This allows a subclass to invoke a standard method in its parent class even though it overrides that method with its own specialized version.

When a method is found, the evaluator binds the receiving object to the symbol `self` and evaluates the method using the remaining elements of the original list as arguments to the method. These arguments are always evaluated prior to being bound to their corresponding formal arguments. The result of evaluating the method becomes the result of the expression.

### The ``Object'' Class

`Object` - the top of the class hierarchy.

Messages:

`:show` - show an object's instance variables.
  returns - the object
`:class` - return the class of an object
  returns - the class of the object
`:isnew` - the default object initialization routine
  returns - the object
`:sendsuper` sel args... - send superclass a message
  sel - the message selector
  args - the message arguments
  returns - the result of sending the message

### The ``Class'' Class

`Class` - class of all object classes (including itself)

Messages:

:new - create a new instance of a class
  returns - the new class object
:isnew ivars [cvars [super]] - initialize a new class
  ivars - the list of instance variable symbols
  cvars - the list of class variable symbols
  super - the superclass (default is object)
  returns - the new class object
:answer msg fargs code - add a message to a class
  msg - the message symbol
  fargs - the formal argument list (lambda list)
  code - a list of executable expressions
  returns - the object

When a new instance of a class is created by sending the message `:new` to an existing class, the message `:isnew` followed by whatever parameters were passed to the `:new` message is sent to the newly created object.

When a new class is created by sending the `:new` message to the object `Class`, an optional parameter may be specified indicating the superclass of the new class. If this parameter is omitted, the new class will be a subclass of `Object`. A class inherits all instance variables, class variables, and methods from its super-class.

### Profiling

The Xlisp 2.0 release has been extended with a profiling facility, which counts how many times and where `eval` is executed. A separate count is maintained for each named function, closure, or macro, and a count indicates an `eval` in the immediately (lexically) enclosing named function, closure, or macro. Thus, the count gives an indication of the amount of time spent in a function, not counting nested function calls. The list of all functions executed is maintained on the global `*profile*` variable. These functions in turn have `*profile*` properties, which maintain the counts. The profile system merely increments counters and puts symbols on the `*profile*` list. It is up to the user to initialize data and gather results. Profiling is turned on or off with the `profile` function. Unfortunately, methods cannot be profiled with this facility.

### SYMBOLS

- `self` - the current object (within a method context)
- `*obarray*` - the object hash table
- `*standard-input*` - the standard input stream
- `*standard-output*` - the standard output stream
- `*error-output*` - the error output stream
- `*trace-output*` - the trace output stream
- `*debug-io*` - the debug i/o stream
- `*breakenable*` - flag controlling entering break loop on errors
- `*tracelist*` - list of names of functions to trace
- `*tracenable*` - enable trace back printout on errors
- `*tracelimit*` - number of levels of trace back information
- `*evalhook*` - user substitute for the evaluator function
- `*applyhook*` - (not yet implemented)
- `*readtable*` - the current readtable
- `*unbound*` - indicator for unbound symbols
- `*gc-flag*` - controls the printing of gc messages
- `*gc-hook*` - function to call after garbage collection
- `*integer-format*` - format for printing integers (``%d'' or ``%ld'')
- `*float-format*` - format for printing floats (``%g'')
- `*print-case*` - symbol output case (:upcase or :downcase)

There are several symbols maintained by the read/eval/print loop. The symbols `+`, `++`, and `+++` are bound to the most recent three input expressions. The symbols `*`, `**` and `***` are bound to the most recent three results. The symbol `-` is bound to the expression currently being evaluated. It becomes the value of `+` at the end of the evaluation.

### Evaluation Functions

(eval expr) - evaluate an xlisp expression
  expr - the expression to be evaluated
  returns - the result of evaluating the expression
(apply fun args) - apply a function to a list of arguments
  fun - the function to apply (or function symbol)
  args - the argument list
  returns - the result of applying the function to the arguments
(funcall fun arg...) - call a function with arguments
  fun - the function to call (or function symbol)
  arg - arguments to pass to the function
  returns - the result of calling the function with the arguments
(quote expr) - return an expression unevaluated
  expr - the expression to be quoted (quoted)
  returns - expr unevaluated
(function expr) - get the functional interpretation
  expr - the symbol or lambda expression (quoted)
  returns - the functional interpretation
(backquote expr) - fill in a template
  expr - the template
  returns - a copy of the template with comma and comma-at
  expressions expanded
(lambda args expr...) - make a function closure
  args - formal argument list (lambda list) (quoted)
  expr - expressions of the function body
  returns - the function closure
(get-lambda-expression closure) - get the lambda expression
  closure - the closure
  returns - the original lambda expression
(macroexpand form) - recursively expand macro calls
  form - the form to expand
  returns - the macro expansion
(macroexpand-1 form) - expand a macro call
  form - the macro call form
  returns - the macro expansion

### Symbol Functions

(set sym expr) - set the value of a symbol
  sym - the symbol being set
  expr - the new value
  returns - the new value
(setq [sym expr]...) - set the value of a symbol
  sym - the symbol being set (quoted)
  expr - the new value
  returns - the new value
(psetq [sym expr]...) - parallel version of setq
  sym - the symbol being set (quoted)
  expr - the new value
  returns - the new value
(setf [place expr]...) - set the value of a field
  place - the field specifier (quoted):
    sym - set value of a symbol
    (car expr) - set car of a cons node
    (cdr expr) - set cdr of a cons node
    (nth n expr) - set nth car of a list
    (aref expr n) - set nth element of an array
    (get sym prop) - set value of a property
    (symbol-value sym) - set value of a symbol
    (symbol-function sym) - set functional value of a symbol
    (symbol-plist sym) - set property list of a symbol
  expr - the new value
  returns - the new value
(defun sym fargs expr...) - define a function
(defmacro sym fargs expr...) - define a macro
  sym - symbol being defined (quoted)
  fargs - formal argument list (lambda list) (quoted)
  expr - expressions constituting the body of the
  function (quoted) returns - the function symbol
(gensym [tag]) - generate a symbol
  tag - string or number
  returns - the new symbol
(intern pname) - make an interned symbol
  pname - the symbol's print name string
  returns - the new symbol
(make-symbol pname) - make an uninterned symbol
  pname - the symbol's print name string
  returns - the new symbol
(symbol-name sym) - get the print name of a symbol
  sym - the symbol
  returns - the symbol's print name
(symbol-value sym) - get the value of a symbol
  sym - the symbol
  returns - the symbol's value
(symbol-function sym) - get the functional value of a symbol
  sym - the symbol
  returns - the symbol's functional value
(symbol-plist sym) - get the property list of a symbol
  sym - the symbol
  returns - the symbol's property list
(hash sym n) - compute the hash index for a symbol
  sym - the symbol or string
  n - the table size (integer)
  returns - the hash index (integer)

### Property List Functions

(get sym prop) - get the value of a property
  sym - the symbol
  prop - the property symbol
  returns - the property value or `nil`
(putprop sym val prop) - put a property onto a property list
  sym - the symbol
  val - the property value
  prop - the property symbol
  returns - the property value
(remprop sym prop) - remove a property
  sym - the symbol
  prop - the property symbol
  returns - `nil`

### Array Functions

(aref array n) - get the nth element of an array
  array - the array
  n - the array index (integer)
  returns - the value of the array element
(make-array size) - make a new array
  size - the size of the new array (integer)
  returns - the new array
(vector expr...) - make an initialized vector
  expr - the vector elements
  returns - the new vector

### List Functions

(car expr) - return the car of a list node
  expr - the list node
  returns - the car of the list node
(cdr expr) - return the cdr of a list node
  expr - the list node
  returns - the cdr of the list node
(cxxr expr) - all cxxr combinations
(cxxxr expr) - all cxxxr combinations
(cxxxxr expr) - all cxxxxr combinations
(first expr) - a synonym for car
(second expr) - a synonym for cadr
(third expr) - a synonym for caddr
(fourth expr) - a synonym for cadddr
(rest expr) - a synonym for cdr
(cons expr1 expr2) - construct a new list node
  expr1 - the car of the new list node
  expr2 - the cdr of the new list node
  returns - the new list node
(list expr...) - create a list of values
  expr - expressions to be combined into a list
  returns - the new list
(append expr...) - append lists
  expr - lists whose elements are to be appended
  returns - the new list
(reverse expr) - reverse a list
  expr - the list to reverse
  returns - a new list in the reverse order
(last list) - return the last list node of a list
  list - the list
  returns - the last list node in the list
(member expr list &key :test :test-not) - find an expression in a list
  expr - the expression to find
  list - the list to search
  :test - the test function (defaults to eql)
  :test-not - the test function (sense inverted)
  returns - the remainder of the list starting with the expression
(assoc expr alist &key :test :test-not) - find an expression in an a-list
  expr - the expression to find
  alist - the association list
  :test - the test function (defaults to eql)
  :test-not - the test function (sense inverted)
  returns - the alist entry or `nil`
(remove expr list &key :test :test-not) - remove elements from a list
  expr - the element to remove
  list - the list
  :test - the test function (defaults to eql)
  :test-not - the test function (sense inverted)
  returns - copy of list with matching expressions removed
(remove-if test list) - remove elements that pass test
  test - the test predicate
  list - the list
  returns - copy of list with matching elements removed
(remove-if-not test list) - remove elements that fail test
  test - the test predicate
  list - the list
  returns - copy of list with non-matching elements removed
(length expr) - find the length of a list, vector or string
  expr - the list, vector or string
  returns - the length of the list, vector or string
(nth n list) - return the nth element of a list
  n - the number of the element to return (zero origin)
  list - the list
  returns - the nth element or `nil` if the list isn't that long
(nthcdr n list) - return the nth cdr of a list
  n - the number of the element to return (zero origin)
  list - the list
  returns - the nth cdr or `nil` if the list isn't that long
(mapc fcn list1 list...) - apply function to successive cars
  fcn - the function or function name
  listn - a list for each argument of the function
  returns - the first list of arguments
(mapcar fcn list1 list...) - apply function to successive cars
  fcn - the function or function name
  listn - a list for each argument of the function
  returns - a list of the values returned
(mapl fcn list1 list...) - apply function to successive cdrs
  fcn - the function or function name
  listn - a list for each argument of the function
  returns - the first list of arguments
(maplist fcn list1 list...) - apply function to successive cdrs
  fcn - the function or function name
  listn - a list for each argument of the function
  returns - a list of the values returned
(subst to from expr &key :test :test-not) - substitute expressions
  to - the new expression
  from - the old expression
  expr - the expression in which to do the substitutions
  :test - the test function (defaults to eql)
  :test-not - the test function (sense inverted)
  returns - the expression with substitutions
(sublis alist expr &key :test :test-not) - substitute with an a-list
  alist - the association list
  expr - the expression in which to do the substitutions
  :test - the test function (defaults to eql)
  :test-not - the test function (sense inverted)
  returns - the expression with substitutions

### Destructive List Functions

(rplaca list expr) - replace the car of a list node
  list - the list node
  expr - the new value for the car of the list node
  returns - the list node after updating the car
(rplacd list expr) - replace the cdr of a list node
  list - the list node
  expr - the new value for the cdr of the list node
  returns - the list node after updating the cdr
(nconc list...) - destructively concatenate lists
  list - lists to concatenate
  returns - the result of concatenating the lists
(delete expr &key :test :test-not) - delete elements from a list
  expr - the element to delete
  list - the list
  :test - the test function (defaults to eql)
  :test-not - the test function (sense inverted)
  returns - the list with the matching expressions deleted
(delete-if test list) - delete elements that pass test
  test - the test predicate
  list - the list
  returns - the list with matching elements deleted
(delete-if-not test list) - delete elements that fail test
  test - the test predicate
  list - the list
  returns - the list with non-matching elements deleted
(sort list test) - sort a list
  list - the list to sort
  test - the comparison function
  returns - the sorted list

### Predicate Functions

(atom expr) - is this an atom?
  expr - the expression to check
  returns - `t` if the value is an atom, `nil` otherwise
(symbolp expr) - is this a symbol?
  expr - the expression to check
  returns - `t` if the expression is a symbol, `nil` otherwise
(numberp expr) - is this a number?
  expr - the expression to check
  returns - `t` if the expression is a number, `nil` otherwise
(null expr) - is this an empty list?
  expr - the list to check
  returns - `t` if the list is empty, `nil` otherwise
(not expr) - is this false?
  expr - the expression to check
  return - `t` if the value is `nil`, `nil` otherwise
(listp expr) - is this a list?
  expr - the expression to check
  returns - `t` if the value is a cons or `nil`, `nil` otherwise
(endp list) - is this the end of a list
  list - the list
  returns - `t` if the value is `nil`, `nil` otherwise
(consp expr) - is this a non-empty list?
  expr - the expression to check
  returns - `t` if the value is a cons, `nil` otherwise
(integerp expr) - is this an integer?
  expr - the expression to check
  returns - `t` if the value is an integer, `nil` otherwise
(floatp expr) - is this a float?
  expr - the expression to check
  returns - `t` if the value is a float, `nil` otherwise
(stringp expr) - is this a string?
  expr - the expression to check
  returns - `t` if the value is a string, `nil` otherwise
(characterp expr) - is this a character?
  expr - the expression to check
  returns - `t` if the value is a character, `nil` otherwise
(arrayp expr) - is this an array?
  expr - the expression to check
  returns - `t` if the value is an array, `nil` otherwise
(streamp expr) - is this a stream?
  expr - the expression to check
  returns - `t` if the value is a stream, `nil` otherwise
(objectp expr) - is this an object?
  expr - the expression to check
  returns - `t` if the value is an object, `nil` otherwise
(boundp sym) - is a value bound to this symbol?
  sym - the symbol
  returns - `t` if a value is bound to the symbol, `nil` otherwise
(fboundp sym) - is a functional value bound to this symbol?
  sym - the symbol
  returns - `t` if a functional value is bound to the symbol,
  `nil` otherwise
(minusp expr) - is this number negative?
  expr - the number to test
  returns - `t` if the number is negative, `nil` otherwise
(zerop expr) - is this number zero?
  expr - the number to test
  returns - `t` if the number is zero, `nil` otherwise
(plusp expr) - is this number positive?
  expr - the number to test
  returns - `t` if the number is positive, `nil` otherwise
(evenp expr) - is this integer even?
  expr - the integer to test
  returns - `t` if the integer is even, `nil` otherwise
(oddp expr) - is this integer odd?
  expr - the integer to test
  returns - `t` if the integer is odd, `nil` otherwise
(eq expr1 expr2) - are the expressions identical?
  expr1 - the first expression
  expr2 - the second expression
  returns - `t` if they are equal, `nil` otherwise
(eql expr1 expr2) - are the expressions identical? (works with all numbers)
  expr1 - the first expression
  expr2 - the second expression
  returns - `t` if they are equal, `nil` otherwise
(equal expr1 expr2) - are the expressions equal?
  expr1 - the first expression
  expr2 - the second expression
  returns - `t` if they are equal, `nil` otherwise

### Control Constructs

(cond pair...) - evaluate conditionally
  pair - pair consisting of:
    (pred expr...)
  where:
    pred - is a predicate expression
    expr - evaluated if the predicate is not `nil`
  returns - the value of the first expression whose predicate is not `nil`
(and expr...) - the logical and of a list of expressions
  expr - the expressions to be anded
  returns - `nil` if any expression evaluates to `nil`, otherwise the value of the last expression (evaluation of expressions stops after the first expression that evaluates to `nil`)
(or expr...) - the logical or of a list of expressions
  expr - the expressions to be ored
  returns - `nil` if all expressions evaluate to `nil`, otherwise the value of the first non-`nil` expression (evaluation of expressions stops after the first expression that does not evaluate to `nil`)
(if texpr expr1 [expr2]) - evaluate expressions conditionally
  texpr - the test expression
  expr1 - the expression to be evaluated if texpr is non-`nil`
  expr2 - the expression to be evaluated if texpr is `nil`
  returns - the value of the selected expression
(when texpr expr...) - evaluate only when a condition is true
  texpr - the test expression
  expr - the expression(s) to be evaluated if texpr is non-`nil`
  returns - the value of the last expression or `nil`
(unless texpr expr...) - evaluate only when a condition is false
  texpr - the test expression
  expr - the expression(s) to be evaluated if texpr is `nil`
  returns - the value of the last expression or `nil`
(case expr case...) - select by case
  expr - the selection expression
  case - pair consisting of:
    (value expr...)
  where:
    value - is a single expression or a list of expressions (unevaluated)
    expr - are expressions to execute if the case matches
  returns - the value of the last expression of the matching case
(let (binding...) expr...) - create local bindings
(let* (binding...) expr...) - let with sequential binding
  binding - the variable bindings each of which is either:
    1) a symbol (which is initialized to `nil`)
    2) a list whose car is a symbol and whose cadr is an initialization expression
  expr - the expressions to be evaluated
  returns - the value of the last expression
(flet (binding...) expr...) - create local functions
(labels (binding...) expr...) - flet with recursive functions
(macrolet (binding...) expr...) - create local macros
  binding - the function bindings each of which is:
    (sym fargs expr...)
  where:
    sym - the function/macro name
    fargs - formal argument list (lambda list)
    expr - expressions constituting the body of the function/macro
  expr - the expressions to be evaluated
  returns - the value of the last expression
(catch sym expr...) - evaluate expressions and catch throws
  sym - the catch tag
  expr - expressions to evaluate
  returns - the value of the last expression the throw expression
(throw sym [expr]) - throw to a catch
  sym - the catch tag
  expr - the value for the catch to return (defaults to `nil`)
  returns - never returns
(unwind-protect expr cexpr...) - protect evaluation of an expression
  expr - the expression to protect
  cexpr - the cleanup expressions
  returns - the value of the expression
  Note: unwind-protect guarantees to execute the cleanup expressions even if a non-local exit terminates the evaluation of the protected expression

### Looping Constructs

(loop expr...) - basic looping form
  expr - the body of the loop
  returns - never returns (must use non-local exit)
(do (binding...) (texpr rexpr...) expr...)
(do* (binding...) (texpr rexpr...) expr...)
  binding - the variable bindings each of which is either:
    1) a symbol (which is initialized to `nil`)
    2) a list of the form: (sym init [step]) where:
      sym - is the symbol to bind
      init - is the initial value of the symbol
      step - is a step expression
  texpr - the termination test expression
  rexpr - result expressions (the default is `nil`)
  expr - the body of the loop (treated like an implicit prog)
  returns - the value of the last result expression
(dolist (sym expr [rexpr]) expr...) - loop through a list
  sym - the symbol to bind to each list element
  expr - the list expression
  rexpr - the result expression (the default is `nil`)
  expr - the body of the loop (treated like an implicit prog)
(dotimes (sym expr [rexpr]) expr...) - loop from zero to n-1
  sym - the symbol to bind to each value from 0 to n-1
  expr - the number of times to loop
  rexpr - the result expression (the default is `nil`)
  expr - the body of the loop (treated like an implicit prog)

### The Program Feature

(prog (binding...) expr...) - the program feature
(prog* (binding...) expr...) - prog with sequential binding
  binding - the variable bindings each of which is either:
    1) a symbol (which is initialized to `nil`)
    2) a list whose car is a symbol and whose cadr is an initialization expression
  expr - expressions to evaluate or tags (symbols)
  returns - `nil` or the argument passed to the return function
(block name expr...) - named block
  name - the block name (symbol)
  expr - the block body
  returns - the value of the last expression
(return [expr]) - cause a prog construct to return a value
  expr - the value (defaults to `nil`)
  returns - never returns
(return-from name [value]) - return from a named block
  name - the block name (symbol)
  value - the value to return (defaults to `nil`)
  returns - never returns
(tagbody expr...) - block with labels
  expr - expression(s) to evaluate or tags (symbols)
  returns - `nil`
(go sym) - go to a tag within a tagbody or prog
  sym - the tag (quoted)
  returns - never returns
(progv slist vlist expr...) - dynamically bind symbols
  slist - list of symbols
  vlist - list of values to bind to the symbols
  expr - expression(s) to evaluate
  returns - the value of the last expression
(prog1 expr1 expr...) - execute expressions sequentially
  expr1 - the first expression to evaluate
  expr - the remaining expressions to evaluate
  returns - the value of the first expression
(prog2 expr1 expr2 expr...) - execute expressions sequentially
  expr1 - the first expression to evaluate
  expr2 - the second expression to evaluate
  expr - the remaining expressions to evaluate
  returns - the value of the second expression
(progn expr...) - execute expressions sequentially
  expr - the expressions to evaluate
  returns - the value of the last expression (or `nil`)

### Debugging and Error Handling

(trace sym) - add a function to the trace list
  sym - the function to add (quoted)
  returns - the trace list
(untrace sym) - remove a function from the trace list
  sym - the function to remove (quoted)
  returns - the trace list
(error emsg [arg]) - signal a non-correctable error
  emsg - the error message string
  arg - the argument expression (printed after the message)
  returns - never returns
(cerror cmsg emsg [arg]) - signal a correctable error
  cmsg - the continue message string
  emsg - the error message string
  arg - the argument expression (printed after the message)
  returns - `nil` when continued from the break loop
(break [bmsg [arg]]) - enter a break loop
  bmsg - the break message string (defaults to `**break**`)
  arg - the argument expression (printed after the message)
  returns - `nil` when continued from the break loop
(clean-up) - clean-up after an error
  returns - never returns
(top-level) - clean-up after an error and return to the top level
  returns - never returns
(continue) - continue from a correctable error
  returns - never returns
(errset expr [pflag]) - trap errors
  expr - the expression to execute
  pflag - flag to control printing of the error message
  returns - the value of the last expression consed with `nil`
  or `nil` on error
(baktrace [n]) - print n levels of trace back information
  n - the number of levels (defaults to all levels)
  returns - `nil`
(evalhook expr ehook ahook [env]) - evaluate with hooks
  expr - the expression to evaluate
  ehook - the value for `*evalhook*`
  ahook - the value for `*applyhook*`
  env - the environment (default is `nil`)
  returns - the result of evaluating the expression
(profile flag) (Footnote 3) - turn profiling on or off.
  flag - `nil` turns profiling off, otherwise on
  returns - the previous state of profiling.

### Arithmetic Functions

(truncate expr) - truncates a floating point number to an integer
  expr - the number
  returns - the result of truncating the number
(float expr) - converts an integer to a floating point number
  expr - the number
  returns - the result of floating the integer
(+ expr...) - add a list of numbers
  expr - the numbers
  returns - the result of the addition
(- expr...) - subtract a list of numbers or negate a single number
  expr - the numbers
  returns - the result of the subtraction
(* expr...) - multiply a list of numbers
  expr - the numbers
  returns - the result of the multiplication
(/ expr...) - divide a list of numbers
  expr - the numbers
  returns - the result of the division
(1+ expr) - add one to a number
  expr - the number
  returns - the number plus one
(1- expr) - subtract one from a number
  expr - the number
  returns - the number minus one
(rem expr...) - remainder of a list of numbers
  expr - the numbers
  returns - the result of the remainder operation
(min expr...) - the smallest of a list of numbers
  expr - the expressions to be checked
  returns - the smallest number in the list
(max expr...) - the largest of a list of numbers
  expr - the expressions to be checked
  returns - the largest number in the list
(abs expr) - the absolute value of a number
  expr - the number
  returns - the absolute value of the number
(gcd n1 n2...) - compute the greatest common divisor
  n1 - the first number (integer)
  n2 - the second number(s) (integer)
  returns - the greatest common divisor
(random n) - compute a random number between 1 and n-1
  n - the upper bound (integer)
  returns - a random number
(sin expr) - compute the sine of a number
  expr - the floating point number
  returns - the sine of the number
(cos expr) - compute the cosine of a number
  expr - the floating point number
  returns - the cosine of the number
(tan expr) - compute the tangent of a number
  expr - the floating point number
  returns - the tangent of the number
(expt x-expr y-expr) - compute x to the y power
  x-expr - the floating point number
  y-expr - the floating point exponent
  returns - x to the y power
(exp x-expr) - compute e to the x power
  x-expr - the floating point number
  returns - e to the x power
(sqrt expr) - compute the square root of a number
  expr - the floating point number
  returns - the square root of the number
(< n1 n2...) - test for less than
(<= n1 n2...) - test for less than or equal to
(= n1 n2...) - test for equal to
(/= n1 n2...) - test for not equal to
(>= n1 n2...) - test for greater than or equal to
(> n1 n2...) - test for greater than
  n1 - the first number to compare
  n2 - the second number to compare
  returns - `t` if the results of comparing n1 with n2, n2 with n3, etc., are all true.

### Bitwise Logical Functions

(logand expr...) - the bitwise and of a list of numbers
  expr - the numbers
  returns - the result of the and operation
(logior expr...) - the bitwise inclusive or of a list of numbers
  expr - the numbers
  returns - the result of the inclusive or operation
(logxor expr...) - the bitwise exclusive or of a list of numbers
  expr - the numbers
  returns - the result of the exclusive or operation
(lognot expr) - the bitwise not of a number
  expr - the number
  returns - the bitwise inversion of number

### String Functions

(string expr) - make a string from an integer ascii value
  expr - the integer
  returns - a one character string
(string-search pat str &key :start :end) (Footnote 4) - search for pattern in string
  pat - a string to search for
  str - the string to be searched
  :start - the starting offset in str
  :end - the ending offset + 1
  returns - index of pat in str or NIL if not found
(string-trim bag str) - trim both ends of a string
  bag - a string containing characters to trim
  str - the string to trim
  returns - a trimed copy of the string
(string-left-trim bag str) - trim the left end of a string
  bag - a string containing characters to trim
  str - the string to trim
  returns - a trimed copy of the string
(string-right-trim bag str) - trim the right end of a string
  bag - a string containing characters to trim
  str - the string to trim
  returns - a trimed copy of the string
(string-upcase str &key :start :end) - convert to uppercase
  str - the string
  :start - the starting offset
  :end - the ending offset + 1
  returns - a converted copy of the string
(string-downcase str &key :start :end) - convert to lowercase
  str - the string
  :start - the starting offset
  :end - the ending offset + 1
  returns - a converted copy of the string
(nstring-upcase str &key :start :end) - convert to uppercase
  str - the string
  :start - the starting offset
  :end - the ending offset + 1
  returns - the converted string (not a copy)
(nstring-downcase str &key :start :end) - convert to lowercase
  str - the string
  :start - the starting offset
  :end - the ending offset + 1
  returns - the converted string (not a copy)
(strcat expr...) - concatenate strings
  expr - the strings to concatenate
  returns - the result of concatenating the strings
(subseq string start [end]) - extract a substring
  string - the string
  start - the starting position (zero origin)
  end - the ending position + 1 (defaults to end)
  returns - substring between start and end
(string< str1 str2 &key :start1 :end1 :start2 :end2)
(string<= str1 str2 &key :start1 :end1 :start2 :end2)
(string= str1 str2 &key :start1 :end1 :start2 :end2)
(string/= str1 str2 &key :start1 :end1 :start2 :end2)
(string>= str1 str2 &key :start1 :end1 :start2 :end2)
(string> str1 str2 &key :start1 :end1 :start2 :end2)
  str1 - the first string to compare
  str2 - the second string to compare
  :start1 - first substring starting offset
  :end1 - first substring ending offset + 1
  :start2 - second substring starting offset
  :end2 - second substring ending offset + 1
  returns - `t` if predicate is true, `nil` otherwise
  Note: case is significant with these comparison functions.
(string-lessp str1 str2 &key :start1 :end1 :start2 :end2)
(string-not-greaterp str1 str2 &key :start1 :end1 :start2 :end2)
(string-equalp str1 str2 &key :start1 :end1 :start2 :end2)
(string-not-equalp str1 str2 &key :start1 :end1 :start2 :end2)
(string-not-lessp str1 str2 &key :start1 :end1 :start2 :end2)
(string-greaterp str1 str2 &key :start1 :end1 :start2 :end2)
  str1 - the first string to compare
  str2 - the second string to compare
  :start1 - first substring starting offset
  :end1 - first substring ending offset + 1
  :start2 - second substring starting offset
  :end2 - second substring ending offset + 1
  returns - `t` if predicate is true, `nil` otherwise
  Note: case is not significant with these comparison functions.

### Character Functions

(char string index) - extract a character from a string
  string - the string
  index - the string index (zero relative)
  returns - the ascii code of the character
(upper-case-p chr) - is this an upper case character?
  chr - the character
  returns - `t` if the character is upper case, `nil` otherwise
(lower-case-p chr) - is this a lower case character?
  chr - the character
  returns - `t` if the character is lower case, `nil` otherwise
(both-case-p chr) - is this an alphabetic (either case) character?
  chr - the character
  returns - `t` if the character is alphabetic, `nil` otherwise
(digit-char-p chr) - is this a digit character?
  chr - the character
  returns - the digit weight if character is a digit, `nil` otherwise
(char-code chr) - get the ascii code of a character
  chr - the character
  returns - the ascii character code (integer)
(code-char code) - get the character with a specified ascii code
  code - the ascii code (integer)
  returns - the character with that code or `nil`
(char-upcase chr) - convert a character to upper case
  chr - the character
  returns - the upper case character
(char-downcase chr) - convert a character to lower case
  chr - the character
  returns - the lower case character
(digit-char n) - convert a digit weight to a digit
  n - the digit weight (integer)
  returns - the digit character or `nil`
(char-int chr) - convert a character to an integer
  chr - the character
  returns - the ascii character code
(int-char int) - convert an integer to a character
  int - the ascii character code
  returns - the character with that code
(char< chr1 chr2...)
(char<= chr1 chr2...)
(char= chr1 chr2...)
(char/= chr1 chr2...)
(char>= chr1 chr2...)
(char> chr1 chr2...)
  chr1 - the first character to compare
  chr2 - the second character(s) to compare
  returns - `t` if predicate is true, `nil` otherwise
  Note: case is significant with these comparison functions.
(char-lessp chr1 chr2...)
(char-not-greaterp chr1 chr2...)
(char-equalp chr1 chr2...)
(char-not-equalp chr1 chr2...)
(char-not-lessp chr1 chr2...)
(char-greaterp chr1 chr2...)
  chr1 - the first string to compare
  chr2 - the second string(s) to compare
  returns - `t` if predicate is true, `nil` otherwise
Note: case is not significant with these comparison functions.

### Input/Output Functions

(read [stream [eof [rflag]]]) - read an expression
  stream - the input stream (default is standard input)
  eof - the value to return on end of file (default is `nil`)
  rflag - recursive read flag (default is `nil`)
  returns - the expression read
(print expr [stream]) - print an expression on a new line
  expr - the expression to be printed
  stream - the output stream (default is standard output)
  returns - the expression
(prin1 expr [stream]) - print an expression
  expr - the expression to be printed
  stream - the output stream (default is standard output)
  returns - the expression
(princ expr [stream]) - print an expression without quoting
  expr - the expressions to be printed
  stream - the output stream (default is standard output)
  returns - the expression
(pprint expr [stream]) - pretty print an expression
  expr - the expressions to be printed
  stream - the output stream (default is standard output)
  returns - the expression
(terpri [stream]) - terminate the current print line
  stream - the output stream (default is standard output)
  returns - `nil`
(flatsize expr) - length of printed representation using prin1
  expr - the expression
  returns - the length
(flatc expr) - length of printed representation using princ
  expr - the expression
  returns - the length

### The Format Function

(format stream fmt arg...) - do formated output
  stream - the output stream
  fmt - the format string
  arg - the format arguments
  returns - output string if stream is `nil`, `nil` otherwise

The format string can contain characters that should be copied directly to the output and formatting directives. The formatting directives are:

> ~A - print next argument using princ
> ~S - print next argument using prin1
> ~% - start a new line
> ~~ - print a tilde character

### File I/O Functions

Note that files are ordinarily opened as text. Binary files (such as standard midi files) must be opened with `open-binary` on non-unix systems.

(open fname &key :direction) - open a file stream
  fname - the file name string or symbol
  :direction - :input or :output (default is :input)
  returns - a stream
(open-binary fname &key :direction) - open a binary file stream
  fname - the file name string or symbol
  :direction - :input or :output (default is :input)
  returns - a stream
(close stream) - close a file stream
  stream - the stream
  returns - `nil`
(read-char [stream]) - read a character from a stream
  stream - the input stream (default is standard input)
  returns - the character
(peek-char [flag [stream]]) - peek at the next character
  flag - flag for skipping white space (default is `nil`)
  stream - the input stream (default is standard input)
  returns - the character (integer)
(write-char ch [stream]) - write a character to a stream
  ch - the character to write
  stream - the output stream (default is standard output)
  returns - the character
(read-int [stream [length]]) - read a binary integer from a stream
  stream - the input stream (default is standard input)
  length - the length of the integer in bytes (default is 4)
  returns - the integer
  Note: Integers are assumed to be big-endian (high-order byte first) and signed, regardless of the platform. To read little-endian format, use a negative number for the length, e.g. -4 indicates a 4-bytes, low-order byte first. The file should be opened in binary mode.
(write-int ch [stream [length]]) - write a binary integer to a stream
  ch - the character to write
  stream - the output stream (default is standard output)
  length - the length of the integer in bytes (default is 4)
  returns - the integer
  Note: Integers are assumed to be big-endian (high-order byte first) and signed, regardless of the platform. To write in little-endian format, use a negative number for the length, e.g. -4 indicates a 4-bytes, low-order byte first. The file should be opened in binary mode.
(read-float [stream [length]]) - read a binary floating-point number from a stream
  stream - the input stream (default is standard input)
  length - the length of the float in bytes (default is 4, legal values are -4, -8, 4, and 8)
  returns - the integer
  Note: Floats are assumed to be big-endian (high-order byte first) and signed, regardless of the platform. To read little-endian format, use a negative number for the length, e.g. -4 indicates a 4-bytes, low-order byte first. The file should be opened in binary mode.
(write-float ch [stream [length]]) - write a binary floating-point number to a stream
  ch - the character to write
  stream - the output stream (default is standard output)
  length - the length of the float in bytes (default is 4, legal values are -4, -8, 4, and 8)
  returns - the integer
  Note: Floats are assumed to be big-endian (high-order byte first) and signed, regardless of the platform. To write in little-endian format, use a negative number for the length, e.g. -4 indicates a 4-bytes, low-order byte first. The file should be opened in binary mode.
(read-line [stream]) - read a line from a stream
  stream - the input stream (default is standard input)
  returns - the string
(read-byte [stream]) - read a byte from a stream
  stream - the input stream (default is standard input)
  returns - the byte (integer)
(write-byte byte [stream]) - write a byte to a stream
  byte - the byte to write (integer)
  stream - the output stream (default is standard output)
  returns - the byte (integer)

### String Stream Functions

These functions operate on unnamed streams. An unnamed output stream collects characters sent to it when it is used as the destination of any output function. The functions `get-output-stream-string` and string or a list of characters.

An unnamed input stream is setup with the `make-string-input-stream` function and returns each character of the string when it is used as the source of any input function.

(make-string-input-stream str [start [end]])
  str - the string
  start - the starting offset
  end - the ending offset + 1
  returns - an unnamed stream that reads from the string
(make-string-output-stream)
  returns - an unnamed output stream
(get-output-stream-string stream)
  stream - the output stream
  returns - the output so far as a string
  Note: the output stream is emptied by this function
(get-output-stream-list stream)
  stream - the output stream
  returns - the output so far as a list
  Note: the output stream is emptied by this function

### System Functions

Note: the `load` function first tries to load a file from the current directory. A `.lsp` extension is added if there is not already an alphanumeric extension following a period. If that fails, XLisp searches the path, which is obtained from the XLISPPATH environment variable in Unix and HKEY_LOCAL_MACHINE\SOFTWARE\CMU\Nyquist\XLISPPATH under Win32. (The Macintosh version has no search path.)

(load fname &key :verbose :print) - load a source file
  fname - the filename string or symbol
  :verbose - the verbose flag (default is t)
  :print - the print flag (default is `nil`)
  returns - the filename
(save fname) - save workspace to a file
  fname - the filename string or symbol
  returns - `t` if workspace was written, `nil` otherwise
(restore fname) - restore workspace from a file
  fname - the filename string or symbol
  returns - `nil` on failure, otherwise never returns
(dribble [fname]) - create a file with a transcript of a session
  fname - file name string or symbol (if missing, close current transcript)
  returns - `t` if the transcript is opened, `nil` if it is closed
(gc) - force garbage collection
  returns - `nil`
(expand num) - expand memory by adding segments
  num - the number of segments to add
  returns - the number of segments added
(alloc num) - change number of nodes to allocate in each segment
  num - the number of nodes to allocate
  returns - the old number of nodes to allocate
(room) - show memory allocation statistics
  returns - `nil`
(type-of expr) - returns the type of the expression
  expr - the expression to return the type of
  returns - `nil` if the value is `nil` otherwise one of the symbols:
    SYMBOL - for symbols
    OBJECT - for objects
    CONS - for conses
    SUBR - for built-in functions
    FSUBR - for special forms
    CLOSURE - for defined functions
    STRING - for strings
    FIXNUM - for integers
    FLONUM - for floating point numbers
    CHARACTER - for characters
    FILE-STREAM - for file pointers
    UNNAMED-STREAM - for unnamed streams
    ARRAY - for arrays
(peek addrs) - peek at a location in memory
  addrs - the address to peek at (integer)
  returns - the value at the specified address (integer)
(poke addrs value) - poke a value into memory
  addrs - the address to poke (integer)
  value - the value to poke into the address (integer)
  returns - the value
(address-of expr) - get the address of an xlisp node
  expr - the node
  returns - the address of the node (integer)
(exit) - exit xlisp
  returns - never returns
(setup-console) - set default console attributes
  returns - NIL
  Note: Under Windows, Nyquist normally starts up in a medium-sized console window with black text and a white background, with a window title of ``Nyquist.'' This is normally accomplished by calling `setup-console` in `system.lsp`. In Nyquist, you can avoid this behavior by setting `*setup-console*` to NIL in your `init.lsp` file. If `setup-console` is not called, Nyquist uses standard input and output as is. This is what you want if you are running Nyquist inside of emacs, for example.

### File I/O Functions

#### Input from a File

To open a file for input, use the `open` function with the keyword argument `:direction` set to `:input`. To open a file for output, use the `open` function with the keyword argument `:direction` set to `:output`. The `open` function takes a single required argument which is the name of the file to be opened. This name can be in the form of a string or a symbol. The `open` function returns an object of type `FILE-STREAM` if it succeeds in opening the specified file. It returns the value `nil` if it fails. In order to manipulate the file, it is necessary to save the value returned by the `open` function. This is usually done by assigning it to a variable with the `setq` special form or by binding it using `let` or `let*`. Here is an example:

    (setq fp (open "init.lsp" :direction :input))

Evaluating this expression will result in the file `init.lsp` being opened. The file object that will be returned by the `open` function will be assigned to the variable `fp`.

It is now possible to use the file for input. To read an expression from the file, just supply the value of the `fp` variable as the optional stream argument to `read`.

    (read fp)

Evaluating this expression will result in reading the first expression from the file `init.lsp`. The expression will be returned as the result of the `read` function. More expressions can be read from the file using further calls to the `read` function. When there are no more expressions to read, the `read` function will return `nil` (or whatever value was supplied as the second argument to `read`).

Once you are done reading from the file, you should close it. To close the file, use the following expression:

    (close fp)

Evaluating this expression will cause the file to be closed.

#### Output to a File

Writing to a file is pretty much the same as reading from one. You need to open the file first. This time you should use the `open` function to indicate that you will do output to the file. For example:

    (setq fp (open "test.dat" :direction :output))

Evaluating this expression will open the file `test.dat` for output. If the file already exists, its current contents will be discarded. If it doesn't already exist, it will be created. In any case, a `FILE-STREAM` object will be returned by the `OPEN` function. This file object will be assigned to the `fp` variable.

It is now possible to write to this file by supplying the value of the `fp` variable as the optional stream parameter in the `print` function.

    (print "Hello there" fp)

Evaluating this expression will result in the string ``Hello there'' being written to the file `test.dat`. More data can be written to the file using the same technique.

Once you are done writing to the file, you should close it. Closing an output file is just like closing an input file.

    (close fp)

Evaluating this expression will close the output file and make it permanent.

#### A Slightly More Complicated File Example

This example shows how to open a file, read each Lisp expression from the file and print it. It demonstrates the use of files and the use of the optional stream argument to the `read` function.

    (do* ((fp (open "test.dat" :direction :input))
          (ex (read fp) (read fp)))
         ((null ex) nil)
      (print ex))

Previous Section | Next Section (Index) | Table of Contents | Title Page