Programmer 7500

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

/ Programmer 7500 / MAX_PROGRAMMERS.iso / INFO / LISP / PDLISP.ZIP / MANUAL2.DOC < prev next >

Wrap

Text File | 1986-08-13 | 193.7 KB | 9,109 lines

PDLISP language manual Character Strings Chapter 10 Character Strings The following functions are provided with PDLISP to manipulate strings: STRCAT CSUBR (&REST STRING) STRCMP CSUBR (STR1 STR2) STREQ CSUBR (STR1 STR2) STRINGP CSUBR (X) STRLEN CSUBR (STR) STRXTRC CSUBR (STR I J) 10.1 STRCMP and STREQ STRCMP and STREQ are functions which are used in PDLISP to allow the comparison of the lexical order of strings. (STRCMP arg1 arg2) returns an integer based upon the comparison of its 2 arguments, as follows: value returned: meaning: -1 str1 < str2 0 str1 = str2 1 str1 > str2 STREQ is a bit simpler function. It returns the value of T if its 2 arguments are lexically the same, otherwise it returns a value of NIL. Here are some examples of STRCMP and STREQ: - 135 - Version 1.10 PDLISP language manual Character Strings /USR/LOGIN->(strcmp " E" "b") -1 ;result of comparison /USR/LOGIN->(strcmp "b" "a") 1 ;"b" is greater than "a". /USR/LOGIN->(strcmp "ab" "ab") ;equality produces 0 ; a zero result. /USR/LOGIN->(strcmp "abc" "abc ");trailing blank makes "abc " -1 ;lexically greater than "abc" /USR/LOGIN->(streq "a" "a") T /USR/LOGIN->(streq "abc" "abd") NIL 10.2 STRLEN and STRLENC STRLEN returns the length, in characters, of a PDLISP string. For example, (STRLEN "a simple string") evaluates to 17. Notice that the double quote marks are included in the length of the string. STRLENC is similar, except that the double quote marks are not included when the length of the string is included. So, in the above example, (STRLENC "a simple string") would evaluate to 15. For both of these functions, if the argument is not a string, then if it is a symbol, the print-name is used. Otherwise, if the argument is not a string or a symbol, an error results. - 136 - Version 1.10 PDLISP language manual Character Strings 10.3 STRCAT STRCAT is used to concatenate strings. STRCAT takes any number of arguments, STR1, STR2, ... STRN. A new string is returned which is the result of concatenating all of the strings together. For example, (STRCAT "MARY" " HAD A " "LITTLE LAMB") ==> "MARY HAD A LITTLE LAMB" 10.4 STRINGP STRINGP returns T if X is a string; otherwise returns NIL. 10.5 STRXTRC STRXTRC CSUBR (STR I J) STRXTRC (standing for "String eXTRaCt"), is the opposite of STRCAT; it takes strings apart instead of putting them together. Given a string, STR, and two integers, I and J, this function returns the substring of STR consisting of the Ith element through the Jth element, inclusive. The first element of STR is considered to be the 0th element, as if it were an array. If I is greater than J, or if the region that they specify lies outside of STR, then a null string ("") is returned. Also, if J is greater than the dynamic length of STR, then only the portion of STR which exists is returned. For example: - 137 - Version 1.10 PDLISP language manual Character Strings /USR/LOGIN->(strxtrc "abcd" 0 2) "abc" /USR/LOGIN->(strxtrc "abcd" 2 4) "cd" /USR/LOGIN->(strxtrc "abcd" 4 2) "" 10.6 FLATSIZE FLATSIZE CSUBR (FORM) FLATSIZE returns an integer which is the number of characters which would be output if form were printed using PRINT. - 138 - Version 1.10 PDLISP language manual Character Strings 10.7 EXPLODE and IMPLODE IMPLODE LAMBDA (X) EXPLODE CSUBR (X) EXPLODE and IMPLODE are used to convert symbol names to a list of individual characters, and back again. The individual characters are called character objects, and they are actually symbols which are interned in the object list. (explode 'foo) ==> (F O O) (implode '(f o o)) ==> FOO Currently, EXPLODE and IMPLODE only work on symbol names; if they were truly Common LISP compatible, they would work on arbitrary s-expressions. For example, we would have: (explode '(a b c)) ==> (#$ a b c #$) The sharp-sign macros are necessary in the above example in order to enable the LISP reader to deal with symbols named "(" and ")". We're planning upon upgrading EXPLODE and IMPLODE up to Common LISP specifications in a future release of PDLISP. IMPLODE creates a string which is the concatenation of the print-names of the elements of X, which must all be symbols. If a symbol exists along the reader search path with this string as its print-name then no action is taken. Otherwise, the new symbol is created in the current directory. In either case, the symbol is returned as the value of this function. As an example, (IMPLODE '(ab c d ef)) ==> ABCDEF and the symbol ABCDEF would be interned in the current directory if a symbol by that name did not already exist along the reader search path. - 139 - Version 1.10 PDLISP language manual Character Strings 10.8 GENSTRING GENSTRING CSUBR (&OPTIONAL X) GENSTRING creates a unique string. The string is of the form <PREFIX> <SUFFIX>, where <PREFIX> can be any string and where <SUFFIX> is an integer. Initially, <PREFIX> is empty, and <SUFFIX> is the string "0", so that (GENSTRING) evaluates to the string "0". After each time that GENSTRING is called, an internal counter is incremented, so that the second time that GENSTRING is called, the string "1" would be generated. The current values of <PREFIX> and <SUFFIX> can be set by using the optional parameter, X. If X is present and is a string, then <PREFIX> is set to it, and remains so altered until it is set to something else. The empty string is a legal PREFIX. Thus, (GENSTRING "FOO") would set PREFIX to the string "FOO", and all strings generated from then on would be of the form "FOOXX", where XX is some integer (not necessarily 2 digits). If X is present and is an integer, then the internal counter is set to X. So, the following sequence of interactions with PDLISP could occur: /USR/LOGIN->(genstring 3) "3" /USR/LOGIN->(genstring "FOO") "FOO4" /USR/LOGIN->(genstring) "FOO5" If X is present and is neither a string nor an integer, an error is signalled, and the normal error-handling machinery takes over, as follows: /USR/LOGIN->(genstring 'a) ***> GENSTRING: illegal &optional arg. - 140 - Version 1.10 PDLISP language manual Character Strings 10.9 GENSYM GENSYM LAMBDA (&OPTIONAL X) Creates a new symbol with a (hopefully) unique print-name according to the rules of GENSTRING. The same conventions which apply to the arguments for GENSTRING also apply to GENSYM. The symbol which is created is not INTERNed on the object list, and it is returned as the value of this function. For a function which creates an INTERNed symbol, see MAKE-SYMBOL. IMPLODE-TO-STRING CSUBR (X) This function concatenates the print-names of the elements of X, which must be a list of symbols. The resultant string is returned. The string so constructed is not interned in the object list; for a function which does that, use IMPLODE. As an example, (IMPLODE-TO-STRING '(x y zz y)) would evaluate to the string "XYZZY". INTERN CSUBR (X &OPTIONAL D) Interns a symbol in the object list with a print-name of X, which must be a string. The symbol is interned in directory D if D is provided; otherwise, the symbol is interned in the current directory. MAKE-SYMBOL CSUBR (X) Creates a new symbol, which is not interned on the object list, with a print-name of X. This function returns the new symbol. - 141 - Version 1.10 PDLISP language manual Character Strings This page intentionally left blank - 142 - Version 1.10 PDLISP language manual Character Strings This page intentionally left blank - 143 - Version 1.10 PDLISP language manual Character Strings This page intentionally left blank - 144 - Version 1.10 PDLISP language manual Arrays Chapter 11 Arrays Arrays are not currently implemented in PDLISP, but may be in the future. They will shortly (as of August, 1986) be available in UNXLISP. - 145 - Version 1.10 PDLISP language manual Arrays This page intentionally left blank - 146 - Version 1.10 PDLISP language manual Arrays This page intentionally left blank - 147 - Version 1.10 PDLISP language manual Arrays This page intentionally left blank - 148 - Version 1.10 PDLISP language manual Arrays This page intentionally left blank - 149 - Version 1.10 PDLISP language manual Arrays This page intentionally left blank - 150 - Version 1.10 PDLISP language manual Arrays This page intentionally left blank - 151 - Version 1.10 PDLISP language manual Arithmetic and Mathematical Functions Chapter 12 Arithmetic and Mathematical Functions This chapter describes the mathematical functions which are provided with PDLISP. Generic functions are capable of handling any combination of integers or floats; type restrictions on other functions are noted. DIV CSUBR (X1 X2) Returns the remainder of X1/X2. X1 and X2 must both be integers, or an error results. % CSUBR (X1 X2) Generic division function. X1 and X2 can be integers or floats, in any combination. FLOATP CSUBR (X) Returns T if X is a float; otherwise returns NIL. INTEGERP CSUBR (X) Returns T if X is an integer; otherwise returns NIL. > CSUBR (X1 X2) Generic greater-than function; works with any combination of integers and floats. >= CSUBR (X1 X2) Generic greater-than-or-equal-to function; works with any combination of integers and floats. - 152 - Version 1.10 PDLISP language manual Arithmetic and Mathematical Functions < CSUBR (X1 X2) Generic arithmetic "less-than" predicate. Works with integers or floats. <= CSUBR (X1 X2) Generic arithmetic "less-than or equal to" predicate. Works with integers or floats. - CSUBR (X1 &OPTIONAL &REST X2) Generic subtraction and negation routine. When invoked with one argument, this function will return the negation of that argument. When applied to more than one argument, this function subtracts from the first argument all of the rest, and returns the result. For example, (- 3 3 4) => -4. Compatibility note: This function is compatible with the - function in ZetaLISP and Common LISP. MOD CSUBR (X1 X2) Returns X1 modulo X2. X1 and X2 must both be integers. NEQL CSUBR (X1 X2) Equivalent to (NOT (EQL X1 X2)). * CSUBR (X1 X2) Generic multiplication function. X1 and X2 can be any combination of integers or floats. + CSUBR (&REST X) Generic addition function. This function returns the sum of its arguments, which can be any combination of integers or floats. - 153 - Version 1.10 PDLISP language manual Arithmetic and Mathematical Functions This page intentionally left blank - 154 - Version 1.10 PDLISP language manual Arithmetic and Mathematical Functions This page intentionally left blank - 155 - Version 1.10 PDLISP language manual Logic Functions Chapter 13 Logic Functions This chapter describes the boolean logic functions which are supported by PDLISP. AND CSUBR (X1 X2 ... Xn) This function is really a combination of a logic function and also a control function. AND evaluates each of its arguments in turn, until one of them evaluates to NIL or the end of the list is reached. If the end of the list is reached, then this function returns the value of the last argument; otherwise it returns NIL. NOT CSUBR (X) NOT performs the same function as NULL, which is a list processing predicate. NOT is included to clarify those situations where a logic operation is being performed, as opposed to testing for the end of a list or some other situation where NIL is being used as a terminator or flag. OR CSUBR (X1 X2 ... Xn) This function scans its parameter list from left to right, and returns the first non-NIL value which is detected. If all of its arguments are NIL, then a value of NIL is returned. - 156 - Version 1.10 PDLISP language manual Logic Functions This page intentionally left blank - 157 - Version 1.10 PDLISP language manual Logic Functions This page intentionally left blank - 158 - Version 1.10 PDLISP language manual Logic Functions This page intentionally left blank - 159 - Version 1.10 PDLISP language manual Logic Functions This page intentionally left blank - 160 - Version 1.10 PDLISP language manual LED, the PDLISP Structure Editor Chapter 14 LED, the PDLISP Structure Editor Although many LISP programmers utilize text editors exclusively, some prefer "structure editors", which enable direct manipulation of the s-expression pointer space. LED, the structure editor provided with PDLISP, is intended to be a small tool for making temporary patches in function definitions and data structures. Permanent changes should be made in the text file defining the function or data structure being altered. 14.1 Invoking and Exiting LED LED can be invoked using any of the following four functions: LEDEQ CNSUBR (X) LEDVQ CNSUBR (X) LEDPQ CNSUBR (X) LEDFQ CNSUBR (X) None of these functions quote their argument. LEDEQ is the most general function, and it means "edit an arbitrary expression." LEDVQ edits the value cell of a symbol. LEDPQ edits the property list of a symbol, and LEDFQ edits the function definition cell of a symbol. - 161 - Version 1.10 PDLISP language manual LED, the PDLISP Structure Editor To edit the function definition cell of FOO, where FOO is defined as (LAMBDA (X) (+ X 2)), one could type: /USR/LOGIN->(ledfq foo) LED ;LED prints out its name. (LAMBDA (X) (+ X 2)) ;and then the expression to ;be edited. * ;LED's prompt. LED saves the original expression so that one can undo all of the changes which we have been made. We can quit LED in two ways. Typing OK causes LED to terminate with any changes which may have been made intact. Typing Q causes LED to terminate, but the original expression is not altered. 14.2 Getting Around LED maintains an internal data structure called the thread. As one moves around inside the expression which is being editing, the thread keeps track of where LED has been. The subpart of the expression being edited is called the current expression. After every command has been executed, LED outputs the current expression, and then its own prompt ("*"), which indicates that it is ready for input. When LED is invoked, the current expression is the same as the entire expression being edited. Entering a positive integer, N, at the prompt causes LED to descend one level into the current expression. The Nth element of the current expression becomes the new current expression. For example, if the current expression were (A B C), then entering 2 at the prompt would cause LED to make B the new current expression. - 162 - Version 1.10 PDLISP language manual LED, the PDLISP Structure Editor LED also takes negative numbers as arguments; it interprets these to mean that you wish to change to the nth element from the end of the current expression. For example, if the current expression were (A B C), entering -1 at the prompt would cause LED to make C the current expression. Entering a 0 at the prompt pops the thread back up one level. As an illustration of these commands, consider the following dialogue: /USR/LOGIN->(ledeq (a b (c d) e)) LED ;LED echoes its name. (A B (C D) E) ;expression we're starting with. * 3 ;select 3rd element. (C D) ;LED echoes it back. * -1 ;select last element in current exp. D ;LED echoes it back. * 0 ;popping the thread 1 level. (C D) ;new current expression * 0 ;pop the thread again. (A B (C D) E) ;we're back at the beginning. 14.3 Making Mistakes If an error occurs during the execution of a command, LED will echo back the command, followed by a question mark ("?"). All errors are (or should) be trapped by LED in this manner. - 163 - Version 1.10 PDLISP language manual LED, the PDLISP Structure Editor 14.4 Making Changes Changes can be made in the current expression with three fairly simple commands: the insert, delete, and replace commands. Here's how they work: To insert something into the current expression, just enter a left parentheses, the letter "I", the position in the list before which you want to insert the new item, the element to be added, and a closing parenthesis. For example, /USR/LOGIN->(ledeq (a b c)) ;invoke LED. LED (A B C) ;current expression. * (i 2 X) ;insert "X" before "B". (A X B C) ; To delete the "X", use the "D" command, as follows: * (d 2) ;delete the second element. (A B C) ;this is the result. One could replace the "B" by an "X" with the "R" command, as follows: * (r b x) (A X C) The replace command replaces all occurences of its target pattern by the new pattern. For example, in the following example, there is more than one occurence of the symbol "D": (A B (C D) E D) ;current expression. * (r d z) ;replace all D's by Z. (A B (C Z) E Z) In the above example, D's are replaced by Z's wherever they appear in the current expression, and not just in the top-most level of the current expression. - 164 - Version 1.10 PDLISP language manual LED, the PDLISP Structure Editor 14.5 How LED prints out expressions When LED prints the current expression, it does so using the SPRINT function, which is defined in the file misc.l, which is part of the distribution. Any components of the current expression which are more than 3 levels deep in the structure are represented by an ampersand ("&"). LED does this in order to compress the output, and so that it does not "blow up" when it encounters a circular list. /USR/LOGIN->(ledeq (a b (c d (e f (g h) i j)))) LED (A B (C D (E F & I J))) ;current expression. * ;LED's prompt. In the above example, the top-most level of the current expression contains 3 sub-expressions; the first one is A, the second one is B, and the third one constitutes the rest of the list. If one wished to move to the third expression, one could enter the number "3", as follows: * 3 (C D (E F (G H) I J)) * In this case, when LED prints out the new current expression, it no longer substitutes "&" for "(G H)", because that subexpression is no longer more than 3 levels deep in the structure. - 165 - Version 1.10 PDLISP language manual LED, the PDLISP Structure Editor 14.6 A Quick Summary of LED Commands n, where n is an integer: n > 0 ==> make the current expression the nth element of the current expression n < 0 ==> make the current expression the nth from the last element of the current expression. (i.e., -1 selects the last element, -2 the second from the last, etc.) n = 0 => pops the thread one level. ^ pops the thread all the way back to the top. OK ends the edit and accepts the altered expression. Q ends the edit with no changes. E evaluates an expression and prints its value. P prints the current expression. PP pretty-prints the current expression COPY copies the entire thread to a safe place. RESTORE restores the thread to the value which was saved by copy. - 166 - Version 1.10 PDLISP language manual LED, the PDLISP Structure Editor MARK sets a mark in the mark list. The mark list is a trail of "knots" in the thread, which are called marks. Through the MARK, <, and << commands one can traverse this list. < goes back 1 place in the mark list, but does not pop the mark list, and << goes back 1 place in the mark list, and pops the mark list. POFF turns off the print flag, and PON turns it on. If the print flag is on, then the current expression is printed out after each command is executed. Otherwise, the current expression is printed out. LED starts out with the print flag on. 14.6.1 Structure Modification Commands (N E), N > 1 replaces the Nth element of the current expression with E. (N E1 E2 ... EM), N,M > 1 replaces the Nth element of the current expression with E1 E2 ... EM. (-N E), N > 1 inserts E before the Nth element of the current expression. (-N E1 E2 ... EM), N,M > 1 inserts E1 ... EM before the Nth element of the current expression. (R X Y) ("Replace") replaces all occurrences of X in the current expression by Y. The replacement is done throughout the current expression, and not just at the top-most level. For example, if the current expression were (LAMBDA (X Y) (+ X Y)), then typing (R Y Z) would change the current expression to (LAMBDA (X Z) (+ X Z)). - 167 - Version 1.10 PDLISP language manual LED, the PDLISP Structure Editor 14.6.2 Parenthesis Moving Commands (BI M N) ("Both In") inserts parenthesis before the mth element and after the nth element of the current expression. For example, if the current expression were (A B C D E), then executing (BI 3 4) would change it to (A B (C D) E). (BO N) ("Both Out") removes both parenthesis from the NTH element of the current expression, and splices its elements into the current expression. For example, if the current expression were (A B (C D) E F), then executing (BO 3) would result in (A B C D E F). (LI N) ("Left In") inserts a left parenthesis before the Nth element, and a matching right parenthesis at the end of the current expression. For example, if (A B C D E) were the current expression, then executing (LI 2) would result in (A (B C D E)). (LO N) ("Left Out") removes a left parenthesis from the Nth element of the current expression, and deletes all elements after the Nth element. For example, if the current expression were (A B (C D) E F), then executing (LO 3) would result in (A B C D). (RI M N) ("Right In") moves the right paren at the end of the Mth element inward until it is after the Nth element of the Mth element of the current expression. The remainder of the Mth element is elevated to the top-most level of the current expression. For example, if the current expression were (A B (C D E) F G), then executing (RI 3 2) would change it to be (A B (C D) E F G). (RO N) ("Right Out") moves the right parenthesis at the end of the Nth element out to the end of the current expression. The rest of the elements following the Nth one are moved inside of the Nth element. For example, if the current expression were (A B (C D) E F) then executing (RO 3) would change it to (A B (C D E F)). note - all of the above parenthesis moving commands take negative arguments, which are processed in the same way as simple numerical commands. That is, -1 refers to the last element of the current expression, -2 to the second to the last element, and so on. - 168 - Version 1.10 PDLISP language manual LED, the PDLISP Structure Editor This page intentionally left blank - 169 - Version 1.10 PDLISP language manual LED, the PDLISP Structure Editor This page intentionally left blank - 170 - Version 1.10 PDLISP language manual LED, the PDLISP Structure Editor This page intentionally left blank - 171 - Version 1.10 PDLISP language manual PDLISP Debugging Functions Chapter 15 PDLISP Debugging Functions 15.1 The PDLISP Debugger 15.1.1 A Bird's Eye View of the Stack If a bird could fly around inside of a LISP interpreter, it would see something like the following diagram: ------------- | frame 1 |<--- top-level +-------------+ | frame 2 | +-------------+ | frame 3 | +-------------+ ... +-------------+ | frame N |<--- current frame +-------------+ The above diagram is supposed to represent what is called the evaluation stack, or simply the stack. The stack consists of a sequence of frames. Each frame corresponds, roughly speaking, to one function call which is in the process of being evaluated. For example, if the expression (foo (bar a b)) were to be evaluated, then two frames would be created: one for the function FOO, and another for the function BAR. No frames are created when the variables A and B are evaluated; when the PDLISP evaluator was implemented, it was deemed too expensive to create a frame for each variable reference. - 172 - Version 1.10 PDLISP language manual PDLISP Debugging Functions The frame at the top of the diagram is called the top-level frame. It corresponds to a function called the top-level driver which is the primary interaction loop in PDLISP. This driver loop displays a prompt string, which is ususally the current directory followed by an "->" sign. Then, it reads an s-expression from the console, evaluates it, and prints the result. So, when you see a prompt like the following one: /USR/LOGIN-> you are interacting with the top-level driver. 15.1.2 DEBUG and DEBUGQ These two functions provide access to the PDLISP debugging system. Normally, when an error occurs, an error message is output on the console, and control is "thrown" back up to the top-level driver. For example, if the variable A were unbound, then we might see the following interaction taking place: /USR/LOGIN->(f a) (***> EVAL: variable A is UNBOUND.) /USR/LOGIN-> But, by using the DEBUG function, the state of the computation can be "frozen" at the point at which the error occurs, as in the following: /USR/LOGIN->(debug '(f a)) (***> EVAL: variable A is UNBOUND.) <1>: (return 1) 1 The DEBUGQ function is identical to the DEBUG function, except that it quotes its argument. So, instead of typing /USR/LOGIN->(debug '(f a)) we could have typed: /USR/LOGIN->(debugq (f a)) - 173 - Version 1.10 PDLISP language manual PDLISP Debugging Functions When the debugger is being used, and the PDLISP interpreter detects a mistake, it outputs a special prompt, namely "<1>:". This means that the interpreter is in a special mode, called the System Break Function, or just BREAK. In the above example, the interpreter halted evaluation of the expression (F A) because A had apparently never had a value assigned to it. The programmer in the above example exited BREAK by entering the expression (return 1). BREAK then took 1 to be the value of the entire expression. After evaluating (RETURN 1), the interpreter continues evaluation of any pending s-expressions on the stack. It is extremely important to notice that PDLISP takes "1" to be the value of "(F A)", and not of just the variable A itself. The "1" inside of the angle brackets represents a number called the "system break level". If we were to make another mistake while at the "<1>" prompt, then the interpreter would enter BREAK again, with an incremented break level. For example suppose that we blunder twice, as follows: /USR/LOGIN->(debugq (f b)) ;expression to be evaluated ***> EVAL: variable B is UNBOUND. ;unbound variable message <1>:(f a) ;suppose A is also unbound ***> EVAL: variable A is UNBOUND. ;unbound variable message <2>:(return 1) ;return 1 as value of (f a) 3 ;result of (f a) <1>:(return 1) ;let's return 1 1 ;as the value of (f b) /USR/LOGIN-> ;back to top-level We could also have returned directly to the top-level prompt, by using the RESET function as shown below: /USR/LOGIN->(debugq (f a)) ***> EVAL: variable A is UNBOUND. ;standard error message. <1>:(reset) /USR/LOGIN-> ;back to top-level - 174 - Version 1.10 PDLISP language manual PDLISP Debugging Functions Note that in the above example, we could be many levels deep into the break handler, and we could still have gotten back to the top-level. For example, if the "<1>:" were a "<4>:", we could still have gotten back to the top-level with a (RESET). 15.2 A Sample Debugging Session Before examining in detail all of the debugging functions which are supplied with PDLISP, let's go through a typical debugging session to see how it is all supposed to fit together. First, suppose that we have written a function called BLOWUP, which is supposed to add two numbers together and return the result. We could have defined BLOWUP as follows: /USR/LOGIN->(defun blowup (x y) (+ x y)) ;a 1-line function definition. BLOWUP ;DEFUN returns name of function. Now, let's invoke BLOWUP on a test case: /USR/LOGIN->(debugq (blowup a 4)) ;suppose that A is not bound. (***> EVAL: variable A is UNBOUND.) ;PDLISP outputs an error message <1>: ; and goes into the break handler. At this point, we can examine the contents of the stack using the SHOWSTACK function, as follows: <1>:(showstack) (SHOWSTACK) <----------------------- frame -----------------------> ("***> EVAL: variable " A "is unbound.") <----------------------- frame -----------------------> (BLOWUP A 4) <----------------------- frame -----------------------> - 175 - Version 1.10 PDLISP language manual PDLISP Debugging Functions (EVAL E) <----------------------- frame -----------------------> (SETQ RESULT (EVAL E)) <----------------------- frame -----------------------> (PROGN (SETQ OLDERRLBL (STATUS ERROR_LABEL)) (STATUS ERROR_LABEL NIL) (SETQ RESULT (EVAL E)) (STATUS ERROR_LABEL OLDERRLBL) RESULT) <----------------------- frame -----------------------> ((PROGN (SETQ OLDERRLBL (STATUS ERROR_LABEL)) (STATUS ERROR_LABEL NIL) (SETQ RESULT (EVAL E)) (STATUS ERROR_LABEL OLDERRLBL) RESULT)) <----------------------- frame -----------------------> (((PROGN (SETQ OLDERRLBL (STATUS ERROR_LABEL)) (STATUS ERROR_LABEL NIL) (SETQ RESULT (EVAL E)) (STATUS ERROR_LABEL OLDERRLBL) RESULT))) <----------------------- frame -----------------------> (BLOCK DEBUG ((PROGN (SETQ OLDERRLBL (STATUS ERROR_LABEL)) (STATUS ERROR_LABEL NIL) (SETQ RESULT (EVAL E)) (STATUS ERROR_LABEL OLDERRLBL) RESULT))) <----------------------- frame -----------------------> (DEBUG E) <----------------------- frame -----------------------> - 176 - Version 1.10 PDLISP language manual PDLISP Debugging Functions (DEBUGQ (BLOWUP A 4)) <----------------------- frame -----------------------> (EVAL E) <----------------------- frame -----------------------> (PRINT (EVAL E)) <----------------------- frame -----------------------> (PROGN (OUTPROMPT) (SETQ E (READ)) (PRINT (EVAL E))) <----------------------- frame -----------------------> ((PROGN (OUTPROMPT) (SETQ E (READ)) (PRINT (EVAL E)))) <----------------------- frame -----------------------> (CATCH ((QUOTE ?*TOPLEVEL*?) (QUOTE CONTROL_C_LABEL)) (PROGN (OUTPROMPT) (SETQ E (READ)) (PRINT (EVAL E)))) <----------------------- frame -----------------------> (TOPLEVEL) <----------------------- frame -----------------------> T (***> EVAL: variable _A is unbound.) <1>: Some explanation of the above output may be in order. The first frame, (SHOWSTACK), pertains to the invocation of the SHOWSTACK function, and has nothing at all to do with the evaluation of BLOWUP. The next frame constitutes the error message which was output immediately before the break loop was entered. There may be some extra double quote marks in this expression, because SHOWSTACK uses different print functions than the PDLISP error handler. - 177 - Version 1.10 PDLISP language manual PDLISP Debugging Functions The following frame, (BLOWUP A 4), is the expression which caused the error to occur. The next several frames, (EVAL E) up to and including (DEBUGQ (BLOWUP A 4)) are related to the evaluation of DEBUGQ. The last group of frames, from (EVAL E) up to and including (TOPLEVEL) pertain to the evaluation of the "top-level driver loop", which control interaction with the interpreter at the "/USR/LOGIN->" prompt. After all frames have been output, the break handler outputs T, which is the value of SHOWSTACK, and outputs the original error message. Then, another break prompt, "<1>:" in this case, is output, and the interpreter waits for more commands from the console. Since only the first few frames pertain to the evaluation of BLOWUP, the SHOWSTACK function takes an optional argument which specifies the number of frames to print out. For example, one could type (SHOWSTACK 4), and only 4 frames would be printed out. Other debugging functions are provided with PDLISP, and are detailed in the following section. - 178 - Version 1.10 PDLISP language manual PDLISP Debugging Functions 15.3 Debugger Support Functions SHOWSTACK LAMBDA (&optional NFRAMES) Prints a display of the environment stack on the standard output (console). An s-expression corresponding to each frame on the stack is output on its own line. A frame is created whenever a lambda-binding transaction occurs. This could happen when: (1) A function is being applied to some (possibly empty) argument list. (2) When a PROG has been entered, one frame each is created for the BLOCK, LET, and TAGBODY forms which are produced when the PROG macro is expanded. (3) Other macros, such as DO and DO*, also expand into combinations of BLOCK, LET, and TAGBODY forms. Consult their source code for more precise details. The s-expression corresponding to the most recent frame is output first, and the top-most expression (which would normally be part of the top-level driver) is output last. If the optional parameter NFRAMES is specified, then only that number of frames back from the current one are printed out. Otherwise, the entire contents of the stack are printed out back to the top-level driver. - 179 - Version 1.10 PDLISP language manual PDLISP Debugging Functions BAKTRACE NLAMBDA (&OPTIONAL NFRAMES) This function is similar to SHOWSTACK, except that only minimal information is shown about each frame. The CAR of the form being evaluated in each frame on the stack is examined. If it is atomic it is printed out. Otherwise the CAAR of the form corresponding to the frame is printed out. This usually results in the name of the function which is being applied to some argument(s) being printed out. The optional parameter NFRAMES is similar to the parameter of the same name when supplied to SHOWSTACK. BAKTRCE CSUBR (MODE) This function is a low-level function designed to facilitate the implementation of debugging tools. It returns a list corresponding to the environment stack. The actual information in the list depends on MODE, which must be an integer. If MODE is 0, then a partial display is produced, consisting of a list of forms. Each form corresponds to the expression being evaluated at a corresponding frame on the environment stack. If MODE is 1, then a full display is produced, consisting of a list of sublists. Each sublist is of the following format: (form frametype framenumber numargs returnable label l-list) where each item has the following meaning: form - the form being evaluated frametype - type of frame, represented as an integer. the values are: 1 - created by EVAL 2 - created by BREAK 3 - created by TAGBODY 4 - created by CATCH 5 - created by the macro expander 6 - created by BLOCK 7 - created by LET or LET* - 180 - Version 1.10 PDLISP language manual PDLISP Debugging Functions framenumber - a unique integer identifying the frame. returnable - T indicates that the computation can be restarted with this frame by calling UNWIND. NIL indicates that this cannot be done. label - catch label if this frame was a catch frame, otherwise NIL. numargs - integer which is the number of arguments (actual parameters) which were passed if the frame was a funcall, otherwise 0 l-list - list of lambda-variables, if there are any, otherwise NIL. DEBUG NLAMBDA (X) Sets up a debugging environment (see DEBUGSET), evaluates X, restores the environment to its original state, and returns the result of evaluating X. DEBUGQ LAMBDA (X) Similar to DEBUG, except that it quotes its argument. DEBUGSET NLAMBDA (X) Sets up the environment to be either a debugging or a non-debugging environment, depending on the value of X. If X is NIL, then a non-debugging environment is set up; otherwise, a debugging environment is set up. In a debugging environment, internal errors (such as those generated by system primitives) generate a call to the break handler, which may be either the system break handler or a user-specified break handler. In a non-debugging environment, internally generated errors cause control to be THROWN back to the top-level driver. Also, the smash hook is set to NIL in a debugging environment, so that macros will appear unexpanded in a back-trace. PDLISP is set up so that, as delivered, it is not in a debugging - 181 - Version 1.10 PDLISP language manual PDLISP Debugging Functions environment. See DEBUG, DEBUGQ, RESET, ERR, ERRSET, CATCH, and THROW. RESET NLAMBDA (&OPTIONAL (E NIL)) Throws control back to the top-level driver loop, if one exists. Optionally, the parameter E can be specified as the value to be thrown. Otherwise, a value of NIL is thrown. 15.3.1 TRACE and UNTRACE TRACE NLAMBDA (&REST FNLIST) UNTRACE NLAMBDA (&REST FNLIST) TRACE and UNTRACE provide a way of selectively viewing the activity of functions as they are entered and exited. For example, suppose that we have defined a function FOO as follows: (defun foo (x y) (+ x y)) Then, after tracing FOO by entering (TRACE FOO) and invoking it, we would see: /USR/LOGIN->(foo 2 3) entering FOO 2 3 exiting FOO 5 A more interesting demonstration involves RFIB, which is provided in the PDLISP distribution in the file named "examples.l". /USR/LOGIN->(loadv "examples.l") _RFIB _IPOWER _DO_IPOWER _IFACT _RFACT _REV _APP - 182 - Version 1.10 PDLISP language manual PDLISP Debugging Functions T /USR/LOGIN->(trace rfib) ;tracing rfib. (T) /USR/LOGIN->(rfib 3) ;invoke rfib. entering _rfib (3) ;arguments are in parenthesis. entering _rfib (2) entering _rfib (1) exiting _rfib 1 ;results are not in parenthesis. entering _rfib (0) exiting _rfib 1 exiting _rfib 2 entering _rfib (1) exiting _rfib 1 exiting _rfib 3 3 ;final result In the above example, the amount of indentation indicates how many times RFIB has called itself. Each time that RFIB is entered, the amount of indentation is increased by 2 spaces. Likewise, each time that RFIB is exited, the indentation is decreased by 2 spaces. We can also trace multiple functions at once by specifying them all at once to TRACE. For example, /USR/LOGIN->(trace foo bar baz) (T T T) would trace the functions named FOO, BAR, and BAZ. The result returned by TRACE is a list of T's and NIL's reflecting the success (or failure) of the tracing operation for each argument. UNTRACE takes a list of symbols to be untraced, and returns T or NIL for each argument to indicate success or failure. For example, if FOO and BAR had previously been traced, and BAZ had not, then we would have: /USR/LOGIN->(untrace foo bar baz) (T T NIL) TRACE and UNTRACE will be brought up to the full Common LISP specification in a future release, and a STEP function will also be released. - 183 - Version 1.10 PDLISP language manual PDLISP Debugging Functions 15.4 System Hooks and the STATUS Function Hooks are a way of communicating with the interpreter about low-level behavior. A general explanation of the hook functions available in PDLISP is presented in this section. STATUS CSUBR (X &OPTIONAL Y) This is a generalized system status routine which allows system "hooks" and constants to be examined and set. STATUS behaves in two different modes, depending upon the number of arguments which are passed to it. The first argument, which is required, must be an integer. This argument is associated with some system hook or constant. The second argument, which is optional, can be any symbolic expression. If one argument is passed to it, then STATUS returns the value of an associated system hook or constant. For example, (STATUS 400) returns the current value of the reader search path. If two arguments are passed to STATUS, then the second argument is assumed to be the new value of the system hook or function which is associated with the first argument. For convenience, a group of variables have been defined as integers in SYS/CONST to allow the usage of STATUS on a mnemonic basis. These variables, their corresponding integer values, and explanations of their meanings are given below: - 184 - Version 1.10 PDLISP language manual PDLISP Debugging Functions 15.4.1 The Top-Level Hook /SYS/CONST/TOP_LEVEL_HOOK value of variable = 0 The top-level hook has been provided so that the user can customize the outermost level of interaction of the interpreter. Usually, this consists of a "read-eval-print" loop, but other configurations are possible. A sample top-level function is defined in dirlib.l. (STATUS TOP_LEVEL_HOOK VALUE) sets the top-level function hook to VALUE. From then on, this user-defined function is used instead of the built-in read-eval-print loop. (STATUS TOP_LEVEL_HOOK) returns the current value of the top-level hook 15.4.2 The Pretty-Printer Hook /SYS/CONST/PP_HOOK value of variable = 1 The pretty-printer hook has been provided so that the user can specify that all output is to be formatted. As delivered, this hook is set to NIL, so that output is formatted only when one of the pretty-printing functions (PP, PPDEF) has been called. See also the descriptions of the functions PP, PPDEF, and UNPRINT. (STATUS PP_HOOK X) sets the system pretty-printer hook to X. If this hook is non-NIL, then the user-specified function is called by PDLISP every time that it outputs an s-expression to the screen. (STATUS PP_HOOK) returns the current contents of the pretty-printer hook. - 185 - Version 1.10 PDLISP language manual PDLISP Debugging Functions 15.4.3 The Smash Hook /SYS/CONST/SMASH_HOOK value of variable = 2 (STATUS SMASH_HOOK X) sets the value of the smash hook to X. If X is non-NIL, then all macros are assumed to be displacing macros. Setting the smash hook to NIL resets the system so that macros are not displacing. As delivered, the smash flag is set to T, in order to speed up execution. The smash flag is turned off inside of the debugger so as to facilitate back-tracing. (STATUS SMASH_HOOK) returns the current contents of the smash hook. 15.4.4 The Break Hook /SYS/CONST/BREAK_HOOK value of variable = 3 This hook has been provided so that the user can specify a custom function to be invoked when an error is detected by the interpreter. As delivered, the break hook is initialized to NIL, so that whenever the system needs to invoke a break handler, it calls the default one which is hard-coded inside of the interpreter. (STATUS BREAK_HOOK) returns the current contents of the break hook. The hook is set by entering (STATUS BREAK_HOOK <hook-fn>), where <hook-fn> is some s-expression which evaluates to the name of the function which is to be the new break handler. For example, (STATUS BREAK_HOOK 'FOO) sets the break hook to be the function FOO. - 186 - Version 1.10 PDLISP language manual PDLISP Debugging Functions 15.4.5 The Evaluatator Hook /SYS/CONST/EVAL_HOOK value of variable = 4 (STATUS EVAL_HOOK VALUE) sets the evaluator hook to VALUE. This hook is examined by EVAL each time that it is entered; if the hook is set to a non-NIL value, then this value is taken to be a user-defined evaluator function. The evaluator hook is then set to NIL, and the user-defined hook function is applied to the current argument list of EVAL. EVAL returns as its value whatever the hook function returned. The PDLISP Debugger uses this function to "single step" through an evaluation. (STATUS EVAL_HOOK) returns the current contents of the evaluator hook. 15.4.6 The Full Path Flag /SYS/CONST/FULL_PATH_FLAG value of variable = 5 (STATUS FULL_PATH_FLAG VALUE) sets the full-path flag to VALUE, and (STATUS FULL_PATH_FLAG) returns its current value. The full path flag regulates the output of symbol names. If this flag is non-NIL, then the full path-name of every symbol is always output; otherwise, only the last segment of symbol names is output. 15.4.7 The Directory Prefix Flag /SYS/CONST/DIR_PREFIX_FLAG value of variable = 6 (STATUS DIR_PREFIX_FLAG VALUE) sets the underscore prefix flag to VALUE, and (STATUS DIR_PREFIX_FLAG) returns its current value. Setting this hook to a non-NIL value causes the PDLISP kernel to print out all symbols which are in the current directory with a leading underscore. Setting the flag to NIL causes PDLISP to print all symbols without the underscore. - 187 - Version 1.10 PDLISP language manual PDLISP Debugging Functions 15.4.8 The Error Hook /SYS/CONST/ERROR_HOOK value of variable = 7 (STATUS ERROR_HOOK VALUE) sets the error handler hook to VALUE. The error hook is the function which is invoked when errors which do not require a break loop are to output their messages. As delivered, this hook is set to NIL, and error messages are output starting at the present position of the cursor. Using this function, one could output error messages in a "status line", or in some particular window. (STATUS ERROR_HOOK) returns the current value of this hook. 15.4.9 The Garbage Collector Verbosity Flag /SYS/CONST/GC_VERBOSITY value of variable = 8 (STATUS GC_VERBOSITY VALUE) sets the garbage collector verbosity flag to VALUE. A VALUE of NIL indicates that the mark and sweep collector is silent, whereas a non-NIL VALUE causes the system to ring the bell every time that the collector is activated. This function returns VALUE as its value. (STATUS GC_VERBOSITY) returns the current contents of this hook. - 188 - Version 1.10 PDLISP language manual PDLISP Debugging Functions 15.4.10 The Back-Quote Hook /SYS/CONST/BACK_QUOTE_HOOK value of variable = 10 The reader expands any expression it sees of the form `<exp> to (<back_quote_hook> <exp>), where <back_quote_hook> is the current value of the back-quote hook. PDLISP initializes this hook on boot-up from code in bakquote.l. (STATUS BACK_QUOTE_HOOK VALUE) sets this hook to VALUE. (STATUS BACK_QUOTE_HOOK) returns its current value. 15.4.11 The Comma Hook /SYS/CONST/COMMA_HOOK value of variable = 11 The reader expands any expression it sees of the form ,<exp> to (<comma_hook> <exp>). PDLISP initializes this hook on boot-up from code in bakquote.l. (STATUS COMMA_HOOK VALUE) sets this hook to VALUE. (STATUS COMMA_HOOK) returns the current contents of this hook. - 189 - Version 1.10 PDLISP language manual PDLISP Debugging Functions 15.4.12 The Comma-At Hook /SYS/CONST/COMMA_AT_HOOK value of variable = 12 The reader expands any expression it sees of the form ,@<exp> to (<comma_at_hook> <exp>). PDLISP initializes this hook on boot-up from code in bakquote.l. (STATUS COMMA_AT_HOOK VALUE) sets this hook to VALUE. (STATUS COMMA_AT_HOOK) returns the current value of this hook. 15.4.13 The Error Label Hook /SYS/CONST/ERROR_LABEL value of variable = 13 (STATUS ERROR_LABEL VALUE) sets the error label to VALUE. VALUE must be an interned symbol. This feature controls what happens when the PDLISP system break handler is called, and the user has not defined a user-break handler. If the error label is set to a non-NIL value, then the PDLISP kernel attempts a (THROW ERROR_LABEL MESSAGE), where MESSAGE is an error message. (STATUS ERROR_LABEL) returns the current contents of this hook. - 190 - Version 1.10 PDLISP language manual PDLISP Debugging Functions 15.4.14 The Parenthesis Counting Flag /SYS/CONST/PCOUNT_FLAG value of variable = 14 (STATUS PCOUNT_FLAG VALUE) sets the parenthesis counting flag to VALUE. If this flag is non-NIL, then parenthesis counting is done whenever an s-expression is read from the console. Whenever the reader is waiting for input, and the current expression being read would require 1 or more right-parenthesis in order to be completed, a line of the form: N -> will be output. The number N refers to the number of unmatched left parenthesis in the expression being entered. This flag is set to T upon boot-up, as a result of an STATUS call in dirlib.l. (STATUS PCOUNT_FLAG) returns the current contents of this hook. 15.4.15 The Current Directory Hook /SYS/CONST/CURRENT_DIR value of variable = 100 (STATUS CURRENT_DIR) returns the current directory. (STATUS CURRENT_DIR X) sets the current directory to X. More convenient functions for setting the current directory are CD, CDQ, MCD, MCDQ, PD, PDQ, and POPD. - 191 - Version 1.10 PDLISP language manual PDLISP Debugging Functions 15.4.16 The Break Level Hook /SYS/CONST/BREAK_LEVEL value of variable = 200 (STATUS BREAK_LEVEL X) sets the break level to X, where X is an integer. The break level is output as part of the system break handler prompt. For example, if the break level was 4, then the system break handler would output "<4>:" as its prompt. The break level is incremented every time that another error occurs, and is decremented whenever the break handler is exited. (STATUS BREAK_LEVEL) returns the current break level as an integer. - 192 - Version 1.10 PDLISP language manual PDLISP Debugging Functions 15.4.17 The X-Position Hook /SYS/CONST/X_POSITION value of variable = 201 (STATUS X_POSITION) returns the current x-coordinate of the cursor on the system console; when windows are implemented, this system will be extended to be usable on any interactive stream. The coordinate system assumes (0,0) to correspond to the extreme upper left of the screen; 15.4.18 The Y-Position Hook /SYS/CONST/Y_POSITION value of variable = 202 (STATUS Y_POSITION) returns the current y-coordinate of the cursor on the system console; when windows are implemented, this system will be extended to be usable on any interactive stream. - 193 - Version 1.10 PDLISP language manual PDLISP Debugging Functions 15.4.19 The Reader Search Path Hook /SYS/CONST/READER_SEARCH_PATH value of variable = 400 (STATUS READER_SEARCH_PATH) returns the current value of the reader search path. (STATUS READER_SEARCH_PATH Y) sets the search path to the new value Y (which must be a list). As delivered, the reader search path is set to (/SYS/CONST /SYS/CMD). - 194 - Version 1.10 PDLISP language manual PDLISP Debugging Functions 15.4.20 The Floating Point Format Hook /SYS/CONST/FLOAT_FORMAT value of variable = 500 The floating point format hook enables the user to customize output of floating point numbers in PDLISP. Basically, this hook is a string which is interpreted by PDLISP in the same way that it would be by the PRINTF function in the C programming language. (STATUS FLOAT_FORMAT VALUE) sets the floating point output format to VALUE. VALUE should be a string, and its meaning is identical to the analogous meaning in the C programming language. As delivered, this string is set to "%g "; for those who are not familiar with C, an explanation of the possible values for this parameter follow: Each format string starts with the percent sign ("%") and ends with a letter, called the conversion character. The conversion character must be "e", "f", or "g". The meaning of the conversion character are as follow: e - Floats are printed out in the form [-]m.nnnnnn[+-]xx, where the number of n's is dtermined by the precision specification, which is item number (4), below. The default precision is 6. f - The float is output in the form [-]mmm.nnnnnn, where the number of n's is determined by the precision specification, which is described under (4), below. The default precision is 6. g - The float is output with either %e or %f, depending upon which alternative produces shorter output. The number of digits trailing the decimal point is specified by the precision, and the default for the precision is 6. - 195 - Version 1.10 PDLISP language manual PDLISP Debugging Functions Inbetween the percent sign and the conversion character there may be: (1) a minus sign, which indicates that floats should be left-justified. (2) a digit or sequence of digits, which specifies a minimum field width. (3) a period, which delimits the field width (number (2), above) from the precision specification (item number (4), below). (4) A digit or sequence of digits, which indicates the number of digits to be printed to the right of the decimal point. (STATUS FLOAT_FORMAT) returns the current value of this hook, which is always a string. - 196 - Version 1.10 PDLISP language manual Interfacing to the Operating System Chapter 16 Interfacing to the Operating System The easiest way to interface to the operating system is to call a program residing on disk with the shell escape. The shell escape can be invoked by typing an exclamation point immediately after the PDLISP prompt, and following that by a command to be sent to the host O/S. For example, we could invoke the VI editor on UNIX by typing: /USR/LOGIN->!vi foo.l Such an invocation would result in VI being called up on a text file called "foo.l". After termination of the VI session, control would revert back to PDLISP. The PDLISP environment should be as it was when VI was invoked. The most usual usage of the shell escape under PDLISP is to edit a lisp file. After the edit, the file can be read in using LOAD or LOADV. For example, after the above example, we could type: /USR/LOGIN->(loadv "foo.l") The shell escape can also be used in another way, that of temporarily exiting PDLISP entirely. To do this, type the exclamation point by itself with nothing after it, and then a carriage return (<CR>). For example, /USR/LOGIN->!<CR> On UNIX, this will result in a UNIX shell prompt being printed. You - 197 - Version 1.10 PDLISP language manual Interfacing to the Operating System are free now to issue any UNIX shell command, and the system will behave as if PDLISP were not present. Upon termination of the session, you should be able exit back to PDLISP as follows: % ^D The actual mechanics of getting to the shell and back again vary from system to system. On MS-DOS (PC-DOS), the system is quite verbose upon being invoked from PDLISP, as follows: /USR/LOGIN->! The IBM Personal Computer DOS Version 3.10 (C)Copyright International Business Machines Corp 1981, 1985 (C)Copyright Microsoft Corp 1981, 1985 C> At this point, you are now in DOS. In order to get back to PDLISP, type "exit" at the DOS command prompt, as follows: C>exit T /USR/LOGIN-> If you move around the O/S directory tree in MS-DOS and then return to PDLISP, you will find upon your next shell escape that you are back in the directory from which PDLISP was booted. PDLISP returns to its own directory so that it can read in its swap file which it sometimes creates to hold some or all of s-expression space during the shell escape. This is not true of PDLISP on UNIX, because it does not need to create a swap file. SHELL CSUBR (STR) or (STR &optional SPACE) Allows calls to the shell (or ccp) of the host operating system. The new process is spawned, and PDLISP waits until the process terminates. After the process terminates, PDLISP resumes execution. This function returns T if the process was executed, and otherwise returns NIL. On operating systems which do not automatically swap processes to disk (such as PC-DOS or MS-DOS), this function takes an optional argument, SPACE. This is the number of bytes - 198 - Version 1.10 PDLISP language manual Interfacing to the Operating System to allocate for the process being executed, and PDLISP will swap out as much of itself as is necessary to provide the requested space. If SPACE is not specified, then a default value is assumed. This default value is 160,000 bytes for MS-DOS and PC-DOS, and may vary for other operating systems; consult the appropriate appendix for more information. - 199 - Version 1.10 PDLISP language manual Storage Management Chapter 17 Storage Management ALLOC CSUBR (SEGTYPE NUMSEGS) Allows the user to manually allocate segments in PDLISP. SEGTYPE is an integer indicating the type of segment(s) to be created, and NUMSEGS is an integer which is interpreted to be the number of segments to be created. If successful, then this function returns the number of segments which have been allocated, but if it runs out of memory or some other allocation fault occurs, it returns a value of 0. The interpretation of SEGTYPE is as follows: integer: SEGMENT TYPE: 0, 1 used internally by system. 2 CODE 3 RNODES (ram-resident s-expression space) 4 DCBBLOCK (directory control blocks) 5 ATOMS (user-defined symbols) 6 LEXATOMS (lexical atoms) 7 HUNKS (used by strings, arrays, and structures) ALLOC is generally used to "tune" a system for a particular memory configuration. GC CSUBR () Invokes the mark-and-sweep garbage collector. After the collection is complete, this function returns an integer which is the number of nodes which are free in allocated memory. If you wish, you can make the garbage collector beep each time that it begins, using the GC_VERBOSITY hook, which is described under the STATUS function. - 200 - Version 1.10 PDLISP language manual Storage Management GETFREE CSUBR () Returns an integer which is the number of free nodes currently on the free-list in allocated memory. MEMMAP CSUBR (&OPTIONAL X) Produces a report of memory usage on the console. The actual contents of this report varies according to the operating system in use; see the appendix corresponding to your situation. - 201 - Version 1.10 PDLISP language manual Storage Management This page intentionally left blank - 202 - Version 1.10 PDLISP language manual Storage Management This page intentionally left blank - 203 - Version 1.10 PDLISP language manual Bibliography Appendix A Bibliography Allen, John [1978] Anatomy of LISP, McGraw-Hill, New York. The most comprehensive, semi-theoretical treatment of the issues which face an implementor of a LISP system. Allen, John [1979] "An Overview of LISP", Byte, Vol 4, No. 8, pg. 10, August 1979. A good introductory tutorial on LISP. Unfortunately, every library which I checked was missing this very popular issue which was a special one on LISP. Charniak, Eugene, and Drew McDermott [1985], Introduction to Artificial Intelligence, published by Addison-Wesley Publishing Company, Inc. A modern introduction to the A.I. field, using examples written in Common LISP. This book is not merely a rewrite of their earlier work, which is described below; that book is about systems programming, or "hacking", whereas this one focuses on "higher level" issues and is suitable for a general introduction to LISP. Charniak, Eugene, C. K. Riesbeck, D. V. McDermott [1980], Artificial Intelligence Programming, published by Lawrence Eribaum Assiciates, Inc. A good, introduction to systems programming in LISP for the advanced A.I. hacker. The examples given in this book are expressed in UCI-LISP, which is unfortunate since that dialect is quite distant from Common LISP, but the text is sufficiently explanatory for the determined reader. Fodero, John K. [1979] "The FRANZ LISP Manual," University of California, Berkeley, California. This document, along with the FRANZ source code, is often distributed by UNIX vendors to Berkely UNIX licensees. - 204 - Version 1.10 PDLISP language manual Bibliography Galley, S. W. and Greg Pfister [1975] The MDL Language, Document SYS.11.01, Laboratory for Computer Science, MIT, Cambridge, Massachusetts, November 1975. A definition of MDL, which, while nearly extinct, contributed materially to modern LISPs, particularly in parameter passing conventions. McCarthy, John., P.W. Abrahams, D.J. Edwards, T.P. Hart, and M.I. Levin, [1965], LISP 1.5 Programmer's Manual, second edition, MIT Press, Cambridge, Massachusetts. A comprehensive manual on the first "stable" LISP dialect by its implementors. Pitman, Kent M. [1983], The Revised MacLISP Manual, MIT/LCR.TR 295, MIT Laboratory for Computer Science, Cambridge, Massachusetts, May 21, 1983, "Saturday Evening Edition." The latest and greatest MacLISP manual. Steele, Guy Lewis, Jr. et al, [1984], COMMON LISP, The Language, Digital Press (Digital Equipment Corporation), order number EY-00031-DP. This is the "working definition" of the Common LISP standard. Steele, Guy Lewis, Jr. and Gerald Jay Sussman [1979] "Compiler Optimization Based on Viewing LAMBDA as RENAME plus GOTO," in Artificial Intelligence: an MIT perspective", volume 2, edited by Patrick H. Winston and Richard H. Brown, pp. 401-431. A re-think of the semantics behind LISP compiler design, with particular emphasis on RABBIT, a compiler for SCHEME, which was an early lexically scoped LISP dialect. Teitelman, Warren [1974] INTERLISP Reference Manual, Xerox Corporation, Palo Alto Research Center, Palo Alto, California, revised 1978. This is both an exhaustive defition of the INTERLISP dialect, as well as series of tutorials on various tools (the BBN structure editor, DWIM, etc) which are supplied with it. - 205 - Version 1.10 PDLISP language manual Bibliography Weinreb, Daniel, and Moon, David, [1981], LISP Machine Manual, Fourth Edition, MIT Artificial Intelligence Lab, Cambridge, Massachusetts, July 1981. This is the authoritative reference on ZETALISP, which, except for dynamic scoping, is extremely similar to Common LISP. This manual is also available from Symbolics, Inc. Weissman, Clark [1967], LISP 1.5 Primer, Dickenson Publishing Company, Inc., Belmont, California. A dated, but comprehensible introduction to LISP. Winston, Patrick H., and Horn, Berthold Klaus Paul. [1984] LISP, Second Edition, Addison-Wesley, Menlo Park, California. A good introductory text on LISP, which uses Common LISP for its examples. - 206 - Version 1.10 PDLISP language manual Bibliography This page intentionally left blank - 207 - Version 1.10 PDLISP language manual Bibliography This page intentionally left blank - 208 - Version 1.10 PDLISP language manual Bibliography This page intentionally left blank - 209 - Version 1.10 PDLISP language manual Bibliography This page intentionally left blank - 210 - Version 1.10 PDLISP language manual PDLISP Error Messages Appendix B PDLISP Error Messages Error messages in PDLISP are printed in two forms, depending upon whether the error was detected within the interpreter, or if it was encountered by a LISP-callable routine. For errors which originate within the interpreter, the name of the routine followed by a set of parenthesis is printed along with an error message. For example: ***> BINDER(): stack overflow. In the above example, a stack overflow was detected in BINDER(), which is a routine which is internal to PDLISP and which is not accessible directly from LISP. After printing out the error message, the system returned to the normal top-level prompt. Errors which are detected in routines which are callable from PDLISP are printed out slightly differently. For example: ***> CAR: arg is atomic. /USR/LOGIN-> Again, after printing out the error message, the system returned to the top-level prompt. Those errors which definitely indicate corruption of the virtual image are noted as being "fatal" or "probably fatal". Corruption of a virtual image could occur because of undetected memory errors or other hardware problems, commission by the user of an error which I did not anticipate, or (heaven forbid!) a bug in PDLISP itself. In all cases where an error might indicate corruption of the current virtual image, one should immediately terminate the current PDLISP session and revert to a virtual image which is known to be good. If you are running PDLISP on a machine which does not have a hardware memory management - 211 - Version 1.10 PDLISP language manual PDLISP Error Messages unit (MS-DOS, PC-DOS, MACINTOSH, etc.) it would probably be a good idea to reboot the entire system. A single bad pointer wandering around inside of such a machine can cause insidiously subtle bugs that are difficult to trace. ***> *: 1st arg is not a number. ***> *: 2nd arg is not a number. ***> +: 1st arg is not a number. ***> +: 2nd arg is not a number. ***> -: bad 2nd arg. All of the above functions expect that all of their arguments be numbers (either integers or floats). Not fatal. ***> <: 1st arg is not a number. ***> <: 2nd arg is not a number. ***> <=: 1st arg is not a number. ***> <=: 2nd arg is not a number. ***> <=: illegal arguments. ***> %: 1st arg is not a number. ***> %: 2nd arg is not a number. All of these functions expect 2 arguments, both of which must be numbers (either integers or floats). Not fatal. ***> ALLOC: 1st argument must be an integer ***> ALLOC: 2nd argument must be an integer ALLOC expects 2 arguments, both of which must be integers. Not fatal. ***> APPEND: non-NIL atomic arg. APPEND doesn't like arguments which are not lists. Not fatal. ***> APPLY: illegal fn. The evaluator attempted to evaluate an expression which had a bad form in its expression slot. Probably not fatal. ***> APPLY: attempted to apply built-in symbol named: <symbol name> The evaluator attempted to apply a built-in constant, such as T or NIL, as a function. This error is usually caused by some mismatched parenthesis in a COND or some other complicated form which causes the evaluator to get lost. Not usually fatal. - 212 - Version 1.10 PDLISP language manual PDLISP Error Messages ***> APPLY: function <function name> is unbound Probably the most common error message in the system, and not fatal. Define the symbol as a function and try again. Not fatal. ***> APPLY: macros not a legal function arg. APPLY cannot apply a function which is defined as a MACRO. Probably not fatal. ***> APPLY: illegal function arg. APPLY was passed a function which was not defined as a LAMBDA, NLAMBDA, CSUBR, CNSUBR, SUBR, or NSUBR. Probably not fatal. ***> BAK_N: arg must be an integer. BAK_N expects to be fed an integer argument which tells it how many frames to display, so give it one. Not fatal. ***> BAK_N: ran out of frames to examine. BAK_N was asked to display X frames on the environment stack, but only Y frames were available, where Y < X. Not fatal. ***> BAKTRCE: bad arg. ***> BAKTRCE: param not an integer. BAKTRCE expects a single parameter, which must be an integer, to tell it what kind of report to generate. Currently, legal values for this parameter are 0 and 1. The following messages are all issued by BINDER(), which is a routine inside of the interpreter which binds parameter lists to their values. ***> BINDER(): initialization of non-&optional param. The system binder found a case where a formal parameter which was not declared as being optional was being initialized to a default value. Not fatal. - 213 - Version 1.10 PDLISP language manual PDLISP Error Messages ***> BINDER(): missing &rest formal parameter. BINDER() expects to find a formal parameter after the &rest keyword in a function declaration. Not fatal. ***> BINDER(): more than 1 &REST formal param. Since a &REST parameter is bound to the rest of the actual parameter list, there is nothing left for a subsequent &REST parameter to be bound to. Delete the extraneous parameter. Not fatal. ***> BINDER(): missing &OPTIONAL formal param. BINDER() expects to find a formal parameter after the &OPTIONAL keyword, so put one in. Not fatal. ***> BINDER(): missing &AUX parameter(s). BINDER() expects to see the name(s) of 1 or more local variables after the &AUX keyword, so put them in. Not fatal. ***> BINDER(): bad formal parameter. BINDER() found a formal parameter which it doesn't like, such as a constant (string, number, or built-in node such as T or NIL). Formal parameters must be symbols. Not fatal. ***> BINDER(): popframe failed. The internal routine which pops the LISP environment detected an inconsistency in the environment stack. Possibly fatal. ***> BINDER(): too few arguments. The call to the routine being interpreted didn't provide enough "actual parameters", or "arguments", to cover all of the non-&OPTIONAL parameters in the function declaration. Not fatal. ***> BINDER(): too many arguments. The call to the routine being interpreted provided too many actual parameters, and they could not be matched. Either change the call or the function declaration. Not fatal. - 214 - Version 1.10 PDLISP language manual PDLISP Error Messages ***> BINDER(): argument stack underflow. Somehow, the environment stack got out of synchronization with the binder. Extremely fatal. ***> BINDER(): bad local variable list. The binder has discovered a fault in an initialized parameter list, such as might be passed to LET. Probably fatal. ***> BLDVVLST(): frame bashed. An internal routine in the interpreter has detected a fault in the environment stack. Probably fatal. ***> BLOCK: fumbled the return. BLOCK was unable to catch a return thrown from somewhere. Probably fatal. ***> BLOCK: popframe failed. BLOCK was unable to pop the environment stack. Probably fatal. ***> BOUNDP: arg must be a symbol. Only symbols can be "bound" or "unbound"; everything else is a constant. Not fatal. ***> CATCH: fumbled the catch CATCH was unable to resume control from a THROW somewhere within its scope. Probably fatal. - 215 - Version 1.10 PDLISP language manual PDLISP Error Messages ***> CAR: arg is atomic. ***> CDR: arg is atomic. ***> CAAR: arg to CAR is atomic. ***> CDAR: arg to CDR is atomic. ***> CADR: arg to CAR is atomic ***> CDDR: arg to 1st CDR is atomic. ***> CAAAR: arg to 1st car is atomic. ***> CAADR: arg to 1st car is atomic. ***> CADAR: arg to 1st CAR is atomic. ***> CADDR: arg to 1st car is atomic. ***> CDAAR: arg to CDR is atomic. ***> CDADR: arg to 1st CDR is atomic. ***> CDDAR: arg to 1st CDR is atomic. ***> CDDDR: arg to 1st CDR is atomic. ***> CADDDR: arg to CAR is atomic. All of these error messages are derivatives of the same error: at some point CAR or CDR was presented with an atomic form as an argument. While some dialects (i.e., MACLISP) permitted such activities, PDLISP is a non-nuclear environment (you can't split an atom in PDLISP). Not fatal. ***> CD: arg not a symbol. CD attempted to change to a directory which is not even a symbol, much less legal. Not fatal by itself. ***> CD: <symbol name> not a directory. CD quite rightfully expects as its argument a symbol which is bound as a directory. Not fatal. ***> COND: illegal form Either the list of COND-pairs or an element of a list of COND-pairs was not a cons-cell (i.e., was atomic). Not fatal. ***> CONS: incorrect number of arguments. CONS, when called from the interpreter, checks to see that it is passed exactly two arguments. Not fatal. - 216 - Version 1.10 PDLISP language manual PDLISP Error Messages ***> DEACTIVE(): illegal tag. Indicates a fault in the mark & sweep garbage collection system. Treat as fatal. ***> DIV: 1st arg is not an integer. ***> DIV: 2nd arg is not an integer. DIV expects both of its arguments to be integers. Not fatal. ***> EVAL: binding error in lambda named: <symbol-name> The binder was unable to match the formal and actual parameter lists for some function bound as a lambda. Usually issued in conjunction with some more specific complaints from the binder. Not fatal. ***> EVAL: binding error in lambda named: ANONYMOUS Same as above, except that the functional part of the form being evaluated did not have a name (i.e., it was "anonymous"). Not fatal. ***> EVAL: lexprs not implemented yet. LEXPR's don't exist in PDLISP yet (some say that they never should). Not fatal. ***> EVAL: binding error in nlambda named: <symbol-name> Usually issued with some specific error message from the binder, and not fatal. ***> EVAL: variable <symbol-name> is unbound. EVAL tried to look up the value of an unbound symbol. Not fatal. ***> EVAL: out of stack space. The control stack collided with the argument stack. This should never happen under Berkeley UNIX, because new stack pages are allocated as needed. If this happens repeatedly on MS-DOS or some other machine which does not have a Memory Management Unit (MMU), then look in the appendix in this manual to see what options are available. Not fatal. - 217 - Version 1.10 PDLISP language manual PDLISP Error Messages ***> EVAL: function tag out of range. The evaluator attempted to evaluate an expression which had a bad form in its function slot. This error is often caused by some mismatched parenthesis in a complicated form, such as a COND. Not usually fatal. ***> EVAL: popframe failed. The internal routine which pops the LISP environment detected an inconsistency in the environment stack. Possibly fatal. ***> EVAL: fumbled the return. Another error message which should never occur. Probably indicates a bashed pointer somewhere, and probably fatal. ***> EVAL: expression has bad tag. EVAL cannot make head or tail out of the expression which it has been asked to evaluate. Probably fatal. ***> EXPLODE: arg not atomic. EXPLODE currently works only with symbols and other atoms. Not fatal. ***> FBOUNDP: arg not a symbol. Only symbols can be bound as functions. Not fatal. ***> FCLOSE: arg must be an integer. FCLOSE expects as its argument a "handle" which corresponds to an i/o stream. Not fatal. ***> FCREATE: argument must be a string. FCREATE expects as its argument a string which is a legal file name for the host operating system. Not fatal. The following error messages are issued by FINDATOM(), which is an internal routine in the reader which looks up symbol names to see if they are already present in the object list. - 218 - Version 1.10 PDLISP language manual PDLISP Error Messages ***> FINDATOM(): idptr argument not a string. FINDATOM() was passed a bad symbol print-name. Probably fatal. ***> FINDATOM(): directory argument not a symbol. FINDATOM() was passed a bad directory argument. Probably fatal, and the directory structure is probably corrupted. Probably fatal. ***> FINDATOM(): <symbol name> is not a directory. ***> FINDATOM(): bad hanger node. ***> FINDATOM(): hanger chain broken. FINDATOM() detected an inconsistency in the linked list which constitutes a directory. Probably fatal. ***> FINDATOM(): bad atom interned. FINDATOM() found an object interned in a directory which is not a valid symbol. Possibly fatal. ***> FINDBF(): hanger node expected. An internal routine which searches along a directory has found an inconsistency. Probably fatal. ***> FLATSIZE(): tag error The routine inside the interpreter which determines the length of the printed representation of an object was handed garbage. Indicates a possibly corrupted virtual image, and possibly fatal. ***> FOPEN: argument must be a string. FOPEN expects a string containing the name of a file to open on the host o/s. Not fatal. ***> FREAD: argument not an integer. FREAD expects as an argument an integer which is the "handle" of the file to be read. Not fatal. ***> FSEEK: 1st arg is not an integer ***> FSEEK: 2nd arg is not an integer ***> FSEEK: 3rd arg is not an integer All of the arguments to FSEEK must be integers; the file i/o system works in terms of "handles", or numbers which correspond to an i/o stream. - 219 - Version 1.10 PDLISP language manual PDLISP Error Messages ***> GENSTRING: illegal &optional arg. If the optional argument to GENSTRING is present, it must be a string. Not fatal. ***> GETCHUNK(): segment descriptor table bashed on entrance. ***> GETCHUNK(): segment table size exceeded. ***> GETCHUNK(): segment type = code. ***> GETCHUNK(): segment type error. The internal routine which allocates chunks of memory has detected an error. In the case of "segment table size exceeded", you have run out of memory. All are fatal. ***> GETMODE: arg not a symbol. Only symbols have access modes. Not fatal. ***> GLOBAL: attempted to set mode of lexical atom. Only dynamic symbols can be global, not fatal. ***> GLOBAL: arg not a symbol. Obviously, only symbols can be "global" or "local," since symbols are the only things which are interned on the object list. Everything else is a constant. ***> GO: attempted jump to non-atomic label. ***> GO: unable to throw control. ***> GO: unable to match go label. GO detected an anomaly in the environment stack. Probably fatal. ***> IMPLODE-TO-STRING: element of list not a symbol. IMPLODE-TO-STRING expects a list of symbols. This function may be extended in a future release to implode other things. ***> INITLISP(): unable to read the file 'pdinit.l' The interpreter expects to find the file "pdinit.l" in the current directory on boot-up unless the name of a virtual image was given on the command line. - 220 - Version 1.10 PDLISP language manual PDLISP Error Messages ***> INITPTR(): idptr illegal. ***> INITPTR(): oblist not atomic. ***> INITPTR(): oblist not a directory. ***> INITPTR(): dcb corrupted. ***> INITPTR(): bad dcb link in directory. ***> INITPTR(): directory bashed. INITPTR() is a routine deep inside the reader. Any complaints from it indicate that something is seriously wrong with the current virtual image. Consider these messages fatal. ***> INITSTOR: unable to reset memory. The internal routine which initializes memory was unable to get cooperation from the operating system. Probably fatal. The following messages are issued by INTERN(), which is the routine inside the reader which puts symbols in the directory system. ***> INTERN(): id not a string. INTERN() was asked to intern an object with an invalid print-name. Not fatal by itself. ***> INTERN(): id has zero length. INTERN() was asked to intern an object with a null string ("") as its print-name. Not fatal by itself. ***> INTERN(): oblist argument not a legal symbol. INTERN() was asked to intern an object on a non-existant directory. Not fatal by itself. ***> INTERN(): illegal position argument. ***> INTERN(): invalid atomic position argument. ***> INTERN(): <symbol name> is not a directory. The directory control block system got confused. Treat current virtual image with suspicion. ***> LBREAK(): fell through setjmp(). Indicates that the compiler which I used to compile the interpreter is broken. Please call me. Definitely fatal. - 221 - Version 1.10 PDLISP language manual PDLISP Error Messages ***> LET or LET*: bad param list. LET or LET* could not process an initialized variable list, which could be because it is poorly formed. Not fatal. ***> LET or LET*: popframe failed. LET or LET* was unable to pop the environment stack after the body of the LET was executed. Probably fatal. ***> LEXBIND(): arg not a symbol. The internal routine which retrieves the lexical binding of a symbol was passed an illegal argument. This should never happen, and is probably fatal. ***> LEXBIND(): arg not a dynamic symbol. The internal routine which retrieves the lexical binding of a symbol was passed an illegal argument. Probably fatal. ***> LEXTRAN(): illegal arg. The internal routine which translates a lexical reference was passed a bad argument. Probably fatal. ***> LEXTRAN(): broken lexical link. The internal routine which translates a lexical reference detected a broken link in the lexical binding system. Probably fatal, and the object list is probably messed up. ***> LOAD or LOADV: argument <arg> is not a string. ***> LOAD or LOADV: argument not atomic. LOAD and LOADV expect as their argument a string specifying the name of a file to be read in. Not fatal. ***> LSTCMP(): illegal 1st arg ***> LSTCMP(): illegal 2nd arg The internal routine which compares strings was handed garbage. Probably fatal. ***> LSTRLEN(): bad argument. The internal routine which finds the length of a LISP string was handed something which is not a string. Fatal. - 222 - Version 1.10 PDLISP language manual PDLISP Error Messages ***> MACXPND: arg not a macro. The macro expander tried to expand something which was not a macro. ***> MACXPND: arg not a cons. MACXPND was called from some LISP program with an argument which was not a cons cell. Not usually fatal. ***> MACXPND: attempted to access functional value of built-in symbol named: <symbol name> MACXPND tried to expand a built-in constant, such as T or NIL, which obviously cannot be defined as a MACRO. Not fatal. ***> MACXPND: arg not a macro. MACXPND was called from a LISP function and tried to expand something which was not defined as a macro. Not fatal. ***> MARK(): free atom or node list corrupted. ***> MARK(): found unmarked system atom. ***> MARK(): found illegal tag value. The mark routine in the mark and sweep garbage collector found an inconsistency in the virtual image. Treat all of these as fatal, and please let me know about them. ***> MARKESTK(): environment stack probably bashed. The part of the mark and sweep garbage collector which marks the environment stack found an inconsistency. Probably fatal. ***> MD: arg not a symbol. MD attempted to make an object which is not a symbol (such as a number or a string) into a directory. Shame on you! Not fatal. ***> MD: arg not a directory. Same as above. - 223 - Version 1.10 PDLISP language manual PDLISP Error Messages ***> MOD: 1st arg is not an integer. ***> MOD: 2nd arg is not an integer. MOD expects 2 arguments, and both must be integers. ***> SHELL: unable to create swap file. ***> SHELL: unable to read swap file. Either of these errors means that the operating system was unable to perform a disk operation which SHELL requested. On operating systems which do not automatically swap programs in and out of RAM, such as MS-DOS, PDLISP creates a temporary file on the disk, if necessary. This file is called PDLISP.SWP. One possible explanation for a failure of this kind is a disk which is nearly full. Not fatal, but you won't be able to exec anything. ***> SHELL: 2nd arg must be an integer. SHELL expects 1 or 2 arguments, a string to be executed, and (optionally, on MS-DOS and some other environments) an integer telling it how much ram to allocate, in bytes. Not fatal. ***> PATHSTR: arg is not a symbol. ***> PATHLST: arg not a symbol. Both of these functions expect symbols as arguments. Not fatal. ***> PATHNME(): arg not a legal symbol. ***> PATHNME(): argument is not legal. PATHNME was passed an argument which is probably not a symbol or which is otherwise unacceptible. Not fatal. ***> PATHSTR: arg not a symbol. PATHSTR was passed an illegal argument. Not fatal. ***> PLIST: argument must be a symbol. Only symbols have property lists. Not fatal. ***> POPNODE(): out of s-expression space. ***> POPDCB(): out of memory space. Either of the above error messages indicate that you have run out of memory. Disasters like this can be avoided by using the MEMMAP command. Fatal. - 224 - Version 1.10 PDLISP language manual PDLISP Error Messages ***> POPLATM(): free-list ptr bashed. ***> POPLATOM(): free-list corrupted. ***> POPATOM(): dynamic atom free-list ptr bashed. ***> POPATOM(): dynamic atom free-list corrupted. ***> POPNODE(): s-expression free-list bashed. ***> POPNODE(): node free-list ptr bashed. ***> POPNODE(): free node list corrupted. ***> POPNODE(): non-nil car of node on free-list ***> POPDCB(): free dcb list probably damaged. All of the above error messages indicate that something is seriously wrong with the memory allocation system, and all are fatal. ***> POPFRAME(): bad frame count ***> POPFRAME(): chkestk failed on entrance. ***> POPFRAME(): chkestk failed on exit. ***> POPFRAME(): empty environment stack. ***> POPFRAME(): stack probably bashed. The above three messages indicate that somehow the control stack got bashed. This could be due to a bad pointer in the virtual image somewhere, or, in some environments, the bad behavior of some other program in the system which wrote over PDLISP's stack. Consider this error fatal. ***> POPPROP: 1st arg must be a symbol. Only symbols have property lists. Not fatal. ***> POPUP(): bad target frame. The internal routine which pops the environment stack for THROW and ERR has detected a bad frame. Since this probably means that the control stack has been bashed also, you're dead. ***> PRNTATOM(): arg not atomic. Probably not fatal. ***> PRNTRSWD(): tag out of range. Probably fatal. - 225 - Version 1.10 PDLISP language manual PDLISP Error Messages ***> PSHFRAME(): chkestk() failed on entrance. ***> PSHFRAME(): frameptr not legal ***> PSHFRAME(): chkestk() failed on exit. The system routine which establishes new environments has discovered an inconsistency in the environment stack. Probably fatal. ***> PUTD: 1st arg not a symbol. PUTD expects as its first argument a symbol whose function cell will be altered; nothing else has a function cell. Not fatal. ***> PUTPROP or REMPROP: invalid indicator. Indicators cannot be built-in symbols, such as T or NIL. Not fatal. The following messages are from the reader, which reads s-expressions from the disk or the console. Usually, the reader outputs the line in which the error occurred, and underneath the offending character or token outputs a carot ("^"). None of these errors are fatal. ***> READER: error in input stream. This message is printed out in addition to other error messages. ***> READER: premature end of input in file: <file name> The reader encountered the end of a file while it was in the middle of reading an s-expression. ***> READER: tried to access functional value of built-in symbol named: <symbol-name> The reader was instructed to apply a function at read-time, but the named symbol currently has no function binding. ***> READER: exceeded maximum lexical level. Currently, the reader permits 255 lexical levels. - 226 - Version 1.10 PDLISP language manual PDLISP Error Messages ***> READER: atom or left paren expected. ***> READER: atom, left or right paren expected. ***> READER: right paren expected. The reader was in the midst of parsing an s-expression, and expected something different than it encountered. ***> READER: undefined sharp-sign macro. A sharp-sign macro which has not been implemented has been processed. ***> READER: identifier or string too long. Currently, the maximum length for a string or identifier is 255 characters, and cannot cross lines. ***> READER: invalid LET or LET* symbol. The reader expected a lexically bound symbol, which cannot be named one of the reserved words described in the first chapter of this manual. ***> REMPROP: 1st arg must be a symbol. Only symbols have property lists. Not fatal. ***> RESTORE: arg must be a string. RESTORE expects a string which it interprets to be the name of a virtual image file to restore. Not fatal. ***> RESTORE: environment stack probably bashed. After restoring a virtual image, RESTORE discovered an inconsistency in the environment stack. Probably fatal. ***> RETURN: unable to find enclosing block. Means just what it says. Look in your code to see if there really is a return without an enclosing block; if such is the case, then this error is probably not fatal. ***> RM or RMQ: bad argument. ***> RM or RMQ: <symbol name> is a directory. ***> RM or RMQ: <symbol name> not in current directory. RM and RMQ expect as arguments symbols which are in the current directory and which are not directories themselves. In order to remove directories, use RMDIR or RMDIRQ. Not fatal. - 227 - Version 1.10 PDLISP language manual PDLISP Error Messages ***> RPATHNME(): arg not a symbol. RPATHNME() was passed an argument which was not a symbol, not fatal. ***> RPLACA: 1st arg must not be atomic. RPLACA expects a list or cons-cell as its first argument, since atoms don't have car fields to alter. Not fatal. ***> RPLACD: 1st arg is atomic. RPLACD expects a list or cons-cell as its first argument. Not fatal. ***> SAVE: arg must be a string. SAVE expects as its argument a string which specifies the name of a file on the host operating system to which the virtual image will be written. Not fatal. ***> scandir(): 1st arg not a directory. One of the internal routines inside the reader was handed garbage. Probably fatal. ***> scan(): directory named <directory name> does not exist. The reader attempted to read a symbol name containing a segment which should have been a directory, but which was not. All of the path-name segments except the last segment must be directories. For example, if we were to specify the path-name /FOO/BAR/BAZ, FOO and BAR are required to be directories. Not fatal. ***> scan(): path name segment does not exist. The reader attempted to read a symbol name containing a segment which does not exist. Recall that the reader only interns new symbols in the current directory. Not fatal. ***> scanseg(): illegal directory argument. The reader attempted to parse a path name containing a segment which is not a symbol (only symbols can be directories). Not fatal. - 228 - Version 1.10 PDLISP language manual PDLISP Error Messages ***> SETATOM(): formal parameter is not a symbol. The part of the interpreter which sets a symbol to a value was handed a bad argument (such as a constant). Probably not fatal. ***> SETMODE: 1st arg not a symbol. ***> SETMODE: 2nd arg not an integer. SETMODE expects 2 arguments: a symbol name and an integer to set it to. Not fatal. ***> SETPLIST: argument must be a symbol. Only symbols can have property lists. Not fatal. ***> SRMDIR: the symbol <symbol name> not a directory. SRMDIR only works on directories. Use RM or RMQ for everything else. Not fatal. ***> SRMDIR: symbol <symbol name> not in current directory. Any directories to be removed must be an object which is interned in the current directory. Not fatal. ***> SRMDIR: can't remove root. SRMDIR is incapable of removing the root directory, since there are easier ways of committing suicide which don't require a computer. Not fatal. ***> SRMDIR: argument not a symbol. All directories are symbols. Not fatal. ***> STATUS: 1st arg must be an integer. ***> STATUS: 1st arg must be >= 0 ***> STATUS: 2nd arg must be a symbol. ***> STATUS: 2nd arg must be an integer. ***> STATUS: 2nd arg must be a flonum. ***> STATUS: 2nd arg must be atomic. ***> STATUS: unimplemented case. STATUS does some type-checking of its arguments. The first argument must always be an integer >= 0; the required type of the second argument depends upon the value of the first argument. Not fatal. - 229 - Version 1.10 PDLISP language manual PDLISP Error Messages ***> STRCAT: arg is not a string. STRCAT expects all of its arguments to be strings. Not fatal. ***> STRLEN: arg is not a string. STRLEN expects its argument to be a string. Not fatal. ***> SWEEP(): found system node in s-expr space. ***> SWEEP(): found atom with bad tag. ***> SWEEP(): found bad dynamic atom variant. ***> SWEEP(): found lexical atom with bad tag. ***> SWEEP(): found bad lexical atom variant. The sweep routine in the mark and sweep garbage collector found an anomaly in the virtual image. Treat all of these errors as fatal. ***> SYMBOL-NAME: arg not a symbol. SYMBOL-NAME only works with symbols. Not fatal. ***> SYSGPROP(): 1st arg must be a symbol. The system routine which retrieves property-value pairs from a property list requires a symbol as its first argument. Not fatal. ***> SYSNCONC(): 1st arg atomic. ***> SYSNCONC(): 1st arg was NIL The system NCONC function, which is called from NCONC and other places, wants all of it arguments except for the last one to be non-nil lists. This is because it bends the CDR of the last cons cell of each argument to point to the next one, and atoms don't have CDR fields. Not usually fatal. ***> SYSPPROP(): 1st arg must be a symbol. The system routine which puts property-value pairs on property lists got an argument which was not a symbol. Probably not fatal. - 230 - Version 1.10 PDLISP language manual PDLISP Error Messages ***> TAGBODY: binding error. TAGBODY had to abort because of a binding error. Not fatal. ***> TAGBODY: pc is atomic. TAGBODY attemped to execute an atomic statement in a tag body. Possibly fatal. ***> TAGBODY: popframe() failed TAGBODY was unable to pop the environment stack upon exit. Probably fatal. ***> TAGBODY: fumbled a GO. TAGBODY was unable to execute a GO statement. Probably fatal. ***> TAGBODY(): tag body corrupted. TAGBODY detected a fault in a tag body. Probably fatal. ***> THROW: unable to throw. ***> THROW: unable to match throw label. THROW was unable to throw contol to the specified label. Possible fatal. ***> UPDTDCB(): dcb corrupted. ***> UPDTDCB(): bad directory link. ***> UPDTDCB(): object list arg not atomic. ***> UPDTDCB(): object list arg not a directory. ***> UPDTDCB(): bad position argument. ***> UPDTDCB(): error in object list. Any of these messages indicate the the directory control block system is terribly confused. All are fatal. ***> ZEROP: argument is not numeric. ZEROP works on numbers. Not fatal. - 231 - Version 1.10 PDLISP language manual PDLISP Error Messages This page intentionally left blank - 232 - Version 1.10 PDLISP language manual PDLISP Error Messages This page intentionally left blank - 233 - Version 1.10 PDLISP language manual Running PDLISP Under MS-DOS & PC-DOS Appendix C Running PDLISP Under MS-DOS & PC-DOS 17.1 Packing List Here is an explanation of the files on the distribution diskette: pdlisp.exe - the actual LISP interpreter pdload.exe - loads the LISP interpreter into ram pdinit.l - the LISP initialization file bakquote.l - the back-quote macro dirlib.l - library of directory functions debug.l - misc debugging functions examples.l - misc demonstration functions fmtio.l - formatted i/o, including the pretty-printer led.l - the PDLISP structure editor misc.l - miscellaneous support functions rudolf.l - property list demonstration test.l - a small test suite 17.2 Getting Started The following instructions assume that you have a hard disk; instructions for floppy-based systems follow. Before attempting to run PDLISP, you should be familiar with the DOS DIR, COPY, FORMAT, and DISKCOPY commands; this information is available in the DOS which should have been provided with your system. You should also be familiar with some sort of text editor - the following is a list of the editors which have successfully been used with PDLISP, but any should work: - 234 - Version 1.10 PDLISP language manual Running PDLISP Under MS-DOS & PC-DOS MINCE (Mark of the Unicorn) SEE (C-WARE) Wordstar (Micropro International) VEDIT (Compuview) EDLIN (Provided with DOS) step 1: Prepare your system by removing any ram-disks which you may have which are located in main memory. PDLISP is pretty memory hungry, but you can run comfortably in a 512k system. With less memory, you may still be able to run the interpreter, but you may not be able to load all of the utilities. step 2: Add/Modify the following lines in your CONFIG.SYS file: FILES=20 BUFFERS=12 step 3: Put all of the above files in the same directory. step 4: Type "PDLOAD" After about a minute, the "/USR/LOGIN->" prompt should come up. If the prompt did not come up, or if you get a error message, see the error message section for MS-DOS, below. step 5: At the prompt, save the virtual image on disk, as shown below: /USR/LOGIN->(save "pd.img") <CR> step 6: After a bit of intensive disk activity, the prompt should come back up. The next time that you wish to run PDLISP, type "PDLOAD pd.img" at the DOS command level to restore the virtual image which you saved in step 4. The loading process should only take a few seconds, and then the "/USR/LOGIN->" prompt should come up. - 235 - Version 1.10 PDLISP language manual Running PDLISP Under MS-DOS & PC-DOS 17.3 Running PDLISP on a Floppy-Only System step 1: Format a blank disk with the "/S" option, which puts a copy of MS-DOS on it, so that you can boot from it. Label the new disk "PDLISP running disk" with a felt- tipped pen. step 2: Format another blank disk without using the "/S" option, and label this disk the "PDLISP virtual image disk" with a felt-tipped pen. step 3: Copy all of the files on the PDLISP distribution disk onto the PDLISP running disk, using the DOS "COPY" command. Put your original PDLISP master diskette in a safe place. Never copy anything onto the master diskette. step 4: Copy your existing CONFIG.SYS file over to the running diskette, and add or modify the following lines: FILES=20 BUFFERS=12 step 5: Check how much room you have on the new disk. If your favorite text editor is relatively small, transfer it to this disk. Otherwise, you will have to put it on another floppy. Be sure that after everything is on the running disk, that you have at least 96k bytes of free space. PDLISP uses this space to swap part its the memory image out to disk when executing the text editor and other programs. step 6: Put the running diskette into drive "A", and boot from it (hit control-alt-delete). Put the virtual image diskette in drive "B" if you have a two-drive machine. Use the DOS "DIR" command to examine the contents of both floppies to insure that both are good and contain the files which you want. The virtual image - 236 - Version 1.10 PDLISP language manual Running PDLISP Under MS-DOS & PC-DOS diskette should be empty at this time. Take care not to remove the running diskette from drive "A" unless specifically asked to by MS-DOS or PDLISP; MS-DOS has a nasty habit of bashing directories on diskettes which have been inserted without its knowledge. step 7: Type "PDLOAD". After about a minute, the "/USR/LOGIN->" prompt should come up. If the prompt did not come up, or if you get a error message, see the error message section for MS-DOS, below. step 8: At the prompt, save the virtual image on disk, as shown below: /USR/LOGIN->(save "b:pd.img") <CR> step 9: After a bit of intensive disk activity, the prompt should come back up. The next time that you wish to run PDLISP, type "PDLOAD b:pd.img" at the DOS command level to restore the virtual image which you saved in step 4. The loading process should only take a few seconds, and then the "/USR/LOGIN->" prompt should come up. 17.4 Editing of Initialization Files If you should wish to edit any of the initialization files (i.e., any of the .L files in the packing list), then you should reconstruct the virtual image, instead of just reading them in after restoring another virtual image. That is, invoke PDLISP again by typing: PDLOAD at the operating system prompt. - 237 - Version 1.10 PDLISP language manual Running PDLISP Under MS-DOS & PC-DOS 17.5 Error Messages on MS-DOS Format of error messages for MS-DOS is identical to the format of other error messages. Messages peculiar to MS-DOS are: ***> clrspace(): prstmem() has not been called. The part of the interpreter which clears out space for SHELL is hopelessly confused. Fatal. ***> longjmp(): bad checksum in environment block. ***> longjmp(): bad stack pointer. An internal routine which does the final transfer of control for THROW and ERR has detected a fault in the stack. Fatal. ***> mark(): out of stack space. The mark routine in the mark & sweep garbage collector has exhausted the stack. Fatal. ***> mark(): found unmarked system atom. ***> mark(): free atom or node list corrupted. ***> mark(): found unmarked system atom. ***> mark(): found illegal tag value. All of these error messages indicate that the mark routine in the mark & sweep garbage collector found an inconsistency in the virtual image. All of these errors are usually fatal. Please let me know if any of these errors occur, since it is possible that it is my fault. ***> SHELL: can't create swap file. For some reason, SHELL can't get DOS to create a swap file. The usual cause of this error is that there is not enough room on the disk. Possibly fatal if the DOS is broken. ***> palloc(): prstmem() has not been called. The memory allocator inside the interpreter is confused. Treat as fatal. - 238 - Version 1.10 PDLISP language manual Running PDLISP Under MS-DOS & PC-DOS ***> prstmem(): error returned from DOS The memory allocator inside the interpreter was unable to get DOS to cooperate. This is indicative of a trashed memory image, or that DOS is broken. Treat as fatal, and reboot. ***> RESTORE: cannot open file. RESTORE could not find the virtual image file specified. Not fatal. ***> RESTORE: bad pointer, cannot reconstruct. ***> RESTORE: bad tag in node. ***> RESTORE: fell through rstdseg() in restore() ***> RESTORE: illegal segment tag. RESTORE has detected a fault in the memory image being restored. See the notes below on restrictions of transfer of virtual image files between machines under MS-DOS. Fatal. ***> SAVE: unable to create the file <file name> SAVE could not create the virtual image file. Perhaps the file name you gave it was illegal under MS-DOS? Not fatal. ***> SAVE: error writing out data segment. ***> SAVE: unable to write out stack segment. ***> SAVE: unable to write out s-expression space. SAVE was unable to write out the virtual image, possibly because not enough room existed on the disk. Not fatal. ***> swpspace(): unable to delete swap file. The swapper was unable to remove the temporary file which it created. Possibly fatal, and indicates that something about DOS is flakey. ***> unable to allocate RAM for segment. The memory allocator was unable to allocate memory. Possibly fatal. - 239 - Version 1.10 PDLISP language manual Running PDLISP Under MS-DOS & PC-DOS ***> PDLISP.EXE: must run PDLOAD.EXE first! PDLISP.EXE cannot be run by itself; run PDLOAD.EXE with PDLISP.EXE in the same directory, and PDLOAD.EXE will automatically load PDLISP.EXE into memory and execute it. Fatal. ***> PDLOAD: memory control blocks bashed, or not enough RAM. ***> PDLOAD: load address too high. aborting... ***> PDLOAD: unable to allocate enough RAM. All of these messages indicate that something is wrong with the initial memory configuration, and that PDLOAD is unable to set up memory properly. The first message indicates that you either don't have enough RAM (512k recommended), or that something was wrong with the DOS memory allocator. Try rebooting and see if that corrects the problem. The second message indicates that you have too much junk in memory before running PDLOAD. At the current time, PDLOAD attempts to locate PDLISP at 96k (decimal). This means that the DOS, any device drivers you may have, and PDLOAD must fit beneath 96k. Things that should be thrown out include PROKEY and SIDEKICK type prorams, since they bump the load address up. I am working on a command-line switch to allow selection of the load address at run-time. If you are unable to get PDLISP to work after throwing everything non-essential out, give me a call, and I will send you out an early release of the command-line switch version. The last error message simply means that you haven't got enough RAM, or at least that DOS doesn't think that you have enough. If you have a PC or clone, check that the switches on the motherboard correspond to the actual amount of RAM in the machine. Also, try rebooting, and see if that cures the problem. ***> xtlt(): bad pointer offset. The internal routine which translates pointers after a RESTORE found a pointer which does not appear to be legal. Probably fatal. - 240 - Version 1.10 PDLISP language manual Running PDLISP Under MS-DOS & PC-DOS This page intentionally left blank - 241 - Version 1.10 PDLISP language manual Running PDLISP Under MS-DOS & PC-DOS 17.6 Peculiarities Since MS-DOS runs in an environment which does not have a memory management unit (MMU), PDLISP has a few restrictions as to its operation concerning initial memory configuration, and the restoration of virtual images. For MS-DOS, PDLISP is designed to load at a fixed address in RAM. The program which accomplishes this is the loader, PDLOAD.EXE. After initial check-out of the environment, PDLOAD.EXE loads in the PDLISP kernel (comprising the file PDLISP.EXE). Some restrictions apply concerning transfer of virtual images between machines. For a machine to be able to boot up a virtual image all of the following must be true: (1) The virtual image must have been created using the same version of the interpreter as the one under which the image is being restored. So, if the image file was created using v1.0, then it can only be restored using v1.0. (2) The load addresses of the two interpreters must be the same. Currently, PDLOAD.EXE always locates PDLISP.EXE at 96k(decimal). We're planning to implement a command-line switch to enable the user to specify the load address. (3) The machine attempting to restore the virtual image must have as much memory as the one which created the image. I will probably be able to soften this requirement in a future release, as long as the machine doing the RESTORE has enough RAM for all of the allocated segments of the image. - 242 - Version 1.10 PDLISP language manual Running PDLISP Under MS-DOS & PC-DOS 17.7 Memory Configuration under MS-DOS The following is a memory map of the way that PDLOAD sets up memory: ------------------------- | DOS loader | ------------------------- <------ 1600 bytes below top of RAM | HEAP 3 (grows down) | | | | | | | | | | HEAP 1 (grows up) | ------------------------- <------ STACKBASE + 64k | control stack | | (grows down) | | | | | | protection stack | | (grows upwards) | ------------------------- <------ STACKBASE (96k + kernel size) | | | PDLISP kernel | | | ------------------------- <------ load address (typically 96k) | communication area | ------------------------- | | | | | HEAP 2 (grows up) | ------------------------- <------ approx 12k above PSP of loader | | | PDLOAD loader | | | ------------------------- <------ PSP of PDLOAD.EXE | | | DOS kernel | | | ------------------------- - 243 - Version 1.10 PDLISP language manual Running PDLISP Under MS-DOS & PC-DOS From the bottom up, we have the following regions in memory: At the base of ram is the DOS kernel and whatever programs and device drivers have been loaded by the DOS, including those which terminate with a "terminate and stay resident" call. Print spoolers and "desktop" utilities fit into this category. Next, we have PDLOAD.EXE, which is the first Cybermetrics program to get control. It allocates memory for PDLISP.EXE, which is the PDLISP kernel, and sets up memory configuration information in the communication area, which resides just beneath the PSP (program segment prefix) of PDLISP.EXE. The communication area is described below. After loading and setting up this information, PDLOAD loads and executes PDLISP.EXE using the DOS exec call. When PDLISP.EXE terminates execution, PDLOAD terminates also, passing a termination code back to DOS. Above PDLOAD.EXE and the communication area, we have HEAP2, which uses up the "gap" between PDLOAD and PDLISP. This heap may or may not exist, depending upon the size of the gap. Next comes the "communication area", which is used for communication between the loader and the interpreter kernel. Its contents can be examined using the MEMMAP function. PDLISP.EXE, the interpreter kernel, is loaded next. Its base address, also called its PSP (for "Program Segment Prefix") is normally 96k decimal. Above the PDLISP kernel itself are two stacks which run towards each other. The stack which runs up is called the "protection stack", because it is used to protect intermediate results from the mark & sweep garbage collector. The stack which runs down is the control stack which is used by the kernel itself. The "environment stack", which can be examined by the various BAKTRACE-type functions is embedded inside this stack for efficiency reasons. Normally, under MS-DOS, the total space for this combined stack area is 64k bytes. Next comes HEAP1, also called the "primary heap." All non-atomic nodes are allocated from this heap. This heap is allocated in 4k-byte "chunks", growing upwards. - 244 - Version 1.10 PDLISP language manual Running PDLISP Under MS-DOS & PC-DOS Finally, HEAP3 is located just below the MS-DOS loader (used by the MS-DOS EXEC call). This heap is really a continuation of HEAP2, in that the same kinds of objects (symbols, arrays, and miscellaneous objects) are allocated from HEAP2 and HEAP3. The following function description is unique to MS-DOS: MEMMAP CSUBR (&OPTIONAL X) Produces a report of memory usage on the console. Two report formats are provided; if X is absent or not EQL to 1, then a summary report is generated, containing general information as to the current memory configuration. If X is present and EQ to 1, then all of the information in the summary report is provided as well as a map of each memory "segment". Segments are 4k-byte blocks of memory which are designated as described under the description of the ALLOC function. - 245 - Version 1.10 PDLISP language manual Running PDLISP Under MS-DOS & PC-DOS This page intentionally left blank - 246 - Version 1.10 PDLISP language manual Running PDLISP Under MS-DOS & PC-DOS This page intentionally left blank - 247 - Version 1.10 PDLISP language manual Running PDLISP Under UNIX Appendix D Running PDLISP Under UNIX This section will be added when PDLISP is released for UNIX. - 248 - Version 1.10 PDLISP language manual Running PDLISP Under UNIX This page intentionally left blank - 249 - Version 1.10 PDLISP language manual Running PDLISP Under UNIX This page intentionally left blank - 250 - Version 1.10 PDLISP language manual Running PDLISP Under UNIX This page intentionally left blank - 251 - Version 1.10 PDLISP language manual Running PDLISP Under UNIX This page intentionally left blank - 252 - Version 1.10 PDLISP language manual LISP Glossary Appendix E LISP Glossary ATOM - either a symbol, string, or number. AUTOMAGICALLY - when a program behaves in an obvious way, but its implementation is not obvious or trivial. As in, "When you change a number in window A, the corresponding result in window B automagically changes." BINDING - The mechanism by which variable names are associated with their values. Most LISPs are characterized by having "dynamic binding", which means that this association can change during run-time, as opposed to languages which have "static binding", where the association is fixed at compile-time. C, Pascal, and PL/1 are examples of languages which utilize static binding. PDLISP (and Common LISP) utilize both static and dynamic binding. This machanism is often called "scoping". See Allen[1978] for more info. BRIEFCASE (verb or noun) - To cause to magically appear in one's briefcase. As in, "I don't know what happened, this gallium arsenide 68020 just appeared in my briefcase one day," or, "He briefcased a VAX 11/780." CAR and CDR - (1) Mnemonics dating back to the earliest LISP implementation on IBM equipment. Each non-atomic node consisted of two parts, which conveniently resided in one machine word. CAR and CDR were assembler mnemonics which corresponded to machine instructions to extract these parts of a word. CAR stands for "Contents of Address part of Register", and CDR stands for "Contents of Decrement part of Register." (2) to proceed to the next item on an agenda. COMMON LISP - A new dialect of LISP which is supposed to reconcile the various dialects (FRANZ, MACLISP, INTERLISP, etc) of modern LISP by defining a subset which all of the MACLISP decendants have in common. Time will tell if this effort is to be successful. - 253 - Version 1.10 PDLISP language manual LISP Glossary CRUFTY - Put together in a slovenly or unsystematic way. Some people spell this word as "KRUFTY". ENVIRONMENT - The term used in LISP to describe the current state of the virtual machine. In particular, this term is often used to refer to the current binding environment. See Allen[1978] and Baker[1982] for more info. ENVIRONMENT FILE - A text file which, by being read in, allows the host interpreter to emulate another LISP dialect. For example, one might load an environment file into a Franz LISP interpreter to emulate MacLISP. See the newsletter ("/SYS/NEWS") for more information on environment files which are available for PDLISP. EVAL-LISP - A type of LISP interpreter which does not quote its top-level arguments. PDLISP, as well as most other modern LISP dialects, are EVAL-LISPS. EVAL-QUOTE LISP - a now largely extinct LISP dialect which quoted its top-level arguments. See Weissman [1967] for an example of an eval-quote environment. EXPR - A function type in MACLISP which is equivalent to LAMBDA in PDLISP and most other LISPs. FEXPR - A function type in MACLISP which is equivalent to NLAMBDA in PDLISP and most other LISPs. FIXNUM - equivalent to INTEGER in Common LISP and PDLISP. Before Common, all LISPs called "integers" "fixnums". FLOAT - a floating point number. FLONUM - equivalent to FLOAT in Common Lisp and PDLISP. Before Common, most LISPs called "floats" "flonums". FOO - the first meta-syntactic variable in the meta-language in which all LISP manuals are written. The second and third meta-syntactic variables are BAR and BAZ. FORM - an s-expression which can be evaluated. FRANZ LISP - a LISP interpreter on UNIX which originated from UC Berkeley and Carnegie-Mellon. Franz LISP is a direct descendant of Harvard PDP-11 LISP, but Franz LISP has evolved towards MacLISP and LISP Machine LISP. HACKER - (1) One who constructs furniture with an axe. - 254 - Version 1.10 PDLISP language manual LISP Glossary (2) A programmer or engineer whose enthusiasm for his work enables him to transcend difficult obstacles. (3) A programmer who has acquired an expert level of proficiency in a particular language, operating system, or set of programs, as in "He is a real LISP hacker." (4) A malicious prankster who has a preference for penetrating security in time-sharing systems, as in "We put a gateway computer in to keep out hackers." HYPERWARE - software which exists exclusively in the minds of some marketing executives. INTERLISP - One of the principle dialects of LISP, developed at Xerox Palo Alto Research Center (called PARC). INTERLISP is marked by several interesting characteristics: (1) Programs are almost always dealt with in s-expression space, and heavy usage is made of structure editors or similar tools. This contrasts heavily with the MACLISP philosophy of viewing programs as textual entities off on disk in a file. (2) Scoping is dynamic, which ties in with (1), above. (3) DWIM, which stands for "Do What I Mean" acts as a "programmer's apprentice" and automatically corrects programming errors. INTERN - to place an object on the object list. LAMBDA - a type of function binding in which the arguments to the function are automatically evaluated when the function is entered. see NLAMBDA, EXPR, FEXPR. MDL - pronounced "muddle." One of the more interesting LISP offshoots, developed at M.I.T., which was marked by (among other things) unusual parameter-passing conventions. These conventions, including &optional, &rest, and &aux parameters, later found their way into LISP Machine LISP and (much later) PDLISP. Note - some people consider MACLISP to be an offshoot of MDL, instead of the other way around. MUNG - stands for "Messed Up until No Good." NOWARE - software which has passed through the stages of VAPORWARE and HYPERWARE, and has arrived into the hands of the customer. - 255 - Version 1.10 PDLISP language manual LISP Glossary NLAMBDA - type of function binding in which the arguments to the function are not evaluated. For example, if F were defined to be an NLAMBDA of 2 arguments, A and B, then A and B would not be evaluated automatically before the code for F was executed. See LAMBDA, EXPR, FEXPR. READER - The part of the LISP interpreter which reads s-expressions in from the console, disk, or a string. Internment of symbols in the object list takes place at this time. SCREEN EDITOR - A type of editor which displays the object to be edited on a terminal, and which allows the user to interactively "move around" inside the object being edited via keyboard strokes, a mouse, or some other "pointing device." The object being edited may reside on disk in a text file, or it may be an object internal to the LISP virtual image. The most popular editor in the LISP world is probably EMACS, which was written in TECO, at MIT. TECO, by the way, is easily one of the worst languages ever developed, at least in terms of readability, and this may explain why the MIT community was driven to develop EMACS. EMACS has spawned a number of derivatives in a variety of operating system environments, including CCA and GOSLING EMACS on UNIX, and MINCE on CP/M and MS-DOS (from Mark of the Unicorn). SPECIAL FORM - a function which does not follow the usual rules for evaluation which are standard for LAMBDA's, NLAMBDA's, etc. Such a function is usually given all of its arguments unevaluated, and then it evaluates them internally at its own discretion. STRUCTURE EDITOR - A type of LISP editor which operates on an s-expression which is in RAM, and which contains commands to move around the s-expression's component elements. Proponents of structure editors maintain that an editor should reflect the logical structure of the object which is being edited. LED, the structure editor provided with PDLISP, is a derivative of the BBN-INTERLISP editor. Compare with "Text Editor" and "Screen Editor." SYMBOL TABLE - A table on which one entry for each symbol is constructed by the reader. Numbers and quoted strings are generally not on the symbol table. Another name for this construct is "object list." TEXT EDITOR - A type of editor which operates on disk files which are organized as a stream of characters. There are basically two types of text editors - line and screen - 256 - Version 1.10 PDLISP language manual LISP Glossary editors. Line editors work with a line of text at a time, and typically display text only under explicit command. Screen editors allow the user to move the cursor around the screen, and any text which he/she alters is immediately updated on the screen. See "screen editor." TOP-LEVEL - a generic term for the "top-level" routine which a LISP interpreter is executing. Usually, this routine is a simple read-eval-print loop, but many LISP interpreters, including PDLISP, allow this to be altered via a "hook" function. UCI LISP - A LISP dialect developed at the University of California at Irvine. VAPORWARE - software which is promised but never delivered. VIRTUAL IMAGE - the entire set of objects which PDLISP (or, for that matter, any LISP interpreter) knows about. The virtual image can be saved on disk and retrieved at a later date. The disk file in which the image is saved is called the "image file," and the standard file name suffix in PDLISP for this type of file is ".img". - 257 - Version 1.10 PDLISP language manual LISP Glossary This page intentionally left blank - 258 - Version 1.10 PDLISP language manual LISP Glossary This page intentionally left blank - 259 - Version 1.10 PDLISP language manual Product Support Appendix F Product Support PDLISP is currently distribute free of charge through bulletin board systems (BBS's) nationwide. In addition, the latest version can always be obtained by contacting A.D.A. 1570 Arran Way Dresher, Penna. 19025 (215)-646-4894 I believe that they charge $10 plus shipping and handling for this service. At some future point, I am planning upon providing some kind of direct electronic support for PDLISP, either through my own BBS, a UNIX system, or one of the commercial computer service companies (compuserve, etc). Stay tuned. - 260 - Version 1.10 PDLISP language manual Product Support - 261 - Version 1.10 PDLISP language manual Index $ 75 $$ 75 % 152 &OPTIONAL 38 &REST 38 * 153 + 153 - 153 /USR 73 /USR/LOGIN 73 < 153 <= 153 > 152 >= 152 ADD-TO-LIST 62 ADD-TO-PATH 87 algorithm 7 ALLOC 200 AND 156 APPEND 18, 44 APPLY 96 arrays 145 ATOM 20, 44 atoms 2 auto-quoting 16 BACK_QUOTE_HOOK 189 BAKTRACE 180 BAKTRCE 180 bindings 6 BLOCK 103 bound variable 33 BOUNDP 65 box notation 23 BREAK 174 BREAK_HOOK 185, 186 BREAK_LEVEL 192 CAR 13, 44 CATCH 109, 109 CD 74, 87 CDQ 74, 87 CDR 13, 45 character object 139 character strings 135 Version 1.07 PDLISP language manual child 75 clauses 97 CNSUBRP 65 COMMA_AT_HOOK 190 COMMA_HOOK 189 comments 5 COMPILED-FUNCTION-P 65 COND 97 cond pairs 97 CONS 18, 45 cons cell 18 consequents 97 console i/o 121 CONSP 18, 62 constants 17 conversion character 195 CSUBRP 66, 66, 66 current directory 72 CURRENT_DIR 191 CXXR 63 CXXXR 63 DEBUG 181 DEBUGQ 181 DEBUGSET 181 DEF 46 DEF$ 87 DELETE 63 DIR 79, 88 directory prefix 78 DIRP 66 DIRQ 88 DIR_PREFIX_FLAG 187 discipline 42 DIV 152 DO 98, 98 DO* 98, 100 dotted pairs 24 dummy variable 33 EQ 20, 28, 45 EQL 20, 28, 45 EQUAL 20, 28, 45 ERR 111 Error Handling 110 error hook 188 ERROR_HOOK 188 ERROR_LABEL 190 ERRSET 111 EVAL 96 EVAL_HOOK 187 EXIT 5 Version 1.07 PDLISP language manual EXPLODE 139 file i/o 124 FIRSTN 63 FIXP 152 FLATSIZE 138 floating point format 132 floating pt format hook 195 FLOATP 152 floats 2 FLOAT_FORMAT 195 form 30 FULL_PATH_FLAG 187 function cell 26, 27 functional directory 87 GC 200 GC_VERBOSITY 188 GENSTRING 140 GENSYM 141 GET 114 GETD 47 GETFREE 201 GLOBAL 88 global symbols 81 GLOBALP 88 Hooks 184 IF 97 image files 57 Implicit PROGN 107 IMPLODE 139 IMPLODE-TO-STRING 141 input 119 integers 2 INTERN 141 internment 26 LAMBDA 33, 34 lambda binding 34 lambda expression 33 lambda-binding transaction 34 LAST 64 LCONC 68 LED 161 LENGTH 64 LEXPR 35 LIST 19, 46 LISTP 64 lists 2, 3 LOAD 55, 119 LOADV 55, 119 LOCAL 88 local symbols 81 Version 1.07 PDLISP language manual LOCALP 89 LOOP 108 LQ 79, 89 MACRO 35 macro expansion 35 MAKE-SYMBOL 141 MAKE-TCONC 68 MAPC 100 MAPCAN 100 MAPCAR 100 MAPCON 100 MAPL 100 MAPLIST 100 mapping functions 100 mark list 167 marks 167 MCD 75, 90 MCDQ 75, 90 MD 74, 90 MDQ 74, 90 MEMBER 64 MEMMAP 201, 245 memory cells 22 MOD 153 NCONC 67 NEQL 153 NIL 14 NLAMBDA 35 NOT 156 NTHCDR 64, 99 NULL 21, 65 NUMBERP 21, 46 numbers 2 object list 26, 71 optional parameter 38 OR 156 output 119 parent 75, 76, 90 parenthesis counting 9 PARENTQ 76 path-name 71 PATHLST 90 PATHNME 90 PATHSTR 91 PCOUNT_FLAG 191 PD 84, 91 PDQ 84, 91 plist cell 26, 27 POPD 84, 91 POPPATH 91 Version 1.07 PDLISP language manual POPPROP 116 PP 119 PPDEF 119 predicates 20 primitive functions 12 PRINC 120 PRINT 120 print flag 167 print-name cell 26, 27 PROG 101, 101 PROG* 106 PROG1 107, 107 PROGN 107, 107 property lists 114 PTOSTR 120 PUSHPATH 91 PUSHPROP 116 PUTD 47 PUTPROP 115 QUOTE 16, 46 quote marks 15 quoted strings 3 READ 120 reader 77 reader search path 77, 77 READER_SEARCH_PATH 194 recursive algorithm 7 recursive definition 7 REMOVE-FIRST 68 REMPROP 115 RESET 182 rest parameter 38 RESTORE 57, 58 REVERSE 19, 65 RM 83, 91 RMDIR 84, 92 RMDIRQ 84, 92 RMQ 83, 92 root directory 73, 73 RPLACA 67 RPLACD 67 S-expressions 1 SAVE 57, 58 scientific notation 2 semicolon 5 SET 16, 47 SETPLIST 115 SETQ 6, 47 SHELL 198 SHOWSTACK 179 Version 1.07 PDLISP language manual side effect 6, 67 smash hook 37 SMASH_HOOK 186 SRMDIR 92 STATUS 184, 184 STRCAT 135, 137 STRCMP 135, 135 STREQ 135 STRLEN 136 STRLENC 136 STRXTRC 135, 137, 137 sub-directory 75 surgical functions 67 symbol table 26 SYMBOL-PLIST 115 symbolic expressions 1 SYMBOLP 20, 66 system error handler hook 188 tag body 102 TAGBODY 102 TCONC 68 tconc structure 68 TERPRI 120 THROW 109, 109 TRACE 182 TYPE 65 UNPRINT 120 UNTRACE 182 value cell 27 variable cell 26, 27 VARP 66 X_POSITION 193 Y_POSITION 193 ZEROP 21, 46 Version 1.07 PDLISP language manual Table of Contents Chapter 1 An Overview of LISP 1 1.1 Symbolic Expressions 1 1.1.1 Atoms and Lists 2 1.1.2 Reserved Words 2 1.1.3 Numbers 3 1.1.4 Quoted Strings 3 1.2 The PDLISP evaluator 4 1.3 The Pause which Refreshes 5 1.4 Assigning Values to Variables 6 1.5 Parenthesis Counting 9 Chapter 2 Some System Primitives 12 2.1 Some Primitive Functions 12 2.1.1 CAR and CDR 13 2.1.2 Quote Marks and the Evaluator 15 2.1.3 Auto-Quoting Functions and Atoms 16 2.1.4 CONS and CONSP 18 2.1.5 APPEND 18 2.1.6 LIST 19 2.1.7 REVERSE 19 2.2 Some Useful Predicates 20 2.2.1 ATOM and SYMBOLP 20 2.2.2 EQ, EQL, and EQUAL 20 2.2.3 NULL 21 2.2.4 NUMBERP 21 2.2.5 ZEROP 21 2.2.6 EVAL and explicit evaluation 21 2.3 Internal Representation of Symbolic Expressions 22 2.3.1 Nodes and Lists 22 2.3.2 Dotted Pairs 24 2.3.3 Atoms and Symbols 26 2.3.4 Symbolic Structure 26 2.3.5 Unique Representation and Equality Version 1.07 PDLISP language manual 27 2.4 Exercises 29 Chapter 3 User-Defined Functions 30 3.1 Defining Functions 31 3.2 DEF and PUTD 32 3.3 Lambda Binding 34 3.4 NLAMBDA's 35 3.5 LEXPR's 35 3.6 MACRO's 35 3.6.1 Displacing Macros 36 3.6.2 Backquoting 36 3.6.3 The Smash Hook 37 3.7 Optional, Rest, and Auxilliary Parameters 38 3.8 Initialized &OPTIONAL parameters 40 3.9 Auxilliary Parameters 40 3.10 PDLISP Function Descriptions 42 3.11 Summary of Functions Presented So Far 44 Chapter 4 Program Development in PDLISP 55 4.1 What's a Program? 55 4.2 Saving and Restoring PDLISP Sessions 57 4.3 Summary of Virtual Image Commands 58 4.4 Booting Up PDLISP 58 Chapter 5 List Processing Functions 62 5.1 Miscellaneous Predicates 65 5.2 Surgical Functions 67 5.3 TCONC Structures 68 Chapter 6 PDLISP Directory Structure 71 6.1 Initial PDLISP Directory Configuration 73 6.2 Creating Directories 74 6.3 The $ and $$ symbols 75 6.4 PARENT and PARENTQ functions 76 6.5 The Reader Search Path 77 6.6 Directory Prefixes 78 6.6.1 The Current Directory Prefix 78 6.6.2 The Directory Suffix 78 Version 1.07 PDLISP language manual 6.7 The DIR Function 79 6.8 The LQ function 79 6.9 Global and Local Symbols 81 6.10 RM and RMQ 83 6.11 RMDIR and RMDIRQ 84 6.12 PD, PDQ, and POPD 84 6.13 Common Mistakes when Using Directories 85 6.14 Functional Directories 86 6.15 Summary of Directory Management Functions 87 Chapter 7 Control Constructs 96 7.1 Explicit Evaluation 96 7.2 Conditional Evaluation 97 7.3 DO and DO* 98 7.4 Mapping Functions 100 7.5 PROG and Friends 101 7.6 PROGN and PROG1 107 7.7 Implicit PROGN 107 7.8 LOOP 108 7.9 CATCH and THROW 109 7.10 Error Handling in PDLISP 110 Chapter 8 Property Lists 114 8.1 GET, PUTPROP, and REMPROP 114 8.2 SYMBOL-PLIST and SETPLIST 115 8.3 PUSHPROP and POPPROP 116 Chapter 9 Input and Output 119 9.1 Console I/O 121 9.2 File I/O 124 9.3 The PDLISP Reader 127 9.4 Floating Point Formats 132 Chapter 10 Character Strings 135 10.1 STRCMP and STREQ 135 10.2 STRLEN and STRLENC 136 10.3 STRCAT 137 10.4 STRINGP 137 10.5 STRXTRC 137 10.6 FLATSIZE 138 10.7 EXPLODE and IMPLODE 139 10.8 GENSTRING 140 10.9 GENSYM 141 Version 1.07 PDLISP language manual Chapter 11 Arrays 145 Chapter 12 Arithmetic and Mathematical Functions 152 Chapter 13 Logic Functions 156 Chapter 14 LED, the PDLISP Structure Editor 161 14.1 Invoking and Exiting LED 161 14.2 Getting Around 162 14.3 Making Mistakes 163 14.4 Making Changes 164 14.5 How LED prints out expressions 165 14.6 A Quick Summary of LED Commands 166 14.6.1 Structure Modification Commands 167 14.6.2 Parenthesis Moving Commands 168 Chapter 15 PDLISP Debugging Functions 172 15.1 The PDLISP Debugger 172 15.1.1 A Bird's Eye View of the Stack 172 15.1.2 DEBUG and DEBUGQ 173 15.2 A Sample Debugging Session 175 15.3 Debugger Support Functions 179 15.3.1 TRACE and UNTRACE 182 15.4 System Hooks and the STATUS Function 184 15.4.1 The Top-Level Hook 185 15.4.2 The Pretty-Printer Hook 185 15.4.3 The Smash Hook 186 15.4.4 The Break Hook 186 15.4.5 The Evaluatator Hook 187 15.4.6 The Full Path Flag 187 15.4.7 The Directory Prefix Flag 187 15.4.8 The Error Hook 188 15.4.9 The Garbage Collector Verbosity Flag 188 15.4.10 The Back-Quote Hook 189 15.4.11 The Comma Hook 189 15.4.12 The Comma-At Hook 190 15.4.13 The Error Label Hook 190 15.4.14 The Parenthesis Counting Flag 191 15.4.15 The Current Directory Hook 191 15.4.16 The Break Level Hook 192 Version 1.07 PDLISP language manual 15.4.17 The X-Position Hook 193 15.4.18 The Y-Position Hook 193 15.4.19 The Reader Search Path Hook 194 15.4.20 The Floating Point Format Hook 195 Chapter 16 Interfacing to the Operating System 197 Chapter 17 Storage Management 200 Appendix A Bibliography 204 Appendix B PDLISP Error Messages 211 Appendix C Running PDLISP Under MS-DOS & PC-DOS 234 17.1 Packing List 234 17.2 Getting Started 234 17.3 Running PDLISP on a Floppy-Only System 236 17.4 Editing of Initialization Files 237 17.5 Error Messages on MS-DOS 238 17.6 Peculiarities 242 17.7 Memory Configuration under MS-DOS 243 Appendix D Running PDLISP Under UNIX 248 Appendix E LISP Glossary 253 Appendix F Product Support 260 Version 1.07