Version 2.0February 6, 1988
by
David Michael Betz
127 Taylor Road
Peterborough, NH 03458Copyright (c) 1988, by David Michael Betz
All Rights Reserved
Permission is granted for unrestricted non-commercial use
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.
Then XLISP attempts to load
XLISP then issues the following prompt:
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.
If the symbol
If the symbol
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
If the symbol
If there is no surrounding errset function, XLISP prints the
error message and returns to the top level.
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:
Integer literals consist of a sequence of digits optionally
beginning with a
Floating point literals consist of a sequence of digits
optionally beginning with a
Literal strings are sequences of characters surrounded by double
quotes. Within quoted strings the "
In the case of
XLISP defines several useful read macros:
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
The
The
The
Here is the complete syntax for lambda lists:
where:
rarg is a required argument symbol
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
The
When a method is found, the evaluator binds the receiving object
to the symbol
Within the body of a method, a message can be sent to the current
object by calling the
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
The
Messages:
Messages:
When a new instance of a class is created by sending the message
When a new class is created by sending the
There are several symbols maintained by the read/eval/print
loop. The symbols
An unnamed input stream is setup with the
It is now possible to use the file for input. To read an
expression from the file, just supply the value of the
Once you are done reading from the file, you should close it.
To close the file, use the following expression:
It is now possible to write to this file by supplying the value
of the
Once you are done writing to the file, you should close it.
Closing an output file is just like closing an input file.
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.
init.lsp
from the current
directory. It then loads any files named as parameters on the
command line (after appending .lsp
to their names).
>
This indicates that XLISP is waiting for an 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:
*breakenable*
is
true, the message corresponding to the error is printed. If
the error is correctable, the correction message is printed.
*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.
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.
*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
.
Data Types
There are several different data types available to XLISP
programmers.
The Evaluator
The process of evaluation in XLISP:
Then, the value produced by the previous step is examined:
Lexical Conventions
The following conventions must be followed when entering XLISP
programs:
( ) ' ` , " ;
Uppercase and lowercase characters are not distinguished within
symbol names. All lowercase characters are mapped to uppercase
on input.
+
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.
+
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.
\
" 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 ('|')
: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.
'
<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.
&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.
&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.
&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
.
&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.
(rarg...
[&optional
[oarg | (oarg [init [svar]])]...]
[&rest
rarg]
[&key
[karg | ([karg | (key karg)] [init [svar]])]...
&allow
-other-keys]
[&aux
[aux | (aux [init])]...])
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.
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.
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.
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.
(send self ...)
. The method lookup
starts with the object's class regardless of the class containing
the current method.
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.
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.
:show
- show an object's instance variables.
:class
- return the class of an object
:isa
class - test if object inherits from class
t
if object is an instance of class or a subclass of class, otherwise nil
:isnew
- the default object initialization routine
The "Class" Class
Class
- class of all object classes (including itself)
:new
- create a new instance of a class
:isnew
ivars [cvars [super]] - initialize a new class
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
fargs - the formal argument list (lambda list)
code - a list of executable expressions
returns - the object
: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.
: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)
+
, ++
, 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
returns - the result of evaluating the expression
apply(fun, args)
[SAL]
(apply fun args)
[LISP] - apply a function to a list of arguments
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
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
returns - expr unevaluated
function(expr)
[SAL]
(function expr)
[LISP] - get the functional interpretation
returns - the functional interpretation
backquote(expr)
[SAL]
(backquote expr)
[LISP] - fill in a 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
expr - expressions of the function body
returns - the function closure
get-lambda-expression(closure)
[SAL]
(get-lambda-expression closure)
[LISP] - get the lambda expression
returns - the original lambda expression
macroexpand(form)
[SAL]
(macroexpand form)
[LISP] - recursively expand macro calls
returns - the macro expansion
macroexpand-1(form)
[SAL]
(macroexpand-1 form)
[LISP] - expand a macro call
returns - the macro expansion
Symbol Functions
set(sym, expr)
[SAL]
(set sym expr)
[LISP] - set the value of a symbol
expr - the new value
returns - the new value
setq([sym, expr]...)
[SAL]
(setq [sym expr]...)
[LISP] - set the value of a symbol
expr - the new value
returns - the new value
psetq([sym, expr]...)
[SAL]
(psetq [sym expr]...)
[LISP] - parallel version of setq
expr - the new value
returns - the new value
setf([place, expr]...)
[SAL]
(setf [place expr]...)
[LISP] - set the value of a field
expr - the new value
(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
returns - the new value
(defun sym fargs expr...)
[LISP] - define a function
(defmacro sym fargs expr...)
[LISP] - define a macro
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
returns - the new symbol
intern(pname)
[SAL]
(intern pname)
[LISP] - make an interned symbol
returns - the new symbol
make-symbol(pname)
[SAL]
(make-symbol pname)
[LISP] - make an uninterned symbol
returns - the new symbol
symbol-name(sym)
[SAL]
(symbol-name sym)
[LISP] - get the print name of a symbol
returns - the symbol's print name
symbol-value(sym)
[SAL]
(symbol-value sym)
[LISP] - get the value of a symbol
returns - the symbol's value
symbol-function(sym)
[SAL]
(symbol-function sym)
[LISP] - get the functional value of a symbol
returns - the symbol's functional value
symbol-plist(sym)
[SAL]
(symbol-plist sym)
[LISP] - get the property list of a symbol
returns - the symbol's property list
hash(sym, n)
[SAL]
(hash sym n)
[LISP] - compute the hash index for a symbol
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
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
val - the property value
prop - the property symbol
returns - the property value
remprop(sym, prop)
[SAL]
(remprop sym prop)
[LISP] - remove a property
prop - the property symbol
returns - nil
Array Functions
aref(array, n)
[SAL]
(aref array n)
[LISP] - get the nth element of an 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
returns - the new array
vector(expr...)
[SAL]
(vector expr...)
[LISP] - make an initialized vector
returns - the new vector
List Functions
car(expr)
[SAL]
(car expr)
[LISP] - return the car of a list node
returns - the car of the list node
cdr(expr)
[SAL]
(cdr expr)
[LISP] - return the cdr of a 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
expr2 - the cdr of the new list node
returns - the new list node
list(expr...)
[SAL]
(list expr...)
[LISP] - create a list of values
returns - the new list
append(expr...)
[SAL]
(append expr...)
[LISP] - append lists
returns - the new list
reverse(expr)
[SAL]
(reverse expr)
[LISP] - reverse a list
returns - a new list in the reverse order
last(list)
[SAL]
(last list)
[LISP] - return the last list node of a 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
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
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
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
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
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
returns - the length of the list, vector or string
nth(n, list)
[SAL]
(nth n list)
[LISP] - return the nth element of a list
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
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
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
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
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
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
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
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
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
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
returns - the result of concatenating the lists
delete(expr, test: test, test-not: test-not)
[SAL]
(delete expr &key :test :test-not)
[LISP] - delete elements from a list
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
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
list - the list
returns - the list with non-matching elements deleted
sort(list, test)
[SAL]
(sort list test)
[LISP] - sort a list
test - the comparison function
returns - the sorted list
Predicate Functions
atom(expr)
[SAL]
(atom expr)
[LISP] - is this an atom?
returns - t
if the value is an atom, nil
otherwise
symbolp(expr)
[SAL]
(symbolp expr)
[LISP] - is this a symbol?
returns - t
if the expression is a symbol, nil
otherwise
numberp(expr)
[SAL]
(numberp expr)
[LISP] - is this a number?
returns - t
if the expression is a number, nil
otherwise
null(expr)
[SAL]
(null expr)
[LISP] - is this an empty list?
returns - t
if the list is empty, nil
otherwise
not(expr)
[SAL]
(not expr)
[LISP] - is this false?
return - t
if the value is nil
, nil
otherwise
listp(expr)
[SAL]
(listp expr)
[LISP] - is this a list?
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
returns - t
if the value is nil
, nil
otherwise
consp(expr)
[SAL]
(consp expr)
[LISP] - is this a non-empty list?
returns - t
if the value is a cons, nil
otherwise
integerp(expr)
[SAL]
(integerp expr)
[LISP] - is this an integer?
returns - t
if the value is an integer, nil
otherwise
floatp(expr)
[SAL]
(floatp expr)
[LISP] - is this a float?
returns - t
if the value is a float, nil
otherwise
stringp(expr)
[SAL]
(stringp expr)
[LISP] - is this a string?
returns - t
if the value is a string, nil
otherwise
characterp(expr)
[SAL]
(characterp expr)
[LISP] - is this a character?
returns - t
if the value is a character, nil
otherwise
arrayp(expr)
[SAL]
(arrayp expr)
[LISP] - is this an array?
returns - t
if the value is an array, nil
otherwise
streamp(expr)
[SAL]
(streamp expr)
[LISP] - is this a stream?
returns - t
if the value is a stream, nil
otherwise
objectp(expr)
[SAL]
(objectp expr)
[LISP] - is this an object?
returns - t
if the value is an object, nil
otherwise
filep(expr)
[SAL]
(filep expr)
[LISP] (Footnote 8) - is this a file?
returns - t
if the value is an object, nil
otherwise
boundp(sym)
[SAL]
(boundp sym)
[LISP] - is a value bound to this 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?
returns - t
if a functional value is bound to the symbol,
nil
otherwise
minusp(expr)
[SAL]
(minusp expr)
[LISP] - is this number negative?
returns - t
if the number is negative, nil
otherwise
zerop(expr)
[SAL]
(zerop expr)
[LISP] - is this number zero?
returns - t
if the number is zero, nil
otherwise
plusp(expr)
[SAL]
(plusp expr)
[LISP] - is this number positive?
returns - t
if the number is positive, nil
otherwise
evenp(expr)
[SAL]
(evenp expr)
[LISP] - is this integer even?
returns - t
if the integer is even, nil
otherwise
oddp(expr)
[SAL]
(oddp expr)
[LISP] - is this integer odd?
returns - t
if the integer is odd, nil
otherwise
eq(expr1, expr2)
[SAL]
(eq expr1 expr2)
[LISP] - are the expressions identical?
expr2 - the second expression
returns - t
if they are equal, nil
otherwise
eql(expr1, expr2)
[SAL]
(eql expr1 expr2)
[LISP] - are the expressions identical? (works with all numbers)
expr2 - the second expression
returns - t
if they are equal, nil
otherwise
equal(expr1, expr2)
[SAL]
(equal expr1 expr2)
[LISP] - are the expressions equal?
expr2 - the second expression
returns - t
if they are equal, nil
otherwise
Control Constructs
(cond pair...)
[LISP] - evaluate conditionally
where:
returns - the value of the first expression whose predicate is not
expr - evaluated if the predicate
is not nil
nil
and(expr...)
[SAL]
(and expr...)
[LISP] - the logical and of a list of expressions
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
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])
[SAL]
(if texpr expr1 [expr2])
[LISP] - evaluate expressions conditionally
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...)
[SAL]
(when texpr expr...)
[LISP] - evaluate only when a condition is true
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
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
case - pair consisting of:
where:
returns - the value of the last expression of the matching case
expr - are expressions to execute if the
case matches
(let (binding...) expr...)
[LISP] - create local bindings
(let* (binding...) expr...)
[LISP] - let with sequential binding
expr - the expressions to be evaluatednil
)
2) a list whose car is a symbol and whose cadr
is an initialization expression
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
where:
expr - the expressions to be evaluated
fargs - formal argument list (lambda list)
expr - expressions constituting the body of
the function/macro
returns - the value of the last expression
catch(sym, expr...)
[SAL]
(catch sym expr...)
[LISP] - evaluate expressions and catch throws
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
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
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
returns - never returns (must use non-local exit)
(do (binding...) (texpr rexpr...) expr...)
[LISP]
(do* (binding...) (texpr rexpr...) expr...)
[LISP]
texpr - the termination test expressionnil
)
2) a list of the form: (sym init [step])
where:
init - is the initial value of the symbol
step - is a step 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
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
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
expr - expressions to evaluate or tags (symbols)nil
)
2) a list whose car is a symbol and whose cadr
is an initialization expression
returns - nil
or the argument passed to the return function
block(name, expr...)
[SAL]
(block name expr...)
[LISP] - named block
expr - the block body
returns - the value of the last expression
(return [expr])
[LISP] - cause a prog construct to return a value
nil
)
returns - never returns
return-from(name[, value])
[SAL]
(return-from name [value])
[LISP] - return from a named block
value - the value to return (defaults to nil
)
returns - never returns
tagbody(expr...)
[SAL]
(tagbody expr...)
[LISP] - block with labels
returns - nil
go(sym)
[SAL]
(go sym)
[LISP] - go to a tag within a tagbody or prog
returns - never returns
(progv slist vlist expr...)
[LISP] - dynamically bind 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
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
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
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
returns - the trace list
untrace(sym)
[SAL]
(untrace sym)
[LISP] - remove a function from the trace list
returns - the trace list
error(emsg[, arg])
[SAL]
(error emsg [arg])
[LISP] - signal a non-correctable error
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
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
**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
(top-level)
[LISP] - clean-up after an error and return to the top level
(continue)
[LISP] - continue from a correctable error
(errset expr [pflag])
[LISP] - trap errors
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
returns - nil
(evalhook expr ehook ahook [env])
[LISP] - evaluate with hooks
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] (Footnote 9) - turn profiling on or off.
nil
turns profiling off, otherwise on
returns - the previous state of profiling.
Arithmetic Functions
truncate(expr)
[SAL]
(truncate expr)
[LISP] - truncates a floating point number to an integer
returns - the result of truncating the number
float(expr)
[SAL]
(float expr)
[LISP] - converts an integer to a floating point number
returns - the result of floating the integer
(+ expr...)
[LISP] - add a list of numbers
returns - the result of the addition
(- expr...)
[LISP] - subtract a list of numbers or negate a single number
returns - the result of the subtraction
(* expr...)
[LISP] - multiply a list of numbers
returns - the result of the multiplication
(/ expr...)
[LISP] - divide a list of numbers
returns - the result of the division
(1+ expr)
[LISP] - add one to a number
returns - the number plus one
(1- expr)
[LISP] - subtract one from a number
returns - the number minus one
rem(expr...)
[SAL]
(rem function) expr...)
[LISP] - remainder of a list of numbers
returns - the result of the remainder operation
min(expr...)
[SAL]
(min expr...)
[LISP] - the smallest of a list of numbers
returns - the smallest number in the list
max(expr...)
[SAL]
(max expr...)
[LISP] - the largest of a list of numbers
returns - the largest number in the list
abs(expr)
[SAL]
(abs expr)
[LISP] - the absolute value of a number
returns - the absolute value of the number
gcd(n1, n2...)
[SAL]
(gcd n1 n2...)
[LISP] - compute the greatest common divisor
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
returns - a random number
rrandom()
[SAL]
(rrandom)
[LISP] - compute a random real number between 0 and 1 inclusive
sin(expr)
[SAL]
(sin expr)
[LISP] - compute the sine of a number
returns - the sine of the number
cos(expr)
[SAL]
(cos expr)
[LISP] - compute the cosine of a number
returns - the cosine of the number
tan(expr)
[SAL]
(tan expr)
[LISP] - compute the tangent of a number
returns - the tangent of the number
atan(expr[, expr2])
[SAL]
(atan expr [expr2])
[LISP] (Footnote 10) - compute the arctangent
expr2 - the value of y (default value is 1.0)
returns - the arctangent of x/y
expt(x-expr, y-expr)
[SAL]
(expt x-expr y-expr)
[LISP] - compute x to the y power
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
returns - e to the x power
sqrt(expr)
[SAL]
(sqrt expr)
[LISP] - compute the square root of a 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
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...)
[SAL]
(logand expr...)
[LISP] - the bitwise and of a list of numbers
returns - the result of the and operation
logior(expr...)
[SAL]
(logior expr...)
[LISP] - the bitwise inclusive or of a list of numbers
returns - the result of the inclusive or operation
logxor(expr...)
[SAL]
(logxor expr...)
[LISP] - the bitwise exclusive or of a list of numbers
returns - the result of the exclusive or operation
lognot(expr)
[SAL]
(lognot expr)
[LISP] - the bitwise not of a number
returns - the bitwise inversion of number
String Functions
string(expr)
[SAL]
(string expr)
[LISP] - make a string from a value
returns - the string representation of the argument
string-search(pat, str, start: start, end: end)
[SAL]
(string-search pat str &key :start :end)
[LISP] (Footnote 11) - search for pattern in string
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)
[SAL]
(string-trim bag str)
[LISP] - trim both ends of a string
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
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
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
: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
: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
: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
:start - the starting offset
:end - the ending offset + 1
returns - the converted string (not a copy)
strcat(expr...)
[SAL]
(strcat expr...)
[LISP] - concatenate strings
returns - the result of concatenating the strings
subseq(string, start[, end])
[SAL]
(subseq string start [end])
[LISP] - extract a substring
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]
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-equalp(str1, str2, start1: start1, end1: end1, start2: start2, end2: end2)
[SAL]
(string-equalp str1 str2 &key :start1 :end1 :start2 :end2)
[LISP]
string-not-equalp(str1, str2, start1: start1, end1: end1, start2: start2, end2: end2)
[SAL]
(string-not-equalp 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]
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
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?
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?
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?
returns - t
if the character is alphabetic, nil
otherwise
digit-char-p(chr)
[SAL]
(digit-char-p chr)
[LISP] - is this a digit 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
returns - the ascii character code (integer)
code-char(code)
[SAL]
(code-char code)
[LISP] - get the character with a specified ascii code
returns - the character with that code or nil
char-upcase(chr)
[SAL]
(char-upcase chr)
[LISP] - convert a character to upper case
returns - the upper case character
char-downcase(chr)
[SAL]
(char-downcase chr)
[LISP] - convert a character to lower case
returns - the lower case character
digit-char(n)
[SAL]
(digit-char n)
[LISP] - convert a digit weight to a digit
returns - the digit character or nil
char-int(chr)
[SAL]
(char-int chr)
[LISP] - convert a character to an integer
returns - the ascii character code
int-char(int)
[SAL]
(int-char int)
[LISP] - convert an integer to a character
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]
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-equalp(chr1, chr2...)
[SAL]
(char-equalp chr1 chr2...)
[LISP]
char-not-equalp(chr1, chr2...)
[SAL]
(char-not-equalp 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]
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
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
stream - the output stream (default is standard output)
returns - the expression
prin1(expr[, stream])
[SAL]
(prin1 expr [stream])
[LISP] - print an expression
stream - the output stream (default is standard output)
returns - the expression
princ(expr[, stream])
[SAL]
(princ expr [stream])
[LISP] - print an expression without quoting
stream - the output stream (default is standard output)
returns - the expression
pprint(expr[, stream])
[SAL]
(pprint expr [stream])
[LISP] - pretty print an expression
stream - the output stream (default is standard output)
returns - the expression
terpri([stream])
[SAL]
(terpri [stream])
[LISP] - terminate the current print line
returns - nil
flatsize(expr)
[SAL]
(flatsize expr)
[LISP] - length of printed representation using prin1
returns - the length
flatc(expr)
[SAL]
(flatc expr)
[LISP] - length of printed representation using princ
returns - the length
The Format Function
The format string can contain characters that should be copied
directly to the output and formatting directives. The
formatting directives are:
format(stream, fmt, arg...)
[SAL]
(format stream fmt arg...)
[LISP] - do formated
output
fmt - the format string
arg - the format arguments
returns - output string if stream is nil
, nil
otherwise
~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
: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
:direction - :input or :output (default is :input)
returns - a stream
close(stream)
[SAL]
(close stream)
[LISP] - close a file stream
returns - nil
setdir(path)
[SAL]
(setdir path)
[LISP] (Footnote 12) - set current directory
returns - the resulting full path, e.g. (setdir ".") gets the current working directory, or nil
if an error occurs
listdir(path)
[SAL]
(listdir path)
[LISP] (Footnote 13) - get a directory listing
returns - list of filenames in the directory
get-temp-path()
[SAL]
(get-temp-path)
[LISP] (Footnote 14) - 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\
.
get-user()
[SAL]
(get-user)
[LISP] (Footnote 15) - 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.
find-in-xlisp-path(filename)
[SAL]
(find-in-xlisp-path filename)
[LISP] (Footnote 16) - 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.
returns - a full path name to the first occurrence found
read-char([stream])
[SAL]
(read-char [stream])
[LISP] - read a character from a stream
returns - the character
peek-char([flag[, stream]])
[SAL]
(peek-char [flag [stream]])
[LISP] - peek at the next character
nil
)
stream - the input stream (default is standard input)
returns - the character (integer)
write-char(ch[, stream])
[SAL]
(write-char ch [stream])
[LISP] - write a character to a stream
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
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
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
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
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
returns - the string
read-byte([stream])
[SAL]
(read-byte [stream])
[LISP] - read a byte from a stream
returns - the byte (integer)
write-byte(byte[, stream])
[SAL]
(write-byte byte [stream])
[LISP] - write a byte to a stream
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.
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]
start - the starting offset
end - the ending offset + 1
returns - an unnamed stream that reads from the string
make-string-output-stream)()
[SAL]
(make-string-output-stream)
[LISP]
get-output-stream-string(stream)
[SAL]
(get-output-stream-string stream)
[LISP]
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]
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-env(name)
[SAL]
(get-env name)
[LISP] - get from an 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
: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
returns - t
if workspace was written, nil
otherwise
restore(fname)
[SAL]
(restore fname)
[LISP] - restore workspace from a file
returns - nil
on failure, otherwise never returns
dribble([fname])
[SAL]
(dribble [fname])
[LISP] - create a file with a transcript of a session
returns - t
if the transcript is opened, nil
if it is closed
gc()
[SAL]
(gc)
[LISP] - force garbage collection
nil
expand(num)
[SAL]
(expand num)
[LISP] - expand memory by adding segments
returns - the number of segments added
alloc(num)
[SAL]
(alloc num)
[LISP] - change number of nodes to allocate in each segment
returns - the old number of nodes to allocate
info()
[SAL]
(info)
[LISP] - show information about memory usage.
nil
room()
[SAL]
(room)
[LISP] - show memory allocation statistics
nil
type-of(expr)
[SAL]
(type-of expr)
[LISP] - returns the type of the expression
returns - nil
if the value is nil
otherwise one of the 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
returns - the value at the specified address (integer)
poke(addrs, value)
[SAL]
(poke addrs value)
[LISP] - poke a value into memory
value - the value to poke into the address (integer)
returns - the value
bigendianp()
[SAL]
(bigendianp)
[LISP] - is this a big-endian machine?
address-of(expr)
[SAL]
(address-of expr)
[LISP] - get the address of an xlisp node
returns - the address of the node (integer)
exit()
[SAL]
(exit)
[LISP] - exit xlisp
setup-console()
[SAL]
(setup-console)
[LISP] - set default console attributes
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
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
.
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
).
(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.
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.
(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