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

Appendix 3: XLISP: An Object-oriented Lisp

Version 2.0

February 6, 1988

by
David Michael Betz
127 Taylor Road
Peterborough, NH 03458

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.

Implementations of XLISP run on virtually every operating system. XLISP 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.

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.

Special Characters

When XLISP is running from a console, some control characters invoke operations:

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.

The Evaluator

The process of evaluation in XLISP:

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:

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:

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:

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:

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.

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.

Within the body of a method, a message can be sent to the current object by calling the (send self ...). The method lookup starts with the object's class regardless of the class containing the current method.

Sometimes it is desirable to invoke a general method in a superclass even when it is overridden by a more specific method in a subclass. This can be accomplished by calling send-super, which begins the method lookup in the superclass of the class defining the current method rather than in the class of the current object.

The send-super function takes a selector as its first argument (which must be a symbol) and the message arguments as its remaining arguments. Notice that send-super can only be sent from within a method, and the target of the message is always the current object (self). (send-super ...) is similar to (send self ...) except that method lookup begins in the superclass of the class containing the current method rather than the class of the current object.

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

:isa class – test if object inherits from class
returns – t if object is an instance of class or a subclass of class, otherwise nil

:isnew – the default object initialization routine
returns – the object

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

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) [SAL]
(eval expr) [LISP] – evaluate an xlisp expression
expr – the expression to be evaluated
returns – the result of evaluating the expression

apply(fun, args) [SAL]
(apply fun args) [LISP] – 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...) [SAL]
(funcall fun arg...) [LISP] – 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) [SAL]
(quote expr) [LISP] – return an expression unevaluated
expr – the expression to be quoted (quoted)
returns – expr unevaluated

(function expr) [LISP] – get the
functional interpretation. Note that in SAL, the function can be accessed as #function.
expr – the symbol or lambda expression (quoted)
returns – the functional interpretation

backquote(expr) [SAL]
(backquote expr) [LISP] – fill in a template
expr – the template
returns – a copy of the template with comma and comma-at
expressions expanded

lambda(args, expr...) [SAL]
(lambda args expr...) [LISP] – 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) [SAL]
(get-lambda-expression closure) [LISP] – get the lambda expression
closure – the closure
returns – the original lambda expression

macroexpand(form) [SAL]
(macroexpand form) [LISP] – recursively expand macro calls
form – the form to expand
returns – the macro expansion

macroexpand-1(form) [SAL]
(macroexpand-1 form) [LISP] – expand a macro call
form – the macro call form
returns – the macro expansion

Symbol Functions

(set sym expr) [LISP] – set the value of a symbol. Note that in SAL, the function can be accessed as #set.
sym – the symbol being set
expr – the new value
returns – the new value

setq([sym, expr]...) [SAL]
(setq [sym expr]...) [LISP] – set the value of a symbol. Note that in SAL, the set command is normally used.
sym – the symbol being set (quoted)
expr – the new value
returns – the new value

psetq([sym, expr]...) [SAL]
(psetq [sym expr]...) [LISP] – parallel version of setq
sym – the symbol being set (quoted)
expr – the new value
returns – the new value

setf([place, expr]...) [SAL]
(setf [place expr]...) [LISP] – 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...) [LISP] – define a function
(defmacro sym fargs expr...) [LISP] – 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]) [SAL]
(gensym [tag]) [LISP] – generate a symbol
tag – string or number
returns – the new symbol

intern(pname) [SAL]
(intern pname) [LISP] – make an interned symbol
pname – the symbol's print name string
returns – the new symbol

make-symbol(pname) [SAL]
(make-symbol pname) [LISP] – make an uninterned symbol
pname – the symbol's print name string
returns – the new symbol

symbol-name(sym) [SAL]
(symbol-name sym) [LISP] – get the print name of a symbol
sym – the symbol
returns – the symbol's print name

symbol-value(sym) [SAL]
(symbol-value sym) [LISP] – get the value of a symbol
sym – the symbol
returns – the symbol's value

symbol-function(sym) [SAL]
(symbol-function sym) [LISP] – get the functional value of a symbol
sym – the symbol
returns – the symbol's functional value

symbol-plist(sym) [SAL]
(symbol-plist sym) [LISP] – get the property list of a symbol
sym – the symbol
returns – the symbol's property list

hash(sym, n) [SAL]
(hash sym n) [LISP] – 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) [SAL]
(get sym prop) [LISP] – get the value of a property
sym – the symbol
prop – the property symbol
returns – the property value or nil

putprop(sym, val, prop) [SAL]
(putprop sym val prop) [LISP] – 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) [SAL]
(remprop sym prop) [LISP] – remove a property
sym – the symbol
prop – the property symbol
returns – nil

Array Functions

aref(array, n) [SAL]
(aref array n) [LISP] – 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) [SAL]
(make-array size) [LISP] – make a new array
size – the size of the new array (integer)
returns – the new array

vector(expr...) [SAL]
(vector expr...) [LISP] – make an initialized vector
expr – the vector elements
returns – the new vector

List Functions

car(expr) [SAL]
(car expr) [LISP] – return the car of a list node
expr – the list node
returns – the car of the list node

cdr(expr) [SAL]
(cdr expr) [LISP] – return the cdr of a list node
expr – the list node
returns – the cdr of the list node

cxxr(expr) [SAL]
(cxxr expr) [LISP] – all cxxr combinations

cxxxr(expr) [SAL]
(cxxxr expr) [LISP] – all cxxxr combinations

cxxxxr(expr) [SAL]
(cxxxxr expr) [LISP] – all cxxxxr combinations

first(expr) [SAL]
(first expr) [LISP] – a synonym for car

second(expr) [SAL]
(second expr) [LISP] – a synonym for cadr

third(expr) [SAL]
(third expr) [LISP] – a synonym for caddr

fourth(expr) [SAL]
(fourth expr) [LISP] – a synonym for cadddr

rest(expr) [SAL]
(rest expr) [LISP] – a synonym for cdr

cons(expr1, expr2) [SAL]
(cons expr1 expr2) [LISP] – construct a new list node
expr1 – the car of the new list node
expr2 – the cdr of the new list node
returns – nil

list(expr...) [SAL]
(list expr...) [LISP] – create a list of values
expr – expressions to be combined into a list
returns – the new list

append(expr...) [SAL]
(append expr...) [LISP] – append lists
expr – lists whose elements are to be appended
returns – the new list

reverse(expr) [SAL]
(reverse expr) [LISP] – reverse a list
expr – the list to reverse
returns – a new list in the reverse order

last(list) [SAL]
(last list) [LISP] – return the last list node of a list
list – the list
returns – the last list node in the list

member(expr, list, test: test, test-not: test-not) [SAL]
(member expr list &key :test :test-not) [LISP] – 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, test: test, test-not: test-not) [SAL]
(assoc expr alist &key :test :test-not) [LISP] – 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, test: test, test-not: test-not) [SAL]
(remove expr list &key :test :test-not) [LISP] – 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) [SAL]
(remove-if test list) [LISP] – 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) [SAL]
(remove-if-not test list) [LISP] – remove elements that fail test
test – the test predicate
list – the list
returns – copy of list with non-matching elements removed

length(expr) [SAL]
(length expr) [LISP] – 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) [SAL]
(nth n list) [LISP] – 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) [SAL]
(nthcdr n list) [LISP] – 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...) [SAL]
(mapc fcn list1 list...) [LISP] – 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...) [SAL]
(mapcar fcn list1 list...) [LISP] – 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...) [SAL]
(mapl fcn list1 list...) [LISP] – 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...) [SAL]
(maplist fcn list1 list...) [LISP] – 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, test: test, test-not: test-not) [SAL]
(subst to from expr &key :test :test-not) [LISP] – 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, test: test, test-not: test-not) [SAL]
(sublis alist expr &key :test :test-not) [LISP] – 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) [SAL]
(rplaca list expr) [LISP] – 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) [SAL]
(rplacd list expr) [LISP] – 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...) [SAL]
(nconc list...) [LISP] – destructively concatenate lists
list – lists to concatenate
returns – the result of concatenating the lists

delete(expr, list, test: test, test-not: test-not) [SAL]
(delete expr list &key :test :test-not) [LISP] – 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) [SAL]
(delete-if test list) [LISP] – delete elements that pass test
test – the test predicate
list – the list
returns – the list with matching elements deleted

delete-if-not(test, list) [SAL]
(delete-if-not) test list) [LISP] – delete elements that fail test
test – the test predicate
list – the list
returns – the list with non-matching elements deleted

sort(list, test) [SAL]
(sort list test) [LISP] – sort a list
list – the list to sort
test – the comparison function
returns – the sorted list
Note: The comparison function should have two parameters and return true if the first parameter should come before the second parameter in the sorted result. For a list of numbers, built-in comparison functions can be used, e.g. (sort '(3 2 1) #'<) returns (1 2 3). To sort a list of lists by the first element of each list, you can write a function to access the keys and compare them, e.g.
(sort '((3 c) (2 b) (1 a)) #'(lambda (x y) (< (car x) (car y)))) returns
((1 A) (2 B) (3 C)). In SAL, you could write
function my-sort(a, b) return first(a) < first(b)
print sort({{3 c} {2 b} {1 a}}, quote(my-sort)), which will print
{{1 A} {2 B} {3 C}}.

Predicate Functions

atom(expr) [SAL]
(atom expr) [LISP] – is this an atom?
expr – the expression to check
returns – t if the value is an atom, nil otherwise

symbolp(expr) [SAL]
(symbolp expr) [LISP] – is this a symbol?
expr – the expression to check
returns – t if the expression is a symbol, nil otherwise

numberp(expr) [SAL]
(numberp expr) [LISP] – is this a number?
expr – the expression to check
returns – t if the expression is a number, nil otherwise

null(expr) [SAL]
(null expr) [LISP] – is this an empty list?
expr – the list to check
returns – t if the list is empty, nil otherwise

not(expr) [SAL]
(not expr) [LISP] – is this false?
expr – the expression to check
return – t if the value is nil, nil otherwise

listp(expr) [SAL]
(listp expr) [LISP] – is this a list?
expr – the expression to check
returns – t if the value is a cons or nil, nil otherwise

endp(list) [SAL]
(endp list) [LISP] – is this the end of a list
list – the list
returns – t if the value is nil, nil otherwise

consp(expr) [SAL]
(consp expr) [LISP] – is this a non-empty list?
expr – the expression to check
returns – t if the value is a cons, nil otherwise

integerp(expr) [SAL]
(integerp expr) [LISP] – is this an integer?
expr – the expression to check
returns – t if the value is an integer, nil otherwise

floatp(expr) [SAL]
(floatp expr) [LISP] – is this a float?
expr – the expression to check
returns – t if the value is a float, nil otherwise

stringp(expr) [SAL]
(stringp expr) [LISP] – is this a string?
expr – the expression to check
returns – t if the value is a string, nil otherwise

characterp(expr) [SAL]
(characterp expr) [LISP] – is this a character?
expr – the expression to check
returns – t if the value is a character, nil otherwise

arrayp(expr) [SAL]
(arrayp expr) [LISP] – is this an array?
expr – the expression to check
returns – t if the value is an array, nil otherwise

streamp(expr) [SAL]
(streamp expr) [LISP] – is this a stream?
expr – the expression to check
returns – t if the value is a stream, nil otherwise

objectp(expr) [SAL]
(objectp expr) [LISP] – is this an object?
expr – the expression to check
returns – t if the value is an object, nil otherwise

filep(expr) [SAL]
(filep expr) [LISP] – is this a file?
expr – the expression to check
returns – t if the value is an object, nil otherwise
This is not part of standard XLISP nor is it built-in. Nyquist defines it though.

boundp(sym) [SAL]
(boundp sym) [LISP] – is a value bound to this symbol?
sym – the symbol
returns – t if a value is bound to the symbol, nil otherwise

fboundp(sym) [SAL]
(fboundp sym) [LISP] – 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) [SAL]
(minusp expr) [LISP] – is this number negative?
expr – the number to test
returns – t if the number is negative, nil otherwise

zerop(expr) [SAL]
(zerop expr) [LISP] – is this number zero?
expr – the number to test
returns – t if the number is zero, nil otherwise

plusp(expr) [SAL]
(plusp expr) [LISP] – is this number positive?
expr – the number to test
returns – t if the number is positive, nil otherwise

evenp(expr) [SAL]
(evenp expr) [LISP] – is this integer even?
expr – the integer to test
returns – t if the integer is even, nil otherwise

oddp(expr) [SAL]
(oddp expr) [LISP] – is this integer odd?
expr – the integer to test
returns – t if the integer is odd, nil otherwise

eq(expr1, expr2) [SAL]
(eq expr1 expr2) [LISP] – are the expressions identical (pointer equality)? Numbers and strings are generally not eq, e.g. (eq 256 256), (eq 1.0 1.0), and (eq "a" "a") are false.
expr1 – the first expression
expr2 – the second expression
returns – t if they are equal, nil otherwise

eql(expr1, expr2) [SAL]
(eql expr1 expr2) [LISP] – are the expressions of equal value? (eql tests for identical objects (pointer equality) except for numbers. Two numbers can be eql even if they are stored in different locations. However, a FIXNUM is never eql to a FLONUM, i.e. (eql 1 1.0) is false.)
expr1 – the first expression
expr2 – the second expression
returns – t if they are equal, nil otherwise

equal(expr1, expr2) [SAL]
(equal expr1 expr2) [LISP] – are the expressions equal? Arrays are not equal unless they are the same array (pointer equality), but numbers and strings are compared by value, and lists are tested recursively for equal content. A FIXNUM is never equal to a FLONUM.
expr1 – the first expression
expr2 – the second expression
returns – t if they are equal, nil otherwise

Control Constructs

(cond pair...) [LISP] – 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...) [SAL]
(and expr...) [LISP] – 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...) [SAL]
(or expr...) [LISP] – 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]) [LISP] – 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 (default is nil)
returns – the value of the selected expression.
Note that the SAL conditional expression syntax is #?(test, iftrue-expression, iffalse-expression), but #if may be used instead of #?. Either form may omit the third argument, which defaults to nil.

when(texpr, expr...) [SAL]
(when texpr expr...) [LISP] – 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...) [SAL]
(unless texpr expr...) [LISP] – 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...) [LISP] – 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...) [LISP] – create local bindings
(let* (binding...) expr...) [LISP] – 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...) [LISP] – create local functions
(labels (binding...) expr...) [LISP] – flet with recursive functions
(macrolet (binding...) expr...) [LISP] – 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...) [SAL]
(catch sym expr...) [LISP] – 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]) [SAL]
(throw sym [expr]) [LISP] – 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...) [SAL]
(unwind-protect expr cexpr...) [LISP] – 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...) [LISP] – basic looping form
expr – the body of the loop
returns – never returns (must use non-local exit)

(do (binding...) (texpr rexpr...) expr...) [LISP]
(do* (binding...) (texpr rexpr...) expr...) [LISP]
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...) [LISP] – 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...) [LISP] – 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...) [LISP] – the program feature
(prog* (binding...) expr...) [LISP] – 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...) [SAL]
(block name expr...) [LISP] – named block
name – the block name (symbol)
expr – the block body
returns – the value of the last expression

(return [expr]) [LISP] – cause a prog construct to return a value
expr – the value (defaults to nil)
returns – never returns

return-from(name [, value]) [SAL]
(return-from name [value]) [LISP] – return from a named block
name – the block name (symbol)
value – the value to return (defaults to nil)
returns – never returns

tagbody(expr...) [SAL]
(tagbody expr...) [LISP] – block with labels
expr – expression(s) to evaluate or tags (symbols)
returns – nil

go(sym) [SAL]
(go sym) [LISP] – go to a tag within a tagbody or prog
sym – the tag (quoted)
returns – never returns

(progv slist vlist expr...) [LISP] – 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...) [SAL]
(prog1 expr1 expr...) [LISP] – 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...) [SAL]
(prog2 expr1 expr2 expr...) [LISP] – 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...) [SAL]
(progn expr...) [LISP] – execute expressions sequentially
expr – the expressions to evaluate
returns – the value of the last expression (or nil)

Debugging and Error Handling

trace(sym) [SAL]
(trace sym) [LISP] – add a function to the trace list
sym – the function to add (quoted)
returns – the trace list

untrace(sym) [SAL]
(untrace sym) [LISP] – remove a function from the trace list
sym – the function to remove (quoted)
returns – the trace list

error(emsg [, arg]) [SAL]
(error emsg [arg]) [LISP] – 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]) [SAL]
(cerror cmsg emsg [arg]) [LISP] – 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]]) [SAL]
(break [bmsg [arg]]) [LISP] – 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) [LISP] – clean-up after an error
returns – never returns

(top-level) [LISP] – clean-up after an error and return to the top level
returns – never returns

(continue) [LISP] – continue from a correctable error
returns – never returns

(errset expr [pflag]) [LISP] – 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]) [LISP] – print n levels of trace back information
n – the number of levels (defaults to all levels)
returns – nil

(evalhook expr ehook ahook [env]) [LISP] – 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) [SAL]
(profile flag) [LISP] – turn profiling on or off.
flag – nil turns profiling off, otherwise on
returns – the previous state of profiling.
This is not part of standard XLISP.

Arithmetic Functions

truncate(expr) [SAL]
(truncate expr) [LISP] – truncates a floating point number to an integer
expr – the number
returns – the result of truncating the number

float(expr) [SAL]
(float expr) [LISP] – converts an integer to a floating point number
expr – the number
returns – the result of floating the integer

(+ expr...) [LISP] – add a list of numbers
expr – the numbers
returns – the result of the addition

(- expr...) [LISP] – subtract a list of numbers or negate a single number
expr – the numbers
returns – the result of the subtraction

(* expr...) [LISP] – multiply a list of numbers
expr – the numbers
returns – the result of the multiplication

(/ expr...) [LISP] – divide a list of numbers
expr – the numbers
returns – the result of the division

(1+ expr) [LISP] – add one to a number
expr – the number
returns – the number plus one

(1- expr) [LISP] – subtract one from a number
expr – the number
returns – the number minus one

rem(expr...) [SAL]
(rem expr...) [LISP] – remainder of a list of numbers
expr – the numbers
returns – the result of the remainder operation

min(expr...) [SAL]
(min expr...) [LISP] – the smallest of a list of numbers
expr – the expressions to be checked
returns – the smallest number in the list

max(expr...) [SAL]
(max expr...) [LISP] – the largest of a list of numbers
expr – the expressions to be checked
returns – the largest number in the list

abs(expr) [SAL]
(abs expr) [LISP] – the absolute value of a number
expr – the number
returns – the absolute value of the number

gcd(n1, n2...) [SAL]
(gcd n1 n2...) [LISP] – compute the greatest common divisor
n1 – the first number (integer)
n2 – the second number(s) (integer)
returns – the greatest common divisor

random(n) [SAL]
(random n) [LISP] – compute a random number between 0 and |n|-1 inclusive. If n is 0, return 0.
n – the upper bound (integer)
returns – a random number

rrandom() [SAL]
(rrandom) [LISP] – compute a random real number between 0 and 1 inclusive
returns – a random floating point number

random-seed(n) [SAL]
(random-seed n) [LISP] – seed the random number generator with starting seed n. If random-seed is not called, sranddev or some other initialization method will be used by default.
n – the upper bound (integer)
returns – a random number

sin(expr) [SAL]
(sin expr) [LISP] – compute the sine of a number
expr – the floating point number
returns – the sine of the number

cos(expr) [SAL]
(cos expr) [LISP] – compute the cosine of a number
expr – the floating point number
returns – the cosine of the number

tan(expr) [SAL]
(tan expr) [LISP] – compute the tangent of a number
expr – the floating point number
returns – the tangent of the number

atan(expr [, expr2]) [SAL]
(atan expr [expr2]) [LISP] – compute the arctangent
expr – the value of x
expr2 – the value of y (default value is 1.0)
returns – the arctangent of x/y
This is not part of standard XLISP.

expt(x-expr, y-expr) [SAL]
(expt x-expr y-expr) [LISP] – 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) [SAL]
(exp x-expr) [LISP] – compute e to the x power
x-expr – the floating point number
returns – e to the x power

sqrt(expr) [SAL]
(sqrt expr) [LISP] – compute the square root of a number
expr – the floating point number
returns – the square root of the number

(< n1 n2...) [LISP] – test for less than
(<= n1 n2...) [LISP] – test for less than or equal to
(= n1 n2...) [LISP] – test for equal to
(/= n1 n2...) [LISP] – test for not equal to
(>= n1 n2...) [LISP] – test for greater than or equal to
(> n1 n2...) [LISP] – test for greater than
n1 – the first number to compare
n2 – the second number to compare
returns – t if all arguments are numbers and the results of comparing n1 with n2,
n2 with n3, etc., are all true. (FIXNUMS are converted to FLONUMS in mixed-type comparisons.)

Bitwise Logical Functions

logand(expr...) [SAL]
(logand expr...) [LISP] – the bitwise and of a list of numbers
expr – the numbers
returns – the result of the and operation

logior(expr...) [SAL]
(logior expr...) [LISP] – the bitwise inclusive or of a list of numbers
expr – the numbers
returns – the result of the inclusive or operation

logxor(expr...) [SAL]
(logxor expr...) [LISP] – the bitwise exclusive or of a list of numbers
expr – the numbers
returns – the result of the exclusive or operation

lognot(expr) [SAL]
(lognot expr) [LISP] – the bitwise not of a number
expr – the number
returns – the bitwise inversion of number

String Functions

string(expr) [SAL]
(string expr) [LISP] – make a string from a value
expr – an integer (which is first converted into its ASCII character value), string, character, or symbol
returns – the string representation of the argument

string-search(pat, str, start: start, end: end) [SAL]
(string-search pat str &key :start :end) [LISP] – 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
This is not part of standard XLISP.

string-trim(bag, str) [SAL]
(string-trim bag str) [LISP] – 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) [SAL]
(string-left-trim bag str) [LISP] – 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) [SAL]
(string-right-trim bag str) [LISP] – 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, start: start, end: end) [SAL]
(string-upcase str &key :start :end) [LISP] – 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, start: start, end: end) [SAL]
(string-downcase str &key :start :end) [LISP] – 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, start: start, end: end) [SAL]
(nstring-upcase str &key :start :end) [LISP] – 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, start: start, end: end) [SAL]
(nstring-downcase str &key :start :end) [LISP] – convert to lowercase
str – the string
:start – the starting offset
:end – the ending offset + 1
returns – the converted string (not a copy)

strcat(expr...) [SAL]
(strcat expr...) [LISP] – concatenate strings
expr – the strings to concatenate
returns – the result of concatenating the strings

subseq(string, start [, end]) [SAL]
(subseq string start [end]) [LISP] – 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, start1: start1, end1: end1, start2: start2, end2: end2) [SAL]
(string< str1 str2 &key :start1 :end1 :start2 :end2) [LISP]
string<=(str1, str2, start1: start1, end1: end1, start2: start2, end2: end2) [SAL]
(string<= str1 str2 &key :start1 :end1 :start2 :end2) [LISP]
string=(str1, str2, start1: start1, end1: end1, start2: start2, end2: end2) [SAL]
(string= str1 str2 &key :start1 :end1 :start2 :end2) [LISP]
string/=(str1, str2, start1: start1, end1: end1, start2: start2, end2: end2) [SAL]
(string/= str1 str2 &key :start1 :end1 :start2 :end2) [LISP]
string>=(str1, str2, start1: start1, end1: end1, start2: start2, end2: end2) [SAL]
(string>= str1 str2 &key :start1 :end1 :start2 :end2) [LISP]
string>(str1, str2, start1: start1, end1: end1, start2: start2, end2: end2) [SAL]
(string> str1 str2 &key :start1 :end1 :start2 :end2) [LISP]
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, start1: start1, end1: end1, start2: start2, end2: end2) [SAL]
(string-lessp str1 str2 &key :start1 :end1 :start2 :end2) [LISP]
string-not-greaterp(str1, str2, start1: start1, end1: end1, start2: start2, end2: end2) [SAL]
(string-not-greaterp str1 str2 &key :start1 :end1 :start2 :end2) [LISP]
string-equal(str1, str2, start1: start1, end1: end1, start2: start2, end2: end2) [SAL]
(string-equal str1 str2 &key :start1 :end1 :start2 :end2) [LISP]
string-not-equal(str1, str2, start1: start1, end1: end1, start2: start2, end2: end2) [SAL]
(string-not-equal str1 str2 &key :start1 :end1 :start2 :end2) [LISP]
string-not-lessp(str1, str2, start1: start1, end1: end1, start2: start2, end2: end2) [SAL]
(string-not-lessp str1 str2 &key :start1 :end1 :start2 :end2) [LISP]
string-greaterp(str1, str2, start1: start1, end1: end1, start2: start2, end2: end2) [SAL]
(string-greaterp str1 str2 &key :start1 :end1 :start2 :end2) [LISP]
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) [SAL]
(char string index) [LISP] – 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) [SAL]
(upper-case-p chr) [LISP] – is this an upper case character?
chr – the character
returns – t if the character is upper case, nil otherwise

lower-case-p(chr) [SAL]
(lower-case-p chr) [LISP] – is this a lower case character?
chr – the character
returns – t if the character is lower case, nil otherwise

both-case-p(chr) [SAL]
(both-case-p chr) [LISP] – is this an alphabetic (either case) character?
chr – the character
returns – t if the character is alphabetic, nil otherwise

digit-char-p(chr) [SAL]
(digit-char-p chr) [LISP] – is this a digit character?
chr – the character
returns – the digit weight if character is a digit, nil otherwise

char-code(chr) [SAL]
(char-code chr) [LISP] – get the ascii code of a character
chr – the character
returns – the ascii character code (integer)

code-char(code) [SAL]
(code-char code) [LISP] – get the character with a specified ascii code
code – the ascii code (integer)
returns – the character with that code or nil

char-upcase(chr) [SAL]
(char-upcase chr) [LISP] – convert a character to upper case
chr – the character
returns – the upper case character

char-downcase(chr) [SAL]
(char-downcase chr) [LISP] – convert a character to lower case
chr – the character
returns – the lower case character

digit-char(n) [SAL]
(digit-char n) [LISP] – convert a digit weight to a digit
n – the digit weight (integer)
returns – the digit character or nil

char-int(chr) [SAL]
(char-int chr) [LISP] – convert a character to an integer
chr – the character
returns – the ascii character code

int-char(int) [SAL]
(int-char int) [LISP] – convert an integer to a character
int – the ascii character code
returns – the character with that code

char<(chr1, chr2...) [SAL]
(char< chr1 chr2...) [LISP]
char<=(chr1, chr2...) [SAL]
(char<= chr1 chr2...) [LISP]
char=(chr1, chr2...) [SAL]
(char= chr1 chr2...) [LISP]
char/=(chr1, chr2...) [SAL]
(char/= chr1 chr2...) [LISP]
char>=(chr1, chr2...) [SAL]
(char>= chr1 chr2...) [LISP]
char>(chr1, chr2...) [SAL]
(char> chr1 chr2...) [LISP]
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...) [SAL]
(char-lessp chr1 chr2...) [LISP]
char-not-greaterp(chr1, chr2...) [SAL]
(char-not-greaterp chr1 chr2...) [LISP]
char-equal(chr1, chr2...) [SAL]
(char-equal chr1 chr2...) [LISP]
char-not-equal(chr1, chr2...) [SAL]
(char-not-equal chr1 chr2...) [LISP]
char-not-lessp(chr1, chr2...) [SAL]
(char-not-lessp chr1 chr2...) [LISP]
char-greaterp(chr1, chr2...) [SAL]
(char-greaterp chr1 chr2...) [LISP]
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]]]) [SAL]
(read [stream [eof [rflag]]]) [LISP] – 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]) [LISP] – print an expression on a new line
expr – the expression to be printed
stream – the output stream (default is standard output)
returns – the expression

(display label expr...) [LISP] – print expressions and their values
label – a string prefix to print, often the current function name or something to identify the source of this line of output
expr – a list of expressions. Each expression is printed literally without evaluation, then it is evaluated and the value is printed. This helps to generate readable debugging output such as "In foo: A = 4, B = 2.5"
returns – the expression
Note: Output from display can be turned on and off by calling display-on or display-off as described below. This is not part of standard XLISP nor is it built-in. Nyquist defines it though.

(display-on) [LISP] – enable display macro
returns – T
Note: This call gives display its default definition as described above. This is not part of standard XLISP nor is it built-in. Nyquist defines it though.

(display-off) [LISP] – disable display macro
returns – NIL
Note: This call redefines display to just evaluate arguments and not print anything.
This is not part of standard XLISP nor is it built-in. Nyquist defines it though.

prin1(expr [, stream]) [SAL]
(prin1 expr [stream]) [LISP] – print an expression
expr – the expression to be printed
stream – the output stream (default is standard output)
returns – the expression

princ(expr [, stream]) [SAL]
(princ expr [stream]) [LISP] – 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]) [SAL]
(pprint expr [stream]) [LISP] – pretty print an expression
expr – the expressions to be printed
stream – the output stream (default is standard output)
returns – the expression

terpri([stream]) [SAL]
(terpri [stream]) [LISP] – terminate the current print line
stream – the output stream (default is standard output)
returns – nil

flatsize(expr) [SAL]
(flatsize expr) [LISP] – length of printed representation using prin1
expr – the expression
returns – the length

flatc(expr) [SAL]
(flatc expr) [LISP] – length of printed representation using princ
expr – the expression
returns – the length

The Format Function

format(stream, fmt, arg...) [SAL]
(format stream fmt arg...) [LISP] – 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
~<newline> – ignore this one newline and white space on the
next line up to the first non-white-space character or newline. This
allows strings to continue across multiple lines

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, direction: direction) [SAL]
(open fname &key :direction) [LISP] – open a file stream
fname – the file name string or symbol
:direction – :input or :output (default is :input)
returns – a stream

open-binary(fname, direction: direction) [SAL]
(open-binary fname &key :direction) [LISP] – open a binary file stream
fname – the file name string or symbol
:direction – :input or :output (default is :input)
returns – a stream

close(stream) [SAL]
(close stream) [LISP] – close a file stream
stream – the stream
returns – nil

setdir(path [, verbose]) [SAL]
(setdir path [verbose]) [LISP] – set current directory
path – the path of the new directory
verbose – print error message if current directory cannot be changed to path
returns – the resulting full path, e.g. (setdir ".") gets the current working directory, or nil if an error occurs
This is not part of standard XLISP.

listdir(path) [SAL]
(listdir path) [LISP] – get a directory listing
path – the path of the directory to be listed
returns – list of filenames in the directory
This is not part of standard XLISP.

get-temp-path() [SAL]
(get-temp-path) [LISP] – get a path where a temporary file can be created. Under Windows, this is based on environment variables. If XLISP is running as a sub-process to Java, the environment may not exist, in which case the default result is the unfortunate choice c:\windows\.
returns – the resulting full path as a string
This is not part of standard XLISP.

get-user() [SAL]
(get-user) [LISP] – get the user ID. In Unix systems (including OS X and Linux), this is the value of the USER environment variable. In Windows, this is currently just “nyquist”, which is also returned if the environment variable cannot be accessed. This function is used to avoid the case of two users creating files of the same name in the same temp directory.
returns – the string naming the user
This is not part of standard XLISP.

find-in-xlisp-path(filename) [SAL]
(find-in-xlisp-path filename) [LISP] – search the XLISP search path (e.g. XLISPPATH from the environment) for filename. If filename is not found as is, and there is no file extension, append ".lsp" to filename and search again. The current directory is not searched.
filename – the name of the file to search for
returns – a full path name to the first occurrence found
This is not part of standard XLISP.

read-char([stream]) [SAL]
(read-char [stream]) [LISP] – read a character from a stream
stream – the input stream (default is standard input)
returns – the character

peek-char([flag [, stream]]) [SAL]
(peek-char [flag [stream]]) [LISP] – 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

write-char(ch [, stream]) [SAL]
(write-char ch [stream]) [LISP] – 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]]) [SAL]
(read-int [stream [length]]) [LISP] – 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]]) [SAL]
(write-int ch [stream [length]]) [LISP] – 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]]) [SAL]
(read-float [stream [length]]) [LISP] – 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]]) [SAL]
(write-float ch [stream [length]]) [LISP] – 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]) [SAL]
(read-line [stream]) [LISP] – read a line from a stream
stream – the input stream (default is standard input)
returns – the string

read-byte([stream]) [SAL]
(read-byte [stream]) [LISP] – read a byte from a stream
stream – the input stream (default is standard input)
returns – the byte (integer)

write-byte(byte [, stream]) [SAL]
(write-byte byte [stream]) [LISP] – 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 get-output-stream-list return a 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]]) [SAL]
(make-string-input-stream str [start [end]]) [LISP]
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(stream) [SAL]
(make-string-output-stream) [LISP]
returns – an unnamed output stream

get-output-stream-string(stream) [SAL]
(get-output-stream-string stream) [LISP]
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) [SAL]
(get-output-stream-list stream) [LISP]
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.)

get-real-time() [SAL]
(get-real-time) [LISP] – get the time
returns – Time as FLONUM seconds since Jan 1, 1970
Note: Since the time is a large number, you may want to subtract an earlier time to measure a time interval or use a custom format to print enough precision. (See *float-format* in Section Symbols.)

get-run-time() [SAL]
(get-run-time) [LISP] – get the run time based on number of Lisp expression evaluations. Typically, a computer will use one unit of run time in about 10ms, but this can vary either way and depends on CPU speed.
returns – Time as a FIXNUM.

get-env(name) [SAL]
(get-env name) [LISP] – get from an environment variable
name – the name of the environment variable
returns – string value of the environment variable, nil if variable does not exist

(load fname &key :verbose :print) [LISP] – 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) [SAL]
(save fname) [LISP] – save workspace to a file
fname – the filename string or symbol
returns – t if workspace was written, nil otherwise

restore(fname) [SAL]
(restore fname) [LISP] – restore workspace from a file
fname – the filename string or symbol
returns – nil on failure, otherwise never returns

dribble([fname]) [SAL]
(dribble [fname]) [LISP] – 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() [SAL]
(gc) [LISP] – force garbage collection
returns – nil

expand(num) [SAL]
(expand num) [LISP] – expand memory by adding segments
num – the number of segments to add
returns – the number of segments added

alloc(num) [SAL]
(alloc num) [LISP] – change number of nodes to allocate in each segment
num – the number of nodes to allocate
returns – the old number of nodes to allocate

info() [SAL]
(info) [LISP] – show information about memory usage.
returns – nil

room() [SAL]
(room) [LISP] – show memory allocation statistics
returns – nil

type-of(expr) [SAL]
(type-of expr) [LISP] – 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) [SAL]
(peek addrs) [LISP] – peek at a location in memory
addrs – the address to peek at (integer)
returns – the value at the specified address (integer)

poke(addrs, value) [SAL]
(poke addrs value) [LISP] – poke a value into memory
addrs – the address to poke (integer)
value – the value to poke into the address (integer)
returns – the value

bigendianp() [SAL]
(bigendianp) [LISP] – is this a big-endian machine?
returns – T if this a big-endian architecture, storing the high-order byte of an integer at the lowest byte address of the integer; otherwise, NIL.
This is not part of standard XLISP.

address-of(expr) [SAL]
(address-of expr) [LISP] – get the address of an xlisp node
expr – the node
returns – the address of the node (integer)

exit() [SAL]
(exit) [LISP] –
exit xlisp. (Note: in Audacity plug-ins, exit is
undefined because exiting would terminate Audacity.)
returns – never returns

setup-console() [SAL]
(setup-console) [LISP] – 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.

echoenabled(flag) [SAL]
(echoenabled flag) [LISP] – turn console input echoing on or off
flag – T to enable echo, NIL to disable
returns – NIL
Note: This function is only implemented under Linux and Mac OS X. If Nyquist I/O is redirected through pipes,
the Windows version does not echo the input, but the Linux and Mac versions do. You can turn off echoing with
this function. Under windows it is defined to do nothing.

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