clisp.doc

                         Tops-20 Common Lisp

                              Red Pages


                          Charles L. Hedrick

                                 1985






           Copyright (C) 1983,1984,1985 Charles L. Hedrick


The  information  in this document is subject to change without notice
and should not be construed as a  commitment  by  Charles  Hedrick  or
Rutgers  University.  Charles Hedrick and Rutgers University assume no
responsibility for any errors that may appear in this document.

Note:    The  following  are  trademarks  of  the  Digital   Equipment
Corporation:  DECSYSTEM-20, DECsystem-10, TOPS-20, TOPS-10
                                                                     i


                          Table of Contents


1. Introduction                                                      1

   1.1. How to read this manual                                      1
   1.2. The genealogy of DECSYSTEM-20 Common Lisp                    2
   1.3. Design Goals                                                 2
   1.4. Overview of the Design                                       3

2. Current Status of the System                                      5

   2.1. Efficiency Issues                                            5

3. User Facilities                                                   6

   3.1. Interrupt Characters                                         7
   3.2. The Break Facility                                           7
   3.3. Trace                                                       10
   3.4. The Stepper                                                 11
   3.5. The Editor                                                  12
   3.6. Special features for system builders                        13
   3.7. I/O Implementation                                          14
       3.7.1. Opening files                                         15
       3.7.2. Representation of files and lines                     16
       3.7.3. Device handling                                       17
           3.7.3.1. Disk files                                      17
           3.7.3.2. Terminals                                       17
           3.7.3.3. Other devices                                   18

4. Reference Manual - Additional Functions and Features             20

5. Differences between Spice Lisp and Common Lisp                   26
                                                                     1


                           1. Introduction



This document contains implementation-dependent information describing
the Common Lisp implementation for the DECSYSTEM-20.  In the  rest  of
the  manual, I will simply refer to it as "Lisp".  Lisp is designed to
be  used  with  the  Common  Lisp  Reference  Manual,   (Guy   Steele,
Carnegie-Mellon  University  Computer  Science  Dept.)    This  manual
documents only the peculiarities of this particular implementation.  I
hope  that  there  aren't very many of those.  Indeed many people will
probably never need this document at all.



1.1. How to read this manual


This document is organized into the following chapters:  

     1    General material about the history and goals of DECSYSTEM-20
          Common Lisp, and an overview of its internal organization.

     2    A description of the current status of the system, including
          the facilities that are not  yet  implemented,  and  various
          issues affecting the speed of your program.

     3    A  description  of  the major user facilities of the system.
          This chapter contains a number of sections,  each  giving  a
          general  discussion  of  some  facility.   It is intended to
          cover the same material as the next chapter, namely  all  of
          the implementation-defined facilities.  However this chapter
          is organized topically, whereas the next  one  is  organized
          alphabetically  by  function.    Also, it is at a conceptual
          level, whereas the next chapter is intended as  a  reference
          manual.  There is a section at the beginning of this chapter
          that provides an overview of its organization.

     4    This is intended as a  complete  reference  manual  for  all
          functions   that  are  extensions  or  whose  definition  is
          implementation-dependent.   In  those  cases  where  a  full
          description  seems  to belong in the previous chapter, there
          is a cross-reference  to  the  appropriate  section.    This
          chapter  is organized alphabetically by function or variable
          name.

     5    Hints for people who want to import  system-dependent  Spice
          Lisp code.  
                                                                     2


1.2. The genealogy of DECSYSTEM-20 Common Lisp


This  Lisp  is  in  fact  an implementation of Carnegie-Mellon's Spice
Lisp.  Spice Lisp was originally intended for  a  micro-coded  machine
with bit-mapped screen.  However implementations based on it are being
done for the DECSYSTEM-20 and VAX.  We  are  attempting  to  keep  the
Spice  implementations as similar as possible.  Here are the pieces of
DECSYSTEM-20 Common Lisp, with an indication of  which  of  them  came
from Spice Lisp:  

   - Compiler  - This is the Spice compiler, with code generation
     rewritten to produce code for the DEC-20.

   - System code - This is the  portion  of  the  runtime  system
     written in Lisp.  It includes most of the functions that the
     user calls. These functions are taken directly  from  Spice,
     with  minor  modifications where the code is representation-
     dependent.

   - Kernel - This  is  the  assembly  language  portion  of  the
     system.  It contains low-level functions, mostly things that
     manipulate internal data representations, e.g. CONS and  the
     garbage  collector.    Most of these functions implement the
     basic byte codes of the Spice machine.  These are documented
     in  the  Internal Design of Spice Lisp (Scott Fahlman et al,
     Carnegie-Mellon  Computer  Science  Dept.)    That  document
     should   be   regarded   as   the   blue   pages   for  this
     implementation.    In   addition,   we   have   added   some
     higher-level  functions  to  the  kernel, when it seems that
     this would help  performance  noticibly.  For  example,  the
     interpreter   (EVAL)   and   much  of  READ  and  PRINT  are
     hand-coded.  In general the assembly language  code  follows
     the Spice Lisp code very closely.  

The  interior  design is sort of a cross between the Spice machine and
Elisp, the Rutgers extended-addressing version of UCI Lisp.  The Elisp
manual  documents  most  of the internal data structures in detail. By
the final release, we will provide a real blue pages  that  integrates
the  information  in  the Elisp manual and the Spice internals manual,
but for the moment, those two documents should allow you to find  your
way   around   in   the   code.      Fortunately,  the  internal  data
representations used by Spice Lisp and Elisp are surprising similar.



1.3. Design Goals


In evaluating this implementation, you might find it  useful  to  know
what goals we had in mind.

   - We  intend  this  implementation  to stick very close to the
     Standard.    The  extensions  are  largely  tools  for   the
     implementors, which we have made accessible to users.  There
                                                                     3


     are also a few features added to increase compatibility with
     the  VAX implementation.  However our experience with Pascal
     has lead us to realize  how  important  standards  are.    I
     believe   that   Pascal's   greatest  weakness  is  that  no
     interesting program written in  it  is  portable.    We  are
     determined that this will not be the case with Common Lisp.

   - We  are  quite  concerned about performance.  However we are
     interested in the performance that a normal researcher  will
     see,  rather  than  in  providing tools to let benchmarks be
     tuned to blinding speeds.  This means  that  we  worry  most
     about  programs  that  use  no  declarations  and  which are
     written without undue concern for speed.  (Note however that
     the  current  copy is considerably slower than it should be,
     because our register allocation is not yet being done in the
     compiler.    This  leads to slow code, and it also makes the
     system larger than it should be.  The size  is  probably  at
     least as important as the CPU time use.)  



1.4. Overview of the Design


Lisp  uses  extended  addressing, which gives it a much larger address
space than conventional programming languages.    Lisp  runs  only  on
Model  B KL-10 processors running TOPS-20 release 5 or later.  That is
because extended addressing is only implemented for those systems.  In
particular,  Lisp  does not run on TOPS-10, on older 2040's and 2050's
(those with Model A CPU's), or on 2020's.

The internal design of Lisp is modelled after the Lisp Machine.    All
Lisp objects are type-coded pointers.  They consist of 3 fields:

   - high order bit is used by the garbage collector for marking.
     It is normally off (for extended addressing to work).

   - next 5 bits are a type code, used internally by the system.

   - last 30 bits are the data for the object.    In  most  cases
     this  is  the address of the object itself.  However in some
     cases the actual object fits in 30 bits, and no  pointer  is
     needed.  E.g. we have 30-bit integer constants.

There  are two free spaces. Most Lisp pointers point to objects within
one of these spaces.    When  a  space  is  full,  a  copying  garbage
collector  is  invoked  to  copy  all  currently used objects to a new
space.

This implementation  is  a  shallow-binding  Lisp.    It  stores  atom
bindings  in  a  "value  cell"  associated  with  the atom, saving old
bindings on  a  pushdown  stack.  List  cells  take  two  words,  each
containing  one object.  Atoms consist of small blocks of memory, with
the following structure:
                                                                     4


     value cell

     pointer to property list

     string pointer to pname

     function definition, or NIL if none

     other internal information involving function definitions  -  set
          by  DEFUN  or  other  function-defining  forms, not directly
          visible to the user
                                                                     5


                   2. Current Status of the System



This is a  preliminary  release  of  this  system.    The  basic  data
structures  are  in  their final form.  So is almost all of the kernel
code.  However a few features are not yet implemented.  We  also  plan
to make some additional performance improvements to the system.

The  only major omission we know of is complex numbers.  However there
may be minor oversights.  If  so,  we  would  appreciate  having  them
brought to our attention.

The  compiler is currently unable to handle functions that use lexical
closures.  When it finds such  a  function,  the  compiler  will  pass
through  the  source into the .LAP file.  Thus the function will work,
but will not be compiled.

Bugs are documented in the file BUGS.  Please report any errors,  even
minor ones, that are not in this file.



2.1. Efficiency Issues


There are still major inefficiencies in the system.  We will fix these
over the next  6  months  or  so.    These  inefficiencies  can  cause
slowdowns  ranging from factors of 2 to 5.  The most serious slowdowns
are in the string and sequence functions.   These  use  DO  loops  and
array  indexing.    We hope to hand-code them to use small ILDB loops.
This will probably not affect most traditional Lisp code, however.

We expect compiled code to be reduced by at least a factor of  1.5  in
code  size,  and almost this much in CPU time.  Currently the compiler
does no register allocation.  It keeps all data on  the  stack.    The
compiler  is designed to allow for register allocation and other kinds
of optimizations.  This will be a high  priority  over  the  next  few
months.

Additional  compiler  optimizations will require open-coding of common
functions, and automatic detection of  fixnum  arithmetic  and  linear
array   references.     This  should  affect  the  sequence  functions
dramatically.  If these optimizations prove  too  difficult,  we  will
hand-optimize the sequence functions.

The  interpreter  is  nearly  as fast as we can make it.  There is one
more optimization, which may speed things about by 10% or so.
                                                                     6


                          3. User Facilities



This chapter contains the following sections:  

     3 - how to run the system, and what the top-level  is  like.    A
          description of the system-wide help convention.

     3.2  - the break handler.  This is an interactive system which is
          entered when an error happens.

     3.3 - TRACE, a function that you can use to get a trace  of  your
          program's behavior.

     3.4 - STEP, a function that you can use to control your program's
          execution on a expression by expression  basis,  seeing  the
          results of each evaluation.

     3.5 - the editor, which is actually an interface to EMACS

     3.6   -   some  miscellaneous  facilities  primarily  for  system
          builders: Customizing the top level (including changing  the
          prompt), creating a saved core image file, loading code into
          a specified package, and calling DDT.

     3.7 - details about the I/O  implementation,  including  how  the
          various  OPEN  options  work,  the  way  the Common Lisp and
          TOPS-20 file models are matched, end of line  handling,  and
          details   about   how   I/O  is  done  to  specific  devices
          (particularly terminals).  This section has a  paragraph  at
          the beginning that describes its organization.  

We  intend  the  Lisp  system  to  be  installed  on  your  system  as
SYS:CLISP.EXE.  If it is, you start it by typing 

    CLISP

Lisp has a simple EVAL top level.  You type Lisp forms to it,  and  it
prints  the result.  If the form returns multiple values, you will see
all of them (each on a new line).

? should usually give you useful information about the context you are
currently  in.   In many cases you will have to type a carriage return
after the ?.  At the top level, it tells you how to define  functions,
and  describes  some  of  the  most  important  facilities.   In other
situations ? is rebound to messages that are useful in  that  context.
We  urge  users  to  continue  this  convention for packages that they
write.
                                                                     7


3.1. Interrupt Characters


Several interrupt characters are defined.  When you type one of  these
characters  once,  its  effect  will  happen the next time the program
reads from the terminal.  If you type it a  second  time,  the  effect
will happen immediately, most of the time.  If your program happens to
be in the middle of a garbage collection, the effect will normally  be
delayed until the end of the garbage collection.

     ^B (Break)
          This causes Lisp to enter the break package, just as  if  an
          error  had  happened.  This is sometimes useful if you think
          your program is in an  infinite  loop.    You  can  use  the
          commands  in  the  break  package to look around.  Currently
          there is no way to continue your program after you have done
          this.   However GO will reevaluate the most recent form, and
          so may allow you to continue in many cases.

     ^C   This will return you to the EXEC.  If you are in the garbage
          collector,  it  will  delay  the  return  until  the garbage
          collection is finished.  If you type more than one ^C,  Lisp
          will  count them.  If you 6 of them, it will return you even
          if you are in the garbage collector.   This  is  to  protect
          against  bugs  in the garbage collector that would otherwise
          make it impossible to escape from Lisp.

     ^G   [Note that ^G is the bell.]  This will return you to the top
          level  of  Lisp.    If you are currently in a break loop, it
          will return you to the top-most break loop.

     ^Y   This is a high-priority version of ^C.    It  always  causes
          Lisp  to exit, even if a garbage collection is going on.  It
          takes precedence over any other interrupts that  may  be  in
          progress.    It is intended to make sure that you can always
          get out of Lisp, even if bugs exist in the ^C code.  



3.2. The Break Facility


The default condition  handlers  for  errors  call  a  built-in  break
package.    This  is a specialized READ-EVAL-PRINT loop.  It evaluates
forms in the context of the bad form.  When an error occurs, you  will
see something like the following:

    Error in function FOO.
    Undefined function: BAR
    1>

The  "1>"  is  the  break level number.  It indicates that this is the
first level of error.  If you make an error while already in a  break,
you  will  get  another recursive level of break.  It will prompt with
"2>".
                                                                     8


When you enter a break, the system attempts to put you  at  the  place
where  the error occured.  When you type forms to the "1>" prompt, the
system will evaluate them in the context of the error.  That  is,  the
variables  of  that function will be visible, and can be changed.  (If
the function is compiled, then of course only  special  variables  are
visible.)

You  can tell where you are by typing the "BK" command.  This prints a
"backtrace".  Here is an example of  a  standard  recursive  Factorial
function,  which  has  a bug that shows up only at the bottom level of
recursion:

    CL>(fact 2)

    Error in function FACT.
    Undefined function: FOO
    If continued: Please define it before continuing
    1> bk

    72 (FOO)
    70 (COND ((ZEROP N) #) #)
    64 ****** FACT
    57 (FACT (1- N))
    55 (* N (FACT #))
    53 (COND ((ZEROP N) #) #)
    47 ****** FACT
    40 (FACT (1- N))
    38 (* N (FACT #))
    36 (COND ((ZEROP N) #) #)
    30 ****** FACT
    23 (FACT 2)
    23 compiled call to EVAL
    1> n
    0
    1>

Notice the numbers on the left margin.  These are  depth  indications.
You  can  use  them  to access levels other than the default one.  For
example, suppose you want to look at the values  of  variables  inside
the  top-level incarnation of FACT.  Any number between 36 and 40 will
do that.  To change to a new level number, you simply type the number.
Here is an example:

    1> 40
    1> n
    2
    1>

Note that the debugger will continue at this level until you change it
again.  To get back to the initial level, use a negative number.

The following forms have special  actions  when  typed  to  the  break
system, and thus can be thought of as commands to it.

     ^^   Returns  you  to  the  top-level  loop, i.e. exits the break
                                                                     9


          abruptly.

     ^    Returns you to the next higher level break loop.  (There can
          be more than one, if you generate an error in a break loop.)

     OK   Attempts  to  proceed  from  the  break,  returning NIL from
          CERROR.  This will only work if the error is  "correctable".
          For this to work, you have to know how to correct the error.
          Some cases are obvious.  If a  function  is  undefined,  you
          must define it.  If a variable is unbound you must set it to
          a value.  In fact these are  the  main  cases  where  OK  is
          useful.    Most  other  error  types require you to return a
          value, which will then be used to repair the  error.    This
          requires  (OK  value),  which  is  documented  below.  OK is
          equivalent to (OK nil).  If the error  is  not  correctable,
          see "GO" below.

     (OK <value>)
          Attempt to proceed from the break, returning  the  specified
          value  from  CERROR.    This  value is returned to the error
          handler. It is used in an attempt to repair the error.  E.g.
          if the system complains that something is not an symbol, you
          should return a symbol.   The  system  will  attempt  to  do
          whatever  it  was  trying to do, using the symbol you return
          instead of the original non-symbol.

     GO   Attempt to proceed from a non-continuable error.    In  this
          case,  there  is no way to exactly continue the computation.
          Instead,  the  form  that  generated  the  error  is  simply
          re-executed.    The hope is that you have fixed something so
          that it will work.  If this is  not  practical,  RETURN  may
          allow you to proceed.

     (RETURN <value>)
          Proceed from a non-continuable error.   In  this  case,  the
          form  that  generated  the  error  is abandoned.  The system
          pretends that that form returned the value specified.

     BK   Displays the call stack.  See the example above.

     ?    Displays the list of commands.  

Note that <value> is evaluated in the context of the error.    I  have
not  done  extensive testing of evaluating forms in the context of the
error.   The  intent  is  that  you  are  put  in  the  exact  binding
environment  of  it,  and  any  sideeffects  are actually made in that
context (i.e. you can do SETQ to change variables). I have little idea
what  would  happen  if  you  execute a GO, RETURN-FROM, etc., in this
manner.  I'm not even sure I know what I want to happen.
                                                                    10


3.3. Trace


The trace facility allows you to ask for printout whenever  a  certain
function is called.  The printout shows the arguments with which it is
called and the value returned.  It  is  indented  to  show  recursion.
Here is a typical example:

    CL>(defun fact (n)
              (cond ((zerop n) 1) (t (* n (fact (1- n))))))
    FACT
    CL>(trace fact)
    FACT
    CL>(fact 4)

     0: (FACT 4)
       1: (FACT 3)
         2: (FACT 2)
           3: (FACT 1)
             4: (FACT 0)
             4: returned 1
           3: returned 1
         2: returned 2
       1: returned 6
     0: returned 24
    24
    CL>


There are a number of options, to allow for more selective output.  In
order to use an option, you must enclose the  function  name  and  the
options in parentheses, e.g.  

    (TRACE (FOO :CONDITION (NEED-TRACE)))

Here are the available options:

     :CONDITION
          A form  that  controls  whether  the  trace  information  is
          printed.  It will be EVAL'ed at each entry to the function.

     :BREAK
          A form that controls whether a break will occur  before  the
          function  is  executed.  It will be EVAL'ed at each entry to
          the function.

     :BREAK-AFTER
          like :BREAK, except that the break occurs after the function
          is executed.

     :WHEREIN
          Allows you to specify that tracing should happen only if the
          function is called inside another specific function.    This
          may be either a symbol or a list of symbols.
                                                                    11


     :PRINT
          A list of forms to EVAL and PRINT at the start of each call.

     :PRINT-AFTER
          A list of forms to EVAL and PRINT at the end of each call.

To  turn  off  tracing, use (UNTRACE).  Untrace checks to see that its
args are all symbols.  If they are,  it  returns  a  form  which  will
untrace  each  one.    Otherwise, it signals an error, and none of the
forms are untraced.  With no args, untraces all traced functions.



3.4. The Stepper


The single stepper is another facility to  make  it  easier  to  debug
functions.    It  allows  you  to watch the interpreter EVAL each form
individually.  Here is an example of what it looks like:

    CL>(step (fact 3))
     (FACT 3) : n
      3 = 3
      (BLOCK FACT (COND # #)) : n
       (COND ((ZEROP N) 1) #) : n
        (ZEROP N) : n
         N = 3
        NIL
        T = T
        (* N (FACT #)) : n
         N = 3
         (FACT (1- N)) : s
         2
        6
       6
      6
     6
    6
    CL>

I typed the lower-case "n"'s and "s".  In the stepper, you do not have
to type a return after each command.  If you don't like this, then set
*TERMINAL-LINE-MODE* to T. Notice what it is doing:  It  types  out  a
form,  and  then  waits  for  me  to  type something.  If I type N, it
evaluates  that  form  and  prints  the  result.    If  this  involves
evaluating  another  form, it stops for that, too.  Typing S causes it
to evaluate the form without showing what going on inside it.

Here is a complete list of commands to the stepper.  If you  type  "?"
while in step mode, you will get this list:

     N (next)
          evaluate current expression in step mode.

     S (skip)
                                                                    12


          evaluate current expression without stepping.

     M (macro)
          steps a macroexpansion, signaled by a :: prompt.

     Q (quit)
          finish evaluation, but turn stepper off.

     p (print)
          print current exp. (ignore *step-print-level* & *step-print-
          length*)

     P (pprint)
          pretty-print current exp.

     B (break)
          enter break loop.

     E (eval)
          evaluate an arbitrary expression.

     ? (help)
          print this text.

     R (return)
          prompt for an arbitrary value to return as result of current
          exp.

     G    throw to top level.

The  stepper  automatically  refuses to step through system code, even
when it is interpreted.  If you need to debug  system  code  with  the
stepper,  you  should  look at the macro STEP-STEP-FORM in STEP.CLISP.
This is where system functions are made un-steppable.



3.5. The Editor


Lisp uses EMACS as its editor.  Lisp will  check  your  definition  of
EDITOR:  when  looking  for  EMACS.  If EDITOR: seems to point to some
version of EMACS it will be used.  Otherwise SYS:EMACS will  be  used.
You  can  call  it  with  the function ED, described in the manual, or
EDIT.  EDIT is just like ED, except it does not evaluate its argument.
In  most  cases,  EDIT  is  probably more convenient.  Otherwise these
functions are identical.

As described in the Common Lisp  manual,  there  are  three  different
things you can do with EMACS:

(ED symbol)
          Edit  a  function  definition.    Lisp will pretty-print the
          current definition into the EMACS  buffer  and  call  EMACS.
          When  you  are finished editing, type ^X^Z (the normal EMACS
                                                                    13


          command to return to the superior).    Lisp  will  read  the
          first  S-expression  back  in from the EMACS buffer and EVAL
          it.  Should you decide that you don't want to  redefine  the
          function,  put  something  innocuous at the beginning of the
          buffer (e.g. a NIL).

(ED pathname)
          Edit a file.  Lisp will simply call  EMACS  and  pass  it  a
          request  to  edit the specified file.  When you are finished
          editing, type ^X^Z to return to Lisp.    Lisp  will  not  do
          anything  additional.  If you want to write out the modified
          file, do ^X^S (or your favorite file-saving command)  before
          exiting.    If  you want to read in the file after modifying
          it, you can use the LOAD command.

(ED)
          With no arguments, ED simply reenters EMACS.   Whatever  you
          edited last is still there.  ^X^Z will return to Lisp.  Lisp
          will not do anything additional, such as reading in from the
          buffer.

This  is  a fairly simple interface, as Lisp-EMACS interfaces go.  The
primitives are present in Lisp to do as hairy an interface to EMACS as
you like (see section 4).  We are planning an interface modelled after
the Maclisp LEDIT.

There is also a function (KILL-EDITOR).  It kills the EMACS fork.



3.6. Special features for system builders


This section documents some internals of Lisp that you may find useful
if you are building a system of your own.

(%TOP-LEVEL) - never returns
          When  a  copy  of  Lisp  is started, it first prints out the
          greeting message (set by SAVE - see below)  and  then  calls
          LISP::%TOP-LEVEL.   LISP::%TOP-LEVEL should be a function of
          no  arguments  that  never  returns.    If   you   redefined
          LISP::%TOP-LEVEL,  the  redefinition  should not take effect
          until a saved core image is run.   The  current  incarnation
          will  not  be  affected,  since Lisp has already started the
          existing top level function, and it will never return.

          If you intend to use the error handlers that we supply, your
          top  level  function should include (CATCH 'LISP::TOP-LEVEL-
          CATCHER ...)  around any EVAL's.  That  is  because  the  ^^
          function within the error handler THROWS to LISP::TOP-LEVEL-
          CATCHER.

          Should %TOP-LEVEL return, you will be in  a  READ-EVAL-PRINT
          loop in the kernel.  It prompts with a "*".  It is a minimal
          top-level, intended for testing the kernel.
                                                                    14


*PROMPT* - variable
          If you prefer to use the existing top level, you can  change
          its  prompt  to anything you like.  The variable *PROMPT* is
          PRINC'ed to produce the prompt.    It  will  normally  be  a
          string,  without  any newlines.  (FRESH-LINE is called right
          before printing the prompt.)

(SAVE filename &OPTIONAL greeting-message)
          The SAVE function can be used to produce an executable  file
          containing the current Lisp system.  The first argument is a
          file name, which is passed to OPEN.    The  second  argument
          (which  is optional) is a normally a string.  It is PRINC'ed
          when the saved core image is started.  It is intended  as  a
          greeting  message.   If this argument is not supplied, or is
          NIL, the PRINC is not done.

(LOAD filename :PACKAGE package)
          LOAD has an extra option, :PACKAGE.    This  allows  you  to
          specify  the  package  into  which the code is to be loaded.
          The system code must be in the internal  Lisp  package,  not
          the  user's package.  So if you wanted to load a new version
          of PPRINT.CLISP (the pretty-printer), you would type 

              (LOAD "PPRINT.CLISP" :PACKAGE *LISP-PACKAGE*)
              (LISP::PPRINT-INIT)

(DDT)
          (DDT) calls DDT in section  1  (the  section  in  which  the
          kernel code is loaded).  It gives DDT access to the kernel's
          symbol table.  To return to Lisp, type 

              IRET$X

          where $ is an escape.  Be careful about using $X in  DDT  to
          single-step.    There  are bugs in some versions of DDT that
          cause   extended-addressing   byte   instructions   to    be
          incorrectly simulated in $X and $$X.



3.7. I/O Implementation


The  Common  Lisp  specificiations leave some aspects of I/O up to the
implementor.  This section will describe what has been done with  some
of them.  It has the following subsections:

     3.7.1  -  opening  files, including details of filename handling,
          and how the various OPEN options are implemented.

     3.7.2 - how the Common Lisp file model is  mapped  onto  TOPS-20,
          including  file  structure,  random  access, and end of line
          handling.

     3.7.3 - details on how Lisp handles various devices.    The  most
                                                                    15


          interesting  is  the  terminal.    This  section describes a
          number of options you have to control  how  Lisp  interfaces
          with the terminal.  



3.7.1. Opening files


A NAMESTRING is simply a TOPS-20 file specification.  Host names go at
the  beginning  of  the  string,  followed  by  "::".    For   example
"RUTGERS::PS:<HEDRICK>CLISP.EXE".   Note however that host names don't
have any effect at the moment.  The filename parser understands all of
the options that TOPS-20 normally understands, including wildcards and
the special version numbers 0, -1, -2, and -3.

There may be a slight problem with namestrings  because  of  ambiguity
about  null  file  types.    In  most  cases,  a  field  in  the  file
specification can be omitted if it is not specified.    Unfortunately,
there  is  no  way  to omit the file type if the version is specified.
"SOURCE..3" is interpreted by TOPS-20 as  having  a  null  file  type.
That  is,  the  file type is specified, and is the null string. If you
need to specify the version and leave the file type  unspecified,  you
will simply have to leave the result in pathname format.

All  of  the  keywords  described  in  the  manual  as "suggested" are
implemented except for INSTALLED.  If someone can suggest a reasonable
meaning for it in TOPS-20, I will be happy to implement it.

Currently  Lisp  cannot  do  network I/O.  Thus host names are ignored
when opening files.  The functions  that  manipulate  namestrings  and
pathnames  do  handle  host  names  properly.   We intend to implement
Internet I/O eventually.

All of the OPEN options are implemented.  Here are some details:  

   - NEW-VERSION operates according to TOPS-20 conventions.  That
     is,  if you specify an explicit version number, that version
     will be used, and NEW-VERSION will be ignored.   This  gives
     an effect similar to SUPERSEDE.

   - If  you  specify  UNSIGNED-BYTE  or  SIGNED-BYTE  without  a
     number, you will get 8-bit bytes.  UNSIGNED-BYTE allows  any
     byte  size up to 35, and SIGNED-BYTE allows any byte size up
     to  36.    Note  that  you  may  specify  UNSIGNED-BYTE   or
     SIGNED-BYTE  even  if you intend to use a file for text I/O.
     This allows you to handle text files with non-standard  byte
     size.   For example, if you open a file for (SIGNED-BYTE 8),
     READ-BYTE will return a signed integer, but  READ-CHAR  will
     still  return  a  character.    Note  that the byte size may
     affect the way certain devices work.  For example, opening a
     terminal  with  a  byte size of 8 will cause I/O to occur in
     binary mode.

   - DEFAULT gives you STRING-CHAR.  STRING-CHAR represents 7-bit
                                                                    16


     ASCII characters.  This is the normal Tops-20 representation
     for text.

   - RENAME and RENAME-AND-DELETE rename the file to have a  file
     type of "LISP-BACKUP".  If there is more than one version of
     the file, they are all renamed.  



3.7.2. Representation of files and lines


The file model that Common Lisp uses is very  close  to  the  DEC-20's
actual  file  model.  Thus most I/O is quite straightforward.  TOPS-20
files have user-determined byte size.  All I/O is  done  in  terms  of
these  bytes.   The file length as shown in a VDIRECTORY command gives
the number of bytes.  This all corresponds nicely to Common Lisp.  The
Common  Lisp  OPEN  function allows you to specify the byte size to be
used for the file.  FILE-LENGTH returns the file size in these  bytes.
NB:    FILE-LENGTH  will use the byte size that you specified when you
OPENed the file.  If you are reading an existing file, this might  not
be the same as the byte size used to write the file.  Thus FILE-LENGTH
might not return the same result as the length  shown  in  VDIRECTORY.
If  you  don't specify the byte size in OPEN, it will be 7 bits, which
is the normal byte size for text files.

Random-access is also quite simple.  Tops-20 stores  files  as  simple
character  streams.    So if you do (FILE-POSITION file 23), Lisp will
position the file after the 23'rd byte.   As  with  FILE-LENGTH,  Lisp
will  use the byte size you specified when you OPENed the file.  As in
Common Lisp, end of line is indicated in a TOPS-20 file by  characters
in  the text.  So if your lines are different lengths there is no easy
way to position to the Nth  line.    It  is  common  for  programs  to
maintain  an  index  into  the  file.   You can build such an index by
calling FILE-POSITION when you are writing the file, to tell you where
the  object  you  are about to write will go.  You can also arrange to
pad short lines with extra characters, so that all lines are the  same
length.    WARNING:  Lines will be longer in the file than they are in
Lisp, because end of line is one character in Lisp,  but  two  in  the
file.  See the next paragraph for details.

Unfortunately  there  is  a slight discrepancy between Common Lisp and
TOPS-20 conventions regarding end of line.   The  Common  Lisp  manual
specifies   that  lines  are  terminated  by  a  single  end  of  line
characters,  referred  to  as  NEWLINE.    TOPS-20  normally  uses   a
two-character  sequence:    carriage  return (CR) followed by linefeed
(LF).  Thus Lisp has to turn CR/LF into NEWLINE  when  reading  files,
and  NEWLINE  into  CR/LF  when  writing  them.  The manual allows the
implementor  to  choose  the  character  code  for  NEWLINE,  but   it
recommends   octal   12,   which   is   LF.   We  have  followed  that
recommendation.  Any  possible  choice  has  its  consequences.    The
consequences  of  this  one is that a Lisp program will not be able to
tell the difference between CRLF and a bare LF in a file.   Both  will
show  up as a single NEWLINE character.  If you really have to be able
to tell what your end of line  is,  you  should  read  the  file  with
                                                                    17


READ-BYTE.  This treats CR and LF just like any other character.



3.7.3. Device handling


Lisp  has  three  different sets of I/O routines for handling external
files.  (There are also routines  for  reading  from  and  writing  to
strings and the EMACS buffer.)  When you OPEN a file, Lisp will choose
the set of routines to use based on the the of device involved.



3.7.3.1. Disk files


If the file is on disk, Lisp will normally use a set of  I/O  routines
that  use the PMAP JSYS.  These routines are capable of random access,
using FILE-POSITION.  They will do I/O using any byte  size  that  you
specify  in the OPEN.  In a few cases PMAP is not possible.  If you to
append to a file for which you have  append-only  access,  of  if  you
write to a file for which you have write-only access, the PMAP JSYS is
not allowed.  In this case, another set of routines is used.  They use
BIN and BOUT for each character individually.



3.7.3.2. Terminals


If  OPEN  is  done  to  a  terminal,  there are several possibilities.
Normally, input is done with the TEXTI  JSYS  and  output  with  BOUT.
TEXTI  implements  the  normal  TOPS-20 terminal handling conventions,
including special actions for rubout, ^R, ^U, and ^W.    In  order  to
allow this editing, it keeps characters in a buffer until you type and
end of line character (normally carriage return, but  line  feed,  ^Z,
^L,  and  escape  also activiate it).  The Lisp program starts reading
from the buffer once you have typed the end of line.   At  that  point
you  can  no longer make changes on that line.  If you print a prompt,
Lisp will automatically put it into the ^R buffer for the  next  read.
That is, you can do something like 

      (PRINC "LISP>") (READ)

What you will see on the terminal is a prompt 

      LISP>

with the cursor waiting for input on the same line.  If you type ^R or
^U, the LISP> will remain at the beginning of the  line.    Lisp  will
keep putting input and output into the ^R buffer as long as you remain
on the same line.  This is done on a stream by stream basis.   If  you
open  a  second  stream  on  the same terminal, you should not print a
prompt from one stream and read the results  from  the  other  stream.
                                                                    18


(Such  a  sequence would work, however ^R would not show the prompt in
the right way.)

Because output is done using BOUT for each  character.    Thus  output
will  show up on your terminal as soon as you generate it.  You do not
need to do anything special to force buffers to be written.

If you OPEN a terminal with  a  byte  size  of  8  (by  specifying  an
ELEMENT-TYPE  of  SIGNED-BYTE  or  UNSIGNED-BYTE),  this has a special
meaning to both the operating system and Lisp.    A  byte  size  of  8
implies  "binary  mode".  In this mode there is no echoing, and normal
character processing (e.g. rubout and  ^U)  is  not  done.    In  some
circumstances  it  is  even  possible to read ^C in binary mode.  Lisp
handles terminals opened this way by using simple BIN and BOUT  jsyses
for each character.

The  choice  between  normal and binary mode is made when you open the
file, on the basis of whether or not you specify a  byte  size  of  8.
You  cannot  change  between  these  modes  once  the  file is opened.
However if you open a terminal normally,  you  can  use  the  function
SET-TERMINAL-MODES  to  change  some of its parameters.  These include
the equivalent of the EXEC commands  TERMINAL  WIDTH,  TERMINAL  PAUSE
END-OF-PAGE,  TERMINAL  ECHO,  and RECEIVE/REFUSE SYSTEM MESSAGES.  In
addition, you can enable or disable PASS-ALL,  TRANSLATE,  and  ESCAPE
modes, which have no equivalent in the EXEC.  

   - PASS-ALL  mode  is  very  similar to the effect of opening a
     terminal for 8-bit I/O.  It allows your program to read  and
     write  any  character.    ^C  and other interrupt characters
     become normal data characters.  ECHO is still  done,  unless
     you  have  disabled  it  with  SET-TERMINAL-MODES.   In many
     cases, PASS-ALL mode is not really required.    If  all  you
     want  is  to  be  able  to  output escapes and other control
     characters, disabling TRANSLATE is often enough.

   - TRANSLATE mode  causes  control  characters  to  echo  as  ^
     followed  by  a  letter, and escape as $. If you disable it,
     then your program can output any character.

   - ESCAPE mode is a designed to allow you to  read  the  escape
     sequences  produced by terminals with special function keys.
     When it is turned on, Lisp handles the escape key specially.
     When  it  sees  an  escape,  it expects one of these special
     escape sequences.  It does not  echo  the  escape,  nor  the
     characters  that  make  up  the  escape  sequence.   When it
     reaches the end of the escape sequence,  it  activates  your
     program,  as  it  would have if you had typed an end of line
     character. At the moment ESCAPE mode has no  effect  if  you
     are already in PASS-ALL mode.  
                                                                    19


3.7.3.3. Other devices


If you OPEN something that is neither a disk nor a terminal, Lisp will
use the BIN and BOUT monitor calls.  It will do a  separate  call  for
each character you read or write.  These are TOPS-20's general-purpose
device-independent I/O calls, so the results  should  be  satisfactory
for  most  devices.    However  there is no special handling for tape,
networks, or other devices.
                                                                    20


       4. Reference Manual - Additional Functions and Features



This section contains documentation for all functions and options that
are not part of standard Spice Lisp.

(APROPOS string &OPTIONAL package)

(APROPOS-LIST string &OPTIONAL package)
          When  package  is omitted, these will search all symbols, as
          documented  in  the  manual,  except  that  they  will  omit
          internal  symbols  of the LISP and COMPILER packages.  These
          symbols are presumably of no signficance to  the  user,  and
          clutter   up  the  output.    If  you  really  want  to  see
          everything, T as a package argument will cause it to look at
          all  packages.   Mentioning a specific package causes all of
          its symbols  to  be  searched,  as  well  as  externals  all
          packages  that it uses.  (The manual is ambiguous as to what
          is meant by supplying a package argument.)

(COMPILE-FILE filename &KEY :OUTPUT-FILE)
          The compiler is just as  documented  in  the  manual.    The
          default  output  file  spec  is  the same as the input spec,
          except with the extension .LAP.  Currently,  output  of  the
          compiler  is  a form of assembly language.  Shortly, we will
          be implementing a binary format, so users should not  depend
          upon the format of the .LAP file.

(DDT) --> NIL
          Go into DDT.  To exit, type IRET$X.  (See also section 3.6.)

(ED thing)

(EDIT thing)
          See section 3.5 for documentation on the editor.  EDIT is an
          additional function.  It is just like  ED,  except  that  it
          does not evaluate its argument.

(SYS:EDITOR-BUFFER-SIZE integer) --> size
          Make  sure  the  buffer  has  at  least  the specified space
          (number of character) for insertion.  This space is made  at
          the EMACS "point".  If no buffer exists, creates one.  If no
          EMACS fork exists, create one.  Returns the actual  size  of
          the gap, which is at least as big as what was ask for.

(SYS:EDITOR-CALL-FORK integer) --> AC3
          Calls the FSsuperior code in EMACS, passing it INTEGER as an
          argument.  Returns what EMACS returns in AC3.  This  is  not
          the normal way to call EMACS.  See EDITOR-RUN-FORK.  This is
          used to call a special kludge in EMACS.  Create a  fork  and
          buffer if none exists.

(SYS:EDITOR-CLEAR-BUFFER) --> NIL
          Clear the EMACS buffer.  Set point to beginning and make the
                                                                    21


          buffer be zero size.

(SYS:EDITOR-CLIP-BUFFER &OPTIONAL stream)
          Use this when you are  finished  writing  into  the  buffer,
          before  calling  EMACS.    It updates some status variables.
          They are invalid between the  call  to  EDITOR-WRITE-CHANNEL
          and  the  call  to  EDITOR-CLIP-BUFFER.   Do not do any more
          writing after calling this function.  If STREAM is  NIL  (or
          not given), the current output stream is used.

(SYS:EDITOR-CREATE-FORK)
          Make  sure you have a valid editor fork and buffer.  Differs
          form EDITOR-GET-FORK in that is calls EMACS with 0FSExit  if
          needed to create a buffer, whereas EDITOR-GET-FORK just gets
          the fork without starting it, so there  is  no  buffer  yet.
          No-op if there is already a fork and buffer.

(SYS:EDITOR-GET-FORK)
          Gets  a  fork  and  puts  EMACS  into it.  Doesn't start it.
          No-op if there is already a fork.

(SYS:EDITOR-KILL-FORK) --> NIL
          Kills the  editor  fork,  i.e.  makes  the  fork  and  EMACS
          completely go away.

(SYS:EDITOR-MODIFIED-P) --> T or NIL
          Returns T if the editor buffer is modifed, else NIL.

(SYS:EDITOR-READ-CHANNEL) --> stream
          Returns  an  I/O  stream such that if you read from it, your
          input comes for the EMACS buffer.  It is set up to start  at
          the  "virtual  beginning" of the buffer, and give EOF at the
          "virtual end".  An ESCAPE will be provided  as  the  N+1  st
          character  if  you  try  to read beyond the end.  Illegal if
          there is no EMACS fork.

(SYS:EDITOR-RUN-FORK small-number) --> AC3
          If SMALL-NUMBER is a small number, start the editor fork  at
          that offset in it's entry vector, else if it is NIL continue
          the fork if it has been started (or start it at entry vector
          offset 0).  In any case, wait for it to stop, and return the
          value EMACS puts into AC3.

(SYS:EDITOR-SET-JCL string) --> the string
          Sets the STRING into the RSCAN buffer.

(SYS:EDITOR-SET-MODIFIED switch) --> switch
          If the SWITCH is T, sets the editor buffer as modified.   If
          NIL, sets the editor buffer as not modifed.

(SYS:EDITOR-WRITE-CHANNEL) --> stream
          Creates  a  stream such that if you write to it, your output
          goes into the EMACS buffer.   Certain  status  variables  in
          EMACS   will  be  temporarily  invalid  after  this.    Call
          EDITOR-CLIP-BUFFER when you are  finished  writing  to  make
                                                                    22


          them  good  again.   the stream is set to that things output
          are inserted after the EMACS "point".

*FEATURES* - variable
          The following "features" are true  in  this  implementation.
          Thus  you  can  use  any  of  them  in  a  #+  test:  COMMON
          DECSYSTEM-20 TOPS-20.

*GC-TRIGGER* - variable
          A variable, initialized to 1.0.  This controls the how often
          a  garbage  collection  will happen.  At the end of each GC,
          all used space is compact.  A certain amount of space  above
          this compact, used space is then allocated for the system to
          grow in until the next GC.  This  is  called  "free  space".
          Free  space  is  computed  as  the  number  of  words used *
          GCTRIGGER.  GCTRIGGER should normally be  a  floating  point
          number  between  0  and  2.    The default is 1.0.  You will
          always get at least 64000 words of free space, even  if  the
          calculation just documented leads to a smaller number.

(GET-TERMINAL-MODES stream) --> mode list 
          Returns  a  list  of  terminal  parameters, of the following
          form:  (:BROADCAST T  :ECHO  T  :ESCAPE  NIL  :PASS-ALL  NIL
          :PAUSE  T  :TRANSLATE T :WRAP 80) See SET-TERMINAL-MODES for
          the meaning of these parameters.  STREAM must  be  a  stream
          that  has  been opened on a terminal for character I/O (i.e.
          not :ELEMENT-TYPE '(UNSIGNED-BYTE 8)).

(KILL-EDITOR)
          Kills the subfork that has EMACS in it.  You may  find  this
          necessary  if  EMACS  because  unusable  for  one  reason or
          another.

(LOAD filename :PACKAGE package)
          LOAD takes an additional keyword, :PACKAGE.  This  specifies
          the package into which the file will be loaded.  If the file
          contains package specifications of its own, they  will  take
          precedence.    This keyword simply rebinds *PACKAGE* for the
          duration of the LOAD.

#\NEWLINE - a character
          See  section  3.7.2  for  a  description  of   the   newline
          convention that this implementation follows.

(OPEN file)
          See  section  3.7.1  for documentation on the effects of the
          various  OPEN  options.    Various  other  I/O  details  are
          discussed in the sections following that one.

*PRINT-GC-INFO* - variable
          A  variable,  initialized to NIL.  It you set it to non-NIL,
          the garbage collector will print a message showing the total
          amount  of  free  space  used  before  and after the garbage
          collection. The difference between these quantities  is  the
          amount of garbage that was removed.
                                                                    23


*PROMPT* - variable
          A  variable,  initialized  to  "CL>".  The default top level
          uses this is its prompt.

(SAVE filename &OPTIONAL greeting-message) --> NIL
          Saves your entire core image  on  the  file  specified.  The
          filename  should  probably  end  in  .EXE.  This function is
          similar to the SAVE command in the EXEC.  However you should
          use  this  function instead of the EXEC's command, since the
          EXEC's command will not save the registers.  Note  that  you
          need  lots  of  disk space to use SAVE.  The base core image
          (with just Common Lisp) is currently over 700 pages.

          If you specify a greeting-message, it will be PRINC'ed  when
          the core image is started.

(SET-TERMINAL-MODES stream &key parameters) --> NIL
          This function allows you to control the way Lisp will handle
          the terminal.  STREAM must be a stream that has been  opened
          on  a  terminal  for  character  I/O (i.e. not :ELEMENT-TYPE
          '(UNSIGNED-BYTE 8)). In many cases these setting will affect
          all  processes  using  the particular terminal, not just the
          particular stream that  is  set.    Here  are  the  possible
          parameters.  Unless  otherwise  stated, the default is taken
          from the way your terminal is set up when you enter Lisp.  

               :BROADCAST
                    non-NIL  if  you  want  your  terminal  to receive
                    messages such as [You have  mail  from  ...],  and
                    SEND's  from  other  users.  NIL to suppress these
                    messages.    Note  that  a  privileged  user   can
                    override  this setting.  Changing this affects all
                    users of this terminal.

               :ECHO
                    non-NIL  for  input  that you type to be "echoed",
                    assuming that you are on a  full-duplex  terminal.
                    (On  half-duplex terminals, the system never echos
                    input.)  NIL turns off this  echo.  Changing  this
                    seems to affect other streams open on the terminal
                    within Lisp, but not other processes than use  it,
                    except  in  PASS-ALL  mode,  where it affects only
                    that one stream.  Default is T.

               :ESCAPE
                    non-NIL  if you want escape sequences sent by ANSI
                    terminals to be treated as  terminators.    Within
                    this,   it   is  moderately  hard  to  read  these
                    sequences.  The problem  is  that  Lisp  does  not
                    normally  process  input  until you type carriage-
                    return,  line-feed,  escape,  form-feed,  or   ^Z.
                    However  typically  you want an escape sequence to
                    be processed immediately.  This mode causes  input
                    to  be  processed  as  soon  as  a complete escape
                    sequence is seen.    It  also  turns  off  echoing
                                                                    24


                    during  processing  of  the  escape sequence.  The
                    escape sequences  recognized  are  a  superset  of
                    those  accepted by the ESCAPE option in VMS.  This
                    includes  all  legal  ANSI  escape   and   control
                    sequences,  plus most of the sequences sent by the
                    older VT52-compatible  terminals.    This  affects
                    only  the  one  stream  for  which  you  issue it.
                    Default is NIL.  Escape processing currently  does
                    not work for pass-all mode.

               :PASS-ALL
                    non-NIL if you want  to  be  able  to  treat  most
                    special  characters  as  ordinary data.  With this
                    turned on, rubout, ^U,  etc.,  are  just  ordinary
                    characaters  for  input.   Also, output characters
                    are sent as is.  That is,  escape  is  not  turned
                    into   dollar   sign,   control-X  into  ^X,  etc.
                    Interrupt characters, such as ^C, will be  treated
                    as  normal data characters.  This affects only the
                    one stream for which you  issue  it,  except  that
                    interrupt   characters   are  turned  on  and  off
                    globally.  Default is NIL.  If echoing  is  turned
                    on,   you   had  better  have  opened  the  stream
                    :DIRECTION  :IO,  since  Lisp  will  have  do  the
                    echoing explicitly.

               :PAUSE
                    non-NIL if you want the system to wait for ^Q each
                    time  it fills your screen.  This is equivalent to
                    TERM PAUSE END-OF-PAGE in the EXEC.  Changing this
                    affects all users of this terminal.

               :TRANSLATE
                    non-NIL if you want control characters and  escape
                    to  be  translated  on output.  That is, a control
                    character appears as ^ followed by a  letter,  and
                    escape  appears  as  $.    NIL  if  you want these
                    characters  to  be  sent  as  themselves.     With
                    :TRANSLATE NIL, the setting of TERM TAB or TERM NO
                    TAB is still obeyed.  That is, if your terminal is
                    shown  as  having  no  tabs,  tabs are turned into
                    spaces.  The default is :TRANSLATE T.

               :WRAP
                    non-NIL  if  you  want  the  system  to  supply  a
                    carriage-return line-feed when it  thinks  it  has
                    reached  the  right margin of your terminal.  This
                    is  equivalent  to  TERM  WIDTH  x  in  the  EXEC.
                    Turning  the  feature  off  (NIL) is equivalent to
                    TERM WIDTH 0.  It  is  somewhat  unfortunate  that
                    there  is  no  way to turn this off without losing
                    the terminal width parameter.   If  you  know  the
                    terminal width, you can specify it as the argument
                    to turn wrapping back on. For example, you can say
                    (SET-TERMINAL-MODES  TERM  :WRAP  80).   Lisp will
                                                                    25


                    remember the terminal width that was present  when
                    you  opened the terminal, if it was non-zero.  (If
                    it was zero, Lisp uses a width of  80.)    If  you
                    specify  an  argument  of  T,  Lisp  will use this
                    remembered value.

               others
                    This  function  specifically ignores keywords that
                    it   does   not   know   about,   because    other
                    implementations  of  Lisp  may have other keywords
                    that do not make sense on a DECSYSTEM-20.  

          It is sometimes convenient to save an old terminal state, as
          returned  by GET-TERMINAL-MODES, and then reset it.  To make
          this easier, SET-TERMINAL-MODES may  also  be  used  in  the
          form:  

              (SET-TERMINAL-MODES term modes)

          In  this  case,  modes  is a list of keyword-value pairs, as
          returned by GET-TERMINAL-MODES.

(STEP form)
          For documentation on the STEP facility, see section 3.4.

(%TOP-LEVEL) - never returns
          For documentation on customizing the top level, see  section
          3.6.

(TRACE function)
          For documentation on the TRACE facility, see section 3.3.
                                                                    26


          5. Differences between Spice Lisp and Common Lisp



The  section  is  really  intended for the benefit of implementors and
maintainers.  It describes the general nature of the changes  we  have
had  to  make to the Spice Lisp system code in order to use it as part
of Common Lisp.  Such changes should not be necessary for  user  code,
so this should not affect normal users.

Unfortunately,  we  have  not  been able to use very many of the Spice
Lisp files unmodified.  However in many cases the changes take only  5
minutes  or  so  to  put in.  In general, our data representations are
quite similar.  %SP-TYPE converts the internal data type code  to  the
correct  Spice Lisp type number.  Thus there are few changes necessary
due to differences in types.  Most of the changes are due to the  fact
that  we  implement  more  in the kernel than Spice Lisp implements in
microcode.  Here are the major things to  look  for  in  converting  a
file:

   - Look  for (PRIMITIVE and %SP-.  Spice Lisp is in the process
     of changing its primitives.  Some of them  are  %SP-foo  and
     others  are  (PRIMITIVE foo).  We have normally used the old
     %SP names, although we  have  HEADER-REF  and  HEADER-LENGTH
     without  the  %SP.    We do not have PRIMITIVE at all.  When
     Spice  Lisp  changes  completely  to  using  the  (PRIMITIVE
     format,  we  should  define PRIMITIVE as a macro. This would
     eliminate a lot of the conversion.

   - Look for code of the form (DEFUN CAR (X) (CAR X)).  This  is
     used   to  provide  Lisp  definitions  for  the  Spice  Lisp
     primitives.  Since  our  kernel  uses  normal  Lisp  calling
     conventions,  such definitions are not needed, and should be
     deleted.

   - Look for functions that we define  in  the  kernel.    Large
     parts   of   HASH,   EVAL,  PRINT,  READ,  and  FILESYS  are
     implemented in the kernel.  We have tried to  be  consistent
     with  Spice  Lisp  in  the  function  names that we used for
     kernel code.   So  often  you  just  have  to  remove  those
     functions  that are already in the kernel.  In some cases it
     was inconvenient to do all of the argument processing in the
     kernel,  so  I supply a small Lisp function to do that.  For
     example, most of OPEN is in the  kernel.    But  the  kernel
     function  is  called  %SP-OPEN.  In FILESYS.CLISP the actual
     OPEN is defined in Lisp.  It simply does some defaulting and
     then  calls %SP-OPEN.  Arithmetic is done almost entirely in
     the kernel.

   - Some of the functions, particularly in FILESYS and MISC, are
     inherently system-dependent.

   - Some of our changes are simply bug fixes.