A GUIDE TO THE PC-LISP INTERPRETER (V2.16) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ By Peter Ashwood-Smith ~~~~~~~~~~~~~~~~~~~~~~ University of Toronto, ~~~~~~~~~~~~~~~~~~~~~ Ontario, Canada. ~~~~~~~~~~~~~~~ Copyright (C) 1985,1986,1987 - Peter Ashwood-Smith for my wife, Guylaine email: petera!utcsri USENET pashwood BIX mail: Peter Ashwood-Smith #811, 120 St. Patrick St. Toronto, Ontario, Canada, M5T-2X7. phone: (416) 593-7574. Addresses valid April 87 then try Ottawa Ont. (BIX address will stay the same) 1 INTRODUCTION ~~~~~~~~~~~~ PC-LISP is a small implementation of LISP for just about any machine with a good C compiler. This manual is biased towards the UNIX and MS-DOS versions. While small, it is capable of running a pretty good subset of Franz LISP. The functions are supposed to perform in the same way as Franz with a few exceptions made for effeciencies sake. Version 2.16 has the following features. - Types fixnum,flonum,list,port,symbol,string, hunk, array. Forms lambda, nlambda, macro and lexpr. - Read Macros including splicing read macros. - Full garbage collection of ALL types. - Compacting relocating heap management. - Access to some MSDOS BIOS graphics routines. - Over 160 built in functions, sufficient to allow you to implement many other Franz functions in PC-LISP. - Stack overflow detection & full error checking on all calls, tracing of user defined functions, and dumping of stack via (showstack). - One level of break from which bindings at point of error can be seen. - Reasonable size, requires minumum of 300K (machine RAM required may differ depending on OS size). - Access to as much (non extended) memory as you've got and control over how this memory is spread among the various data types. This program is Shareware. This means that it you are free to distribute it or post it to any BBS that you want. The more the better. The idea is that if you feel you like the program and are pleased with it then send us $15 to help cover development costs. Source code for this program is available upon request. You must however send me 3 blank diskettes and about $1.50 to cover first class postage. The program can be compiled with any good C compiler that has a pretty complete libc. In particular the program will compile with almost no changes on most UNIX systems. A source code guide will probably be included with the source if it is finished at the time I receive your source request. If you send diskettes, SEND NEW, GOOD QUALITY DISKS as I have had problems writing IBM-PC readable data to old or poor quality diskettes with my Tandy 2000's 720K disk drives. 2 A WARNING ~~~~~~~~~ PC-LISP is distributed as ShareWare. The executable and source code may be freely distributed. It is contrary to the purpose of ShareWare to charge more than media and or mailing costs for this program in any form source,disk,tape etc. If you use PC-LISP you do so at your own risk. I will not be held responsible for loss or dammage of any kind as a result of the correct or incorrect use of this program. If you modify the source and redistribute this source or its resulting executable I ask that you add a "modified by x" or a "ported to z by y" line to the initial banner and comment the code accordingly. Please do not remove my name from the banner. A NOTE ~~~~~~ The rest of this manual assumes some knowledge of LISP, MSDOS/UNIX and a little programming experience. If you are new to LISP or programming in general you should work your way through a book on LISP such as LISPcraft by Robert Wilensky. You can use the interpreter to run almost all of the examples in the earlier chapters. I obviously cannot attempt to teach you LISP here because it would require many hundreds of pages and there are much better books on the subject than I could write. Also, there are other good books on Franz LISP besides LISPcraft. IF YOU WANT TO TRY PC-LISP RIGHT NOW ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Make sure that PC-LISP.EXE and PC-LISP.L are in the same directory. Then type PC-LISP from the DOS prompt. Wait until you get the "-->" prompt. Here is what you should see starting by typing pc-lisp at the prompt: PC-LISP V2.16 Copyright (C) 1986 by Peter Ashwood-Smith NNN cell bytes, NNN alpha bytes, NNN heap bytes --- [pc-lisp.l] loaded --- --> Be patient, it takes a few seconds to load the program especially off a floppy. When you see the first line with the version number it will take another second or two to produce the status line. (The N's depend on how much memory you have). At this point PC-LISP is up and running and is reading LISP from the file PC-LISP.L. Again this takes a second or two. If your machine has some sort of graphics capability you can try the graphics demo as follows. Type "(load 'turtle)" without the "'s. Wait until you see the "t" and the prompt "-->" again, then type "(GraphicsDemo)". You should see some Logo like squirals etc. If you do not have any graphics capability try "(load 'queens)" or "(load 'hanoi)" and then (queens 5) or (hanoi 5) respectively. For a more extensive example turn to the last couple of chapters in LISPcraft and look at the deductive data base retriever. Type (load 'match) and look at the match.l documentation. 3 EXAMPLE LOAD FILES AND THE PC-LISP.L FILE ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Included with PC-LISP (V2.16) are a number of .L files. These include: PC-LISP.L, MATCH.L, TURTLE.L, DRAGON.L, DIFF.L and perhaps a few others. These are as follows. PC-LISP.L ~~~~~~~~~ A file of extra functions to help fill the gap between PC and Franz LISP. This file defines the pretty print function and a number of macros etc. It will be automatically loaded from the current directory or from the directory whose path is set in LISP_LIB when PC-LISP is executed. The functions in this file are NOT documented in this manual, look instead at a Franz manual. MATCH.L ~~~~~~~ A small programming example taken from the last 2 chapters of LISPcraft. It is a deductive data base retriever. This is along the lines of PROLOG. Very few changes were necessary to get this to run under PC-LISP. TURTLE.L ~~~~~~~~ Turtle Graphics primitives and a small demonstration program. To run the demo you call the function "GraphicsDemo" without any parameters. This should run albeit slowly on just about every MS-DOS machine. The graphics primitives look at the global variable !Mode to decide what resolution to use. If you have mode 8 (640X400) you should use it as the lines are much sharper. Turtle graphic modes can be set by typing (setq !Mode - number-). Have a look at TURTLE.L to see how they work. DRAGON.L ~~~~~~~~ A very slow example of a dragon curve. This one was translated from a FORTH example in the April/86 BYTE. It takes a long time on my 8Mhz 80186 machine so it will probably run for a few hours on a PC or AT. I usually let it run for about 1/2 hour before getting tired of waiting. To run it you just type (load 'dragon) ...
septix