CP/M

home *** CD-ROM | disk | FTP | other *** search

/ CP/M / CPM_CDROM.iso / lambda / soundpot / f / ilisp-2.lbr / LISP.DZC / LISP.DOC

Wrap

Text File | 1993-10-26 | 89.8 KB | 2,059 lines

NOTE: This is the table of contents of the complete iLISP Reference Manual. Only a portion of this manual is included in this file. The contents of this file are (C) Copyrighted by Computing Insights, 1983. iLISP Reference Manual Table of Contents Section Page ============================================================ 0 Introduction About This Book 4 Using iLISP 5 1 Data Types Numbers 7 Literal Atoms 9 Lists 10 Functions 11 2 Primitive Functions List Functions 14 Selector Functions 14 Constructor Functions 15 Destructive Functions 17 Miscellaneous 19 Property List Functions 20 Literal Atom Functions 22 Arithmetic Functions 24 Non Numeric Predicates 26 EQ and EQUALity 26 Procedure Functions 28 EVAL 28 MAP Functions 29 Input/Output 32 READ 32 Character Syntax 33 Read Macros 35 Console Input 39 PRINT 41 OUTPUT Formatting 42 Files 43 Creating Files 43 Random Access 44 ERASE, RENAME 44 Miscellaneous Functions 45 3 Syntactic Forms QUOTE 48 LAMBDA 49 PROGN 50 IF 51 COND 51 SELECTQ 53 AND 53 OR 54 SETQ 54 LET 54 LETSYS 55 DEFINE 56 CATCH 56 ERRORSET 57 MACRO 57 How MACROs Work 59 4 iLISP Semantics LAMBDA 61 Variable Scoping 63 Tail Recursion 65 5 System Operation EXEC 69 Start Up Procedures 72 Command Line Parameters 72 Keyboard Interrupts 73 6 The iLISP Editor Basic Editing Concepts 76 Move Commands 77 Modify Commands 80 Other Editing Features 84 7 Error Processing Error Handling Philosophy 87 Nonrecoverable Errors 88 Recoverable Errors 88 The Debugging Loop 89 Modifying Error Handling Procedures 91 8 Tracing 93 9 The iLISP Library Utility Creating Library Files 98 Saving Functions 98 Retrieving Functions 99 Documenting Functions 99 Listing Functions 100 Other Functions 101 10 iLISP Memory Allocation Primary Memory Usage 102 Saving an iLISP memory image 104 Garbage Collection 105 Appendicies A Alphabetical Guide to iLISP Functions 107 B EVAL Description 141 C LISP Error Messages 143 D LISP Editor Commands 145 E How to configure CS and CURSOR 147 F System Reconfiguration Options 151 G Machine Language Interfacing 155 H iLISP internal addresses 159 I iLISP and Standard LISP Differences 163 A Guide to Learning iLISP Table of Contents Section Page ========================================================== 1 - Introducing LISP Getting Started 171 Numbers 171 Notations 172 Functions and Applications 173 Variables 174 Assignment and SETQ 175 Nested Evaluation and Composition 176 Defining New Functions 178 2 - New Data Types: Literal Atoms and Lists Literal Atoms 183 Lists 185 NIL, The Empty List 186 CAR & CDR, CONS, LIST, APPEND 187 Defining New List Functions 189 3 - The LISP Secret: Programs are Data 191 4 - More LISP Programming IF, PREDICATES, T 197 Syntactic Forms 199 Equality 200 Recursion 202 LISP Programs 209 5 - Input/Output in LISP: READ 211 PRINT 212 6 - iLISP and Disk Files 215 7 - Functions are Data LAMBDA 218 Abstracting Control Structures 219 Some New Forms 225 8 - What to Do Next 227 Supplements The Pretty Print Algorithm 229 Some Basic Statistics 235 Using and Improving ELIZA 239 Bibliography 248 iLISP Reference Manual Chapter 0 (ABRIDGED) INTRODUCTION iLISP is an implementation of LISP for the Z-80 CPU running under the CP/M 2.x operating system. It is based on the LISP dialect called SCHEME, developed at M.I.T. by Guy Lewis Steele and Gerald Sussman. Its most unusual feature is that it supports lexical scoping of variables (as opposed to the traditional dynamic scoping) and, consequently, offers a stack free implementation of tail recursion which allows LISP programmers to write recursive functions without unnecessary overhead. About This Book =============== The iLISP Reference Manual is a reference document and a guide, offering both a description of the iLISP implementation and suggestions on how to write programs in iLISP. Many of the chapters are broken into three types of sections: 1) Introductory notes for people who may not have seen the type of thing being described. E.g. the opening section of the list EDITOR chapter. 2) Straightforward reference material, organized to facilitate rapid lookup of particular information. E.g. Appendix A which presents all of the iLISP functions in alphabetical order. 3) Follow up suggestions and advice on how to use the feature described in the chapter. Because of the importance of the primitive function set provided by any LISP implementation, the iLISP set is documented twice: First in Chapter Two, where all of the available functions are presented, grouped by function or topic. Then in Appendix A, where they are all presented in alphabetical order. Very technical information is relegated to the appendicies at the end of manual. Getting Into and Getting Out of iLISP ===================================== To use iLISP, first make a copy of the distribution disk using the PIP utility. Once this is done, and your copy is loaded into the A: disk drive of your system, simply type at CP/M: A>LISP There is no need to provide any command line parameters. It takes a moment to load the iLISP interpreter. When it is loaded, it will print out: iLISP 2.0 - (C) Copyright by Computing Insights, 1982 Serial #nnnn and pause again. Under normal conditions, iLISP spends about five seconds allocating internal memory. When it finishes, it will print a greeting and then begin a new line with the standard iLISP prompt character: "-". At this point it is ready for your instructions. To exit iLISP, you only have to evaluate the function EXIT. This is usually done at the top level: -(EXIT) ;return to CP/M A> iLISP resists most other means of exiting programs (e.g. typing control-C) in order to reduce the chances of accidentally exiting LISP before you have saved your programs and closed any open files. Once you have examined iLISP you may want to copy the LISP.COM file onto the disk you use as your "standard" A: disk, the one that holds all your COM files (Sometimes called a MASCOM disk). If you do this, be sure to also copy the file named INIT.LSP as this is needed to maintain iLISP's standard behavior. Chapter 5 documents this file and how to change it. Additional Note =============== iLISP monitors the console keyboard frequently. The following keys are recognized at all times: Control-C forces an evaluation of (RESET). All processing is aborted. INPUT and OUTPUT are set to CON:. Control returns to the (EVAL EXEC) loop. No error processing is performed. Control-B causes an ERROR #10. Usually results in a BREAK from which the computation can be aborted or continued. Control-E causes an ERROR, but bypasses all error processing. That is, it behaves as though ERRPRIN were NIL. Control goes to the next level ERRORSET, or to the top level loop if there are no ERRORSETs. The following keys are recognized during printing to the console: Control-O abort the current call to print and continue. Used to bypass the output of long or circular lists. No error is caused; control flow is unchanged. Control-S suspend printing. Resume by typing control-Q. For specialized applicatons, keyboard monitoring can be turned off by uing the BYTE function to store a 255 in location PINT (see appendix H for this address). iLISP Reference Manual Chapter 6 (ABRIDGED) The ilISP List Editor The iLISP list editor provides a convenient way to modify function definitions and variable values. It is an editor which is oriented towards list structures rather than text. While it may take some getting used to, it will become your most valuable programming tool. EDITING LISP FUNCTIONS ====================== One of the best aspects of programming in LISP is its interactive nature. You sit at your terminal and type in a function, and test it, and change it, and test it, .... ... List oriented editors are not oriented toward modification of characters or text, but are oriented toward modifying list data structures. Their commands operate on the list structures themselves and consequently go a long way toward eliminating the hassles of LISP's highly parenthesized syntax. The iLISP editor is a list oriented editor. BASIC CONCEPTS ============== When a text editor is said to be line oriented, it usually means that it is has an internal pointer which is always pointing to a particular line in the text and its commands are oriented toward modifying that line, or, derive meaning through reference to the line (e.g. move pointer relative to the current line). When we say a list editor is list oriented, we mean that it has a built in pointer which is always pointing to a list, called the current list and all of its commands are oriented toward modifying or manipulating that list, and, its commands derive meaning through reference to that list. The usual way of using the editor is with the LISP macro EDIT. EDIT take a single literal atom as an argument and it makes, as the current expression to be edited, a DEFINE or MACRO expression which gives the definition or value of the atom. E.g. typing (EDIT PP) will have you editing the expression: (DEFINE PP (X) (PROGN (PPRIN2 X) (TERPRI))) because this is the expression which when evaluated will properly define PP. When you exit the editor, this expression, modified by you, will be passed to EVAL which will cause PP to be redefined. When the editor is called, it clears the screen* and presents the list being edited by printing each element of the list on a separate numbered line: ---------------------------------------------------------------- * Optimal use of the editor requires that the function CS, for clearing the screen, be correctly adapted for use on your terminal. The default operation of CS will work for many terminals (it simply prints the character control-L). To test whether CS works properly with your terminal, just type (CS) followed by a carriage return. The terminal screen should clear and "()" should be printed in the upper left hand corner of the screen. If this doesn't happen, refer to Appendix E and follow the instructions there for customizing CS for your terminal. ---------------------------------------------------------------- . . ; All of the following examples of editor operations ; will be made on the function FAC, defined by: -(DEFINE FAC (N) (IF (ZEROP N) 1 (* N (FAC (SUB1 N))))) FAC -(EDIT FAC) 1 DEFINE 2 FAC 3 (N) 4 (IF (ZEROP N) 1 (* N &)) ' ' The editor uses a PRINTLEVEL of 2 (See Chapter 2) to start with, so each element rarely, if ever, extends over one line. The editor accepts a variety of commands for moving about inside the current list and for modifying the list in several ways. Commands are either LISP atoms or lists and should be typed in remembering the general rules for typing LISP data objects: in particular: you can put as many as you want on one line, you can spread one list out across several lines, you should separate adjacent atoms with a space or some other delimiter, and, of course, you must type RETURN before the editor will actually see and act on your commands. The easiest way to get a feel for how the editor works is to actually type in the examples below and try out the various editing commands as they are introduced. MOVING ABOUT INSIDE THE LIST ============================ The commands for traversing the list structure allow you to move into or out from the current list. Typing a number makes the element of the current list which is identified by that number the new current list. . . 1 DEFINE 2 FAC 3 (N) 4 (IF (ZEROP N) 1 (* N &)) *4 ;move to element 4 1 IF 2 (ZEROP N) 3 1 4 (* N (FAC &)) *2 ;move to element 2 1 ZEROP 2 N ' ' Typing a zero means "go back up one level". That is, go back to the list surrounding the current list. . . 1 ZEROP 2 N *0 1 IF 2 (ZEROP N) 3 1 4 (* N (FAC &)) * 4 3 ;more than one command ;per line is ok 1 FAC 2 (SUB1 N) ' ' Typing the single character "^", (the uparrow), means "go back to the outermost list". It is like typing a "B" for Beginning command in some text editors. . . 1 FAC 2 (SUB1 N) *^ 1 DEFINE 2 FAC 3 (N) 4 (IF (ZEROP N) 1 (* N &)) ' ' SEARCH COMMANDS =============== LIST MODIFICATION ================= Once you have found a list that you want to change, the list modification commands allow you to add to, delete and replace elements of the current list. All editor commands which actually modify the current list are in the form of lists; that is, the commands themselves are enclosed in parentheses. To insert a new element into the current list the command is: (-n X) where n is an integer. This means insert X into the current list BEFORE the nth element. To insert more than one element at a time, you can just follow X with as many new elements as you wish: (-n X Y Z ...) which means: insert X, Y, Z, ... all into the current list BEFORE the nth element. To replace an element of the current list with one or more elements use: (n X) which means: replace the nth element of the current list with the expression (As with the insert commands you can replace a single element with many simply by including them in the replace command, e.g. (n X Y Z ...).) . . 1 DEFINE 2 FAC 3 (N) 4 (IF (ZEROP N) 1 (* N &)) *(-4 (M)) ;insert the list (M) ;before the 4th element 1 DEFINE 2 FAC 3 (N) 4 (M) 5 (IF (ZEROP N) 1 (* N &)) *(4 (A B) (C D)) ;replace the 4th element ;with these two lists 1 DEFINE 2 FAC 3 (N) 4 (A B) 5 (C D) 6 (IF (ZEROP N) 1 (* N &)) *(4) ;To Delete an element: ;replace it with nothing. 1 DEFINE 2 FAC 3 (N) 4 (C D) 5 (IF (ZEROP N) 1 (* N &)) *(4) 1 DEFINE 2 FAC 3 (N) 4 (IF (ZEROP N) 1 (* N &)) ' ' To insert a new element at the beginning of the current list you can use: (-1 A) ;ADD BEFORE the first element or (0 A) ;REPLACE the (nonexistent) zeroth element To add an element to the end of the current list you can use: (-5 A) ;ADD BEFORE the (nonexistent) element after the last ; or (N A) ;The command N means "add to the end" Remember: Any of these commands: (n X Y Z), (-n X Y) and (N X Y) may have zero, one or more elements in the list. THE EDITOR's READ MACRO: # ========================== Within the editor, the character "#" is a read macro which can be used in the following way: #n, where n is a positive integer, means "a copy of the nth element of the current list". You can use this notation to move pieces of the list structure without retyping them. ... MANIPULATING PARENTHESES ======================== The grouping of the elements of the current list into sublists may be modified by these two editor commands: (PI n m) - Parentheses In Insert parentheses around the elements starting with the nth element and ending with the mth element. (PO n) - Parentheses Out Remove the parentheses surrounding the nth element of the current list. SEARCH and REPLACE ================== The editor also has a "search and replace" command: (R X Y) - replace all occurences of X (in the current list) with Y MISCELLANEOUS EDITING COMMANDS OK When not inside an F* command, OK means EXIT the editor. When you are in the F* command, it means go on to the next occurence. ABORT! exit the editor, but forget the changes made during this editing session. This is for when you've made a terrible mistake. Since the editor is working on a copy of the actual expression, this command is always available to you. P n Change the current PRINTLEVEL used by the editor to n. PP Pretty Print the current list. The pretty printed list will remain on the screen until you type any key. E.g. E exp Evaluate the expression "exp", print the results, pause until the user types a key. This allows you to invoke the full power of EVAL during an editing session. EDITING HINTS ============= While we have deliberately kept the editor small, because it usually resides in memory. It can still serve as a powerful tool, providing facilities beyond what its simple command set might seem to imply. 1) Use The E Command The E command is the key to using all of LISP's functions while you are editing. For example, If you need to consult or modify the definition of a function (e.g. PPRIN2) while editing another one, you can type: * E (EDIT PPRIN2) which will call the editor on PPRIN2 from inside the editor. When you finish editing PPRIN2, you will be returned to the editor at exactly the point you invoked the second call from. (Remember that the E command waits for you to type a key before returning you to the editor.) 2) Buffering Portions of the Current List Structure There is no primitive command for extracting and buffering a piece of list structure. However, the simple commands for moving pieces of the current list about within the current list are not always enough. Sometimes you need to move a piece of the current list to some other part of the function definition. You need the equivalent of a list structure buffer. The E command gives you the ability to use any LISP variable: * E (SETQ BUF '#3) ;Extract the third element ;and store it in a variable * ;after moving * (-2 $BUF) ;insert the value of BUF before the ;second element of this structure You can even carry these buffers (as many as you want) from one call of the editor into another. 3) The Editor as a Filtering Pipeline There is a second EDIT function available: EDITL. EDITL takes a list as its argument. It invokes the editor on a copy of the list and returns the new value of the list as its value. It can not be used to edit function definitions or variable values because it makes a copy and will not actually modify values. However it can be used inside functions or inside expressions to permit you to step in and modify values on the fly. For example, I want to copy some of the function definitions on one file to another. But, I don't remember all the names of all of the functions I want to copy. I type: (COPYFILE 'OLD 'NEW (EDITL (DIRFILE 'OLD))) Which, when evaluated, finds the directory of the old file (DIRFILE 'OLD) and passes it to the editor, allowing me to edit the list of functions, leaving only the ones I want to copy. EDITL then passes the modified list on to the COPYFILE command. Here's another: Some of my library files need packing, but I don't remember all of their names. (MAPNIL PACKFILE (EDITL (FILDIR '*.LSP))) allows me to edit a list of all of the names of all of the files with the extension .LSP. I can edit the list, deleting the files which don't need to be packed, and when I'm done (when I type OK), PACKFILE will be applied to the ones that remain. Once you start using this trick, it becomes indispensable. Appendix D contains a one page summary of all of the editor commands. APPENDIX A - A Function Index ---------- ABRIDGED FOR ELECTRONIC DISTRIBUTION NOTE: This abridged version of Appendix A contains all of the entries that the complete appendix contains, however, most examples and descriptions have been deleted in an attempt to make this file reasonably small. ---------- This appendix contains descriptions of all of the functions provided with iLISP. The entries are in alphabetical order. Each entry contains a one line description of the function, with an indication of whether it is a machine language function (a SUBR) or a LISP expression (an EXPR). For EXPRs the one line description also indicates which library file the source code for the function can be found on, and whether or not the file is actually resident in the standard iLISP file (if the file name is followed by an asterisk, the function must be loaded before it can be used) e.g. (ADDEL NEW LIST N) Add an Element to a list EXPR/UTILITY* ADDEL is an EXPR type function, which is stored on the file UTILITY and which is not loaded into the standard LISP.COM file. Each entry also contains: - a description of the value of the function, - any side effects it causes (if any), - a description of what the function actually does, or how it works, and - sometimes, examples of the use of the function or hints about when it is appropriate to use it. This section does not include entries for all of the functions internal to the iLISP utilities or the extra LISP programs such as ELIZA. The List Starts Here: (ABS N) Absolute Value of N SUBR Argument Types: N - number Value: Absolute value of N (ADDEL NEW LIST N) Add an element to a list EXPR/UTILITY* Argument Types: NEW - any data object LIST - a list N - integer, indicating position within the list Value: a list Description: Inserts the new element into the list after the Nth element of the list. (ADD1 N) Increment a Number SUBR Argument Types: N - number Value: A number equal to N+1 (ALPHORDER X Y) Alphabetize Two Literal Atoms SUBR Argument Types: X, Y - no restrictions Value: T - if X and Y are literal atoms and X precedes Y alphabetically, () - otherwise (APPEND L1 L2) Concatenate Two Lists SUBR Argument Types: L1, L2 - lists Value: Copy of L1 with L2 attached to the end. Description: Makes a top level copy of L1 and then uses NCONC. (ARCTAN N) Arctangent of N SUBR Argument Types: N - a number Value: floating point arctangent of N (in radians). (ARGCNT X) Argument Count of a Function SUBR Argument Types: X - no restrictions Description: If X is a function, ARGCNT returns the number of arguments it expects. If the number is indefinite (e.g. as for LIST), ARGCNT returns -1. If X is not a function, ARGCNT returns NIL. (ASCII X) Convert Literal to ASCII SUBR Argument Types: X - literal atom Value: Integer which is the ASCII code for the first character of X's print name. (ATOM X) Test for Atom SUBR Argument Types: X - no restrictions Value: X - if X is an atom, literal or numeric () - otherwise (BYTE addr val) General Byte Manipulating Function SUBR Argument Types: addr - number val - optional, number Value: Current contents of (addr) Side Effects: May change the value of the byte at (addr). Description: This is a combined PEEK and POKE. If only one argument is provided, it returns the value of the byte at that address. If two are provided, it returns the current value, but changes it to the second argument. (It behaves like a system function.) Its only real use is for manipulating internal variables for which functions have not been provided (see appendix H). Use caution with this function as it is easy to accidentally damage the iLISP program with unpredictable results. (CALL X ...) Call a Machine Language Subroutine SUBR Argument Types: X - a literal atom others - depends, see below Description: CALL's first argument is a literal atom whose print name has been constructed out of the bytes of a machine language subroutine according to the rules and methods of Appendix G. The remaining arguments, if any, are for that subroutine. CALL transfers control to the subroutine, which is responsible for returning its own value. (CAR L) Select First Element of L SUBR Argument Types: L - a list Value: First element of L (CARS L N) Copy First N Elements of L SUBR Argument Types: L - a list N - an integer >= 0 Value: A new list of the first N elements of L. Description: This is a constructor function. It builds a new list which is a copy of the first N nodes of L. (CDR L) Select All But First Element SUBR Argument Types: L - a list Value: The sublist of L containing all except first element of L. (CDRS L N) Repeat CDR N times SUBR Argument Types: L - a list N - an integer >= 0 Value: The sublist of L containing all but the first N elements of L. (CHAR N) Convert ASCII to Literal SUBR Argument Types: N - integer Value: A one character literal atom whose print name is the ASCII character denoted by N. Description: Packs the integer into a literal atom format. For the inverse function, see ASCII. (CLEARBUF) Skip to Next Line of INPUT SUBR Value: () Side Effects: Advances input file pointer Description: Skips current input device/file ahead until the next end of line sequence. (CLOSE F) Close a File SUBR Argument Types: F - a literal atom Value: The full file name of file F Side Effects: CP/M closes the named file. Description: Flushes the internal buffer if necessary and closes the file for i/o operations. If CLOSE closes either the primary input or output file, it resets it to CON:. (CLOSEALL) Close all Open Files EXPR/AUX Value: A list of all closed files. Side Effects: CP/M closes all open files Description: Just maps CLOSE over (OPENP). (CONCATENATE X Y) Concatenate two literal atoms EXPR/UTILITY* Argument Types: Both literal atoms Value: A literal atom (CONS X L) Allocate a New List Element SUBR Argument Types: X - no restrictions L - a list Value: A list node whose CAR is X and CDR is L NOTE: That since iLISP does not support dotted pairs, the second argument, L, MUST BE A LIST. (COPY L) Make a Copy of a List SUBR Argument Types: L - no restrictions Value: A copy of L Description: Deep copy of L (COSINE N) Cosine of N SUBR Argument Types: N - a number, denotes an angle in radians Value: floating point number = cosine of N (CS) Clear the Screen SUBR Value: () Side Effects: Clears console screen and homes the cursor Description: This function must be customized by the user. Consult Appendix E for details. (CURSOR COL ROW) Position Cursor SUBR Argument Types: COL, ROW - both numbers Value: () Side Effects: Repositions the console's cursor Description: Moves the console's CRT cursor to (COL,ROW) on the screen. This function must be customized by the user. See Appendix E. (DEFEXP X) Build a Defining Expression EXPR/AUX Argument Types: X - a literal atom Value: A DEFINE or MACRO expression Description: Returns a DEFINE or a MACRO expression which, when evaluated, correctly redefines X as either a function or a macro or just a variable with a value. (DELETEL L N) Delete an element from a list EXPR/UTILITY* Argument Types: L - a list N - an integer Value: a modified L Description: This function is one of three (ADDEL, DELETEL and REPLACEL) which allow you to treat lists as arrays. DELETEL actually modifies the list L (using RPLACAD) and removes the Nth element from it. If L only has one element in it, the value of DELETEL will be NIL, but, it is impossible for DELETEL to change L into () so the actual list structure will be unchanged. (DESCRIBE X) Describe a Procedure SUBR Argument Types: X - no restrictions Description: If X is a user defined function with no local environment, DESCRIBE returns a LAMBDA expression which, when evaluated in the global environment would yield an equivalent function, otherwise it just returns X. (DIR X) Print a CP/M directory EXPR/UTILITY* Argument Types: X, literal atom (optional) Value: () Description: Prints a directory of the current or specified disk. Acts just like the CP/M CCP DIR command. Optionally accepts a file group identifier, e.g. *.*, *.LSP, etc. (Needs PRL.) (DIRF F) Print a library file directory EXPR/UTILITY* Argument Types: file name Value: () Description: Prints the names of the entries on the specified iLISP library file, in a columnar format. (Needs PRL.) (DIRIO n) CP/M Direct Console i/o SUBR Argument Types: (n) - an integer between 0 and 255, or NIL (optional) Value: 1) If no argument was provided, DIRIO returns an an integer representing the ASCII value of the next character typed on the console. 2) If the argument was an integer, DIRIO transmits that integer directly to the console, using the CP/M DIRIO function, and returns the number as its value. 3) If the argument was NIL, DIRIO returns a T if there is a character available from the console, else (). Side Effects: Receives or transmits a character from or to the console Description: direct console i/o using CP/M BDOS function 6. Special Note: You should be familiar with this CP/M function before using DIRIO. Input performed using (DIRIO) is done without recognition of any special characters and without echoing to the console. Furthermore, if you use option (2) to transmit bytes to the console, you will find that CP/M ignores the values 255 and 254. If the keyboard interrupt functions are enabled, (and they usually are) a call to (DIRIO ()) will always return () because iLISP is regularly inspecting the keyboard for interrupt characters. Consult Chapter 2 for information on disabling the keyboard interrupts. (DISK X) Get/Set New Default Disk SUBR Argument Types: X - a literal atom, optional Value: The current default disk name Side Effects: Changes the current default disk Description: A system function which sets the current default disk to x: where x is the first character of X. (DISK) returns the current disk. (DO I J FN AFN R) Apply FN over a List of Numbers EXPR/UTILITY* Argument Types: I - starting number J - final number FN - function of 1 numeric argument AFN - function of two arguments R - no restrictions Description: applies FN to all integers X, I <= X <= J, in order, and accumulates the results to R using AFN. Value: Final value of R (DREVERSE L) Reverse the Elements of L SUBR Argument Types: L - a LIST Value: L, with the elements in reverse order. Side Effects: Actually modifies the argument L Description: Destructive; actually performs RPLACDs on L's own list elements to produce a new list with the elements in the reverse order from L's. NOTICE that the pointer which was the argument to L originally pointed to the first node in L, but now points to the last node. (DSKRES) Reset the Disk System SUBR Value: () Side Effects: Changes current default disk, resets CP/M disk i/o system. Description: Uses the CP/M DSKRES call to reset the disk system and set the current disk to A:. Used when you need to change a disk without rebooting the system. Can't be called when files are open. (DSUBST X Y Z) Substitute X for Y in Z EXPR/AUX Argument Types: X, Y, Z - no restrictions Value: Z, with X replacing every occurence of Y in it Side Effects: Actually modifies Z. Description: DSUBST of course uses EQUAL to find occurences of Y in Z and uses RPLACA and RPLACD to change them. (EDIT X) Invoke the list editor on a value MACRO/EDIT Argument Types: X - a literal atom Value: X Side Effects: Invokes the list editing program Description: Invokes the editor on a copy of (DEFEXP X), an expression which will define X. Since this is a macro, the result is given to EVAL so the atom will be redefined once editing is complete. (EDITL L) Invoke the list editor on a list EXPR/EDIT Argument Types: L - a list Value: L, modified by the editor Description: Invokes the list editor on a copy of L. (ERASE file) Delete a File From The Directory. SUBR Argument Types: File - a literal atom Value: File Side Effects: ERASES A FILE FROM THE DISK Description: Just calls CP/M. However, iLISP won't let you erase an OPEN file or a Read Only ($R/O) file. (ERR N) Cause Recoverable Error N SUBR Argument Types: N - a number Side Effects: Invokes error processing Description: Causes an ERROR number N. Useful for extending the types of errors recognized by iLISP. (EQ X1 X2) Test for Pointer Equality SUBR Argument Types: X1, X2 - no restrictions Value: T - if X1 is the same pointer as X2 () - otherwise (EQUAL X Y) Test for Equality SUBR Argument Types: X, Y - no restrictions Value: T - if X and Y have equivalent structure or value () - otherwise (EVAL X) Evaluate X SUBR Argument Types: no restrictions Value: Value of X Side Effects: None in particular, but X can be ANY LISP expression, including side affecting ones. Description: There is an OPTIONAL additional argument: (EVAL X) X evaluated in the global environment. (EVAL X T) X evaluated in the local environment. EVAL is the real GOTO of LISP. Avoid using it. (EXIT) Exit LISP SUBR Side Effects: EXITS iLISP. Prints a list of all open files. Description: Calls CP/M function 0. Performs a system reset and warm boot. EXIT closes all open files before EXITing. (FILDIR filegroup) Get the Disk Directory SUBR Argument Types: Filename a literal atom Value: A list of file names. Description: This provides a DIR type function from within iLISP as well as giving you a way of telling whether an OPEN operation will succeed. If (FILDIR F) returns (F) then the file already exists and it can't be opened for writing. If (FILDIR F) returns (), then the file doesn't exist and can't be opened for reading. Both the "?" and "*" characters perform just a they do in CP/M's DIR command. (FILLBUF) Read Next Line of INPUT SUBR Value: () Side Effects: May cause a read request at the console; skips input file pointer over remainder of current line. Description: If current input file is not CON:, FILLBUF is the same as CLEARBUF. For CON:, FILLBUF performs a CP/M RDLINE function, i.e. it reads a line from the console, and stores it in an internal buffer, but the line isn't processed until some other input function is called (e.g. READ). This function provides a convenient way to recognize a user's typing of an empty line: if you call (READ), READ will keep after the user until a valid data object is typed. If you call (READP), the user won't be prompted if the current line is empty. But, if you first call (FILLBUF) and then (READP), if READP returns (), you can assume that the user simply typed a carriage return to LISP's prompt. (FIT X) Will X fit? EXPR/PP Argument Types: X - any data object Value: T or () Description: Returns T if X will fit on the remainder of the current line (when printed with PRIN1). Used by PPRIN2. (FIX N) Convert Floating Point to Integer SUBR Argument Types: N - a number Value: Integer Description: Truncates the fractional part of N (if any). (FLOAT N) Convert Integer to Floating Point SUBR Argument Types: N - a number Value: A floating point number equal to N (FREE) number of FREE spaces nodes remaining SUBR Value: A count of the remaining free nodes Description: Returns a count of the number of nodes remaining in the space allocated to FREE memory. This value is the number of list nodes that can be allocated before the next garbage collection occurs. (FULL) number of FULL space bytes remaining SUBR Value: A count of the remaining FULL space bytes Description: Returns a count of the bytes in the space allocated to FULL memory. This is the number of bytes that can be allocated to print names and file buffers before the next garbage collection occurs. (GETPL X) Get the Property List of X SUBR Argument Types: X - a literal atom Value: The property list of X. Description: Just returns the associated list. (GETPROP A P) Get Property SUBR Argument Types: A - literal atom P - no restrictions Value: Value associated with P in (GETPL A) OR (). Description: Performs a LISTGET on the property list of A. Equivalent to: (LISTGET (GETPL A) P) (GFP file) Return Current File Position SUBR Argument Types: file - a literal atom Value: An integer, the value of file's pointer. Description: The file pointer is the position, relative to the beginning of the file, of the byte at which the next input or output operation on file will begin. (ID X) Identity Function SUBR Argument Types: X - no restrictions Value: X Description: This is not QUOTE. ID is a genuine function. Its argument IS evaluated before it is passed to ID. ID just gives it back. Its primary usage is as an argument to one of the MAP functions. (INB) Read one Byte SUBR Value: An integer or (), see below Side Effects: Advances input file pointer Description: Reads one byte from the primary input file and returns it as an integer between 0 and 255. If the end of file is encountered, INB returns (). INB only recognizes a CP/M physical end of file as the end of file indicator; control-Z is returned as 26. For more information regarding the processing of the end of file indicators, consult the i/o section of the manual. (INPUT file) Get/Set Primary Input File SUBR Argument Types: file - a literal atom, optional Value: The old or current primary input file Side Effects: Changes currently selected input file Description: A system function used to set or query the current primary input file. The file must have been previously opened for input or update operations. (INPUT) returns the current primary input file. (IOBYTE n) Get/Set the CP/M IOBYTE SUBR Argument Types: N - an integer, optional Value: The old or current value of IOBYTE Side Effects: May change the IOBYTE Description: A system function which sets the CP/M IOBYTE to the byte n. Returns the old value of the IOBYTE. (IOBYTE) returns the current value. The function of the IOBYTE is described in the CP/M reference manual. (LAST L) Get the Last Node in L SUBR Argument Types: L - a non NIL list Value: The last node in L. Description: The value is NOT the last element, but the last NODE. (LAST L) actually performs: (CDRS L (SUB1 (LENGTH L))). (LENGTH L) Measure The Length of a List SUBR Argument Types: L - a list Value: integer, number of elements in L (LINELENGTH N) Get/Set Line Length SUBR Argument Types: N - integer, optional Value: Old or current value of LINELENGTH Side Effects: Changes current LINELENGTH Description: A system function which sets or queries iLISP's value for the line length of the current output file. A line length of zero signifies an indefinitely long line. iLISP issues automatic TERPRIs at the end of each line, being careful not to split atoms across line boundaries. (LIST X1 X2 X3 ... )Build a List SUBR Argument Types: No Restrictions, indefinite number Value: A list whose elements are X1, X2, ... Description: Just returns its argument list. Its actual definition is equivalent to: (LAMBDA FORM FORM). Useful for building new lists. (LISTGET L P) Retrieve a Property from a Property List SUBR Argument Types: L - a property list P - no restrictions Value: Either the value associated with P in L or NIL Description: Treats L as a property list and searches for a property P on L; returns associated value (V) or NIL if P not found. (LISTP X) Test for List SUBR Argument Types: X - no restrictions Value: X - if X is a list () - otherwise Description: Notice that LISTP returns X itself if it is a list, not the atom T. This means that (LISTP ()) is (), EVEN THOUGH () IS A LIST. To spot () you must use NULL. This was a deliberate decision because there are many occasions when a list is wanted that () will not do (e.g. RPLACA). (LISTPUT L P V) Put Property P on L with Value V SUBR Argument Types: L - a property list P - no restrictions V - no restrictions Value: L Side Effects: Changes the list L. Description: Treats L as a property list and adds the property P with associated value V. (LISTREM L P) Remove all Properties P from L SUBR Argument Types: L - a property list P - no restrictions Value: L Side Effects: Changes the list L Description: Treats L as a property list and destructively removes all occurrences of P (and associated values) from it. (LITATOM X) Test for Literal Atom SUBR Argument Types: X - no restrictions Value: X - if X is a literal atom () - otherwise Description: Notice that LITATOM returns X itself, not T. (MACROP X Y) Get/Set the Macro Bit of Atom X SUBR Argument Types: X - a literal atom Y - optional, T or () Value: T/NIL representing current state of X's macro status Side Effects: With optional argument, MACROP changes X's MACRO status. Description: If only one argument is provided, MACROP returns T or NIL depending on whether X is or is not an iLISP MACRO. If two arguments are provided, MACROP either makes X a MACRO or makes it not a MACRO, depending on whether Y is T or NIL. Its value however reflects Xs status before the change was performed. Special Note: Setting an atom's macro status WILL NOT save it from the garbage collector if it doesn't have a value. (MAP FN L AFN R) Map A Function Over a List SUBR Argument Types: FN - a function of one argument L - a list AFN- a function of two arguments R - no restrictions Description: Applies the function FN to successive elements of L accumulates the results of the application to R using the function AFN. I.e. repeatedly performs R <- (AFN (FN (CAR L)) R) L <- (CDR L) UNTIL L = (). Value: Final value of R. (MAPCONS FN L) MAP, accumulate results with CONS EXPR/MAP Argument Types: FN - a function of one argument L - a list of arguments for FN Description: Applies FN to elements of L, and CONSes the results to (). Value: The result of all the CONSing. (MAPCONSN FN L) MAPCONS, but forget NILs EXPR/MAP Argument Types: FN - a function of one argument L - a list of arguments for FN Description: Applies FN to elements of L, and CONSes the results to (), unless the result is NIL. Value: The result of all the CONSing. (MAPNCONC FN L) MAP, accumulate results with NCONC EXPR/MAP Argument Types: FN - a function of one argument L - a list of arguments for FN Description: Applies FN to elements of L, and NCONCs the results to (). Similar to MAPCONS, except that NCONC won't work with atoms, eliminates () and concatenates lists into one big list. Value: The result of all the NCONCing (MAPNIL FN L) MAP, forget the results EXPR/MAP Argument Types: FN - a function of one argument L - a list of arguments for FN Side Effects: None, BUT, presumably the FN itself has a side effect, else why use MAPNIL? Description: Applies FN to elements of L, forget the results. Value: () (MAPTCONC FN L) MAP, accumulate the results with TCONC EXPR/MAP Argument Types: FN - a function of one argument L - a list of arguments for FN Description: Applies FN to elements of L, and TCONC the results to (). Really just like MAPCONS except that the elements in the result list are in the same order as the elements in L, not the reverse. Value: The CAR of the result of the TCONCing (MARGIN N) Get/Set Left Margin SUBR Argument Types: N - number, optional Value: Old or current value of MARGIN Side Effects: Changes current MARGIN Description: A system function which sets or queries the current left margin, which is simply the number of spaces printed after each TERPRI. (MEMB X L) Simple Test For Membership SUBR Argument Types: X - no restrictions L - a list Value: The tail of L which begins with X, or NIL. Description: Uses EQ to compare X with the elements of L. (MEMBER X L) Test for Membership SUBR Argument Types: X - no restrictions L - a list Value: The tail of L which begins with X, or NIL. Description: Uses EQUAL instead of EQ (MEMORY free full) Get/Set Memory Allocation SUBR Argument Types: free, full - both numbers (optional) Value: A list of four numbers (see description) Side Effects: May allocate memory to free or full space Description: If the two arguments are provided, they are interpreted as the number of unallocated pages to give to each of FREE space and FULL space. Regardless of whether the arguments are provided, the value of MEMORY is a list of four numbers: 1) The number of pages currently allocated to free space 2) The number of pages currently allocated to full space 3) The number of pages currently unallocated 4) The address of the highest allocated element in full space. (Useful if you want to save the binary image of iLISP.) (MINUS N) Negate N SUBR Argument Types: N - a number Value: N * -1 (NCHARS X) Count the Characters in X SUBR Argument Types: X - no restrictions Value: Integer, count of characters in X's PRIN1 print image. Description: This can be a time consuming function. (NCONC L1 L2) Concatenate Two Lists SUBR Argument Types: L1, L2 - both lists Value: L1 with L2 attached to the end. Side Effects: Modifies argument L1 Description: This is a destructive function and should be used with caution since it is possible to create a circular list structure with it. It actually changes L1 by performing (RPLACD (LAST L1) L2). (NodeCount L) Count the Nodes in a List EXPR/UTILITY* Argument Types: L - a list Value: integer Description: Counts the total number of list nodes in a list, including all sublists. NodeCount contains a built in DESCRIBE call so that it can be called directly on user defined functions. (NTH L N) Select The Nth Element of L SUBR Argument Types: L - a list N - an integer, 0 < N <= (LENGTH L) Value: The Nth element of L. (NULL X) Test for NIL Pointer SUBR Argument Types: X - no restrictions Value: T - if X = (), () - otherwise (NUMBERP X) Test for Number SUBR Argument Types: X - no restrictions Value: X - if X is a number () - otherwise Description: Notice that NUMBERP returns X itself, not T. (OPEN file flag) Open/Create a Disk File SUBR Argument Types: file - name of file or logical device flag - {R, W or U} (for read, write, or update i/o). Value: The complete file name of file Side Effects: May create a file. CP/M opens the file. Description: Opens the file for the specified type of operation. Different restrictions apply to different types of opening: READ - the file must already exist. WRITE - the file must NOT exist. This is how you create new files. UPDATE- if the file exists, it will be used. If not, it will be created. Logical devices are always open. (OPENP file) Test for Open File SUBR Argument Types: (file) - a literal atom, optional Value: R - if file is open for input W - if file is open for output U - if file is open for updating T - if file is a logical device () - if file is not open OR: a list of all open files, if file is not provided Description: Useful for determining which files are currently open. (OUTB n) Output One Byte SUBR Argument Types: N - an integer between 0 and 255 Value: n Side Effects: Advances output file pointer Description: Sends the byte N to the primary output file. (OUTPUT file) Get/Set Primary Output File SUBR Argument Types: file - a literal atom, optional Value: The old or current primary output file Side Effects: Changes currently selected output file Description: A system function used to set or query the current primary output file. The file must have been previously opened for output or update operation. (OUTPUT) returns the current primary output file. (PACK L) Pack a List of Characters to an Atom SUBR Argument Types: L - a list of literal atoms or numbers Value: A new literal atom Description: Builds a new literal atom out of the elements of L. Literal atoms contribute their first characters; numbers contribute their ASCII equivalents. (PEEKC) Peek at One Character SUBR Value: Next character on current input file. Description: Same as READC, but does not advance the file's pointer, i.e. successive calls to PEEKC without intervening reads will return the same character. When the primary input file is the terminal PEEKC will return () if there are no more characters in the line buffer. It will not cause a new line to be read. PEEKC recognizes either control-Z or a physical end of file as the end of file indicator. (POSITION N) Get/Set Current Output Column SUBR Argument Types: N - a number, optional Value: Old or current value of position. Side Effects: Changes current POSITION variable Description: A system function used to set or query iLISP's column position indicator. It returns the current column position of the current output file. Setting this to a value DOES NOT actually perform any output. It only adjusts iLISP's current knowledge of where the output device's cursor is. iLISP will correctly keep track of spaces, printing characters, tabs and the carriage return/line feed. But other non printing characters affect different terminals in different ways. Both CURSOR and CS keep POSITION up to date, but other uses of special characters on your terminal may necessitate your using POSITION. (PP X) Pretty-Print X EXPR/PP Argument Types: X - no restrictions Value: () Side Effects: Advances output file pointer Description: Performs (PPRIN2 X) followed by a TERPRI. (PPRIN2 X) Pretty-Prin X EXPR/PP Argument Types: X - no restrictions Value: X Side Effects: Advances output file pointer Description: Similar to PRIN2 in that it prints the expressions X on the primary output file, with the escape character "%" inserted where needed for X to be properly read back in by READ. HOWEVER: Lists are printed in a more readable fashion than with the ordinary PRIN2. Indentation is used to show the structure of lists embedded within lists. (PRINT X) Print X SUBR Argument Types: X - no restrictions Value: X Side Effects: Advances output file pointer Description: PRIN2 followed by TERPRI. (PRINTD N) Print a number in a monetary format EXPR/UTILITY* Argument Types: N - an integer Value: NIL Description: N is printed with a leading dollar sign and a decimal point inserted before the penultimate digit. (PRINTLEVEL N) Get/Set Printlevel SUBR Argument Types: N - number, optional Value: Old or current value of PRINTLEVEL Side Effects: Changes current printlevel Description: A system function used to set or query iLISP's PRINTLEVEL byte which controls the depth to which lists are printed on the console. The printlevel is the number of levels deep the PRINT routine will print lists on the console before substituting an &. All output that is not directed to the console is printed completely, without the PRINTLEVEL restriction. (PRINT@ X Y Z) Print After Positioning EXPR/AUX Argument Types: X, Y - numbers (optional) Z - no restrictions Value: Z Side Effects: Moves current output file pointer. Description: Prints the S-expression Z on the primary output file, using PRIN2, followed by an end-of-line. The numbers X and Y are interpreted as follows: IF output file is the console ; (EQ 'CON: (INPUT)) THEN Move screen cursor to X,Y ; (CURSOR X Y) ELSE Position the file to byte X ; (SFP (INPUT) X) [Y missing.] (PRIN1 X) Print X SUBR Argument Types: X - no restrictions Value: X Side Effects: Advances output file pointer Description: Prints the expression X on the primary output file. Literal atoms with odd characters in their print names are printed without the '%' necessary to read them back in. (PRIN2 X) Print X SUBR Argument Types: X - no restrictions Value: X Side Effects: Advances output file pointer Description: Prints the S-expression X on the primary output file with the escape character "%" inserted where needed for X to be properly read back in by READ. (PRL L) Print the Elements of a List EXPR/UTILITY* Argument Types: L - a list Value: () Description: PRL prints the individual elements of the list L, each followed by a TAB character for separation. It is used by functions such as DIR and DIRF for presenting atoms in a columnar format. (PROCP X) Test for Procedure SUBR Argument Types: X - no restrictions Value: X - if X is a procedure () - otherwise Description: PROCP returns X itself if X is a procedure; not T. (PROG1 X1 X2) Evaluate Two Forms SUBR Argument Types: X1, X2 - No Restrictions Value: X1. Description: Similar to ID; it just returns its first argument. Primary use is as a control structure which is useful when you need to perform some side effect (e.g. a SETQ or a file CLOSE) AFTER calculating the value of an expression. (PROMPT X) Get/Set Prompt Character SUBR Argument Types: X - a number, optional Value: ASCII value of old or current prompt character Side Effects: Modifies current PROMPT character Description: X is the ASCII value of the character used to prompt the user at the console at the beginning of each line, AT THE BEGINNING OF EACH READ. (PROMPT) returns the current prompt. (PROMPT1 X) Get/Set Extended Prompt Character SUBR Argument Types: X - number, optional Value: ASCII value of old or current PROMPT1 character Side Effects: Modifies current PROMPT1 character Description: X is the ASCII value of the character used to prompt the user at the console at the beginning of each line, WHEN IN THE MIDDLE OF A READ. (PROMPT1) just returns the ASCII value of the current prompt character. (PUTPROP A P V) Put property/value on A's property list SUBR Argument Types: A - a literal atom P, V - no restrictions Value: V Side Effects: Changes the property list of A Description: Performs a LISTPUT on the property list of A. (RANDINT N) Generate a Random Integer EXPR/UTILITY* Argument Types: N - an integer Value: a random non negative integer less than N (RANDOM X) Generate a Random Number SUBR Argument Types: X - a number or (), optional Value: A floating point number X, 0 < X < 1 Side Effects: Modifies RANDOM's internal seed for next call Description: Usually called with no argument. RANDOM just calculates the next element in a pseudo random sequence. When a number is provided as an argument, RANDOM uses it as a seed to start a new sequence. Any number will do: small or large, floating point or integer. When the value of the argument is (), RANDOM generates a new seed itself, "at random". This is the same as what is called RANDOMIZE in some BASICs. (RDSTR X) Read a String SUBR Argument Types: X - a number Value: Next atom in current input file Side Effects: Advances input file pointer Description: Reads a literal atom which consists of all the characters on INPUT up to the next character whose ASCII code is X. If no characters intervene, () is returned. RDSTR recognizes either control-Z or a physical end of file as the end of file indicator. (READ) Read an S-expression SUBR Value: Next expression on current input file. Side Effects: Advances input file pointer past next expression Description: Reads and returns an expression from the primary input file. Recognizes either control-Z or a physical end of file as the end of file indicator. (READC) Read A Character SUBR Value: Next character on current input file. Side Effects: Advances input file pointer Description: Reads one character from the primary input file. Returns it as an atom with a single character print name. READC recognizes either control-Z or a physical end of file as the end of file indicator. (READLINE) Read a Line EXPR/AUX Value: A list of elements in (INPUT)'s line buffer Side Effects: Advances the input file's pointer Description: Reads the elements on the current line of input and returns a list of them. If there is nothing available, READLINE returns (). (READP) Test For More to Read SUBR Value: T - if there is anything useful left to READ from the current input file () - otherwise Side Effects: May advance input file pointer Description: READP skips over the next sequence of delimiters; It actually advances the file pointer. If it encounters a non delimiter before the end of file it returns T, otherwise (). If the current input file is the console, READP advances only to the end of the current line; it won't perform a (FILLBUF). While READP is useful for deciding whether it is safe to READ, it can be misled. For example, if the last character in a file is a macro character which calls READ (e.g. any of ', ", $ or ;) or a left parenthesis, READP will return T even though performing a READ will cause an end of file error. READP recognizes either control-Z or a physical end of file as the end of file indicator. (READ@ X Y) READ after Positioning EXPR/AUX Argument Types: X, Y - numbers, optional Value: Expression read from current input file Side Effects: Repositions either the cursor or file pointer Description: Reads and returns one S-expression from the primary input file, using READ. The numbers X and Y are interpreted thus: IF input file is the console ; (EQ 'CON: (INPUT)) THEN Move screen cursor to X,Y ; (CURSOR X Y) ELSE Position the file to byte X ; (SFP (INPUT) X) (READ) This is useful both for reading from files and for reading from particular places on the screen. (RECLAIM) Do a Garbage Collection SUBR Value: () Side Effects: Causes a garbage collection (REM N1 N2) Divide Two Numbers, Return Remainder SUBR Argument Types: N1, N2 - numbers Value: A number equal to N1 REM N2 Description: Floats the computation if either argument is floating point. The remainder operation on floating point numbers is: (REM N1 N2) = N1 - ROUND(N1/N2)*N2 ROUND will round to the nearest integer. This is not quite the same as MOD (not provided) which truncates N1/N2 instead of rounding. For integers, REM is just like MOD. (REMPROP A P) Remove P from Property List of A SUBR Argument Types: A - a literal atom P - no restrictions Value: () Side Effects: Changes the property list of A Description: Performs a LISTREM on the property list of A. It (RENAME new old) Rename a Disk File SUBR Argument Types: new, old - both literal atoms Value: New if successful, NIL otherwise. Side Effects: Actually changes the file's name Description: Just calls CP/M. However, iLISP won't let you RENAME an open file or a read-only (i.e. CP/M $R/O) file. (REPEAT N exp) A simple control macro EXPR/UTILITY* Argument Types: N - an integer exp - an expression to be evaluated Value: NIL Description: REPEAT is a MACRO. Its meaning is: EVALUATE the expression N times. (REPLACEL X L N) Replace an Element of a List EXPR/UTILITY* Argument Types: X - the new element L - the list to be changed N - the position of the element to be replaced Description: Replaces the Nth element of the list L with the new element X (using RPLACA). (RESET) Abort Computation SUBR Value: Doesn't matter Side Effects: Aborts current computation Description: Forces a return to iLISP's top level evaluator. Both INPUT and OUTPUT are reset to CON:. (REVERSE L) Reverse the Elements of L EXPR/AUX Argument Types: L - a LIST Value: Copy of L, with element order reversed. Description: Makes a copy of L and performs DREVERSE on it. (RPLACA L X) Replace CAR of L with X SUBR Argument Types: L - non NIL list X - no restrictions Value: New value of L Side Effects: Modifies argument L Description: Replaces the CAR of L with X. This is a destructive function; it actually changes the list structure of L. It should be used with caution since it is possible to create a circular list structure with it. (RPLACAD L1 L2) Replace CAR and CDR of L1 SUBR Argument Types: L1 - non nil list L2 - non nil list Value: EQ to L1, but EQUAL to L2 Side Effects: Modifies argument L1 Description: Replaces both the CAR and CDR of L1 with the CAR and CDR of L2. This is a destructive function; it actually changes the list structure of L1. It should be used with caution since it is possible to create a circular list structure with it. (RPLACD L X) Replace CDR of L with X SUBR Argument Types: L - non NIL list X - list Value: New value of L Side Effects: Modifies argument L Description: Replaces the CDR of L with X. This is a destructive function; it actually changes the list structure of L. It should be used with caution since it is possible to create a circular list structure with it. (SET X V) Assign V to X SUBR Argument Types: X - a literal atom V - no restrictions Value: V Side Effects: Changes the local value of X Description: Like the syntactic form SETQ, except that both of the arguments are evaluated before the SET is performed. That is, (SET 'A 1) (SETQ A 1) (SET' A 1) are all equivalent. (SETPL X L) Set the Property List of an Atom SUBR Argument Types: X - a literal atom L - a list Value: L Side Effects: Changes the property list of X Description: Clobbers previous value for (GETPL X); installs new one. (SFP file addr) Set Current File Position SUBR Argument Types: file - an open file addr - an integer Value: Addr Side Effects: Moves the file pointer for file Description: Sets the file pointer for file to addr. Special Note: CP/M does not provide an open-for-append function, but if SFP is given a negative addr it will position the file to the beginning of the last record in the file. If the file is a binary file (unusual for LISP) the actual end of file position is 128 bytes past this point. If the file is an ASCII file (terminated with a control-Z) you then can PEEKC/READC your way to the last byte in the file. That is, repeatedly perform READCs until PEEKC returns (). (Or you can use INB to look for the control-Z.) (SINE N) Sine N SUBR Argument Types: N - a number, an angle in radians Value: A floating point number equal to the sine of N. (SPACES n) Print N Spaces SUBR Argument Types: N - an integer Value: () Side Effects: Advances output file pointer Description: Prints N spaces on the primary output file. (SQRT X) Square Root of X SUBR Argument Types: X - a positive number Value: floating point number = square root of X. (SUBST X Y Z) Substitute X for Y in Z EXPR/AUX Argument Types: X, Y, Z - no restrictions Value: Copy of Z with X replacing every occurence of Y in Z. (SUBSTRING S F N) Extract a Substring of a Literal Atom EXPR/UTILITY* Argument Types: S - a literal atom F, N - integers Description: Constructs a new literal atom whose print name is the substring of the print name of STRING, beginning with the START character and extending for COUNT characters. E.g. (SUB1 N) Decrement a Number SUBR Argument Types: N - a number Value: A number equal to N-1 Description: (- N 1) (SYNTAB X) Get/Set Entire Character Syntax Table SUBR Argument Types: X - literal atom, previously returned by SYNTAB, optional Value: A literal atom with the current or old value of the character syntax table as its print name. Side Effects: Changes character syntax table Description: A system function which sets or queries the entire character syntax table. (SYNTAX X N) Get/Set Character Syntax SUBR Argument Types: X - single character atom N - an integer, 0 <= N <= 7 (optional) Value: Old or current syntax number of X Side Effects: Changes syntax status of X Description: The character type of X is set to N, and the previous type is returned. (SYNTAX X) returns X's type unchanged. (TAB N) Tab to a Column SUBR Argument Types: N - an integer Value: () Side Effects: Advances output file pointer Description: Advances the output file to the specified column. If the pointer is at or past column N, no action is taken. (TCONC X L) Attach X to the End of L SUBR Argument Types: X - no restriction L - either NIL or a TCONC format list Value: A TCONC format list with X added to the end of L. Side Effects: Modifies its argument L. Description: TCONC is similar to CONS in that it adds its first argument X to its second argument L, a list. However TCONC adds X to the end of the list L, not the beginning. It is functionally similar (in purpose) to: (RPLACD (LAST L) (LIST X)). HOWEVER, a TCONC format list X, is a list whose CAR is the real list of interest and whose CDR is (LAST (CAR X)). This means that the pointer needed to perform the RPLACD is always available and there is no need to traverse the list with (LAST L) in order to add the element to the end of the list. In the end, you must take the CAR of the result for it to be useful. (TERPRI) Print an End of Line SUBR Value: () Side Effects: Advances output file pointer Description: Prints a CR/LF on the current output file. (TRACE X) Trace a function SUBR Argument Types: Either a number or a literal atom Description: IF X is a literal atom, TRACE sets a trace flag for the atom, meaning that when it is used as a function or a macro, tracing messages will be printed out. In this case, TRACE returns X as its value. IF X is a number, TRACE sets the PRINTLEVEL used for printing trace output to that number. In this case, TRACE returns the previous value of the TRACE printlevel. (TYPE file) Type the Contents of a File EXPR/UTILITY* Argument Types: a file name Value: file Description: TYPE duplicates the CP/M CCP command TYPE. It takes one argument, a file name, and types out the contents of the file on the current output device (presumably the console) . TYPE is interesting because it illustrates the use of a local function, TYPELOOP. This is defined as the value of a local variable, one defined inside the LET statement. The function is used by TYPE, but its definition disappears once TYPE is exited. (UNPACK X) Unpack a Print Name SUBR Argument Types: X - a literal atom Value: A list of single character atoms. Description: The inverse of PACK. Breaks the print name of X into single character atoms and constructs a list of them. (UNSET X) Remove X's Value SUBR Argument Types: X - a literal atom Value: NIL Side Effects: Actually changes X's value Description: Removes Xs binding in the current environment. (UNSETF F) Unset the entries on a file EXPR/UTILITY* Argument Types: File name Value: F Description: Applies UNSET to all of the entry names in file F. It effectively reverses an INFILE to the file F. This releases the free space and full space occupied by those functions for use by new ones. (UNTRACE X) Clear X's Trace Flag SUBR Argument Types: X - a literal atom Value: X Side Effects: Clears the trace flag associated with X (VALUEP X) Test for Value SUBR Argument Types: X - literal atom Value: T - if X has a value in the current environment () - otherwise Description: VALUEP doesn't return the value of X, (it might be ()), but simply T. If you need the value of X you might try: (ERRORSET NIL X) which returns a list of the value of X or () if X has no value. (ZEROP N) Test For Zero SUBR Argument Types: N - a number Value: T - if N = 0 () - otherwise (+ N1 N2) Add Two Numbers SUBR Argument Types: N1, N2 - numbers Value: A number equal to (N1 + N2). (- N1 N2) Subtract Two Numbers SUBR Argument Types: N1, N2 - numbers Value: A number equal to (N1 - N2) (* N1 N2) Multiply Two Numbers SUBR Argument Types: N1, N2 - numbers Value: A number equal to (N1 * N2) (/ N1 N2) Divide Two Numbers SUBR Argument Types: N1, N2 - numbers Value: A number equal to (N1 / N2) (= N1 N2) Test for Number Equality SUBR Argument Types: N1, N2 - numbers Value: T - if N1 and N2 have the same value () - otherwise (> N1 N2) Test for > relationship SUBR Argument Types: N1, N2 - numbers Value: T - if N1 > N2, () - otherwise (>= N1 N2) Test for >= relationship SUBR Argument Types: N1, N2 - numbers Value: T - if N1 >= N2, () - otherwise (< N1 N2) Test for < relationship SUBR Argument Types: N1, N2 - numbers Value: T - if N1 < N2, () - otherwise (<= N1 N2) Test for <= relationship SUBR Argument Types: N1, N2 - numbers Value: T - if N1 <= N2, () - otherwise Appendix I iLISP and Other LISP Differences Until recently, there was no standard definition of the LISP language. iLISP was written before the Common LISP definition was common knowledge. There are still many different dialects of LISP. iLISP is yet another. However, iLISP is very different from most other implementations because it is based on a radically different dialect of LISP called SCHEME. The main differences between iLISP and most other dialects are summarized below: 1) Function Definitions are Values Function definitions are not stored on LISP property lists as they are in many implementations. They are the values of literal atoms. 2) There are No FEXPRS iLISP does not support functions which block the evaluation of their arguments, the so-called FEXPRS. It does support LISP evaluation MACROs which, especially in conjunctions with LAMBDA, can handle all cases that FEXPRs were needed for. 3) Evaluation of the First Position of Function Application In iLISP, the function position of each function application is always evaluated exactly once. In most cases, when the first position is a variable, the single evaluation simply extracts its value and uses it. In other cases, e.g. a LAMBDA form, the position is evaluated and must evaluate to a function. One, consequence of this is that, in nearly all cases, LAMBDA forms (e.g. as used in the MAP functions) are NEVER quoted. 4) No Dotted Pairs iLISP supports only true lists. The final CDR of every list is NIL. This is enforced by READ, which doesn't recognize the dotted pair syntax, and by CONS, which doesn't accept a non list as its second argument 5) Lexical Variable Scoping Unlike most dialects of LISP, iLISP uses a static or lexical scoping rule. This has nothing to do with variable allocation, which, of course, is dynamic. It has to do with where variables get their values from at execution time. Traditional LISP has always had a dynamic variable scoping rule. The effect of this was that if a function, FOO called another function, FIE, FIE had access to FOO's internal variables. It could use their current values and even change them. While this device has legitimate uses, it is more often abused. In iLISP, references to variables which are not local to the function in which the reference is made refer to the outermost, static, global environment, where most of the function definitions are kept. One of the greatest advantages of this type of implementation is: 6) Tail Recursion is Stack Free Function calling, and in particular, recursive function calling, is one of the most powerful tools LISP has. Unfortunately, in most implementations, LISP programmers have had to restrict their use of this method of describing programs because it always uses the runtime stack of the LISP interpreter. However, in iLISP, as in SCHEME, the implementation iLISP was based on, a special case of the recursive use of functions is made without the use of the runtime stack. In particular, the last function call made from inside a function is made with a jump or a GOTO instead of a CALL. For a discussion of the differences between tail recursion and general recursion, see the discussion in Chapter 4 and also in the introductory guide. Because of this implementation of tail recursion, 7) No PROG and No GO Functions are Needed PROG and its associated non-applicative blemishes on LISP were added in order to allow programmers to write iterative alternatives to the recursive functions they wanted to write but could not because they were so expensive. With the stack free implementation of tail recursion, these functions are no longer needed and are not included in iLISP. Anything that once was coded with a PROG can now be coded as a tail recursive function or with a general control structure (coded in a tail recursive manner) such as DO or one of the MAP functions. 8) Functions are Genuine Data Types, the Value of LAMBDA forms Functions are not a subset of the list data type, i.e. those lists that begin with LAMBDA. LAMBDA is a special form which EVALUATES to a functions. The new data is internal only; it can't be read in or printed out directly. Example -CAR ;value of CAR #1246 ;the way procedures are printed out -REVERSE ;even EXPRs are printed in this way #42A3 However, EXPRs can be examined via the DESCRIBE function and modified via the EDITor. Functions are closures in that they carry their own environments (the environment in which the LAMBDA was evaluated) with them thus eliminating the so called FUNARG problem completely. CHAPTER FOUR discusses the most important of these differences, those relating to variable bindings and tail recursion, in greater detail.