XLISP-PLUS: Another Object-oriented Lisp
May 27, 1994
Tom Almy
tom.almy@tek.com
Portions of
this manual and software are from XLISP which is Copyright (c)
1988, by David
Michael Betz, all
rights reserved. Mr.
Betz grants
permission for unrestricted non-commercial use. Portions
of XLISP-PLUS from
XLISP-STAT are Copyright (c) 1988, Luke Tierney. UNIXSTUF.C
is from Winterp
1.0,
Copyright 1989 Hewlett-Packard Company (by Niels
Mayer). Other
enhancements
and bug fixes are provided
without restriction by Tom Almy,
Mikael
Pettersson, Neal Holtz,
Johnny Greenblatt, Ken Whedbee,
Blake
McBride, Pete Yadlowsky, and Richard Zidlicky. See
source code for details.
Table of Contents
INTRODUCTION .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
XLISP COMMAND LOOP
. . . . . . . . . . . . . . . . . . . . . . . . . . 2
BREAK COMMAND LOOP
. . . . . . . . . . . . . . . . . . . . . . . . . . 4
DATA TYPES . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
THE EVALUATOR . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 7
HOOK FUNCTIONS
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
LEXICAL CONVENTIONS . . . . . . . . . . . . . . . . .
. . . . . . . . . 9
8 BIT ASCII CHARACTERS . . . . . . . . . . . . . . . . . . . . . . . . 11
READTABLES . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
SYMBOL CASE CONTROL . . . . . . . . . . . . . . . . .
. . . . . . . . . 14
PACKAGES . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
LAMBDA LISTS .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
OBJECTS . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 19
SYMBOLS . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 23
EVALUATION FUNCTIONS
. . . . . . . . . . . . . . . . . . . . . . . . . 25
MULTIPLE VALUE FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . 27
SYMBOL FUNCTIONS
. . . . . . . . . . . . . . . . . . . . . . . . . . . 28
PACKAGE FUNCTIONS . . . . . . . . . . . . . . . . . .
. . . . . . . . . 32
PROPERTY LIST FUNCTIONS . . . . . . . . . . . . . . .
. . . . . . . . . 36
HASH TABLE FUNCTIONS
. . . . . . . . . . . . . . . . . . . . . . . . . 37
ARRAY FUNCTIONS . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 38
SEQUENCE FUNCTIONS
. . . . . . . . . . . . . . . . . . . . . . . . . . 39
LIST FUNCTIONS
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
DESTRUCTIVE LIST FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . 48
ARITHMETIC FUNCTIONS
. . . . . . . . . . . . . . . . . . . . . . . . . 49
BITWISE LOGICAL FUNCTIONS . . . . . . . . . . . . . .
. . . . . . . . . 54
STRING FUNCTIONS
. . . . . . . . . . . . . . . . . . . . . . . . . . . 55
CHARACTER FUNCTIONS . . . . . . . . . . . . . . . . .
. . . . . . . . . 57
XLISP 2.1g Table of Contents
STRUCTURE FUNCTIONS . . . . . . . . . . . . . . . . .
. . . . . . . . . 59
OBJECT FUNCTIONS
. . . . . . . . . . . . . . . . . . . . . . . . . . . 61
PREDICATE FUNCTIONS . . . . . . . . . . . . . . . . .
. . . . . . . . . 63
CONTROL CONSTRUCTS
. . . . . . . . . . . . . . . . . . . . . . . . . . 67
LOOPING CONSTRUCTS
. . . . . . . . . . . . . . . . . . . . . . . . . . 70
THE PROGRAM FEATURE . . . . . . . . . . . . . . . . .
. . . . . . . . . 71
INPUT/OUTPUT FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . 73
THE FORMAT FUNCTION . . . . . . . . . . . . . . . . .
. . . . . . . . . 75
FILE I/O FUNCTIONS
. . . . . . . . . . . . . . . . . . . . . . . . . . 78
STRING STREAM FUNCTIONS . . . . . . . . . . . . . . .
. . . . . . . . . 82
DEBUGGING AND ERROR HANDLING FUNCTIONS . . . . . . . . . . . . . . . . 83
SYSTEM FUNCTIONS
. . . . . . . . . . . . . . . . . . . . . . . . . . . 85
ADDITIONAL FUNCTIONS AND UTILITIES . . . . . . . . . . . . . . . . . . 91
BUG FIXES AND EXTENSIONS . . . . . . . . . . . . . . . . . . . . . . . 95
EXAMPLES: FILE I/O FUNCTIONS . . . . . . . . . . . . . . . . . . . . . 104
INDEX . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 106
XLISP 2.1g INTRODUCTION Page 1
INTRODUCTION
XLISP-PLUS is
an enhanced version of David Michael Betz's XLISP to have
additional
features of Common Lisp. XLISP-PLUS is distributed for the IBM-
PC family and
for UNIX, but can be easily ported
to other platforms.
Complete source code
is provided (in "C")
to allow easy modification and
extension.
Since XLISP-PLUS is based on XLISP, most XLISP programs will run on XLISP-
PLUS. Since XLISP-PLUS incorporates many more features
of Common Lisp, many
small
Common Lisp applications will run on
XLISP-PLUS with little
modification.
See the section starting on
page 95 for details
of the
differences between XLISP and XLISP-PLUS.
Many Common
Lisp functions are built into
XLISP-PLUS. 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
heirarchy 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-PLUS.
It assumes some
knowledge of LISP and some understanding of the
concepts of object-oriented
programming.
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.
XLISP-PLUS has
a number of compilation options
to to eliminate groups of
functions and
to tailor itself to various
environments. Unless otherwise
indicated this
manual assumes all options
are enabled and the
system
dependent code is as complete as that provided for the
MS/DOS environment.
Assistance for
using or porting XLISP-PLUS can
be obtained on the USENET
newsgroup
comp.lang.lisp.x, or by writing to
Tom Almy at the Internet
address tom.almy@tek.com. You can also reach Tom by
writing to him at 17830
SW Shasta Trail, Tualatin, OR 97062, USA.
XLISP 2.1g XLISP COMMAND LOOP Page 2
XLISP COMMAND LOOP
When XLISP is started, it first tries to load the
workspace "xlisp.wks", or
an alternative
file specified with
the "-wfilename"
option, from the
current directory. If that file doesn't exist, or the "-w" flag is in the
command
line, XLISP builds an initial
workspace, empty except for the
built-in functions and symbols.
Then,
providing no workspace file was
loaded, XLISP attempts to load
"init.lsp" from a path in XLPATH or the
current directory. This file can be
modified
to suit the
user's requirements. It
contains a number
of
preference items.
If *startup-functions* is non-nil (default is nil), it is taken as a list
of functions with no arguments which are executed in
sequence at this time.
This allows automatically starting applications stored
in workspaces.
If the
variable *load-file-arguments* is non-nil (default is "t"), it then
loads any
files named as parameters on the
command line (after appending
".lsp" to their names). If the "-v" flag is in the command
line, then the
files are loaded verbosely.
The option "-tfilename" will open a
transcript file of the name "filename".
At this time
the top level command loop is
entered. This is the function
TOP-LEVEL-LOOP, by default.
XLISP then
issues the following prompt (unless standard input has been
redirected):
>
This indicates that XLISP is waiting for an expression to be typed. If the
current package is other than USER, the the package
name is printed before
the ">".
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 for another expression.
The following
control characters can be
used while XLISP is waiting for
input:
Backspace
delete last character
Del delete last character
tab tabs over (treated as space by XLISP
reader)
ctrl-C
goto top level
ctrl-G cleanup and return one level
ctrl-Z end of file (returns one level or exits
program)
ctrl-P proceed (continue)
ctrl-T print information
Under MS-DOS (at least) the following control
characters can be typed while
XLISP is executing (providing standard input has not been redirected away
from the console):
XLISP 2.1g XLISP COMMAND LOOP Page 3
ctrl-B BREAK -- enter break loop
ctrl-S Pause until another key is struck
ctrl-C go to top level
ctrl-T print information
Under MS-DOS if the global variable *dos-input* is set
non-NIL, DOS is used
to read entire input lines. Operation this way is
convenient if certain DOS
utilities, such as
CED, are used, or if XLISP is
run under an editor like
EPSILON. In
this case, normal command line
editing is available, but the
control keys will not work (in particular, ctrl-C will
cause the program to
exit!). Use the XLISP
functions top-level, clean-up, and continue instead
of ctrl-C, ctrl-G, and ctrl-P.
Under MS-DOS if the
global variable *dos-input* is NIL, a special internal
line editor is used. In this case the last 20 lines are saved, and can be
recalled and
viewed using the up and down arrow
keys. Duplicate lines are
not saved.
An additional
feature is symbol name lookup. This command takes what
appears to be
an incomplete symbol name to the
left of the cursor and
prints
all interned symbol
names that match.
Case is ignored.
The
printnames of the symbols are printed without
processing.
The control keys for the editor are:
Up
Arrow Previous command in queue
Down
Arrow Next command in queue
Left
Arrow Move cursor to left
Right
Arrow Move cursor to right
Home Move cursor to start of line
End Move cursor to end of line
Delete Delete character at cursor
Backspace
Delete character to left of cursor
Escape Delete current line
Tab Look up partial symbol name to left of
cursor
Characters are inserted at the current cursor position. Lines are limited
in length to
the width of the display, and invalid keystrokes cause the
bell to ring.
XLISP 2.1g BREAK COMMAND LOOP Page 4
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.
If XLISP was invoked with the command line argument
"-b" then XLISP assumes
it is running in
batch mode. In batch mode any
uncaught error will cause
XLISP to exit after printing the error message.
XLISP 2.1g DATA TYPES Page 5
DATA TYPES
There are several different data types available to
XLISP-PLUS programmers.
Typical implementation limits are shown for 32
bit word systems. Values in
square brackets apply to 16 bit MS-DOS
implementations.
All data nodes
are effectively cons cells
consisting of two pointers and
one or two
bytes of identification flags (9
or 10 bytes per cell). Node
space is managed and
garbage collected by XLISP. Array and
string storage
is either allocated
by the C runtime or managed and
garbaged collected by
XLISP (compilation option). If C does the allocation, memory fragmentation
can occur.
Fragmentation can be
eliminated by saving
the image and
restarting XLISP-PLUS.
˘ NIL
Unlike the original XLISP,
NIL is a symbol (although not in the
*obarray*),
to allowing setting its properties.
˘ lists
Either
NIL or a CDR-linked list of cons cells,
terminated by a symbol
(typically
NIL). Circular lists are allowable, but
can cause problems
with some
functions so they must be used with care.
˘
arrays
The CDR
field of an array points to the
dynamically allocated data
array, while
the CAR contains the
integer length of the
array.
Elements
in the data array are pointers to other
cells [Size limited
to about
16360].
˘
character strings
Implemented like arrays, except string array is
byte indexed and
contains
the actual characters. Note that unlike the underlying C, the
null
character (value 0) is valid. [Size limited to about 65500]
˘
symbols
Implemented as a 4
element array. The
elements are value cell,
function cell, property list, and print name
(a character string
node).
Print names are limited to 100 characters. There are also flags
for
constant and special. Values bound to special symbols (declared
with
DEFVAR or DEFPARAMETER) are always dynamically bound, rather than
being
lexically bound.
˘
fixnums (integers)
Small
integers (> -129 and <256) are statically allocated and are thus
always EQ integers of the same value. The CAR field
is used to hold
the value,
which is a 32 bit signed integer.
˘
ratios
The CAR field is used to hold the numerator
while the CDR field is
used to hold the denominator. The numerator is a 32 bit signed value
while the
denominator is a 31 bit positive value.
˘
characters
All characters are statically allocated and are
thus EQ characters of
the
same value. The CAR field is
used to hold the value. In XLISP
characters
are "unsigned" and thus range in value from 0 to 255.
˘
flonums (floating point numbers)
The
CAR and CDR fields hold the value, which is typically a 64 bit
IEEE
floating point number.
XLISP 2.1g DATA TYPES Page 6
˘
complex numbers
Part of
the math extension compilation option. Internally
implemented
as an
array of the real and imaginary parts. The
parts can be either
both fixnums
or both flonums. Any function
which would return an
fixnum complex number with a zero
imaginary part returns just the
fixnum.
˘
objects
Implemented as an array of
instance variable count plus one elements.
The first
element is the object's class, while the remaining arguments
are the
instance variables.
˘
streams (file)
The CAR and CDR fields are used in a system dependent way as a file
pointer.
˘
streams (unnamed -- string)
Implemented
as a tconc-style list of characters.
˘ subrs
(built-in functions)
The
CAR field points to the
actual code to execute,
while the CDR
field is
an internal pointer to the name of the function.
˘
fsubrs (special forms)
Same
implementation as subrs.
˘
closures (user defined functions)
Implemented
as an array of 11 elements:
1. name symbol or NIL
2. 'lambda or 'macro
3. list of required arguments
4. optional
arguments as list
of (<arg> <init> <specified-p>)
triples.
5. &rest argument
6. &key
arguments as list of (<key> <arg> <init>
<specified-p>)
quadruples.
7. &aux arguments as list of (<arg>
<init>) pairs.
8. function body
9. value environment (see page 84 for format)
10. function environment
11. argument list (unprocessed)
˘
structures
Implemented as an array with first
element being a pointer to the
structure
name string, and the remaining elements
being the structure
elements.
˘
hash-tables
Implemented as a structure
of varying length with no
generalized
accessing functions,
but with a
special print function
(print
functions
not available for standard structures).
˘
random-states
Implemented as a structure with
a single element which is the random
state (here
a fixnum, but
could change without
impacting xlisp
programs).
˘
packages
Implemented using a structure. Packages must only be manipulated with
the
functions provided.
XLISP 2.1g THE EVALUATOR Page 7
THE EVALUATOR
The process of evaluation in XLISP:
Strings,
characters, numbers of any type,
objects, arrays, structures,
streams, subrs, fsubrs and closures evaluate to
themselves.
Symbols act
as variables and are evaluated
by retrieving the
value
associated with their current binding.
Lists are
evaluated by examining the first element of the list and then
taking one of the following actions:
If it is a
symbol, the functional binding of the symbol is retrieved.
If it
is a lambda expression, a closure is constructed for the
function
described by the lambda expression.
If it is a
subr, fsubr or closure, it stands for itself.
Any other
value is an error.
Then, the value produced by the previous step is
examined:
If it is a
subr or closure, the remaining list
elements are evaluated
and the
subr or closure is applied to these evaluated expressions.
If it is
an fsubr, the fsubr
is called with the remaining list
elements
as arguments (unevaluated).
If it is
a macro, the macro is
expanded with the remaining list
elements as
arguments (unevaluated). The macro
expansion is then
evaluated in
place of the
original macro call.
If the symbol
*displace-macros* is not
NIL, then the
expanded macro will
(destructively)
replace the original macro expression. This means that
the
macro will only be expanded once, but the original code will be
lost. The displacement will not take place unless the macro expands
into a
list. The standard XLISP practice is the macro will be expanded
each time
the expression is
evaluated, which negates some of the
advantages
of using macros.
XLISP 2.1g HOOK FUNCTIONS Page 8
HOOK FUNCTIONS
The evalhook and applyhook facility are useful for
implementing debugging
programs or
just observing the operation
of XLISP. It is possible
to
control evaluation of forms in any context.
If the symbol '*evalhook*' is bound to a function closure, then every call
of eval will
call this function. The function takes two arguements, the
form to be
evaluated and execution
environment. During the execution of
this function, *evalhook* (and *applyhook*) are
dynamically bound to NIL to
prevent undesirable recursion. This "hook" function returns the result of
the evaluation.
If the symbol
'*applyhook*' is bound to a function, then every function
application within an eval will call this
function (note that the function
apply, and
others which do not use eval,
will not invoke the apply hook
function). The function takes two arguments, the function closure and the
argument list (which is already evaluated). During execution of this hook
function, *applyhook*
(and *evalhook*) are
dynamically bound to NIL
to
prevent undesired recursion. This function is to return the result of the
function application.
Note that the hook functions cannot reset *evalhook*
or *applyhook* to NIL,
because
upon exit these values will
be reset. An excape
mechanism is
provided --
execution of 'top-level', or any
error that causes return to
the top level,
will unhook the functions. Applications should bind these
values either via 'progv', 'evalhook', or 'applyhook'.
The functions 'evalhook' and 'applyhook' allowed for
controlled application
of the hook
functions. The form supplied as an
argument to 'evalhook', or
the function
application given to 'applyhook', are
not hooked themselves,
but any
subsidiary forms and applications are. In addition, by supplying
NIL values for the hook functions, 'evalhook' can be
used to execute a form
within a specific environment passed as an argument.
An additional hook function exists for the garbage
collector. If the symbol
'*gc-hook*' is
bound to a function, then this
function is called after
every garbage collection. The function has two
arguments. The first is the
total number
of nodes, and the second is the
number of nodes free. The
return value is ignored. During the execution of the
function, *gc-hook* is
dynamically bound to NIL to prevent undesirable
recursion.
XLISP 2.1g LEXICAL CONVENTIONS Page 9
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.
Except when escape sequences are used, symbol names in
XLISP can consist of
any sequence of non-blank printable characters except
the terminating macro
characters:
( ) ' ` ,
" ;
and the escape characters:
\ |
In addition,
the first character may not
be '#' (non-terminating macro
character),
nor may the symbol
have identical syntax
with a numeric
literal. Uppercase
and lowercase characters are
not distinguished within
symbol
names because, by default,
lowercase characters are mapped
to
uppercase on input.
Any printing character, including whitespace, may be part of a symbol name
when
escape characters are used.
The backslash escapes the
following
character, while multiple characters can be escaped by
placing them between
vertical bars. At
all times the backslash must
be used to escape either
escape characters.
For semantic
reasons, certain chararacter sequences should/can never be
used as symbols in XLISP. A single period is used to denote dotted lists.
The symbol T
is also reserved for use as the
truth value. The symbol NIL
represents an empty list.
Symbols starting with
a colon are keywords, and will always evaluate to
themselves. When the package facility is compiled as part of XLISP, colons
have a special
significance. Thus colons should
not be used as part of a
symbol name, except for these special uses.
Fixnum (integer)
literals consist of a
sequence of digits optionally
beginning with
a sign ('+' 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.
Ratio
literals consist of two
integer literals separated
by a slash
character ('/').
The second number, the denominator, must be positive.
Ratios are
automatically reduced to their cannonical form; if they are
integral, then they are reduced to an integer.
Flonum (floating point) literals consist of a sequence
of digits optionally
beginning with a sign ('+' or '-') and including one
or both of an embedded
decimal point or
a trailing exponent. The optional exponent is denoted by
an 'E' or
'e' followed by an optional sign and one or more digits. The
XLISP 2.1g LEXICAL CONVENTIONS Page 10
range of values
a floating point number can
represent is limited by the
size of a C 'double' on most machines on which XLISP
is running.
Numeric literals cannot have embedded escape characters. If they do, they
are treated as symbols. Thus '12\3' is a symbol even
though it would appear
to be identical to '123'.
Complex literals are
constructed using a read-macro of the format #C(r i),
where r is the
real part and i is the imaginary part. The numeric fields
can be any
valid fixnum, ratio, or flonum literal.
If either field has a
ratio or flonum literal, then both values are
converted to flonums. Fixnum
complex
literals with a zero imaginary
part are automatically reduced to
fixnums.
Character literals are handled via the #\ read-macro
construct:
#\<char> == the ASCII code of the printing
character
#\newline == ASCII linefeed character
#\space == ASCII space character
#\rubout == ASCII rubout
(DEL)
#\C-<char> == ASCII control character
#\M-<char> == ASCII
character with msb set (Meta character)
#\M-C-<char> == ASCII
control character with msb set
Literal strings
are sequences of characters surrounded by double quotes
(the "
read-macro). Within quoted strings the '\'
character is used to
allow non-printable characters to be included. The
codes
recognized are:
\\ means the character '\'
\n means newline
\t means tab
\r means return
\f means form feed
\nnn means the character whose octal code is
nnn
XLISP 2.1g 8 BIT ASCII CHARACTERS Page 11
8 BIT ASCII CHARACTERS
When used
in an IBM PC environment (or
perhaps others), XLISP-PLUS is
compiled by
default to allow the full use of the IBM 8 bit ASCII character
set, including
all characters with diacritic marks. Note that using such
characters will make
programs non-portable. XLISP-PLUS can be compiled for
standard 7 bit ASCII if desired for portability.
When 8 bit ASCII is enabled, the following system
characteristics change:
Character
codes 128 to 254 are marked as :constituent in the readtable.
This means
that any of the new characters (except for
the nonprinting
character
255) can be symbol
constituent. Alphabetic
characters which
appear in both cases, such as Ç and ê, are
considered to be alphabetical
for purposes
of symbol case control, while
characters such as † that have
no coresponding upper case are not considered to be
alphabetical.
The
reader is extended for
the character data type to
allow all the
additional
characters (except code 255)
to be entered literally, for
instance "#\Ç". These characters are also
printed literally, rather than
using the
"M-" construct. Code 255 must
still be entered as, and will be
printed as, "#\M-Rubout".
Likewise strings
do not need and will not
use the backslash
escape
mechanism for codes 128 to 254.
The functions alphanumericp, alpha-char-p, upper-case-p, and
lower-case-p
perform
as would be expected on
the extended characters, treating the
diacritic characters
as their unadorned
counterparts. As per the Common
Lisp definition, both-case-p will only indicate T for characters available
in both cases.
XLISP 2.1g READTABLES Page 12
READTABLES
The behaviour
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 -- if
it is changed
then the section LEXICAL
CONVENTIONS may not apply. The
readtable is an array with 256 entries, one for each
of the extended ASCII
character codes. Each entry contains one of the following values, with the
initial entries assigned to the values indicated:
:white-space A whitespace character - tab, cr, lf,
ff, space
(:tmacro .
fun) terminating readmacro - ( )
" , ; ' `
(:nmacro .
fun) non-terminating readmacro - #
:sescape Single escape character - \
:mescape Multiple escape character - |
:constituent
Indicating a symbol
constituent (all printing
characters not listed above)
NIL Indicating an invalid
character (everything else)
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 takes 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 occurance of the
specified value. Of course, the
readmacro code is free to read additional characters
from the input stream.
A :nmacro
is a symbol constituent except
as the first character of a
symbol.
As an example,
the following read macro allows the
square brackets to be
used as a more visibly appealing alternative to the
SEND function:
(setf (aref *readtable* (char-int #\[)) ; #\[ table
entry
(cons
:tmacro
(lambda (f c &aux ex) ; second arg is not used
(do ()
((eq (peek-char t f)
#\]))
(setf ex (append ex (list (read f)))))
(read-char f) ; toss the trailing #\]
(cons (cons 'send ex) NIL))))
(setf (aref *readtable* (char-int #\]))
(cons
:tmacro
(lambda (f c)
(error "misplaced right bracket"))))
XLISP 2.1g READTABLES Page 13
XLISP defines several useful read macros:
'<expr> == (quote <expr>)
`<expr> == (backquote <expr>)
,<expr> == (comma <expr>)
,@<expr> ==
(comma-at <expr>)
#'<expr> == (function <expr>)
#(<expr>...) == an array of the specified
expressions
#S(<structtype>
[<slotname> <value>]...)
== structure of specified type and initial
values
#.<expr> == result of evaluating
<expr>
#x<hdigits> == a hexadecimal number (0-9,A-F)
#o<odigits> == an
octal number (0-7)
#b<bdigits> == a binary number (0-1)
#| |# == a comment
#:<symbol> == an
uninterned symbol
#C(r
i) == a complex number
#+<expr> ==
conditional on feature expression true
#-<expr> == conditional on feature
expression false
A feature expression
is either a symbol or a list
where the first element
is AND, OR, or
NOT and any remaining elements
(NOT requires exactly one)
are feature
expressions. A symbol is
true if it is a member
(by test
function EQ)
of the list in global variable *FEATURES*. Init.lsp defines
one initial feature,
:XLISP, and the features :TIMES,
:GENERIC, :POSFCNS
(various position
functions), :MATH (complex math),
:PC8 (character set),
:PACKAGES, and :MULVALS depending on the coresponding feature having been
compiled into the XLISP executable. Utility files
supplied with XLISP-PLUS
generally add new features which are EQ to the keyword
made from their file
names.
XLISP 2.1g SYMBOL CASE CONTROL Page 14
SYMBOL CASE CONTROL
XLISP-PLUS
uses two variables,
*READTABLE-CASE* and *PRINT-CASE* to
deturmine
case conversion during
reading and printing
of symbols.
*READTABLE-CASE*
can have the
values :UPCASE :DOWNCASE
:PRESERVE or
:INVERT, while
*PRINT-CASE* can have the
values :UPCASE :DOWNCASE
or
:CAPITALIZE. By default, or when other values have
been specified, both are
:UPCASE.
When *READTABLE-CASE*
is :UPCASE, all unescaped
lowercase characters are
converted
to uppercase when read. When
it is :DOWNCASE, all unescaped
uppercase
characters are converted to lowercase. This mode is not very
useful because
the predefined symbols are all
uppercase and would need to
be escaped to
read them. When *READTABLE-CASE* is :PRESERVE, no conversion
takes place.
This allows case sensitive input with predefined functions in
uppercase. The final
choice, :INVERT, will invert the
case of any symbol
that is not mixed case. This provides case sensitive
input while making the
predefined functions and variables appear to be in
lowercase.
The printing
of symbols involves the settings of both *READTABLE-CASE* and
*PRINT-CASE*. When
*READTABLE-CASE* is :UPCASE,
lowercase characters are
escaped (unless PRINC is used), and uppercase characters
are printed in the
case
specified by *PRINT-CASE*. When
*READTABLE-CASE* is :DOWNCASE,
uppercase
characters are escaped (unless PRINC is used), and lowercase are
printed in the
case specified by *PRINT-CASE*. The *PRINT-CASE* value of
:CAPITALIZE means that the first character of the
symbol, and any character
in the symbol
immediately following a non-alphabetical character are to be
in uppercase,
while all other alphabetical characters
are to be in
lowercase. The remaining *READTABLE-CASE* modes ignore *PRINT-CASE* and do
not
escape alphabetic
characters. :PRESERVE never changes the case of
characters while :INVERT inverts the case of any non
mixed-case symbols.
There are five major useful combinations of these
modes:
A:
*READTABLE-CASE* :UPCASE
*PRINT-CASE* :UPCASE
"Traditional" mode. Case insensitive input; must escape to put lowercase
characters in symbol names. Symbols print exactly as
they are stored, with
lowercase characters escaped when PRIN1 is used.
B:
*READTABLE-CASE* :UPCASE
*PRINT-CASE* :DOWNCASE
"Eyesaver"
mode. Case insensitive input; must
escape to put lowercase
characters in
symbol name. Symbols print
entirely in lowercase except
symbols escaped when lowercase characters present with
PRIN1.
C:
*READTABLE-CASE* :PRESERVE
"Oldfashioned
case sensitive" mode.
Case sensitive input.
Predefined
symbols must
be typed in uppercase. No alpha quoting needed. Symbols print
exactly as stored.
XLISP 2.1g SYMBOL CASE CONTROL Page 15
D:
*READTABLE-CASE* :INVERT
"Modern case sensitive" mode. Case sensitive
input. Predefined symbols must
be typed in
lowercase. Alpha quoting should be avoided. Predefined symbols
print in lower case, other symbols print as they were
entered.
E: *READTABLE-CASE* :UPCASE *PRINT-CASE* :CAPITALIZE
Like case B, except symbol names print capitalized.
As far as compatibility between these modes are
concerned, data printed in
mode A can be read in A, B, C, or E. Data printed in mode B can be read in
A, B, D, or
E. Data printed in mode C can be
read in mode C, and if no
lowercase symbols in
modes A, B and E as well. Data
printed in mode D can
be read in mode D, and if no (internally) lowercase
symbols in modes A, B,
and E as well. Data printed in mode E can be read in modes A, B, and E. In
addition, symbols
containing characters requiring
quoting are compatible
among all modes.
XLISP 2.1g PACKAGES Page 16
PACKAGES
When compiled in, XLISP-PLUS provides the "Packages" name hiding facility
of Common
Lisp. When in use,
there are multiple object
arrays (name
spaces). Each package
has internal and external symbols.
Internal symbols
can only normally be accessed while in that package,
while external symbols
can be
imported into the current
package and used as though they
are
members of the current package. There are three standard packages, XLISP,
KEYWORD, and USER. In addition, some of the utility
programs are in package
TOOLS.
Normally one is in package
USER, which is initally empty. USER
imports all external symbols from XLISP, which contains all
the functions
and variables described in the body of this document. Symbols
which are not
imported into the current package, but are declared to
be external in their
home package, can be referenced with the syntax
"packageName:symbolName" to
identify symbol s_y_m_b_o_l_N_a_m_e_ in package p_a_c_k_a_g_e_N_a_m_e_.
Those symbols which are
internal in
their home package need the
slightly more difficult syntax
"packageName::symbolName".
The KEYWORD
package is referenced by a
symbol name with a leading colon.
All keywords are
in this package. All
keywords are automatically marked
external, and are interned as constants with
themselves as their values.
To build an application in a package (to avoid name
clashes, for instance),
use
MAKE-PACKAGE to create a
new package (only if the
package does not
already exist,
use FIND-PACKAGE to test
first), and then preceed
the
application with the IN-PACKAGE command to set
the package. Use the EXPORT
function to
indicate the symbols that will
be accessable from outside the
package.
To use an application in a package, either use
IMPORT to make specific
symbols
accessable as local internal symbols, use USE-PACKAGE to make them
all accessable, or explicitly reference the symbols
with the colon syntax.
For the
subtleties of the package facility, read Common Lisp the Language,
second edition.
XLISP 2.1g LAMBDA LISTS Page 17
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. 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'.
If identical
keywords occur, those after the
first are ignored. Extra
keywords will signal
an error unless &allow-other-keys is present, in which
case the extra
keywords are ignored. Also, if the keyword :allow-other-keys
is used in
the function/macro call,
and has a
non-nil value, then
additional keys will
be ignored.
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.
XLISP 2.1g LAMBDA LISTS Page 18
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 (starts with ':')
<aux> is an auxiliary variable symbol
<init> is an initialization expression
<svar> is a supplied-p variable symbol
XLISP 2.1g OBJECTS Page 19
OBJECTS
Definitions:
˘ selector - a symbol used to select an
appropriate method
˘ message - a selector and a list of actual
arguments
˘ method - the code that implements a
message
Since XLISP was created to provide a simple basis for experimenting with
object-oriented
programming, one of the primitive data types included is
'object'. In XLISP, an object consists of a data
structure containing a
pointer to the
object's class as well as an array containing the values of
the object's instance
variables.
Officially, there is no way to see inside an object (look at the
values of
its instance
variables). The only way to communicate
with an object is by
sending it a message.
You can send
a message to an
object using the 'send' function. This
function takes
the object as its first argument, the message selector as
its second argument (which must be a symbol) and the message arguments as
its remaining
arguments.
The 'send' function determines the class of
the receiving object and
attempts to find a
method corresponding to the message
selector in the set
of messages defined for that class. If the message is not found in the
object's class
and the class has a super-class, the search continues by
looking at the
messages defined for the super-class. This process continues
from one super-class
to the next until a method for the message is found.
If no method is found,
an error occurs.
To perform a method lookup starting with the
method's superclass rather
than the
object's class, use the function
'send-super'. This allows a
subclass to invoke a standard method in its parent
class even though it
overrides that method
with its own specialized version.
When a method is found, the evaluator binds the
receiving object to the
symbol 'self' and
evaluates the method using the remaining elements of the
original list as
arguments to the method.
These arguments are always
evaluated prior to
being bound to their corresponding formal arguments. The
result of evaluating
the method becomes the result of the expression.
Two objects, both classes, are predefined: Object and Class. Both Object
and Class are of class Class. The superclass of
Class is Object, while
Object has no
superclass. Typical use is to create new
classes (by sending
:new to Class) to represent application objects.
Objects of these classes,
created by sending :new to the appropriate new
class, are subclasses of
Object. The Object method :show can be used
to view the contents of any
object.
XLISP 2.1g OBJECTS Page 20
THE 'Object' CLASS
Object THE TOP OF THE CLASS HEIRARCHY
Messages:
:show SHOW AN OBJECT'S INSTANCE VARIABLES
returns the object
:class RETURN THE CLASS OF AN OBJECT
returns the class of the object
:prin1 [<stream>] PRINT THE
OBJECT
<stream> T
is *terminal-io*, NIL
does not print
(for
FLATSIZE
calculation), and default is *standard-
output*
returns the object
:isnew THE DEFAULT OBJECT INITIALIZATION ROUTINE
returns the object
:superclass GET THE SUPERCLASS OF THE OBJECT
returns NIL
(Defined in classes.lsp, see
:superclass below)
:ismemberof <class> CLASS MEMBERSHIP
<class> class name
returns T if object member of class, else NIL
(defined in classes.lsp)
:iskindof <class> CLASS
MEMBERSHIP
<class> class name
returns T
if object member of class or subclass of class,
else NIL
(defined in classes.lsp)
:respondsto <sel> SELECTOR
KNOWLEDGE
<sel> message selector
returns T if
object responds to message selector, else
NIL.
(defined in classes.lsp)
:storeon READ REPRESENTATION
returns a list, that when executed will create
a copy of
the object. Only works for members of
classes
created with
defclass.
(defined in classes.lsp)
XLISP 2.1g OBJECTS Page 21
THE 'Class' CLASS
Class THE 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 symbol
<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
:superclass GET THE SUPERCLASS OF THE OBJECT
returns the superclass (of the class)
(defined in classes.lsp)
:messages GET THE LIST OF MESSAGES OF THE CLASS
returns association list of message selectors and
closures
for messages.
(defined in classes.lsp)
:storeon READ REPRESENTATION
returns a
list, that when executed
will re-create the
class and its
methods.
(defined in classes.lsp)
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.
Therefore, when a new
class is created by sending ':new'
to class 'Class'
the message ':isnew'
is sent to Class automatically. To create a new class,
a function of the
following format is used:
(setq <newclassname> (send Class
:new <ivars> [<cvars> [<super>]]))
When a new
class is created, 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, and methods
from its super-class. Only class variables of a
method's class are
accessable.
XLISP 2.1g OBJECTS Page 22
INSTANCE VARIABLES OF
CLASS 'CLASS':
MESSAGES
- An association list of
message names and
closures
implementing the messages.
IVARS - List of names of instance
variables.
CVARS - List of names of class variables.
CVAL - Array of class variable values.
SUPERCLASS - The superclass of this
class or NIL if no superclass
(only for class OBJECT).
IVARCNT - instance variables in this
class (length of IVARS)
IVARTOTAL - total instance
variables for this
class and all
superclasses of this class.
PNAME - printname string for this class.
XLISP 2.1g SYMBOLS Page 23
SYMBOLS
All values are initially NIL unless otherwise specified. All are special
variables unless
indicated to be constants.
˘ NIL -
represents empty list and the
boolean value for "false". The
value of NIL is NIL, and cannot be changed
(it is a constant). (car
NIL) and (cdr NIL) are also defined to be
NIL.
˘ t - boolean value "true" is
constant with value t.
˘ self -
within a method context,
the current object (see page
19),
otherwise initially unbound.
˘ object - constant, value is the class
'Object.'
˘ class - constant, value is the class
'Class'.
˘ internal-time-units-per-second - integer constant to divide returned
times by to get time in seconds.
˘ pi - floating point aproximation of pi
(constant defined when math
extension is compiled).
˘ *obarray* - the object hash table. Length
of array is a compilation
option. Objects are hashed using the hash
function and are placed on a
list in the appropriate array slot. This
variable does note exist when
the package feature is compiled in.
˘ *package*
- the current package. Do
not alter. Part of the package
feature.
˘ *terminal-io* - stream bound to keyboard
and display. Do not alter.
˘ *standard-input* - the standard input stream, initially stdin. If
stdin is not redirected on the command
line, then *terminal-io* is
used so that all interactive i/o uses the
same stream.
˘ *standard-output* - the standard output stream, initially stdout. If
stdout is not redirected on the command
line then *terminal-io* is
used so that all interactive i/o uses the
same stream.
˘ *error-output* - the error output stream
(used by all error messages),
initially same as *terminal-io*.
˘ *trace-output* - the trace output stream
(used by the trace function),
initially same as *terminal-io*.
˘ *debug-io* - the break
loop i/o stream,
initially same as
*terminal-io*. System messages (other than error messages) also print
out on this stream.
˘ *breakenable* - flag controlling entering
break loop on errors (see
page 4)
˘ *tracelist* - list of names of
functions to trace, as set by trace
function.
˘ *tracenable* - enable trace back printout
on errors (see page 4).
˘ *tracelimit* - number of levels of
trace back information (see page
4).
˘ *evalhook* - user substitute for the evaluator function (see page 8,
and evalhook and applyhook functions).
˘ *applyhook* - user substitute for
function application (see page
8,
and evalhook and applyhook functions).
˘ *readtable* - the current readtable (see
page 12).
˘ *gc-flag*
- controls the printing of gc
messages. When non-NIL, a
message
is printed after each garbage collection giving the total
number of nodes and the number of nodes
free.
˘ *gc-hook* - function to call after garbage
collection (see page 8).
XLISP 2.1g SYMBOLS Page 24
˘ *integer-format* - format for printing integers (when not bound to a
string, defaults to "%d" or
"%ld" depending on implementation)
˘ *ratio-format* - format for printing ratios (when not bound to a
string, defaults to "%d/%d" or
"%ld/%ld" depending on implementation)
˘ *float-format* - format for printing floats (when not bound to a
string, defaults to "%g")
˘ *readtable-case* - symbol read and output
case. See page 14
for
details
˘ *print-case* - symbol output case when
printing. See page 14 for
details
˘ *print-level* - When bound to a number,
list levels beyond this value
are printed as '#'. Used by all printing
functions. Good precaution to
avoid getting caught in circular lists.
˘ *print-length* - When bound to a number, lists longer than this value
are
printed as '...'. Used by all printing functions. Good precaution
to avoid getting caught in circular
lists.
˘ *dos-input* - When not NIL, uses dos line
input function for read (see
page 3).
˘ *displace-macros* -
When not NIL,
macros are replaced
by their
expansions when exectuted (see page 7).
˘ *random-state* - the default random-state
used by the random function.
˘ *features* - list of features, initially
(:xlisp), used for #+ and #-
reader macros.
˘ *startup-functions* - list of functions to be executed when
workspace
started
˘ *command-line* - the xlisp command
line, in the form of a
list of
strings, one string per argument.
˘ *load-file-arguments* - When not NIL, file arguements are loaded at
startup.
˘ *top-level-loop* - Top level loop to utilize, defaults to TOP-LEVEL-
LOOP. Note that this function can only be restarted by executing TOP-
LEVEL, and it never exits.
˘ *read-suppress* - When not
NIL, inhibits certain parts of reading.
Used by the #+ and #- macroes.
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.
XLISP 2.1g EVALUATION FUNCTIONS Page 25
EVALUATION FUNCTIONS
(eval
<expr>)
EVALUATE AN XLISP EXPRESSION
<expr> the expression to be evaluated
returns
the result of evaluating the expression
(apply <fun>
<arg>...<args>) APPLY
A FUNCTION TO A LIST OF ARGUMENTS
<fun> the function to apply (or function symbol). May not be macro
or fsubr.
<arg> initial arguments, which are CONSed to...
<args> the argument list
returns
the result of applying the function to the arguments
(funcall <fun>
<arg>...) CALL
A FUNCTION WITH ARGUMENTS
<fun> the function to call
(or function symbol). May not be macro
or fsubr.
<arg> arguments to pass to the function
returns
the result of calling the function with the arguments
(quote
<expr>)
RETURN AN EXPRESSION UNEVALUATED
fsubr
<expr> the expression to be quoted (quoted)
returns
<expr> unevaluated
(function
<expr>)
GET THE FUNCTIONAL INTERPRETATION
fsubr
<expr> the symbol or lambda expression (quoted)
returns
the functional interpretation
(complement
<fun>)
MAKE A COMPLEMENTARY FUNCTION
This
function is intended to eliminate the need for -IF-NOT functions
and :TEST-NOT keys by providing a way to
make complementary functions.
<fun> the function or closure (not macro or fsubr)
returns
a new function closure that returns NOT of the result of the
original function.
(identity
<expr>) RETURN THE
EXPRESSION
<expr> the expression
returns
the expression
(backquote
<expr>) FILL IN A TEMPLATE
fsubr. Note: an improved backquote
facility, which works properly when
nested, is available by loading the file
backquot.lsp.
<expr> the template (quoted)
returns
a copy of the template with
comma and comma-at expressions
expanded.
(comma
<expr>)
COMMA EXPRESSION
(Never
executed) As the
object of a
backquote expansion, the
expression is evaluated and becomes an
object in the enclosing list.
XLISP 2.1g EVALUATION FUNCTIONS Page 26
(comma-at
<expr>) COMMA-AT EXPRESSION
(Never
executed) As the
object of a
backquote expansion, the
expression is evaluated (and must
evaluate to a list) and is then
spliced into the enclosing list.
(lambda <args>
<expr>...)
MAKE A FUNCTION CLOSURE
fsubr
<args> formal argument list (lambda list) (quoted)
<expr> expressions of the function body (quoted)
returns
the function closure
(get-lambda-expression
<closure>) GET THE
LAMBDA EXPRESSION
<closure> the closure
returns
the original lambda expression,
or NIL if not a closure.
Second return value
is T if closure has
a non-global
environment, and the third return value is the name of the
closure.
(macroexpand
<form>)
RECURSIVELY EXPAND MACRO CALLS
<form> the form to expand
returns
the macro expansion
(macroexpand-1
<form>)
EXPAND A MACRO CALL
<form> the macro call form
returns
the macro expansion
XLISP 2.1g MULTIPLE VALUE FUNCTIONS Page 27
MULTIPLE VALUE
FUNCTIONS
XLISP-PLUS supports
multiple return values (via a compilation option) as in
Common Lisp. Note that most
FSUBR control structure
functions will pass
back multiple return
values, with the exceptions being PROG1 and PROG2.
(multiple-value-bind
<varlist> <vform> [<form>...])
BIND
RETURN VALUES INTO LOCAL CONTEXT
defined as macro in common.lsp
<vform> form to be evaluated
<varlist> list of variables to bind
to return values of vform
<form> forms evaluated sequentially, as in LET,
using local
bindings
returns
values of last form evaluated, or NIL if no forms
(multiple-value-call
<fun> <form> ...) COLLECT
VALUES AND APPLY FUNCTION
fsubr
<fun> function to apply
<form> forms, which are evaluated, with result values collected
returns
result of applying fun to all of
the returned values of the
forms
(multiple-value-list
<form>) COLLECT MULTIPLE
RETURNED VALUES INTO A LIST
defined as macro in common.lsp
<form> form to be evaluated
returns
list of returned values
(multiple-value-prog1
<form> [<form> ...])
RETURN VALUES OF FIRST FORM
fsubr
<form> one or more forms, which are evaluated sequentially
returns
the result values of the first form
(multiple-value-setq
<varlist> <form>) BIND
RETURN VALUES TO VARIABLES
defined as macro in common.lsp
<form> form to be evaluated
<varlist> list of variables to bind
to return values of form
returns
(undefined, implementation dependent)
(nth-value
<index> <form>) EXTRACT A RETURN VALUE
fsubr
<index> index into return values
<form> form which gets evaluated
returns
the nth result value of exectuing the form
(values
[<expr>]) RETURN MULTIPLE VALUES
<expr> expression(s) to be evaluated
returns
each argument as a separate value
(values-list
<list>)
RETURN MULTIPLE VALUES FROM LIST
defined in common.lsp
<list> a list
returns
each list element as a separate value
XLISP 2.1g SYMBOL FUNCTIONS Page 28
SYMBOL FUNCTIONS
(set <sym>
<expr>)
SET THE GLOBAL VALUE OF A SYMBOL
<sym> the symbol being set
<expr> the new value
returns
the new value
(setq [<sym>
<expr>]...)
SET THE VALUE OF A SYMBOL
fsubr
<sym> the symbol being set (quoted)
<expr> the new value
returns
the last new value or NIL if no arguments
(psetq [<sym>
<expr>]...)
PARALLEL VERSION OF SETQ
fsubr. All expressions are evaluated before
any assignments are
made.
<sym> the symbol being set (quoted)
<expr> the new value
returns
NIL
(setf [<place>
<expr>]...)
SET THE VALUE OF A FIELD
fsubr
<place> the field specifier (if a macro it is expanded, then the form
arguments are evaluated):
<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 or string
(elt <expr> <n>) set nth element of a sequence
(get <sym> <prop>
[<dflt>]) set value
of a symbol's
property
(getf <pl> <prop>
[<dflt>]) set value of a property. <pl>
must be a
valid field
specifier.
(symbol-value <sym>) set global value of a symbol
(symbol-function
<sym>) set functional
value of a
symbol
(symbol-plist <sym>) set property list of a symbol
(gethash <key> <tbl> <def>) add
or replace hash
table
entry. <def> is ignored
(send <obj>
:<ivar>) (When classes.lsp
used), set instance
variable of
object.
(<sym>-<element>
<struct>) set the element
of structure
struct, type sym.
(<fieldsym>
<args>) the function stored in property
*setf*
in symbol
<fieldsym> is applied
to
(<args> <expr>). As an
alternative, the
function stored in
property
*setf-lambda* is applied,
then the
result is
evaled in the current context.
<expr> the new value
returns the last new value, or NIL if no
arguments
XLISP 2.1g SYMBOL FUNCTIONS Page 29
(psetf [<place>
<expr>]...) PARALLEL VERSION OF SETF
fsubr. All expressions are evaluated
and macro place forms expanded
before any assignments are made.
<place> the field specifier (see SETF, above)
<expr> the new value
returns
NIL
(defsetf <sym>
<fcn>)
DEFINE A SETF FIELD SPECIFIER
(defsetf <sym>
<fargs> (<value>) <expr>...)
Defined
as macro in common.lsp. Convenient, Common Lisp compatible
alternative to setting *setf* or
*setf-lambda* property directly.
<sym> field specifier symbol (quoted)
<fcn> function to use
(quoted symbol) which
takes the same
arguments as the field
specifier plus an additional argument
for the value. The value must
be returned.
<fargs> formal argument list of unevaluated arguments (lambda list)
(quoted)
<value> symbol bound to value to store (quoted).
<expr> The last expression
must an expression to evaluate
in the
setf context.In
this respect, defsetf works like
a macro
definition.
returns
the field specifier symbol
(push <expr> <place>) CONS TO
A FIELD
Defined as macro in common.lsp. Only evaluates place form arguments
one time. It is recommended that
*displace-macros* be non-NIL for best
performance.
<place> field specifier being modified (see setf)
<expr> value to cons to field
returns
the new value which is (CONS <expr> <place>)
(pushnew <expr>
<place> &key :test :test-not :key) CONS NEW TO A FIELD
Defined
as macro in common.lsp. Only
evaluates place form arguments
one time. It is recommended that
*displace-macros* be non-NIL for best
performance.
<place> field specifier being modified (see setf)
<expr> value to cons to field, if not already MEMBER of field
:test
the test function (defaults to eql)
:test-not the test function (sense
inverted)
:key
function to apply to test
function list argument (defaults
to identity)
returns
the new value which is (CONS <expr> <place>) or
<place>
(pop
<place>)
REMOVE FIRST ELEMENT OF A FIELD
Defined
as macro in common.lsp. Only
evaluates place form arguments
one time. It is recommended that
*displace-macros* be non-NIL for best
performance.
<place> the field being modified (see setf)
returns
(CAR <place>), field changed to (CDR <place>)
XLISP 2.1g SYMBOL FUNCTIONS Page 30
(incf <place>
[<value>]) INCREMENT A FIELD
(decf <place>
[<value>]) DECREMENT A FIELD
Defined as macro in common.lsp. Only
evaluates place form arguments
one time. It is recommended that
*displace-macros* be non-NIL for best
performance.
<place> field specifier being modified (see setf)
<value> Numeric value (default 1)
returns
the new value which is (+ <place> <value>) or (-
<place>
<value>)
(defun <sym>
<fargs> <expr>...) DEFINE A FUNCTION
(defmacro <sym>
<fargs> <expr>...) DEFINE A MACRO
fsubr
<sym> symbol being defined (quoted)
<fargs> formal argument list (lambda list) (quoted)
<expr> expressions constituting the body of the function (quoted)
returns
the function symbol
(gensym
[<tag>]) GENERATE A
SYMBOL
<tag> string or number
returns
the new symbol, uninterned
(intern <pname>
[<package>])
MAKE AN INTERNED SYMBOL
<pname> the symbol's print name string
<package> the package (defaults to
current package)
returns
the new symbol. A second value
is returned which is NIL if
the symbol did not pre-exist,
:internal if it is an internal
symbol, :external if it is an
external symbol, or :inherited
if it inherited via
USE-PACKAGE.
(make-symbol
<pname>)
MAKE AN UNINTERNED SYMBOL
<pname> the symbol's print name string
returns
the new symbol
(symbol-name
<sym>)
GET THE PRINT NAME OF A SYMBOL
<sym> the symbol
returns
the symbol's print name
(symbol-value
<sym>)
GET THE VALUE OF A SYMBOL
<sym> the symbol
returns
the symbol's value
(symbol-function
<sym>) GET THE
FUNCTIONAL VALUE OF A SYMBOL
<sym> the symbol
returns
the symbol's functional value
(symbol-plist
<sym>) GET
THE PROPERTY LIST OF A SYMBOL
<sym> the symbol
returns
the symbol's property list
(hash <expr>
<n>)
COMPUTE THE HASH INDEX
<expr> the object to hash
<n> the table size (positive integer)
returns
the hash index (integer 0 to n-1)
XLISP 2.1g SYMBOL FUNCTIONS Page 31
(makunbound
<sym>)
MAKE A SYMBOL VALUE BE UNBOUND
You cannot unbind constants.
<sym> the symbol
returns
the symbol
(fmakunbound
<sym>) MAKE
A SYMBOL FUNCTION BE UNBOUND
<sym> the symbol
returns
the symbol
(unintern <sym>
[<package>])
UNINTERN A SYMBOL
Defined in common.lsp if package feature
not compiled.
<sym> the symbol
<package> the package to look in
for the symbol
returns
t if successful, NIL if symbol not interned
(defconstant
<sym> <val> [<comment>]) DEFINE A CONSTANT
fsubr.
<sym> the symbol
<val> the value
<comment> optional comment string
(ignored)
returns
the value
(defparameter
<sym> <val> [<comment>]) DEFINE A PARAMETER
fsubr.
<sym> the symbol
<val> the value
<comment> optional comment string
(ignored)
returns
the value
(defvar <sym>
[<val> [<comment>]]) DEFINE A VARIABLE
fsubr. Variable only initialized if not
previously defined.
<sym> the symbol
<val> the initial value, or NIL if absent.
<comment> optional comment string
(ignored)
returns
the current value
(mark-as-special
<sym> [<flag>]) SET SPECIAL ATTRIBUTE
Also see definition of PROCLAIM and
DECLARE.
<sym> symbol to mark
<flag> non-nil to make into a constant
returns
nil, with symbol
marked as special
and possibly as a
constant.
(declare
[<declaration> ...])
DECLARE ARGUMENT ATTRIBUTES
Macro
in common.lsp provided
to assist in
porting Common Lisp
applications to XLISP-PLUS.
<declaration> list of local variable and attributes
returns
nil, produces an error message if attribute SPECIAL is used.
(proclaim
<proc>)
PROCLAIM GLOBAL SYMBOL ATTRIBUTES
Function in common.lsp provided
to assist in porting Common Lisp
applications to XLISP-PLUS.
<proc> a list of symbols. If
the CAR of the list is SPECIAL, then
the remaining symbols are
marked as special variables.
XLISP 2.1g PACKAGE FUNCTIONS Page 32
PACKAGE FUNCTIONS
These functions
are defined when the packages
option is compiled. The
<package>
argument can be either a string,
symbol, or package object. The
default when
no package is given is the
current package (as bound to
*package*), unless otherwise specified in the
definition. The <symbols>
argument may be either a single symbol or a list
of symbols. In case of
name conflicts, a
correctable error occurs.
(apropos
<string> [<package>]) SEARCH SYMBOLS FOR NAME MATCH
(apropos-list
<string> [<package>])
Functions in common.lsp.
<string> find symbols which contain this string as substring of print
name
<package> package to search, if
absent, or NIL, search all packages
returns
apropos-list returns list of
symbols, apropos prints them,
along with some information,
and returns nothing.
(defpackage
<package> [<option>...]) (RE)DEFINE A PACKAGE
Macro in common.lsp. Use to define a
package, or redefine a package.
<package> the name of the package
to (re)define
<option> any one or more of the following, none evaluated, applied in
this order:
(:shadow <symbol>...)
one or more symbols to shadow,
as in function SHADOW
(:shadowing-import-from
<symbol>...)
one or more symbols
to shadow, as
in function
SHADOWING-IMPORT
(:use <package>...)
one or more packages to
"use", as in function USE-PACKAGE
(:import-from <package>
<symbol>...)
one or more symbols to import
from the package, as
in
function IMPORT
(:intern <symbol>...)
one or more symbols to
be located or
created in this
package, as in function INTERN
(:export <symbol>...)
one or more symbols to be
exported from this package, as in
function EXPORT
returns
the new or redefined package
(delete-package
<package>) DELETE A PACKAGE
Deletes
a package by uninterning all its
symbols and removing the
package.
<package> package to delete
returns
T if successful
XLISP 2.1g PACKAGE FUNCTIONS Page 33
(do-symbols
(<var> [<package> [<result>]]) <expr>...)) ITERATE OVER
SYMBOLS
(do-external-symbols
(<var> [<package> [<result>]]) <expr>...)
(do-all-symbols
(<var> [<result>]) <expr>...)
Implemented as macros in common.lsp. DO-SYMBOLS iterates over all
symbols in a single package,
DO-EXTERNAL-SYMBOLS iterates only over
the
external symbols, and DO-ALL-SYMBOLS iterates over all symbols in
all packages.
<var> variable to bind to symbol
<package> the package to search
<result> a single result form
<expr> expressions to evaluate (implicit tag-body)
returns
result of result form, or NIL if not specified
(export
<symbols> [<package>]) DECLARE EXTERNAL SYMBOLS
<symbols> symbols to declare as
external
<package> package symbol is in
returns
T
(find-all-symbols
<string>) FIND SYMBOLS
WITH SPECIFIED NAME
<string> string or symbol (if latter, print name string is used)
returns
list of all symbols having that print-name
(find-package
<package>) FIND
PACKAGE WITH SPECIFIED NAME
<package> package to find
returns
package with name or nickname <package>, or NIL if not found
(find-symbol
<string> [<package>]) LOOK UP A SYMBOL
<string> print name to search for
<package> package to search in
returns
two values, the first being the symbol, and the second being
:internal if
the symbol is
internal in the
package,
:external if
it is external, or :inherited
if it is
inherited via USE-PACKAGE. If
the symbol was not found, then
both return values are NIL.
(import
<symbols> [<package>]) IMPORT SYMBOLS INTO A PACKAGE
<symbols> symbols to import (fully
qualified names)
<package> package to import symbols
into
returns T
(in-package
<package>) SET CURRENT PACKAGE
FSUBR which sets the current package
until next call or end of current
LOAD.
<package> the package to enter
returns
the package
(list-all-packages) GET ALL
PACKAGE NAMES
returns
list of all currently existing packages
(make-package
<package> &key :nicknames :use) MAKE A NEW PACKAGE
<package> name of new package to
create
:nicknames list of package
nicknames
:use
list of packages to use (as in USE-PACKAGE)
returns
the new package
XLISP 2.1g PACKAGE FUNCTIONS Page 34
(package-name
<package>)
GET PACKAGE NAME STRING
<package> package name
returns
package name string
(package-nicknames
<package>) GET
PACKAGE NICKNAME STRINGS
<package> package name
returns
list of package nickname strings
(package-obarray
<package> [<external>]) GET AN OBARRAY
<package> package to use
<external> non-nil for external obarray,
else internal
obarray (default)
returns
the obarray (array of lists of symbols in package)
(package-shadowing-symbols
<package>) GET LIST OF
SHADOWING SYMBOLS
<package> the package
returns
list of shadowing symbols in package
(package-use-list
<package>) GET
PACKAGES USED BY A PACKAGE
<package> the package
returns
list of packages used by this package (as in USE-PACKAGE)
(package-used-by-list
<package>) GET PACKAGES
THAT USE THIS PACKAGE
<package> the package
returns
list of packages that use this package (as in USE-PACKAGE)
(package-valid-p
<package>)
IS THIS A GOOD PACKAGE?
<package> object to check
returns
T if a valid package, else NIL
(rename-package
<package> <new> [<nick>]) RENAME A PACKAGE
<package> original package
<new> new package name (may be same as original name)
<nick> list of new package nicknames
returns
the new package
(shadow
<symbols> [<package>]) MAKE SHADOWING SYMBOLS
If a symbol is not already in the package, it is interned. The symbol
is placed in the shadowing symbols list
for the package.
<symbols> the symbol or symbols to
shadow
<package> package to put symbols in
returns
T
(shadowing-import
<symbols> [<package>])
IMPORT SYMBOLS AND SHADOW
If a
symbol exists in the package, it is first uninterned. The symbol
is imported, and then made shadowing.
<symbols> the symbol or symbols to
import and shadow
<package> package to put symbols in
returns
T
(symbol-package
<symbol>)
FIND THE PACKAGE OF A SYMBOL
<symbol> the symbol
returns
the home package of the symbol, or NIL if none
XLISP 2.1g PACKAGE FUNCTIONS Page 35
(unexport
<symbols> [<package>])
MAKE SYMBOLS INTERNAL TO PACKAGE
<symbols> symbol or symbols to make
internal
<package> package for symbols
returns
T
(unuse-package
<pkgs> [<package>])
REMOVE PACKAGES FROM USE LIST
<pkgs> A single package or list of packages
<package> Package in which
to un-use packages (default is
current
package)
returns
T
(use-package
<pkgs> [<package>]) ADD PACKAGES TO USE LIST
<pkgs> A single package or list of packages
<package> Package in which
to use packages in (default
is current
package)
returns
T
XLISP 2.1g PROPERTY LIST FUNCTIONS Page 36
PROPERTY LIST
FUNCTIONS
Note that property
names are not limited to symbols. All functions handle a
symbol's property lists
except for GETF and REMF
which work with any
property list.
(get <sym>
<prop> [<dflt>])
GET THE VALUE OF A SYMBOL'S PROPERTY
Use SETF with GET to add or change
properties.
<sym> the symbol
<prop> the property name
<dflt> value to return if property not found, default is NIL
returns
the property value or <dflt> if property doesn't exist.
(getf <place>
<prop> [<dflt>])
GET THE VALUE OF A PROPERTY
Use SETF with GETF to add or change properties. (NOTE--when used with
SETF,
<place> must be a
valid place form. It gets
executed twice,
contrary to Common Lisp standard.)
<place> where the property list is stored
<prop> the property name
<dflt> value to return if property not found, default is NIL
returns
the property value or <dflt> if property doesn't exist.
(putprop <sym>
<val> <prop>) PUT
A PROPERTY ONTO A PROPERTY LIST
Modern practice is to use (SETF
(GET...)...) rather than PUTPROP.
<sym> the symbol
<val> the property value
<prop> the property name
returns
the property value
(remf <place>
<prop>) DELETE A PROPERTY
Defined as a macro in COMMON.LSP
<place> where the property list is stored
<prop> the property name
returns
T if property existed, else NIL
(remprop <sym>
<prop>)
DELETE A SYMBOL'S PROPERTY
<sym> the symbol
<prop> the property name
returns
NIL
XLISP 2.1g HASH TABLE FUNCTIONS Page 37
HASH TABLE FUNCTIONS
A hash table is
implemented as an structure of type
hash-table. No general
accessing functions
are provided, and hash tables print out using the angle
bracket convention
(not readable by READ).
The first element is
the
comparison
function. The remaining elements contain association lists of
keys (that hash to the
same value) and their data.
(make-hash-table
&key :size :test)
MAKE A HASH TABLE
:size
size of hash table --
should be a prime number. Default is
31.
:test
comparison function. Defaults to eql.
returns
the hash table
(gethash <key>
<table> [<def>]) EXTRACT FROM HASH TABLE
See also gethash in SETF.
<key> hash key
<table> hash table
<def> value to return on no match (default is NIL)
returns
associated data, if found, or <def> if not found.
(remhash <key>
<table>)
DELETE FROM HASH TABLE
<key> hash key
<table> hash table
returns
T if deleted, NIL if not in table
(clrhash
<table>) CLEAR THE HASH TABLE
<table> hash table
returns
NIL, all entries cleared from table
(hash-table-count
<table>) NUMBER
OF ENTRIES IN HASH TABLE
<table> hash table
returns
integer number of entries in table
(maphash <fcn>
<table>) MAP
FUNCTION OVER TABLE ENTRIES
<fcn> the function or function name, a function of two arguments,
the first is bound to the key, and the second the value of
each table entry in turn.
<table> hash table
returns
NIL
XLISP 2.1g ARRAY FUNCTIONS Page 38
ARRAY FUNCTIONS
Note that sequence
functions also work on arrays.
(aref <array>
<n>) GET
THE NTH ELEMENT OF AN ARRAY
See setf for setting elements of arrays
<array> the array (or string)
<n> the array index (integer, zero based)
returns
the value of the array element
(make-array
<size> &key :initial-element :initial-contents) MAKE A NEW ARRAY
<size> the size of the new array (integer)
:initial-element
value to initialize all array
elements, default NIL
:initial-contents
sequence used to
initialize all array elements,
consecutive
sequence elements
are used for each
array element. The
length of the sequence must be the same as the size of the
array
returns
the new array
(vector
<expr>...)
MAKE AN INITIALIZED VECTOR
<expr> the vector elements
returns
the new vector
XLISP 2.1g SEQUENCE FUNCTIONS Page 39
SEQUENCE FUNCTIONS
These functions work
on sequences -- lists, arrays, or strings.
(concatenate
<type> <expr> ...) CONCATENATE SEQUENCES
If result type is string, sequences must
contain only characters.
<type> result type, one of CONS, LIST, ARRAY, or STRING
<expr> zero or more sequences to concatenate
returns
a sequence which is
the concatenation of the
arguement
sequences
(elt <expr>
<n>) GET
THE NTH ELEMENT OF A SEQUENCE
<expr> the sequence
<n> the index of element to return
returns
the element if the index is in bounds, otherwise error
(map <type>
<fcn> <expr> ...)
APPLY FUNCTION TO SUCCESSIVE ELEMENTS
(map-into
<target> <fcn> [<expr> ...])
<type> result type, one of CONS, LIST, ARRAY, STRING, or NIL
<target> destination sequence to modify
<fcn> the function or function name
<expr> a sequence for each argument of the function
returns
a new sequence of type
<type> for MAP, and <target> for
MAP-INTO.
(every <fcn>
<expr> ...) APPLY
FUNCTION TO ELEMENTS UNTIL FALSE
(notevery <fcn>
<expr> ...)
<fcn> the function or function name
<expr> a sequence for each argument of the function
returns
every returns last evaluated function result
notevery returns T if there is a NIL function result, else
NIL
(some <fcn>
<expr> ...) APPLY
FUNCTION TO ELEMENTS UNTIL TRUE
(notany <fcn>
<expr> ...)
<fcn> the function or function name
<expr> a sequence for each argument of the function
returns
some returns first non-NIL function result, or NIL
notany returns NIL
if there is a non-NIL
function result,
else T
(length
<expr>)
FIND THE LENGTH OF A SEQUENCE
Note that a circular list causes an error. To detect a circular list,
use LIST-LENGTH.
<expr> the list, vector or string
returns
the length of the list, vector or string
(reverse
<expr>) REVERSE A SEQUENCE
(nreverse
<expr>)
DESTRUCTIVELY REVERSE A SEQUENCE
<expr> the sequence to reverse
returns
a new sequence in the reverse order
XLISP 2.1g SEQUENCE FUNCTIONS Page 40
(subseq <seq>
<start> [<end>]) EXTRACT A SUBSEQUENCE
<seq> the sequence
<start> the starting position (zero origin)
<end> the ending position + 1 (defaults to end) or NIL for end of
sequence
returns
the sequence between <start> and <end>
(sort <seq>
<test> &key :key)
DESTRUCTIVELY SORT A SEQUENCE
<seq> the sequence to sort
<test> the comparison function
:key
function to apply to comparison function arguments (defaults
to identity)
returns
the sorted sequence
(search
<seq1> <seq2> &key :test :test-not :key :start1 :end1
:start2
:end2)
SEARCH FOR
SEQUENCE
<seq1> the sequence to search for
<seq2> the sequence to search in
:test the test
function (defaults to eql)
:test-not the test function (sense
inverted)
:key
function to apply to test function arguments (defaults to
identity)
:start1
starting index in <seq1>
:end1
index of end+1 in <seq1> or NIL for end of sequence
:start2
starting index in <seq2>
:end2
index of end+1 in <seq2> or NIL for end of sequence
returns
position of first match
(remove <expr>
<seq> &key :test :test-not :key :start :end)
REMOVE ELEMENTS FROM A SEQUENCE
<expr> the element to remove
<seq> the sequence
:test
the test function (defaults to eql)
:test-not the test function (sense
inverted)
:key
function to apply
to test function
sequence argument
(defaults to identity)
:start
starting index
:end
index of end+1, or NIL for (length <seq>)
returns
copy of sequence with matching expressions removed
(remove-if
<test> <seq> &key :key :start :end)
REMOVE ELEMENTS THAT PASS TEST
(remove-if-not
<test> <seq> &key :key :start :end)
REMOVE ELEMENTS THAT FAIL TEST
<test> the test predicate
<seq> the sequence
:key
function to apply to test
function argument (defaults to
identity)
:start
starting index
:end
index of end+1, or NIL for (length <seq>)
returns copy of sequence with
matching or non-matching elements
removed
XLISP 2.1g SEQUENCE FUNCTIONS Page 41
(count <expr>
<seq> &key :test :test-not :key :start :end)
COUNT
MATCHING ELEMENTS IN A SEQUENCE
<expr> element to count
<seq> the sequence
:test
the test function (defaults to eql)
:test-not the test function (sense
inverted)
:key
function to apply
to each <seq> argument
(defaults to
identity)
:start
starting index
:end
index of end+1, or NIL for (length <seq>)
returns
count of matching elements
(count-if <test>
<seq> &key :key :start :end)
COUNT ELEMENTS THAT PASS TEST
(count-if-not
<test> <seq> &key :key :start :end)
COUNT ELEMENTS THAT FAIL TEST
<test> the test predicate
<seq> the sequence
:key
function to apply to test
function argument (defaults to
identity)
:start
starting index
:end
index of end+1, or NIL for (length <seq>)
returns
count of matching/non-matching elements
(find <expr>
<seq> &key :test :test-not :key :start :end)
FIND FIRST
MATCHING ELEMENT IN SEQUENCE
<expr> element to search for
<seq> the sequence
:test
the test function (defaults to eql)
:test-not the test function (sense
inverted)
:key
function to apply
to each <seq> argument
(defaults to
identity)
:start
starting index
:end
index of end+1, or NIL for (length <seq>)
returns
first matching element of sequence, or NIL
(find-if <test>
<seq> &key :key :start :end)
FIND
FIRST ELEMENT THAT PASSES TEST
(find-if-not
<test> <seq> &key :key :start :end)
FIND
FIRST ELEMENT THAT FAILS TEST
<test> the test predicate
<seq> the sequence
:key
function to apply to test
function argument (defaults to
identity)
:start
starting index
:end
index of end+1, or NIL for (length <seq>)
returns
first element of sequence that passes/fails test, or NIL
XLISP 2.1g SEQUENCE FUNCTIONS Page 42
(position <expr>
<seq> &key :test :test-not :key :start :end)
FIND POSITION OF FIRST
MATCHING ELEMENT IN SEQUENCE
<expr> element to search for
<seq> the sequence
:test
the test function (defaults to eql)
:test-not the test function (sense
inverted)
:key
function to apply
to each <seq> argument
(defaults to
identity)
:start
starting index
:end
index of end+1, or NIL for (length <seq>)
returns
position of first matching element of sequence, or NIL
(position-if
<test> <seq> &key :key :start :end)
FIND POSITION OF FIRST ELEMENT THAT PASSES TEST
(position-if-not
<test> <seq> &key :key :start :end)
FIND POSITION OF
FIRST ELEMENT THAT FAILS TEST
<test> the test predicate
<seq> the sequence
:key
function to apply to test
function argument (defaults to
identity)
:start
starting index
:end
index of end+1, or NIL for (length <seq>)
returns
position of first element
of sequence that passes/fails
test, or NIL.
(delete <expr>
<seq> &key :key :test :test-not :start :end)
DELETE ELEMENTS FROM A SEQUENCE
<expr> the element to delete
<seq> the sequence
:test
the test function (defaults to eql)
:test-not the test function (sense
inverted)
:key
function to apply
to test function
sequence argument
(defaults to identity)
:start
starting index
:end
index of end+1, or NIL for (length <seq>)
returns
the sequence with the matching expressions deleted
(delete-if
<test> <seq> &key :key :start :end)
DELETE ELEMENTS THAT PASS TEST
(delete-if-not
<test> <seq> &key :key :start :end)
DELETE ELEMENTS THAT FAIL TEST
<test> the test predicate
<seq> the sequence
:key
function to apply to test
function argument (defaults to
identity)
:start
starting index
:end
index of end+1, or NIL for (length <seq>)
returns
the sequence with matching or non-matching elements deleted
XLISP 2.1g SEQUENCE FUNCTIONS Page 43
(reduce <fcn>
<seq> &key :initial-value :start :end)
REDUCE SEQUENCE TO SINGLE VALUE
<fcn> function (of two
arguments) to apply to result of
previous
function application (or first element) and each member of
sequence.
<seq> the sequence
:initial-value value to use as first
argument in first function
application rather
than using the first element of
the sequence.
:start
starting index
:end
index of end+1, or NIL for (length <seq>)
returns
if sequence is empty and there
is no initial value, returns
result of applying function to
zero arguements. If there is
a single element, returns the
element. Otherwise returns the
result of the last function
application.
(remove-duplicates
<seq> &key :test :test-not :key :start :end)
REMOVE DUPLICATES FROM SEQUENCE
<seq> the sequence
:test
comparison function (default eql)
:test-not comparison function (sense
inverted)
:key
function to apply to test function arguments (defaults to
identity)
:start
starting index
:end index of end+1,
or NIL for (length <seq>)
returns
copy of sequence with duplicates removed.
(fill <seq>
<expr> &key :start :end)
REPLACE ITEMS IN SEQUENCE
Defined in common.lsp
<seq> the sequence
<expr> new value to place in sequence
:start
starting index
:end
index of end+1, or NIL for (length <seq>)
returns
sequence with items replaced with new item
(replace <seq1>
<seq2> &key :start1 :end1 :start2 :end2)
REPLACE ITEMS IN SEQUENCE FROM SEQUENCE
Defined in common.lsp
<seq1> the sequence to modify
<seq2> sequence with new items
:start1
starting index in <seq1>
:end1
index of end+1 in <seq1> or NIL for end of sequence
:start2
starting index in <seq2>
:end2
index of end+1 in <seq2> or NIL for end of sequence
returns
first sequence with items replaced
XLISP 2.1g LIST FUNCTIONS Page 44
LIST FUNCTIONS
(car
<expr>)
RETURN THE CAR OF A LIST NODE
<expr> the list node
returns
the car of the list node
(cdr
<expr>)
RETURN THE CDR OF A LIST NODE
<expr> the list node
returns
the cdr of the list node
(cxxr
<expr>) ALL CxxR COMBINATIONS
(cxxxr
<expr>) ALL CxxxR COMBINATIONS
(cxxxxr
<expr>) ALL CxxxxR COMBINATIONS
(first
<expr>) A SYNONYM FOR CAR
(second
<expr>) A SYNONYM FOR CADR
(third
<expr>) A SYNONYM FOR CADDR
(fourth
<expr>) A SYNONYM FOR CADDDR
(rest
<expr>) A SYNONYM FOR CDR
(cons <expr1>
<expr2>)
CONSTRUCT A NEW LIST NODE
<expr1> the car of the new list node
<expr2> the cdr of the new list node
returns
the new list node
(acons <expr1>
<expr2> <alist>)
ADD TO FRONT OF ASSOC LIST
defined in common.lsp
<expr1> key of new association
<expr2> value of new association
<alist> association list
returns
new association list, which is
(cons (cons <expr1> <expr2>)
<expr3>))
(list
<expr>...) CREATE A LIST OF VALUES
(list* <expr>
... <list>)
<expr> expressions to be combined into a list
returns
the new list
(append
<expr>...) APPEND LISTS
<expr> lists whose elements are to be appended
returns
the new list
(list-length
<list>)
FIND THE LENGTH OF A LIST
<list> the list
returns
the length of the list or NIL if the list is circular
(last
<list>)
RETURN THE LAST LIST NODE OF A LIST
<list> the list
returns the last list
node in the list
(butlast <list>
[<n>]) RETURN
COPY OF ALL BUT LAST OF LIST
<list> the list
<n> count of elements to omit (default 1)
returns
copy of list with last element(s) absent.
XLISP 2.1g LIST FUNCTIONS Page 45
(nth <n>
<list>)
RETURN THE NTH ELEMENT OF A LIST
<n> the number of the element to return (zero origin)
<list> the list
returns
the nth element or NIL if the list isn't that long
(nthcdr <n>
<list>)
RETURN THE NTH CDR OF A LIST
<n> the number of the element to return (zero origin)
<list> the list
returns
the nth cdr or NIL if the list isn't that long
(member <expr>
<list> &key :test :test-not :key)
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)
:key
function to apply to test
function list argument (defaults
to identity)
returns
the remainder of the list starting with the expression
(assoc <expr>
<alist> &key :test :test-not :key)
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)
:key
function to apply to test
function list argument (defaults
to identity)
returns
the alist entry or NIL
(mapc <fcn>
<list1> <list>...)
APPLY FUNCTION TO SUCCESSIVE CARS
<fcn> the function or function name
<listn> a list for each argument of the function
returns
the first list of arguments
(mapcar <fcn>
<list1> <list>...)
APPLY FUNCTION TO SUCCESSIVE CARS
<fcn> the function or function name
<listn> a list for each argument of the function
returns
a list of the values returned
(mapl <fcn>
<list1> <list>...)
APPLY FUNCTION TO SUCCESSIVE CDRS
<fcn> the function or function name
<listn> a list for each argument of the function
returns
the first list of arguments
(maplist <fcn>
<list1> <list>...)
APPLY FUNCTION TO SUCCESSIVE CDRS
<fcn> the function or function name
<listn> a list for each argument of the function
returns
a list of the values returned
(mapcan <fcn>
<list1> <list>...)
APPL FUNCTION TO SUCCESSIVE CARS
<fcn> the function or function name
<listn> a list for each argument of the function
returns
list of return values nconc'd together
XLISP 2.1g LIST FUNCTIONS Page 46
(mapcon <fcn>
<list1> <list>...)
APPL FUNCTION TO SUCCESSIVE CDRS
<fcn> the function or function name
<listn> a list for each argument of the function
returns
list of return values nconc'd together
(subst <to>
<from> <expr> &key :test :test-not :key)
(nsubst <to>
<from> <expr> &key :test :test-not :key)
SUBSTITUTE EXPRESSIONS
SUBST does minimum copying as required by Common Lisp. NSUBST is the
destructive version.
<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)
:key
function to apply
to subtree test
function expression
argument (defaults to identity)
returns
the expression with substitutions
(sublis <alist>
<expr> &key :test :test-not :key)
(nsublis <alist>
<expr> &key :test :test-not :key)
SUBSTITUTE WITH AN A-LIST
SUBLIS does minimum copying as required
by Common Lisp. NSUBLIS is the
destructive version.
<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)
:key
function to apply
to subtree test
function expression
argument (defaults to identity)
returns
the expression with substitutions
(pairlis <keys>
<values> [<alist>])
BUILD AN A-LIST FROM TWO LISTS
In file common.lsp
<keys> list of association keys
<values> list of association values, same length as keys
<alist> existing association list, default NIL
returns
new association list
(copy-list
<list>)
COPY THE TOP LEVEL OF A LIST
In file common.lsp
<list> the list
returns
a copy of the list (new cons cells in top level)
(copy-alist
<alist>)
COPY AN ASSOCIATION LIST
In file common.lsp
<alist> the association list
returns a copy of the association list (keys and values not copies)
(copy-tree
<tree>) COPY A TREE
In file common.lsp
<tree> a tree structure of cons cells
returns
a copy of the tree structure
XLISP 2.1g LIST FUNCTIONS Page 47
(intersection
<list1> <list2> &key :test :test-not :key) SET FUNCTIONS
(union <list1>
<list2> &key :test :test-not :key)
(set-difference
<list1> <list2> &key :test :test-not :key)
(set-exclusive-or
<list1> <list2> &key :test :test-not :key)
(nintersection
<list1> <list2> &key :test :test-not :key)
(nunion <list1>
<list2> &key :test :test-not :key)
(nset-difference
<list1> <list2> &key :test :test-not :key)
(nset-exclusive-or
<list1> <list2> &key :test :test-not :key)
set-exclusive-or and nset-exclusive-or
defined in common.lsp. nunion,
nintersection, and
nset-difference are aliased
to their
non-destructive counterparts in
common.lsp.
<list1> first list
<list2> second list
:test
the test function (defaults to eql)
:test-not the test function (sense
inverted)
:key
function to apply to test function arguments (defaults to
identity)
returns
intersection: list of all elements in both lists
union: list of all elements in
either list
set-diference: list of all
elements in first list but not in
second list
set-exclusive-or: list of all
elements in only one list
"n" versions are
potentially destructive.
(adjoin <expr>
<list> :test :test-not :key)
ADD UNIQUE TO LIST
<expr> new element to add
<list> the list
:test
the test function (defaults to eql)
:test-not the test function <sense
inverted)
:key
function to apply to test function arguments (defaults to
identity)
returns
if element not in
list then (cons <expr> <list>), else
<list>.
XLISP 2.1g DESTRUCTIVE LIST FUNCTIONS Page 48
DESTRUCTIVE LIST
FUNCTIONS
Destructive functions
that have non-desctructive equivalents
are listed in
other sections.
See also sort, map-into, nreverse, delete, delete-if,
delete-if-not, fill,
and replace under SEQUENCE
FUNCTIONS, setf under
SYMBOL FUNCTIONS,
and mapcan, mapcon,
nsubst, nsublis, nintersection,
nunion,
nset-difference, and nset-exclusive-or under LIST FUNCTIONS.
(rplaca <list>
<expr>)
REPLACE THE CAR OF A LIST NODE
<list> the list node
<expr> the new value for the car of the list node
returns
the list node after updating the car
(rplacd <list>
<expr>)
REPLACE THE CDR OF A LIST NODE
<list> the list node
<expr> the new value for the cdr of the list node
returns
the list node after updating the cdr
(nconc
<list>...)
DESTRUCTIVELY CONCATENATE LISTS
<list> lists to concatenate
returns
the result of concatenating the lists
(nsubst-if <to>
<test> <expr> &key :key)
(nsubst-if-not
<to> <test> <expr> &key :key)
SUBSTITUTE EXPRESSIONS
<to> the new expression
<test> function of one argument to test each subtree
<expr> the expression in which to do the substitutions
:key
function to apply to test
function argument (defaults to
identity)
returns
the expression with substitutions
XLISP 2.1g ARITHMETIC FUNCTIONS Page 49
ARITHMETIC FUNCTIONS
Warning: integer and
ratio calculations that overflow become floating point
values as part
of the math extension, but give
no error otherwise. On
systems with IEEE
floating point, the values
+INF and -INF result from
overflowing floating
point calculations.
The math extension option adds complex numbers,
ratios, new functions, and
additional
functionality to some existing functions. Because of the size of
the extension, and the
performance loss it entails, some users may not wish
to include it. This
section documents the math
functions both with and
without the extension.
Functions that are described as having floating point arguments (SIN COS
TAN ASIN ACOS ATAN EXPT EXP SQRT) will take arguments of
any type (real or
complex) when the math extension is used. In
the descriptions, "rational
number" means integer or ratio only, and "real number" means floating
point number or
rational only.
Any rational
results are reduced to
canonical form (the
gcd of the
numerator and
denominator is 1, the denominator is positive); integral
results are
reduced to integers.
Integer complex numbers
with zero
imaginary parts are
reduced to integers.
(truncate <expr>
<denom>)
TRUNCATES TOWARD ZERO
(round <expr>
<denom>) ROUNDS
TOWARD NEAREST EVEN INTEGER
(floor <expr>
<denom>) TRUNCATES
TOWARD NEGATIVE INFINITY
(ceiling <expr>
<denom>)
TRUNCATES TOWARD INFINITY
Round,
floor, and ceiling, and the
second argument of truncate, are
part
of the math extension. Results too
big to be represented as
integers are returned as floating point numbers as part of the math
extension. Integers are returned as is.
<expr> the real number
<denom> real number to divide <expr> by before converting
returns
the integer result of converting the number, and, as a
second return value, the
remainder of the operation, defined
as expr - result*denom. the
type is float if either argument
is float, otherwise it is
rational.
(float
<expr>) CONVERTS AN
INTEGER TO A FLOATING POINT NUMBER
<expr> the real number
returns
the number as a floating point number
(rational
<expr>)
CONVERTS A REAL NUMBER TO A RATIONAL
Floating
point numbers too large to express return the floating point
number,
while numbers too small to
express return zero. Rational
numbers are returned as is.
<expr> the real number
returns
the number as a ratio or integer.
(+
[<expr>...]) ADD A LIST OF NUMBERS
With no arguments returns addition
identity, 0 (integer)
<expr> the numbers
returns
the result of the addition
XLISP 2.1g ARITHMETIC FUNCTIONS Page 50
(-
<expr>...) SUBTRACT A
LIST OF NUMBERS OR NEGATE A SINGLE NUMBER
<expr> the numbers
returns
the result of the subtraction
(*
[<expr>...]) MULTIPLY A LIST OF NUMBERS
With no arguments returns multiplication
identity, 1
<expr> the numbers
returns
the result of the multiplication
(/
<expr>...) DIVIDE A
LIST OF NUMBERS OR INVERT A SINGLE NUMBER
With
the math extension,
division of integer numbers results in a
rational quotient, rather than integer. To perform integer division,
use TRUNCATE. When an integer complex
is divided by an integer, the
quotient is floating point complex.
<expr> the numbers
returns
the result of the division
(1+ <expr>)
ADD ONE TO A NUMBER
<expr> the number
returns
the number plus one
(1- <expr>) SUBTRACT
ONE FROM A NUMBER
<expr> the number
returns
the number minus one
(rem
<expr>...)
REMAINDER OF A LIST OF NUMBERS
With the math extension, only two
arguments allowed.
<expr> the real numbers (must be integers, without math extension)
returns
the result of
the remainder operation
(remainder with
truncating division)
(mod <expr1>
<expr2>)
NUMBER MODULO ANOTHER NUMBER
Part of math extension.
<expr1> real number
<expr2> real number divisor (may not be zero)
returns
the remainder after
dividing <expr1> by
<expr2> using
flooring division, thus there is no discontinuity in the
function around zero.
(min
<expr>...)
THE SMALLEST OF A LIST OF NUMBERS
<expr> the real numbers
returns
the smallest number in the list
(max
<expr>...)
THE LARGEST OF A LIST OF NUMBERS
<expr> the real numbers
returns
the largest number in the list
(abs
<expr>)
THE ABSOLUTE VALUE OF A NUMBER
<expr> the number
returns
the absolute value of
the number, which is the floating
point magnitude for complex
numbers.
XLISP 2.1g ARITHMETIC FUNCTIONS Page 51
(signum
<expr>) GET THE SIGN OF A NUMBER
Defined in common.lsp
<expr> the number
returns
zero if number is zero, one if
positive, or negative one if
negative. Numeric type is same as number. For
a complex
number, returns unit magnitude
but same phase as number.
(gcd
[<n>...])
COMPUTE THE GREATEST COMMON DIVISOR
With no arguments returns 0, with one
argument returns the argument.
<n> The number(s) (integer)
returns
the greatest common divisor
(lcm
<n>...)
COMPUTE THE LEAST COMMON MULTIPLE
Part
of math extension. A result
which would be larger
than the
largest integer causes an error.
<n> The number(s) (integer)
returns
the least common multiple
(random <n>
[<state>])
COMPUTE A PSEUDO-RANDOM NUMBER
<n> the real number upper bound
<state> a random-state (default is *random-state*)
returns
a random number in range [0,n)
(make-random-state
[<state>])
CREATE A RANDOM-STATE
<state> a random-state, t,
or NIL (default NIL). NIL
means
*random-state*
returns
If <state> is t, a random
random-state, otherwise a copy of
<state>
(sin
<expr>)
COMPUTE THE SINE OF A NUMBER
(cos
<expr>)
COMPUTE THE COSINE OF A NUMBER
(tan
<expr>)
COMPUTE THE TANGENT OF A NUMBER
(asin
<expr>)
COMPUTE THE ARC SINE OF A NUMBER
(acos
<expr>)
COMPUTE THE ARC COSINE OF A NUMBER
<expr> the floating point number
returns
the sine, cosine, tangent,
arc sine, or arc cosine of the
number
(atan <expr>
[<expr2>]) COMPUTE
THE ARC TANGENT OF A NUMBER
<expr> the floating point number (numerator)
<expr2> the denominator, default
1. May only be specified if math
extension installed
returns
the arc tangent of <expr>/<expr2>
(sinh
<expr>)
COMPUTE THE HYPERBOLIC SINE OF A NUMBER
(cosh
<expr>)
COMPUTE THE HYPERBOLIC COSINE OF A NUMBER
(tanh
<expr>) COMPUTE
THE HYPERBOLIC TANGENT OF A NUMBER
(asinh
<expr>) COMPUTE
THE HYPERBOLIC ARC SINE OF A NUMBER
(acosh
<expr>) COMPUTE THE
HYPERBOLIC ARC COSINE OF A NUMBER
(atanh
<expr>) COMPUTE THE
HYPERBOLIC ARC TANGENT OF A NUMBER
Defined in common.lsp
<expr> the number
returns
the hyperbolic sine, cosine,
tangent, arc sine, arc cosine,
or arc tangent of the number.
XLISP 2.1g ARITHMETIC FUNCTIONS Page 52
(expt <x-expr>
<y-expr>)
COMPUTE X TO THE Y POWER
<x-expr> the number
<y-expr> the exponent
returns
x to the y power. If y is a fixnum, then the result type is
the same as the type
of x, unless fixnum or ratio and it
would overflow, then the result
type is a flonum.
(exp <x-expr>) COMPUTE E
TO THE X POWER
<x-expr> the floating point number
returns
e to the x power
(cis
<x-expr>) COMPUTE COSINE + I SINE
Defined in common.lsp
<x-expr> the number
returns
e to the ix power
(log <expr>
[<base>]) COMPUTE THE LOGRITHM
Part of the math extension
<expr> the number
<base> the base, default is e
returns
log base <base> of <expr>
(sqrt
<expr>)
COMPUTE THE SQUARE ROOT OF A NUMBER
<expr> the number
returns
the square root of the number
(numerator
<expr>)
GET THE NUMERATOR OF A NUMBER
Part of math extension
<expr> rational number
returns
numerator of number (number if integer)
(denominator
<expr>) GET
THE DENOMINATOR OF A NUMBER
Part of math extension
<expr> rational number
returns
denominator of number (1 if integer)
(complex <real>
[<imag>])
CONVERT TO COMPLEX NUMBER
Part of math extension
<real> real number real part
<imag> real number imaginary part (default 0)
returns
the complex number
(realpart
<expr>)
GET THE REAL PART OF A NUMBER
Part of the math extension
<expr> the number
returns
the real part of a complex number, or the number itself if a
real number
(imagpart
<expr>) GET THE IMAGINARY PART OF A NUMBER
Part of the math extension
<expr> the number
returns
the imaginary part of a complex
number, or zero of the type
of the number if a real number.
XLISP 2.1g ARITHMETIC FUNCTIONS Page 53
(conjugate
<expr>)
GET THE CONJUGATE OF A NUMBER
Part of the math extension
<expr> the number
returns
the conjugate of a complex number, or the number itself if a
real number.
(phase
<expr>) GET THE PHASE OF A NUMBER
Part of the math extension
<expr> the number
returns
the phase angle,
equivalent to (atan (imagpart
<expr>)
(realpart <expr>))
(< <n1>
<n2>...) TEST FOR LESS THAN
(<= <n1>
<n2>...)
TEST FOR LESS THAN OR EQUAL TO
(= <n1>
<n2>...) TEST FOR EQUAL TO
(/= <n1>
<n2>...) TEST FOR NOT EQUAL TO
(>= <n1>
<n2>...)
TEST FOR GREATER THAN OR EQUAL TO
(> <n1>
<n2>...) TEST FOR GREATER THAN
<n1> the first real number to compare
<n2> the second real number to compare
returns
the result of comparing <n1> with <n2>...
XLISP 2.1g BITWISE LOGICAL FUNCTIONS Page 54
BITWISE LOGICAL
FUNCTIONS
(logand
[<expr>...]) THE BITWISE AND OF A LIST OF INTEGERS
With no arguments returns identity -1
<expr> the integers
returns
the result of the and operation
(logior
[<expr>...]) THE BITWISE
INCLUSIVE OR OF A LIST OF INTEGERS
With no arguments returns identity 0
<expr> the integers
returns
the result of the inclusive or operation
(logxor
[<expr>...]) THE BITWISE
EXCLUSIVE OR OF A LIST OF INTEGERS
With no arguments returns identity 0
<expr> the integers
returns the result of the
exclusive or operation
(lognot
<expr>)
THE BITWISE NOT OF A INTEGER
<expr> the integer
returns
the bitwise inversion of integer
(logtest <expr1>
<expr2>) TEST
BITWISE AND OF TWO INTEGERS
Defined in common.lsp
<expr1> the first integer
<expr2> the second integer
returns
T if the result of the and operation is non-zero, else NIL
(ash <expr1>
<expr2>) ARITHMETIC SHIFT
Part of math extension
<expr1> integer to shift
<expr2> number of bit positions to shift (positive is to left)
returns
shifted integer
XLISP 2.1g STRING FUNCTIONS Page 55
STRING FUNCTIONS
Note: functions with
names starting "string" will
also accept a symbol, in
which case the
symbol's print name is used.
(string
<expr>) MAKE A
STRING FROM AN INTEGER ASCII 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-trim
<bag> <str>)
TRIM BOTH ENDS OF A STRING
<bag> a string containing characters to trim
<str> the string to trim
returns
a trimed copy of the string
(string-left-trim
<bag> <str>)
TRIM THE LEFT END OF A STRING
<bag> a string containing characters to trim
<str> the string to trim
returns
a trimed copy of the string
(string-right-trim
<bag> <str>)
TRIM THE RIGHT END OF A STRING
<bag> a string containing characters to trim
<str> the string to trim
returns
a trimed copy of the string
(string-upcase
<str> &key :start :end) CONVERT TO UPPERCASE
<str> the string
:start
the starting offset
:end
the ending offset + 1 or NIL for end of string
returns
a converted copy of the string
(string-downcase
<str> &key :start :end)
CONVERT TO LOWERCASE
<str> the string
:start
the starting offset
:end
the ending offset + 1 or NIL for end of string
returns
a converted copy of the string
(string-capitalize
<str> &key :start :end) CAPITALIZE STRING
<str> the string
:start
the starting offset
:end
the ending offset + 1 or NIL for end of string
returns
a converted copy of the
string with each word having an
initial uppercase letter and
following lowercase letters
(nstring-upcase
<str> &key :start :end) CONVERT TO UPPERCASE
<str> the string
:start
the starting offset
:end
the ending offset + 1 or NIL for end of string
returns
the converted string (not a copy)
XLISP 2.1g STRING FUNCTIONS Page 56
(nstring-downcase
<str> &key :start :end)
CONVERT TO LOWERCASE
<str> the string
:start
the starting offset
:end
the ending offset + 1 or NIL for end of string
returns
the converted string (not a copy)
(nstring-capitalize
<str> &key :start :end)
CAPITALIZE STRING
<str> the string
:start
the starting offset
:end
the ending offset + 1 or NIL for end of string
returns
the string with each word having an initial uppercase letter
and following lowercase letters
(not a copy)
(strcat
<expr>...) CONCATENATE STRINGS
Macro in init.lsp, to maintain
compatibility with XLISP.
See CONCATENATE for preferred function.
<expr> the strings to concatenate
returns
the result of concatenating the strings
(string<
<str1> <str2> &key :start1 :end1 :start2 :end2)
(string<=
<str1> <str2> &key :start1 :end1 :start2 :end2)
(string= <str1>
<str2> &key :start1 :end1 :start2 :end2)
(string/= <str1>
<str2> &key :start1 :end1 :start2 :end2)
(string>=
<str1> <str2> &key :start1 :end1 :start2 :end2)
(string>
<str1> <str2> &key :start1 :end1 :start2 :end2)
<str1> the first string to compare
<str2> the second string to compare
:start1
first substring starting offset
:end1
first substring ending offset + 1 or NIL for end of string
:start2
second substring starting offset
:end2
second substring ending offset + 1 or NIL for end of string
returns
string=: t if predicate is true, NIL otherwise
others: If predicate is true
then number of initial matching
characters, else NIL
Note: case is significant with these
comparison functions.
(string-lessp
<str1> <str2> &key :start1 :end1 :start2 :end2)
(string-not-greaterp
<str1> <str2> &key :start1 :end1 :start2 :end2)
(string-equal
<str1> <str2> &key :start1 :end1 :start2 :end2)
(string-not-equal
<str1> <str2> &key :start1 :end1 :start2 :end2)
(string-not-lessp
<str1> <str2> &key :start1 :end1 :start2 :end2)
(string-greaterp
<str1> <str2> &key :start1 :end1 :start2 :end2)
<str1> the first string to compare
<str2> the second string to compare
:start1
first substring starting offset
:end1
first substring ending offset + 1 or NIL for end of string
:start2
second substring starting offset
:end2
second substring ending offset + 1 or NIL for end of string
returns
string-equal: t if predicate is true, NIL otherwise
others: If predicate is true
then number of initial matching
characters, else NIL
Note: case is not significant with these comparison
functions -- all
uppercase characters are converted to
lowercase before being compared.
XLISP 2.1g CHARACTER FUNCTIONS Page 57
CHARACTER FUNCTIONS
(char <string>
<index>) EXTRACT
A CHARACTER FROM A STRING
<string> the string
<index> the string index (zero relative)
returns
the ascii code of the character
(alphanumericp
<chr>) IS THIS CHARACTER
ALPHANUMERIC?
<chr> the character
returns
true if the
character is alphabetic
or numeric, NIL
otherwise
(upper-case-p
<chr>) IS
THIS AN UPPER CASE CHARACTER?
<chr> the character
returns
true if the character is upper case, NIL otherwise
(lower-case-p
<chr>) IS
THIS A LOWER CASE CHARACTER?
<chr> the character
returns
true if the character is lower case, NIL otherwise
(alpha-char-p
<chr>) IS
THIS AN ALPHABETIC CHARACTER?
<chr> the character
returns
true if the character is alphabetic, NIL otherwise
(both-case-p
<chr>) IS THIS AN
ALPHABETIC (EITHER CASE) CHARACTER?
<chr> the character
returns
true if the character
is available in both
cases, NIL
otherwise
(digit-char-p
<chr>)
IS THIS A DIGIT CHARACTER?
<chr> the character
returns
the digit weight if character is a digit, NIL otherwise
(char-code
<chr>) GET
THE ASCII CODE OF A CHARACTER
<chr> the character
returns
the ASCII character code (integer, parity bit stripped)
(code-char
<code>) GET THE
CHARACTER WITH A SPECFIED ASCII CODE
<code> the ASCII code (integer, range 0-127)
returns
the character with that code or NIL
(char-upcase
<chr>)
CONVERT A CHARACTER TO UPPER CASE
<chr> the character
returns
the upper case version of
the character, if one exists,
otherwise returns the character
(char-downcase
<chr>) CONVERT
A CHARACTER TO LOWER CASE
<chr> the character
returns
the lower case version
of the character, if one exists,
otherwise returns the character
(digit-char
<n>)
CONVERT A DIGIT WEIGHT TO A DIGIT
<n> the digit weight (integer)
returns
the digit character or NIL
XLISP 2.1g CHARACTER FUNCTIONS Page 58
(char-int
<chr>)
CONVERT A CHARACTER TO AN INTEGER
<chr> the character
returns
the ASCII character code (range 0-255)
(int-char
<int>)
CONVERT AN INTEGER TO A CHARACTER
<int> the ASCII character code (treated modulo 256)
returns
the character with that code
(char< <chr1>
<chr2>...)
(char<=
<chr1> <chr2>...)
(char= <chr1>
<chr2>...)
(char/= <chr1>
<chr2>...)
(char>=
<chr1> <chr2>...)
(char> <chr1>
<chr2>...)
<chr1> the first character to compare
<chr2> the second character(s) to compare
returns
t if predicate is true, NIL otherwise
Note: case is significant with these
comparison functions.
(char-lessp
<chr1> <chr2>...)
(char-not-greaterp
<chr1> <chr2>...)
(char-equal
<chr1> <chr2>...)
(char-not-equal
<chr1> <chr2>...)
(char-not-lessp
<chr1> <chr2>...)
(char-greaterp
<chr1> <chr2>...)
<chr1> the first string to compare
<chr2> the second string(s) to compare
returns
t if predicate is true, NIL otherwise
Note: case is not significant with these comparison
functions -- all
uppercase characters are converted to
lowercase before the comparison.
XLISP 2.1g STRUCTURE FUNCTIONS Page 59
STRUCTURE FUNCTIONS
XLISP provides a
subset of the Common Lisp
structure definition facility.
No slot options are allowed, but
slots can have default initialization
expressions.
(defstruct name [<comment>]
<slot-desc>...)
or
(defstruct (name <option>...)
[<comment>] <slot-desc>...)
fsubr
<name> the structure name symbol
(quoted)
<option> option description (quoted)
<comment> comment string (ignored)
<slot-desc> slot descriptions (quoted)
returns the structure name
The recognized options
are:
(:conc-name name)
(:include name [<slot-desc>...])
(:print-function <function>)
Note that if
:CONC-NAME appears, it should be before :INCLUDE.
Each slot description
takes the form:
<name>
or
(<name> <defexpr>)
If the default
initialization expression is not specified, the slot will be
initialized to NIL
if no keyword argument
is passed to the
creation
function.
The optional
:PRINT-FUNCTION overrides the
default #S notation.
The
function must take
three arguments, the structure instance, the stream, and
the current printing
depth.
DEFSTRUCT causes access functions to be created for each of the slots and
also arranges that
SETF will work with those access
functions. The access
function names are constructed by taking the structure name, appending a
'-' and then
appending the slot name. This can
be overridden by using the
:CONC-NAME option.
DEFSTRUCT also makes a creation function called MAKE-<structname>, a copy
function called
COPY-<structname>
and a predicate function called
<structname>-P.
The creation function takes keyword
arguments for each of
the slots. Structures
can be created using the #S( read macro, as well.
The property
*struct-slots* is added
to the symbol that names
the
structure. This
property consists of an association
list of slot names and
closures that evaluate to the initial
values (NIL if no initial
value
expression).
XLISP 2.1g STRUCTURE FUNCTIONS Page 60
For instance:
(defstruct foo bar (gag 2))
creates the following
functions:
(foo-bar <expr>)
(setf (foo-bar <expr>)
<value>)
(foo-gag <expr>)
(setf (foo-gag <expr>)
<value>)
(make-foo &key :bar :gag)
(copy-foo <expr>)
(foo-p <expr>)
XLISP 2.1g OBJECT FUNCTIONS Page 61
OBJECT FUNCTIONS
Note that the
functions provided in
classes.lsp are useful
but not
necessary.
Messages defined for
Object and Class are listed starting on page 20.
(send <object>
<message> [<args>...]) SEND A MESSAGE
<object> the object to receive the message
<message> message sent to object
<args> arguments to method (if any)
returns
the result of the method
(send-super
<message> [<args>])
SEND A MESSAGE TO SUPERCLASS
valid only in method context
<message> message sent to method's
superclass
<args> arguments to method (if any)
returns
the result of the method
(defclass <sym>
<ivars> [<cvars> [<super>]]) DEFINE A NEW CLASS
defined in class.lsp as a macro
<sym> symbol whose
value is to be bound to the
class object
(quoted)
<ivars> list of instance variables
(quoted). Instance variables
specified either as
<ivar> or (<ivar>
<init>) to specify
non-NIL default initial value.
<cvars> list of class variables (quoted)
<super> superclass, or Object if absent.
This function sends :SET-PNAME (defined
in classes.lsp) to the new
class to set the class' print name
instance variable.
Methods defined for classes defined with
defclass:
(send <object> :<ivar>)
Returns the specified instance
variable
(send <object> :SET-IVAR
<ivar> <value>)
Used to set an instance
variable, typically with setf.
(send <sym> :NEW {:<ivar>
<init>})
Actually definition
for :ISNEW. Creates
new object
initializing instance
variables as specified
in keyword
arguments, or
to their default if
keyword argument is
missing. Returns the object.
(defmethod
<class> <sym> <fargs> <expr> ...) DEFINE A NEW METHOD
defined in class.lsp as a macro
<class> Class which will respond to message
<sym> Message name (quoted)
<fargs> Formal argument list. Leading "self" is implied
(quoted)
<expr> Expressions constituting body of method (quoted)
returns
the class object.
XLISP 2.1g OBJECT FUNCTIONS Page 62
(definst <class>
<sym> [<args>...])
DEFINE A NEW GLOBAL INSTANCE
defined in class.lsp as a macro
<class> Class of new object
<sym> Symbol whose value will be set to new object
<args> Arguments passed to
:NEW (typically initial values
for
instance variables)
XLISP 2.1g PREDICATE FUNCTIONS Page 63
PREDICATE FUNCTIONS
(atom
<expr>) IS THIS AN ATOM?
<expr> the expression to check
returns
t if the value is an atom, NIL otherwise
(symbolp
<expr>) IS THIS A SYMBOL?
<expr> the expression to check
returns
t if the expression is a symbol, NIL otherwise
(numberp
<expr>) IS THIS A NUMBER?
<expr> the expression to check
returns
t if the expression is a number, NIL otherwise
(null
<expr>) IS THIS AN EMPTY LIST?
<expr> the list to check
returns
t if the list is empty, NIL otherwise
(not
<expr>) IS THIS FALSE?
<expr> the expression to check
return
t if the value is NIL, NIL otherwise
(listp
<expr>) IS THIS A LIST?
<expr> the expression to check
returns
t if the value is a cons or NIL, NIL otherwise
(endp
<list>) IS THIS THE END OF A LIST?
<list> the list
returns
t if the value is NIL, NIL otherwise
(consp
<expr>) IS THIS A NON-EMPTY LIST?
<expr> the expression to check
returns
t if the value is a cons, NIL otherwise
(constantp
<expr>) IS THIS A CONSTANT?
<expr> the expression to check
returns
t if the value is a constant
(basically, would EVAL <expr>
repeatedly return the same
thing?), NIL otherwise.
(specialp
<expr>)
IS THIS A SPECIAL SYMBOL?
<expr> the expression to check
returns
t if the value is a symbol which is SPECIAL, NIL otherwise.
(integerp
<expr>) IS THIS AN INTEGER?
<expr> the expression to check
returns
t if the value is an integer, NIL otherwise
(floatp
<expr>) IS THIS A FLOAT?
<expr> the expression to check
returns
t if the value is a float, NIL otherwise
XLISP 2.1g PREDICATE FUNCTIONS Page 64
(rationalp
<expr>)
IS THIS A RATIONAL NUMBER?
Part of math extension.
<expr> the expression to check
returns
t if the value is rational (integer or ratio), NIL otherwise
(complexp
<expr>)
IS THIS A COMPLEX NUMBER?
Part of math extension.
<expr> the expression to check
returns
t if the value is a complex number, NIL otherwise
(stringp
<expr>) IS THIS A STRING?
<expr> the expression to check
returns
t if the value is a string, NIL otherwise
(characterp
<expr>) IS THIS A CHARACTER?
<expr> the expression to check
returns
t if the value is a character, NIL otherwise
(arrayp
<expr>) IS THIS
AN ARRAY?
<expr> the expression to check
returns
t if the value is an array, NIL otherwise
(streamp
<expr>) IS THIS A STREAM?
<expr> the expression to check
returns
t if the value is a stream, NIL otherwise
(open-stream-p
<stream>) IS STREAM OPEN?
<stream> the stream
returns
t if the stream is open, NIL otherwise
(input-stream-p
<stream>) IS STREAM READABLE?
<stream> the stream
returns
t if stream is readable, NIL otherwise
(output-stream-p
<stream>)
IS STREAM WRITABLE?
<stream> the stream
returns
t if stream is writable, NIL otherwise
(objectp
<expr>) IS THIS AN OBJECT?
<expr> the expression to check
returns
t if the value is an object, NIL otherwise
(classp
<expr>) IS THIS A CLASS OBJECT?
<expr> the expression to check
returns
t if the value is a class object, NIL otherwise
(boundp
<sym>)
IS A VALUE BOUND TO THIS SYMBOL?
<sym> the symbol
returns
t if a value is bound to the symbol, NIL otherwise
(fboundp
<sym>) IS A
FUNCTIONAL VALUE BOUND TO THIS SYMBOL?
<sym> the symbol
returns
t if a functional value is
bound to the
symbol, NIL
otherwise
XLISP 2.1g PREDICATE FUNCTIONS Page 65
(functionp
<sym>) IS THIS A FUNCTION?
Defined in common.lsp
<expr> the expression to check
returns
t if the value is a function --
that is, can it be applied
to arguments. This is true for any symbol (even those with
no function binding), list with
car being lambda, a closure,
or subr. Otherwise returns NIL.
(minusp
<expr>) IS THIS NUMBER
NEGATIVE?
<expr> the number to test
returns
t if the number is negative, NIL otherwise
(zerop
<expr>) IS THIS NUMBER ZERO?
<expr> the number to test
returns
t if the number is zero, NIL otherwise
(plusp
<expr>) IS THIS NUMBER POSITIVE?
<expr> the number to test
returns
t if the number is positive, NIL otherwise
(evenp
<expr>) IS THIS INTEGER EVEN?
<expr> the integer to test
returns
t if the integer is even, NIL otherwise
(oddp
<expr>) IS THIS INTEGER ODD?
<expr> the integer to test
returns
t if the integer is odd, NIL otherwise
(subsetp <list1>
<list2> &key :test :test-not :key) IS SET A SUBSET?
<list1> the first list
<list2> the second list
:test
test function (defaults to eql)
:test-not test function (sense inverted)
:key
function to apply to test function arguments (defaults to
identity)
returns
t if every element of the first
list is in the second list,
NIL otherwise
(eq <expr1>
<expr2>)
ARE THE EXPRESSIONS EQUAL?
(eql <expr1>
<expr2>)
(equal <expr1>
<expr2>)
(equalp <expr1>
<expr2>)
equalp defined in common.lsp
<expr1> the first expression
<expr2> the second expression
returns
t if equal, NIL otherwise. Each is progressively more
liberal in what is
"equal":
eq: identical pointers --
works with characters, symbols,
and arbitrarily small
integers
eql: works with all numbers, if same type (see also = on
page 53)
equal: lists and strings
equalp: case insensitive characters (and strings), numbers
of differing types,
arrays (which can be equalp to
string containing same elements)
XLISP 2.1g PREDICATE FUNCTIONS Page 66
(typep <expr>
<type>)
IS THIS A SPECIFIED TYPE?
<expr> the expression to test
<type> the type
specifier. Symbols can either
be one of those
listed under type-of (on page
87) or one of:
ATOM any atom
NULL NIL
LIST matches NIL or any cons cell
STREAM any stream
NUMBER any number type
RATIONAL fixnum or ratio (math extension)
STRUCT any structure (except hash-table)
FUNCTION any function, as defined by functionp (page
65)
The specifer can also be a form (which can be nested). All
form elements are quoted. Valid
form cars:
or any of the cdr type specifiers must be true
and all of the cdr type specifiers must be true
not the single cdr type specifier must be false
satisfies the result of applying the cdr predicate
function
to <expr>
member <expr> must be eql to one of the cdr
values
object <expr> must be an
object, of class specified by
the single
cdr value. The cdr value
can be a
symbol which must
evaluate to a class.
Note that everything is of type T, and nothing is of type
NIL.
returns
t if <expr> is of type <type>, NIL otherwise.
XLISP 2.1g CONTROL CONSTRUCTS Page 67
CONTROL CONSTRUCTS
(cond
<pair>...) EVALUATE CONDITIONALLY
fsubr
<pair> pair consisting of:
(<pred> <expr>...)
where
<pred> is a predicate expression
<expr> evaluated if the predicate is not NIL
returns
the value of the first expression whose predicate is not NIL
(and
<expr>...) THE
LOGICAL AND OF A LIST OF EXPRESSIONS
fsubr
<expr> the expressions to be ANDed
returns
NIL if any expression evaluates
to NIL, otherwise the value
of the last expression (evaluation
of expressions stops
after the first expression that
evaluates to NIL)
(or
<expr>...)
THE LOGICAL OR OF A LIST OF EXPRESSIONS
fsubr
<expr> the expressions to be ORed
returns
NIL if all expressions evaluate to NIL, otherwise the value
of the first non-NIL expression (evaluation of expressions
stops after the first expression
that does not evaluate to
NIL)
(if <texpr>
<expr1> [<expr2>])
EVALUATE EXPRESSIONS CONDITIONALLY
fsubr
<texpr> the test expression
<expr1> the expression to be evaluated if texpr is non-NIL
<expr2> the expression to be evaluated if texpr is NIL
returns
the value of the selected expression
(when <texpr>
<expr>...) EVALUATE
ONLY WHEN A CONDITION IS TRUE
fsubr
<texpr> the test expression
<expr> the expression(s) to be evaluted if texpr is non-NIL
returns
the value of the last expression or NIL
(unless <texpr>
<expr>...) EVALUATE ONLY
WHEN A CONDITION IS FALSE
fsubr
<texpr> the test expression
<expr> the expression(s) to be evaluated if texpr is NIL
returns
the value of the last expression or NIL
XLISP 2.1g CONTROL CONSTRUCTS Page 68
(case <expr>
<case>...[(t <expr>)]) SELECT BY CASE
fsubr
<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
(t <expr>) default case (no previous matching)
returns
the value of the last expression of the matching case
(let
(<binding>...) <expr>...) CREATE LOCAL BINDINGS
(let*
(<binding>...) <expr>...) LET WITH SEQUENTIAL BINDING
fsubr
<binding> the variable bindings
each of which is either:
1) a symbol (which is initialized to NIL)
2) a list whose car is
a symbol and whose cadr is an
initialization
expression
<expr> the expressions to be evaluated
returns
the value of the last expression
(flet
(<binding>...) <expr>...) CREATE LOCAL FUNCTIONS
(labels
(<binding>...) <expr>...) FLET WITH RECURSIVE FUNCTIONS
(macrolet
(<binding>...) <expr>...) CREATE LOCAL MACROS
fsubr
<binding> the function bindings
each of which is:
(<sym> <fargs>
<expr>...)
where:
<sym> the function/macro name
<fargs> formal argument list (lambda list)
<expr> expressions constituting the body
of the
function/macro
<expr> the expressions to be evaluated
returns
the value of the last expression
(catch <sym>
<expr>...) EVALUATE
EXPRESSIONS AND CATCH THROWS
fsubr
<sym> the catch tag
<expr> expressions to evaluate
returns the value of the last expression or the throw expression
(throw <sym>
[<expr>]) THROW TO A CATCH
fsubr
<sym> the catch tag
<expr> the value for the catch to return (defaults to NIL)
returns
never returns
XLISP 2.1g CONTROL CONSTRUCTS Page 69
(unwind-protect
<expr> <cexpr>...)
PROTECT EVALUATION OF AN EXPRESSION
fsubr
<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
XLISP 2.1g LOOPING CONSTRUCTS Page 70
LOOPING CONSTRUCTS
(loop
<expr>...) BASIC LOOPING FORM
fsubr
<expr> the body of the loop
returns
never returns (must use non-local exit, such as RETURN)
(do
(<binding>...) (<texpr> <rexpr>...) <expr>...) GENERAL LOOPING FORM
(do*
(<binding>...) (<texpr> <rexpr>...) <expr>...)
fsubr. do binds simultaneously, do* binds
sequentially
<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> the initial value of the symbol
<step> a step expression
<texpr> the termination test expression
<rexpr> result expressions (the default is NIL)
<expr> the body of the loop (treated like an implicit prog)
returns
the value of the last result expression
(dolist (<sym>
<expr> [<rexpr>]) <expr>...) LOOP THROUGH A LIST
fsubr
<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)
returns
the result expression
(dotimes (<sym>
<expr> [<rexpr>]) <expr>...) LOOP FROM ZERO TO N-1
fsubr
<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)
returns
the result expression
XLISP 2.1g THE PROGRAM FEATURE Page 71
THE PROGRAM FEATURE
(prog
(<binding>...) <expr>...) THE PROGRAM FEATURE
(prog*
(<binding>...) <expr>...) PROG WITH SEQUENTIAL BINDING
fsubr -- equivalent to (let () (block NIL
(tagbody ...)))
<binding> the variable bindings
each of which is either:
1) a symbol (which is initialized to NIL)
2) a list whose car is a
symbol and whose cadr is an
initialization expression
<expr> expressions to evaluate or tags (symbols)
returns
NIL or the argument passed to the return function
(block <name>
<expr>...) NAMED BLOCK
fsubr
<name> the block name (quoted symbol)
<expr> the block body
returns
the value of the last expression
(return
[<expr>]) CAUSE A
PROG CONSTRUCT TO RETURN A VALUE
fsubr
<expr> the value (defaults to NIL)
returns
never returns
(return-from
<name> [<value>])
RETURN FROM A NAMED BLOCK OR FUNCTION
fsubr.
In traditional Xlisp, the names
are dynamically scoped. A
compilation option (default) uses lexical
scoping like Common Lisp.
<name> the block or function
name (quoted symbol). If name is NIL,
use function RETURN.
<value> the value to return (defaults to NIL)
returns
never returns
(tagbody
<expr>...) BLOCK WITH LABELS
fsubr
<expr> expression(s) to evaluate or tags (symbols)
returns
NIL
(go <sym>) GO TO A
TAG WITHIN A TAGBODY
fsubr.
In traditional Xlisp,
tags are dynamically scoped. A
compilation option (default) uses lexical
scoping like Common Lisp.
<sym> the tag (quoted)
returns
never returns
(progv <slist>
<vlist> <expr>...)
DYNAMICALLY BIND SYMBOLS
fsubr
<slist> list of symbols (evaluated)
<vlist> list of values to
bind to the symbols (evaluated)
<expr> expression(s) to evaluate
returns
the value of the last expression
(prog1 <expr1>
<expr>...)
EXECUTE EXPRESSIONS SEQUENTIALLY
fsubr
<expr1> the first expression to evaluate
<expr> the remaining expressions to evaluate
returns
the value of the first expression
XLISP 2.1g THE PROGRAM FEATURE Page 72
(prog2 <expr1>
<expr2> <expr>...) EXECUTE EXPRESSIONS SEQUENTIALLY
fsubr
<expr1> the first expression to evaluate
<expr2> the second expression to evaluate
<expr> the remaining expressions to evaluate
returns
the value of the second expression
(progn
<expr>...)
EXECUTE EXPRESSIONS SEQUENTIALLY
fsubr
<expr> the expressions to evaluate
returns
the value of the last expression (or NIL)
XLISP 2.1g INPUT/OUTPUT FUNCTIONS Page 73
INPUT/OUTPUT FUNCTIONS
Note that when printing objects, printing is accomplished by sending the
message :prin1 to the
object.
(read [<stream>
[<eofp> [<eof> [<rflag>]]]]) READ AN EXPRESSION
NOTE:
there has been an incompatible
change in arguments from prior
versions.
<stream> the input stream (default, or NIL, is *standard-input*, T is
*terminal-io*)
<eofp> When T, signal an error on end of file, when NIL return
<eof> (default is T)
<eof> the value to return on end of file (default is NIL)
<rflag> recursive read flag. The value is ignored
returns
the expression read
(set-macro-character
<ch> <fcn> [ T ]) MODIFY READ TABLE
defined in init.lsp
<ch> character to define
<fcn> function to bind to character (see page 12)
T
if TMACRO rather than NMACRO
(get-macro-character
<ch>)
EXAMINE READ TABLE
defined in init.lsp
<ch> character
returns
function bound to character
(print <expr>
[<stream>]) PRINT
AN EXPRESSION ON A NEW LINE
The expression is printed using prin1,
then current line is terminated
(Note: this is backwards from Common
Lisp).
<expr> the expression to be printed
<stream> the output stream (default,
or NIL, is *standard-output*, T
is *terminal-io*)
returns
the expression
(prin1 <expr>
[<stream>])
PRINT AN EXPRESSION
symbols, cons cells (without
circularities), arrays, strings, numbers,
and characters are printed in
a format generally acceptable to the
read
function. Printing format
can be affected by the
global
formatting variables: *print-level*
and *print-length* for lists and
arrays,
*integer-format* for fixnums,
*float-format* for flonums,
*ratio-format* for ratios, and *print-case* and *readtable-case* for
symbols.
<expr> the expression to be printed
<stream> the output stream (default,
or NIL, is *standard-output*, T
is *terminal-io*)
returns
the expression
XLISP 2.1g INPUT/OUTPUT FUNCTIONS Page 74
(princ <expr>
[<stream>]) PRINT AN
EXPRESSION WITHOUT QUOTING
Like
PRIN1 except symbols
(including uninterned), strings,
and
characters are printed without using any
quoting mechanisms.
<expr> the expressions to be printed
<stream> the output stream (default,
or NIL, is *standard-output*, T
is *terminal-io*)
returns
the expression
(pprint <expr>
[<stream>])
PRETTY PRINT AN EXPRESSION
Uses prin1 for printing.
<expr> the expressions to be printed
<stream> the output stream (default,
or NIL, is *standard-output*, T
is *terminal-io*)
returns
the expression
(terpri
[<stream>])
TERMINATE THE CURRENT PRINT LINE
<stream> the output stream (default,
or NIL, is *standard-output*, T
is *terminal-io*)
returns
NIL
(fresh-line
[<stream>]) START A NEW LINE
<stream> the output stream (default,
or NIL, is *standard-output*, T
is *terminal-io*)
returns
t if a new list was started, NIL
if already at the start of
a line.
(flatsize
<expr>) LENGTH OF
PRINTED REPRESENTATION USING PRIN1
<expr> the expression
returns the length
(flatc
<expr>) LENGTH OF
PRINTED REPRESENTATION USING PRINC
<expr> the expression
returns
the length
(y-or-n-p [<fmt>
[<arg>...]])
ASK A YES OR NO QUESTION
(yes-or-no-p
[<fmt> [<arg>...]])
defined
in common.lsp. Uses *terminal-io* stream for
interaction.
y-or-n-p
strives for a single character answer, using
get-key if
defined.
<fmt> optional format string for question (see page 75)
<arg> arguments, if any, for
format string
returns
T for yes, NIL for no.
XLISP 2.1g THE FORMAT FUNCTION Page 75
THE FORMAT FUNCTION
(format <stream>
<fmt> [<arg>...]) DO FORMATTED OUTPUT
<stream> the output stream (T is *standard-output*)
<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 or ~a
print next argument using princ
~S or ~s
print next argument using prin1
~D or ~d
print next argument as decimal integer
~E or ~e
print next argument in exponential form
~F or ~f
print next argument in fixed point form
~G or ~g
print next argument using either ~E or ~F depending
on
magnitude
~O or ~o
print next argument as octal integer
~X or ~x
print next argument as hexidecimal integer
~%
start a new line
~& start a new line if not on a new line
~|
start a new page
~?
use next argument as recursive format string
~( ~)
process format string with case conversion
~{ ~}
process format string repetitively
~[ ~; ~]
process format string conditionally
~*
skip arguments
~t or ~T
go to a specified column
~~
print a tilde character
~\n
ignore return and following whitespace
The format directives
can contain optional prefix and optional colon (:) or
at-sign (@) modifiers between the tilde and
directive character. Prefix
characters are unsigned integers, the character '#' which represents the
remaining number of
arguments, the character 'v' to
indicate the number is
taken from the next argument, or a single quote (') followed by a single
character for those
parameters that should be a single character.
For ~A and ~S the full
form is:
~mincol,colinc,minpad,padchar:@A (or S)
If : is given, NIL will print as
"()" rather than
"NIL". The string is
padded on the right
(or left, if @ is given) with at least
"minpad" copies
of the "padchar". Padding characters are
then inserted "colinc" characters
at a time until the total width is at least
"mincol". The defaults are 0
for mincol and minpad,
1 for colinc, and #\space for padchar. For example:
~15,,2,'.@A
The output is padded on the left with at least 2 periods until the output
is at least 15
characters wide.
XLISP 2.1g THE FORMAT FUNCTION Page 76
For ~D, ~O, and ~X the
full form is ("D" shown):
~mincol,padchar@D
If the argument is not a
FIXNUM, then the format
"~mincolA" is used. If
"mincol" is
specified then the number is padded on
the left to be at least
that many characters long using "padchar". "padchar"
defaults to #\space.
If @ is used and the
value is positive, then a leading plus sign is printed
before the first digit.
For ~E ~F and ~G the
full form is:
~mincol,round,padchar@E (or F or G)
(This implementation
is not Common Lisp compatible.) If the argument is not
a real
number (FIXNUM, RATIO,
or FLONUM), then
the format
"~mincol,padcharD"
is used. The number is printed using the C language e,
f, or g formats. If
the number could potentially take more
than 100 digits
to print, then F format is forced to E format, although some
C libraries
will do this at a lower
number of digits. If
"round" is specified,
than
that is the number of
digits to the right of the decimal point that will be
printed,
otherwise six digits (or whatever is necessary in G format) are
printed. In G format, trailing zeroes are deleted and
exponential notation
is used if the
exponent of the number is greater than the precision or less
than -4. If the @ modifier is used, a leading plus sign is printed before
positive values. If
"mincol" is specified, the number is padded on the left
to be at least
"mincol" characters long using "padchar".
"padchar" defaults
to #\space.
For ~%, ~|,
and ~~, the full
form is ~n%, ~n|,
or ~n~. "n" copies
(default=1) of the
character are output.
For ~&, the full
form is ~n&. ~0& does nothing.
Otherwise enough new line
characters are emited
to move down to the "n"th new line (default=1).
For ~?, the next argument is taken as a format string, upon completion
execution resumes in
the current format string. The argument after is taken
as the list
of arguments used for the new
format string unless the @
modifier is used, in
which case the current argument list is used.
For ~(, the full
form is ~(string~). The string is processed as a format
string, however case
conversion is performed on the output. If no modifiers
are used, the string is converted to lowercase. If the colon modifier is
used alone then all
words are capitalized. If the @ modifier
is used alone
then the first character is converted to upper case and all remaining to
lowercase. If both
modifiers are used, all characters are converted to
uppercase.
For ~{, the full form is ~n{string~}.
Repeatedly processes string as a
format string, or if the string is zero length, takes the
next argument as
the string. Iteration stops when processing has occured n
times or no
arguments remain. If
the colon modifier is used on the ~} command, and n is
non-zero then the string will be processed at least once. If no modifiers
are used on ~{, then
the arguments are taken from the
next argument (like
in ~?). If the colon modifier is used, the arguments
are taken from the
XLISP 2.1g THE FORMAT FUNCTION Page 77
next argument which
must be a list of sublists -- the sublists are
used in
turn to provide
arguments on each iteration. In either case, the @ modifier
will cause the current arguement list to be used
rather than a single list
argument.
For ~[,
there are three
formats. The first
form is
~n[clause0~;clause1...~;clausen~]. Only
one clause string
is used,
depending on the value
of n. When n is absent, its value is taken
from the
argument list (as
though 'v' had been used.) The last
clause is treated as
an "otherwise" clause if
a colon modifier is
used in its leading ~;
command. The second
form is ~:[clauset~;clausenil~]. The
next argument is
examined (but not
consumed), and if nil
clausenil is used, otherwise
clauset is used. The third form is ~@[string~]. If then next argument is
non-nil, then it
is not used up and the format string is used, otherwise
the argument is used
up and the string is not used.
For ~*, the full form
is ~n*. The count, n, defaults to 1 and is the number
of arguments to skip. If the colon
modifier is used, n is
negated and
skipping is backwards. The @ modifier causes n to be an absolute argument
position (with default of 0), where the first argument is argument 0.
Attempts to position
before the first argument will position
at the first
argument, while
attempts to position after the last argument signals an
error.
For ~T, the full form
is:
~count,tabwidth@T
The cursor is
moved to column "count" (default 1). If the cursor
is
initially at count or
beyond, then the cursor is moved
forward to the next
position that is a
multiple of "tabwidth" (default 1) columns beyond count.
When the @
modifier is used, then positioning is
relative. "count" spaces
are printed, then additional spaces are printed to make the column number
be a multiple of
"tabwidth". Note that column calcuations will be incorrect
if ASCII tab
characters or ANSI cursor positioning sequences are used.
For ~\n, if the
colon modifier is used, then
the format directive is
ignored (allowing
embedded returns in the source for enhanced readability).
If the at-sign modifier is used, then a carriage return is
emitted, and
following whitespace
is ignored.
XLISP 2.1g FILE I/O FUNCTIONS Page 78
FILE I/O FUNCTIONS
Note that initially, when starting XLISP-PLUS,
there are six system stream
symbols which are
associated with three streams. *TERMINAL-IO* is a special
stream that
is bound to
the keyboard and
display, and allows
for
interactive editing. *STANDARD-INPUT* is bound
to standard input or to
*TERMINAL-IO* if not
redirected. *STANDARD-OUTPUT* is
bound to standard
output or to
*TERMINAL-IO* if not redirected. *ERROR-OUTPUT* (error message
output), *TRACE-OUTPUT* (for TRACE
and TIME functions), and *DEBUG-IO*
(break loop i/o, and messages) are all bound to
*TERMINAL-IO*. Standard
input and output can
be redirected on most systems.
File streams are printed using the #< format that cannot be read by the
reader. Console, standard input, standard output, and closed streams are
explicitly indicated. Other file streams will typically indicate the name
of the attached file.
When the transcript is
active (either -t on the command line or the DRIBBLE
function), all
characters that would
be sent to
the display via
*TERMINAL-IO* are also
placed in the transcript file.
*TERMINAL-IO* should not
be changed. Any other system streams that are
changed by an
application should be restored to their original values.
(read-char
[<stream>[<eofp>[<eof>]]]) READ A CHARACTER FROM A STREAM
NOTE: New eof arguments are incompatible
with older XLISP versions.
<stream> the input stream (default, or NIL, is *standard-input*, T is
*terminal-io*)
<eofp> When T, signal
an error on end of file, when NIL return
<eof> (default is T)
<eof> the value to return on end of file (default is NIL)
returns
the character or <eof> at end of file
(peek-char
[<flag> [<stream>]]) PEEK AT THE NEXT CHARACTER
<flag> flag for skipping white space (default is NIL)
<stream> the input stream (default, or NIL, is *standard-input*, T is
*terminal-io*)
returns
the character or NIL at end of file
(write-char <ch>
[<stream>]) WRITE
A CHARACTER TO A STREAM
<ch> the character to write
<stream> the output stream (default,
or NIL, is *standard-output*, T
is *terminal-io*)
returns
the character
(read-line
[<stream>[<eofp>[<eof>]]]) READ A LINE FROM A STREAM
NOTE: New eof arguments are incompatible
with older XLISP versions.
<stream> the input stream (default, or NIL, is *standard-input*, T is
*terminal-io*)
<eofp> When T, signal an error
on end of file, when NIL return
<eof> (default is T)
<eof> the value to return on end of file (default is NIL)
returns
the string excluding the #\newline, or <eof> at end of file
XLISP 2.1g FILE I/O FUNCTIONS Page 79
(open <fname>
&key :direction :element-type :if-exists :if-does-not-exist)
OPEN A
FILE STREAM
The function OPEN has been significantly
enhanced over original XLISP.
The original function only had the :direction keyword argument, which
could only have the values :input or
:output. When used with the
:output keyword, it was equivalent to
(open <fname> :direction :output
:if-exists :supersede). A maximum of ten
files can be open at any one
time, including any files open via the
LOAD, DRIBBLE, SAVE and RESTORE
commands. The open command may force a garbage collection to reclaim
file slots used by unbound file streams.
<fname> the file name
string, symbol, or file stream created
via OPEN. In the last
case, the name is used to open a
second stream on
the same file --
this can cause
problems if one or more
streams is used for writing.
:direction Read and write
permission for stream
(default is
:input).
:input Open file for read operations only.
:probe Open file for reading,
then close it (use to test for
file existance)
:output Open file for write operations only.
:io Like :output, but reading also allowed.
:element-type FIXNUM or CHARACTER (default is CHARACTER), as returned
by type-of function (on page 87). Files opened with
type FIXNUM are binary
files instead of ascii, which
means no crlf to/from lf conversion takes
place, and
control-Z will not
terminate an input file. It is the
intent of
Common Lisp that
binary files only
be
accessed with
read-byte and write-byte while
ascii
files be accessed with any function but read-byte and
write-byte. XLISP does not
enforce that distinction.
:if-exists action to take if file
exists. Argument ignored for
:input (file is positioned
at start) or :probe (file is
closed)
:error give error message
:rename rename file to generated backup name, then open a new
file of the original name.
This is the default action
:new-version same as :rename
:overwrite file is positioned to start, original data intact
:append file is positioned to end
:supersede delete original file and open new file of the same name
:rename-and-delete same as :supersede
NIL close file and return NIL
:if-does-not-exist action to take if file does not exist.
:error give error message
(default for :input, or :overwrite
or :append)
:create create a new file
(default for :output or :io when not
:overwrite or :append)
NIL return NIL (default for :probe)
returns a file stream, or sometimes NIL
XLISP 2.1g FILE I/O FUNCTIONS Page 80
(close
<stream>) CLOSE A FILE STREAM
The stream becomes a "closed stream." Note that
unbound file streams
are closed automatically during a garbage
collection.
<stream> the stream, which may be a string stream
returns
t if stream closed, NIL if terminal (cannot be closed) or
already closed.
(delete-file
<fname>) DELETE A FILE
<fname> file name string, symbol or a stream opened with OPEN
returns
t if file does not exist or is deleted. If <fname> is a
stream, the stream is closed before the file is
deleted. An
error occurs if the file cannot
be deleted.
(truename
<fname>)
OBTAIN THE FILE PATH NAME
<fname> file name string, symbol, or a stream opened with OPEN
returns
string representing the true file
name (absolute path to
file).
(with-open-file
(<var> <fname> [<karg>...]) [<expr>...])
EVALUATE USING A FILE
Defined in common.lsp as a
macro. File will always be closed
upon
completion
<var> symbol name to bind
stream to while evaluating expresssions
(quoted)
<fname> file name string or symbol
<karg> keyword arguments for the implicit open command
<expr> expressions to evaluate while file is open (implicit progn)
returns
value of last <expr>.
(read-byte
[<stream>[<eofp>[<eof>]]]) READ A BYTE FROM A STREAM
NOTE: New eof arguments are incompatible
with older XLISP versions.
<stream> the input stream (default, or NIL, is *standard-input*, T is
*terminal-io*)
<eofp> When T, signal an error on end of file, when NIL return
<eof> (default is T)
<eof> the value to return on end of file (default is NIL)
returns
the byte (integer) or <eof> at end of file
(write-byte <byte>
[<stream>])
WRITE A BYTE TO A STREAM
<byte> the byte to write (integer)
<stream> the output stream (default,
or NIL, is *standard-output*, T
is *terminal-io*)
returns
the byte (integer)
(file-length
<stream>) GET LENGTH OF FILE
For
an ascii file, the length reported
may be larger than the number
of characters read or written because of
CR conversion.
<stream> the file stream (should be disk file)
returns
length of file, or NIL if cannot be determined.
XLISP 2.1g FILE I/O FUNCTIONS Page 81
(file-position
<stream> [<expr>])
GET OR SET FILE POSITION
For an ascii file, the file position may
not be the same as the number
of characters read or written
because of CR conversion. It
will be
correct
when using file-position to position a
file at a location
earlier reported by file-position.
<stream> the file stream (should be a disk file)
<expr> desired file
position, if setting position. Can
also be
:start for start of file or
:end for end of file.
returns
if setting position, and
successful, then T; if getting
position and successful then
the position; otherwise NIL
XLISP 2.1g STRING STREAM FUNCTIONS Page 82
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 list return a
sting or list of the
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.
Note that there is no difference between unnamed input
and output streams.
Unnamed input streams
may be written to by output functions,
in which case
the characters are
appended to the tail end of the
stream. Unnamed output
streams may also be (destructively) read by any input function as well as
the get-output-stream
functions.
(make-string-input-stream
<str> [<start> [<end>]])
<str> the string
<start> the starting offset
<end> the ending offset + 1 or NIL for end of string
returns
an unnamed stream that reads from the string
(make-string-output-stream)
returns
an unnamed output stream
(get-output-stream-string
<stream>)
The output stream is emptied by this
function
<stream> the output stream
returns
the output so far as a string
(get-output-stream-list
<stream>)
The output stream is emptied by this
function
<stream> the output stream
returns
the output so far as a list
(with-input-from-string
(<var> <str> &key :start :end :index) [<expr>...])
Defined in common.lsp as a macro
<var> symbol that stream
is bound to
during execution of
expressions (quoted)
<str> the string
:start
starting offset into string (default 0)
:end
ending offset + 1 (default, or
NIL, is end of string)
:index
setf place form which gets final
index into string after
last expression is executed
(quoted)
<expr> expressions to evaluate (implicit progn)
returns
the value of the last <expr>
(with-output-to-string
(<var>) [<expr>...])
Defined in common.lsp as a macro
<var> symbol that stream
is bound to
during execution of
expressions (quoted)
<expr> expressions to evaluate (implicit progn)
returns
contents of stream, as a string
XLISP 2.1g DEBUGGING AND ERROR
HANDLING Page 83
DEBUGGING AND ERROR
HANDLING FUNCTIONS
(trace
[<sym>...])
ADD A FUNCTION TO THE TRACE LIST
fsubr
<sym> the function(s) to add (quoted)
returns
the trace list
(untrace
[<sym>...]) REMOVE A FUNCTION FROM THE TRACE LIST
fsubr. If no functions given, all
functions are removed from the trace
list.
<sym> the function(s) to remove (quoted)
returns
the trace list
(error <emsg>
{<arg>})
SIGNAL A NON-CORRECTABLE ERROR
Note
that the definition of this
function has changed from 2.1e and
earlier so to match Common Lisp.
<emsg> the error message string, which is processed by FORMAT
<arg> optional argument{s} for FORMAT
returns
never returns
(cerror <cmsg>
<emsg> {<arg>})
SIGNAL A CORRECTABLE ERROR
Note that the definition of this function has changed from 2.1e and
earlier so to match Common Lisp.
<cmsg> the continue message string, which is processed by FORMAT
<emsg> the error message string, which is processed by FORMAT
<arg> optional argument(s) for both FORMATs (arguments are useable
twice)
returns
NIL when continued from the break loop
(break <bmsg>
{<arg>}) ENTER A BREAK LOOP
Note that the definition of this function
has changed from 2.1e and
earlier so to match Common Lisp.
<bmsg> the break message string, which is processed by FORMAT
<arg> optional argument(s) for FORMAT
returns
NIL when continued from the break loop
(clean-up)
CLEAN-UP AFTER AN ERROR
returns
never returns
(top-level) CLEAN-UP AFTER AN ERROR AND
RETURN TO THE TOP LEVEL
Runs
the function in variable
*top-level-loop* (ususally TOP-LEVEL-
LOOP)
returns
never returns
(continue) CONTINUE FROM
A CORRECTABLE ERROR
returns
never returns
(errset <expr>
[<pflag>]) TRAP ERRORS
fsubr
<expr> the expression to execute
<pflag> flag to control printing of the error message (default t)
returns
the value of the last expression
consed with NIL or NIL on
error
XLISP 2.1g DEBUGGING AND ERROR
HANDLING Page 84
(baktrace
[<n>]) PRINT N
LEVELS OF TRACE BACK INFORMATION
<n> the number of levels (defaults to all levels)
returns
NIL
(evalhook <expr>
<ehook> <ahook> [<env>]) EVALUATE WITH HOOKS
<expr> the expression to evaluate.
<ehook> is not used at the
top
level.
<ehook> the value for *evalhook*
<ahook> the value for *applyhook*
<env> the environment
(default is NIL). The format is
a dotted
pair of value (car) and function (cdr) binding lists. Each
binding list is a list of level binding a-lists,
with the
innermost a-list first. The level binding a-list associates
the bound symbol with its
value.
returns
the result of evaluating the expression
(applyhook <fun>
<arglist> <ehook> <ahook>) APPLY WITH HOOKS
<fun> The function closure. <ahook> is not used for this function
application.
<arglist> The list of arguments.
<ehook> the value for *evalhook*
<ahook> the value for *applyhook*
returns
the result of applying <fun> to <arglist>
(debug)
ENABLE DEBUG BREAKS
(nodebug)
DISABLE DEBUG BREAKS
Defined in init.lsp
XLISP 2.1g SYSTEM FUNCTIONS Page 85
SYSTEM FUNCTIONS
(load <fname>
&key :verbose :print)
LOAD A SOURCE FILE
An
implicit ERRSET exists in this
function so that if error occurs
during
loading, and *breakenable* is NIL, then the error message will
be printed and NIL will be returned.
The OS environmental variable
XLPATH is used as a search path
for files in this function. If the
filename
does not contain path separators
('/' for UNIX, and either
'/' or '\' for MS-DOS)
and XLPATH is defined, then each pathname in
XLPATH is tried in turn until a matching
file is found. If no file is
found,
then one last attempt is
made in the current directory. The
pathnames are separated by either a space
or semicolon, and a trailing
path separator character is optional.
<fname> the filename string,
symbol, or a file stream created
with
OPEN. The extension
"lsp" is assumed.
:verbose
the verbose flag (default is t)
:print
the print flag (default is NIL)
returns
t if successful, else NIL
(restore
<fname>)
RESTORE WORKSPACE FROM A FILE
The OS
environmental variable XLPATH is
used as a search path for
files in this function. See the note
under function "load", above. The
standard
system streams are restored to
the defaults as of
when
XLISP-PLUS was started. Files streams
are restored in the same mode
they were created, if possible, and are positioned where they were at
the time of the save. If the files have
been altered or moved since
the time
of the save, the restore will
not be completely successful.
Memory
allocation will not be the same as
the current settings of
ALLOC are used. Execution proceeds
at the top-level read-eval-print
loop. The state of the
transcript logging is not affected by this
function.
<fname> the filename string,
symbol, or a file stream created
with
OPEN. The extension
"wks" is assumed.
returns
NIL on failure, otherwise never returns
(save
<fname>) SAVE WORKSPACE TO A FILE
You cannot save from within a load. Not all of the state may be saved
-- see "restore", above. By
saving a workspace with the name
"xlisp",
that
workspace will be
loaded automatically when
you invoke
XLISP-PLUS.
<fname> the filename string,
symbol, or a file stream created
with
OPEN. The extension "wks" is assumed.
returns
t if workspace was written, NIL otherwise
(savefun
<fcn>) SAVE FUNCTION TO A FILE
defined in init.lsp
<fcn> function name (saves it to file of same name, with extension
".lsp")
returns
t if successful
(dribble
[<fname>]) CREATE A
FILE WITH A TRANSCRIPT OF A SESSION
<fname> file name string, symbol, or file stream created with OPEN
(if missing, close current
transcript)
returns
t if the transcript is opened, NIL if it is closed
XLISP 2.1g SYSTEM FUNCTIONS Page 86
(gc)
FORCE GARBAGE COLLECTION
returns
NIL
(expand
[<num>])
EXPAND MEMORY BY ADDING SEGMENTS
<num> the number of segments to add, default 1
returns
the number of segments added
(alloc <num>
[<num2>]) CHANGE SEGMENT SIZE
<num> the number of nodes to allocate
<num2> the number of pointer
elements to allocate in
an array
segment (when dynamic array
allocation compiled). Default is
no change.
returns
the old number of nodes to allocate
(room) SHOW
MEMORY ALLOCATION STATISTICS
Statistics (which are sent to
*STANDARD-OUTPUT*) include:
Nodes - number of nodes, free
and used
Free nodes - number of free
nodes
Segments - number of node
segments, including those reserved
for characters and
small integers.
Allocate -
number of nodes to allocate
in any new node
segments
Total - total memory bytes allocated for node segments,
arrays, and strings
Collections - number of garbage
collections
Time - time spent
performing garbage collections
(in
seconds)
When dynamic array allocation is
compiled, the following additional
statistics are printed:
Vector nodes
- number of pointers
in arrays and (size
equivalent) strings
Vector free - free space in vector area (may be fragmented
across segments)
Vector segs
- number of vector
segments. Increases and
decreases as needed.
Vec allocate - number of pointer elements to allocate in any
new vector segment
returns
NIL
(time
<expr>) MEASURE EXECUTION TIME
fsubr.
<expr> the expression to evaluate
returns
the result of the expression.
The execution time is printed
to *TRACE-OUTPUT*
(get-internal-real-time) GET ELAPSED CLOCK
TIME
(get-internal-run-time) GET ELAPSED EXECUTION
TIME
returns
integer time in
system units (see
internal-time-units-per-second
on page 23).
meaning of
absolute values is system
dependent.
XLISP 2.1g SYSTEM FUNCTIONS Page 87
(coerce <expr>
<type>) FORCE
EXPRESSION TO DESIGNATED TYPE
Sequences can be coerced
into other sequences, single
character
strings or symbols with single
character printnames can be coerced
into characters, fixnums can be coerced into characters or
flonums.
Ratios can be coerced into flonums.
Flonums and ratios can be coerced
into complex (so can fixnums, but they
turn back into fixnums).
<expr> the expression to coerce
<type> desired type, as returned by type-of (see page 87)
returns
<expr> if type is correct, or converted object.
(type-of
<expr>)
RETURNS THE TYPE OF THE EXPRESSION
It is recommended that typep be used instead, as it is more general.
In the original XLISP, the value NIL was
returned for NIL.
<expr> the expression to return the type of
returns
One of the symbols:
LIST for NIL (lists, conses return CONS)
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
RATIO for ratios
FLONUM for floating point numbers
COMPLEX for complex numbers
CHARACTER for characters
FILE-STREAM for file pointers
UNNAMED-STREAM for unnamed streams
ARRAY for arrays
HASH-TABLE for hash tables
sym for structures of type "sym"
(peek
<addrs>)
PEEK AT A LOCATION IN MEMORY
<addrs> the address to peek at (integer)
returns
the value at the specified address (integer)
(poke <addrs>
<value>)
POKE A VALUE INTO MEMORY
<addrs> the address to poke (integer)
<value> the value to poke into the address (integer)
returns
the value
(address-of
<expr>) GET
THE ADDRESS OF AN XLISP NODE
<expr> the node
returns
the address of the node (integer)
(get-key) READ A
KEYSTROKE FROM CONSOLE
OS dependent.
returns
integer value of key (no echo)
XLISP 2.1g SYSTEM FUNCTIONS Page 88
(system
<command>) EXECUTE A SYSTEM COMMAND
OS dependent -- not always available.
<command> Command string, if 0
length then spawn OS shell
returns
T if successful (note that MS/DOS command.com always returns
success)
(set-stack-mark
<size>) SET
SYSTEM STACK WARNING POINT
OS
dependent -- not always available. The system will perform
a
continuable error when the amount
of remaining system stack passes
below this setting. The trap is
reset at the top-level. This function
is useful for debugging runaway recursive
functions.
<size> Remaining stack, in
bytes. Minimum value is fixed
at the
value that causes the system
stack overflow error, while the
maximum value is limitied to
somewhat less than the current
remaining stack space. Use
"0" to turn the warnings off.
returns
the previous value.
(top-level-loop) DEFAULT
TOP LEVEL LOOP
Runs
the XLISP top level read-eval-print loop, described earlier.
Never returns.
(reset-system)
FLUSH INPUT BUFFERS
Used by user-implemented top level loops
to flush the input buffer
returns
NIL
(exit) EXIT
XLISP
returns
never returns
(generic
<expr>) CREATE A
GENERIC TYPED COPY OF THE EXPRESSION
Note: added function, Tom Almy's creation
for debugging xlisp.
<expr> the expression to copy
returns
NIL if value is NIL and NILSYMBOL compilation option not
declared, otherwise if type is:
SYMBOL copy as an ARRAY
OBJECT copy as an ARRAY
CONS (CONS (CAR <expr>)(CDR <expr>))
CLOSURE copy as an ARRAY
STRING copy of the string
FIXNUM value
FLONUM value
RATIO value
CHARACTER value
UNNAMED-STREAM
copy as a CONS
ARRAY copy of the array
COMPLEX copy as an ARRAY
HASH-TABLE copy as an ARRAY
structure copy as an ARRAY
(eval-when
<condition> <body> ...)
Macro
defined in common.lsp, and provided to assist in porting Common
Lisp applications to XLISP-PLUS.
<condition> List of conditions
<body> expressions which are evaluated if one of the conditions is
EXECUTE or LOAD.
returns
result of last body expression
XLISP 2.1g SYSTEM FUNCTIONS Page 89
The following graphic
and display functions represent an
extension by Tom
Almy:
(cls) CLEAR
DISPLAY
Clear the display and position cursor at
upper left corner.
returns
nil
(cleol)
CLEAR TO END OF LINE
Clears current line to end.
returns
nil
(goto-xy
[<column> <row>]) GET OR SET CURSOR POSITION
Cursor
is repositioned if
optional arguments are
specified.
Coordinates are clipped to actual size of
display.
<column> 0-based column (x coordinate)
<row> 0-based row (y coordinate)
returns
list of original column and row positions
(color
<value>) SET DRAWING COLOR
<value> Drawing color (not checked for validity)
returns
<value>
(move <x1>
<y1> [<x2> <y2> ...]) ABSOLUTE MOVE
(moverel <x1>
<y2> [<x2> <y2> ...]) RELATIVE MOVE
For moverel, all coordinates are relative
to the preceeding point.
<x1> <y1> Moves to point
x1,y1 in anticipation of draw.
<x2> <y2> Draws to points
specified in additional arguments.
returns
T if succeeds, else NIL
(draw [<x1>
<y1> ...]) ABSOLUTE DRAW
(drawrel [<x1>
<y1> ...]) RELATIVE DRAW
For drawrel, all coordinates are relative
to the preceeding point.
<x1> <y1> Point(s) drawn to,
in order.
returns
T if succeeds, else NIL
XLISP 2.1g SYSTEM FUNCTIONS Page 90
(mode <ax>
[<bx> <width> <height>) SET DISPLAY MODE
Standard modes require only <ax> argument. Extended modes are "Super-
VGA" or "Super-EGA"
and are display card
specific. Not all XLISP
versions support all modes.
<ax> Graphic mode (value passed in register AX)
Common standard Modes:
0,1 - 40x25 text
2,3 - 80x25 text
4,5 - 320x200 4 color graphics
(CGA)
6 - 640x200 monchrome graphics
(CGA)
13 - 320x200 16 color graphics
(EGA)
14 - 640x200 16 color graphics
(EGA)
16 - 640x350 16 color graphics
(EGA)
18 - 640x480 16 color graphics
(VGA)
19 - 320x200 256 color graphics
(VGA)
<bx> BX value for some extended graphic modes
<width> width for extended graphic modes
<height> height for extended graphic modes
returns
a list of the number
of columns, number of lines (1 for
CGA), maximum X graphic coordinate (-1 for text modes),
and
the maximum Y graphic
coordinate (-1 for text modes), or NIL
if fails
XLISP 2.1g ADDITIONAL FUNCTIONS Page 91
ADDITIONAL FUNCTIONS
AND UTILITIES
STEP.LSP
This file contains a simple Lisp single-step debugger. It started as an
implementation of the
"hook" example in
chapter 20 of Steele's "Common
Lisp". This
version was brought up on Xlisp 1.7 for the Amiga, and then on
VAXLISP.
When the package
feature is compiled in, the debugger is in the TOOLS
package.
To invoke: (step
(whatever-form with args))
For each
list (interpreted function
call), the stepper
prints the
environment and the
list, then enters a read-eval-print loop. At this point
the available commands
are:
(a
list)<CR> evaluate the list
in the current environment, print the
result, and repeat.
<CR> step into the called function
anything_else<CR> step over the called function.
If the stepper comes
to a form that is not a list it prints the form and
the value, and
continues on without stopping.
Note that stepper
commands are executed in the current environment. Since
this is the case, the stepper commands can change
the current environment.
For example, a SETF will change an environment variable
and thus can alter
the course of
execution.
Global variables -
newline, *hooklevel*
Functions/macros -
while step eval-hool-function step-spaces step-flush
Note -- an even more
powerful stepper package is in
stepper.lsp (documented
in stepper.doc).
XLISP 2.1g ADDITIONAL FUNCTIONS Page 92
PP.LSP
In addition to
the pretty-printer itself,
this file contains
a few
functions that
illustrate some simple but useful applications.
When the package feature is compiled in, these funtions are in the TOOLS
package.
(pp <object>
[<stream>])
PRETTY PRINT EXPRESSION
(pp-def <funct>
[<stream>])
PRETTY PRINT FUNCTION/MACRO
(pp-file <file>
[<stream>])
PRETTY PRINT FILE
<object> The expression to print
<funct> Function to print (as DEFUN or DEFMACRO)
<file> File to print (specify either as string or quoted symbol)
<stream> Output stream (default is *standard-output*)
returns
T
Global variables:
tabsize maxsize miser-size min-miser-car max-normal-car
Functions/Macros:
sym-function pp-file pp-def make-def pp pp1 moveto spaces
pp-rest-across pp-rest printmacrop
pp-binding-form pp-do-form
pp-defining-form
pp-pair-form
See the source file
for more information.
XLISP 2.1g ADDITIONAL FUNCTIONS Page 93
INSPECT.LSP
INSPECT..LSP
contains an XLISP editor/inspector.
When the package feature
is compiled in, the
editor is in the TOOLS package.
Execute
(ins
'symbol) to edit a symbol.
(insf
symbol) to edit the
function binding of a
symbol (allows
changing the
argument list or function
type, lambda or
macro).
The editor alters the current selection by
copying so that aborting all
changes is generally
posible; the exception is when editing
a closure, if
the closure is backed out
of, the change is permanent.
Also, naturally,
changing the
values of structure elements, instance
variables, or symbols
cannot be undone.
For all commands taking a numeric argument,
the first element of the
selection is the 0th
(as in NTH function).
Do not create
new closures, because the environment will be incorrect.
Closures become LAMBDA or MACRO expressions
as the selection. Only the
closure body
may be changed; the argument
list cannot be successfully
modified, nor can the
environment.
For class objects, the class variables, methods and message names can be
modified. For instance objects, instance variables can
be examined (if the
object under-stands the message
:<ivar> for the particular
ivar), and
changed (if :SET-IVAR
is defined for that class, as it is if CLASSES.LSP is
used). Structure
elements can be examined and changed.
(command list on next
page)
XLISP 2.1g ADDITIONAL FUNCTIONS Page 94
COMMANDS (all
"hot keyed and case sensitive"):
?
List available commands
A
select the CAR of the current selection.
D
select the CDR of the current selection.
e n
select ("Edit") element n
r n x
Replaces element n with x.
X
eXit, saving all changes
Q
Quit, without saving changes
b
go Back one level (backs up A, D or e commands)
B n
go Back n levels.
l
List selection using
pprint; if selection is symbol, give
short description
v
Verbosity toggle
. n
change maximum print length (default 10)
# n
change maximum print depth (default 3)
! x
evaluates x and prints
result, the symbol tools:@ is bound
to the selection
R x
Replaces the selection with
evaluated x, the symbol tools:@
is bound to the selection
ADDITIONAL
COMMANDS (selection is a list or
array):
( n m
inserts parenthesis starting
with the nth element, for
m
elements.
) n
removes parenthesis
surrounding nth element of selection,
which may be array or list
[ n m
as in (, but makes elements into an array
i n x
Inserts x before nth element in selection.
d n
Deletes nth element in selection.
S x y
Substitute all occurances of
y with x in selection (which
must be a list). EQUAL is used for the comparison.
XLISP 2.1g BUG FIXES AND EXTENSIONS Page 95
BUG FIXES AND
EXTENSIONS
In this section, CL
means "Common Lisp compatible to
the extent possible".
CX means
"now works with complex numbers". CR
means "now works with
ratios". *
means "implemented in
LISP rather than
C". # means
"implementation
moved from LISP to C".
Bug Fixes
RESTORE did not work -- several bugs for 80x86 systems. Only one restore
would work per session
-- all systems.
:downcase for variable
*printcase* did not work with some compilers.
Modifications to make
the source acceptable to ANSI C compilers.
Values for ADEPTH and EDEPTH changed to more reasonable values -- before
this change the
processor stack would overflow first, causing a crash.
On systems with 16 bit
integers: STRCAT crashes
when aggregate size of
argument strings were greater than 32k. MAKE-ARRAY crashes
on too-large
arrays. DOTIMES, AREF, AREF
and NTH place
forms of SETF,
MAKE-STRING-INPUT-STREAM and
GET-OUTPUT-STREAM-STRING
treat numeric
argument modulo
65536.
MAKE-STRING-INPUT-STREAM
did not check
for
start>end.
Strings containing
nulls could not be read or printed.
NTH and NTHCDR failed
for zero length lists.
Unnamed streams did
not survive garbage collections.
(format nil ...) did
not protect from garbage collection the unnamed stream
it creates.
SORT did not protect
some pointers from garbage collection.
SYMBOL-NAME
SYMBOL-VALUE SYMBOL-PLIST BOUNDP and FBOUNDP failed with symbol
NIL as argument.
LAST returned wrong
value when its argument list ended with a dotted pair.
*gc-hook* was
not rebound to NIL during
execution of gchook function,
causing potential
infinite recursion and crash.
Executing RETURN from
within a DOLIST or DOTIMES caused the
environment to
be wrong.
When errors occured
during loading, which were not
caught, the file would
be left open.
EVAL and LOAD did not use global environment. EVALHOOK's
default environment
was not global.
XLISP 2.1g BUG FIXES AND EXTENSIONS Page 96
Invalid symbols (those
containing control characters, for instance), can no
longer be created with
intern and make-symbol.
The key T,
meaning "otherwise" in the
CASE function used to be allowed in
any position. Now it
only means "otherwise" when used as the last case.
The lexical and functional environment of send
of :answer (which defines a
new method) are now used during the method's evaluation, rather than the
global environment.
Signatures added for
WKS files so that invalid ones will be rejected.
Checks added for file
names and identifier names being too long.
Indexing code fixed to
allow almost 64k long strings in 16 bit
systems. It
is no longer
possible to allocate arrays or strings
that are too long for
the underlying system.
Circularity checks added to PRINT LAST BUTLAST
LENGTH MEMBER and MAP
functions. An error is produced for all but MEMBER, which will execute
correctly.
Code for SETF modified so that a Common Lisp compatible DEFSETF could be
used.
Circularity checks
added to EQUAL.
Check for even number of arguments to SETQ, SETF, and PSETQ added. PSETQ
changed to return NIL
rather than result of first assignment (really now!).
User Interface
Changes
-w command line
argument to specify alternate or no workspace.
-b command line
argument for batch operation.
-? command line
argument gives usage message.
init.lsp not loaded if
workspace loaded.
Search path can be
provided for workspaces and .lsp files.
Standard input and output
can be redirected.
*TERMINAL-IO* stream added
which is always bound
to console (stderr).
Non-error messages
are sent to
*DEBUG-IO* so they
don't clutter
*STANDARD-OUTPUT*
Results of evaluations
are printed on a fresh line rather than
at the end
of the preceeding line
(if any). This enhances readability.
Display writes are
buffered.
Character literals
available for all 256 values. CL
XLISP 2.1g BUG FIXES AND EXTENSIONS Page 97
Uninterned symbols
print with leading #:. CL
PRIN1 generates
appropriate escape sequences
for control and
meta
characters in strings.
CL
Read macro #. added.
CL
Lisp code for nested
backquote macros added. CL
Read macro #C added
for complex numbers. CL
Semantics for #S
read macro changed so that it
can read in structures
written by PRINT. CL
PRINT of file streams
shows file name, or "closed" if a closed file stream.
*PRINT-CASE* now
applies to PRINC. CL
Added
*READTABLE-CASE* to control case
conversion on input and output,
allowing case
sensitive code. CL-like
Reader macros #+ and
#- added, along with global variable *FEATURES*. CL
Added optional
and OS dependent checking of system stack overflow, with
checks in READ,
PRINT, EVAL, and in the garbage collector. Added a new
function SET-STACK-MARK which performs a
continuable error when
the
remaining stack space
drops below a preset amount.
Improved command line editing, symbol name
lookup, and history (command
recall) for MS-DOS.
*PRINT-CASE* can now
be :CAPITALIZE. CL
Packages added.
New/Changed Data
Types
NIL -- was treated as
a special case, now just a normal symbol.
symbols -- value
binding can optionally be constant or special. "*unbound*"
is no longer a symbol so does not have to
be specially treated.
ratio numbers -- new
type.
complex numbers -- new
type, can be integer or real.
character strings --
The ASCII NUL (code 0) is now a valid character.
objects -- objects of
class Class have a new instance variable which is the
print name of the class.
hash-table -- new
type, close to CL
random-state -- new
type, CL
Property list
properties are no longer limited to just symbols CL
Multiple value returns
added where appropriate
Packages added where
appropriate
New Variables and
Constants
*apply-hook* Now activated
*command-line*
XLISP 2.1g BUG FIXES AND EXTENSIONS Page 98
*displace-macros*
Macros are replaced with their expansions when possible
*dos-input* MSDOS only, uses
DOS interface to interact with user.
Allows recall of earlier command(s).
*load-file-arguments*
*print-level* CL
*print-length* CL
*random-state* CL
*ratio-format*
*readtable-case*
CL-like
*startup-functions*
*terminal-io* CL
*top-level-loop*
internal-time-units-per-second
CL
pi CL
New functions
ACONS CL*
ACOSH CL*
ADJOIN CL
ALPHA-CHAR-P CL
APPLYHOOK CL
APROPOS CL*
APROPOS-LIST CL*
ASH CL
ASINH CL*
ATANH CL*
BUTLAST CL
CEILING CL
CIS CL*
CLREOL (clear to end
of line -- MS/DOS only)
CLRHASH CL
CLS (clear screen --
MS/DOS only)
COERCE CL
COLOR (graphics --
MS/DOS only)
COMPLEMENT CL
COMPLEX CL
COMPLEXP CL
CONCATENATE CL
CONJUGATE CL
CONSTANTP CL
COPY-ALIST CL*
COPY-LIST CL*
COPY-TREE CL*
COSH CL*
COUNT-IF CL except no
:from-end
DECF CL*
DECLARE *
DEFCLASS * (define a
new class)
DEFINST * (define a
new instance)
DEFMETHOD * (define a
new method)
DEFPACKAGE CL*
DEFSETF CL*
DELETE-FILE CL
XLISP 2.1g BUG FIXES AND EXTENSIONS Page 99
DELETE-PACKAGE CL
DENOMINATOR CL
DO-ALL-SYMBOLS CL*
DO-EXTERNAL-SYMBOLS
CL*
DO-SYMBOLS CL*
DRAW (graphics --
MS/DOS only)
DRAWREL (graphics --
MS/DOS only)
ELT CL
EQUALP CL*
EVAL-WHEN *
EVERY CL
EXPORT CL
FILE-LENGTH CL
FILE-POSITION CL
FILL CL*
FIND-ALL-SYMBOLS CL
FIND-IF CL except no
:from-end
FIND-PACKAGE CL
FLOOR CL
FRESH-LINE CL
FUNCTIONP CL*
GENERIC
(implementation debugging function)
GET-INTERNAL-REAL-TIME
CL
GET-INTERNAL-RUN-TIME
CL
GETF CL
GETHASH CL
GOTO-XY (position
cursor -- MS/DOS only)
HASH-TABLE-COUNT CL
IDENTITY CL
IMAGPART CL
IMPORT CL
INCF CL*
IN-PACKAGE CL
INPUT-STREAM-P CL
INTERSECTION CL
LCM CL
LIST* CL
LIST-ALL-PACKAGES CL
LIST-LENGTH CL
LOG CL
LOGTEST CL*
MAKE-HASK-TABLE CL
MAKE-PACKAGE CL
MAKE-RANDOM-STATE CL
MAP CL
MAP-INTO CL
MAPHASH CL
MARK-AS-SPECIAL
MODE (graphics -- MS/DOS
only)
MOVE (graphics --
MS/DOS only)
MOVEREL (graphics --
MS/DOS only)
MULTIPLE-VALUE-BIND
CL*
MULTIPLE-VALUE-CALL CL
MULTIPLE-VALUE-LIST
CL*
MULTIPLE-VALUE-PROG1
CL
XLISP 2.1g BUG FIXES AND EXTENSIONS Page 100
MULTIPLE-VALUE-SETQ
CL*
NINTERSECTION CL*
NTH-VALUE
NOTANY CL
NOTEVERY CL
NREVERSE CL
NSET-DIFFERENCE CL*
NSET-EXCLUSIVE-OR CL*
NSTRING-CAPITALIZE CL
NUMERATOR CL
NUNION CL*
OPEN-STREAM-P CL
OUTPUT-STREAM-P CL
PACKAGE-NAME CL
PACKAGE-NICKNAMES CL
PACKAGE-OBARRAY
PACKAGE-SHADOWING-SYMBOLS
CL
PACKAGE-USED-BY-LIST
CL
PACKAGE-USE-LIST CL
PACKAGE-VALID-P
PAIRLIS CL*
PHASE CL
POP CL*
POSITION-IF CL except
no :from-end
PROCLAIM *
PSETF CL
PUSH CL*
PUSHNEW CL*
RATIONAL CL
RATIONALP CL
REALPART CL
REDUCE CL except no
:from-end
REMF CL*
REMHASH CL
REMOVE-DUPLICATES CL
except no :from-end
RENAME-PACKAGE CL
REPLACE CL*
RESET-SYSTEM
ROUND CL
SEARCH CL except no
:from-end
SET-DIFFERENCE CL
SET-EXCLUSIVE-OR CL*
SET-STACK-MARK
SETF Placeform
ELT CL
SETF Placeform GETF CL
SETF Placeform
GETHASH CL
SETF Placeform SEND*
(set instance variable)
SHADOW CL
SHADOWING-IMPORT CL
SIGNUM CL*
SINH CL*
SOME CL
SPECIALP CL
STRING-CAPITALIZE CL
SUBSETP CL
XLISP 2.1g BUG FIXES AND EXTENSIONS Page 101
SYMBOL-PACKAGE CL
TANH CL*
TIME CL
TOP-LEVEL-LOOP
TRUENAME CL
TYPEP CL
UNEXPORT CL
UNINTERN CL*
UNION CL
UNUSE-PACKAGE CL
USE-PACKAGE CL
VALUES CL
VALUES-LIST CL
WITH-INPUT-FROM-STRING
CL*
WITH-OPEN-FILE CL*
WITH-OUTPUT-TO-STRING
CL*
Y-OR-N-P CL*
YES-OR-NO-P CL*
Changed functions
&ALLOW-OTHER-KEYS
CL (now functions, is no longer ignored)
:ALLOW-OTHER-KEYS CL
* CL CR CX (with no
arguments, returns 1)
+ CL CR CX (with no
arguments, returns 0)
- CL CR CX
/ CL CR CX
1+ CL CR CX
1- CL CR CX
ABS CL CR CX
ACOS CL CR CX
ALLOC (new optional
second argument)
APPLY CL (allows
multiple arguments)
AREF CL (now works on
strings)
ASIN CL CR CX
ASSOC CL (added :key)
ATAN CL CR CX (second
argument now allowed)
BREAK CL
CERROR CL
CHAR-CODE CL (parity
bit is stripped)
CLOSE CL (will close
unnamed stream strings)
COS CL CR CX
DEFCONSTANT CL# (true
constants)
DEFPARAMETER CL# (true
special variables)
DEFSTRUCT (added
option :print-function, comment field)
DEFVAR CL# (true
special variables)
DELETE (added keywords
:key :start :end. Works on arrays and strings)
DELETE-IF (added
keywords :key :start :end. Works on arrays and strings)
DELETE-IF-NOT (added
keywords :key :start
:end. Works on arrays
and
strings)
ERROR CL
EXP CL CR CX
EXPT CL CR CX
FMAKUNBOUND #
XLISP 2.1g BUG FIXES AND EXTENSIONS Page 102
FORMAT (added directives # ~D ~E ~F ~G ~O ~X ~& ~* ~? ~| ~( ~[ ~{ ~T ~\N
and lowercase directives)
GET CL
HASH (hashes
everything, not just symbols or strings)
LOAD CL (uses path to
find file, allows file stream for name argument)
LOGAND CL (with no
arguments, returns -1)
LOGIOR CL (with no
arguments, returns 0)
LOGXOR CL (with no
arguments returns 0)
MAKE-ARRAY (added
keywords :initial-contents and :initial-element)
MAKE-STRING-INPUT-STREAM
CL (:end NIL means end of string)
MAKUNBOUND #
MAPCAN #
MAPCON #
MEMBER CL (added :key)
NSTRING-DOWNCASE CL
(string argument can be symbol, :end
NIL means end of
string)
NSTRING-UPCASE CL
(string argument can be symbol, :end NIL means end of
string)
NSUBLIS CL
NSUBST CL
NSUBST-IF CL
NSUBST-IF-NOT CL
OPEN CL (many
additional options, as in Common Lisp)
PEEK (fixnum sized
location is fetched)
PEEK-CHAR CL (input
stream NIL is *standard-input*, T is *terminal-io*)
POKE (fixnum sized
location is stored)
PPRINT (output stream
NIL is *standard-output*, T is *terminal-io*)
PRIN1 CL (output
stream NIL is *standard-output*, T is *terminal-io*)
PRINC CL (output
stream NIL is *standard-output*, T is *terminal-io*)
PRINT (output stream
NIL is *standard-output*, T is *terminal-io*)
RANDOM CL (works with
random-states)
READ (input
stream NIL is
*standard-input*, T is *terminal-io*, eof
arguments)
READ-BYTE CL (input
stream NIL is *standard-input*, T is *terminal-io*, eof
arguments)
READ-CHAR CL (input
stream NIL is *standard-input*, T is *terminal-io*, eof
arguments)
READ-LINE CL (input
stream NIL is *standard-input*, T is *terminal-io*, eof
arguments)
REM CR CL (only two
arguments now allowed, may be floating point)
REMOVE (added keywords
:key :start :end. Works on arrays and strings)
REMOVE-IF (added
keywords :key :start :end. Works on arrays and strings)
REMOVE-IF-NOT (added
keywords :key :start :end.
Works on arrays
and
strings)
RESTORE (uses path to
find file, restores file streams, fine name
argument
may be file stream)
REVERSE CL (works on
arrays and strings)
ROUND CL (rounds to
nearest even)
SAVE (file name
argument may be file stream)
SIN CL CR CX
SORT (added :key) CL
(with most compilers)
SQRT CL CR CX
STRCAT * (now a macro,
use of CONCATENATE is recommended)
STRING-comparisonFunctions
CL (string arguments can be symbols)
XLISP 2.1g BUG FIXES AND EXTENSIONS Page 103
STRING-DOWNCASE CL
(string argument can be symbol, :end NIL means end of
string)
STRING-LEFT-TRIM CL
(string argument can be symbol)
STRING-RIGHT-TRIM CL
(string argument can be symbol)
STRING-TRIM CL (string
argument can be symbol)
STRING-UPCASE CL (string
argument can be symbol,
:end NIL means end of
string)
SUBLIS CL (modified to
do minimum copying)
SUBSEQ CL (works on
arrays and lists)
SUBST CL (modified to
do minimum copying)
TAN CL CR CX
TERPRI CL (output
stream NIL is *standard-output*, T is *terminal-io*)
TRUNCATE CR CL (allows
denominator argument)
TYPE-OF (returns HASH-TABLE for hashtables,
COMPLEX for complex, and LIST
for NIL)
UNTRACE CL (with no
arguments, untraces all functions)
VALUES CL
VALUES-LIST CL
WRITE-BYTE CL (output
stream NIL is *standard-output*, T is *terminal-io*)
WRITE-CHAR CL (output
stream NIL is *standard-output*, T is *terminal-io*)
New messages for class
Object
:prin1 <stream>
:superclass *
:ismemberof
<cls> *
:iskindof <cls>
*
:respondsto
<selector> *
:storeon (returns form
that will create a copy of the object) *
New messages for class
Class
:superclass *
:messages *
:storeon (returns form
that will recreate class and methods) *
XLISP 2.1g EXAMPLES Page 104
EXAMPLES: 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
give an error (or if a second nil argument is specified,
will return nil or whatever value was supplied as the
third 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.
XLISP 2.1g EXAMPLES Page 105
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 :if-exists :supersede))
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 nil) (read fp nil)))
((null ex) (close fp) nil)
(print ex))
The file will be
closed with the next garbage collection.
XLISP 2.1g INDEX Page 106
INDEX
:allow-other-keys 17 :start
40-43, 55, 56, 81
:answer 21 :start1 40, 43, 56
:append 79 :start2 40, 43, 56
:capitalize 14 :storeon
20, 21
:class 20 :superclass 20, 21
:conc-name 59 :supersede 79
:constituent 12 :test
29, 37, 40-43,
:create 79 45-47, 65
:direction 79 :test-not 29, 40-43,
:downcase 14 45-47, 65
:element-type 79 :tmacro
12
:end 40-43, 55, 56, 81 :upcase 14
:end1 40, 43, 56 :use
33
:end2 40, 43, 56 :verbose
85
:error 79 :white-space 12
:external 30, 33 +
24, 49
:if-does-not-exist 79 ++ 24
:if-exists 79 +++
24
:include 59 -
24, 50
:inherited 30, 33
* 24, 50
:initial-contents 38 ** 24
:initial-element 38 *** 24
:initial-value 43 *applyhook*
8, 23
:input 79 *breakenable* 4, 23
:internal 30, 33 *command-line* 24
:invert 14 *debug-io* 23
:io 79 *displace-macros* 7, 24
:iskindof 20 *dos-input* 3, 24
:ismemberof 20 *error-output* 23
:isnew 20, 21 *evalhook* 8, 23
:key 29, 40-43, 45-48, 65 *features* 13, 24
:mescape 12 *float-format* 24, 73
:messages 21 *gc-flag* 23
:new 21 *gc-hook* 8, 23
:new-version 79 *integer-format* 24, 73
:nicknames 33 *load-file-arguments* 2, 24
:nmacro 12 *obarray* 23
:output 79 *package* 23
:overwrite 79 *print-case* 14, 24, 73
:preserve 14 *print-length* 24, 73
:prin1 20 *print-level* 24, 73
:print 85 *random-state* 24
:print-function 59 *ratio-format* 24, 73
:probe 79 *read-suppress* 24
:rename 79 *readtable-case* 14, 24, 73
:rename-and-delete 79 *readtable*
12, 23
:respondsto 20 *standard-input* 23
:sescape 12 *standard-output* 23
:set-ivar 61 *startup-functions* 2, 24
:set-pname 61 *struct-slots* 59
:show 20 *terminal-io* 23
:size 37 *top-level-loop* 24
XLISP 2.1g INDEX Page 107
*trace-output* 23
char 57
*tracelimit* 4, 23 char-code
57
*tracelist* 23 char-downcase 57
*tracenable* 4, 23 char-equal
58
/ 50 char-greaterp 58
/= 53 char-int 58
< 53 char-lessp 58
<= 53 char-not-equal 58
= 53 char-not-greaterp 58
> 53 char-not-lessp 58
>= 53 char-upcase 57
&allow-other-keys 17 char/=
58
&aux 17 char< 58
&key 17 char<= 58
&optional 17 char=
58
&rest 17 char> 58
1+ 50 char>= 58
1- 50 CHARACTER 87
abs 50 characterp 64
acons 44
cis 52
acos 51 class 23
acosh 51 classp 64
address-of 87 clean-up
3, 83
adjoin 47 clean-up, 4
alloc 86 close 80
alpha-char-p 57 CLOSURE
87
and 66, 67 clrhash 37
append 44 cls
89
apply 25 code-char 57
applyhook 8, 84 coerce
87
apropos 32 color
89
apropos-list 32 comma
25
aref 28, 38 comma-at 26
ARRAY 87 complement 25
arrayp 64 complex 52, 87
ash 54 complexp 64
asin 51 concatenate 39
asinh 51 cond 67
assoc 45 conjugate 53
atan 51 cons 44, 87
atanh 51 consp 63
atom 63, 66 constantp 63
backquote 25 continue 3, 4, 83
baktrace 84 copy-alist 46
block 71 copy-list 46
both-case-p 57 copy-tree
46
boundp 64 cos
51
break 83 cosh 51
butlast 44 count 41
car 28, 44 count-if 41
case 68 count-if-not 41
catch 68 cxxr 44
cdr 28, 44 cxxxr
44
ceiling 49 cxxxxr 44
cerror 83 debug 84
XLISP 2.1g INDEX Page 108
decf 30 find-all-symbols 33
declare 31 find-if 41
defclass 61 find-if-not 41
defconstant 31 find-package 33
definst 62 find-symbol 33
defmacro 30 first
44
defmethod 61 FIXNUM
87
defpackage 32 flatc
74
defparameter 31 flatsize
74
defsetf 29 flet
68
defstruct 59 float
49
defun 30 floatp 63
defvar 31 FLONUM 87
delete 42 floor 49
delete-file 80 fmakunbound 31
delete-if 42 format
75
delete-if-not 42 fourth
44
delete-package 32 fresh-line
74
denominator 52 FSUBR
87
digit-char 57 funcall
25
digit-char-p 57 function
25, 66
do 70 functionp
65
do-all-symbols 33 gc 86
do-external-symbols 33 gcd 51
do-symbols 33 generic
88
do* 70 gensym 30
dolist 70 get
28, 36
dotimes 70 get-internal-real-time 86
draw 89 get-internal-run-time 86
drawrel 89 get-key 87
dribble 85 get-lambda-expression 26
elt 28, 39 get-macro-character 73
endp 63 get-output-stream-list 82
eq 65 get-output-stream-string 82
eql 65 getf 36
equal 65 gethash 28, 37
equalp 65 go
71
error 83 goto-xy 89
errset 4, 83 hash
30
eval 25 HASH-TABLE 87
eval-when 88 hash-table-count 37
evalhook 8, 84 identity
25
evenp 65 if
67
every 39 imagpart 52
exit 88 import 33
exp 52 in-package 33
expand 86 incf
30
export 33 input-stream-p 64
expt 52 int-char 58
fboundp 64 integerp 63
file-length 80 intern
30
file-position 81 internal-time-units-per-second
FILE-STREAM 87 23
fill 43 intersection 47
find 41 labels 68
XLISP 2.1g INDEX Page 109
lambda 26 NIL
23
last 44 nintersection 47
lcm 51 nodebug 84
length 39 not
63, 66
let 68 notany 39
let* 68 notevery 39
list 44, 66, 87 nreverse
39
list-all-packages 33 nset-difference
47
list-length 44 nset-exclusive-or 47
list* 44 nstring-capitalize 56
listp 63 nstring-downcase 56
load 85 nstring-upcase 55
log 52 nsubst 46
logand 54 nsubst-if 48
logior 54 nsubst-if-not 48
lognot 54 nth
28, 45
logtest 54 nth-value 27
logxor 54 nthcdr 45
loop 70 null 63, 66
lower-case-p 57 NUMBER
66
macroexpand 26 numberp 63
macroexpand-1 26 numerator
52
macrolet 68 nunion
47
make-array 38 object
23, 66, 87
make-hash-table 37 objectp
64
make-package 33 oddp
65
make-random-state 51 open 79
make-string-input-stream 82 open-stream-p
64
make-string-output-stream 82
or 66, 67
make-symbol 30 output-stream-p 64
makunbound 31 package-name 34
map 39 package-nicknames 34
map-into 39 package-obarray 34
mapc 45 package-shadowingsymbols 34
mapcan 45 package-use-list 34
mapcar 45 package-used-by-list 34
mapcon 46 package-valid-p 34
maphash 37 pairlis 46
mapl 45 peek 87
maplist 45 peek-char 78
mark-as-special 31 phase
53
max 50 pi 23
member 45, 66 plusp
65
min 50 poke 87
minusp 65 pop
29
mod 50 position 42
mode 90 position-if 42
move 89 position-if-not 42
moverel 89 pp 92
multiple-value-bind 27 pprint 74
multiple-value-call 27 prin1 73
multiple-value-list 27 princ 74
multiple-value-prog1 27 print 73
multiple-value-setq 27 proclaim
31
nconc 48 prog 71
XLISP 2.1g INDEX Page 110
prog* 71 setf 28
prog1 71 setq 28
prog2 72 shadow 34
progn 72 shadowing-import 34
progv 71 signum 51
psetf 29 sin
51
psetq 28 sinh 51
push 29 some 39
pushnew 29 sort
40
putprop 36 specialp 63
quote 25 sqrt 52
random 51 step
91
RATIO 87
strcat
56
rational 49, 66 STREAM
66
rationalp 64 streamp
64
read 73 string 55, 87
read-byte 80 string-capitalize 55
read-char 78 string-downcase 55
read-line 78 string-equal 56
realpart 52 string-greaterp 56
reduce 43 string-left-trim 55
rem 50
string-lessp
56
remf 36 string-not-equal 56
remhash 37 string-not-greaterp 56
remove 40 string-not-lessp 56
remove-duplicates 43 string-right-trim 55
remove-if 40 string-trim 55
remove-if-not 40 string-upcase 55
remprop 36 string/= 56
rename-package 34 string<
56
repair 93 string<= 56
repairf 93 string= 56
replace 43 string> 56
reset-system 88 string>= 56
rest 44 stringp 64
restore 85 STRUCT 66
return 71 sublis 46
return-from 71 SUBR
87
reverse 39 subseq 40
room 86 subsetp 65
round 49 subst 46
rplaca 48 SYMBOL 87
rplacd 48 symbol-function 28, 30
satisfies 66 symbol-name 30
save 85 symbol-package 34
search 40 symbol-plist 28, 30
second 44 symbol-value 28, 30
self 19, 23 symbolp 63
send 19, 28, 61 system
88
send-super 19, 61 t 23
set 28 tagbody 71
set-difference 47 tan
51
set-exclusive-or 47 tanh 51
set-macro-character 73 terpri 74
set-stack-mark 88 third
44
XLISP 2.1g INDEX Page 111
throw 68
time 86
top-level 3, 83
top-level-loop 2, 88
trace 83
truename 80
truncate 49
type-of 87
typep 66
unexport 35
union 47
unless 67
UNNAMED-STREAM 87
untrace 83
unuse-package 35
unwind-protect 69
upper-case-p 57
use-package 35
values 27
values-list 27
vector 38
when 67
with-input-from-string 82
with-open-file 80
with-output-to-string 82
write-byte 80
write-char 78
XLPATH 85
y-or-n-p 74
yes-or-no-p 74
zerop 65