garym@cognos.UUCP (Gary Murphy) (02/27/90)
Posting-number: Volume 10, Issue 92 Submitted-by: garym@cognos.UUCP (Gary Murphy) Archive-name: xlisp21/part05 #!/bin/sh # This is a shell archive, meaning: # 1. Remove everything above the #!/bin/sh line. # 2. Save the resulting text in a file. # 3. Execute the file with /bin/sh (not csh) to create the files: # xlisp.doc # This archive created: Sun Feb 18 23:35:09 1990 # By: Gary Murphy () export PATH; PATH=/bin:$PATH echo shar: extracting "'xlisp.doc'" '(80928 characters)' if test -f 'xlisp.doc' then echo shar: over-writing existing file "'xlisp.doc'" fi sed 's/^X//' << \SHAR_EOF > 'xlisp.doc' X X X X X X X XLISP: An Object-oriented Lisp X X Version 2.0 X X February 6, 1988 X X X by X David Michael Betz X 127 Taylor Road X Peterborough, NH 03458 X X (603) 924-6936 (home) X (603) 882-1599 (BBS) X X Copyright (c) 1988, by David Michael Betz X All Rights Reserved X Permission is granted for unrestricted non-commercial use X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X XLISP TABLE OF CONTENTS Page 2 X X X Table of Contents X X X TABLE OF CONTENTS 2 X X INTRODUCTION 4 X X A NOTE FROM THE AUTHOR 5 X X XLISP COMMAND LOOP 6 X X BREAK COMMAND LOOP 7 X X DATA TYPES 8 X X THE EVALUATOR 9 X X LEXICAL CONVENTIONS 10 X X READTABLES 11 X X LAMBDA LISTS 12 X X OBJECTS 14 X X SYMBOLS 17 X X EVALUATION FUNCTIONS 18 X X SYMBOL FUNCTIONS 19 X X PROPERTY LIST FUNCTIONS 21 X X ARRAY FUNCTIONS 22 X X LIST FUNCTIONS 23 X X DESTRUCTIVE LIST FUNCTIONS 26 X X PREDICATE FUNCTIONS 27 X X CONTROL CONSTRUCTS 29 X X LOOPING CONSTRUCTS 31 X X THE PROGRAM FEATURE 32 X X DEBUGGING AND ERROR HANDLING 33 X X ARITHMETIC FUNCTIONS 34 X X BITWISE LOGICAL FUNCTIONS 36 X X STRING FUNCTIONS 37 X X X X X X X X X X XLISP TABLE OF CONTENTS Page 3 X X X CHARACTER FUNCTIONS 39 X X INPUT/OUTPUT FUNCTIONS 41 X X THE FORMAT FUNCTION 42 X X FILE I/O FUNCTIONS 43 X X STRING STREAM FUNCTIONS 44 X X SYSTEM FUNCTIONS 45 X X EXAMPLES 47 X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X XLISP INTRODUCTION Page 4 X X X INTRODUCTION X X XLISP is an experimental programming language combining some of X the features of Common Lisp with an object-oriented extension X capability. It was implemented to allow experimentation with X object-oriented programming on small computers. X X There are currently implementations of XLISP running on the IBM- X PC and clones under MS-DOS, on the Macintosh, the Atari-ST and X the Amiga. It is completely written in the programming language X 'C' and is easily extended with user written built-in functions X and classes. It is available in source form to non-commercial X users. X X Many Common Lisp functions are built into XLISP. In addition, X XLISP defines the objects 'Object' and 'Class' as primitives. X 'Object' is the only class that has no superclass and hence is X the root of the class heirarchy tree. 'Class' is the class of X which all classes are instances (it is the only object that is X an instance of itself). X X This document is a brief description of XLISP. It assumes some X knowledge of LISP and some understanding of the concepts of X object-oriented programming. X X I recommend the book "LISP" by Winston and Horn and published by X Addison Wesley for learning Lisp. The first edition of this X book is based on MacLisp and the second edition is based on X Common Lisp. XLISP will continue to migrate towards X compatibility with Common Lisp. X X You will probably also need a copy of "Common Lisp: The X Language" by Guy L. Steele, Jr., published by Digital Press to X use as a reference for some of the Common Lisp functions that X are described only briefly in this document. X X X X X X X X X X X X X X X X X X X X X X X X X X X X X XLISP A NOTE FROM THE AUTHOR Page 5 X X X A NOTE FROM THE AUTHOR X X If you have any problems with XLISP, feel free to contact me for X help or advice. Please remember that since XLISP is available X in source form in a high level language, many users have been X making versions available on a variety of machines. If you call X to report a problem with a specific version, I may not be able X to help you if that version runs on a machine to which I don't X have access. Please have the version number of the version that X you are running readily accessible before calling me. X X If you find a bug in XLISP, first try to fix the bug yourself X using the source code provided. If you are successful in fixing X the bug, send the bug report along with the fix to me. If you X don't have access to a C compiler or are unable to fix a bug, X please send the bug report to me and I'll try to fix it. X X Any suggestions for improvements will be welcomed. Feel free to X extend the language in whatever way suits your needs. However, X PLEASE DO NOT RELEASE ENHANCED VERSIONS WITHOUT CHECKING WITH ME X FIRST!! I would like to be the clearing house for new features X added to XLISP. If you want to add features for your own X personal use, go ahead. But, if you want to distribute your X enhanced version, contact me first. Please remember that the X goal of XLISP is to provide a language to learn and experiment X with LISP and object-oriented programming on small computers. I X don't want it to get so big that it requires megabytes of memory X to run. X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X XLISP XLISP COMMAND LOOP Page 6 X X X XLISP COMMAND LOOP X X When XLISP is started, it first tries to load the workspace X "xlisp.wks" from the current directory. If that file doesn't X exist, XLISP builds an initial workspace, empty except for the X built-in functions and symbols. X X Then XLISP attempts to load "init.lsp" from the current X directory. It then loads any files named as parameters on the X command line (after appending ".lsp" to their names). X X XLISP then issues the following prompt: X X > X X This indicates that XLISP is waiting for an expression to be X typed. X X When a complete expression has been entered, XLISP attempts to X evaluate that expression. If the expression evaluates X successfully, XLISP prints the result and then returns to the X initial prompt waiting for another expression to be typed. X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X XLISP BREAK COMMAND LOOP Page 7 X X X BREAK COMMAND LOOP X X When XLISP encounters an error while evaluating an expression, X it attempts to handle the error in the following way: X X If the symbol '*breakenable*' is true, the message corresponding X to the error is printed. If the error is correctable, the X correction message is printed. X X If the symbol '*tracenable*' is true, a trace back is printed. X The number of entries printed depends on the value of the symbol X '*tracelimit*'. If this symbol is set to something other than a X number, the entire trace back stack is printed. X X XLISP then enters a read/eval/print loop to allow the user to X examine the state of the interpreter in the context of the X error. This loop differs from the normal top-level X read/eval/print loop in that if the user invokes the function X 'continue', XLISP will continue from a correctable error. If X the user invokes the function 'clean-up', XLISP will abort the X break loop and return to the top level or the next lower X numbered break loop. When in a break loop, XLISP prefixes the X break level to the normal prompt. X X If the symbol '*breakenable*' is nil, XLISP looks for a X surrounding errset function. If one is found, XLISP examines X the value of the print flag. If this flag is true, the error X message is printed. In any case, XLISP causes the errset X function call to return nil. X X If there is no surrounding errset function, XLISP prints the X error message and returns to the top level. X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X XLISP DATA TYPES Page 8 X X X DATA TYPES X X There are several different data types available to XLISP X programmers. X X o lists X o symbols X o strings X o integers X o characters X o floats X o objects X o arrays X o streams X o subrs (built-in functions) X o fsubrs (special forms) X o closures (user defined functions) X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X XLISP THE EVALUATOR Page 9 X X X THE EVALUATOR X X The process of evaluation in XLISP: X X Strings, integers, characters, floats, objects, arrays, streams, X subrs, fsubrs and closures evaluate to themselves. X X Symbols act as variables and are evaluated by retrieving the X value associated with their current binding. X X Lists are evaluated by examining the first element of the list X and then taking one of the following actions: X X If it is a symbol, the functional binding of the symbol is X retrieved. X X If it is a lambda expression, a closure is constructed for X the function described by the lambda expression. X X If it is a subr, fsubr or closure, it stands for itself. X X Any other value is an error. X X Then, the value produced by the previous step is examined: X X If it is a subr or closure, the remaining list elements are X evaluated and the subr or closure is called with these X evaluated expressions as arguments. X X If it is an fsubr, the fsubr is called using the remaining X list elements as arguments (unevaluated). X X If it is a macro, the macro is expanded using the remaining X list elements as arguments (unevaluated). The macro X expansion is then evaluated in place of the original macro X call. X X X X X X X X X X X X X X X X X X X X X X X X X X X X XLISP LEXICAL CONVENTIONS Page 10 X X X LEXICAL CONVENTIONS X X The following conventions must be followed when entering XLISP X programs: X X Comments in XLISP code begin with a semi-colon character and X continue to the end of the line. X X Symbol names in XLISP can consist of any sequence of non-blank X printable characters except the following: X X ( ) ' ` , " ; X X Uppercase and lowercase characters are not distinguished within X symbol names. All lowercase characters are mapped to uppercase X on input. X X Integer literals consist of a sequence of digits optionally X beginning with a '+' or '-'. The range of values an integer can X represent is limited by the size of a C 'long' on the machine on X which XLISP is running. X X Floating point literals consist of a sequence of digits X optionally beginning with a '+' or '-' and including an embedded X decimal point. The range of values a floating point number can X represent is limited by the size of a C 'float' ('double' on X machines with 32 bit addresses) on the machine on which XLISP is X running. X X Literal strings are sequences of characters surrounded by double X quotes. Within quoted strings the '\' character is used to X allow non-printable characters to be included. The codes X recognized are: X X \\ means the character '\' X \n means newline X \t means tab X \r means return X \f means form feed X \nnn means the character whose octal code is nnn X X X X X X X X X X X X X X X X X X X X X X X X XLISP READTABLES Page 11 X X X READTABLES X X The behaviour of the reader is controlled by a data structure X called a "readtable". The reader uses the symbol *READTABLE* to X locate the current readtable. This table controls the X interpretation of input characters. It is an array with 128 X entries, one for each of the ASCII character codes. Each entry X contains one of the following things: X X NIL Indicating an invalid character X :CONSTITUENT Indicating a symbol constituent X :WHITE-SPACE Indicating a whitespace character X (:TMACRO . fun) Terminating readmacro X (:NMACRO . fun) Non-terminating readmacro X :SESCAPE Single escape character ('\') X :MESCAPE Multiple escape character ('|') X X In the case of :TMACRO and :NMACRO, the "fun" component is a X function. This can either be a built-in readmacro function or a X lambda expression. The function should take two parameters. X The first is the input stream and the second is the character X that caused the invocation of the readmacro. The readmacro X function should return NIL to indicate that the character should X be treated as white space or a value consed with NIL to indicate X that the readmacro should be treated as an occurance of the X specified value. Of course, the readmacro code is free to read X additional characters from the input stream. X X XLISP defines several useful read macros: X X '<expr> == (quote <expr>) X #'<expr> == (function <expr>) X #(<expr>...) == an array of the specified expressions X #x<hdigits> == a hexadecimal number (0-9,A-F) X #o<odigits> == an octal number (0-7) X #b<bdigits> == a binary number (0-1) X #\<char> == the ASCII code of the character X #| ... |# == a comment X #:<symbol> == an uninterned symbol X `<expr> == (backquote <expr>) X ,<expr> == (comma <expr>) X ,@<expr> == (comma-at <expr>) X X X X X X X X X X X X X X X X X X X X X X XLISP LAMBDA LISTS Page 12 X X X LAMBDA LISTS X X There are several forms in XLISP that require that a "lambda X list" be specified. A lambda list is a definition of the X arguments accepted by a function. There are four different X types of arguments. X X The lambda list starts with required arguments. Required X arguments must be specified in every call to the function. X X The required arguments are followed by the &optional arguments. X Optional arguments may be provided or omitted in a call. An X initialization expression may be specified to provide a default X value for an &optional argument if it is omitted from a call. X If no initialization expression is specified, an omitted X argument is initialized to NIL. It is also possible to provide X the name of a 'supplied-p' variable that can be used to X determine if a call provided a value for the argument or if the X initialization expression was used. If specified, the supplied- X p variable will be bound to T if a value was specified in the X call and NIL if the default value was used. X X The &optional arguments are followed by the &rest argument. The X &rest argument gets bound to the remainder of the argument list X after the required and &optional arguments have been removed. X X The &rest argument is followed by the &key arguments. When a X keyword argument is passed to a function, a pair of values X appears in the argument list. The first expression in the pair X should evaluate to a keyword symbol (a symbol that begins with a X ':'). The value of the second expression is the value of the X keyword argument. Like &optional arguments, &key arguments can X have initialization expressions and supplied-p variables. In X addition, it is possible to specify the keyword to be used in a X function call. If no keyword is specified, the keyword obtained X by adding a ':' to the beginning of the keyword argument symbol X is used. In other words, if the keyword argument symbol is X 'foo', the keyword will be ':foo'. X X The &key arguments are followed by the &aux variables. These X are local variables that are bound during the evaluation of the X function body. It is possible to have initialization X expressions for the &aux variables. X X X X X X X X X X X X X X X X X X X X X XLISP LAMBDA LISTS Page 13 X X X Here is the complete syntax for lambda lists: X X (<rarg>... X [&optional [<oarg> | (<oarg> [<init> [<svar>]])]...] X [&rest <rarg>] X [&key X [<karg> | ([<karg> | (<key> <karg>)] [<init> [<svar>]])]... X &allow-other-keys] X [&aux X [<aux> | (<aux> [<init>])]...]) X X where: X X <rarg> is a required argument symbol X <oarg> is an &optional argument symbol X <rarg> is the &rest argument symbol X <karg> is a &key argument symbol X <key> is a keyword symbol X <aux> is an auxiliary variable symbol X <init> is an initialization expression X <svar> is a supplied-p variable symbol X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X XLISP OBJECTS Page 14 X X X OBJECTS X X Definitions: X X o selector - a symbol used to select an appropriate method X o message - a selector and a list of actual arguments X o method - the code that implements a message X X Since XLISP was created to provide a simple basis for X experimenting with object-oriented programming, one of the X primitive data types included is 'object'. In XLISP, an object X consists of a data structure containing a pointer to the X object's class as well as an array containing the values of the X object's instance variables. X X Officially, there is no way to see inside an object (look at the X values of its instance variables). The only way to communicate X with an object is by sending it a message. X X You can send a message to an object using the 'send' function. X This function takes the object as its first argument, the X message selector as its second argument (which must be a symbol) X and the message arguments as its remaining arguments. X X The 'send' function determines the class of the receiving object X and attempts to find a method corresponding to the message X selector in the set of messages defined for that class. If the X message is not found in the object's class and the class has a X super-class, the search continues by looking at the messages X defined for the super-class. This process continues from one X super-class to the next until a method for the message is found. X If no method is found, an error occurs. X X A message can also be sent from the body of a method by using X the current object, but the method lookup starts with the X object's superclass rather than its class. This allows a X subclass to invoke a standard method in its parent class even X though it overrides that method with its own specialized X version. X X When a method is found, the evaluator binds the receiving object X to the symbol 'self' and evaluates the method using the X remaining elements of the original list as arguments to the X method. These arguments are always evaluated prior to being X bound to their corresponding formal arguments. The result of X evaluating the method becomes the result of the expression. X X X X X X X X X X X X X X X X X X XLISP OBJECTS Page 15 X X X THE 'Object' CLASS X X Classes: X X Object THE TOP OF THE CLASS HEIRARCHY X X Messages: X X :show SHOW AN OBJECT'S INSTANCE VARIABLES X returns the object X X :class RETURN THE CLASS OF AN OBJECT X returns the class of the object X X :isnew THE DEFAULT OBJECT INITIALIZATION ROUTINE X returns the object X X :sendsuper <sel> <args>... SEND SUPERCLASS A MESSAGE X <sel> the message selector X <args> the message arguments X returns the result of sending the message X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X XLISP OBJECTS Page 16 X X X THE 'Class' CLASS X X Class THE CLASS OF ALL OBJECT CLASSES (including itself) X X Messages: X X :new CREATE A NEW INSTANCE OF A CLASS X returns the new class object X X :isnew <ivars> [<cvars> [<super>]] INITIALIZE A NEW CLASS X <ivars> the list of instance variable symbols X <cvars> the list of class variable symbols X <super> the superclass (default is Object) X returns the new class object X X :answer <msg> <fargs> <code> ADD A MESSAGE TO A CLASS X <msg> the message symbol X <fargs> the formal argument list (lambda list) X <code> a list of executable expressions X returns the object X X X When a new instance of a class is created by sending the message X ':new' to an existing class, the message ':isnew' followed by X whatever parameters were passed to the ':new' message is sent to X the newly created object. X X When a new class is created by sending the ':new' message to the X object 'Class', an optional parameter may be specified X indicating the superclass of the new class. If this parameter X is omitted, the new class will be a subclass of 'Object'. A X class inherits all instance variables, class variables, and X methods from its super-class. X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X XLISP SYMBOLS Page 17 X X X SYMBOLS X X o self - the current object (within a method context) X o *obarray* - the object hash table X o *standard-input* - the standard input stream X o *standard-output* - the standard output stream X o *error-output* - the error output stream X o *trace-output* - the trace output stream X o *debug-io* - the debug i/o stream X o *breakenable* - flag controlling entering break loop on errors X o *tracelist* - list of names of functions to trace X o *tracenable* - enable trace back printout on errors X o *tracelimit* - number of levels of trace back information X o *evalhook* - user substitute for the evaluator function X o *applyhook* - (not yet implemented) X o *readtable* - the current readtable X o *unbound* - indicator for unbound symbols X o *gc-flag* - controls the printing of gc messages X o *gc-hook* - function to call after garbage collection X o *integer-format* - format for printing integers ("%d" or "%ld") X o *float-format* - format for printing floats ("%g") X o *print-case* - symbol output case (:upcase or :downcase) X X There are several symbols maintained by the read/eval/print X loop. The symbols '+', '++', and '+++' are bound to the most X recent three input expressions. The symbols '*', '**' and '***' X are bound to the most recent three results. The symbol '-' is X bound to the expression currently being evaluated. It becomes X the value of '+' at the end of the evaluation. X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X XLISP EVALUATION FUNCTIONS Page 18 X X X EVALUATION FUNCTIONS X X (eval <expr>) EVALUATE AN XLISP EXPRESSION X <expr> the expression to be evaluated X returns the result of evaluating the expression X X (apply <fun> <args>) APPLY A FUNCTION TO A LIST OF ARGUMENTS X <fun> the function to apply (or function symbol) X <args> the argument list X returns the result of applying the function to the arguments X X (funcall <fun> <arg>...) CALL A FUNCTION WITH ARGUMENTS X <fun> the function to call (or function symbol) X <arg> arguments to pass to the function X returns the result of calling the function with the arguments X X (quote <expr>) RETURN AN EXPRESSION UNEVALUATED X <expr> the expression to be quoted (quoted) X returns <expr> unevaluated X X (function <expr>) GET THE FUNCTIONAL INTERPRETATION X <expr> the symbol or lambda expression (quoted) X returns the functional interpretation X X (backquote <expr>) FILL IN A TEMPLATE X <expr> the template X returns a copy of the template with comma and comma-at X expressions expanded X X (lambda <args> <expr>...) MAKE A FUNCTION CLOSURE X <args> formal argument list (lambda list) (quoted) X <expr> expressions of the function body X returns the function closure X X (get-lambda-expression <closure>) GET THE LAMBDA EXPRESSION X <closure> the closure X returns the original lambda expression X X (macroexpand <form>) RECURSIVELY EXPAND MACRO CALLS X <form> the form to expand X returns the macro expansion X X (macroexpand-1 <form>) EXPAND A MACRO CALL X <form> the macro call form X returns the macro expansion X X X X X X X X X X X X X X X X X X X XLISP SYMBOL FUNCTIONS Page 19 X X X SYMBOL FUNCTIONS X X (set <sym> <expr>) SET THE VALUE OF A SYMBOL X <sym> the symbol being set X <expr> the new value X returns the new value X X (setq [<sym> <expr>]...) SET THE VALUE OF A SYMBOL X <sym> the symbol being set (quoted) X <expr> the new value X returns the new value X X (psetq [<sym> <expr>]...) PARALLEL VERSION OF SETQ X <sym> the symbol being set (quoted) X <expr> the new value X returns the new value X X (setf [<place> <expr>]...) SET THE VALUE OF A FIELD X <place> the field specifier (quoted): X <sym> set value of a symbol X (car <expr>) set car of a cons node X (cdr <expr>) set cdr of a cons node X (nth <n> <expr>) set nth car of a list X (aref <expr> <n>) set nth element of an array X (get <sym> <prop>) set value of a property X (symbol-value <sym>) set value of a symbol X (symbol-function <sym>) set functional value of a symbol X (symbol-plist <sym>) set property list of a symbol X <value> the new value X returns the new value X X (defun <sym> <fargs> <expr>...) DEFINE A FUNCTION X (defmacro <sym> <fargs> <expr>...) DEFINE A MACRO X <sym> symbol being defined (quoted) X <fargs> formal argument list (lambda list) (quoted) X <expr> expressions constituting the body of the X function (quoted) X returns the function symbol X X (gensym [<tag>]) GENERATE A SYMBOL X <tag> string or number X returns the new symbol X X (intern <pname>) MAKE AN INTERNED SYMBOL X <pname> the symbol's print name string X returns the new symbol X X (make-symbol <pname>) MAKE AN UNINTERNED SYMBOL X <pname> the symbol's print name string X returns the new symbol X X (symbol-name <sym>) GET THE PRINT NAME OF A SYMBOL X <sym> the symbol X returns the symbol's print name X X X X X X X X X X XLISP SYMBOL FUNCTIONS Page 20 X X X (symbol-value <sym>) GET THE VALUE OF A SYMBOL X <sym> the symbol X returns the symbol's value X X (symbol-function <sym>) GET THE FUNCTIONAL VALUE OF A SYMBOL X <sym> the symbol X returns the symbol's functional value X X (symbol-plist <sym>) GET THE PROPERTY LIST OF A SYMBOL X <sym> the symbol X returns the symbol's property list X X (hash <sym> <n>) COMPUTE THE HASH INDEX FOR A SYMBOL X <sym> the symbol or string X <n> the table size (integer) X returns the hash index (integer) X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X XLISP PROPERTY LIST FUNCTIONS Page 21 X X X PROPERTY LIST FUNCTIONS X X (get <sym> <prop>) GET THE VALUE OF A PROPERTY X <sym> the symbol X <prop> the property symbol X returns the property value or nil X X (putprop <sym> <val> <prop>) PUT A PROPERTY ONTO A PROPERTY LIST X <sym> the symbol X <val> the property value X <prop> the property symbol X returns the property value X X (remprop <sym> <prop>) REMOVE A PROPERTY X <sym> the symbol X <prop> the property symbol X returns nil X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X XLISP ARRAY FUNCTIONS Page 22 X X X ARRAY FUNCTIONS X X (aref <array> <n>) GET THE NTH ELEMENT OF AN ARRAY X <array> the array X <n> the array index (integer) X returns the value of the array element X X (make-array <size>) MAKE A NEW ARRAY X <size> the size of the new array (integer) X returns the new array X X (vector <expr>...) MAKE AN INITIALIZED VECTOR X <expr> the vector elements X returns the new vector X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X XLISP LIST FUNCTIONS Page 23 X X X LIST FUNCTIONS X X (car <expr>) RETURN THE CAR OF A LIST NODE X <expr> the list node X returns the car of the list node X X (cdr <expr>) RETURN THE CDR OF A LIST NODE X <expr> the list node X returns the cdr of the list node X X (cxxr <expr>) ALL CxxR COMBINATIONS X (cxxxr <expr>) ALL CxxxR COMBINATIONS X (cxxxxr <expr>) ALL CxxxxR COMBINATIONS X X (first <expr>) A SYNONYM FOR CAR X (second <expr>) A SYNONYM FOR CADR X (third <expr>) A SYNONYM FOR CADDR X (fourth <expr>) A SYNONYM FOR CADDDR X (rest <expr>) A SYNONYM FOR CDR X X (cons <expr1> <expr2>) CONSTRUCT A NEW LIST NODE X <expr1> the car of the new list node X <expr2> the cdr of the new list node X returns the new list node X X (list <expr>...) CREATE A LIST OF VALUES X <expr> expressions to be combined into a list X returns the new list X X (append <expr>...) APPEND LISTS X <expr> lists whose elements are to be appended X returns the new list X X (reverse <expr>) REVERSE A LIST X <expr> the list to reverse X returns a new list in the reverse order X X (last <list>) RETURN THE LAST LIST NODE OF A LIST X <list> the list X returns the last list node in the list X X (member <expr> <list> &key :test :test-not) FIND AN EXPRESSION IN A LIST X <expr> the expression to find X <list> the list to search X :test the test function (defaults to eql) X :test-not the test function (sense inverted) X returns the remainder of the list starting with the expression X X (assoc <expr> <alist> &key :test :test-not) FIND AN EXPRESSION IN AN A-LIST X <expr> the expression to find X <alist> the association list X :test the test function (defaults to eql) X :test-not the test function (sense inverted) X returns the alist entry or nil X X X X X X X X X X XLISP LIST FUNCTIONS Page 24 X X X (remove <expr> <list> &key :test :test-not) REMOVE ELEMENTS FROM A LIST X <expr> the element to remove X <list> the list X :test the test function (defaults to eql) X :test-not the test function (sense inverted) X returns copy of list with matching expressions removed X X (remove-if <test> <list>) REMOVE ELEMENTS THAT PASS TEST X <test> the test predicate X <list> the list X returns copy of list with matching elements removed X X (remove-if-not <test> <list>) REMOVE ELEMENTS THAT FAIL TEST X <test> the test predicate X <list> the list X returns copy of list with non-matching elements removed X X (length <expr>) FIND THE LENGTH OF A LIST, VECTOR OR STRING X <expr> the list, vector or string X returns the length of the list, vector or string X X (nth <n> <list>) RETURN THE NTH ELEMENT OF A LIST X <n> the number of the element to return (zero origin) X <list> the list X returns the nth element or nil if the list isn't that long X X (nthcdr <n> <list>) RETURN THE NTH CDR OF A LIST X <n> the number of the element to return (zero origin) X <list> the list X returns the nth cdr or nil if the list isn't that long X X (mapc <fcn> <list1> <list>...) APPLY FUNCTION TO SUCCESSIVE CARS X <fcn> the function or function name X <listn> a list for each argument of the function X returns the first list of arguments X X (mapcar <fcn> <list1> <list>...) APPLY FUNCTION TO SUCCESSIVE CARS X <fcn> the function or function name X <listn> a list for each argument of the function X returns a list of the values returned X X (mapl <fcn> <list1> <list>...) APPLY FUNCTION TO SUCCESSIVE CDRS X <fcn> the function or function name X <listn> a list for each argument of the function X returns the first list of arguments X X (maplist <fcn> <list1> <list>...) APPLY FUNCTION TO SUCCESSIVE CDRS X <fcn> the function or function name X <listn> a list for each argument of the function X returns a list of the values returned X X X X X X X X X X X X X X XLISP LIST FUNCTIONS Page 25 X X X (subst <to> <from> <expr> &key :test :test-not) SUBSTITUTE EXPRESSIONS X <to> the new expression X <from> the old expression X <expr> the expression in which to do the substitutions X :test the test function (defaults to eql) X :test-not the test function (sense inverted) X returns the expression with substitutions X X (sublis <alist> <expr> &key :test :test-not) SUBSTITUTE WITH AN A-LIST X <alist> the association list X <expr> the expression in which to do the substitutions X :test the test function (defaults to eql) X :test-not the test function (sense inverted) X returns the expression with substitutions X X X X X X X X X XLISP DESTRUCTIVE LIST FUNCTIONS Page 26 X X X DESTRUCTIVE LIST FUNCTIONS X X (rplaca <list> <expr>) REPLACE THE CAR OF A LIST NODE X <list> the list node X <expr> the new value for the car of the list node X returns the list node after updating the car X X (rplacd <list> <expr>) REPLACE THE CDR OF A LIST NODE X <list> the list node X <expr> the new value for the cdr of the list node X returns the list node after updating the cdr X X (nconc <list>...) DESTRUCTIVELY CONCATENATE LISTS X <list> lists to concatenate X returns the result of concatenating the lists X X (delete <expr> &key :test :test-not) DELETE ELEMENTS FROM A LIST X <expr> the element to delete X <list> the list X :test the test function (defaults to eql) X :test-not the test function (sense inverted) X returns the list with the matching expressions deleted X X (delete-if <test> <list>) DELETE ELEMENTS THAT PASS TEST X <test> the test predicate X <list> the list X returns the list with matching elements deleted X X (delete-if-not <test> <list>) DELETE ELEMENTS THAT FAIL TEST X <test> the test predicate X <list> the list X returns the list with non-matching elements deleted X X (sort <list> <test>) SORT A LIST X <list> the list to sort X <test> the comparison function X returns the sorted list X X X X X X X X X X X X X X X X X X X X X X X X X X X XLISP PREDICATE FUNCTIONS Page 27 X X X PREDICATE FUNCTIONS X X (atom <expr>) IS THIS AN ATOM? X <expr> the expression to check X returns t if the value is an atom, nil otherwise X X (symbolp <expr>) IS THIS A SYMBOL? X <expr> the expression to check X returns t if the expression is a symbol, nil otherwise X X (numberp <expr>) IS THIS A NUMBER? X <expr> the expression to check X returns t if the expression is a number, nil otherwise X X (null <expr>) IS THIS AN EMPTY LIST? X <expr> the list to check X returns t if the list is empty, nil otherwise X X (not <expr>) IS THIS FALSE? X <expr> the expression to check X return t if the value is nil, nil otherwise X X (listp <expr>) IS THIS A LIST? X <expr> the expression to check X returns t if the value is a cons or nil, nil otherwise X X (endp <list>) IS THIS THE END OF A LIST X <list> the list X returns t if the value is nil, nil otherwise X X (consp <expr>) IS THIS A NON-EMPTY LIST? X <expr> the expression to check X returns t if the value is a cons, nil otherwise X X (integerp <expr>) IS THIS AN INTEGER? X <expr> the expression to check X returns t if the value is an integer, nil otherwise X X (floatp <expr>) IS THIS A FLOAT? X <expr> the expression to check X returns t if the value is a float, nil otherwise X X (stringp <expr>) IS THIS A STRING? X <expr> the expression to check X returns t if the value is a string, nil otherwise X X (characterp <expr>) IS THIS A CHARACTER? X <expr> the expression to check X returns t if the value is a character, nil otherwise X X (arrayp <expr>) IS THIS AN ARRAY? X <expr> the expression to check X returns t if the value is an array, nil otherwise X X X X X X X X X X X XLISP PREDICATE FUNCTIONS Page 28 X X X (streamp <expr>) IS THIS A STREAM? X <expr> the expression to check X returns t if the value is a stream, nil otherwise X X (objectp <expr>) IS THIS AN OBJECT? X <expr> the expression to check X returns t if the value is an object, nil otherwise X X (boundp <sym>) IS A VALUE BOUND TO THIS SYMBOL? X <sym> the symbol X returns t if a value is bound to the symbol, nil otherwise X X (fboundp <sym>) IS A FUNCTIONAL VALUE BOUND TO THIS SYMBOL? X <sym> the symbol X returns t if a functional value is bound to the symbol, X nil otherwise X X (minusp <expr>) IS THIS NUMBER NEGATIVE? X <expr> the number to test X returns t if the number is negative, nil otherwise X X (zerop <expr>) IS THIS NUMBER ZERO? X <expr> the number to test X returns t if the number is zero, nil otherwise X X (plusp <expr>) IS THIS NUMBER POSITIVE? X <expr> the number to test X returns t if the number is positive, nil otherwise X X (evenp <expr>) IS THIS INTEGER EVEN? X <expr> the integer to test X returns t if the integer is even, nil otherwise X X (oddp <expr>) IS THIS INTEGER ODD? X <expr> the integer to test X returns t if the integer is odd, nil otherwise X X (eq <expr1> <expr2>) ARE THE EXPRESSIONS IDENTICAL? X <expr1> the first expression X <expr2> the second expression X returns t if they are equal, nil otherwise X X (eql <expr1> <expr2>) ARE THE EXPRESSIONS IDENTICAL? X (WORKS WITH ALL NUMBERS) X <expr1> the first expression X <expr2> the second expression X returns t if they are equal, nil otherwise X X (equal <expr1> <expr2>) ARE THE EXPRESSIONS EQUAL? X <expr1> the first expression X <expr2> the second expression X returns t if they are equal, nil otherwise X X X X X X X X X X X X XLISP CONTROL CONSTRUCTS Page 29 X X X CONTROL CONSTRUCTS X X (cond <pair>...) EVALUATE CONDITIONALLY X <pair> pair consisting of: X (<pred> <expr>...) X where X <pred> is a predicate expression X <expr> evaluated if the predicate X is not nil X returns the value of the first expression whose predicate X is not nil X X (and <expr>...) THE LOGICAL AND OF A LIST OF EXPRESSIONS X <expr> the expressions to be ANDed X returns nil if any expression evaluates to nil, X otherwise the value of the last expression X (evaluation of expressions stops after the first X expression that evaluates to nil) X X (or <expr>...) THE LOGICAL OR OF A LIST OF EXPRESSIONS X <expr> the expressions to be ORed X returns nil if all expressions evaluate to nil, X otherwise the value of the first non-nil expression X (evaluation of expressions stops after the first X expression that does not evaluate to nil) X X (if <texpr> <expr1> [<expr2>]) EVALUATE EXPRESSIONS CONDITIONALLY X <texpr> the test expression X <expr1> the expression to be evaluated if texpr is non-nil X <expr2> the expression to be evaluated if texpr is nil X returns the value of the selected expression X X (when <texpr> <expr>...) EVALUATE ONLY WHEN A CONDITION IS TRUE X <texpr> the test expression X <expr> the expression(s) to be evaluted if texpr is non-nil X returns the value of the last expression or nil X X (unless <texpr> <expr>...) EVALUATE ONLY WHEN A CONDITION IS FALSE X <texpr> the test expression X <expr> the expression(s) to be evaluated if texpr is nil X returns the value of the last expression or nil X X (case <expr> <case>...) SELECT BY CASE X <expr> the selection expression X <case> pair consisting of: X (<value> <expr>...) X where: X <value> is a single expression or a list of X expressions (unevaluated) X <expr> are expressions to execute if the X case matches X returns the value of the last expression of the matching case X X X X X X X X X X X X XLISP CONTROL CONSTRUCTS Page 30 X X X (let (<binding>...) <expr>...) CREATE LOCAL BINDINGS X (let* (<binding>...) <expr>...) LET WITH SEQUENTIAL BINDING X <binding> the variable bindings each of which is either: X 1) a symbol (which is initialized to nil) X 2) a list whose car is a symbol and whose cadr X is an initialization expression X <expr> the expressions to be evaluated X returns the value of the last expression X X (flet (<binding>...) <expr>...) CREATE LOCAL FUNCTIONS X (labels (<binding>...) <expr>...) FLET WITH RECURSIVE FUNCTIONS X (macrolet (<binding>...) <expr>...) CREATE LOCAL MACROS X <binding> the function bindings each of which is: X (<sym> <fargs> <expr>...) X where: X <sym> the function/macro name X <fargs> formal argument list (lambda list) X <expr> expressions constituting the body of X the function/macro X <expr> the expressions to be evaluated X returns the value of the last expression X X (catch <sym> <expr>...) EVALUATE EXPRESSIONS AND CATCH THROWS X <sym> the catch tag X <expr> expressions to evaluate X returns the value of the last expression the throw expression X X (throw <sym> [<expr>]) THROW TO A CATCH X <sym> the catch tag X <expr> the value for the catch to return (defaults to nil) X returns never returns X X (unwind-protect <expr> <cexpr>...) PROTECT EVALUATION OF AN EXPRESSION X <expr> the expression to protect X <cexpr> the cleanup expressions X returns the value of the expression X Note: unwind-protect guarantees to execute the cleanup expressions X even if a non-local exit terminates the evaluation of the X protected expression X X X X X X X X X X X X X X X X X X X X X X X X X XLISP LOOPING CONSTRUCTS Page 31 X X X LOOPING CONSTRUCTS X X (loop <expr>...) BASIC LOOPING FORM X <expr> the body of the loop X returns never returns (must use non-local exit) X X (do (<binding>...) (<texpr> <rexpr>...) <expr>...) X (do* (<binding>...) (<texpr> <rexpr>...) <expr>...) X <binding> the variable bindings each of which is either: X 1) a symbol (which is initialized to nil) X 2) a list of the form: (<sym> <init> [<step>]) X where: X <sym> is the symbol to bind X <init> is the initial value of the symbol X <step> is a step expression X <texpr> the termination test expression X <rexpr> result expressions (the default is nil) X <expr> the body of the loop (treated like an implicit prog) X returns the value of the last result expression X X (dolist (<sym> <expr> [<rexpr>]) <expr>...) LOOP THROUGH A LIST X <sym> the symbol to bind to each list element X <expr> the list expression X <rexpr> the result expression (the default is nil) X <expr> the body of the loop (treated like an implicit prog) X X (dotimes (<sym> <expr> [<rexpr>]) <expr>...) LOOP FROM ZERO TO N-1 X <sym> the symbol to bind to each value from 0 to n-1 X <expr> the number of times to loop X <rexpr> the result expression (the default is nil) X <expr> the body of the loop (treated like an implicit prog) X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X XLISP THE PROGRAM FEATURE Page 32 X X X THE PROGRAM FEATURE X X (prog (<binding>...) <expr>...) THE PROGRAM FEATURE X (prog* (<binding>...) <expr>...) PROG WITH SEQUENTIAL BINDING X <binding> the variable bindings each of which is either: X 1) a symbol (which is initialized to nil) X 2) a list whose car is a symbol and whose cadr X is an initialization expression X <expr> expressions to evaluate or tags (symbols) X returns nil or the argument passed to the return function X X (block <name> <expr>...) NAMED BLOCK X <name> the block name (symbol) X <expr> the block body X returns the value of the last expression X X (return [<expr>]) CAUSE A PROG CONSTRUCT TO RETURN A VALUE X <expr> the value (defaults to nil) X returns never returns X X (return-from <name> [<value>]) RETURN FROM A NAMED BLOCK X <name> the block name (symbol) X <value> the value to return (defaults to nil) X returns never returns X X (tagbody <expr>...) BLOCK WITH LABELS X <expr> expression(s) to evaluate or tags (symbols) X returns nil X X (go <sym>) GO TO A TAG WITHIN A TAGBODY OR PROG X <sym> the tag (quoted) X returns never returns X X (progv <slist> <vlist> <expr>...) DYNAMICALLY BIND SYMBOLS X <slist> list of symbols X <vlist> list of values to bind to the symbols X <expr> expression(s) to evaluate X returns the value of the last expression X X (prog1 <expr1> <expr>...) EXECUTE EXPRESSIONS SEQUENTIALLY X <expr1> the first expression to evaluate X <expr> the remaining expressions to evaluate X returns the value of the first expression X X (prog2 <expr1> <expr2> <expr>...) EXECUTE EXPRESSIONS SEQUENTIALLY X <expr1> the first expression to evaluate X <expr2> the second expression to evaluate X <expr> the remaining expressions to evaluate X returns the value of the second expression X X (progn <expr>...) EXECUTE EXPRESSIONS SEQUENTIALLY X <expr> the expressions to evaluate X returns the value of the last expression (or nil) X X X X X X X X X X X XLISP DEBUGGING AND ERROR HANDLING Page 33 X X X DEBUGGING AND ERROR HANDLING X X (trace <sym>) ADD A FUNCTION TO THE TRACE LIST X <sym> the function to add (quoted) X returns the trace list X X (untrace <sym>) REMOVE A FUNCTION FROM THE TRACE LIST X <sym> the function to remove (quoted) X returns the trace list X X (error <emsg> [<arg>]) SIGNAL A NON-CORRECTABLE ERROR X <emsg> the error message string X <arg> the argument expression (printed after the message) X returns never returns X X (cerror <cmsg> <emsg> [<arg>]) SIGNAL A CORRECTABLE ERROR X <cmsg> the continue message string X <emsg> the error message string X <arg> the argument expression (printed after the message) X returns nil when continued from the break loop X X (break [<bmsg> [<arg>]]) ENTER A BREAK LOOP X <bmsg> the break message string (defaults to "**BREAK**") X <arg> the argument expression (printed after the message) X returns nil when continued from the break loop X X (clean-up) CLEAN-UP AFTER AN ERROR X returns never returns X X (top-level) CLEAN-UP AFTER AN ERROR AND RETURN TO THE TOP LEVEL X returns never returns X X (continue) CONTINUE FROM A CORRECTABLE ERROR X returns never returns X X (errset <expr> [<pflag>]) TRAP ERRORS X <expr> the expression to execute X <pflag> flag to control printing of the error message X returns the value of the last expression consed with nil X or nil on error X X (baktrace [<n>]) PRINT N LEVELS OF TRACE BACK INFORMATION X <n> the number of levels (defaults to all levels) X returns nil X X (evalhook <expr> <ehook> <ahook> [<env>]) EVALUATE WITH HOOKS X <expr> the expression to evaluate X <ehook> the value for *evalhook* X <ahook> the value for *applyhook* X <env> the environment (default is nil) X returns the result of evaluating the expression X X X X X X X X X X X X X XLISP ARITHMETIC FUNCTIONS Page 34 X X X ARITHMETIC FUNCTIONS X X (truncate <expr>) TRUNCATES A FLOATING POINT NUMBER TO AN INTEGER X <expr> the number X returns the result of truncating the number X X (float <expr>) CONVERTS AN INTEGER TO A FLOATING POINT NUMBER X <expr> the number X returns the result of floating the integer X X (+ <expr>...) ADD A LIST OF NUMBERS X <expr> the numbers X returns the result of the addition X X (- <expr>...) SUBTRACT A LIST OF NUMBERS OR NEGATE A SINGLE NUMBER X <expr> the numbers X returns the result of the subtraction X X (* <expr>...) MULTIPLY A LIST OF NUMBERS X <expr> the numbers X returns the result of the multiplication X X (/ <expr>...) DIVIDE A LIST OF NUMBERS X <expr> the numbers X returns the result of the division X X (1+ <expr>) ADD ONE TO A NUMBER X <expr> the number X returns the number plus one X X (1- <expr>) SUBTRACT ONE FROM A NUMBER X <expr> the number X returns the number minus one X X (rem <expr>...) REMAINDER OF A LIST OF NUMBERS X <expr> the numbers X returns the result of the remainder operation X X (min <expr>...) THE SMALLEST OF A LIST OF NUMBERS X <expr> the expressions to be checked X returns the smallest number in the list X X (max <expr>...) THE LARGEST OF A LIST OF NUMBERS X <expr> the expressions to be checked X returns the largest number in the list X X (abs <expr>) THE ABSOLUTE VALUE OF A NUMBER X <expr> the number X returns the absolute value of the number X X (gcd <n1> <n2>...) COMPUTE THE GREATEST COMMON DIVISOR X <n1> the first number (integer) X <n2> the second number(s) (integer) X returns the greatest common divisor X X X X X X X X X X XLISP ARITHMETIC FUNCTIONS Page 35 X X X (random <n>) COMPUTE A RANDOM NUMBER BETWEEN 1 and N-1 X <n> the upper bound (integer) X returns a random number X X (sin <expr>) COMPUTE THE SINE OF A NUMBER X <expr> the floating point number X returns the sine of the number X X (cos <expr>) COMPUTE THE COSINE OF A NUMBER X <expr> the floating point number X returns the cosine of the number X X (tan <expr>) COMPUTE THE TANGENT OF A NUMBER X <expr> the floating point number X returns the tangent of the number X X (expt <x-expr> <y-expr>) COMPUTE X TO THE Y POWER X <x-expr> the floating point number X <y-expr> the floating point exponent X returns x to the y power X X (exp <x-expr>) COMPUTE E TO THE X POWER X <x-expr> the floating point number X returns e to the x power X X (sqrt <expr>) COMPUTE THE SQUARE ROOT OF A NUMBER X <expr> the floating point number X returns the square root of the number X X (< <n1> <n2>...) TEST FOR LESS THAN X (<= <n1> <n2>...) TEST FOR LESS THAN OR EQUAL TO X (= <n1> <n2>...) TEST FOR EQUAL TO X (/= <n1> <n2>...) TEST FOR NOT EQUAL TO X (>= <n1> <n2>...) TEST FOR GREATER THAN OR EQUAL TO X (> <n1> <n2>...) TEST FOR GREATER THAN X <n1> the first number to compare X <n2> the second number to compare X returns the result of comparing <n1> with <n2>... X X X X X X X X X X X X X X X X X X X X X X X X X X XLISP BITWISE LOGICAL FUNCTIONS Page 36 X X X BITWISE LOGICAL FUNCTIONS X X (logand <expr>...) THE BITWISE AND OF A LIST OF NUMBERS X <expr> the numbers X returns the result of the and operation X X (logior <expr>...) THE BITWISE INCLUSIVE OR OF A LIST OF NUMBERS X <expr> the numbers X returns the result of the inclusive or operation X X (logxor <expr>...) THE BITWISE EXCLUSIVE OR OF A LIST OF NUMBERS X <expr> the numbers X returns the result of the exclusive or operation X X (lognot <expr>) THE BITWISE NOT OF A NUMBER X <expr> the number X returns the bitwise inversion of number X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X XLISP STRING FUNCTIONS Page 37 X X X STRING FUNCTIONS X X (string <expr>) MAKE A STRING FROM AN INTEGER ASCII VALUE X <expr> the integer X returns a one character string X X (string-trim <bag> <str>) TRIM BOTH ENDS OF A STRING X <bag> a string containing characters to trim X <str> the string to trim X returns a trimed copy of the string X X (string-left-trim <bag> <str>) TRIM THE LEFT END OF A STRING X <bag> a string containing characters to trim X <str> the string to trim X returns a trimed copy of the string X X (string-right-trim <bag> <str>) TRIM THE RIGHT END OF A STRING X <bag> a string containing characters to trim X <str> the string to trim X returns a trimed copy of the string X X (string-upcase <str> &key :start :end) CONVERT TO UPPERCASE X <str> the string X :start the starting offset X :end the ending offset + 1 X returns a converted copy of the string X X (string-downcase <str> &key :start :end) CONVERT TO LOWERCASE X <str> the string X :start the starting offset X :end the ending offset + 1 X returns a converted copy of the string X X (nstring-upcase <str> &key :start :end) CONVERT TO UPPERCASE X <str> the string X :start the starting offset X :end the ending offset + 1 X returns the converted string (not a copy) X X (nstring-downcase <str> &key :start :end) CONVERT TO LOWERCASE X <str> the string X :start the starting offset X :end the ending offset + 1 X returns the converted string (not a copy) X X (strcat <expr>...) CONCATENATE STRINGS X <expr> the strings to concatenate X returns the result of concatenating the strings X X (subseq <string> <start> [<end>]) EXTRACT A SUBSTRING X <string> the string X <start> the starting position (zero origin) X <end> the ending position + 1 (defaults to end) X returns substring between <start> and <end> X X X X X X X X X X XLISP STRING FUNCTIONS Page 38 X X X (string< <str1> <str2> &key :start1 :end1 :start2 :end2) X (string<= <str1> <str2> &key :start1 :end1 :start2 :end2) X (string= <str1> <str2> &key :start1 :end1 :start2 :end2) X (string/= <str1> <str2> &key :start1 :end1 :start2 :end2) X (string>= <str1> <str2> &key :start1 :end1 :start2 :end2) X (string> <str1> <str2> &key :start1 :end1 :start2 :end2) X <str1> the first string to compare X <str2> the second string to compare X :start1 first substring starting offset X :end1 first substring ending offset + 1 X :start2 second substring starting offset X :end2 second substring ending offset + 1 X returns t if predicate is true, nil otherwise X Note: case is significant with these comparison functions. X X (string-lessp <str1> <str2> &key :start1 :end1 :start2 :end2) X (string-not-greaterp <str1> <str2> &key :start1 :end1 :start2 :end2) X (string-equalp <str1> <str2> &key :start1 :end1 :start2 :end2) X (string-not-equalp <str1> <str2> &key :start1 :end1 :start2 :end2) X (string-not-lessp <str1> <str2> &key :start1 :end1 :start2 :end2) X (string-greaterp <str1> <str2> &key :start1 :end1 :start2 :end2) X <str1> the first string to compare X <str2> the second string to compare X :start1 first substring starting offset X :end1 first substring ending offset + 1 X :start2 second substring starting offset X :end2 second substring ending offset + 1 X returns t if predicate is true, nil otherwise X Note: case is not significant with these comparison functions. X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X XLISP CHARACTER FUNCTIONS Page 39 X X X CHARACTER FUNCTIONS X X (char <string> <index>) EXTRACT A CHARACTER FROM A STRING X <string> the string X <index> the string index (zero relative) X returns the ascii code of the character X X (upper-case-p <chr>) IS THIS AN UPPER CASE CHARACTER? X <chr> the character X returns true if the character is upper case, nil otherwise X X (lower-case-p <chr>) IS THIS A LOWER CASE CHARACTER? X <chr> the character X returns true if the character is lower case, nil otherwise X X (both-case-p <chr>) IS THIS AN ALPHABETIC (EITHER CASE) CHARACTER? X <chr> the character X returns true if the character is alphabetic, nil otherwise X X (digit-char-p <chr>) IS THIS A DIGIT CHARACTER? X <chr> the character X returns the digit weight if character is a digit, nil otherwise X X (char-code <chr>) GET THE ASCII CODE OF A CHARACTER X <chr> the character X returns the ASCII character code (integer) X X (code-char <code>) GET THE CHARACTER WITH A SPECFIED ASCII CODE X <code> the ASCII code (integer) X returns the character with that code or nil X X (char-upcase <chr>) CONVERT A CHARACTER TO UPPER CASE X <chr> the character X returns the upper case character X X (char-downcase <chr>) CONVERT A CHARACTER TO LOWER CASE X <chr> the character X returns the lower case character X X (digit-char <n>) CONVERT A DIGIT WEIGHT TO A DIGIT X <n> the digit weight (integer) X returns the digit character or nil X X (char-int <chr>) CONVERT A CHARACTER TO AN INTEGER X <chr> the character X returns the ASCII character code X X (int-char <int>) CONVERT AN INTEGER TO A CHARACTER X <int> the ASCII character code X returns the character with that code X X X X X X X X X X X X X X XLISP CHARACTER FUNCTIONS Page 40 X X X (char< <chr1> <chr2>...) X (char<= <chr1> <chr2>...) X (char= <chr1> <chr2>...) X (char/= <chr1> <chr2>...) X (char>= <chr1> <chr2>...) X (char> <chr1> <chr2>...) X <chr1> the first character to compare X <chr2> the second character(s) to compare X returns t if predicate is true, nil otherwise X Note: case is significant with these comparison functions. X X (char-lessp <chr1> <chr2>...) X (char-not-greaterp <chr1> <chr2>...) X (char-equalp <chr1> <chr2>...) X (char-not-equalp <chr1> <chr2>...) X (char-not-lessp <chr1> <chr2>...) X (char-greaterp <chr1> <chr2>...) X <chr1> the first string to compare X <chr2> the second string(s) to compare X returns t if predicate is true, nil otherwise X Note: case is not significant with these comparison functions. X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X XLISP INPUT/OUTPUT FUNCTIONS Page 41 X X X INPUT/OUTPUT FUNCTIONS X X (read [<stream> [<eof> [<rflag>]]]) READ AN EXPRESSION X <stream> the input stream (default is standard input) X <eof> the value to return on end of file (default is nil) X <rflag> recursive read flag (default is nil) X returns the expression read X X (print <expr> [<stream>]) PRINT AN EXPRESSION ON A NEW LINE X <expr> the expression to be printed X <stream> the output stream (default is standard output) X returns the expression X X (prin1 <expr> [<stream>]) PRINT AN EXPRESSION X <expr> the expression to be printed X <stream> the output stream (default is standard output) X returns the expression X X (princ <expr> [<stream>]) PRINT AN EXPRESSION WITHOUT QUOTING X <expr> the expressions to be printed X <stream> the output stream (default is standard output) X returns the expression X X (pprint <expr> [<stream>]) PRETTY PRINT AN EXPRESSION X <expr> the expressions to be printed X <stream> the output stream (default is standard output) X returns the expression X X (terpri [<stream>]) TERMINATE THE CURRENT PRINT LINE X <stream> the output stream (default is standard output) X returns nil X X (flatsize <expr>) LENGTH OF PRINTED REPRESENTATION USING PRIN1 X <expr> the expression X returns the length X X (flatc <expr>) LENGTH OF PRINTED REPRESENTATION USING PRINC X <expr> the expression X returns the length X X X X X X X X X X X X X X X X X X X X X X X X X XLISP THE FORMAT FUNCTION Page 42 X X X THE FORMAT FUNCTION X X (format <stream> <fmt> <arg>...) DO FORMATTED OUTPUT X <stream> the output stream X <fmt> the format string X <arg> the format arguments X returns output string if <stream> is nil, nil otherwise X X The format string can contain characters that should be copied X directly to the output and formatting directives. The X formatting directives are: X X ~A print next argument using princ X ~S print next argument using prin1 X ~% start a new line X ~~ print a tilde character X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X XLISP FILE I/O FUNCTIONS Page 43 X X X FILE I/O FUNCTIONS X X (open <fname> &key :direction) OPEN A FILE STREAM X <fname> the file name string or symbol X :direction :input or :output (default is :input) X returns a stream X X (close <stream>) CLOSE A FILE STREAM X <stream> the stream X returns nil X X (read-char [<stream>]) READ A CHARACTER FROM A STREAM X <stream> the input stream (default is standard input) X returns the character X X (peek-char [<flag> [<stream>]]) PEEK AT THE NEXT CHARACTER X <flag> flag for skipping white space (default is nil) X <stream> the input stream (default is standard input) X returns the character (integer) X X (write-char <ch> [<stream>]) WRITE A CHARACTER TO A STREAM X <ch> the character to write X <stream> the output stream (default is standard output) X returns the character X X (read-line [<stream>]) READ A LINE FROM A STREAM X <stream> the input stream (default is standard input) X returns the string X X (read-byte [<stream>]) READ A BYTE FROM A STREAM X <stream> the input stream (default is standard input) X returns the byte (integer) X X (write-byte <byte> [<stream>]) WRITE A BYTE TO A STREAM X <byte> the byte to write (integer) X <stream> the output stream (default is standard output) X returns the byte (integer) X X X X X X X X X X X X X X X X X X X X X X X X X X X XLISP STRING STREAM FUNCTIONS Page 44 X X X STRING STREAM FUNCTIONS X X These functions operate on unnamed streams. An unnamed output X stream collects characters sent to it when it is used as the X destination of any output function. The functions 'get-output- X stream-string' and string or a list of characters. X X An unnamed input stream is setup with the 'make-string-input- X stream' function and returns each character of the string when X it is used as the source of any input function. X X (make-string-input-stream <str> [<start> [<end>]]) X <str> the string X <start> the starting offset X <end> the ending offset + 1 X returns an unnamed stream that reads from the string X X (make-string-output-stream) X returns an unnamed output stream X X (get-output-stream-string <stream>) X <stream> the output stream X returns the output so far as a string X Note: the output stream is emptied by this function X X (get-output-stream-list <stream>) X <stream> the output stream X returns the output so far as a list X Note: the output stream is emptied by this function X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X XLISP SYSTEM FUNCTIONS Page 45 X X X SYSTEM FUNCTIONS X X (load <fname> &key :verbose :print) LOAD A SOURCE FILE X <fname> the filename string or symbol X :verbose the verbose flag (default is t) X :print the print flag (default is nil) X returns the filename X X (save <fname>) SAVE WORKSPACE TO A FILE X <fname> the filename string or symbol X returns t if workspace was written, nil otherwise X X (restore <fname>) RESTORE WORKSPACE FROM A FILE X <fname> the filename string or symbol X returns nil on failure, otherwise never returns X X (dribble [<fname>]) CREATE A FILE WITH A TRANSCRIPT OF A SESSION X <fname> file name string or symbol X (if missing, close current transcript) X returns t if the transcript is opened, nil if it is closed X X (gc) FORCE GARBAGE COLLECTION X returns nil X X (expand <num>) EXPAND MEMORY BY ADDING SEGMENTS X <num> the number of segments to add X returns the number of segments added X X (alloc <num>) CHANGE NUMBER OF NODES TO ALLOCATE IN EACH SEGMENT X <num> the number of nodes to allocate X returns the old number of nodes to allocate X X (room) SHOW MEMORY ALLOCATION STATISTICS X returns nil X X (type-of <expr>) RETURNS THE TYPE OF THE EXPRESSION X <expr> the expression to return the type of X returns nil if the value is nil otherwise one of the symbols: X SYMBOL for symbols X OBJECT for objects X CONS for conses X SUBR for built-in functions X FSUBR for special forms X CLOSURE for defined functions X STRING for strings X FIXNUM for integers X FLONUM for floating point numbers X CHARACTER for characters X FILE-STREAM for file pointers X UNNAMED-STREAM for unnamed streams X ARRAY for arrays X X X X X X X X X X X X X XLISP SYSTEM FUNCTIONS Page 46 X X X (peek <addrs>) PEEK AT A LOCATION IN MEMORY X <addrs> the address to peek at (integer) X returns the value at the specified address (integer) X X (poke <addrs> <value>) POKE A VALUE INTO MEMORY X <addrs> the address to poke (integer) X <value> the value to poke into the address (integer) X returns the value X X (address-of <expr>) GET THE ADDRESS OF AN XLISP NODE X <expr> the node X returns the address of the node (integer) X X (exit) EXIT XLISP X returns never returns X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X XLISP EXAMPLES Page 47 X X X FILE I/O FUNCTIONS X X Input from a File X X To open a file for input, use the OPEN function with the keyword X argument :DIRECTION set to :INPUT. To open a file for output, X use the OPEN function with the keyword argument :DIRECTION set X to :OUTPUT. The OPEN function takes a single required argument X which is the name of the file to be opened. This name can be in X the form of a string or a symbol. The OPEN function returns an X object of type FILE-STREAM if it succeeds in opening the X specified file. It returns the value NIL if it fails. In order X to manipulate the file, it is necessary to save the value X returned by the OPEN function. This is usually done by X assigning it to a variable with the SETQ special form or by X binding it using LET or LET*. Here is an example: X X (setq fp (open "init.lsp" :direction :input)) X X Evaluating this expression will result in the file "init.lsp" X being opened. The file object that will be returned by the OPEN X function will be assigned to the variable "fp". X X It is now possible to use the file for input. To read an X expression from the file, just supply the value of the "fp" X variable as the optional "stream" argument to READ. X X (read fp) X X Evaluating this expression will result in reading the first X expression from the file "init.lsp". The expression will be X returned as the result of the READ function. More expressions X can be read from the file using further calls to the READ X function. When there are no more expressions to read, the READ X function will return NIL (or whatever value was supplied as the X second argument to READ). X X Once you are done reading from the file, you should close it. X To close the file, use the following expression: X X (close fp) X X Evaluating this expression will cause the file to be closed. X X X X X X X X X X X X X X X X X X X X X XLISP EXAMPLES Page 48 X X X Output to a File X X Writing to a file is pretty much the same as reading from one. X You need to open the file first. This time you should use the X OPEN function to indicate that you will do output to the file. X For example: X X (setq fp (open "test.dat" :direction :output)) X X Evaluating this expression will open the file "test.dat" for X output. If the file already exists, its current contents will X be discarded. If it doesn't already exist, it will be created. X In any case, a FILE-STREAM object will be returned by the OPEN X function. This file object will be assigned to the "fp" X variable. X X It is now possible to write to this file by supplying the value X of the "fp" variable as the optional "stream" parameter in the X PRINT function. X X (print "Hello there" fp) X X Evaluating this expression will result in the string "Hello X there" being written to the file "test.dat". More data can be X written to the file using the same technique. X X Once you are done writing to the file, you should close it. X Closing an output file is just like closing an input file. X X (close fp) X X Evaluating this expression will close the output file and make X it permanent. X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X XLISP EXAMPLES Page 49 X X X A Slightly More Complicated File Example X X This example shows how to open a file, read each Lisp expression X from the file and print it. It demonstrates the use of files X and the use of the optional "stream" argument to the READ X function. X X (do* ((fp (open "test.dat" :direction :input)) X (ex (read fp) (read fp))) X ((null ex) nil) X (print ex)) X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X SHAR_EOF if test 80928 -ne "`wc -c 'xlisp.doc'`" then echo shar: error transmitting "'xlisp.doc'" '(should have been 80928 characters)' fi # End of shell archive exit 0 -- Gary Murphy uunet!mitel!sce!cognos!garym (garym%cognos.uucp@uunet.uu.net) (613) 738-1338 x5537 Cognos Inc. P.O. Box 9707 Ottawa K1G 3N3 "There are many things which do not concern the process" - Joan of Arc