PS/8 LISP - WRITE UP DECUS 8- -V3 16/5/73 PAGE 1 SUMMARY ------- THE LISP INTERPRETER, DECUS NO. 8-120A, HAS BEEN MODIFIED TO RUN UNDER PS/8; PS/8 FILE INPUT AND OUTPUT IS ALLOWED WHICH, ANONG OTHER THINGS, ALLOWS THE USER TO PREPARE LISP PROGRAMS USING THE PS/8 EDITOR. THE FUNCTIONS USED FOR FILE I/O ARE 'IOPEN','ICLOSE','OOPEN' AND 'OCLOSE'. ALSO LINE AT A TIME EDITING IS NOW AVAILABLE DIRECTLY WITHIN THE LISP INTERPRETER. 'TIMES','CLEAR', AND 'EXIT' FUNCTIONS HAVE BEEN ADDED. CCITT2 TELEPRINTER CODE IS NO LONGER SUPPORTED. WRITE UP PRINT CONVENTIONS -------------------------- DOUBLE QUOTES (") ARE USED AROUND NAMES OF CHARACTERS AS THEY APPEAR ON THE TERMINAL KEYBOARD. I.E. "$","(","RETURN". SINGLE QUOTES (') ARE USED AROUND THE PRINT NAMES OF LISP OBJECTS AND FUNCTIONS WHEN THEY APPEAR IN TEXT. I.E. 'ATOM','EVALQUOTE' IN EXAMPLE LISP EXPRESSIONS THE PRINT NAMES ARE USED WITHOUT THE QUOTES. ANGLE BRACKETS (<,>) ARE USED AROUND DISCRIPTIVE NAMES OF STRING ELEMENTS INTRODUCTION ------------ THE READER IS ASSUMED TO BE FAMILIAR WITH LISP, A PROGRAMMING LANGUAGE FOR LIST MANIPULATION. DETAILED DESCRIPTIONS CAN BE FOUND IN: 1. "LISP 1.5 PROGRAMMER'S MANUAL", J MCCARTHY ET AL, M.I.T PRESS, 1965 2. "THE PROGRAMMING LANGUAGE LISP - ITS OPERATION AND APPLICATION" E. C. BERKELEY AND D. G. BOBROW, EDS., INFORMATION INTERNATIONAL, INC. 3. "LISP 1.5 PRIMER", CLARK WEISSMAN, DICKINSON PUBLISHING COMPANY THE LISP SYSTEM IS AN INTERPRETER-BASED SIMPLIFICATION OF LISP 1.5 AS IMPLEMENTED ON THE IBM 7090. THE RESTRICTIONS ON SIZE IN THE PDP-8 HAVE CAUSED THE OMISSION OF MANY ADVANCED FUNCTIONS, WHICH CAN BE DEFINED IN MORE BASIC FUNCTIONS. NEVERTHELESS, THE SYSTEM HAS BEEN DESIGNED IN A VERY GENERAL WAY, E.G. NO RESTRICTIONS ON THE LENGTH OF NAMES AND ON THE SIZE OF THE PUSH-DOWN LIST, ALL FUNCTIONS C....R WITH AS MANY AS 11 A'S AND D'S IN BETWEEN ARE BUILT IN, DECIMAL INPUT/OUTPUT (CAN BE SWITCHED TO OCTAL INDEPENDENTLY FOR INPUT AND OUTPUT). THE STORAGE IS USED BOTH FOR PUSH-DOWN SPACE AND LIST SPACE. ONLY IF THE TOTAL CAPACITY OF BOTH TOGETHER IS TOO BIG, THE SYSTEM STOPS. THE PUSH-DOWN IS ORGANIZED ITSELF AS A LIST IN THE NORMAL LIST SPACE. A VERY FULL ASSORTMENT OF ERROR STOPS IS INCLUDED. JUST AS IN 7090 LISP, THE PROGRAMMER NEED NOT QUOTE HIS ARGUMENTS ON THE OUTSIDE LEVEL; THE SYSTEM HAS THE FUNCTION 'EVALQUOTE'. INPUT IS IN ASCII CODE. CONTROL OVER THE CHOICE OF LOW OR HIGH SPEED READER CAN BE EXERCISED BY A MODE NUMBER INSTEAD OF A FUNCTION IN 'EVALQUOTE'. (SEE SYSTEM OPERATION) PAGE 2 INSIDE THE SYSTEM A LISP CELL OCCUPIES TWO LOCATIONS IN CORE. THE FIRST LOCATION IS USED FOR THE 'CDR' PART AND THE NEXT LOCATION IS USED FOR THE 'CAR' PART. AS ALL CELLS START IN AN EVEN LOCATION, POINTERS ARE ALWAYS EVEN. THEREFORE, THE RIGHTMOST BIT HAS BEEN USED FOR OTHER PURPOSES, E.G. THE RIGHTMOST BIT IN THE 'CAR' PART IS THE ATOM MARK AND THE RIGHT- MOST BIT IN THE 'CDR' PART IS USED IN THE GARBAGE COLLECTER. IT IS NORMALLY ZERO. AS THE 'CDR' OPERATION IS MORE FREQUENT THAN THE 'CAR' OPERATION, THIS ARRANGEMENT ALLOWS THE 'CDR' TO BE SIMPLY PERFORMED BY THE INDIRECT ACCESS OF A LOCATION. ACCESS TO MACHINE CODE PROGRAMING IS THROUGH THE FUNCTIONS 'EXPR' AND 'ZEXPR'. 'EXPR' IS USED TO ACCESS CODE IN FIELD 1 WERE THE BODY OF THE INTERPRETER IS LOCATED. 'ZEXPR' IS USED TO ACCESS CODE IN FIELD 0 WERE PS/8 INTERFACE IS LOCATED AND WERE CONSIDERABLE SPACE IS AVAILABLE FOR EXTENDED FUNCTIONS. REFER TO THE LIST OF MACHINE CODE FUNCTIONS FOR DETAILS. THE SYSTEM IS LOCATED AT 10000-13765, 00034-00046,00100-02377 AND 05400-07577. 07600-07777 AND 17600-17777 ARE NORMALLY RESERVED FOR THE PS/8 MONITOR HEAD. THE REST OF FIELD 1 IS USED AS THE LIST SPACE. BY CHANGING A SINGLE CONSTANT THE LIST SPACE CAN BE LENGTHENED OR SHORTENED. FOR EXAMPLE, MACHINE CODE PROGRAMS CAN BE PLACED ABOVE THE LIST SPACE. THESE CHANGES CAN BE EXPRESSED IN THE LISP LANGUAGE ITSELF. THE AVAILABLE FUNCTIONS AND OBJECTS ----------------------------------- THE FOLLOWING LIST OF OBJECTS AND FUNCTIONS ARE BUILT-IN FOR PS/8 LISP. WHEN THEY ARE IDENTICAL TO THE SAME FUNCTIONS IN 7090 LISP, THEY ARE DESCRIBED VERY SUMMARILY, BUT SEVERAL FUNCTIONS DEVIATE IN SOME RESPECTS AND ARE MORE FULLY DESCRIBED. IN ADDITION, A LISP DEFINITION OF THE FUNCTION IS GIVEN WHERE POSSIBLE. THE LISP DESCRIPTION IS NOT ALWAYS ACCURATE, E.G. NO ERROR TESTING WILL BE SHOWN, NOR WILL MACHINE MODE FUNCTION BE EXPRESSED ADEQUATELY. BUILT-IN FUNCTIONS ARE RECOGNIZED BY THE VALUE OF THEIR POINTER. THEY DO NOT HAVE INDICATORS 'SUBR' OR 'FSUBR' ON THEIR PROPERTY LISTS. IN FACT THERE ARE FIVE KINDS OF BUILT-IN FUNCTIONS AND OBJECTS: 1. SPECIAL FUNCTIONS HAVING AN ARBITRARY NUMBER OF ARGUMENTS OR A VERY SPECIAL TREATMENT OF THEIR ARGUMENTS. THEY ARE: 'LAMBDA','NIL','FUNARG','T','APVAL','COND','FEXPR','FUNCTI','GO', 'LIST','MINUS','PLUS','TIMES','PROG','QUOTE','RETURN','SETQ','STOP', 'CLEAR','EXIT'. 2. FUNCTIONS WITH NO ARGUMENTS: 'GENSYM','READ','TERPRI','ICLOSE','OCLOSE'. 3. FUNCTIONS WITH ONE ARGUMENT: 'ATOM','CAR','CDR','DEFINE','NULL','NUMBER','PRINT'. 4. FUNCTIONS WITH TWO ARGUMENTS: 'ASSOC','CONS','DEFLIS','EQ','EQUAL','EVAL','GET','LESSP', 'RPLACA','RPLACD','SET'. 5. FUNCTIONS WITH THREE ARGUMENTS: 'APPLY','EXPR','ZEXPR','IOPEN','OOPEN'. PAGE 3 APPLY THIS IS A FUNCTION OF THREE ARGUMENTS. IT APPLYS THE FUNCTION MENTIONED IN THE FIRST ARGUMENT TO THE LIST OF ARGUMENTS MENTIONED AS THE SECOND ARGUMENT. THE ASSOCIATION LIST TO BE USED IS GIVEN IN THE THIRD ARGUMENT (OFTEN 'NIL'). DEFINE(( (APPLY(LAMBDA(FN ARGS ALIST)(PROG(K) ((NULL FN)(RETURN NIL)) ((FN-POINTER))NIL) THIS WILL PUT IN 10045 THE DIFFERENCE BETWEEN THE FIRST USABLE ADDRESS (=3725) AND THE LAST USABLE ADDRESS (NORMALLY 7577). THE CHANGE IN 10045 WILL HAVE NO IMMEDIATE EFFECT BUT WILL COME INTO PLAY ON THE NEXT RESTARTING (OR ON A COLLECTOR RUN). THEREFORE IT IS ADVISABLE TO HAVE THE CHANGE IN SIZE FOLLOWED IMMEDIATELY BY EXPR(3000 NIL NIL) OR CLEAR TO REINITIALIZE THE SYSTEM AND TO CREATE A NEW FREE SPACE. CHANGING THE SIZE GIVES THE POSSIBILITY TO ADD MACHINE CODE FUNCTIONS IN FIELD 1 OR TO RUN A SMALL LISP COMPILER TO COMPILE MACHINE CODE FUNCTIONS BEHIND THE LIST SPACE. IF WORKING SPACE IS AT A PREMIUM, ONE CAN ENLARGE THE WORKING SPACE TO THE MAXIMUM AMOUNT POSSIBLE, THEREBY OVERWRITING THE PS/8 MONITOR HEAD IN FIELD 1 BY EXPR(3202 45 3756) OR EXPR(1666 37 2030) IN DECIMAL. NOTE THAT THE PS/8 SYSTEM WILL HAVE TO BE BOOTSTRAPED AFTER DOING THIS. PS/8 PROGRAMMERS WILL NOTE THAT THE AREA FROM 17600 TO 17646 IS USED ONLY TO HOLD THE OUTPUT OF THE COMMAND DECODER. AS THIS IS NORMALLY NOT USED WITH LISP THIS SPACE CAN BE ADDED TO THE WORKING SPACE WITHOUT DESTROYING THE SYSTEM HEAD. PAGE 16 THE OPERATION OF THE SYSTEM CAN BE CONCISELY DESCRIBED BY THE FOLLOWING PROGRAM FOR 'EVALQUOTE': DEFINE(((EVALQUOTE(LAMBDA()(PROG(FN ARGS VALUE MODE ECHO HI) START13000 (CLEAR) (CLEARGENSYM) ERROR (SETQ MODE 2) START13001 (TERPRI) (SETQ ECHO (EQ(LOGAND MODE 45)0)) (SETQ HI (EQ(LOGAND MODE 4)4)) (SETQ FN (READ)) ((EQ(LOGAND MODE 1)0)(GO NOFN)) (PRINT FN) NOFN ((NUMBER FN)(GO NEWMODE)) (SETQ ARGS (READ)) ((EQ(LOGAND MODE 1)0)(GO NOARGS)) (PRINT ARGS) (TERPRI) NOARGS (SETQ VALUE (APPLY FN ARGS NIL)) ((EQ(LOGAND MODE 2)0)(GO START13001)) (PRINT VALUE) (GO START13001) NEWMODE (SETQ MODE FN) (GO START13001) ))) (CLEAR(LAMBDA()(RPLACD OBLIST(QUOTE(OBLIST))))) (CLEARGENSYM(LAMBDA()(EXPR 3202 17 0))) (LOGAND(LAMBDA(X Y)(EXPR 3174 X Y))) ))) EVALQUOTE NIL SOME FEATURES HAVE NOT BEEN SHOWN ADEQUATELY. THE FUNCTION 'READ' WILL PRINT AN IMMEDIATE ECHO IF 'ECHO' = 'T'. THE HIGH SPEED READER WILL BE USED IF 'HI' = 'T'. AN ERROR WILL GIVE AN ERROR PRINT AND WILL GO TO 'ERROR'. IF ANYWHERE INSIDE AN 'EVALQUOTE' PAIR A BLANK OR TRAILER CODE IS READ THIS IS AN ERROR. BLANK WILL ONLY BE SKIPPED BEFORE A PAIR. THIS FEATURE CAN BE USED TO STOP A TAPE ON THE HIGH SPEED READER BY ENDING THE PREVIOUS PAIR WITH A CARRIAGE RETURN,LINE FEED,BLANK. THE FUNCTION READ WILL THEN REACT AS IF THE NEW PAIR HAD BEGUN BECAUSE OF THE CARRAIGE- RETURN AND GIVES AN ERROR STOP. THE ERROR STOP THEN AUTOMATICALLY RETURNS THE MODE TO 2 AND HENCE SWITCHS TO KEYBOARD. SOME ACTIONS WILL BE DIFFERENT IF INPUT OR OUTPUT FILES ARE OPEN (SEE 'IOPEN','OOPEN'). PAGE 17 LIST OF ERROR CODES ------------------- DEPENDING ON WHETHER THE SYSTEM IS PRINTING IN DECIMAL OR IN OCTAL, THE FOLLOWING ERROR CODES WILL BE PRINTED: OCTAL DECIMAL KIND OF ERROR ----- ------- ------------- 164 116 ERROR IN OPENING/CLOSING FILE; ARGUMENTS NOT ATOMS 171 121 ERROR IN OUTPUTTING A CHARACTER ON CURRENTLY OPEN FILE 213 139 VALUE OF THIS VARIABLE IS NOT DEFINED 243 163 A NUMBER IS STANDING IN THE PLACE OF A FUNCTION 331 217 BUILT-IN FUNCTION HAS TOO FEW ARGUMENTS 346 230 BUILT-IN FUNCTION HAS TOO MANY ARGUMENTS 422 274 THIS FUNCTIONAL ARGUMENT IS NOT A FUNCTION 501 321 'LAMBDA' FORM HAS TOO FEW ARGUMENTS 522 338 'LAMBDA' FORM HAS TOO MANY ARGUMENTS 554 364 'GO','RETURN', OR 'COND' WITH UNDEFINED VALUE HAS BEEN ENCOUNTERED OUTSIDE OF A 'PROG' 567 375 'GO' HAS AN UNKNOWN LABEL 744 484 FIRST ARGUMENT OF 'SET' OR 'SETQ' IS NOT ATOMIC 1022 530 WRONG NUMBER OF ARGUMENTS IN THIS FUNCTION 1231 665 FIRST ELEMENT OF A PAIR IN 'DEFINE' OR 'DEFLIS' IS NOT A NAME 1260 688 ERROR IN OPENING AN INPUT FILE 1335 733 ERROR READING AN INPUT FILE 1345 741 NAME IN POSITION OF A FUNCTION WHICH IS NOT A FUNCTION 1501 833 THE 'CAR' OF AN ATOM HAS BEEN TAKEN 2125 1109 DIVIDE CHECK IN ZEXPR FOR DIVISION 2433 1306 BLANK IN A LISP EXPRESSION CANNOT OCCUR 2505 1348 CLOSING PARENTHESIS CANNOT OCCUR HERE 2526 1365 BLANK AFTER A NUMBER HAS BEEN FOUND 3252 1706 BLANK AFTER "'" HAS BEEN FOUND ? ? WORKING SPACE FULL @ @ COLLECTOR STACK FULL PAGE 18 EDITING CAPABILITIES IN THE INTERPRETER --------------------------------------- WHEN INPUT IS FROM THE TELETYPE, CHARACTERS ARE PLACED IN A BUFFER. NO TRANSMISSION OF CHARACTERS TO THE LISP SYSTEM OCCURS UNTIL A CARRIAGE RETURN OR ALTMODE IS STRUCK. WHEN EITHER OF THESE IS STRUCK, NO MORE INFORMATION IS READ FROM THE TELETYPE UNTIL ALL OF THE CHARACTERS IN THE BUFFER HAVE BEEN USED. THIS METHOD OF BUFFERED INPUT WAS CHOSEN IN ORDER THAT EDITING MAY BE DONE ON A TEXT LINE BEFORE TRANSMITTING THE LINE TO LISP. EDITING MAY ONLY BE DONE ON THE CURRENT LINE. CHARACTERS WITH SPECIAL SIGNIFICANCE ARE: 1. RUBOUT ECHOS (IF ECHO IS SPECIFIED) AS "\". THIS DELETES THE LAST CHARACTER IN THE BUFFER. 2. CONTROL-U ECHOS AS "^U". THIS DELETES THE ENTIRE BUFFER. 3. CONTROL-C ECHOS AS "^C". THIS CLEARS THE LISP SYSTEM (SAME AS CLEAR). 4. CONTROL-R ECHOS AS "^R". RESTARTS THE LISP SYSTEM (SAME AS START 13001) 5. RETURN. ECHOS AS A CARRIAGE-RETURN AND LINE-FEED. A CARRIAGE- RETURN IS INSERTED AS THE LAST CHARACTER IN THE BUFFER AND TRANSMISSION OF THE CHARACTERS IN THE BUFFER BEGINS. 6. ALTMODE. SAME AS "RETURN", BUT NO ECHO OCCURS. THE BUFFER IS 126 CHARACTERS LONG. MORE CHARACTERS (OTHER THAN RETURN OR ALTMODE ARE IGNORED UNTIL RETURN OR ALTMODE IS STRUCK. ASSEMBLING AND LOADING LISP --------------------------- .R PAL8 *LISP/L$ .SAVE SYS LISP;13000 OR: .R PAL8 *LISP,LISP) WILL CONVERT A NUMBER INTO A POINTER. ZEXPR(1703 X Y) WILL STORE THE NUMBER Y IN LOCATION X IN FIELD 0. ZEXPR(1713 X 0) WILL PRINT THE ASCII CHARACTER REPRESENTED IN THE LOW ORDER 8 BITS OF THE AC ON THE LINE PRINTER (I.E. THE DEVICE WHOSE HANDLER IS LOCATED AT 00600). IT RETURNS WITH THE AC CLEAR. USING THIS, ONE CAN PRINT ON THE LINE PRINTER EVEN IF ANOTHER OUTPUT FILE IS OPEN. ZEXPR(1710 X 0) WILL RETURN THE CONTENTS OF LOCATION X IN FIELD 0 AS ITS VALUE. ZEXPR (1717 X Y) WILL STORE X AT LOCATION Y IN FIELD 2 ZEXPR (1724 X Y) WILL STORE X AT LOCATION Y IN FIELD 3 ZEXPR (1731 X 0) WILL GET CONTENT OF LOCATION X IN FIELD 2 ZEXPR (1733 X 0) WILL GET CONTENT OF LOCATION X IN FIELD 3 ZEXPR (1735 X Y) WILL RETURN EXCLUSIVE LOCGICAL OR OF X AND Y ZEXPR (1745 X Y) WILL RETURN INCLUSIVE LOGICAL OR OF X AND Y ZEXPR (1755 X Y) WILL RETURN INCLUSIVE LOGICAL OR OF X AND Y USING MQ OPERATIONS. CAN BE USED ON PDP 8/E OR A PDP 8/I WITH EAE. ZEXPR (2000 X Y) LISP LEFTSHIFT FUNCTION. X*(2**Y) IF Y > 0 SHIFT X LOGICAL LEFT Y STEPS IF Y < 0 SHIFT X LOGICAL RIGHT Y STEPS. ZEXPR (2026 X Y) EAE VERSION OF ABOVE. NEEDS A PDP 8/I OR PDP 8/E WITH EAE. USES SHL/LSR. ZEXPR (2054 X Y) LISP DIVIDE FUNCTION. RETURNS REMAINDER AND STORES QUOoTIENT IN WORD 15 OF FIELD 1, WHERE IT CAN BE RETEIVED BY EXPR (3172 15-1) X/Y TO <15> ; X-Y*(X/Y) AS FUNCTION VALUE. ZEXPR (2076 X Y) EAE VERSION OF LISP DIVIDE. FUNCTION. RESULTS AS ABOVE. USES DVI, NEEDS EAE. ZEXPR (2112 X Y) UNSIGNED MULTIPLICATION, 12 BIT RESULT. X*Y IS RETURNED. USES EAE. PAGE 21 ZEXPR (2125 X Y) UNSIGNED MULTIPLICATION, 24 BIT RESULT. X*Y+<15>. MOST SIGNIFICANT 12 BITS TO <15>, LEAST SIGNIFICANT 12 BITS AS RETURNED RESULT. THE ROUTINE IS AIMED AT MULTIPLE PRECISION INTEGER ARITHMETIC. USES EAE. <15> IS THE QUOTIENT CELL IN FIELD 1. ZEXPR (2137 X Y) TWO WORD DIVIDE. (<15>,X)/Y TO <15> (QUOTIENT), RETURN REMAINDER USES EAE. THE ROUTINE IS AIMED AT MULTIPLE PRECISION INTEGER ARITHMETIC, USES EAE. <15> MUST BE LESS THAN Y. ZEXPR (2200 X Y) ADDITION WITH CARRY. (X+Y+<15>) TO <15> (CARRY), RESULT. THE ROUTINE IS AIMED AT MULTIPLE PRECISION INTEGER ARITHMETIC. ZEXPR (2211 X Y) BINARY PUNCH ROUTINE. IF Y<=0 THEN PUNCH X AND Y ELSE PUNCH X, -Y TIMES. ZEXPR (2237 0 0) SET DECIMAL, SIGNED INPUT/OUTPUT MODE. ZEXPR (2253 0 0) [ZEXPR (1195 0 0) IN DECIMAL] SET OCTAL UNSIGNED INPUT/OUTPUT MODE. ZEXPR (2307 X Y) ASSEMBLER FUNCTION CPAGE. CHECKS IF X AND X+Y BELONG TO SAME PAGE. IF TRUE THEN RETURN X, ELSE RETURN X+Y MASKED WITH 7600. DEFINE(( (CPAGE(LAMBDA(X Y)(COND ((EQ(LOGAND X 7600)(LOGAND(PLUS X Y)7600)X) (T(LOGAND(PLUS X Y)7600)) ))) )) ADDING NEW MACHINE LANGUAGE FUNCTIONS ------------------------------------- ASSEMBLE THE NEW FUNCTIONS INTO BINARY FILES THEN LOAD THEM OVER LISP AND RUN OR SAVE THE RESULTING PROGRAM. (STARTING ADDRESS IS 13000) EXAMPLE: ASSUME YOU HAVE TWO NEW FUNCTIONS, OVL1.BN AND OVL2.BN .R ABSLDR *LISP.SV/I *OVL1,OVL2$ .SAVE SYS LISPN;13000 .R LISPN