XLISP-PLUS: Another Object-oriented Lisp Version 2.1e September 11, 1992 Tom Almy tom.almy@tek.com Portions of this manual and software are from XLISP which is Copyright (c) 1988, by David Michael Betz, all rights reserved. Mr. Betz grants permission for unrestricted non-commercial use. Portions of XLISP-PLUS from XLISP-STAT are Copyright (c) 1988, Luke Tierney. UNIXSTUF.C is from Winterp 1.0, Copyright 1989 Hewlett-Packard Company (by Niels Mayer). Other enhancements and bug fixes are provided without restriction by Tom Almy, Mikael Pettersson, Neal Holtz, Johnny Greenblatt, Ken Whedbee, Blake McBride, and Pete Yadlowsky. See source code for details. Table of Contents INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 XLISP COMMAND LOOP . . . . . . . . . . . . . . . . . . . . . . . . . . 2 BREAK COMMAND LOOP . . . . . . . . . . . . . . . . . . . . . . . . . . 4 DATA TYPES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 THE EVALUATOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 HOOK FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 LEXICAL CONVENTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . 9 8 BIT ASCII CHARACTERS . . . . . . . . . . . . . . . . . . . . . . . . 11 READTABLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 SYMBOL CASE CONTROL . . . . . . . . . . . . . . . . . . . . . . . . . . 14 LAMBDA LISTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 OBJECTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 SYMBOLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 EVALUATION FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 24 SYMBOL FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 PROPERTY LIST FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . 30 HASH TABLE FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 31 ARRAY FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 SEQUENCE FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . 33 LIST FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 DESTRUCTIVE LIST FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . 42 ARITHMETIC FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . 43 BITWISE LOGICAL FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . 48 STRING FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 CHARACTER FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . 51 STRUCTURE FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . 53 XLISP 2.1e Table of Contents OBJECT FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 PREDICATE FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . 57 CONTROL CONSTRUCTS . . . . . . . . . . . . . . . . . . . . . . . . . . 61 LOOPING CONSTRUCTS . . . . . . . . . . . . . . . . . . . . . . . . . . 64 THE PROGRAM FEATURE . . . . . . . . . . . . . . . . . . . . . . . . . . 65 INPUT/OUTPUT FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . 67 THE FORMAT FUNCTION . . . . . . . . . . . . . . . . . . . . . . . . . . 69 FILE I/O FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . 71 STRING STREAM FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . 75 DEBUGGING AND ERROR HANDLING FUNCTIONS . . . . . . . . . . . . . . . . 77 SYSTEM FUNCTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 ADDITIONAL FUNCTIONS AND UTILITIES . . . . . . . . . . . . . . . . . . 84 BUG FIXES AND EXTENSIONS . . . . . . . . . . . . . . . . . . . . . . . 88 EXAMPLES: FILE I/O FUNCTIONS . . . . . . . . . . . . . . . . . . . . . 96 INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 XLISP 2.1e 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 proved (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 88 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 toma@sail.labs.tek.com. You can also reach Tom by writing to him at 17830 SW Shasta Trail, Tualatin, OR 97062, USA. XLISP 2.1e 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 providing no workspace file was loaded, XLISP attempts to load "init.lsp" from the current directory. It then loads any files named as parameters on the command line (after appending ".lsp" to their names). 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". XLISP then issues the following prompt (unless standard input has been redirected): > This indicates that XLISP is waiting for an expression to be typed. When a complete expression has been entered, XLISP attempts to evaluate that expression. If the expression evaluates successfully, XLISP prints the result and then returns 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 the following control characters can be typed while XLISP is executing (providing standard input has not been redirected away from the console): ctrl-B BREAK -- enter break loop ctrl-S Pause until another key is struck ctrl-C go to top level (if lucky: ctrl-B,ctrl-C is safer) 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 XLISP 2.1e XLISP COMMAND LOOP Page 3 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. XLISP 2.1e BREAK COMMAND LOOP Page 4 BREAK COMMAND LOOP When XLISP encounters an error while evaluating an expression, it attempts to handle the error in the following way: If the symbol '*breakenable*' is true, the message corresponding to the error is printed. If the error is correctable, the correction message is printed. If the symbol '*tracenable*' is true, a trace back is printed. The number of entries printed depends on the value of the symbol '*tracelimit*'. If this symbol is set to something other than a number, the entire trace back stack is printed. XLISP then enters a read/eval/print loop to allow the user to examine the state of the interpreter in the context of the error. This loop differs from the normal top-level read/eval/print loop in that if the user invokes the function 'continue', XLISP will continue from a correctable error. If the user invokes the function 'clean-up', XLISP will abort the break loop and return to the top level or the next lower numbered break loop. When in a break loop, XLISP prefixes the break level to the normal prompt. If the symbol '*breakenable*' is NIL, XLISP looks for a surrounding errset function. If one is found, XLISP examines the value of the print flag. If this flag is true, the error message is printed. In any case, XLISP causes the errset function call to return NIL. If there is no surrounding errset function, XLISP prints the error message and returns to the top level. If XLISP was invoked with the command line argument "-b" then XLISP assumes it is running in batch mode. In batch mode any uncaught error will cause XLISP to exit after printing the error message. XLISP 2.1e DATA TYPES Page 5 DATA TYPES There are several different data types available to XLISP-PLUS programmers. Typical implementation limits are shown for 32 bit word systems. Values in square brackets apply to 16 bit MS-DOS implementations. All data nodes are effectively cons cells consisting of two pointers and and one or two bytes of identification flags (9 or 10 bytes per cell). Node space is managed and garbage collected by XLISP. Array and string storage is either allocated by the C runtime or managed and garbaged collected by XLISP (compilation option). If C does the allocation, memory fragmentation can occur. Fragmentation can be eliminated by saving the image and restarting XLISP-PLUS. NIL Unlike the original XLISP, NIL is a symbol (although not in the *obarray*), to allowing setting its properties. lists Either NIL or a CDR-linked list of cons cells, terminated by a symbol (typically NIL). Circular lists are allowable, but can cause problems with some functions so they must be used with care. arrays The CDR field of an array points to the dynamically allocated data array, while the CAR contains the integer length of the array. Elements in the data array are pointers to other cells [Size limited to about 16360]. character strings Implemented like arrays, except string array is byte indexed and contains the actual characters. Note that unlike the underlying C, the null character (value 0) is valid. [Size limited to about 65500] symbols Implemented as a 4 element array. The elements are value cell, function cell, property list, and print name (a character string node). Print names are limited to 100 characters. There are also flags for constant and special. Values bound to special symbols (declared with DEFVAR or DEFPARAMETER) are always dynamically bound, rather than being lexically bound. fixnums (integers) Small integers (> -129 and <256) are statically allocated and are thus always EQ integers of the same value. The CAR field is used to hold the value, which is a 32 bit signed integer. ratios The CAR field is used to hold the numerator while the CDR field is used to hold the denominator. The numerator is a 32 bit signed value while the denominator is a 31 bit positive value. characters All characters are statically allocated and are thus EQ characters of the same value. The CAR field is used to hold the value. In XLISP characters are "unsigned" and thus range in value from 0 to 255. XLISP 2.1e DATA TYPES Page 6 flonums (floating point numbers) The CAR and CDR fields hold the value, which is typically a 64 bit IEEE floating point number. complex numbers Part of the math extension compilation option. Internally implemented as an array of the real and imaginary parts. The parts can be either both fixnums or both flonums. Any function which would return an fixnum complex number with a zero imaginary part returns just the fixnum. objects Implemented as an array of instance variable count plus one elements. The first element is the object's class, while the remaining arguments are the instance variables. streams (file) The CAR and CDR fields are used in a system dependent way as a file pointer. streams (unnamed -- string) Implemented as a tconc-style list of characters. subrs (built-in functions) The CAR field points to the actual code to execute, while the CDR field is an internal pointer to the name of the function. fsubrs (special forms) Same implementation as subrs. closures (user defined functions) Implemented as an array of 11 elements: 1. name symbol or NIL 2. 'lambda or 'macro 3. list of required arguments 4. optional arguments as list of ( ) triples. 5. &rest argument 6. &key arguments as list of ( ) quadruples. 7. &aux arguments as list of ( ) pairs. 8. function body 9. value environment (see page 78 for format) 10. function environment 11. argument list (unprocessed) structures Implemented as an array with first element being a pointer to the structure name string, and the remaining elements being the structure elements. hash-tables Implemented as a structure of varying length with no generalized accessing functions, but with a special print function (print functions not available for standard structures). random-states Implemented as a structure with a single element which is the random state (here a fixnum, but could change without impacting xlisp programs). XLISP 2.1e THE EVALUATOR Page 7 THE EVALUATOR The process of evaluation in XLISP: Strings, characters, numbers of any type, objects, arrays, structures, streams, subrs, fsubrs and closures evaluate to themselves. Symbols act as variables and are evaluated by retrieving the value associated with their current binding. Lists are evaluated by examining the first element of the list and then taking one of the following actions: If it is a symbol, the functional binding of the symbol is retrieved. If it is a lambda expression, a closure is constructed for the function described by the lambda expression. If it is a subr, fsubr or closure, it stands for itself. Any other value is an error. Then, the value produced by the previous step is examined: If it is a subr or closure, the remaining list elements are evaluated and the subr or closure is applied to these evaluated expressions. If it is an fsubr, the fsubr is called with the remaining list elements as arguments (unevaluated). If it is a macro, the macro is expanded with the remaining list elements as arguments (unevaluated). The macro expansion is then evaluated in place of the original macro call. If the symbol *displace-macros* is not NIL, then the expanded macro will (destructively) replace the original macro expression. This means that the macro will only be expanded once, but the original code will be lost. The displacement will not take place unless the macro expands into a list. The standard XLISP practice is the macro will be expanded each time the expression is evaluated, which negates some of the advantages of using macros. XLISP 2.1e HOOK FUNCTIONS Page 8 HOOK FUNCTIONS The evalhook and applyhook facility are useful for implementing debugging programs or just observing the operation of XLISP. It is possible to control evaluation of forms in any context. If the symbol '*evalhook*' is bound to a function closure, then every call of eval will call this function. The function takes two arguements, the form to be evaluated and execution environment. During the execution of this function, *evalhook* (and *applyhook*) are dynamically bound to NIL to prevent undesirable recursion. This "hook" function returns the result of the evaluation. If the symbol '*applyhook*' is bound to a function, then every function application within an eval will call this function (note that the function apply, and others which do not use eval, will not invoke the apply hook function). The function takes two arguments, the function closure and the argument list (which is already evaluated). During execution of this hook function, *applyhook* (and *evalhook*) are dynamically bound to NIL to prevent undesired recursion. This function is to return the result of the function application. Note that the hook functions cannot reset *evalhook* or *applyhook* to NIL, because upon exit these values will be reset. An excape mechanism is provided -- execution of 'top-level', or any error that causes return to the top level, will unhook the functions. Applications should bind these values either via 'progv', 'evalhook', or 'applyhook'. The functions 'evalhook' and 'applyhook' allowed for controlled application of the hook functions. The form supplied as an argument to 'evalhook', or the function application given to 'applyhook', are not hooked themselves, but any subsidiary forms and applications are. In addition, by supplying NIL values for the hook functions, 'evalhook' can be used to execute a form within a specific environment passed as an argument. An additional hook function exists for the garbage collector. If the symbol '*gc-hook*' is bound to a function, then this function is called after every garbage collection. The function has two arguments. The first is the total number of nodes, and the second is the number of nodes free. The return value is ignored. During the execution of the function, *gc-hook* is dynamically bound to NIL to prevent undesirable recursion. XLISP 2.1e LEXICAL CONVENTIONS Page 9 LEXICAL CONVENTIONS The following conventions must be followed when entering XLISP programs: Comments in XLISP code begin with a semi-colon character and continue to the end of the line. Except when escape sequences are used, symbol names in XLISP can consist of any sequence of non-blank printable characters except the terminating macro characters: ( ) ' ` , " ; and the escape characters: \ | In addition, the first character may not be '#' (non-terminating macro character), nor may the symbol have identical syntax with a numeric literal. Uppercase and lowercase characters are not distinguished within symbol names because, by default, lowercase characters are mapped to uppercase on input. Any printing character, including whitespace, may be part of a symbol name when escape characters are used. The backslash escapes the following character, while multiple characters can be escaped by placing them between vertical bars. At all times the backslash must be used to escape either escape characters. For semantic reasons, certain chararacter sequences should/can never be used as symbols in XLISP. A single period is used to denote dotted lists. The symbol NIL represents an empty list. Symbols starting with a colon are keywords, and will always evaluate to themselves. Thus they should not be used as regular symbols. The symbol T is also reserved for use as the truth value. Fixnum (integer) literals consist of a sequence of digits optionally beginning with a sign ('+' or '-'). The range of values an integer can represent is limited by the size of a C 'long' on the machine on which XLISP is running. Ratio literals consist of two integer literals separated by a slash character ('/'). The second number, the denominator, must be positive. Ratios are automatically reduced to their cannonical form; if they are integral, then they are reduced to an integer. Flonum (floating point) literals consist of a sequence of digits optionally beginning with a sign ('+' or '-') and including one or both of an embedded decimal point or a trailing exponent. The optional exponent is denoted by an 'E' or 'e' followed by an optional sign and one or more digits. The XLISP 2.1e LEXICAL CONVENTIONS Page 10 range of values a floating point number can represent is limited by the size of a C 'double' on most machines on which XLISP is running. Numeric literals cannot have embedded escape characters. If they do, they are treated as symbols. Thus '12\3' is a symbol even though it would appear to be identical to '123'. Complex literals are constructed using a read-macro of the format #C(r i), where r is the real part and i is the imaginary part. The numeric fields can be any valid fixnum, ratio, or flonum literal. If either field has a ratio or flonum literal, then both values are converted to flonums. Fixnum complex literals with a zero imaginary part are automatically reduced to fixnums. Character literals are handled via the #\ read-macro construct: #\ == the ASCII code of the printing character #\newline == ASCII linefeed character #\space == ASCII space character #\rubout == ASCII rubout (DEL) #\C- == ASCII control character #\M- == ASCII character with msb set (Meta character) #\M-C- == ASCII control character with msb set Literal strings are sequences of characters surrounded by double quotes (the " read-macro). Within quoted strings the '\' character is used to allow non-printable characters to be included. The codes recognized are: \\ means the character '\' \n means newline \t means tab \r means return \f means form feed \nnn means the character whose octal code is nnn XLISP 2.1e 8 BIT ASCII CHARACTERS Page 11 8 BIT ASCII CHARACTERS When used in an IBM PC environment (or perhaps others), XLISP-PLUS is compiled by default to allow the full use of the IBM 8 bit ASCII character set, including all characters with diacritic marks. Note that using such characters will make programs non-portable. XLISP-PLUS can be compiled for standard 7 bit ASCII if desired for portability. When 8 bit ASCII is enabled, the following system characteristics change: Character codes 128 to 254 are marked as :constituent in the readtable. This means that any of the new characters (except for the nonprinting character 255) can be symbol constituent. Alphabetic characters which appear in both cases, such as and , are considered to be alphabetical for purposes of symbol case control, while characters such as that have no coresponding upper case are not considered to be alphabetical. The reader is extended for the character data type to allow all the additional characters (except code 255) to be entered literally, for instance "#\". These characters are also printed literally, rather than using the "M-" construct. Code 255 must still be entered as, and will be printed as, "#\M-Rubout". Likewise strings do not need and will not use the backslash escape mechanism for codes 128 to 254. The functions alphanumericp, alpha-char-p, upper-case-p, and lower-case-p perform as would be expected on the extended characters, treating the diacritic characters as their unadorned counterparts. As per the Common Lisp definition, both-case-p will only indicate T for characters available in both cases. XLISP 2.1e READTABLES Page 12 READTABLES The behaviour of the reader is controlled by a data structure called a "readtable". The reader uses the symbol *readtable* to locate the current readtable. This table controls the interpretation of input characters -- if it is changed then the section LEXICAL CONVENTIONS may not apply. The readtable is an array with 256 entries, one for each of the extended ASCII character codes. Each entry contains one of the following values, with the initial entries assigned to the values indicated: :white-space A whitespace character - tab, cr, lf, ff, space (:tmacro . fun) terminating readmacro - ( ) " , ; ' ` (:nmacro . fun) non-terminating readmacro - # :sescape Single escape character - \ :mescape Multiple escape character - | :constituent Indicating a symbol constituent (all printing characters not listed above) NIL Indicating an invalid character (everything else) In the case of :TMACRO and :NMACRO, the "fun" component is a function. This can either be a built-in readmacro function or a lambda expression. The function takes two parameters. The first is the input stream and the second is the character that caused the invocation of the readmacro. The readmacro function should return NIL to indicate that the character should be treated as white space or a value consed with NIL to indicate that the readmacro should be treated as an occurance of the specified value. Of course, the readmacro code is free to read additional characters from the input stream. A :nmacro is a symbol constituent except as the first character of a symbol. As an example, the following read macro allows the square brackets to be used as a more visibly appealing alternative to the SEND function: (setf (aref *readtable* (char-int #\[)) ; #\[ table entry (cons :tmacro (lambda (f c &aux ex) ; second arg is not used (do () ((eq (peek-char t f) #\])) (setf ex (append ex (list (read f))))) (read-char f) ; toss the trailing #\] (cons (cons 'send ex) NIL)))) (setf (aref *readtable* (char-int #\])) (cons :tmacro (lambda (f c) (error "misplaced right bracket")))) XLISP 2.1e READTABLES Page 13 XLISP defines several useful read macros: ' == (quote ) ` == (backquote ) , == (comma ) ,@ == (comma-at ) #' == (function ) #(...) == an array of the specified expressions #S( [ ]...) == structure of specified type and initial values #. == result of evaluating #x == a hexadecimal number (0-9,A-F) #o == an octal number (0-7) #b == a binary number (0-1) #| |# == a comment #: == an uninterned symbol #C(r i) == a complex number #+ == conditional on feature expression true #- == 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. Utility files supplied with XLISP-PLUS generally add new features which are EQ to the keyword made from their file names. XLISP 2.1e SYMBOL CASE CONTROL Page 14 SYMBOL CASE CONTROL XLISP-PLUS uses two variables, *READTABLE-CASE* and *PRINT-CASE* to deturmine case conversion during reading and printing of symbols. *READTABLE-CASE* can have the values :UPCASE :DOWNCASE :PRESERVE or :INVERT, while *PRINT-CASE* can have the values :UPCASE or :DOWNCASE. 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 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 four major useful combinations of these modes: A: *READTABLE-CASE* :UPCASE *PRINT-CASE* :UPCASE "Traditional" mode. Case insensitive input; must escape to put lowercase characters in symbol names. Symbols print exactly as they are stored, with lowercase characters escaped when PRIN1 is used. B: *READTABLE-CASE* :UPCASE *PRINT-CASE* :DOWNCASE "Eyesaver" mode. Case insensitive input; must escape to put lowercase characters in symbol name. Symbols print entirely in lowercase except symbols escaped when lowercase characters present with PRIN1. C: *READTABLE-CASE* :PRESERVE "Oldfashioned case sensitive" mode. Case sensitive input. Predefined symbols must be typed in uppercase. No alpha quoting needed. Symbols print exactly as stored. XLISP 2.1e SYMBOL CASE CONTROL Page 15 D: *READTABLE-CASE* :INVERT "Modern case sensitive" mode. Case sensitive input. Predefined symbols must be typed in lowercase. Alpha quoting should be avoided. Predefined symbols print in lower case, other symbols print as they were entered. As far as compatibility between these modes are concerned, data printed in mode A can be read in A, B, or C. Data printed in mode B can be read in A, B, and D. Data printed in mode C can be read in mode C, and if no lowercase symbols in modes A and B as well. Data printed in mode D can be read in mode D, and if no (internally) lowercase symbols in modes A and B as well. In addition, symbols containing characters requiring quoting are compatible among all modes. XLISP 2.1e LAMBDA LISTS Page 16 LAMBDA LISTS There are several forms in XLISP that require that a "lambda list" be specified. A lambda list is a definition of the arguments accepted by a function. There are four different types of arguments. The lambda list starts with required arguments. Required arguments must be specified in every call to the function. The required arguments are followed by the &optional arguments. Optional arguments may be provided or omitted in a call. An initialization expression may be specified to provide a default value for an &optional argument if it is omitted from a call. If no initialization expression is specified, an omitted argument is initialized to NIL. It is also possible to provide the name of a 'supplied-p' variable that can be used to determine if a call provided a value for the argument or if the initialization expression was used. If specified, the supplied-p variable will be bound to T if a value was specified in the call and NIL if the default value was used. The &optional arguments are followed by the &rest argument. The &rest argument gets bound to the remainder of the argument list after the required and &optional arguments have been removed. The &rest argument is followed by the &key arguments. When a keyword argument is passed to a function, a pair of values appears in the argument list. The first expression in the pair should evaluate to a keyword symbol (a symbol that begins with a ':'). The value of the second expression is the value of the keyword argument. Like &optional arguments, &key arguments can have initialization expressions and supplied-p variables. In addition, it is possible to specify the keyword to be used in a function call. If no keyword is specified, the keyword obtained by adding a ':' to the beginning of the keyword argument symbol is used. In other words, if the keyword argument symbol is 'foo', the keyword will be ':foo'. Extra keywords will signal an error unless &allow-other-keys is present, in which case the extra keywords are ignored. In XLISP, the &allow-other-keys argument is ignored, and extra keywords are ignored. The &key arguments are followed by the &aux variables. These are local variables that are bound during the evaluation of the function body. It is possible to have initialization expressions for the &aux variables. XLISP 2.1e LAMBDA LISTS Page 17 Here is the complete syntax for lambda lists: (... [&optional [ | ( [ []])]...] [&rest ] [&key [ | ([ | ( )] [ []])] ... [&allow-other-keys]] [&aux [ | ( [])]...]) where: is a required argument symbol is an &optional argument symbol is the &rest argument symbol is a &key argument symbol is a keyword symbol (starts with ':') is an auxiliary variable symbol is an initialization expression is a supplied-p variable symbol XLISP 2.1e OBJECTS Page 18 OBJECTS Definitions: selector - a symbol used to select an appropriate method message - a selector and a list of actual arguments method - the code that implements a message Since XLISP was created to provide a simple basis for experimenting with object-oriented programming, one of the primitive data types included is 'object'. In XLISP, an object consists of a data structure containing a pointer to the object's class as well as an array containing the values of the object's instance variables. Officially, there is no way to see inside an object (look at the values of its instance variables). The only way to communicate with an object is by sending it a message. You can send a message to an object using the 'send' function. This function takes the object as its first argument, the message selector as its second argument (which must be a symbol) and the message arguments as its remaining arguments. The 'send' function determines the class of the receiving object and attempts to find a method corresponding to the message selector in the set of messages defined for that class. If the message is not found in the object's class and the class has a super-class, the search continues by looking at the messages defined for the super-class. This process continues from one super-class to the next until a method for the message is found. If no method is found, an error occurs. To perform a method lookup starting with the method's superclass rather than the object's class, use the function 'send-super'. This allows a subclass to invoke a standard method in its parent class even though it overrides that method with its own specialized version. When a method is found, the evaluator binds the receiving object to the symbol 'self' and evaluates the method using the remaining elements of the original list as arguments to the method. These arguments are always evaluated prior to being bound to their corresponding formal arguments. The result of evaluating the method becomes the result of the expression. Two objects, both classes, are predefined: Object and Class. Both Object and Class are of class Class. The superclass of Class is Object, while Object has no superclass. Typical use is to create new classes (by sending :new to Class) to represent application objects. Objects of these classes, created by sending :new to the appropriate new class, are subclasses of Object. The Object method :show can be used to view the contents of any object. XLISP 2.1e OBJECTS Page 19 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 [] PRINT THE OBJECT default, or NIL, is *standard-output*, T is *terminal-io* 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 MEMBERSHIP class name returns T if object member of class, else NIL (defined in classes.lsp) :iskindof CLASS MEMBERSHIP class name returns T if object member of class or subclass of class, else NIL (defined in classes.lsp) :respondsto SELECTOR KNOWLEDGE message selector returns T if object responds to message selector, else NIL. (defined in classes.lsp) :storeon READ REPRESENTATION returns a list, that when executed will create a copy of the object. Only works for members of classes created with defclass. (defined in classes.lsp) XLISP 2.1e OBJECTS Page 20 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 [ []] INITIALIZE A NEW CLASS the list of instance variable symbol the list of class variable symbols the superclass (default is Object) returns the new class object :answer ADD A MESSAGE TO A CLASS the message symbol the formal argument list (lambda list) 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 (send Class :new [ []])) When a new class is created, an optional parameter may be specified indicating the superclass of the new class. If this parameter is omitted, the new class will be a subclass of 'Object'. A class inherits all instance variables, and methods from its super-class. Only class variables of a method's class are accessable. XLISP 2.1e OBJECTS Page 21 INSTANCE VARIABLES OF CLASS 'CLASS': MESSAGES - An association list of message names and closures implementing the messages. IVARS - List of names of instance variables. CVARS - List of names of class variables. CVAL - Array of class variable values. SUPERCLASS - The superclass of this class or NIL if no superclass (only for class OBJECT). IVARCNT - instance variables in this class (length of IVARS) IVARTOTAL - total instance variables for this class and all superclasses of this class. PNAME - printname string for this class. XLISP 2.1e SYMBOLS Page 22 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 18), 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. *terminal-io* - stream bound to keyboard and display. Do not alter. *standard-input* - the standard input stream, initially stdin. If stdin is not redirected on the command line, then *terminal-io* is used so that all interactive i/o uses the same stream. *standard-output* - the standard output stream, initially stdout. If stdout is not redirected on the command line then *terminal-io* is used so that all interactive i/o uses the same stream. *error-output* - the error output stream (used by all error messages), initially same as *terminal-io*. *trace-output* - the trace output stream (used by the trace function), initially same as *terminal-io*. *debug-io* - the break loop i/o stream, initially same as *terminal-io*. System messages (other than error messages) also print out on this stream. *breakenable* - flag controlling entering break loop on errors (see page 4) *tracelist* - list of names of functions to trace, as set by trace function. *tracenable* - enable trace back printout on errors (see page 4). *tracelimit* - number of levels of trace back information (see page 4). *evalhook* - user substitute for the evaluator function (see page 8, and evalhook and applyhook functions). *applyhook* - user substitute for function application (see page 8, and evalhook and applyhook functions). *readtable* - the current readtable (see page 12). *unbound* - indicator for unbound symbols. A constant. Do not use this symbol since accessing any variable to which this has been bound will cause an unbound symbol error message. XLISP 2.1e SYMBOLS Page 23 *gc-flag* - controls the printing of gc messages. When non-NIL, a message is printed after each garbage collection giving the total number of nodes and the number of nodes free. *gc-hook* - function to call after garbage collection (see page 8). *integer-format* - format for printing integers (when not bound to a string, defaults to "%d" or "%ld" depending on implementation) *ratio-format* - format for printing ratios (when not bound to a string, defaults to "%d/%d" or "%ld/%ld" depending on implementation) *float-format* - format for printing floats (when not bound to a string, defaults to "%g") *readtable-case* - symbol read and output case. See page 14 for details *print-case* - symbol output case when printing. See page 14 for details *print-level* - When bound to a number, list levels beyond this value are printed as '#'. Used by all printing functions. Good precaution to avoid getting caught in circular lists. *print-length* - When bound to a number, lists longer than this value are printed as '...'. Used by all printing functions. Good precaution to avoid getting caught in circular lists. *dos-input* - When not NIL, uses dos line input function for read (see page 2). *displace-macros* - When not NIL, macros are replaced by their expansions when exectuted (see page 7). *random-state* - the default random-state used by the random function. *features* - list of features, initially (:xlisp), used for #+ and #- reader macros. There are several symbols maintained by the read/eval/print loop. The symbols '+', '++', and '+++' are bound to the most recent three input expressions. The symbols '*', '**' and '***' are bound to the most recent three results. The symbol '-' is bound to the expression currently being evaluated. It becomes the value of '+' at the end of the evaluation. XLISP 2.1e EVALUATION FUNCTIONS Page 24 EVALUATION FUNCTIONS (eval ) EVALUATE AN XLISP EXPRESSION the expression to be evaluated returns the result of evaluating the expression (apply ...) APPLY A FUNCTION TO A LIST OF ARGUMENTS the function to apply (or function symbol). May not be macro or fsubr. initial arguments, which are CONSed to... the argument list returns the result of applying the function to the arguments (funcall ...) CALL A FUNCTION WITH ARGUMENTS the function to call (or function symbol). May not be macro or fsubr. arguments to pass to the function returns the result of calling the function with the arguments (quote ) RETURN AN EXPRESSION UNEVALUATED fsubr the expression to be quoted (quoted) returns unevaluated (function ) GET THE FUNCTIONAL INTERPRETATION fsubr the symbol or lambda expression (quoted) returns the functional interpretation (identity ) RETURN THE EXPRESSION New function. In common.lsp the expression returns the expression (backquote ) FILL IN A TEMPLATE fsubr. Note: an improved backquote facility, which works properly when nested, is available by loading the file backquot.lsp. the template (quoted) returns a copy of the template with comma and comma-at expressions expanded. (comma ) COMMA EXPRESSION (Never executed) As the object of a backquote expansion, the expression is evaluated and becomes an object in the enclosing list. (comma-at ) 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. XLISP 2.1e EVALUATION FUNCTIONS Page 25 (lambda ...) MAKE A FUNCTION CLOSURE fsubr formal argument list (lambda list) (quoted) expressions of the function body (quoted) returns the function closure (get-lambda-expression ) GET THE LAMBDA EXPRESSION the closure returns the original lambda expression (macroexpand
) RECURSIVELY EXPAND MACRO CALLS the form to expand returns the macro expansion (macroexpand-1 ) EXPAND A MACRO CALL the macro call form returns the macro expansion XLISP 2.1e SYMBOL FUNCTIONS Page 26 SYMBOL FUNCTIONS (set ) SET THE GLOBAL VALUE OF A SYMBOL the symbol being set the new value returns the new value (setq [ ]...) SET THE VALUE OF A SYMBOL fsubr the symbol being set (quoted) the new value returns the new value (psetq [ ]...) PARALLEL VERSION OF SETQ fsubr. All expressions are evaluated before any assignments are made. the symbol being set (quoted) the new value returns the new value (setf [ ]...) SET THE VALUE OF A FIELD fsubr the field specifier (if a macro it is expanded, then the form arguments are evaluated): set value of a symbol (car ) set car of a cons node (cdr ) set cdr of a cons node (nth ) set nth car of a list (aref ) set nth element of an array or string (elt ) set nth element of a sequence (get ) set value of a property (symbol-value ) set global value of a symbol (symbol-function ) set functional value of a symbol (symbol-plist ) set property list of a symbol (gethash ) add or replace hash table entry. is ignored (send :) (When classes.lsp used), set instance variable of object. (- ) set the element of structure struct, type sym. ( ) the function stored in property *setf* in symbol is applied to ( ). As an alternative, the function stored in property *setf-lambda* is applied, then the result is evaled in the current context. the new value returns the new value XLISP 2.1e SYMBOL FUNCTIONS Page 27 (defsetf ) DEFINE A SETF FIELD SPECIFIER (defsetf () ...) Defined as macro in common.lsp. Convenient, Common Lisp compatible alternative to setting *setf* or *setf-lambda* property directly. field specifier symbol (quoted) 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. formal argument list of unevaluated arguments (lambda list) (quoted) symbol bound to value to store (quoted). 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 ) 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. field specifier being modified (see setf) value to cons to field returns the new value which is (CONS ) (pushnew &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. field specifier being modified (see setf) 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 ) or (pop ) 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. the field being modified (see setf) returns (CAR ), field changed to (CDR ) XLISP 2.1e SYMBOL FUNCTIONS Page 28 (incf []) INCREMENT A FIELD (decf []) 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. field specifier being modified (see setf) Numeric value (default 1) returns the new value which is (+ ) or (- ) (defun ...) DEFINE A FUNCTION (defmacro ...) DEFINE A MACRO fsubr symbol being defined (quoted) formal argument list (lambda list) (quoted) expressions constituting the body of the function (quoted) returns the function symbol (gensym []) GENERATE A SYMBOL string or number returns the new symbol, uninterned (intern ) MAKE AN INTERNED SYMBOL the symbol's print name string returns the new symbol (make-symbol ) MAKE AN UNINTERNED SYMBOL the symbol's print name string returns the new symbol (symbol-name ) GET THE PRINT NAME OF A SYMBOL the symbol returns the symbol's print name (symbol-value ) GET THE VALUE OF A SYMBOL the symbol returns the symbol's value (symbol-function ) GET THE FUNCTIONAL VALUE OF A SYMBOL the symbol returns the symbol's functional value (symbol-plist ) GET THE PROPERTY LIST OF A SYMBOL the symbol returns the symbol's property list (hash ) COMPUTE THE HASH INDEX the object to hash the table size (positive integer) returns the hash index (integer 0 to n-1) XLISP 2.1e SYMBOL FUNCTIONS Page 29 (makunbound ) MAKE A SYMBOL VALUE BE UNBOUND You cannot unbind constants. the symbol returns the symbol (fmakunbound ) MAKE A SYMBOL FUNCTION BE UNBOUND Defined in init.lsp the symbol returns the symbol (unintern ) UNINTERN A SYMBOL Defined in common.lsp the symbol returns t if successful, NIL if symbol not interned (defconstant ) DEFINE A CONSTANT fsubr. the symbol the value returns the value (defparameter ) DEFINE A PARAMETER fsubr. the symbol the value returns the value (defvar []) DEFINE A VARIABLE fsubr. Variable only initialized if not previously defined. the symbol the initial value, or NIL if absent. returns the current value XLISP 2.1e PROPERTY LIST FUNCTIONS Page 30 PROPERTY LIST FUNCTIONS Note that property names are not limited to symbols. (get ) GET THE VALUE OF A PROPERTY the symbol the property symbol returns the property value or NIL (putprop ) PUT A PROPERTY ONTO A PROPERTY LIST the symbol the property value the property symbol returns the property value (remprop ) DELETE A PROPERTY the symbol the property symbol returns NIL XLISP 2.1e HASH TABLE FUNCTIONS Page 31 HASH TABLE FUNCTIONS A hash table is implemented as an structure of type hash-table. No general accessing functions are provided, and hash tables print out using the angle bracket convention (not readable by READ). The first element is the comparison function. The remaining elements contain association lists of keys (that hash to the same value) and their data. (make-hash-table &key :size :test) MAKE A HASH TABLE :size size of hash table -- should be a prime number. Default is 31. :test comparison function. Defaults to eql. returns the hash table (gethash []) EXTRACT FROM HASH TABLE See also gethash in SETF. hash key
hash table value to return on no match (default is NIL) returns associated data, if found, or if not found. (remhash
) DELETE FROM HASH TABLE hash key
hash table returns T if deleted, NIL if not in table (clrhash
) CLEAR THE HASH TABLE
hash table returns NIL, all entries cleared from table (hash-table-count
) NUMBER OF ENTRIES IN HASH TABLE
hash table returns integer number of entries in table (maphash
) MAP FUNCTION OVER TABLE ENTRIES 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.
hash table returns NIL XLISP 2.1e ARRAY FUNCTIONS Page 32 ARRAY FUNCTIONS Note that sequence functions also work on arrays. (aref ) GET THE NTH ELEMENT OF AN ARRAY See setf for setting elements of arrays the array (or string) the array index (integer, zero based) returns the value of the array element (make-array ) MAKE A NEW ARRAY the size of the new array (integer) returns the new array (vector ...) MAKE AN INITIALIZED VECTOR the vector elements returns the new vector XLISP 2.1e SEQUENCE FUNCTIONS Page 33 SEQUENCE FUNCTIONS These functions work on sequences -- lists, arrays, or strings. (concatenate ...) CONCATENATE SEQUENCES If result type is string, sequences must contain only characters. result type, one of CONS, LIST, ARRAY, or STRING zero or more sequences to concatenate returns a sequence which is the concatenation of the arguement sequences (elt ) GET THE NTH ELEMENT OF A SEQUENCE the sequence the index of element to return returns the element if the index is in bounds, otherwise error (map ...) APPLY FUNCTION TO SUCCESSIVE ELEMENTS result type, one of CONS, LIST, ARRAY, STRING, or NIL the function or function name a sequence for each argument of the function returns a new sequence of type . (every ...) APPLY FUNCTION TO ELEMENTS UNTIL FALSE (notevery ...) the function or function name 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 ...) APPLY FUNCTION TO ELEMENTS UNTIL TRUE (notany ...) the function or function name 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 ) FIND THE LENGTH OF A SEQUENCE the list, vector or string returns the length of the list, vector or string (reverse ) REVERSE A SEQUENCE (nreverse ) DESTRUCTIVELY REVERSE A SEQUENCE the sequence to reverse returns a new sequence in the reverse order XLISP 2.1e SEQUENCE FUNCTIONS Page 34 (subseq []) EXTRACT A SUBSEQUENCE the sequence the starting position (zero origin) the ending position + 1 (defaults to end) or NIL for end of sequence returns the sequence between and (search &key :test :test-not :key :start1 :end1 :start2 :end2) SEARCH FOR SEQUENCE the sequence to search for 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 :end1 index of end+1 in or NIL for end of sequence :start2 starting index in :end2 index of end+1 in or NIL for end of sequence returns position of first match (remove &key :test :test-not :key :start :end) REMOVE ELEMENTS FROM A SEQUENCE the element to remove the sequence :test the test function (defaults to eql) :test-not the test function (sense inverted) :key function to apply to test function sequence argument (defaults to identity) :start starting index :end index of end+1, or NIL for (length ) returns copy of sequence with matching expressions removed (remove-if &key :key :start :end) REMOVE ELEMENTS THAT PASS TEST (remove-if-not &key :key :start :end) REMOVE ELEMENTS THAT FAIL TEST the test predicate the sequence :key function to apply to test function argument (defaults to identity) :start starting index :end index of end+1, or NIL for (length ) returns copy of sequence with matching or non-matching elements removed XLISP 2.1e SEQUENCE FUNCTIONS Page 35 (count-if &key :key :start :end) COUNT ELEMENTS THAT PASS TEST the test predicate the sequence :key function to apply to test function argument (defaults to identity) :start starting index :end index of end+1, or NIL for (length ) returns count of matching elements (find-if &key :key :start :end) FIND FIRST ELEMENT THAT PASSES TEST the test predicate the list :key function to apply to test function argument (defaults to identity) :start starting index :end index of end+1, or NIL for (length ) returns first element of sequence that passes test (position-if &key :key :start :end) FIND POSITION OF FIRST ELEMENT THAT PASSES TEST the test predicate the list :key function to apply to test function argument (defaults to identity) :start starting index :end index of end+1, or NIL for (length ) returns position of first element of sequence that passes test, or NIL. (delete &key :key :test :test-not :start :end) DELETE ELEMENTS FROM A SEQUENCE the element to delete the sequence :test the test function (defaults to eql) :test-not the test function (sense inverted) :key function to apply to test function sequence argument (defaults to identity) :start starting index :end index of end+1, or NIL for (length ) returns the sequence with the matching expressions deleted XLISP 2.1e SEQUENCE FUNCTIONS Page 36 (delete-if &key :key :start :end) DELETE ELEMENTS THAT PASS TEST (delete-if-not &key :key :start :end) DELETE ELEMENTS THAT FAIL TEST the test predicate the sequence :key function to apply to test function argument (defaults to identity) :start starting index :end index of end+1, or NIL for (length ) returns the sequence with matching or non-matching elements deleted (reduce &key :initial-value :start :end) REDUCE SEQUENCE TO SINGLE VALUE function (of two arguments) to apply to result of previous function application (or first element) and each member of sequence. 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 ) 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 &key :test :test-not :key :start :end) REMOVE DUPLICATES FROM SEQUENCE 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 ) returns copy of sequence with duplicates removed. (fill &key :start :end) REPLACE ITEMS IN SEQUENCE Defined in common.lsp the sequence new value to place in sequence :start starting index :end index of end+1, or NIL for (length ) returns sequence with items replaced with new item XLISP 2.1e SEQUENCE FUNCTIONS Page 37 (replace &key :start1 :end1 :start2 :end2) REPLACE ITEMS IN SEQUENCE FROM SEQUENCE Defined in common.lsp the sequence to modify sequence with new items :start1 starting index in :end1 index of end+1 in or NIL for end of sequence :start2 starting index in :end2 index of end+1 in or NIL for end of sequence returns first sequence with items replaced XLISP 2.1e LIST FUNCTIONS Page 38 LIST FUNCTIONS (car ) RETURN THE CAR OF A LIST NODE the list node returns the car of the list node (cdr ) RETURN THE CDR OF A LIST NODE the list node returns the cdr of the list node (cxxr ) ALL CxxR COMBINATIONS (cxxxr ) ALL CxxxR COMBINATIONS (cxxxxr ) ALL CxxxxR COMBINATIONS (first ) A SYNONYM FOR CAR (second ) A SYNONYM FOR CADR (third ) A SYNONYM FOR CADDR (fourth ) A SYNONYM FOR CADDDR (rest ) A SYNONYM FOR CDR (cons ) CONSTRUCT A NEW LIST NODE the car of the new list node the cdr of the new list node returns the new list node (acons ) ADD TO FRONT OF ASSOC LIST defined in common.lsp key of new association value of new association association list returns new association list, which is (cons (cons ) )) (list ...) CREATE A LIST OF VALUES (list* ... ) expressions to be combined into a list returns the new list (append ...) APPEND LISTS lists whose elements are to be appended returns the new list (last ) RETURN THE LAST LIST NODE OF A LIST the list returns the last list node in the list (butlast []) RETURN COPY OF ALL BUT LAST OF LIST the list count of elements to omit (default 1) returns copy of list with last element(s) absent. XLISP 2.1e LIST FUNCTIONS Page 39 (nth ) RETURN THE NTH ELEMENT OF A LIST the number of the element to return (zero origin) the list returns the nth element or NIL if the list isn't that long (nthcdr ) RETURN THE NTH CDR OF A LIST the number of the element to return (zero origin) the list returns the nth cdr or NIL if the list isn't that long (member &key :test :test-not :key) FIND AN EXPRESSION IN A LIST the expression to find the list to search :test the test function (defaults to eql) :test-not the test function (sense inverted) :key function to apply to test function list argument (defaults to identity) returns the remainder of the list starting with the expression (assoc &key :test :test-not :key) FIND AN EXPRESSION IN AN A-LIST the expression to find the association list :test the test function (defaults to eql) :test-not the test function (sense inverted) :key function to apply to test function list argument (defaults to identity) returns the alist entry or NIL (mapc ...) APPLY FUNCTION TO SUCCESSIVE CARS the function or function name a list for each argument of the function returns the first list of arguments (mapcar ...) APPLY FUNCTION TO SUCCESSIVE CARS the function or function name a list for each argument of the function returns a list of the values returned (mapl ...) APPLY FUNCTION TO SUCCESSIVE CDRS the function or function name a list for each argument of the function returns the first list of arguments (maplist ...) APPLY FUNCTION TO SUCCESSIVE CDRS the function or function name a list for each argument of the function returns a list of the values returned XLISP 2.1e LIST FUNCTIONS Page 40 (mapcan ...) APPL FUNCTION TO SUCCESSIVE CARS the function or function name a list for each argument of the function returns list of return values nconc'd together (mapcon ...) APPL FUNCTION TO SUCCESSIVE CDRS the function or function name a list for each argument of the function returns list of return values nconc'd together (subst &key :test :test-not :key) SUBSTITUTE EXPRESSIONS Does minimum copying as required by Common Lisp the new expression the old expression 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 test function expression argument (defaults to identity) returns the expression with substitutions (sublis &key :test :test-not :key) SUBSTITUTE WITH AN A-LIST Does minimum copying as required by Common Lisp the association list 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 test function expression argument (defaults to identity) returns the expression with substitutions (pairlis []) BUILD AN A-LIST FROM TWO LISTS In file common.lsp list of association keys list of association values, same length as keys existing association list, default NIL returns new association list (copy-list ) COPY THE TOP LEVEL OF A LIST In file common.lsp the list returns a copy of the list (new cons cells in top level) (copy-alist ) COPY AN ASSOCIATION LIST In file common.lsp the association list returns a copy of the association list (keys and values not copies) XLISP 2.1e LIST FUNCTIONS Page 41 (copy-tree ) COPY A TREE In file common.lsp a tree structure of cons cells returns a copy of the tree structure (intersection &key :test :test-not :key) SET FUNCTIONS (union &key :test :test-not :key) (set-difference &key :test :test-not :key) (set-exclusive-or &key :test :test-not :key) (nintersection &key :test :test-not :key) (nunion &key :test :test-not :key) (nset-difference &key :test :test-not :key) (nset-exclusive-or &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. first list 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 :test :test-not :key) ADD UNIQUE TO LIST new element to add the list :test the test function (defaults to eql) :test-not the test function ), else . XLISP 2.1e DESTRUCTIVE LIST FUNCTIONS Page 42 DESTRUCTIVE LIST FUNCTIONS See also nreverse, delete, delete-if, delete-if-not, fill, and replace under SEQUENCE FUNCTIONS, setf under SYMBOL FUNCTIONS, and nintersection, nunion, nset-difference, and nset-exclusive-or under LIST FUNCTIONS. (rplaca ) REPLACE THE CAR OF A LIST NODE the list node the new value for the car of the list node returns the list node after updating the car (rplacd ) REPLACE THE CDR OF A LIST NODE the list node the new value for the cdr of the list node returns the list node after updating the cdr (nconc ...) DESTRUCTIVELY CONCATENATE LISTS lists to concatenate returns the result of concatenating the lists (sort &key :key) SORT A LIST the list to sort the comparison function :key function to apply to comparison function arguments (defaults to identity) returns the sorted list XLISP 2.1e ARITHMETIC FUNCTIONS Page 43 ARITHMETIC FUNCTIONS Warning: integer and ratio calculations that overflow become floating point values as part of the math extension, but give no error otherwise. On systems with IEEE floating point, the values +INF and -INF result from overflowing floating point calculations. The math extension option adds complex numbers, ratios, new functions, and additional functionality to some existing functions. Because of the size of the extension, and the performance loss it entails, some users may not wish to include it. This section documents the math functions both with and without the extension. Functions that are described as having floating point arguments (SIN COS TAN ASIN ACOS ATAN EXPT EXP SQRT) will take arguments of any type (real or complex) when the math extension is used. In the descriptions, "rational number" means integer or ratio only, and "real number" means floating point number or rational only. Any rational results are reduced to canonical form (the gcd of the numerator and denominator is 1, the denominator is positive); integral results are reduced to integers. Integer complex numbers with zero imaginary parts are reduced to integers. (truncate ) TRUNCATES TOWARD ZERO (round ) ROUNDS TOWARD NEAREST INTEGER (floor ) TRUNCATES TOWARD NEGATIVE INFINITY (ceiling ) TRUNCATES TOWARD INFINITY Round, floor, and ceiling, and the second argument of truncate, are part of the math extension. Results too big to be represented as integers are returned as floating point numbers as part of the math extension. Integers are returned as is. the real number real number to divide by before converting returns the integer result of converting the number (float ) CONVERTS AN INTEGER TO A FLOATING POINT NUMBER the real number returns the number as a floating point number (rational ) CONVERTS A REAL NUMBER TO A RATIONAL Floating point numbers too large to express return the floating point number, while numbers too small to express return zero. Rational numbers are returned as is. the real number returns the number as a ratio or integer. XLISP 2.1e ARITHMETIC FUNCTIONS Page 44 (+ [...]) ADD A LIST OF NUMBERS With no arguments returns addition identity, 0 (integer) the numbers returns the result of the addition (- ...) SUBTRACT A LIST OF NUMBERS OR NEGATE A SINGLE NUMBER the numbers returns the result of the subtraction (* [...]) MULTIPLY A LIST OF NUMBERS With no arguments returns multiplication identity, 1 the numbers returns the result of the multiplication (/ ...) DIVIDE A LIST OF NUMBERS OR INVERT A SINGLE NUMBER With the math extension, division of integer numbers results in a rational quotient, rather than integer. To perform integer division, use TRUNCATE. When an integer complex is divided by an integer, the quotient is floating point complex. the numbers returns the result of the division (1+ ) ADD ONE TO A NUMBER the number returns the number plus one (1- ) SUBTRACT ONE FROM A NUMBER the number returns the number minus one (rem ...) REMAINDER OF A LIST OF NUMBERS With the math extension, only two arguments allowed. the real numbers (must be integers, without math extension) returns the result of the remainder operation (remainder with truncating division) (mod ) NUMBER MODULO ANOTHER NUMBER Part of math extension. real number real number divisor (may not be zero) returns the remainder after dividing by using flooring division, thus there is no discontinuity in the function around zero. (min ...) THE SMALLEST OF A LIST OF NUMBERS the real numbers returns the smallest number in the list (max ...) THE LARGEST OF A LIST OF NUMBERS the real numbers returns the largest number in the list XLISP 2.1e ARITHMETIC FUNCTIONS Page 45 (abs ) THE ABSOLUTE VALUE OF A NUMBER the number returns the absolute value of the number, which is the floating point magnitude for complex numbers. (signum ) GET THE SIGN OF A NUMBER Defined in common.lsp the number returns zero if number is zero, one if positive, or negative one if negative. Numeric type is same as number. For a complex number, returns unit magnitude but same phase as number. (gcd [...]) COMPUTE THE GREATEST COMMON DIVISOR With no arguments returns 0, with one argument returns the argument. The number(s) (integer) returns the greatest common divisor (lcm ...) COMPUTE THE LEAST COMMON MULTIPLE Part of math extension. A result which would be larger than the largest integer causes an error. The number(s) (integer) returns the least common multiple (random []) COMPUTE A PSEUDO-RANDOM NUMBER the real number upper bound a random-state (default is *random-state*) returns a random number in range [0,n) (make-random-state []) CREATE A RANDOM-STATE a random-state, t, or NIL (default NIL). NIL means *random-state* returns If is t, a random random-state, otherwise a copy of (sin ) COMPUTE THE SINE OF A NUMBER (cos ) COMPUTE THE COSINE OF A NUMBER (tan ) COMPUTE THE TANGENT OF A NUMBER (asin ) COMPUTE THE ARC SINE OF A NUMBER (acos ) COMPUTE THE ARC COSINE OF A NUMBER the floating point number returns the sine, cosine, tangent, arc sine, or arc cosine of the number (atan []) COMPUTE THE ARC TANGENT OF A NUMBER the floating point number (numerator) the denominator, default 1. May only be specified if math extension installed returns the arc tangent of / XLISP 2.1e ARITHMETIC FUNCTIONS Page 46 (sinh ) COMPUTE THE HYPERBOLIC SINE OF A NUMBER (cosh ) COMPUTE THE HYPERBOLIC COSINE OF A NUMBER (tanh ) COMPUTE THE HYPERBOLIC TANGENT OF A NUMBER (asinh ) COMPUTE THE HYPERBOLIC ARC SINE OF A NUMBER (acosh ) COMPUTE THE HYPERBOLIC ARC COSINE OF A NUMBER (atanh ) COMPUTE THE HYPERBOLIC ARC TANGENT OF A NUMBER Defined in common.lsp the number returns the hyperbolic sine, cosine, tangent, arc sine, arc cosine, or arc tangent of the number. (expt ) COMPUTE X TO THE Y POWER the number the exponent returns x to the y power. If y is a fixnum, then the result type is the same as the type of x, unless fixnum or ratio and it would overflow, then the result type is a flonum. (exp ) COMPUTE E TO THE X POWER the floating point number returns e to the x power (cis ) COMPUTE COSINE + I SINE Defined in common.lsp the number returns e to the ix power (log []) COMPUTE THE LOGRITHM Part of the math extension the number the base, default is e returns log base of (sqrt ) COMPUTE THE SQUARE ROOT OF A NUMBER the number returns the square root of the number (numerator ) GET THE NUMERATOR OF A NUMBER Part of math extension rational number returns numerator of number (number if integer) (denominator ) GET THE DENOMINATOR OF A NUMBER Part of math extension rational number returns denominator of number (1 if integer) XLISP 2.1e ARITHMETIC FUNCTIONS Page 47 (complex []) CONVERT TO COMPLEX NUMBER Part of math extension real number real part real number imaginary part (default 0) returns the complex number (realpart ) GET THE REAL PART OF A NUMBER Part of the math extension the number returns the real part of a complex number, or the number itself if a real number (imagpart ) GET THE IMAGINARY PART OF A NUMBER Part of the math extension the number returns the imaginary part of a complex number, or zero of the type of the number if a real number. (conjugate ) GET THE CONJUGATE OF A NUMBER Part of the math extension the number returns the conjugate of a complex number, or the number itself if a real number. (phase ) GET THE PHASE OF A NUMBER Part of the math extension the number returns the phase angle, equivalent to (atan (imagpart ) (realpart )) (< ...) TEST FOR LESS THAN (<= ...) TEST FOR LESS THAN OR EQUAL TO (= ...) TEST FOR EQUAL TO (/= ...) TEST FOR NOT EQUAL TO (>= ...) TEST FOR GREATER THAN OR EQUAL TO (> ...) TEST FOR GREATER THAN the first real number to compare the second real number to compare returns the result of comparing with ... XLISP 2.1e BITWISE LOGICAL FUNCTIONS Page 48 BITWISE LOGICAL FUNCTIONS (logand [...]) THE BITWISE AND OF A LIST OF INTEGERS With no arguments returns identity -1 the integers returns the result of the and operation (logior [...]) THE BITWISE INCLUSIVE OR OF A LIST OF INTEGERS With no arguments returns identity 0 the integers returns the result of the inclusive or operation (logxor [...]) THE BITWISE EXCLUSIVE OR OF A LIST OF INTEGERS With no arguments returns identity 0 the integers returns the result of the exclusive or operation (lognot ) THE BITWISE NOT OF A INTEGER the integer returns the bitwise inversion of integer (logtest ) TEST BITWISE AND OF TWO INTEGERS Defined in common.lsp the first integer the second integer returns T if the result of the and operation is non-zero, else NIL (ash ) ARITHMETIC SHIFT Part of math extension integer to shift number of bit positions to shift (positive is to left) returns shifted integer XLISP 2.1e STRING FUNCTIONS Page 49 STRING FUNCTIONS Note: functions with names starting "string" will also accept a symbol, in which case the symbol's print name is used. (string ) MAKE A STRING FROM AN INTEGER ASCII VALUE an integer (which is first converted into its ASCII character value), string, character, or symbol returns the string representation of the argument (string-trim ) TRIM BOTH ENDS OF A STRING a string containing characters to trim the string to trim returns a trimed copy of the string (string-left-trim ) TRIM THE LEFT END OF A STRING a string containing characters to trim the string to trim returns a trimed copy of the string (string-right-trim ) TRIM THE RIGHT END OF A STRING a string containing characters to trim the string to trim returns a trimed copy of the string (string-upcase &key :start :end) CONVERT TO UPPERCASE 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 &key :start :end) CONVERT TO LOWERCASE the string :start the starting offset :end the ending offset + 1 or NIL for end of string returns a converted copy of the string (nstring-upcase &key :start :end) CONVERT TO UPPERCASE 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-downcase &key :start :end) CONVERT TO LOWERCASE the string :start the starting offset :end the ending offset + 1 or NIL for end of string returns the converted string (not a copy) XLISP 2.1e STRING FUNCTIONS Page 50 (strcat ...) CONCATENATE STRINGS Macro in init.lsp, to maintain compatibility with XLISP. See CONCATENATE for preferred function. the strings to concatenate returns the result of concatenating the strings (string< &key :start1 :end1 :start2 :end2) (string<= &key :start1 :end1 :start2 :end2) (string= &key :start1 :end1 :start2 :end2) (string/= &key :start1 :end1 :start2 :end2) (string>= &key :start1 :end1 :start2 :end2) (string> &key :start1 :end1 :start2 :end2) the first string to compare the second string to compare :start1 first substring starting offset :end1 first substring ending offset + 1 or NIL for end of string :start2 second substring starting offset :end2 second substring ending offset + 1 or NIL for end of string returns string=: t if predicate is true, NIL otherwise others: If predicate is true then number of initial matching characters, else NIL Note: case is significant with these comparison functions. (string-lessp &key :start1 :end1 :start2 :end2) (string-not-greaterp &key :start1 :end1 :start2 :end2) (string-equal &key :start1 :end1 :start2 :end2) (string-not-equal &key :start1 :end1 :start2 :end2) (string-not-lessp &key :start1 :end1 :start2 :end2) (string-greaterp &key :start1 :end1 :start2 :end2) the first string to compare the second string to compare :start1 first substring starting offset :end1 first substring ending offset + 1 or NIL for end of string :start2 second substring starting offset :end2 second substring ending offset + 1 or NIL for end of string returns string-equal: t if predicate is true, NIL otherwise others: If predicate is true then number of initial matching characters, else NIL Note: case is not significant with these comparison functions -- all uppercase characters are converted to lowercase before being compared. XLISP 2.1e CHARACTER FUNCTIONS Page 51 CHARACTER FUNCTIONS (char ) EXTRACT A CHARACTER FROM A STRING the string the string index (zero relative) returns the ascii code of the character (alphanumericp ) IS THIS CHARACTER ALPHANUMERIC? the character returns true if the character is alphabetic or numeric, NIL otherwise (upper-case-p ) IS THIS AN UPPER CASE CHARACTER? the character returns true if the character is upper case, NIL otherwise (lower-case-p ) IS THIS A LOWER CASE CHARACTER? the character returns true if the character is lower case, NIL otherwise (alpha-char-p ) IS THIS AN ALPHABETIC CHARACTER? the character returns true if the character is alphabetic, NIL otherwise (both-case-p ) IS THIS AN ALPHABETIC (EITHER CASE) CHARACTER? the character returns true if the character is available in both cases, NIL otherwise (digit-char-p ) IS THIS A DIGIT CHARACTER? the character returns the digit weight if character is a digit, NIL otherwise (char-code ) GET THE ASCII CODE OF A CHARACTER the character returns the ASCII character code (integer, parity bit stripped) (code-char ) GET THE CHARACTER WITH A SPECFIED ASCII CODE the ASCII code (integer, range 0-127) returns the character with that code or NIL (char-upcase ) CONVERT A CHARACTER TO UPPER CASE the character returns the upper case version of the character, if one exists, otherwise returns the character (char-downcase ) CONVERT A CHARACTER TO LOWER CASE the character returns the lower case version of the character, if one exists, otherwise returns the character XLISP 2.1e CHARACTER FUNCTIONS Page 52 (digit-char ) CONVERT A DIGIT WEIGHT TO A DIGIT the digit weight (integer) returns the digit character or NIL (char-int ) CONVERT A CHARACTER TO AN INTEGER the character returns the ASCII character code (range 0-255) (int-char ) CONVERT AN INTEGER TO A CHARACTER the ASCII character code (treated modulo 256) returns the character with that code (char< ...) (char<= ...) (char= ...) (char/= ...) (char>= ...) (char> ...) the first character to compare the second character(s) to compare returns t if predicate is true, NIL otherwise Note: case is significant with these comparison functions. (char-lessp ...) (char-not-greaterp ...) (char-equal ...) (char-not-equal ...) (char-not-lessp ...) (char-greaterp ...) the first string to compare the second string(s) to compare returns t if predicate is true, NIL otherwise Note: case is not significant with these comparison functions -- all uppercase characters are converted to lowercase before the comparison. XLISP 2.1e STRUCTURE FUNCTIONS Page 53 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 ...) or (defstruct (name