XLISP-PLUS: Another Object-oriented Lisp
Version 3.0
January 15, 1997
Tom Almy
almy@teleport.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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
HOOK FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
LEXICAL CONVENTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . 10
8 BIT ASCII CHARACTERS . . . . . . . . . . . . . . . . . . . . . . . . 12
READTABLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
SYMBOL CASE CONTROL . . . . . . . . . . . . . . . . . . . . . . . . . . 15
PACKAGES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
LAMBDA LISTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
GENERALIZED VARIABLES . . . . . . . . . . . . . . . . . . . . . . . . . 20
OBJECTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
SYMBOLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
EVALUATION FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 27
MULTIPLE VALUE FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . 29
SYMBOL FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
GENERALIZED VARIABLE FUNCTIONS . . . . . . . . . . . . . . . . . . . . 33
PACKAGE FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
PROPERTY LIST FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . 39
HASH TABLE FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 40
ARRAY FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
SEQUENCE FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . 42
LIST FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
DESTRUCTIVE LIST FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . 54
ARITHMETIC FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 55
BITWISE LOGICAL FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . 60
XLISP-PLUS 3.0 Table of Contents
STRING FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
CHARACTER FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . 66
STRUCTURE FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . 68
OBJECT FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
PREDICATE FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . 72
CONTROL CONSTRUCTS . . . . . . . . . . . . . . . . . . . . . . . . . . 77
LOOPING CONSTRUCTS . . . . . . . . . . . . . . . . . . . . . . . . . . 80
THE PROGRAM FEATURE . . . . . . . . . . . . . . . . . . . . . . . . . . 81
INPUT/OUTPUT FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . 83
THE FORMAT FUNCTION . . . . . . . . . . . . . . . . . . . . . . . . . . 86
FILE I/O FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . 89
STRING STREAM FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . 94
DEBUGGING AND ERROR HANDLING FUNCTIONS . . . . . . . . . . . . . . . . 95
SYSTEM FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
ADDITIONAL FUNCTIONS AND UTILITIES . . . . . . . . . . . . . . . . . . 104
COMPILATION OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . 109
BUG FIXES AND EXTENSIONS . . . . . . . . . . . . . . . . . . . . . . . 111
EXAMPLES: FILE I/O FUNCTIONS . . . . . . . . . . . . . . . . . . . . . 121
INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
XLISP-PLUS 3.0 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 111 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 almy@teleport.com, http://www.teleport.com/~almy/xlisp.html.
You can also reach Tom by writing to him at 17830 SW Shasta Trail,
Tualatin, OR 97062, USA.
XLISP-PLUS 3.0 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 or OS/2 (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-PLUS 3.0 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, or under OS/2 or
Windows, 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.
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-PLUS 3.0 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-PLUS 3.0 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 and Windows 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.
ù bignums (integers)
Big integers which don't fit in fixnums are stored in a special
structure. Part of the bignum extension compilation option, when
absent fixnums will overflow into flonums. Fixnums and flonums are
collectively referred to as "integers". [size limit is about 65500
characters for printing or about 500000 bits for calculations].
XLISP-PLUS 3.0 DATA TYPES Page 6
ù ratios
The CAR field is used to hold the numerator while the CDR field is
used to hold the denominator. The numerator and denominator are stored
as either both bignums or both fixnums. All ratios results are
returned in reduced form, and are returned as integers if the
denominator is 1. Part of the bignums extension. Ratios and integers
are collectively referred to as rationals.
ù 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. Flonums and rational numbers are
collectively referred to as real numbers.
ù complex numbers
Part of the math extension compilation option. The CAR field is used
to hold the real part while the CDR field is used to hold the
imaginary part. The parts can be either both rationals (ratio or
integer) or both flonums. Any function which would return an integer
complex number with a zero imaginary part returns just the real
integer.
ù 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 96 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.
XLISP-PLUS 3.0 DATA TYPES Page 7
ù 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-PLUS 3.0 THE EVALUATOR Page 8
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-PLUS 3.0 HOOK FUNCTIONS Page 9
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-PLUS 3.0 LEXICAL CONVENTIONS Page 10
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.
Integer literals consist of a sequence of digits optionally beginning with
a sign ('+' or '-'). Unless the bignum extension is used, 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. The radix of the literal is determined
by the value of the variable *read-base* if it has an integer value within
the range 2 to 36. However the literal can end with a period '.' in which
case it is treated as a decimal number. It is generally not a good idea to
assign a value to *read-base* unless you are reading from a file of
integers in a non-decimal radix. Use the read macros instead to specify the
base explicitly.
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.
XLISP-PLUS 3.0 LEXICAL CONVENTIONS Page 11
Flonum (floating point) literals consist of a sequence of digits optionally
beginning with a sign ('+' or '-') and including one or both of an embedded
(not trailing) 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 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'. Conversely, symbols that could be interpreted as
numeric literals in the current radix must have escape characters.
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 real number literal. If either field has a flonum literal,
then both values are converted to flonums. Rational (integer or ratio)
complex literals with a zero imaginary part are automatically reduced to
rationals.
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-PLUS 3.0 8 BIT ASCII CHARACTERS Page 12
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-PLUS 3.0 READTABLES Page 13
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-PLUS 3.0 READTABLES Page 14
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>
#d<digits> == a decimal number (integer or ratio)
#x<hdigits> == a hexadecimal integer or ratio (0-9,A-F)
#o<odigits> == an octal integer or ratio (0-7)
#b<bdigits> == a binary integer or ratio (0-1)
#<base>r<digits> == an integer or ratio in base <base>, 2-36
#| |# == 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), :BIGNUMS (bignums and
ratios), :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-PLUS 3.0 SYMBOL CASE CONTROL Page 15
SYMBOL CASE CONTROL
XLISP-PLUS uses two variables, *READTABLE-CASE* and *PRINT-CASE* to
determine 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-PLUS 3.0 SYMBOL CASE CONTROL Page 16
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-PLUS 3.0 PACKAGES Page 17
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.
The file MAKEWKS.LSP shows how to build an initial XLISP workspace such
that all the tools are accessable.
For the subtleties of the package facility, read Common Lisp the Language,
second edition.
XLISP-PLUS 3.0 LAMBDA LISTS Page 18
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-PLUS 3.0 LAMBDA LISTS Page 19
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-PLUS 3.0 GENERALIZED VARIABLES Page 20
GENERALIZED VARIABLES
Several XLISP functions support the concept of generalized variables. The
idea behind generalized variables is that variables have two operations,
access and update. Often two separate functions exist for the access and
update operations, such as SYMBOL-VALUE and SET for the dynamic symbol
value, or CAR and REPLACA for the car part of a cons cell. Code can be
simplified if only one such function, the access function, is necessary.
The function SETF is used to update. SETF takes a "place form" argument
which specifies where the data is to be stored. The place form is identical
to the function used for access. Thus we can use (setf (car x) 'y) instead
of (rplaca x 'y). Updates using place forms are "destructive" in that the
alter the data structure rather than rebuilding. Other functions which take
place forms include PSETF, GETF, REMF, PUSH, PUSHNEW, POP, INCF, and DECF.
XLISP has a number of place forms pre-defined in code. In addition, the
function DEFSETF can be used to define new place forms. Place forms and
functions that take them as arguments must be carefully defined so that no
expression is evaluated more than once, and evaluation proceeds from left
to right. The result of this is that these functions tend to be slow. If
multiple evaluation and execution order is not a concern, alternative
simpler functions can be un-commented in COMMON.LSP and COMMON2.LSP.
A place form may be one of the following:
ù A symbol (variable name). In this case note that (setf x y) is the
same as (setq x y)
ù A function call form of one of the following functions: CAR CDR NTH
AREF ELT GET GETF SYMBOL-VALUE SYMBOL-FUNCTION SYMBOL-PLIST GETHASH.
The function GETF itself has a place form which must aditionally be
valid. The file COMMON2.LSP define additional placeforms (using
DEFSETF) for LDB MASK-FIELD FIRST REST SECOND THIRD (through TENTH)
and CxR. When used as a place form, the second argument of LDB and
MASK-FIELD must be place forms and the number is not destructively
modified.
ù A macro form, which is expanded and re-evaluated as a place form.
ù (send <obj> :<ivar>) to set the instance variable of an object
(requires CLASSES.LSP be used).
ù (<sym>-<element> <struct>) to set the element, <element>, of structure
<struct> which is of type <sym>/
ù (<fieldsym> <args>) form name <fieldsym>, defined with DEFSETF or
manually, is used with the arguments. When used with SETF, the
function stored in property *setf* of symbol <fieldsym> is applied to
(<args> <setf expr>), or, alternatively, the function stored in
property *setf-lambda* is applied then the result is evaluated in the
current context.
XLISP-PLUS 3.0 OBJECTS Page 21
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-PLUS 3.0 OBJECTS Page 22
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 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-PLUS 3.0 OBJECTS Page 23
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-PLUS 3.0 OBJECTS Page 24
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-PLUS 3.0 SYMBOLS Page 25
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 21),
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 9,
and evalhook and applyhook functions).
ù *applyhook* - user substitute for function application (see page 9,
and evalhook and applyhook functions).
ù *readtable* - the current readtable (see page 13).
ù *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 9).
XLISP-PLUS 3.0 SYMBOLS Page 26
ù *integer-format* - format for printing integers (when not bound to a
string, defaults to "%d" or "%ld" depending on implementation).
Variable not used when bignum extension installed.
ù *float-format* - format for printing floats (when not bound to a
string, defaults to "%g")
ù *readtable-case* - symbol read and output case. See page 15 for
details
ù *read-base* - When bound to a fixnum in the range 2 through 36,
determines the default radix used when reading rational numbers. Part
of bignum extension.
ù *print-base* - When bound to a fixnum in the range 2 through 36,
determines the radix used when printing rational numbers with prin1
and princ. Part of bignum extension.
ù *print-case* - symbol output case when printing. See page 15 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 8).
ù *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-PLUS 3.0 EVALUATION FUNCTIONS Page 27
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-PLUS 3.0 EVALUATION FUNCTIONS Page 28
(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-PLUS 3.0 MULTIPLE VALUE FUNCTIONS Page 29
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-PLUS 3.0 SYMBOL FUNCTIONS Page 30
SYMBOL FUNCTIONS
(set <sym> <expr>) SET THE GLOBAL VALUE OF A SYMBOL
You can also use (setf (symbol-value <sym>) <expr>)
<sym> the symbol being set
<expr> the new value
returns the new value
(setq [<sym> <expr>]...) SET THE VALUE OF A SYMBOL
fsubr. You can also use (setf <sym> <expr>)
<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
(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
May be used as a place form.
<sym> the symbol
returns the symbol's value
XLISP-PLUS 3.0 SYMBOL FUNCTIONS Page 31
(symbol-function <sym>) GET THE FUNCTIONAL VALUE OF A SYMBOL
May be used as a place form.
<sym> the symbol
returns the symbol's functional value
(symbol-plist <sym>) GET THE PROPERTY LIST OF A SYMBOL
May be used as a place form.
<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 fixnum less than 32768)
returns the hash index (fixnum 0 to n-1)
(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 extension 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 (will be marked "special")
<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 (will be marked "special")
<val> the initial value, or NIL if absent.
<comment> optional comment string (ignored)
returns the current value
XLISP-PLUS 3.0 SYMBOL FUNCTIONS Page 32
(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.
(copy-symbol <sym> [<flag>]) MAKE A COPY OF A SYMBOL
Function in common2.lsp
<sym> symbol to copy
<flag> if present and non-nil, copy value, function binding, and
property list.
returns un-interned copy of <sym>
XLISP-PLUS 3.0 GENERALIZED VARIABLE FUNCTIONS Page 33
GENERALIZED VARIABLE FUNCTIONS
(setf [<place> <expr>]...) SET THE VALUE OF A FIELD
fsubr
<place> the field specifier
<expr> the new value
returns the last new value, or NIL if no arguments
(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
<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>
XLISP-PLUS 3.0 GENERALIZED VARIABLE FUNCTIONS Page 34
(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>)
(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>)
XLISP-PLUS 3.0 PACKAGE FUNCTIONS Page 35
PACKAGE FUNCTIONS
These functions are defined when the packages extension 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.
When the packages extension is not compiled, simplified versions of
apropos, apropos-list, and do-all-symbols are provided in common2.lsp. In
addition, init.lsp will define dummy versions of export and in-package.
(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-PLUS 3.0 PACKAGE FUNCTIONS Page 36
(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-PLUS 3.0 PACKAGE FUNCTIONS Page 37
(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 (default), else
internal obarray
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-PLUS 3.0 PACKAGE FUNCTIONS Page 38
(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-PLUS 3.0 PROPERTY LIST FUNCTIONS Page 39
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 as a place form (with SETF) 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 GETF as a place form with SETF 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-PLUS 3.0 HASH TABLE FUNCTIONS Page 40
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 fixnum 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
May be used as place form.
<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-PLUS 3.0 ARRAY FUNCTIONS Page 41
ARRAY FUNCTIONS
Note that sequence functions also work on arrays.
(aref <array> <n>) GET THE NTH ELEMENT OF AN ARRAY
May be used as a place form
<array> the array (or string)
<n> the array index (fixnum, 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 (fixnum)
: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-PLUS 3.0 SEQUENCE FUNCTIONS Page 42
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
May be used as a place form
<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-PLUS 3.0 SEQUENCE FUNCTIONS Page 43
(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
(stable-sort <seq> <test> &key :key) STABLE DESTRUCTIVE SORT
<seq> the sequence to sort
<test> the comparison function, must return T only if its first
argument is strictly to the left of its second argument.
: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 :count
:from-end)
REMOVE ELEMENTS FROM A SEQUENCE
(remove-if <test> <seq> &key :key :start :end :count :from-end)
REMOVE ELEMENTS THAT PASS TEST
(remove-if-not <test> <seq> &key :key :start :end :count :from-end)
REMOVE ELEMENTS THAT FAIL TEST
<expr> the element to remove
<test> the test predicate, applied to each <seq> element in turn
<seq> the sequence
:test the test function (defaults to eql)
:test-not the test function (sense inverted)
:key function to apply to each <seq> element (defaults to
identity)
:start starting index
:end index of end+1, or NIL for (length <seq>)
:count maximum number of elements to remove, negative values
treated as zero, NIL same as default -- unlimited.
:from-end if non-nil, behaves as though elements are removed from
right end. This only has an affect when :count is used.
returns copy of sequence with matching/non-matching expressions
removed
XLISP-PLUS 3.0 SEQUENCE FUNCTIONS Page 44
(count <expr> <seq> &key :test :test-not :key :start :end :from-end)
COUNT MATCHING ELEMENTS IN A SEQUENCE
(count-if <test> <seq> &key :key :start :end :from-end)
COUNT ELEMENTS THAT PASS TEST
(count-if-not <test> <seq> &key :key :start :end :from-end)
COUNT ELEMENTS THAT FAIL TEST
<expr> element to count
<test> the test predicate, applied to each <seq> element in turn
<seq> the sequence
:test the test function (defaults to eql)
:test-not the test function (sense inverted)
:key function to apply to each <seq> element (defaults to
identity)
:start starting index
:end index of end+1, or NIL for (length <seq>)
:from-end this argument is ignored
returns count of matching/non-matching elements
(find <expr> <seq> &key :test :test-not :key :start :end :from-end)
FIND FIRST MATCHING ELEMENT IN SEQUENCE
(find-if <test> <seq> &key :key :start :end :from-end)
FIND FIRST ELEMENT THAT PASSES TEST
(find-if-not <test> <seq> &key :key :start :end :from-end)
FIND FIRST ELEMENT THAT FAILS TEST
<expr> element to search for
<test> the test predicate, applied to each <seq> element in turn
<seq> the sequence
:test the test function (defaults to eql)
:test-not the test function (sense inverted)
:key function to apply to each <seq> element (defaults to
identity)
:start starting index
:end index of end+1, or NIL for (length <seq>)
:from-end if non-nil search is done for last element
returns first matching/non-matching element of sequence, or NIL
(position <expr> <seq> &key :test :test-not :key :start :end :from-end)
FIND POSITION OF FIRST MATCHING ELEMENT IN SEQUENCE
(position-if <test> <seq> &key :key :start :end :from-end)
FIND POSITION OF FIRST ELEMENT THAT PASSES TEST
(position-if-not <test> <seq> &key :key :start :end :from-end)
FIND POSITION OF FIRST ELEMENT THAT FAILS TEST
<expr> element to search for
<test> the test predicate, applied to each <seq> element in turn
<seq> the sequence
:test the test function (defaults to eql)
:test-not the test function (sense inverted)
:key function to apply to each <seq> element (defaults to
identity)
:start starting index
:end index of end+1, or NIL for (length <seq>)
:from-end if non-nil search is made for last element
returns position of first matching/non-matching element of sequence,
or NIL
XLISP-PLUS 3.0 SEQUENCE FUNCTIONS Page 45
(delete <expr> <seq> &key :key :test :test-not :start :end :count
:from-end)
DELETE ELEMENTS FROM A SEQUENCE
(delete-if <test> <seq> &key :key :start :end :count :from-end)
DELETE ELEMENTS THAT PASS TEST
(delete-if-not <test> <seq> &key :key :start :end :count :from-end)
DELETE ELEMENTS THAT FAIL TEST
<expr> the element to delete
<test> the test predicate, applied to each <seq> element in turn
<seq> the sequence
:test the test function (defaults to eql)
:test-not the test function (sense inverted)
:key function to apply to each <seq> element (defaults to
identity)
:start starting index
:end index of end+1, or NIL for (length <seq>)
:count maximum number of elements to remove, negative values
treated as zero, NIL same as default -- unlimited.
:from-end if non-nil, behaves as though elements are removed from
right end. This only has an affect when :count is used.
returns <seq> with the matching/non-matching expressions deleted
(substitute <r> <e> <s> &key :key :test :test-not :start :end :count :from-
end)
SUBSTITUTE ELEMENTS IN A SEQUENCE
(substitute-if <r> <test> <s> &key :key :start :end :count :from-end)
SUBSTITUTE ELEMENTS THAT PASS TEST
(substitute-if-not <r> <test> <s> &key :key :start :end :count :from-end)
SUBSTITUTE ELEMENTS THAT FAIL TEST
<r> the replacement expression
<e> the element to replace
<test> the test predicate, applied to each <s> element in turn
<s> the sequence
:test the test function (defaults to eql)
:test-not the test function (sense inverted)
:key function to apply to each <s> element (defaults to identity)
:start starting index
:end index of end+1, or NIL for (length <s>)
:count maximum number of elements to remove, negative values
treated as zero, NIL same as default -- unlimited.
:from-end if non-nil, behaves as though elements are removed from
right end. This only has an affect when :count is used.
returns copy of <s> with the matching/non-matching expressions
substituted
XLISP-PLUS 3.0 SEQUENCE FUNCTIONS Page 46
(nsubstitute <r> <e> <s> &key :key :test :test-not :start :end :count
:from-end)
DESTRUCTIVELY SUBSTITUTE ELEMENTS IN A SEQUENCE
(nsubstitute-if <r> <test> <s> &key :key :start :end :count :from-end)
DESTRUCTIVELY SUBSTITUTE ELEMENTS THAT PASS TEST
(nsubstitute-if-not <r> <test> <s> &key :key :start :end :count :from-end)
DESTRUCTIVELY SUBSTITUTE ELEMENTS THAT FAIL TEST
<r> the replacement expression
<e> the element to replace
<test> the test predicate, applied to each <s> element in turn
<s> the sequence
:test the test function (defaults to eql)
:test-not the test function (sense inverted)
:key function to apply to each <s> element (defaults to identity)
:start starting index
:end index of end+1, or NIL for (length <s>)
:count maximum number of elements to remove, negative values
treated as zero, NIL same as default -- unlimited.
:from-end if non-nil, behaves as though elements are removed from
right end. This only has an affect when :count is used.
returns <s> with the matching/non-matching expressions substituted
(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)
MAKE SEQUENCE WITH DUPLICATES REMOVED
(delete-duplicates <seq> &key :test :test-not :key :start :end)
DELETE DUPLICATES FROM SEQUENCE
Delete-duplicates defined in common2.lsp.
<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, or <seq> with
duplicates deleted (destructive).
XLISP-PLUS 3.0 SEQUENCE FUNCTIONS Page 47
(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
(make-sequence <type> <size> &key :initial-element) MAKE A SEQUENCE
Defined in common2.lsp.
<type> type of sequence to create: CONS LIST ARRAY or STRING
<size> size of sequence (non-negative integer)
:initial-element
initial value of all elements in sequence
returns the new sequence
(copy-seq <seq>) COPY A SEQUENCE
Defined in common2.lsp
<seq> sequence to copy
returns copy of the sequence, sequence elements are eq those in the
original sequence.
(merge <type> <seq1> <seq2> <pred> &key :key) MERGE TWO SEQUENCES
Defined in common2.lsp. Non-destructive, although may be destructive
in Common Lisp.
<type> type of result sequence: CONS LIST ARRAY or STRING
<seq1> first sequence to merge
<seq2> second sequence to merge
<pred> function of two arguments which returns true if its first
argument should precede its second
:key optional function to apply to each sequence element before
applying predicate function (defaults to identity)
returns new sequence containing all the elements of seq1 (in order)
merged with all the elements of seq2, according to the
predicate function
XLISP-PLUS 3.0 SEQUENCE FUNCTIONS Page 48
(mismatch <s1> <s2> &key :test :test-not :key :start1 :end1 :start2 :end2)
FIND DIFFERENCE BETWEEN TWO SEQUENCES
Defined in common2.lsp.
<s1> first sequence
<s2> second sequence
:test the test function (defaults to eql)
:test-not the test function (sense inverted)
:key function to apply to to each sequence element before
applying test function (defaults to identity)
:start1 starting index in <s1>
:end1 index of end+1 in <s1> or NIL for end of sequence
:start2 starting index in <s2>
:end2 index of end+1 in <s2> or NIL for end of sequence
returns integer index of first mismatch in s1, or NIL if no mismatch
XLISP-PLUS 3.0 LIST FUNCTIONS Page 49
LIST FUNCTIONS
(car <expr>) RETURN THE CAR OF A LIST NODE
May be used as a place form.
<expr> the list node
returns the car of the list node
(cdr <expr>) RETURN THE CDR OF A LIST NODE
May be used as a place form.
<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
May be used as place forms when COMMON2.LSP loaded.
(first <expr>) A SYNONYM FOR CAR
(second <expr>) A SYNONYM FOR CADR
(third <expr>) A SYNONYM FOR CADDR
(fourth <expr>) A SYNONYM FOR CADDDR
(fifth <expr>) FIFTH LIST ELEMENT
(sixth <expr>) SIXTH LIST ELEMENT
(seventh <expr>) SEVENTH LIST ELEMENT
(eighth <expr>) EIGHTH LIST ELEMENT
(ninth <expr>) NINTH LIST ELEMENT
(tenth <expr>) TENTH LIST ELEMENT
(rest <expr>) A SYNONYM FOR CDR
May be used as place forms when COMMON2.LSP loaded. fifth through
tenth defined in COMMON2.LSP.
(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
XLISP-PLUS 3.0 LIST FUNCTIONS Page 50
(revappend <expr1> <expr2>) APPEND REVERSE LIST
Defined in common2.lsp
<expr1> first list
<expr2> second list
returns new list comprised of reversed first list appended to second
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
(tailp <sublist> <list>) IS ONE LIST A SUBLIST OF ANOTHER?
Defined in common2.lsp
<sublist> list to search for
<list> list to search in
returns T if sublist is EQ one of the top level conses of list
(butlast <list> [<n>]) RETURN COPY OF ALL BUT LAST OF LIST
(nbutlast <list> [<n>]) DELETE LAST ELEMENTS OF LIST
nbutlast defined in common2.lsp
<list> the list
<n> count of elements to omit (default 1)
returns copy of list with last element(s) absent, or, for nbutlast,
the list with the last elements deleted (destructive).
(nth <n> <list>) RETURN THE NTH ELEMENT OF A LIST
May be used as a place form
<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
(member-if <test> <list> &key :key) FIND ELEMENT PASSING TEST
(member-if-not <test> <list> &key :key) FIND ELEMENT FAILING TEST
Functions member-if and member-if-not defined in common2.lsp
<expr> the expression to find
<test> the test predicate
<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 or
element passing/failing the test predicate
XLISP-PLUS 3.0 LIST FUNCTIONS Page 51
(assoc <expr> <alist> &key :test :test-not :key)
FIND AN EXPRESSION IN AN A-LIST
(assoc-if <test> <alist> &key :key) FIND ELEMENT IN A-LIST PASSING TEST
(assoc-if-not <test> <alist> &key :key) FIND ELEMENT IN A-LIST FAILING TEST
(rassoc <expr> <alist> &key :test :test-not :key)
FIND AN EXPRESSION IN AN A-LIST
(rassoc-if <test> <alist> &key :key) FIND ELEMENT IN A-LIST PASSING TEST
(rassoc-if-not <test> <alist> &key :key)FIND ELEMENT IN A-LIST FAILING TEST
All functions but assoc defined in common2.lsp. The rassoc functions
match the cdrs of the a-list elements while the assoc functions match
the cars.
<expr> the expression to find
<test> the test predicate
<alist> the association list
:test the test function (defaults to eql)
:test-not the test function (sense inverted)
:key function to apply to a-list argument (defaults to identity)
returns the alist entry or NIL
(mapc <fcn> <list1> <list>...) APPLY FUNCTION TO SUCCESSIVE CARS
(mapcar <fcn> <list1> <list>...) APPLY FUNCTION TO SUCCESSIVE CARS
(mapcan <fcn> <list1> <list>...) APPLY FUNCTION TO SUCCESSIVE CARS
(mapl <fcn> <list1> <list>...) APPLY FUNCTION TO SUCCESSIVE CDRS
(maplist <fcn> <list1> <list>...) APPLY FUNCTION TO SUCCESSIVE CDRS
(mapcon <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 (mapc or mapl), a list of the
values returned (mapcar or maplist), or list or returned
values nconc'd together (mapcan or mapcon).
(subst <to> <from> <expr> &key :test :test-not :key)
(nsubst <to> <from> <expr> &key :test :test-not :key)
(nsubst-if <to> <test> <expr> &key :key)
(nsubst-if-not <to> <test> <expr> &key :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 (match to part of <expr> using test
function
<test> test predicate
<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
XLISP-PLUS 3.0 LIST FUNCTIONS Page 52
(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
(make-list <size> &key :initial-element) MAKE A LIST
In file common2.lsp
<size> size of list (non-negative integer)
:initial-element
initial value for each element, default NIL
returns the new 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-PLUS 3.0 LIST FUNCTIONS Page 53
(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>.
(ldiff <list> <sublist>) GET INITIAL ELEMENTS OF LIST
In file common2.lsp
<list> list to get elements of
<sublist> list to search for in <list> (uses tailp)
returns copy of list up to match with sublist.
XLISP-PLUS 3.0 DESTRUCTIVE LIST FUNCTIONS Page 54
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, nbutlast, nsubst, nsubst-if,
nsubst-if-not, nsublis, nintersection, nunion, nset-difference, and
nset-exclusive-or under LIST FUNCTIONS. Also, setf is a destructive
function.
(rplaca <list> <expr>) REPLACE THE CAR OF A LIST NODE
Modern practice is to use (setf (car <list>) <expr>)
<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
Modern practice is to use (setf (cdr <list>) <expr>)
<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
(nreconc <list1> <list2>) DESTRUCTIVELY CONCATENATE LISTS
Defined in common2.lsp
<list1> first list
<list2> second list
returns second list concantenated to the end of the first list,
which has been destructively reversed.
XLISP-PLUS 3.0 ARITHMETIC FUNCTIONS Page 55
ARITHMETIC FUNCTIONS
Warning: integer calculations that overflow become floating point values as
part of the math extension, but give no error in the base-line Xlisp.
Integer calculations cannot overflow when the bignum extension is compiled.
On systems with IEEE floating point, the values +INF and -INF result from
overflowing floating point calculations.
The math extension option adds complex numbers, new functions, and
additional functionality to some existing functions. The bignum extension,
in addition, adds ratios, bignums, new functions and additional
functionality to some existing functions. Because of the size of the
extensions, and the performance loss they entail, some users may not wish
to include bignums, or bignums and math. This section documents the math
functions both with and without the extensions.
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 (bignum extension) 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. Rational 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. 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 flonum if either
argument is flonum, otherwise it is rational.
(float <expr>) CONVERTS AN INTEGER TO A FLOATING POINT NUMBER
<expr> the real number
returns the number as a flonum
(rational <expr>) CONVERTS A REAL NUMBER TO A RATIONAL
Rational numbers are returned as is. Part of the bignum extension.
<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-PLUS 3.0 ARITHMETIC FUNCTIONS Page 56
(- <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 bignum extension, division of integer numbers results in a
rational quotient, rather than integer. To perform integer division,
use TRUNCATE.
<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-PLUS 3.0 ARITHMETIC FUNCTIONS Page 57
(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.
(float-sign <expr1> [<expr2>]) APPLY SIGN TO A NUMBER
Defined in common2.lsp
<expr1> the real number
<expr2> another real number, defaults to 1.0
returns the number <expr2> with the sign of <expr1>
(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>
XLISP-PLUS 3.0 ARITHMETIC FUNCTIONS Page 58
(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.
(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 an integer, then the result type
is the same as the type of x.
(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
(isqrt <expr>) COMPUTER THE INTEGER SQUARE ROOT OF A NUMBER
Defined in common2.lsp
<expr> non-negative integer
returns the integer square root, either exact or the largest integer
less than the exact value.
(numerator <expr>) GET THE NUMERATOR OF A NUMBER
Part of bignum extension
<expr> rational number
returns numerator of number (number if integer)
(denominator <expr>) GET THE DENOMINATOR OF A NUMBER
Part of bignum extension
<expr> rational number
returns denominator of number (1 if integer)
XLISP-PLUS 3.0 ARITHMETIC FUNCTIONS Page 59
(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.
(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-PLUS 3.0 BITWISE LOGICAL FUNCTIONS Page 60
BITWISE LOGICAL FUNCTIONS
Integers are treated as two's complement, which can cause what appears to
be strange results when negative numbers are supplied as arguments.
(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
(logeqv [<expr>...]) THE BITWISE EQUIVALENCE OF A LIST OF INTEGERS
With no arguments returns identity -1
<expr> the integers
returns the result of the equivalence operation
(lognand <expr1> <expr2>) BITWISE LOGICAL FUNCTIONS
(logandc1 <expr1> <expr2>)
(logandc2 <expr1> <expr2>)
(lognor <expr1> <expr2>)
(logorc1 <expr1> <expr2>)
(logorc2 <expr1> <expr2>)
Part of the bignums extension, the remaining logical functions of two
integers.
<expr1> the first integer
<expr2> the second integer
returns lognand: (lognot (logand <expr1> <expr2>))
logandc1: (logand (lognot <expr1>) <expr2>)
logandc2: (logand <expr1> (lognot <expr2>))
lognor: (lognot (logor <expr1> <expr2>))
logorc1: (logor (lognot <expr1>) <expr2>)
logorc2: (logor <expr1> (lognot <expr2>))
(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 when bignum extension not loaded
<expr1> the first integer
<expr2> the second integer
returns T if the result of the and operation is non-zero, else NIL
XLISP-PLUS 3.0 BITWISE LOGICAL FUNCTIONS Page 61
(logbitp <pos> <expr>) TEST BIT OF INTEGER
Part of bignums extension
<pos> non-negative fixnum bit position, as in (expt 2 <pos>)
<expr> integer to test
returns T if the bit is "1", else NIL.
(logcount <expr>) COUNT BITS IN AN INTEGER
Part of bignums extension
<expr> integer
returns if <expr> is negative, returns the number of 0 bits, else
returns the number of 1 bits
(integer-length <expr>) CALCULATE LENGTH OF AN INTEGER
Part of bignums extension
<expr> integer
returns the minimum number of bits necessary to represent the
integer, excluding any sign bit.
(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
(byte <size> <pos>) CREATE A BYTE SPECIFIER
(byte-size <spec>) GET SPECIFIER SIZE FIELD
(byte-position <spec>) GET SPECIFIER POSITION FIELD
Defined in common2.lsp. A "byte specifier" is implemented as a CONS
cell with the CAR being the size and the CDR being the position. These
functions are aliases for CONS, CAR, and CDR, respectively.
<size> size of byte field (non-negative integer)
<pos> starting position of byte field (non-negative integer),
which is position with least bit weight
<spec> byte specifier (a CONS cell)
returns BYTE returns the specifier, BYTE-SIZE returns the size
field, and BYTE-POSITION returns the starting position
(ldb <spec> <int>) LOAD BYTE
Defined in common2.lsp. LDB can be used with SETF, in which case it
performs a STB followed by a SETF into the field.
<spec> specifier of byte to extract
<int> integer to extract byte from
returns the extracted byte, a non-negative integer
(ldb-test <spec> <int>) TEST A BYTE
Defined in common2.lsp
<spec> specifier of byte to test
<int> integer containing byte to test
returns T if byte is zero, else NIL
XLISP-PLUS 3.0 BITWISE LOGICAL FUNCTIONS Page 62
(mask-field <spec> <int>) EXTRACT UNDER MASK
Defined in common2.lsp. MASK-FIELD can be used with SETF, in which
case it performs a DEPOSIT-FIELD followed by a SETF into the field.
<spec> specified byte to extract
<int> integer to extract byte from
returns the extracted byte in the same bit position as it was in
<int>
(dpb <new> <spec> <int>) DEPOSIT BYTE
Defined in common2.lsp
<new> integer byte to insert
<spec> specifier of position and size of byte
<int> integer to insert byte into
returns <int> with <new> in the bit positions specified by <spec>
(deposit-field <new> <spec> <int>) INSERT UNDER MASK
Defined in common2.lsp
<new> integer containing byte field to insert
<spec> specifier of position and size of byte
<int> integer to insert byte into
returns <new> at <spec> replacing bits at <spec> in <int>
XLISP-PLUS 3.0 STRING FUNCTIONS Page 63
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-PLUS 3.0 STRING FUNCTIONS Page 64
(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)
(make-string <size> &key :initial-element) MAKE A STRING
Defined in common2.lsp.
<size> size of string (non-negative integer)
:initial-element
initial value of all characters in the string
returns the new string
(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.
XLISP-PLUS 3.0 STRING FUNCTIONS Page 65
(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-PLUS 3.0 CHARACTER FUNCTIONS Page 66
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>[<radix>]) IS THIS A DIGIT CHARACTER?
<chr> the character
<radix> the radix (default 10)
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
XLISP-PLUS 3.0 CHARACTER FUNCTIONS Page 67
(digit-char <n>[<radix>]) CONVERT A DIGIT WEIGHT TO A DIGIT
<n> the digit weight (integer)
<radix> the radix (default 10)
returns the digit character or NIL
(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
(character <expr>) CREATE A CHARACTER
Defined in common2.lsp
<expr> single character symbol, string, or integer
returns <expr> converted into a character
(char-name <chr>) CHARACTER PRINT NAME
Defined in common2.lsp
<chr> the character
returns string which is the name of the character, or NIL if no name
(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-PLUS 3.0 STRUCTURE FUNCTIONS Page 68
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-PLUS 3.0 STRUCTURE FUNCTIONS Page 69
For instance:
(defstruct foo bar (gag 2))
creates the following functions:
(foo-bar <expr>)
(setf (foo-bar <expr>) <value>)
(foo-gag <expr>)
place form (foo-gag <expr>)
(make-foo &key :bar :gag)
(copy-foo <expr>)
(foo-p <expr>)
XLISP-PLUS 3.0 OBJECT FUNCTIONS Page 70
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 22.
(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 via
(setf (send <object> :<ivar>) <value>).
(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.
returns the new class 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 selector name (quoted)
<fargs> Formal argument list. Leading "self" is implied (quoted)
<expr> Expressions constituting body of method (quoted)
returns the class object.
XLISP-PLUS 3.0 OBJECT FUNCTIONS Page 71
(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)
returns the instance object
(tracemethod <class> [<sel>]) ADD A METHOD TO THE TRACE LIST
defined in class.lsp
<class> Class containing method to trace
<sel> Message selector of method to trace, if absent then trace
all methods defined in <class>.
returns the trace list
(untracemethod [<class> [<sel>]])) REMOVE A METHOD FROM THE TRACE LIST
defined in class.lsp
<class> Class containing method to remove, if absent remove all
methods of all classes.
<sel> Message selector of method to remove, if absent then remove
all methods of <class>.
returns the trace list
XLISP-PLUS 3.0 PREDICATE FUNCTIONS Page 72
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-PLUS 3.0 PREDICATE FUNCTIONS Page 73
(rationalp <expr>) IS THIS A RATIONAL NUMBER?
Part of bignum extension.
<expr> the expression to check
returns t if the value is rational (integer or ratio), NIL otherwise
(realp <expr>) IS THIS A REAL NUMBER?
Defined in common2.lsp
<expr> the expression to check
returns t if the value is rational or float, 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
(array-in-bounds-p <expr> <index>) IS ARRAY INDEX IN BOUNDS?
Defined in common2.lsp
<expr> the array
<index> index to check
returns t if index is in bounds for the 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
XLISP-PLUS 3.0 PREDICATE FUNCTIONS Page 74
(classp <expr>) IS THIS A CLASS OBJECT?
<expr> the expression to check
returns t if the value is a class object, NIL otherwise
(hash-table-p <expr>) IS THIS A HASH TABLE?
Defined in common2.lsp
<expr> the expression to check
returns t if the value is a hash table, NIL otherwise
(keywordp <expr>) IS THIS A KEYWORD?
Defined in common2.lsp
<expr> the expression to check
returns t if the value is a keyword symbol, NIL otherwise
(packagep <expr>) IS THIS A PACKAGE?
Defined in common2.lsp
<expr> the expression to check
returns t if the value is a package, 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
(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
XLISP-PLUS 3.0 PREDICATE FUNCTIONS Page 75
(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 59)
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-PLUS 3.0 PREDICATE FUNCTIONS Page 76
(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 100) or one of:
ATOM any atom
NULL NIL
LIST matches NIL or any cons cell
STREAM any stream
NUMBER any numeric type
REAL flonum or rational number
INTEGER fixnum or bignum
RATIONAL fixnum or ratio
STRUCT any structure (except hash-table)
FUNCTION any function, as defined by functionp (page 74)
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-PLUS 3.0 CONTROL CONSTRUCTS Page 77
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-PLUS 3.0 CONTROL CONSTRUCTS Page 78
(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
(typecase <expr> <case>...[(t <expr>)]) SELECT BY TYPE
macro defined in common2.lsp
<expr> the selection expression
<case> pair consisting of:
(<type> <expr>...)
where:
<type> type specifier as in function TYPEP (page 76)
<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
XLISP-PLUS 3.0 CONTROL CONSTRUCTS Page 79
(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
(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-PLUS 3.0 LOOPING CONSTRUCTS Page 80
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 (a fixnum)
<rexpr> the result expression (the default is NIL)
<expr> the body of the loop (treated like an implicit prog)
returns the result expression
XLISP-PLUS 3.0 THE PROGRAM FEATURE Page 81
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-PLUS 3.0 THE PROGRAM FEATURE Page 82
(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-PLUS 3.0 INPUT/OUTPUT FUNCTIONS Page 83
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 13)
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, *print-base* for rationals, *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-PLUS 3.0 INPUT/OUTPUT FUNCTIONS Page 84
(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 86)
<arg> arguments, if any, for format string
returns T for yes, NIL for no.
(prin1-to-string <expr>) PRINT TO A STRING
(princ-to-string <expr>)
defined in common2.lsp. Uses prin1 or princ conventions, respectively.
<expr> the expression to print
returns the string containing the "printed" expression
XLISP-PLUS 3.0 INPUT/OUTPUT FUNCTIONS Page 85
(read-from-string <str> [<eofp> [<eof>]] &key :start :end)
READ AN EXPRESSION
defined in common2.lsp.
<str> the input string
<eofp> When T, signal an error on end of string, when NIL return
<eof> (default is T)
<eof> the value to return on end of string (default is NIL)
:start starting index of <str>, default 0
:end ending index of <str>, default NIL (end of string)
returns two values: the expression read and index of character after
last one used
XLISP-PLUS 3.0 THE FORMAT FUNCTION Page 86
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:
~? use next argument as recursive format string
~( ~) process format string with case conversion
~{ ~} process format string repetitively
~* skip arguments
~% start a new line
~& start a new line if not on a new line
~\n ignore return and following whitespace
~| start a new page
~~ print a tilde character
~A or ~a print next argument using princ
~B or ~b print next argument as binary integer (bignum extension)
~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
~R or ~r print next number in any radix (bignum extension)
~S or ~s print next argument using prin1
~T or ~t go to a specified column
~X or ~x print next argument as hexidecimal integer
~[ ~; ~] process format string conditionally
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
XLISP-PLUS 3.0 THE FORMAT FUNCTION Page 87
The output is padded on the left with at least 2 periods until the output
is at least 15 characters wide.
For ~D, ~B, ~O, and ~X the full form is ("D" shown):
~mincol,padchar@D
If the data to print is not an integer, 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 ~R, the full form is:
~radix,mincol,padchar@R
The radix must be in the range 2 through 36. Other arguments are as in ~D,
above. Unlike Common Lisp, English text and Roman numeral output is not
supported.
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
XLISP-PLUS 3.0 THE FORMAT FUNCTION Page 88
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
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 ~:[clausenil~;clauset~]. The next argument is
examined (and also 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-PLUS 3.0 FILE I/O FUNCTIONS Page 89
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> [<eofp> [<eof>]]]])
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*)
<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
(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
XLISP-PLUS 3.0 FILE I/O FUNCTIONS Page 90
(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-PLUS 3.0 FILE I/O FUNCTIONS Page 91
(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 100), or UNSIGNED-BYTE,
SIGNED-BYTE, (UNSIGNED-BYTE <size>), or (SIGNED-BYTE
<size>) with the bignum extension. CHARACTER (the
default) is for text files, the other types are for
binary files and can only be used with READ-BYTE and
WRITE-BYTE. FIXNUM is a vestige of older XLISP-PLUS
releases and is identical to (UNSIGNED-BYTE 8). If no
size is given, then size defaults to 8. Size must be a
multiple of 8.
: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-PLUS 3.0 FILE I/O FUNCTIONS Page 92
(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.
(probe-file <fname>) CHECK FOR EXISTANCE OF A FILE
Defined in common2.lsp
<fname> file name string or symbol
returns t if file exists, else NIL
(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
(with-open-stream (<var> <stream>) [<expr>...])
EVALUATE USING AN OPENED STREAM
Defined in common.lsp and common2.lsp, respectively, as macros. Stream
will always be closed upon completion
<var> symbol name to bind stream to while evaluating expresssions
(quoted)
<fname> file name string or symbol
<stream> a file or string stream
<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 argument used to be optional. Number of system bytes read
depend on :element-type specified in the open command.
<stream> the input stream
<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
NOTE: Stream argument used to be optional. Number of system bytes
writen depend on :element-type specified in open command. No checks
are made for overflow, however negative values cannot be written to
unsigned-byte streams.
<byte> the byte to write (integer)
<stream> the output stream
returns the byte (integer)
XLISP-PLUS 3.0 FILE I/O FUNCTIONS Page 93
(file-length <stream>) GET LENGTH OF FILE
For a CHARACTER 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.
(file-position <stream> [<expr>]) GET OR SET FILE POSITION
For a CHARACTER 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-PLUS 3.0 STRING STREAM FUNCTIONS Page 94
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-PLUS 3.0 DEBUGGING AND ERROR HANDLING Page 95
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-PLUS 3.0 DEBUGGING AND ERROR HANDLING Page 96
(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
(ecase <expr> <case>...) SELECT BY CASE
(ccase <expr> <case>...)
Defined in common2.lsp as macros. ECASE signals a non-continuable
error if there are no case matches, while CCASE signals a continuable
error and allows changing the value of <expr>.
<expr> the selection expression
<case> pair consisting of:
(<value> <expr>...)
where:
<value> is a single expression or a list of expressions
(unevaluated)
<expr> are expressions to execute if the case matches
returns the value of the last expression of the matching case
(etypecase <expr> <case>...) SELECT BY TYPE
(ctypecase <expr> <case>...)
Defined in common2.lsp as macros. ETYPECASE signals a non-continuable
error if there are no case matches, while CTYPECASE signals a
continuable error and allows changing the value of <expr>.
<expr> the selection expression
<case> pair consisting of:
(<type> <expr>...)
where:
<type> type specifier as in function TYPEP (page 76)
<expr> are expressions to execute if the case matches
returns the value of the last expression of the matching case
XLISP-PLUS 3.0 DEBUGGING AND ERROR HANDLING Page 97
(check-type <place> <type> [<string>]) VERIFY DATA TYPE
Defined in common2.lsp as a macro. If value stored at <place> is not
of type <type> then a continuable error is signaled which allows
changing the value at <place>.
<place> a valid field specifier (generalized variable)
<type> a valid type specifier as in function TYPEP (page 76)
<string> string to print as the error message
returns NIL
(assert <test> [([<place>...]) [<string> [<args>...]]]) MAKE AN ASSERTION
Defined in common2.lsp. If value of <test> is NIL then a continuable
error is signaled which allows changing the place values.
<test> assertion test
<place> zero or more valid field specifiers
<string> error message printed using FORMAT (evaluated only if
assertion fails)
<args> arguments for FORMAT (evaluated only if assertion fails)
returns NIL
XLISP-PLUS 3.0 SYSTEM FUNCTIONS Page 98
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-PLUS 3.0 SYSTEM FUNCTIONS Page 99
(gc) FORCE GARBAGE COLLECTION
returns NIL
(expand [<num>]) EXPAND MEMORY BY ADDING SEGMENTS
<num> the (fixnum) number of segments to add, default 1
returns the (fixnum) number of segments added
(alloc <num> [<num2> [<num3>]]) CHANGE SEGMENT SIZE
<num> the (fixnum) number of nodes to allocate
<num2> the (fixnum) number of pointer elements to allocate in an
array segment (when dynamic array allocation compiled).
Default is no change.
<num3> the <fixnum> ideal ratio of free to used vector space
(versions of XLISP using dldmem.c). Default is 1. Increase
if extensive time is spent in garbage collection in bignum
math intensive programs.
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 - total vector space (pointers and string, in
pointer sized units)
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
Vec collect - number of garbage collections instigated by
vector space exhaustion
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*
(sleep <expr>) TIME DELAY
defined in common2.lsp
<expr> time in seconds
returns NIL, after <expr> seconds delay
XLISP-PLUS 3.0 SYSTEM FUNCTIONS Page 100
(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 25). meaning of
absolute values is system dependent.
(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, integers can be coerced into characters or flonums.
Ratios can be coerced into flonums. Flonums can be coerced into
complex.
<expr> the expression to coerce
<type> desired type, as returned by type-of (see page 100)
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
BIGNUM for large 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 (fixnum)
returns the value at the specified address (integer)
(poke <addrs> <value>) POKE A VALUE INTO MEMORY
<addrs> the address to poke (fixnum)
<value> the value to poke into the address (fixnum)
returns the value
(address-of <expr>) GET THE ADDRESS OF AN XLISP NODE
<expr> the node
returns the address of the node (fixnum)
XLISP-PLUS 3.0 SYSTEM FUNCTIONS Page 101
(get-key) READ A KEYSTROKE FROM CONSOLE
OS dependent.
returns integer value of key (no echo)
(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
BIGNUM copy as a string
structure copy as an ARRAY
XLISP-PLUS 3.0 SYSTEM FUNCTIONS Page 102
(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
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
(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
(color <value>) SET DRAWING COLOR
<value> Drawing color (not checked for validity)
returns <value>
XLISP-PLUS 3.0 ADDITIONAL FUNCTIONS Page 103
(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-PLUS 3.0 ADDITIONAL FUNCTIONS Page 104
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-PLUS 3.0 ADDITIONAL FUNCTIONS Page 105
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-PLUS 3.0 ADDITIONAL FUNCTIONS Page 106
DOCUMENT.LSP
This file provides the documentation feature of Common Lisp. When loaded,
glossary descriptions of system functions and variables are installed from
the file GLOS.TXT. References are made directly to the file so that the
size of the XLISP image will not increase. The following functions are
implemented:
(documentation <symbol> <doctype>) GET DOCUMENTATION STRING
Use with SETF to alter documentation string.
<symbol> Symbol of interest
<doctype> Documentation type, one of FUNCTION, VARIABLE, STRUCTURE,
SETF, or TYPE.
returns Documentation string
(glos <symbol> [T]) GET DOCUMENTATION
Defined in package TOOLS.
<symbol> Either the symbol for which the documentation is requested,
or a string which will match all symbol names containing
that string.
T Flag saying to treat symbol as a string, and match all
related names.
returns nothing
Documentation can be added via the DEFCONSTANT, DEFPARAMETER, DEFVAR,
DEFUN, DEFMACRO, and DEFSTRUCT functions as well as via DOCUMENTATION.
Documentation is stored in the property list in properties %DOC-FUNCTION,
%DOC-STRUCTURE, %DOC-VARIABLE, %DOC-SETF, and %DOC-TYPE. The latter two are
not currently used. These properties either contain the documentation
string or the offset into the GLOS.TXT file.
XLISP-PLUS 3.0 ADDITIONAL FUNCTIONS Page 107
INSPECT.LSP
INSPECT.LSP contains an XLISP editor/inspector. When the package feature is
compiled in, the editor is in the TOOLS package. Two functions, INSPECT and
DESCRIBE, are part of Common Lisp and are in the XLISP package.
(ins <symbol>) INSPECT A SYMBOL
(inspect <expr>) INSPECTOR
(insf <symbol>) INSPECT FUNCTION BINDING
INS and INSF are macros defined in package TOOLS. INSF edits the
function binding and allows changing the argument list or type (MACRO
or LAMBDA).
<symbol> Symbol to inspect (quoted)
<expr> Expression to inspect
returns Symbol or expression
(describe <expr>) DESCRIBE
Tells what <expr> is, but doesn't allow editing. Use INSPECT to edit.
<expr> Expression to describe
returns The expression
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-PLUS 3.0 ADDITIONAL FUNCTIONS Page 108
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-PLUS 3.0 COMPILATION OPTIONS Page 109
COMPILATION OPTIONS
XLISP PLUS has many compilation options to optimize the executable for
specific tasks. These are the most useful:
1. Available Functions (all turned on by default)
- SRCHFCN supplies SEARCH
- MAPFCNS supplies SOME EVERY NOTANY NOTEVERY and MAP
- POSFCNS supplies POSITION-* COUNT-* and FIND-* functions
- REMDUPS supplies REMOVE-DUPLICATES
- REDUCE supplies REDUCE
- SUBSTITUTE supplies SUBSTITUTE-* and NSUBSTITUTE-*
- ADDEDTAA supplies GENERIC
- TIMES supplies TIME GET-INTERNAL-RUN-TIME GET-INTERNAL-REAL-TIME
and the constant INTERNAL-TIME-UNITS-PER-SECOND
- RANDOM supplies RANDOM-NUMBER-STATE type, *RANDOM-STATE*, and the
function MAKE-RANDOM-STATE. Requires TIMES.
- HASHFCNS supplies SETHASH MAKE-HASH-TABLE REMHASH MAPHASH CLRHASH
and HASH-TABLE-COUNT
- SETS supplies ADJOIN UNION INTERSECTION SET-DIFFERENCE and
SUBSETP
- SAVERESTORE supplies SAVE and RESTORE
- GRAPHICS supplies graphic functions (when available)
2. Features (all turned on by default)
- COMPLX adds complex number support including math functions
COMPLEX COMPLEXP IMAGPART REALPART CONJUGATE PHASE LOG FLOOR
CEILING ROUND PI LCM and ASH
- BIGNUMS adds bignum, ratio, and read/print radix support.
Requires COMPLX.
- NOOVFIXNUM Check for fixnum overflow, and convert to flonum (only
applies if BIGNUMS not used)
- PACKAGES uses the packages implementation. Some people find XLISP
PLUS easier to use if this is not defined.
- MULVALS multiple value returns
- FILETABLE files referenced via a table -- allows saving and
restoring open files (in WKS files), and is required by Microsoft
Windows versions. Also allows functions TRUENAME and DELETE-FILE.
- KEYARG adds :key keyword option to functions having it
- FROMEND adds the :from-end and :count keywords to functions
having them
- AOKEY makes &allow-other-keys functional. Without this option,
all functions behave as though &allow-other-keys is always
specified.
- APPLYHOOK adds applyhook support
3. Backwards compatibility
- OLDERRORS makes CERROR and ERROR work as in XLISP-PLUS 2.1e or
earlier, which is not compatible with more recent versions (or
Common Lisp)
- LEXBIND lexical tag scoping for TAGBODY/GO and BLOCK/RETURN, as
in Common Lisp. If not defined, then the original dynamic scoping
is used.
4. Environmental options
XLISP-PLUS 3.0 COMPILATION OPTIONS Page 110
- ASCII8 eight bit ASCII character support
- ANSI8 used in addition to ASCII8 for MS Windows character code
page
- READTABLECASE adds *readtable-case* and its functionality
- PATHNAMES allows environment variable to specify search path for
RESTORE and LOAD functions
- BIGENDIANFILE binary files use "bigendian" orientation. Normally
this option is defined when BIGENDIAN (required on bigendian
systems) is defined, but this has been made a separate option to
allow file portability between systems.
5. Performance options
- JMAC increases performance slightly, except on 16 bit DOS
environments.
- GENERIC use generic bignum to float conversion. Required for
bigendian or non IEEE floating point systems (such as Macs).
Using this selection decreases precision and increases execution
time.
In addition, there are options for various stack sizes, static fixnum
values, and various allocation sizes that can be altered. They have been
set optimally for each compiler/environment and "typical" applications.
XLISP-PLUS 3.0 BUG FIXES AND EXTENSIONS Page 111
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-PLUS 3.0 BUG FIXES AND EXTENSIONS Page 112
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-PLUS 3.0 BUG FIXES AND EXTENSIONS Page 113
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.
Reader macro #nR added. Added *READ-BASE* to control default read radix.
Numeric input is now Common Lisp compliant.
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 rational or real. (Older versions
allowed fixnum or real.)
bignums -- new type.
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
XLISP-PLUS 3.0 BUG FIXES AND EXTENSIONS Page 114
New Variables and Constants
*apply-hook* Now activated
*command-line*
*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
*read-base*
*print-base*
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
COUNT-IF-NOT CL
DECF CL*
DECLARE *
XLISP-PLUS 3.0 BUG FIXES AND EXTENSIONS Page 115
DEFCLASS * (define a new class)
DEFINST * (define a new instance)
DEFMETHOD * (define a new method)
DEFPACKAGE CL*
DEFSETF CL*
DELETE-FILE CL
DELETE-PACKAGE CL
DENOMINATOR CL
DESCRIBE CL*
DO-ALL-SYMBOLS CL*
DO-EXTERNAL-SYMBOLS CL*
DO-SYMBOLS CL*
DOCUMENTATION 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
FIND-IF-NOT CL
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
INSPECT CL*
INTEGER-LENGTH CL
INTERSECTION CL
LCM CL
LIST* CL
LIST-ALL-PACKAGES CL
LIST-LENGTH CL
LOG CL
LOGANDC1 CL
LOGANDC2 CL
LOGBITP CL
LOGCOUNT CL
XLISP-PLUS 3.0 BUG FIXES AND EXTENSIONS Page 116
LOGEQV CL
LOGNAND CL
LOGNOR CL
LOGORC1 CL
LOGORC2 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
MULTIPLE-VALUE-SETQ CL*
NINTERSECTION CL*
NTH-VALUE
NOTANY CL
NOTEVERY CL
NREVERSE CL
NSET-DIFFERENCE CL*
NSET-EXCLUSIVE-OR CL*
NSTRING-CAPITALIZE CL
NSUBSTITUTE CL
NSUBSTITUTE-IF CL
NSUBSTITUTE-IF-NOT 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
POSITION-IF-NOT CL
PROCLAIM *
PSETF CL
PUSH CL*
PUSHNEW CL*
RATIONAL CL
RATIONALP CL
REALPART CL
XLISP-PLUS 3.0 BUG FIXES AND EXTENSIONS Page 117
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
STABLE-SORT CL
STRING-CAPITALIZE CL
SUBSETP CL
SUBSTITUTE CL
SUBSTITUTE-IF CL
SUBSTITUTE-IF-NOT CL
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
XLISP-PLUS 3.0 BUG FIXES AND EXTENSIONS Page 118
/ 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 :count :from-end. Works on arrays
and strings)
DELETE-IF (added keywords :key :start :end :count :from-end. Works on
arrays and strings)
DELETE-IF-NOT (added keywords :key :start :end :count :from-end. Works on
arrays and strings)
DIGIT-CHAR CL (added optional radix argument)
DIGIT-CHAR-P CL (added optional radix argument)
ERROR CL
EXP CL CR CX
EXPT CL CR CX
FMAKUNBOUND #
FORMAT (added directives # ~B ~D ~E ~F ~G ~O ~R ~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)
XLISP-PLUS 3.0 BUG FIXES AND EXTENSIONS Page 119
PEEK (fixnum sized location is fetched)
PEEK-CHAR CL (input stream NIL is *standard-input*, T is *terminal-io*, eof
arguments)
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
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 :count :from-end. Works on arrays
and strings)
REMOVE-IF (added keywords :key :start :end :count :from-end. Works on
arrays and strings)
REMOVE-IF-NOT (added keywords :key :start :end :count :from-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)
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
WRITE-CHAR CL (output stream NIL is *standard-output*, T is *terminal-io*)
XLISP-PLUS 3.0 BUG FIXES AND EXTENSIONS Page 120
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-PLUS 3.0 EXAMPLES Page 121
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-PLUS 3.0 EXAMPLES Page 122
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-PLUS 3.0 INDEX Page 123
INDEX
:allow-other-keys 18 :set-pname 70
:answer 23 :show 22
:append 91 :size 40
:capitalize 15 :start 43-47, 63, 64, 85, 93
:class 22 :start1 43, 47, 48, 64, 65
:conc-name 68 :start2 43, 47, 48, 64, 65
:constituent 13 :storeon 22, 23
:count 43, 45, 46 :superclass 22, 23
:create 91 :supersede 91
:direction 91 :test 33, 40, 43-46, 48, 50,
:downcase 15 51, 52, 53, 75
:element-type 91 :test-not 33, 43-46, 48, 50,
:end 43-47, 63, 64, 85, 93 51, 52, 53, 75
:end1 43, 47, 48, 64, 65 :tmacro 13
:end2 43, 47, 48, 64, 65 :upcase 15
:error 91 :use 36
:external 30, 36 :verbose 98
:from-end 43-46 :white-space 13
:if-does-not-exist 91 + 26, 55
:if-exists 91 ++ 26
:include 68 +++ 26
:inherited 30, 36 - 26, 56
:initial-contents 41 * 26, 56
:initial-element 41, 47, 52, ** 26
64 *** 26
:initial-value 46 *applyhook* 9, 25
:input 91 *breakenable* 4, 25
:internal 30, 36 *command-line* 26
:invert 15 *debug-io* 25
:io 91 *displace-macros* 8, 26
:iskindof 22 *dos-input* 3, 26
:ismemberof 22 *error-output* 25
:isnew 22, 23 *evalhook* 9, 25
:key 33, 43-47, 50-53, 75 *features* 14, 26
:mescape 13 *float-format* 26, 83
:messages 23 *gc-flag* 25
:new 23 *gc-hook* 9, 25
:new-version 91 *integer-format* 26, 83
:nicknames 36 *load-file-arguments* 2, 26
:nmacro 13 *obarray* 25
:output 91 *package* 25
:overwrite 91 *print-base* 26, 83
:preserve 15 *print-case* 15, 26, 83
:prin1 22 *print-length* 26, 83
:print 98 *print-level* 26, 83
:print-function 68 *random-state* 26
:probe 91 *ratio-format* 83
:rename 91 *read-base* 10
:rename-and-delete 91 *read-suppress* 26
:respondsto 22 *readtable-case* 15, 26, 83
:sescape 13 *readtable* 13, 25
:set-ivar 70 *standard-input* 25
XLISP-PLUS 3.0 INDEX Page 124
*standard-output* 25 backquote 27
*startup-functions* 2, 26 baktrace 96
*struct-slots* 68 block 81
*terminal-io* 25 both-case-p 66
*top-level-loop* 26 boundp 74
*trace-output* 25 break 95
*tracelimit* 4, 25 butlast 50
*tracelist* 25 byte 61
*tracenable* 4, 25 byte-position 61
/ 56 byte-size 61
/= 59 car 49
< 59 case 78
<= 59 catch 78
= 59 ccase 96
> 59 cdr 49
>= 59 ceiling 55
%DOC-FUNCTION 106 cerror 95
%DOC-STRUCTURE 106 char 66
%DOC-TYPE 106 char-code 66
%DOC-VARIABLE 106 char-downcase 66
&allow-other-keys 18 char-equal 67
&aux 18 char-greaterp 67
&key 18 char-int 67
&optional 18 char-lessp 67
&rest 18 char-name 67
1+ 56 char-not-equal 67
1- 56 char-not-greaterp 67
abs 56 char-not-lessp 67
acons 49 char-upcase 66
acos 57 char/= 67
acosh 58 char< 67
address-of 100 char<= 67
adjoin 53 char= 67
alloc 99 char> 67
alpha-char-p 66 char>= 67
and 76, 77 character 67, 100
append 49 characterp 73
apply 27 check-type 97
applyhook 9, 96 cis 58
apropos 35 class 25
apropos-list 35 classp 74
aref 41 clean-up 3, 95
ARRAY 100 clean-up, 4
array-in-bounds-p 73 close 92
arrayp 73 CLOSURE 100
ash 61 clrhash 40
asin 57 cls 102
asinh 58 code-char 66
assert 97 coerce 100
assoc 51 color 102
assoc-if 51 comma 27
assoc-if-not 51 comma-at 28
atan 57 complement 27
atanh 58 complex 59, 100
atom 72, 76 complexp 73
XLISP-PLUS 3.0 INDEX Page 125
concatenate 42 draw 103
cond 77 drawrel 103
conjugate 59 dribble 98
cons 49, 100 ecase 96
consp 72 eighth 49
constantp 72 elt 42
continue 3, 4, 95 endp 72
copy-alist 52 eq 75
copy-list 52 eql 75
copy-seq 47 equal 75
copy-symbol 32 equalp 75
copy-tree 52 error 95
cos 57 errset 4, 95
cosh 58 etypecase 96
count 44 eval 27
count-if 44 eval-when 102
count-if-not 44 evalhook 9, 96
ctypecase 96 evenp 74
cxxr 49 every 42
cxxxr 49 exit 101
cxxxxr 49 exp 58
debug 96 expand 99
decf 34 export 36
declare 32 expt 58
defclass 70 fboundp 74
defconstant 31 fifth 49
definst 71 file-length 93
defmacro 30 file-position 93
defmethod 70 FILE-STREAM 100
defpackage 35 fill 47
defparameter 31 find 44
defsetf 33 find-all-symbols 36
defstruct 68 find-if 44
defun 30 find-if-not 44
defvar 31 find-package 36
delete 45 find-symbol 36
delete-duplicates 46 first 49
delete-file 92 FIXNUM 100
delete-if 45 flatc 84
delete-if-not 45 flatsize 84
delete-package 35 flet 78
denominator 58 float 55
deposit-field 62 float-sign 57
describe 107 floatp 72
digit-char 67 FLONUM 100
digit-char-p 66 floor 55
do 80 fmakunbound 31
do-all-symbols 36 format 86
do-external-symbols 36 fourth 49
do-symbols 36 fresh-line 84
do* 80 FSUBR 100
documentation 106 funcall 27
dolist 80 function 27, 76
dotimes 80 functionp 74
dpb 62 gc 99
XLISP-PLUS 3.0 INDEX Page 126
gcd 57 log 58
generic 101 logand 60
gensym 30 logandc1 60
get 39 logandc2 60
get-internal-real-time 100 logbitp 61
get-internal-run-time 100 logcount 61
get-key 101 logeqv 60
get-lambda-expression 28 logior 60
get-macro-character 83 lognand 60
get-output-stream-list 94 lognor 60
get-output-stream-string 94 lognot 60
getf 39 logorc1 60
gethash 40 logorc2 60
glos 106 logtest 60
go 81 logxor 60
goto-xy 102 loop 80
hash 31 lower-case-p 66
HASH-TABLE 100 macroexpand 28
hash-table-count 40 macroexpand-1 28
hash-table-p 74 macrolet 78
identity 27 make-array 41
if 77 make-hash-table 40
imagpart 59 make-package 36
import 36 make-random-state 57
in-package 36 make-sequence 47
incf 34 make-string 64
input-stream-p 73 make-string-input-stream 94
ins 107 make-string-output-stream 94
insf 107 make-symbol 30
inspect 107 makunbound 31
int-char 67 map 42
integer-length 61 map-into 42
integerp 72 mapc 51
intern 30 mapcan 51
internal-time-units-per-second mapcar 51
25 mapcon 51
intersection 53 maphash 40
isqrt 58 mapl 51
keywordp 74 maplist 51
labels 78 mark-as-special 32
lambda 28 mask-field 62
last 50 max 56
lcm 57 member 50, 76
ldb 61 member-if 50
ldb-test 61 member-if-not 50
ldiff 53 merge 47
length 42 min 56
let 78 minusp 74
let* 78 mismatch 48
list 49, 76, 100 mod 56
list-all-packages 36 mode 102
list-length 50 move 103
list* 49 moverel 103
listp 72 multiple-value-bind 29
load 98 multiple-value-call 29
XLISP-PLUS 3.0 INDEX Page 127
multiple-value-list 29 pop 34
multiple-value-prog1 29 position 44
multiple-value-setq 29 position-if 44
nbutlast 50 position-if-not 44
nconc 54 pp 105
NIL 25 pprint 84
nintersection 53 prin1 83
ninth 49 prin1-to-string 84
nodebug 96 princ 84
not 72, 76 princ-to-string 84
notany 42 print 83
notevery 42 probe-file 92
nreconc 54 proclaim 32
nreverse 42 prog 81
nset-difference 53 prog* 81
nset-exclusive-or 53 prog1 81
nstring-capitalize 64 prog2 82
nstring-downcase 64 progn 82
nstring-upcase 63 progv 81
nsubst 51 psetf 33
nsubst-if 51 psetq 30
nsubst-if-not 51 push 33
nsubstitute 46 pushnew 33
nsubstitute-if 46 putprop 39
nsubstitute-if-not 46 quote 27
nth 50 random 57
nth-value 29 rassoc 51
nthcdr 50 rassoc-if 51
null 72, 76 rassoc-if-not 51
NUMBER 76 RATIO 100
numberp 72 rational 55, 76
numerator 58 rationalp 73
nunion 53 read 83
object 25, 76, 100 read-byte 92
objectp 73 read-char 89
oddp 74 read-from-string 85
open 91 read-line 90
open-stream-p 73 realp 73
or 76, 77 realpart 59
output-stream-p 73 reduce 46
package-name 37 rem 56
package-nicknames 37 remf 39
package-obarray 37 remhash 40
package-shadowingsymbols 37 remove 43
package-use-list 37 remove-duplicates 46
package-used-by-list 37 remove-if 43
package-valid-p 37 remove-if-not 43
packagep 74 remprop 39
pairlis 52 rename-package 37
peek 100 replace 47
peek-char 89 reset-system 101
phase 59 rest 49
pi 25 restore 98
plusp 74 return 81
poke 100 return-from 81
XLISP-PLUS 3.0 INDEX Page 128
revappend 50 string>= 64
reverse 42 stringp 73
room 99 STRUCT 76
round 55 sublis 52
rplaca 54 SUBR 100
rplacd 54 subseq 43
satisfies 76 subsetp 75
save 98 subst 51
search 43 substitute 45
second 49 substitute-if 45
self 21, 25 substitute-if-not 45
send 21, 70 SYMBOL 100
send-super 21, 70 symbol-function 31
set 30 symbol-name 30
set-difference 53 symbol-package 37
set-exclusive-or 53 symbol-plist 31
set-macro-character 83 symbol-value 30
set-stack-mark 101 symbolp 72
setf 33 system 101
setq 30 t 25
seventh 49 tagbody 81
shadow 37 tailp 50
shadowing-import 37 tan 57
signum 57 tanh 58
sin 57 tenth 49
sinh 58 terpri 84
sixth 49 third 49
sleep 99 throw 79
some 42 time 99
sort 43 top-level 3, 95
specialp 72 top-level-loop 2, 101
sqrt 58 trace 95
stable-sort 43 tracemethod 71
step 104 truename 92
strcat 64 truncate 55
STREAM 76 type-of 100
streamp 73 typecase 78, 96
string 63, 100 typep 76
string-capitalize 63 unexport 38
string-downcase 63 union 53
string-equal 65 unless 77
string-greaterp 65 UNNAMED-STREAM 100
string-left-trim 63 untrace 95
string-lessp 65 untracemethod 71
string-not-equal 65 unuse-package 38
string-not-greaterp 65 unwind-protect 79
string-not-lessp 65 upper-case-p 66
string-right-trim 63 use-package 38
string-trim 63 values 29
string-upcase 63 values-list 29
string/= 64 vector 41
string< 64 when 77
string<= 64 with-input-from-string 94
string= 64 with-open-file 92
string> 64 with-open-stream 92
XLISP-PLUS 3.0 INDEX Page 129
with-output-to-string 94
write-byte 92
write-char 89
XLPATH 98
y-or-n-p 84
yes-or-no-p 84
zerop 74
