BSD 4_1c_2 development

Work on file usr/src/ucb/lisp/lisplib/manual/ch8.r
Work on file usr/src/ucb/lisp/lisplib/manual/ch9.r
Work on file usr/src/ucb/lisp/lisplib/manual/ch10.r
Work on file usr/src/ucb/lisp/lisplib/manual/ch11.r

Synthesized-from: CSRG/cd1/4.1c.2

diff --git a/usr/src/ucb/lisp/lisplib/manual/ch10.r b/usr/src/ucb/lisp/lisplib/manual/ch10.r
new file mode 100644 (file)
index 0000000..5fa2025
--- /dev/null
+++ b/usr/src/ucb/lisp/lisplib/manual/ch10.r
@@ -0,0 +1,262 @@
+
+
+
+
+
+
+
+                        C\bC\bC\bCH\bH\bH\bHA\bA\bA\bAP\bP\bP\bPT\bT\bT\bTE\bE\bE\bER\bR\bR\bR  1\b1\b1\b10\b0\b0\b0
+
+
+                     E\bE\bE\bEx\bx\bx\bxc\bc\bc\bce\be\be\bep\bp\bp\bpt\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bn H\bH\bH\bHa\ba\ba\ban\bn\bn\bnd\bd\bd\bdl\bl\bl\bli\bi\bi\bin\bn\bn\bng\bg\bg\bg
+
+
+
+
+
+
+
+1\b1\b1\b10\b0\b0\b0.\b.\b.\b.1\b1\b1\b1.\b.\b.\b.  E\bE\bE\bEr\br\br\brr\br\br\brs\bs\bs\bse\be\be\bet\bt\bt\bt a\ba\ba\ban\bn\bn\bnd\bd\bd\bd E\bE\bE\bEr\br\br\brr\br\br\bro\bo\bo\bor\br\br\br H\bH\bH\bHa\ba\ba\ban\bn\bn\bnd\bd\bd\bdl\bl\bl\ble\be\be\ber\br\br\br F\bF\bF\bFu\bu\bu\bun\bn\bn\bnc\bc\bc\bct\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bns\bs\bs\bs
+
+     FRANZ LISP allows the user to handle  in  a  number  of
+ways  the errors which arise during computation.  One way is
+through the use of the _\be_\br_\br_\bs_\be_\bt function.  If an error  occurs
+during  the  evaluation of the _\be_\br_\br_\bs_\be_\bt's first argument, then
+the locus of control will return to the  errset  which  will
+return  nil  (except  in  special  cases, such as _\be_\br_\br).  The
+other method of error handling is through an  error  handler
+function.  When an error occurs, the error handler is called
+and is given as an argument  a  description   of  the  error
+which  just occurred.  The error handler may take one of the
+following actions:
+
+(1)  it could take some drastic action like  a  _\br_\be_\bs_\be_\bt  or  a
+     _\bt_\bh_\br_\bo_\bw.
+
+(2)  it could,  assuming  that  the  error  is  continuable,
+     return  to  the  function which noticed the error.  The
+     error handler indicates that it wants to return a value
+     from  the  error  by  returning a list whose _\bc_\ba_\br is the
+     value it wants to return.
+
+(3)  it could decide not to handle the error  and  return  a
+     non-list to indicate this fact.
+
+
+
+
+1\b1\b1\b10\b0\b0\b0.\b.\b.\b.2\b2\b2\b2.\b.\b.\b.  T\bT\bT\bTh\bh\bh\bhe\be\be\be A\bA\bA\bAn\bn\bn\bna\ba\ba\bat\bt\bt\bto\bo\bo\bom\bm\bm\bmy\by\by\by o\bo\bo\bof\bf\bf\bf a\ba\ba\ban\bn\bn\bn e\be\be\ber\br\br\brr\br\br\bro\bo\bo\bor\br\br\br
+
+     Each error is described by a list of these items:
+
+(1)  error type - This is a symbol which indicates the  gen-
+     eral  classification of the error.  This classification
+     may determine which function handles this error.
+
+(2)  unique id - This is a fixnum unique to this error.
+
+(3)  continuable - If this is non-nil  then  this  error  is
+     continuable.   There are some who feel that every error
+     should be continuable and the reason that some (in fact
+
+
+E\bE\bE\bEx\bx\bx\bxc\bc\bc\bce\be\be\bep\bp\bp\bpt\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bn H\bH\bH\bHa\ba\ba\ban\bn\bn\bnd\bd\bd\bdl\bl\bl\bli\bi\bi\bin\bn\bn\bng\bg\bg\bg                                      1\b1\b1\b10\b0\b0\b0-\b-\b-\b-1\b1\b1\b1
+
+
+
+
+
+
+
+E\bE\bE\bEx\bx\bx\bxc\bc\bc\bce\be\be\bep\bp\bp\bpt\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bn H\bH\bH\bHa\ba\ba\ban\bn\bn\bnd\bd\bd\bdl\bl\bl\bli\bi\bi\bin\bn\bn\bng\bg\bg\bg                                      1\b1\b1\b10\b0\b0\b0-\b-\b-\b-2\b2\b2\b2
+
+
+     most)  errors  in FRANZ LISP are not continuable is due
+     to the laziness of the programmers.
+
+(4)  message string - This is a symbol whose print  name  is
+     a message describing the error.
+
+(5)  data - There may be from  zero  to  three  lisp  values
+     which  help describe this particular  error.  For exam-
+     ple, the unbound  variable  error  contains  one  datum
+     value,  the  symbol  whose  value is unbound.  The list
+     describing that error might look like:
+            (ER%misc 0 t |Unbound Variable:| foobar)
+
+
+
+
+1\b1\b1\b10\b0\b0\b0.\b.\b.\b.3\b3\b3\b3.\b.\b.\b.  E\bE\bE\bEr\br\br\brr\br\br\bro\bo\bo\bor\br\br\br h\bh\bh\bha\ba\ba\ban\bn\bn\bnd\bd\bd\bdl\bl\bl\bli\bi\bi\bin\bn\bn\bng\bg\bg\bg a\ba\ba\bal\bl\bl\blg\bg\bg\bgo\bo\bo\bor\br\br\bri\bi\bi\bit\bt\bt\bth\bh\bh\bhm\bm\bm\bm
+
+     This is the sequence of operations which is  done  when
+an error occurs:
+
+(1)  If the symbol E\bE\bE\bER\bR\bR\bR%\b%\b%\b%a\ba\ba\bal\bl\bl\bll\bl\bl\bl has a  non  nil  value  then  this
+     value  is  the name of an error handler function.  That
+     function is called with a description of the error.  If
+     that  function returns (and of course it may choose not
+     to) and the value is a list and this error is  continu-
+     able,  then  we return the _\bc_\ba_\br of the list to the func-
+     tion which called the error.  Presumably  the  function
+     will  use  this  value  to retry the operation.  On the
+     other hand, if the error handler returns  a  non  list,
+     then  it has chosen not to handle this error, so  we go
+     on to step (2).  Something special  happens  before  we
+     call  the E\bE\bE\bER\bR\bR\bR%\b%\b%\b%a\ba\ba\bal\bl\bl\bll\bl\bl\bl error handler which does not happen in
+     any of the other cases we will describe below.  To help
+     insure  that  we  don't get infinitely recursive errors
+     if E\bE\bE\bER\bR\bR\bR%\b%\b%\b%a\ba\ba\bal\bl\bl\bll\bl\bl\bl is set to a bad value, the value of E\bE\bE\bER\bR\bR\bR%\b%\b%\b%a\ba\ba\bal\bl\bl\bll\bl\bl\bl is
+     set  to  nil  before the handler is called.  Thus it is
+     the responsibility of the E\bE\bE\bER\bR\bR\bR%\b%\b%\b%a\ba\ba\bal\bl\bl\bll\bl\bl\bl handler to  `reenable'
+     itself by storing its name in E\bE\bE\bER\bR\bR\bR%\b%\b%\b%a\ba\ba\bal\bl\bl\bll\bl\bl\bl.\b.\b.\b.
+
+(2)  Next the specific error handler for the type  of  error
+     which  just  occurred is called  (if one exists) to see
+     if it wants to handle the  error.   The  names  of  the
+     handlers for the specific types of errors are stored as
+     the values of the symbols whose names  are  the  types.
+     For  example  the  handler  for miscellaneous errors is
+     stored as the value of E\bE\bE\bER\bR\bR\bR%\b%\b%\b%m\bm\bm\bmi\bi\bi\bis\bs\bs\bsc\bc\bc\bc.\b.\b.\b.  Of course, if  E\bE\bE\bER\bR\bR\bR%\b%\b%\b%m\bm\bm\bmi\bi\bi\bis\bs\bs\bsc\bc\bc\bc
+     has  a value of nil, then there is no error handler for
+     this type of error.  Appendix B contains  list  of  all
+     error  types.  The process of classifying the errors is
+     not complete and thus most errors are lumped  into  the
+     E\bE\bE\bER\bR\bR\bR%\b%\b%\b%m\bm\bm\bmi\bi\bi\bis\bs\bs\bsc\bc\bc\bc  category.   Just  as  in  step  (1), the error
+     handler function may choose not to handle the error  by
+
+
+                                     Printed: March 23, 1982
+
+
+
+
+
+
+
+E\bE\bE\bEx\bx\bx\bxc\bc\bc\bce\be\be\bep\bp\bp\bpt\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bn H\bH\bH\bHa\ba\ba\ban\bn\bn\bnd\bd\bd\bdl\bl\bl\bli\bi\bi\bin\bn\bn\bng\bg\bg\bg                                      1\b1\b1\b10\b0\b0\b0-\b-\b-\b-3\b3\b3\b3
+
+
+     returning a non-list, and then we go to step (3).
+
+(3)  Next a check is made to see if there is an _\be_\br_\br_\bs_\be_\bt  sur-
+     rounding  this error.  If so the second argument to the
+     _\be_\br_\br_\bs_\be_\bt call is examined. If the second argument was not
+     given  or  is non nil then the error message associated
+     with this error is  printed.   Finally   the  stack  is
+     popped to the context of the _\be_\br_\br_\bs_\be_\bt and then the _\be_\br_\br_\bs_\be_\bt
+     returns nil.  If there was no _\be_\br_\br_\bs_\be_\bt we go to step (4).
+
+(4)  If the symbol E\bE\bE\bER\bR\bR\bR%\b%\b%\b%t\bt\bt\btp\bp\bp\bpl\bl\bl\bl has a value then it is the name of
+     an error handler which is called in a manner similar to
+     that discussed above.  If it chooses not to handle  the
+     error, we go to step (5).
+
+(5)  At this point it has  been  determined  that  the  user
+     doesn't want to handle this error.  Thus the error mes-
+     sage is printed out and a _\br_\be_\bs_\be_\bt is  done  to  send  the
+     flow of control to the top-level.
+
+     To summarize the error handling system: When  an  error
+occurs,  you have two chances to handle it before the search
+for an _\be_\br_\br_\bs_\be_\bt is done.  Then, if there  is  no  _\be_\br_\br_\bs_\be_\bt,  you
+have  one  more  chance  to  handle the error before control
+jumps to the top level.  Every  error handler works  in  the
+same  way:  It  is  given  a  description  of  the error (as
+described in the previous  section).   It  may  or  may  not
+return.   If  it returns, then it returns either a list or a
+non-list.  If it returns a list and the  error  is  continu-
+able,  then  the _\bc_\ba_\br of the list is returned to the function
+which noticed the error.  Otherwise the  error  handler  has
+decided  not  to  handle the error and we go on to something
+else.
+
+
+
+
+1\b1\b1\b10\b0\b0\b0.\b.\b.\b.4\b4\b4\b4.\b.\b.\b.  D\bD\bD\bDe\be\be\bef\bf\bf\bfa\ba\ba\bau\bu\bu\bul\bl\bl\blt\bt\bt\bt a\ba\ba\bai\bi\bi\bid\bd\bd\bds\bs\bs\bs
+
+     There are two standard error handlers  which will prob-
+ably  handle  the  needs of most users.  One of these is the
+lisp coded function _\bb_\br_\be_\ba_\bk-_\be_\br_\br-_\bh_\ba_\bn_\bd_\bl_\be_\br which is  the  default
+value  of E\bE\bE\bER\bR\bR\bR%\b%\b%\b%t\bt\bt\btp\bp\bp\bpl\bl\bl\bl.\b.\b.\b.  Thus when all other handlers have ignored
+an error, _\bb_\br_\be_\ba_\bk-_\be_\br_\br-_\bh_\ba_\bn_\bd_\bl_\be_\br will take over.  It  will  print
+out  the  error  message and go into a read-eval-print loop.
+The other standard error handler is _\bd_\be_\bb_\bu_\bg-_\be_\br_\br-_\bh_\ba_\bn_\bd_\bl_\be_\br.  This
+handler  is  designed to be connected to E\bE\bE\bER\bR\bR\bR%\b%\b%\b%a\ba\ba\bal\bl\bl\bll\bl\bl\bland is useful
+if your program uses _\be_\br_\br_\bs_\be_\bt and you  want  to  look  at  the
+error  before it is thrown up to the _\be_\br_\br_\bs_\be_\bt.
+
+
+
+\e9
+
+\e9                                     Printed: March 23, 1982
+
+
+
+
+
+
+
+E\bE\bE\bEx\bx\bx\bxc\bc\bc\bce\be\be\bep\bp\bp\bpt\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bn H\bH\bH\bHa\ba\ba\ban\bn\bn\bnd\bd\bd\bdl\bl\bl\bli\bi\bi\bin\bn\bn\bng\bg\bg\bg                                      1\b1\b1\b10\b0\b0\b0-\b-\b-\b-4\b4\b4\b4
+
+
+1\b1\b1\b10\b0\b0\b0.\b.\b.\b.5\b5\b5\b5.\b.\b.\b.  A\bA\bA\bAu\bu\bu\but\bt\bt\bto\bo\bo\bol\bl\bl\blo\bo\bo\boa\ba\ba\bad\bd\bd\bdi\bi\bi\bin\bn\bn\bng\bg\bg\bg
+
+     When _\be_\bv_\ba_\bl, _\ba_\bp_\bp_\bl_\by or _\bf_\bu_\bn_\bc_\ba_\bl_\bl are told to call  an  unde-
+fined  function, an E\bE\bE\bER\bR\bR\bR%\b%\b%\b%u\bu\bu\bun\bn\bn\bnd\bd\bd\bde\be\be\bef\bf\bf\bf error is signaled.  The default
+handler for this error is _\bu_\bn_\bd_\be_\bf-_\bf_\bu_\bn_\bc-_\bh_\ba_\bn_\bd_\bl_\be_\br.  This function
+checks  the  property list of the undefined function for the
+indicator autoload.  If present, the value of that indicator
+should be the name of the file which contains the definition
+of the undefined function.  _\bU_\bn_\bd_\be_\bf-_\bf_\bu_\bn_\bc-_\bh_\ba_\bn_\bd_\bl_\be_\br will load the
+file  and  check if it has defined the function which caused
+the error.  If it has, the error handler will return and the
+computation  will  continue  as  if the error did not occur.
+This provides a way for the user to  tell  the  lisp  system
+about  the  location  of commonly used functions.  The trace
+package  sets  up  an  autoload   property   to   point   to
+/usr/lib/lisp/trace.
+
+
+
+
+1\b1\b1\b10\b0\b0\b0.\b.\b.\b.6\b6\b6\b6.\b.\b.\b.  I\bI\bI\bIn\bn\bn\bnt\bt\bt\bte\be\be\ber\br\br\brr\br\br\bru\bu\bu\bup\bp\bp\bpt\bt\bt\bt p\bp\bp\bpr\br\br\bro\bo\bo\boc\bc\bc\bce\be\be\bes\bs\bs\bss\bs\bs\bsi\bi\bi\bin\bn\bn\bng\bg\bg\bg
+
+     The  UNIX operating system provides one user  interrupt
+character which defaults to ^C.[] The user may select a lisp
+function to run when an interrupt occurs.  Since this inter-
+rupt could occur at any time, and in particular could  occur
+at a time when the internal stack pointers were in an incon-
+sistent state,  the  processing  of  the  interrupt  may  be
+delayed  until a safe time.  When the first ^C is typed, the
+lisp  system  sets  a  flag  that  an  interrupt  has   been
+requested.   This flag is  checked at safe places within the
+interpreter and in the _\bq_\bl_\bi_\bn_\bk_\be_\br function.  If the lisp system
+doesn't respond to the first ^C, another ^C should be typed.
+This will cause all of the transfer  tables  to  be  cleared
+forcing  all  calls  from  compiled  code  to go through the
+_\bq_\bl_\bi_\bn_\bk_\be_\br function where the interrupt flag will  be  checked.
+If  the  lisp  system still doesn't respond, a third ^C will
+cause an  immediate  interrupt.   This  interrupt  will  not
+necessarily  be in a safe place so the user should _\br_\be_\bs_\be_\bt the
+lisp system as soon as possible.
+
+
+
+
+
+
+
+
+____________________
+\e9   []Actually there are two but the lisp system does not al-
+low you to catch the QUIT interrupt.
+
+
+
+\e9                                     Printed: March 23, 1982
+
+
+

diff --git a/usr/src/ucb/lisp/lisplib/manual/ch11.r b/usr/src/ucb/lisp/lisplib/manual/ch11.r
new file mode 100644 (file)
index 0000000..0a55318
--- /dev/null
+++ b/usr/src/ucb/lisp/lisplib/manual/ch11.r
@@ -0,0 +1,328 @@
+
+
+
+
+
+
+
+                        CHAPTER  11
+
+
+              The Joseph Lister Trace Package
+
+
+
+
+     The Joseph Lister[] Trace package is an important  tool
+for the interactive debugging of a Lisp program.  It  allows
+you  to  examine selected  calls to a function or functions,
+and optionally to stop execution  of  the  Lisp  program  to
+examine the values of variables.
+
+     The trace package is a set of Lisp programs located  in
+the    Lisp   program   library   (usually   in   the   file
+/usr/lib/lisp/trace.l).  Although not normally loaded in the
+Lisp  system,  the  package will be loaded in when the first
+call to _\bt_\br_\ba_\bc_\be is made.
+
+(trace [ls_arg1 ...])
+
+     WHERE:   the form of the ls_arg_\bi is described below.
+
+     RETURNS: a list of the  function  sucessfully  modified
+              for  tracing.   If  no  arguments are given to
+              _\bt_\br_\ba_\bc_\be, a list of all functions currently being
+              traced is returned.
+
+     SIDE EFFECT: The function definitions of the  functions
+                  to trace are modified.
+
+
+The ls_arg_\bi can have one of the following forms:
+
+
+  foo - when foo is entered and exited, the  trace  informa-
+       tion will be printed.
+
+
+  (foo break) - when foo is entered  and  exited  the  trace
+       information  will  be  printed.  Also, just after the
+       trace information for foo is printed upon entry,  you
+       will  be put in  a special break loop.  The prompt is
+       `T>' and you may type any Lisp  expression,  and  see
+       its  value printed.  The _\bith argument to the function
+       just called can be accessed as (arg _\bi).  To leave the
+       trace   loop,  just  type  ^D  or  (tracereturn)  and
+____________________
+\e9   []_\bL_\bi_\bs_\bt_\be_\br, _\bJ_\bo_\bs_\be_\bp_\bh     1st  Baron  Lister  of  Lyme  Regis,
+1827-1912; English surgeon: introduced antiseptic surgery.
+
+
+
+\e9The Joseph Lister Trace Package                         11-1
+
+
+
+
+
+
+
+The Joseph Lister Trace Package                         11-2
+
+
+       execution will continue.  Note that ^D will work only
+       on UNIX systems.
+
+
+  (foo if expression) - when foo is entered and the  expres-
+       sion evaluates to non-nil, then the trace information
+       will be printed for both exit and entry.  If  expres-
+       sion evaluates to nil, then no trace information will
+       be printed.
+
+
+  (foo ifnot expression) -  when  foo  is  entered  and  the
+       expression  evaluates to nil, then the trace informa-
+       tion will be printed for both  entry  and  exit.   If
+       both  if and _\bi_\bf_\bn_\bo_\bt are specified, then the _\bi_\bf expres-
+       sion must evaluate to non nil AND the  _\bi_\bf_\bn_\bo_\bt  expres-
+       sion  must  evaluate to nil for the trace information
+       to be printed out.
+
+
+  (foo evalin expression) - when foo is  entered  and  after
+       the  entry  trace  information is printed, expression
+       will be evaluated. Exit  trace  information  will  be
+       printed when foo exits.
+
+
+  (foo evalout expression) -  when  foo  is  entered,  entry
+       trace  information  will be printed.  When foo exits,
+       and before the exit  trace  information  is  printed,
+       expression will be evaluated.
+
+
+  (foo evalinout expression) - this has the same  effect  as
+       (trace (foo evalin expression evalout expression)).
+
+
+  (foo lprint) - this tells _\bt_\br_\ba_\bc_\be to use the  level  printer
+       when  printing  the arguments to and the result of  a
+       call to foo.  The level printer prints only  the  top
+       levels  of  list structure. Any structure below three
+       levels is printed as a &.  This allows you  to  trace
+       functions with massive arguments or results.
+
+
+
+          The following trace options  permit  one  to  have
+     greater control over each action which takes place when
+     a function is traced.  These options are only meant  to
+     be used by people who need special hooks into the trace
+     package.  Most people should skip reading this section.
+
+
+  (foo traceenter  tefunc)  -  this  tells  _\bt_\br_\ba_\bc_\be  that  the
+
+
+                                     Printed: March 23, 1982
+
+
+
+
+
+
+
+The Joseph Lister Trace Package                         11-3
+
+
+       function  to be called when foo is entered is tefunc.
+       tefunc should be a lambda of two arguments, the first
+       argument  will  be  bound to the name of the function
+       being traced, foo in this case.  The second  argument
+       will  be  bound to the list of arguments to which foo
+       should be applied.  The function tefunc should  print
+       some  sort  of "entering foo" message.  It should not
+       apply foo to the arguments,  however.  That  is  done
+       later on.
+
+
+  (foo traceexit txfunc) - this tells _\bt_\br_\ba_\bc_\be that  the  func-
+       tion  to  be  called  when  foo  is exited is txfunc.
+       txfunc should be a lambda of two arguments, the first
+       argument  will  be  bound to the name of the function
+       being traced, foo in this case.  The second  argument
+       will  be bound to the result of the call to foo.  The
+       function txfunc should print some  sort  of  "exiting
+       foo" message.
+
+
+  (foo evfcn evfunc) - this tells _\bt_\br_\ba_\bc_\be that the form evfunc
+       should  be  evaluated to get the value of foo applied
+       to its arguments. This option is a bit different from
+       the  other  special options since evfunc will usually
+       be an expression, not just the name  of  a  function,
+       and  that  expression will be specific to the evalua-
+       tion of  function  foo.   The  argument  list  to  be
+       applied will be available as T-arglist.
+
+
+  (foo printargs prfunc) - this tells _\bt_\br_\ba_\bc_\be to  used  prfunc
+       to print the arguments  to be applied to the function
+       foo.  prfunc should be a lambda of one argument.  You
+       might  want  to use this option if you wanted a print
+       function which could  handle  circular  lists.   This
+       option  will work only if you do not specify your own
+       _\bt_\br_\ba_\bc_\be_\be_\bn_\bt_\be_\br function.  Specifying the option _\bl_\bp_\br_\bi_\bn_\bt is
+       just  a simple way of changing the printargs function
+       to the level printer.
+
+
+  (foo printres prfunc) - this tells _\bt_\br_\ba_\bc_\be to use prfunc  to
+       print the result of evaluating foo.  prfunc should be
+       a lambda of one argument.  This option will work only
+       if  you  do  not specify your own _\bt_\br_\ba_\bc_\be_\be_\bx_\bi_\bt function.
+       Specifying the option _\bl_\bp_\br_\bi_\bn_\bt changes printres to  the
+       level printer.
+
+
+
+          You may specify more  than  one  option  for  each
+     function traced. For example:
+
+
+                                     Printed: March 23, 1982
+
+
+
+
+
+
+
+The Joseph Lister Trace Package                         11-4
+
+
+     (_\bt_\br_\ba_\bc_\be (_\bf_\bo_\bo _\bi_\bf (_\be_\bq _\b3 (_\ba_\br_\bg _\b1)) _\bb_\br_\be_\ba_\bk _\bl_\bp_\br_\bi_\bn_\bt) (_\bb_\ba_\br _\be_\bv_\ba_\bl_\bi_\bn
+     (_\bp_\br_\bi_\bn_\bt _\bx_\by_\bz_\bz_\by)))
+
+     This tells _\bt_\br_\ba_\bc_\be to trace two more functions,  foo  and
+     bar.   Should  foo be called with the first argument _\be_\bq
+     to 3, then the entering foo  message  will  be  printed
+     with  the  level  printer.   Next it will enter a trace
+     break loop, allowing you to evaluate any  lisp  expres-
+     sions.  When you exit the trace break loop, foo will be
+     applied to its arguments and the resulting  value  will
+     be printed, again using the level printer.  Bar is also
+     traced, and each time bar is entered, an  entering  bar
+     message  will  be  printed  and then the value of xyzzy
+     will be printed.  Next bar will be applied to its argu-
+     ments  and  the  result  will  be printed.  If you tell
+     _\bt_\br_\ba_\bc_\be to trace a function which is already  traced,  it
+     will  first  _\bu_\bn_\bt_\br_\ba_\bc_\be  it.   Thus if you want to specify
+     more than one trace option for a function, you must  do
+     it all at once.  The following is _\bn_\bo_\bt equivalent to the
+     preceding call to _\bt_\br_\ba_\bc_\be for foo:
+
+     (_\bt_\br_\ba_\bc_\be (_\bf_\bo_\bo  _\bi_\bf  (_\be_\bq  _\b3  (_\ba_\br_\bg  _\b1)))  (_\bf_\bo_\bo  _\bb_\br_\be_\ba_\bk)  (_\bf_\bo_\bo
+     _\bl_\bp_\br_\bi_\bn_\bt))
+
+     In this example, only the last option, lprint, will  be
+     in effect.
+
+          If the symbol $tracemute is given a non nil value,
+     printing  of  the  function name and arguments on entry
+     and exit will be surpressed.  This is particularly use-
+     ful  if  the  function you are tracing fails after many
+     calls to it.  In this case  you  would  tell  _\bt_\br_\ba_\bc_\be  to
+     trace  the function, set $tracemute to t, and begin the
+     computation.  When an error occurs  you  can  use  _\bt_\br_\ba_\b-
+     _\bc_\be_\bd_\bu_\bm_\bp to print out the current trace frames.
+
+          Generally the trace package has its  own  internal
+     names  for  the the lisp functions it uses, so that you
+     can feel free to trace system functions like  _\bc_\bo_\bn_\bd  and
+     not worry about adverse interaction with the actions of
+     the trace package.  You can trace any type of function:
+     lambda,  nlambda,  lexpr  or  macro whether compiled or
+     interpreted and you can  even  trace  array  references
+     (however  you  should  not attempt to store in an array
+     which has been traced).
+
+          When tracing compiled code keep in mind that  many
+     function  calls  are  translated  directly  to  machine
+     language  or other equivalent  function calls.  A  full
+     list of open coded functions is listed at the beginning
+     of  the  liszt  compiler  source.   _\bT_\br_\ba_\bc_\be  will  do   a
+     (_\bs_\bs_\bt_\ba_\bt_\bu_\bs _\bt_\br_\ba_\bn_\bs_\bl_\bi_\bn_\bk _\bn_\bi_\bl)  to  insure that the new traced
+     definitions it defines are called instead  of  the  old
+
+
+                                     Printed: March 23, 1982
+
+
+
+
+
+
+
+The Joseph Lister Trace Package                         11-5
+
+
+     untraced  ones.  You may notice that compiled code will
+     run slower after this is done.
+
+(traceargs s_func [x_level])
+
+     WHERE:   if x_level is missing it is assumed to be 1.
+
+     RETURNS: the arguments to the x_level_\bt_\bh call to  traced
+              function s_func are returned.
+
+(tracedump)
+
+     SIDE EFFECT: the  currently  active  trace  frames  are
+                  printed  on  the terminal.  returns a list
+                  of functions untraced.
+
+(untrace [s_arg1 ...])
+
+     RETURNS: a list of the functions which were untraced.
+
+     NOTE: if no arguments  are  given,  all  functions  are
+           untraced.
+
+     SIDE EFFECT: the old function definitions of all traced
+                  functions  are restored except in the case
+                  where it appears that the current  defini-
+                  tion  of  a  function  was  not created by
+                  trace.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+\e9
+
+\e9                                     Printed: March 23, 1982
+
+
+

diff --git a/usr/src/ucb/lisp/lisplib/manual/ch8.r b/usr/src/ucb/lisp/lisplib/manual/ch8.r
new file mode 100644 (file)
index 0000000..ac18185
--- /dev/null
+++ b/usr/src/ucb/lisp/lisplib/manual/ch8.r
@@ -0,0 +1,913 @@
+
+
+
+
+
+
+
+                         C\bC\bC\bCH\bH\bH\bHA\bA\bA\bAP\bP\bP\bPT\bT\bT\bTE\bE\bE\bER\bR\bR\bR  8\b8\b8\b8
+
+
+                    F\bF\bF\bFu\bu\bu\bun\bn\bn\bnc\bc\bc\bct\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bns\bs\bs\bs a\ba\ba\ban\bn\bn\bnd\bd\bd\bd M\bM\bM\bMa\ba\ba\bac\bc\bc\bcr\br\br\bro\bo\bo\bos\bs\bs\bs
+
+
+
+
+
+
+
+8\b8\b8\b8.\b.\b.\b.1\b1\b1\b1.\b.\b.\b.  v\bv\bv\bva\ba\ba\bal\bl\bl\bli\bi\bi\bid\bd\bd\bd f\bf\bf\bfu\bu\bu\bun\bn\bn\bnc\bc\bc\bct\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bn o\bo\bo\bob\bb\bb\bbj\bj\bj\bje\be\be\bec\bc\bc\bct\bt\bt\bts\bs\bs\bs
+
+     There are many different objects which can  occupy  the
+function  field  of  a  symbol  object.  The following table
+shows all of the possibilities, how to  recognize  them  and
+where to look for documentation.
+
+
+\e8_____________________________________________________________
+  informal name           object type         documentation
+\e8_____________________________________________________________\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b_____________________________________________________________
+   interpreted           list with _\bc_\ba_\br             8.2
+ lambda function         _\be_\bq to lambda
+\e8_____________________________________________________________
+   interpreted           list with _\bc_\ba_\br             8.2
+ nlambda function        _\be_\bq to nlambda
+\e8_____________________________________________________________
+   interpreted           list with _\bc_\ba_\br             8.2
+  lexpr function          _\be_\bq to lexpr
+\e8_____________________________________________________________
+   interpreted           list with _\bc_\ba_\br             8.3
+      macro               _\be_\bq to macro
+\e8_____________________________________________________________
+     compiled       binary with discipline         8.2
+ lambda or lexpr         _\be_\bq to lambda
+     function
+\e8_____________________________________________________________
+     compiled       binary with discipline         8.2
+ nlambda function        _\be_\bq to nlambda
+\e8_____________________________________________________________
+     compiled       binary with discipline         8.3
+      macro               _\be_\bq to macro
+\e8_____________________________________________________________
+     foreign        binary with discipline         8.4
+    subroutine         of "subroutine"[]
+\e8_____________________________________________________________
+     foreign        binary with discipline         8.4
+     function           of "function"[]
+\e8_____________________________________________________________
+     foreign        binary with discipline         8.4
+ integer function   of "integer-function"[]
+\e8_____________________________________________________________
+     foreign        binary with discipline         8.4
+  real function      of "real-function"[]
+\e8_____________________________________________________________
+      array              array object               9
+\e8_____________________________________________________________
+\e7\b|\b\e8|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+\e9                 |\b\e8|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+\e9                                           |\b\e8|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+\e9                                                            |\b\e8|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+\e9\e9
+
+\e9F\bF\bF\bFu\bu\bu\bun\bn\bn\bnc\bc\bc\bct\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bns\bs\bs\bs a\ba\ba\ban\bn\bn\bnd\bd\bd\bd M\bM\bM\bMa\ba\ba\bac\bc\bc\bcr\br\br\bro\bo\bo\bos\bs\bs\bs                                     8\b8\b8\b8-\b-\b-\b-1\b1\b1\b1
+
+
+
+
+
+
+
+F\bF\bF\bFu\bu\bu\bun\bn\bn\bnc\bc\bc\bct\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bns\bs\bs\bs a\ba\ba\ban\bn\bn\bnd\bd\bd\bd M\bM\bM\bMa\ba\ba\bac\bc\bc\bcr\br\br\bro\bo\bo\bos\bs\bs\bs                                     8\b8\b8\b8-\b-\b-\b-2\b2\b2\b2
+
+
+8\b8\b8\b8.\b.\b.\b.2\b2\b2\b2.\b.\b.\b.  f\bf\bf\bfu\bu\bu\bun\bn\bn\bnc\bc\bc\bct\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bns\bs\bs\bs
+
+     The basic lisp function is the lambda function.  When a
+lambda   function   is  called,  the  actual  arguments  are
+evaluated from left to right and  are  lambda-bound  to  the
+formal parameters of the lambda function.
+
+     An nlambda function is usually used for functions which
+are  invoked  by the user at top level.  Some built-in func-
+tions which evaluate their arguments  in  special  ways  are
+also  nlambdas (e.g _\bc_\bo_\bn_\bd, _\bd_\bo, _\bo_\br).  When an nlambda function
+is called, the list of unevaluated arguments is lambda bound
+to the single formal parameter of the nlambda function.
+
+     Some programmers will use an nlambda function when they
+are  not  sure  how many arguments will be passed.  Then the
+first thing the nlambda function does is map _\be_\bv_\ba_\bl  over  the
+list  of  unevaluated arguments it has been passed.  This is
+usually the wrong thing to do as it won't work  compiled  if
+any of the arguments are local variables. The solution is to
+use a lexpr.  When a lexpr function is called, the arguments
+are  evaluated  and  a  fixnum  whose value is the number of
+arguments is lambda-bound to the single formal parameter  of
+the  lexpr  function.  The lexpr then accesses the arguments
+using the _\ba_\br_\bg function.
+
+     When a function is compiled, _\bs_\bp_\be_\bc_\bi_\ba_\bl  declarations  may
+be  needed  to  preserve  its  behavior.  An argument is not
+lambda-bound to the name of the corresponding formal parame-
+ter  unless  that formal parameter has been declared _\bs_\bp_\be_\bc_\bi_\ba_\bl
+(see 12.3.2.2).
+
+     Lambda and lexpr functions both compile into  a  binary
+object  with  a  discipline  of lambda.  However, a compiled
+lexpr still acts like an interpreted lexpr.
+
+
+
+
+8\b8\b8\b8.\b.\b.\b.3\b3\b3\b3.\b.\b.\b.  m\bm\bm\bma\ba\ba\bac\bc\bc\bcr\br\br\bro\bo\bo\bos\bs\bs\bs
+
+     An important features of Lisp is its ability to manipu-
+late  programs  as  data.   As  a  result of this, most Lisp
+implementations have very powerful  macro  facilities.   The
+Lisp  language's  macro  facility can be used to incorporate
+popular features of the  other  languages  into  Lisp.   For
+example,  there are macro packages which allow one to create
+records (ala Pascal) and refer to elements of those  records
+____________________
+\e9   []Only the first character of the string  is  significant
+(i.e "s" is ok for "subroutine")
+
+
+
+\e9                                     Printed: March 23, 1982
+
+
+
+
+
+
+
+F\bF\bF\bFu\bu\bu\bun\bn\bn\bnc\bc\bc\bct\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bns\bs\bs\bs a\ba\ba\ban\bn\bn\bnd\bd\bd\bd M\bM\bM\bMa\ba\ba\bac\bc\bc\bcr\br\br\bro\bo\bo\bos\bs\bs\bs                                     8\b8\b8\b8-\b-\b-\b-3\b3\b3\b3
+
+
+by the key names.[] Another  popular use for  macros  is  to
+create  more  readable  control structures which expand into
+_\bc_\bo_\bn_\bd, _\bo_\br and _\ba_\bn_\bd.  One such example is the If macro  in  the
+jkfmacs.l package.  It allows you to write
+
+(_\bI_\bf (_\be_\bq_\bu_\ba_\bl _\bn_\bu_\bm_\bb _\b0) _\bt_\bh_\be_\bn (_\bp_\br_\bi_\bn_\bt '_\bz_\be_\br_\bo) (_\bt_\be_\br_\bp_\br)
+ _\be_\bl_\bs_\be_\bi_\bf (_\be_\bq_\bu_\ba_\bl _\bn_\bu_\bm_\bb _\b1) _\bt_\bh_\be_\bn (_\bp_\br_\bi_\bn_\bt '_\bo_\bn_\be) (_\bt_\be_\br_\bp_\br)
+ _\be_\bl_\bs_\be (_\bp_\br_\bi_\bn_\bt '|_\bI _\bg_\bi_\bv_\be _\bu_\bp|))
+
+which expands to
+
+(_\bc_\bo_\bn_\bd
+    ((_\be_\bq_\bu_\ba_\bl _\bn_\bu_\bm_\bb _\b0) (_\bp_\br_\bi_\bn_\bt '_\bz_\be_\br_\bo) (_\bt_\be_\br_\bp_\br))
+    ((_\be_\bq_\bu_\ba_\bl _\bn_\bu_\bm_\bb _\b1) (_\bp_\br_\bi_\bn_\bt '_\bo_\bn_\be) (_\bt_\be_\br_\bp_\br))
+    (_\bt (_\bp_\br_\bi_\bn_\bt '|_\bI _\bg_\bi_\bv_\be _\bu_\bp|)))
+
+
+
+
+
+8\b8\b8\b8.\b.\b.\b.3\b3\b3\b3.\b.\b.\b.1\b1\b1\b1.\b.\b.\b.  m\bm\bm\bma\ba\ba\bac\bc\bc\bcr\br\br\bro\bo\bo\bo f\bf\bf\bfo\bo\bo\bor\br\br\brm\bm\bm\bms\bs\bs\bs
+
+     A macro is a function which accepts a  Lisp  expression
+as  input  and  returns another Lisp expression.  The action
+the macro takes is called macro expansion.  Here is a simple
+example:
+
+-> (_\bd_\be_\bf _\bf_\bi_\br_\bs_\bt (_\bm_\ba_\bc_\br_\bo (_\bx) (_\bc_\bo_\bn_\bs '_\bc_\ba_\br (_\bc_\bd_\br _\bx))))
+first
+-> (_\bf_\bi_\br_\bs_\bt '(_\ba _\bb _\bc))
+a
+-> (_\ba_\bp_\bp_\bl_\by '_\bf_\bi_\br_\bs_\bt '(_\bf_\bi_\br_\bs_\bt '(_\ba _\bb _\bc)))
+(car '(a b c))
+
+The first input line defines a macro called  _\bf_\bi_\br_\bs_\bt.   Notice
+that  the  macro  has one formal parameter, _\bx. On the second
+input   line,   we   ask   the   interpreter   to   evaluate
+(_\bf_\bi_\br_\bs_\bt '(_\ba _\bb _\bc)).   _\bE_\bv_\ba_\bl  sees  that  _\bf_\bi_\br_\bs_\bt  has  a function
+definition of type macro  so it evaluates _\bf_\bi_\br_\bs_\bt's definition
+passing  to  _\bf_\bi_\br_\bs_\bt  as  an argument the form _\be_\bv_\ba_\bl itself was
+trying to evaluate: (_\bf_\bi_\br_\bs_\bt '(_\ba _\bb _\bc)).  The _\bf_\bi_\br_\bs_\bt macro chops
+off  the  car  of  the argument with _\bc_\bd_\br, cons' a _\bc_\ba_\br at the
+beginning of the list and returns (_\bc_\ba_\br '(_\ba _\bb _\bc)).  Now  _\be_\bv_\ba_\bl
+evaluates  that, and the value is _\ba which is returned as the
+value of (_\bf_\bi_\br_\bs_\bt '(_\ba _\bb _\bc)).   Thus  whenever  _\be_\bv_\ba_\bl  tries  to
+evaluate  a list whose car has a macro definition it ends up
+doing (at least) two operations, one is a call to the  macro
+____________________
+\e9   []A record definition macro package especially suited for
+FRANZ  LISP  is in the planning stages at Berkeley.  At this
+time the Maclisp _\bs_\bt_\br_\bu_\bc_\bt package can be used.
+
+
+
+\e9                                     Printed: March 23, 1982
+
+
+
+
+
+
+
+F\bF\bF\bFu\bu\bu\bun\bn\bn\bnc\bc\bc\bct\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bns\bs\bs\bs a\ba\ba\ban\bn\bn\bnd\bd\bd\bd M\bM\bM\bMa\ba\ba\bac\bc\bc\bcr\br\br\bro\bo\bo\bos\bs\bs\bs                                     8\b8\b8\b8-\b-\b-\b-4\b4\b4\b4
+
+
+to let it macro expand  the  form,  and  the  other  is  the
+evaluation  of  the  result of the macro.  The result of the
+macro may be yet another call to a macro, so _\be_\bv_\ba_\bl  may  have
+to  do  even more evaluations until it can finally determine
+the  value of an expression.  One way to  see  how  a  macro
+will expand is to use _\ba_\bp_\bp_\bl_\by as shown on the third input line
+above.
+
+
+
+
+8\b8\b8\b8.\b.\b.\b.3\b3\b3\b3.\b.\b.\b.2\b2\b2\b2.\b.\b.\b.  d\bd\bd\bde\be\be\bef\bf\bf\bfm\bm\bm\bma\ba\ba\bac\bc\bc\bcr\br\br\bro\bo\bo\bo
+
+     The macro _\bd_\be_\bf_\bm_\ba_\bc_\br_\bo makes it  easier  to  define  macros
+because  it  allows  you  to name the arguments to the macro
+call.  For example, suppose we find ourselves often  writing
+code  like (_\bs_\be_\bt_\bq _\bs_\bt_\ba_\bc_\bk (_\bc_\bo_\bn_\bs _\bn_\be_\bw_\be_\bl_\bt _\bs_\bt_\ba_\bc_\bk).  We could define
+a macro named _\bp_\bu_\bs_\bh to do this for us.  One way to define  it
+is:
+
+-> (_\bd_\be_\bf _\bp_\bu_\bs_\bh
+      (_\bm_\ba_\bc_\br_\bo (_\bx) (_\bl_\bi_\bs_\bt '_\bs_\be_\bt_\bq (_\bc_\ba_\bd_\bd_\br _\bx) (_\bl_\bi_\bs_\bt '_\bc_\bo_\bn_\bs (_\bc_\ba_\bd_\br _\bx) (_\bc_\ba_\bd_\bd_\br _\bx)))))
+push
+
+then (_\bp_\bu_\bs_\bh _\bn_\be_\bw_\be_\bl_\bt _\bs_\bt_\ba_\bc_\bk) will expand to the  form  mentioned
+above.  The same macro written using defmacro would be:
+
+-> (_\bd_\be_\bf_\bm_\ba_\bc_\br_\bo _\bp_\bu_\bs_\bh (_\bv_\ba_\bl_\bu_\be _\bs_\bt_\ba_\bc_\bk) (_\bl_\bi_\bs_\bt '_\bs_\be_\bt_\bq _\bs_\bt_\ba_\bc_\bk (_\bl_\bi_\bs_\bt '_\bc_\bo_\bn_\bs _\bv_\ba_\bl_\bu_\be _\bs_\bt_\ba_\bc_\bk))
+push
+
+Defmacro allows you to name the arguments of the macro call,
+and  makes  the  macro  definition look more like a function
+definition.
+
+
+
+
+8\b8\b8\b8.\b.\b.\b.3\b3\b3\b3.\b.\b.\b.3\b3\b3\b3.\b.\b.\b.  t\bt\bt\bth\bh\bh\bhe\be\be\be b\bb\bb\bba\ba\ba\bac\bc\bc\bck\bk\bk\bkq\bq\bq\bqu\bu\bu\buo\bo\bo\bot\bt\bt\bte\be\be\be c\bc\bc\bch\bh\bh\bha\ba\ba\bar\br\br\bra\ba\ba\bac\bc\bc\bct\bt\bt\bte\be\be\ber\br\br\br m\bm\bm\bma\ba\ba\bac\bc\bc\bcr\br\br\bro\bo\bo\bo
+
+     The default syntax for FRANZ LISP has four   characters
+with associated character macros.  One is semicolon for com-
+ments.  Two others are the backquote  and  comma  which  are
+used  by  the  backquote character macro.  The fourth is the
+sharp sign macro described in the next section.
+
+     The backquote macro is used to create lists where  many
+of  the elements are fixed (quoted). This makes it very use-
+ful for creating macro definitions.  In the simplest case, a
+backquote acts just like a single quote:
+
+->`(_\ba _\bb _\bc _\bd _\be)
+(a b c d e)
+\e9
+
+\e9                                     Printed: March 23, 1982
+
+
+
+
+
+
+
+F\bF\bF\bFu\bu\bu\bun\bn\bn\bnc\bc\bc\bct\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bns\bs\bs\bs a\ba\ba\ban\bn\bn\bnd\bd\bd\bd M\bM\bM\bMa\ba\ba\bac\bc\bc\bcr\br\br\bro\bo\bo\bos\bs\bs\bs                                     8\b8\b8\b8-\b-\b-\b-5\b5\b5\b5
+
+
+If a comma precedes an element of  a  backquoted  list  then
+that element is evaluated and its value is put in the list.
+
+->(_\bs_\be_\bt_\bq _\bd '(_\bx _\by _\bz))
+(x y z)
+->`(_\ba _\bb _\bc ,_\bd _\be)
+(a b c (x y z) e)
+
+If a comma followed by an at sign precedes an element  in  a
+backquoted  list, then that element is evaluated and spliced
+into the list with _\ba_\bp_\bp_\be_\bn_\bd.
+
+->`(_\ba _\bb _\bc ,@_\bd _\be)
+(a b c x y z e)
+
+Once a list begins with a backquote, the commas  may  appear
+anywhere in the list as this example shows:
+
+->`(_\ba _\bb (_\bc _\bd ,(_\bc_\bd_\br _\bd)) (_\be _\bf (_\bg _\bh ,@(_\bc_\bd_\bd_\br _\bd) ,@_\bd)))
+(a b (c d (y z)) (e f (g h z x y z)))
+
+It is also possible and sometimes even  useful  to  use  the
+backquote  macro within itself.  As a final demonstration of
+the backquote macro, we shall define the first and push mac-
+ros  using  all  the power at our disposal, defmacro and the
+backquote macro.
+
+->(_\bd_\be_\bf_\bm_\ba_\bc_\br_\bo _\bf_\bi_\br_\bs_\bt (_\bl_\bi_\bs_\bt) `(_\bc_\ba_\br ,_\bl_\bi_\bs_\bt))
+first
+->(_\bd_\be_\bf_\bm_\ba_\bc_\br_\bo _\bp_\bu_\bs_\bh (_\bv_\ba_\bl_\bu_\be _\bs_\bt_\ba_\bc_\bk) `(_\bs_\be_\bt_\bq ,_\bs_\bt_\ba_\bc_\bk (_\bc_\bo_\bn_\bs ,_\bv_\ba_\bl_\bu_\be ,_\bs_\bt_\ba_\bc_\bk)))
+stack
+
+
+
+
+8\b8\b8\b8.\b.\b.\b.3\b3\b3\b3.\b.\b.\b.4\b4\b4\b4.\b.\b.\b.  s\bs\bs\bsh\bh\bh\bha\ba\ba\bar\br\br\brp\bp\bp\bp s\bs\bs\bsi\bi\bi\big\bg\bg\bgn\bn\bn\bn c\bc\bc\bch\bh\bh\bha\ba\ba\bar\br\br\bra\ba\ba\bac\bc\bc\bct\bt\bt\bte\be\be\ber\br\br\br m\bm\bm\bma\ba\ba\bac\bc\bc\bcr\br\br\bro\bo\bo\bo
+
+     The sharp sign macro can perform a number of  different
+functions   at  read time.  The character directly following
+the sharp sign determines which function will be  done,  and
+following lisp s-expressions may serve as arguments.
+
+
+
+
+8\b8\b8\b8.\b.\b.\b.3\b3\b3\b3.\b.\b.\b.4\b4\b4\b4.\b.\b.\b.1\b1\b1\b1.\b.\b.\b.  c\bc\bc\bco\bo\bo\bon\bn\bn\bnd\bd\bd\bdi\bi\bi\bit\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bna\ba\ba\bal\bl\bl\bl i\bi\bi\bin\bn\bn\bnc\bc\bc\bcl\bl\bl\blu\bu\bu\bus\bs\bs\bsi\bi\bi\bio\bo\bo\bon\bn\bn\bn
+
+If you plan to run one source file in more than one environ-
+ment then you may want to some pieces of code to be included
+or not included depending on the environment. The C language
+uses  "#ifdef" and "#ifndef" for this purpose, and lisp uses
+"#+" and "#-".  The environment that the  sharp  sign  macro
+checks  is  the  (_\bs_\bt_\ba_\bt_\bu_\bs _\bf_\be_\ba_\bt_\bu_\br_\be_\bs) list which is initialized
+
+
+                                     Printed: March 23, 1982
+
+
+
+
+
+
+
+F\bF\bF\bFu\bu\bu\bun\bn\bn\bnc\bc\bc\bct\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bns\bs\bs\bs a\ba\ba\ban\bn\bn\bnd\bd\bd\bd M\bM\bM\bMa\ba\ba\bac\bc\bc\bcr\br\br\bro\bo\bo\bos\bs\bs\bs                                     8\b8\b8\b8-\b-\b-\b-6\b6\b6\b6
+
+
+when the Lisp system is built  and which may be  altered  by
+(_\bs_\bs_\bt_\ba_\bt_\bu_\bs _\bf_\be_\ba_\bt_\bu_\br_\be _\bf_\bo_\bo)  and  (_\bs_\bs_\bt_\ba_\bt_\bu_\bs _\bn_\bo_\bf_\be_\ba_\bt_\bu_\br_\be _\bb_\ba_\br) The form
+of conditional inclusion is
+                        _\b#_\b+_\bw_\bh_\be_\bn _\bw_\bh_\ba_\bt
+where _\bw_\bh_\be_\bn is either a symbol  or  an  expression  involving
+symbols  and the functions _\ba_\bn_\bd, _\bo_\br, and _\bn_\bo_\bt.  The meaning is
+that _\bw_\bh_\ba_\bt will only be read in if _\bw_\bh_\be_\bn is true.  A symbol in
+_\bw_\bh_\be_\bn  is  true  only  if it appears in the (_\bs_\bt_\ba_\bt_\bu_\bs _\bf_\be_\ba_\bt_\bu_\br_\be_\bs)
+list.
+
+
+    ____________________________________________________
+
+    ; suppose we want to write a program which references a file
+    ; and which can run at ucb, ucsd and cmu where the file naming conventions
+    ; are different.
+    ;
+    -> (_\bd_\be_\bf_\bu_\bn _\bh_\bo_\bw_\bo_\bl_\bd (_\bn_\ba_\bm_\be)
+          (_\bt_\be_\br_\bp_\br)
+          (_\bl_\bo_\ba_\bd #+(_\bo_\br _\bu_\bc_\bb _\bu_\bc_\bs_\bd) "/_\bu_\bs_\br/_\bl_\bi_\bb/_\bl_\bi_\bs_\bp/_\ba_\bg_\be_\bs._\bl"
+                 #+_\bc_\bm_\bu "/_\bu_\bs_\br/_\bl_\bi_\bs_\bp/_\bd_\bo_\bc/_\ba_\bg_\be_\bs._\bl")
+          (_\bp_\ba_\bt_\bo_\bm "_\bH_\be _\bi_\bs ")
+          (_\bp_\br_\bi_\bn_\bt (_\bc_\bd_\br (_\ba_\bs_\bs_\bo_\bc _\bn_\ba_\bm_\be _\ba_\bg_\be_\bf_\bi_\bl_\be)))
+          (_\bp_\ba_\bt_\bo_\bm "_\by_\be_\ba_\br_\bs _\bo_\bl_\bd")
+          (_\bt_\be_\br_\bp_\br))
+    ____________________________________________________
+
+
+
+The form
+                        _\b#_\b-_\bw_\bh_\be_\bn _\bw_\bh_\ba_\bt
+is equivalent to
+                     _\b#_\b+_\b(_\bn_\bo_\bt _\bw_\bh_\be_\bn_\b) _\bw_\bh_\ba_\bt
+
+
+
+
+8\b8\b8\b8.\b.\b.\b.3\b3\b3\b3.\b.\b.\b.4\b4\b4\b4.\b.\b.\b.2\b2\b2\b2.\b.\b.\b.  f\bf\bf\bfi\bi\bi\bix\bx\bx\bxn\bn\bn\bnu\bu\bu\bum\bm\bm\bm c\bc\bc\bch\bh\bh\bha\ba\ba\bar\br\br\bra\ba\ba\bac\bc\bc\bct\bt\bt\bte\be\be\ber\br\br\br e\be\be\beq\bq\bq\bqu\bu\bu\bui\bi\bi\biv\bv\bv\bva\ba\ba\bal\bl\bl\ble\be\be\ben\bn\bn\bnt\bt\bt\bts\bs\bs\bs
+
+When working with fixnum equivalents  of  characters  it  is
+often hard to remember the number corresponding to a charac-
+ter.  The form
+                            _\b#_\b/_\bc
+is equivalent to the fixnum representation of character c.
+
+
+
+
+
+
+
+
+\e9
+
+\e9                                     Printed: March 23, 1982
+
+
+
+
+
+
+
+F\bF\bF\bFu\bu\bu\bun\bn\bn\bnc\bc\bc\bct\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bns\bs\bs\bs a\ba\ba\ban\bn\bn\bnd\bd\bd\bd M\bM\bM\bMa\ba\ba\bac\bc\bc\bcr\br\br\bro\bo\bo\bos\bs\bs\bs                                     8\b8\b8\b8-\b-\b-\b-7\b7\b7\b7
+
+
+
+    ____________________________________________________
+
+    ; a function  which returns t if the user types y else it returns nil.
+    ;
+    -> (_\bd_\be_\bf_\bu_\bn _\by_\be_\bs_\bo_\br_\bn_\bo _\bn_\bi_\bl
+          (_\bp_\br_\bo_\bg_\bn (_\ba_\bn_\bs)
+                 (_\bs_\be_\bt_\bq _\ba_\bn_\bs (_\bt_\by_\bi))
+                 (_\bc_\bo_\bn_\bd ((_\be_\bq_\bu_\ba_\bl _\ba_\bn_\bs #/_\by) _\bt)
+                       (_\bt _\bn_\bi_\bl))))
+    ____________________________________________________
+
+
+
+
+
+
+
+8\b8\b8\b8.\b.\b.\b.3\b3\b3\b3.\b.\b.\b.4\b4\b4\b4.\b.\b.\b.3\b3\b3\b3.\b.\b.\b.  r\br\br\bre\be\be\bea\ba\ba\bad\bd\bd\bd t\bt\bt\bti\bi\bi\bim\bm\bm\bme\be\be\be e\be\be\bev\bv\bv\bva\ba\ba\bal\bl\bl\blu\bu\bu\bua\ba\ba\bat\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bn
+
+Occasionally you want  to  express  a  constant  as  a  lisp
+expression,  yet  you  don't  want  to  pay  the  penalty of
+evaluating this expression each time it is referenced.   The
+form
+                        _\b#_\b._\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn
+evaluates the expression at read time and returns its value.
+
+
+    ____________________________________________________
+
+    ; a function to test if any of bits 1 3 or 12 are set in a fixnum.
+    ;
+    -> (_\bd_\be_\bf_\bu_\bn _\bt_\be_\bs_\bt_\bi_\bt (_\bn_\bu_\bm)
+          (_\bc_\bo_\bn_\bd ((_\bz_\be_\br_\bo_\bp (_\bb_\bo_\bo_\bl_\be _\b1 _\bn_\bu_\bm #.(+ (_\bl_\bs_\bh _\b1 _\b1) (_\bl_\bs_\bh _\b1 _\b3) (_\bl_\bs_\bh _\b1 _\b1_\b2))))
+                 _\bn_\bi_\bl)
+                (_\bt _\bt)))
+    ____________________________________________________
+
+
+
+
+
+
+
+8\b8\b8\b8.\b.\b.\b.4\b4\b4\b4.\b.\b.\b.  f\bf\bf\bfo\bo\bo\bor\br\br\bre\be\be\bei\bi\bi\big\bg\bg\bgn\bn\bn\bn s\bs\bs\bsu\bu\bu\bub\bb\bb\bbr\br\br\bro\bo\bo\bou\bu\bu\but\bt\bt\bti\bi\bi\bin\bn\bn\bne\be\be\bes\bs\bs\bs a\ba\ba\ban\bn\bn\bnd\bd\bd\bd f\bf\bf\bfu\bu\bu\bun\bn\bn\bnc\bc\bc\bct\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bns\bs\bs\bs
+
+     FRANZ LISP has the ability to dynamically  load  object
+files  produced  by  other compilers and then call functions
+defined in those files.  These functions are called  _\bf_\bo_\br_\be_\bi_\bg_\bn
+functions.   There  are  four types of foreign functions and
+they are characterized by the type of result they return:
+
+\e9
+
+\e9                                     Printed: March 23, 1982
+
+
+
+
+
+
+
+F\bF\bF\bFu\bu\bu\bun\bn\bn\bnc\bc\bc\bct\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bns\bs\bs\bs a\ba\ba\ban\bn\bn\bnd\bd\bd\bd M\bM\bM\bMa\ba\ba\bac\bc\bc\bcr\br\br\bro\bo\bo\bos\bs\bs\bs                                     8\b8\b8\b8-\b-\b-\b-8\b8\b8\b8
+
+
+subroutine
+     This does not return anything. The lisp  system  always
+     returns t after calling a subroutine.
+
+function
+     This returns whatever the function returns.  This  must
+     be  a valid lisp object or it may cause the lisp system
+     to fail.
+
+integer-function
+     This returns an integer which  the  lisp  system  makes
+     into a fixnum and returns.
+
+real-function
+     This returns a double precision real number  which  the
+     lisp system makes into a flonum and returns.
+
+A foreign function is accessed through a binary object  just
+like  a  compiled lisp function.  The difference is that the
+discipline field for a binary object of a  foreign  function
+is  a string whose first character is either s for a subrou-
+tine, f for a function, i for an integer-function or r for a
+real-function.   Two  functions are provided for the setting
+up of foreign functions.  _\bC_\bf_\ba_\bs_\bl loads an  object  file  into
+the  lisp  system  and  sets  up one foreign function binary
+object.  If there is more than one  function  in  an  object
+file, _\bg_\be_\bt_\ba_\bd_\bd_\br_\be_\bs_\bs can be used to set up further foreign func-
+tion objects.
+
+     Foreign  functions are called  just  like  other  func-
+tions,  e.g  (_\bf_\bu_\bn_\bn_\ba_\bm_\be _\ba_\br_\bg_\b1 _\ba_\br_\bg_\b2).   When  one is called, the
+arguments are evaluated and then examined.  List,  hunk  and
+symbol  arguments  are passed unchanged to the foreign func-
+tion.  Fixnum and flonum arguments are copied  into  a  tem-
+porary  location  and a pointer to the value is passed (this
+is  because  Fortran  uses  call  by  reference  and  it  is
+dangerous to modify the contents of a fixnum or flonum which
+something else might point to).  If an array  object  is  an
+argument  the  data  field of the array  object is passed to
+the foreign function (this is the easiest way to send  large
+amounts  of data to and receive large amounts of data from a
+foreign function).  If a binary object is an  argument,  the
+entry field of that object is passed to the foreign function
+(the entry field is the  address  of  a  function,  so  this
+amounts to passing a function as an argument).
+
+     The method a foreign function uses to access the  argu-
+ments  provided  by lisp is dependent on the language of the
+foreign function.  The following scripts demonstrate how how
+lisp  can  interact with three languages: C, Pascal and For-
+tran.  C and Pascal have pointer types and the first  script
+shows  how  to use pointers to extract information from lisp
+objects.  There are two functions defined for each language.
+
+
+                                     Printed: March 23, 1982
+
+
+
+
+
+
+
+F\bF\bF\bFu\bu\bu\bun\bn\bn\bnc\bc\bc\bct\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bns\bs\bs\bs a\ba\ba\ban\bn\bn\bnd\bd\bd\bd M\bM\bM\bMa\ba\ba\bac\bc\bc\bcr\br\br\bro\bo\bo\bos\bs\bs\bs                                     8\b8\b8\b8-\b-\b-\b-9\b9\b9\b9
+
+
+The  first  (cfoo  in C, pfoo in Pascal) is given four argu-
+ments, a fixnum, a flonum-block array, a hunk  of  at  least
+two  fixnums  and a list of at least two fixnums.  To demon-
+strate that the  values  were  passed,  each  ?foo  function
+prints  its arguments (or parts of them).  The ?foo function
+then modifies the second element of the  flonum-block  array
+and  returns  a 3 to lisp.  The second function (cmemq in C,
+pmemq in Pascal) acts  just  like  the  lisp  _\bm_\be_\bm_\bq  function
+(except it won't work for fixnums whereas the lisp _\bm_\be_\bm_\bq will
+work for small fixnums).  In the script, typed input  is  in
+b\bb\bb\bbo\bo\bo\bol\bl\bl\bld\bd\bd\bd,  computer  output  is  in  roman  and  comments are in
+_\bi_\bt_\ba_\bl_\bi_\bc.
+
+
+____________________________________________________________
+
+_\bT_\bh_\be_\bs_\be _\ba_\br_\be _\bt_\bh_\be _\bC _\bc_\bo_\bd_\be_\bd _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn_\bs
+% c\bc\bc\bca\ba\ba\bat\bt\bt\bt c\bc\bc\bch\bh\bh\bh8\b8\b8\b8a\ba\ba\bau\bu\bu\bux\bx\bx\bxc\bc\bc\bc.\b.\b.\b.c\bc\bc\bc
+/* demonstration of c coded foreign integer-function */
+
+/* the following will be used to extract fixnums out of a list of fixnums */
+struct listoffixnumscell
+{    struct listoffixnumscell *cdr;
+     int *fixnum;
+};
+
+struct listcell
+{       struct listcell *cdr;
+        int car;
+};
+
+cfoo(a,b,c,d)
+int *a;
+double b[];
+int *c[];
+struct listoffixnumscell *d;
+{
+    printf("a: %d, b[0]: %f, b[1]: %f0, *a, b[0], b[1]);
+    printf(" c (first): %d   c (second): %d0,
+               *c[0],*c[1]);
+    printf(" ( %d %d ... ) ", *(d->fixnum), *(d->cdr->fixnum));
+    b[1] = 3.1415926;
+    return(3);
+}
+
+struct listcell *
+cmemq(element,list)
+int element;
+struct listcell *list;
+{
+   for( ; list && element != list->car ;  list = list->cdr);
+   return(list);
+}
+
+
+                                     Printed: March 23, 1982
+
+
+
+
+
+
+
+F\bF\bF\bFu\bu\bu\bun\bn\bn\bnc\bc\bc\bct\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bns\bs\bs\bs a\ba\ba\ban\bn\bn\bnd\bd\bd\bd M\bM\bM\bMa\ba\ba\bac\bc\bc\bcr\br\br\bro\bo\bo\bos\bs\bs\bs                                    8\b8\b8\b8-\b-\b-\b-1\b1\b1\b10\b0\b0\b0
+
+
+_\bT_\bh_\be_\bs_\be _\ba_\br_\be _\bt_\bh_\be _\bP_\ba_\bs_\bc_\ba_\bl _\bc_\bo_\bd_\be_\bd _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn_\bs
+% c\bc\bc\bca\ba\ba\bat\bt\bt\bt c\bc\bc\bch\bh\bh\bh8\b8\b8\b8a\ba\ba\bau\bu\bu\bux\bx\bx\bxp\bp\bp\bp.\b.\b.\b.p\bp\bp\bp
+type    pinteger = ^integer;
+        realarray = array[0..10] of real;
+        pintarray = array[0..10] of pinteger;
+        listoffixnumscell = record
+                                cdr  : ^listoffixnumscell;
+                                fixnum : pinteger;
+                            end;
+        plistcell = ^listcell;
+        listcell = record
+                      cdr : plistcell;
+                      car : integer;
+                   end;
+
+function pfoo ( var a : integer ;
+                var b : realarray;
+                var c : pintarray;
+                var d : listoffixnumscell) : integer;
+begin
+   writeln(' a:',a, ' b[0]:', b[0], ' b[1]:', b[1]);
+   writeln(' c (first):', c[0]^,' c (second):', c[1]^);
+   writeln(' ( ', d.fixnum^, d.cdr^.fixnum^, ' ...) ');
+   b[1] := 3.1415926;
+   pfoo := 3
+end ;
+
+{ the function pmemq looks for the lisp pointer given as the first argument
+  in the list pointed to by the second argument.
+  Note that we declare " a : integer " instead of " var a : integer " since
+  we are interested in the pointer value instead of what it points to (which
+  could be any lisp object)
+}
+function pmemq( a : integer; list : plistcell) : plistcell;
+begin
+ while (list <> nil) and (list^.car <> a) do list := list^.cdr;
+ pmemq := list;
+end ;
+
+
+_\bT_\bh_\be _\bf_\bi_\bl_\be_\bs _\ba_\br_\be _\bc_\bo_\bm_\bp_\bi_\bl_\be_\bd
+% c\bc\bc\bcc\bc\bc\bc -\b-\b-\b-c\bc\bc\bc c\bc\bc\bch\bh\bh\bh8\b8\b8\b8a\ba\ba\bau\bu\bu\bux\bx\bx\bxc\bc\bc\bc.\b.\b.\b.c\bc\bc\bc
+1.0u 1.2s 0:15 14% 30+39k 33+20io 147pf+0w
+% p\bp\bp\bpc\bc\bc\bc -\b-\b-\b-c\bc\bc\bc c\bc\bc\bch\bh\bh\bh8\b8\b8\b8a\ba\ba\bau\bu\bu\bux\bx\bx\bxp\bp\bp\bp.\b.\b.\b.p\bp\bp\bp
+3.0u 1.7s 0:37 12% 27+32k 53+32io 143pf+0w
+
+
+% l\bl\bl\bli\bi\bi\bis\bs\bs\bsp\bp\bp\bp
+Franz Lisp, Opus 33b
+_\bF_\bi_\br_\bs_\bt _\bt_\bh_\be _\bf_\bi_\bl_\be_\bs _\ba_\br_\be _\bl_\bo_\ba_\bd_\be_\bd _\ba_\bn_\bd _\bw_\be _\bs_\be_\bt _\bu_\bp _\bo_\bn_\be  _\bf_\bo_\br_\be_\bi_\bg_\bn  _\bf_\bu_\bn_\bc_\b-
+_\bt_\bi_\bo_\bn  _\bb_\bi_\bn_\ba_\br_\by.  _\bW_\be _\bh_\ba_\bv_\be _\bt_\bw_\bo _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn_\bs _\bi_\bn _\be_\ba_\bc_\bh _\bf_\bi_\bl_\be _\bs_\bo _\bw_\be _\bm_\bu_\bs_\bt
+_\bc_\bh_\bo_\bo_\bs_\be _\bo_\bn_\be _\bt_\bo _\bt_\be_\bl_\bl _\bc_\bf_\ba_\bs_\bl _\ba_\bb_\bo_\bu_\bt.  _\bT_\bh_\be _\bc_\bh_\bo_\bi_\bc_\be _\bi_\bs _\ba_\br_\bb_\bi_\bt_\br_\ba_\br_\by.
+-> (\b(\b(\b(c\bc\bc\bcf\bf\bf\bfa\ba\ba\bas\bs\bs\bsl\bl\bl\bl '\b'\b'\b'c\bc\bc\bch\bh\bh\bh8\b8\b8\b8a\ba\ba\bau\bu\bu\bux\bx\bx\bxc\bc\bc\bc.\b.\b.\b.o\bo\bo\bo '\b'\b'\b'_\b_\b_\b_c\bc\bc\bcf\bf\bf\bfo\bo\bo\boo\bo\bo\bo '\b'\b'\b'c\bc\bc\bcf\bf\bf\bfo\bo\bo\boo\bo\bo\bo "\b"\b"\b"i\bi\bi\bin\bn\bn\bnt\bt\bt\bte\be\be\beg\bg\bg\bge\be\be\ber\br\br\br-\b-\b-\b-f\bf\bf\bfu\bu\bu\bun\bn\bn\bnc\bc\bc\bct\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bn"\b"\b"\b")\b)\b)\b)
+
+
+                                     Printed: March 23, 1982
+
+
+
+
+
+
+
+F\bF\bF\bFu\bu\bu\bun\bn\bn\bnc\bc\bc\bct\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bns\bs\bs\bs a\ba\ba\ban\bn\bn\bnd\bd\bd\bd M\bM\bM\bMa\ba\ba\bac\bc\bc\bcr\br\br\bro\bo\bo\bos\bs\bs\bs                                    8\b8\b8\b8-\b-\b-\b-1\b1\b1\b11\b1\b1\b1
+
+
+/usr/lib/lisp/nld -N -A /usr/local/lisp -T 63000 ch8auxc.o -e _cfoo -o /tmp/Li7055.0  -lc
+#63000-"integer-function"
+-> (\b(\b(\b(c\bc\bc\bcf\bf\bf\bfa\ba\ba\bas\bs\bs\bsl\bl\bl\bl '\b'\b'\b'c\bc\bc\bch\bh\bh\bh8\b8\b8\b8a\ba\ba\bau\bu\bu\bux\bx\bx\bxp\bp\bp\bp.\b.\b.\b.o\bo\bo\bo '\b'\b'\b'_\b_\b_\b_p\bp\bp\bpf\bf\bf\bfo\bo\bo\boo\bo\bo\bo '\b'\b'\b'p\bp\bp\bpf\bf\bf\bfo\bo\bo\boo\bo\bo\bo "\b"\b"\b"i\bi\bi\bin\bn\bn\bnt\bt\bt\bte\be\be\beg\bg\bg\bge\be\be\ber\br\br\br-\b-\b-\b-f\bf\bf\bfu\bu\bu\bun\bn\bn\bnc\bc\bc\bct\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bn"\b"\b"\b" "\b"\b"\b"-\b-\b-\b-l\bl\bl\blp\bp\bp\bpc\bc\bc\bc"\b"\b"\b")\b)\b)\b)
+/usr/lib/lisp/nld -N -A /tmp/Li7055.0 -T 63200 ch8auxp.o -e _pfoo -o /tmp/Li7055.1 -lpc -lc
+#63200-"integer-function"
+_\bH_\be_\br_\be _\bw_\be _\bs_\be_\bt _\bu_\bp _\bt_\bh_\be _\bo_\bt_\bh_\be_\br _\bf_\bo_\br_\be_\bi_\bg_\bn _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn _\bb_\bi_\bn_\ba_\br_\by _\bo_\bb_\bj_\be_\bc_\bt_\bs
+-> (\b(\b(\b(g\bg\bg\bge\be\be\bet\bt\bt\bta\ba\ba\bad\bd\bd\bdd\bd\bd\bdr\br\br\bre\be\be\bes\bs\bs\bss\bs\bs\bs '\b'\b'\b'_\b_\b_\b_c\bc\bc\bcm\bm\bm\bme\be\be\bem\bm\bm\bmq\bq\bq\bq '\b'\b'\b'c\bc\bc\bcm\bm\bm\bme\be\be\bem\bm\bm\bmq\bq\bq\bq "\b"\b"\b"f\bf\bf\bfu\bu\bu\bun\bn\bn\bnc\bc\bc\bct\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bn"\b"\b"\b" '\b'\b'\b'_\b_\b_\b_p\bp\bp\bpm\bm\bm\bme\be\be\bem\bm\bm\bmq\bq\bq\bq '\b'\b'\b'p\bp\bp\bpm\bm\bm\bme\be\be\bem\bm\bm\bmq\bq\bq\bq "\b"\b"\b"f\bf\bf\bfu\bu\bu\bun\bn\bn\bnc\bc\bc\bct\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bn"\b"\b"\b")\b)\b)\b)
+#6306c-"function"
+_\bW_\be _\bw_\ba_\bn_\bt _\bt_\bo _\bc_\br_\be_\ba_\bt_\be _\ba_\bn_\bd _\bi_\bn_\bi_\bt_\bi_\ba_\bl_\bi_\bz_\be _\ba_\bn _\ba_\br_\br_\ba_\by  _\bt_\bo  _\bp_\ba_\bs_\bs  _\bt_\bo  _\bt_\bh_\be
+_\bc_\bf_\bo_\bo  _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn.  _\bI_\bn _\bt_\bh_\bi_\bs _\bc_\ba_\bs_\be _\bw_\be _\bc_\br_\be_\ba_\bt_\be _\ba_\bn _\bu_\bn_\bn_\ba_\bm_\be_\bd _\ba_\br_\br_\ba_\by _\ba_\bn_\bd
+_\bs_\bt_\bo_\br_\be _\bi_\bt _\bi_\bn _\bt_\bh_\be _\bv_\ba_\bl_\bu_\be _\bc_\be_\bl_\bl _\bo_\bf _\bt_\be_\bs_\bt_\ba_\br_\br.  _\bW_\bh_\be_\bn  _\bw_\be  _\bc_\br_\be_\ba_\bt_\be  _\ba_\bn
+_\ba_\br_\br_\ba_\by  _\bt_\bo  _\bp_\ba_\bs_\bs  _\bt_\bo  _\bt_\bh_\be  _\bP_\ba_\bs_\bc_\ba_\bl _\bp_\br_\bo_\bg_\br_\ba_\bm _\bw_\be _\bw_\bi_\bl_\bl _\bu_\bs_\be _\ba _\bn_\ba_\bm_\be_\bd
+_\ba_\br_\br_\ba_\by _\bj_\bu_\bs_\bt _\bt_\bo _\bd_\be_\bm_\bo_\bn_\bs_\bt_\br_\ba_\bt_\be _\bt_\bh_\be _\bd_\bi_\bf_\bf_\be_\br_\be_\bn_\bt _\bw_\ba_\by _\bt_\bh_\ba_\bt  _\bn_\ba_\bm_\be_\bd  _\ba_\bn_\bd
+_\bu_\bn_\bn_\ba_\bm_\be_\bd _\ba_\br_\br_\ba_\by_\bs _\ba_\br_\be _\bc_\br_\be_\ba_\bt_\be_\bd _\ba_\bn_\bd _\ba_\bc_\bc_\be_\bs_\bs_\be_\bd.
+-> (\b(\b(\b(s\bs\bs\bse\be\be\bet\bt\bt\btq\bq\bq\bq t\bt\bt\bte\be\be\bes\bs\bs\bst\bt\bt\bta\ba\ba\bar\br\br\brr\br\br\br (\b(\b(\b(a\ba\ba\bar\br\br\brr\br\br\bra\ba\ba\bay\by\by\by n\bn\bn\bni\bi\bi\bil\bl\bl\bl f\bf\bf\bfl\bl\bl\blo\bo\bo\bon\bn\bn\bnu\bu\bu\bum\bm\bm\bm-\b-\b-\b-b\bb\bb\bbl\bl\bl\blo\bo\bo\boc\bc\bc\bck\bk\bk\bk 2\b2\b2\b2)\b)\b)\b))\b)\b)\b)
+array[2]
+-> (\b(\b(\b(s\bs\bs\bst\bt\bt\bto\bo\bo\bor\br\br\bre\be\be\be (\b(\b(\b(f\bf\bf\bfu\bu\bu\bun\bn\bn\bnc\bc\bc\bca\ba\ba\bal\bl\bl\bll\bl\bl\bl t\bt\bt\bte\be\be\bes\bs\bs\bst\bt\bt\bta\ba\ba\bar\br\br\brr\br\br\br 0\b0\b0\b0)\b)\b)\b) 1\b1\b1\b1.\b.\b.\b.2\b2\b2\b23\b3\b3\b34\b4\b4\b4)\b)\b)\b)
+1.234
+-> (\b(\b(\b(s\bs\bs\bst\bt\bt\bto\bo\bo\bor\br\br\bre\be\be\be (\b(\b(\b(f\bf\bf\bfu\bu\bu\bun\bn\bn\bnc\bc\bc\bca\ba\ba\bal\bl\bl\bll\bl\bl\bl t\bt\bt\bte\be\be\bes\bs\bs\bst\bt\bt\bta\ba\ba\bar\br\br\brr\br\br\br 1\b1\b1\b1)\b)\b)\b) 5\b5\b5\b5.\b.\b.\b.6\b6\b6\b67\b7\b7\b78\b8\b8\b8)\b)\b)\b)
+5.678
+-> (\b(\b(\b(c\bc\bc\bcf\bf\bf\bfo\bo\bo\boo\bo\bo\bo 3\b3\b3\b38\b8\b8\b85\b5\b5\b5 t\bt\bt\bte\be\be\bes\bs\bs\bst\bt\bt\bta\ba\ba\bar\br\br\brr\br\br\br (\b(\b(\b(h\bh\bh\bhu\bu\bu\bun\bn\bn\bnk\bk\bk\bk 1\b1\b1\b10\b0\b0\b0 1\b1\b1\b11\b1\b1\b1 1\b1\b1\b13\b3\b3\b3 1\b1\b1\b14\b4\b4\b4)\b)\b)\b) '\b'\b'\b'(\b(\b(\b(1\b1\b1\b15\b5\b5\b5 1\b1\b1\b16\b6\b6\b6 1\b1\b1\b17\b7\b7\b7)\b)\b)\b))\b)\b)\b)
+a: 385, b[0]: 1.234000, b[1]: 5.678000
+ c (first): 10   c (second): 11
+ ( 15 16 ... )
+ 3
+_\bN_\bo_\bt_\be _\bt_\bh_\ba_\bt _\bc_\bf_\bo_\bo _\bh_\ba_\bs _\br_\be_\bt_\bu_\br_\bn_\be_\bd _\b3 _\ba_\bs _\bi_\bt _\bs_\bh_\bo_\bu_\bl_\bd.  _\bI_\bt _\ba_\bl_\bs_\bo _\bh_\ba_\bd _\bt_\bh_\be
+_\bs_\bi_\bd_\be  _\be_\bf_\bf_\be_\bc_\bt  _\bo_\bf  _\bc_\bh_\ba_\bn_\bg_\bi_\bn_\bg  _\bt_\bh_\be _\bs_\be_\bc_\bo_\bn_\bd _\bv_\ba_\bl_\bu_\be _\bo_\bf _\bt_\bh_\be _\ba_\br_\br_\ba_\by _\bt_\bo
+_\b3._\b1_\b4_\b1_\b5_\b9_\b2_\b6  _\bw_\bh_\bi_\bc_\bh _\bc_\bh_\be_\bc_\bk _\bn_\be_\bx_\bt.
+-> (\b(\b(\b(f\bf\bf\bfu\bu\bu\bun\bn\bn\bnc\bc\bc\bca\ba\ba\bal\bl\bl\bll\bl\bl\bl t\bt\bt\bte\be\be\bes\bs\bs\bst\bt\bt\bta\ba\ba\bar\br\br\brr\br\br\br 1\b1\b1\b1)\b)\b)\b)
+3.1415926
+
+
+_\bI_\bn _\bp_\br_\be_\bp_\ba_\br_\ba_\bt_\bi_\bo_\bn _\bf_\bo_\br _\bc_\ba_\bl_\bl_\bi_\bn_\bg _\bp_\bf_\bo_\bo _\bw_\be _\bc_\br_\be_\ba_\bt_\be _\ba_\bn _\ba_\br_\br_\ba_\by.
+-> (\b(\b(\b(a\ba\ba\bar\br\br\brr\br\br\bra\ba\ba\bay\by\by\by t\bt\bt\bte\be\be\bes\bs\bs\bst\bt\bt\bt f\bf\bf\bfl\bl\bl\blo\bo\bo\bon\bn\bn\bnu\bu\bu\bum\bm\bm\bm-\b-\b-\b-b\bb\bb\bbl\bl\bl\blo\bo\bo\boc\bc\bc\bck\bk\bk\bk 2\b2\b2\b2)\b)\b)\b)
+array[2]
+-> (\b(\b(\b(s\bs\bs\bst\bt\bt\bto\bo\bo\bor\br\br\bre\be\be\be (\b(\b(\b(t\bt\bt\bte\be\be\bes\bs\bs\bst\bt\bt\bt 0\b0\b0\b0)\b)\b)\b) 1\b1\b1\b1.\b.\b.\b.2\b2\b2\b23\b3\b3\b34\b4\b4\b4)\b)\b)\b)
+1.234
+-> (\b(\b(\b(s\bs\bs\bst\bt\bt\bto\bo\bo\bor\br\br\bre\be\be\be (\b(\b(\b(t\bt\bt\bte\be\be\bes\bs\bs\bst\bt\bt\bt 1\b1\b1\b1)\b)\b)\b) 5\b5\b5\b5.\b.\b.\b.6\b6\b6\b67\b7\b7\b78\b8\b8\b8)\b)\b)\b)
+5.678
+-> (\b(\b(\b(p\bp\bp\bpf\bf\bf\bfo\bo\bo\boo\bo\bo\bo 3\b3\b3\b38\b8\b8\b85\b5\b5\b5 (\b(\b(\b(g\bg\bg\bge\be\be\bet\bt\bt\btd\bd\bd\bd '\b'\b'\b't\bt\bt\bte\be\be\bes\bs\bs\bst\bt\bt\bt)\b)\b)\b) (\b(\b(\b(h\bh\bh\bhu\bu\bu\bun\bn\bn\bnk\bk\bk\bk 1\b1\b1\b10\b0\b0\b0 1\b1\b1\b11\b1\b1\b1 1\b1\b1\b13\b3\b3\b3 1\b1\b1\b14\b4\b4\b4)\b)\b)\b) '\b'\b'\b'(\b(\b(\b(1\b1\b1\b15\b5\b5\b5 1\b1\b1\b16\b6\b6\b6 1\b1\b1\b17\b7\b7\b7)\b)\b)\b))\b)\b)\b)
+ a:       385 b[0]:  1.23400000000000E+00 b[1]:  5.67800000000000E+00
+ c (first):        10 c (second):        11
+ (         15        16 ...)
+3
+-> (\b(\b(\b(t\bt\bt\bte\be\be\bes\bs\bs\bst\bt\bt\bt 1\b1\b1\b1)\b)\b)\b)
+3.1415926
+
+ _\bN_\bo_\bw _\bt_\bo _\bt_\be_\bs_\bt _\bo_\bu_\bt _\bt_\bh_\be _\bm_\be_\bm_\bq'_\bs
+-> (\b(\b(\b(c\bc\bc\bcm\bm\bm\bme\be\be\bem\bm\bm\bmq\bq\bq\bq '\b'\b'\b'a\ba\ba\ba '\b'\b'\b'(\b(\b(\b(b\bb\bb\bb c\bc\bc\bc a\ba\ba\ba d\bd\bd\bd e\be\be\be f\bf\bf\bf)\b)\b)\b))\b)\b)\b)
+(_\ba _\bd _\be _\bf)
+-> (\b(\b(\b(p\bp\bp\bpm\bm\bm\bme\be\be\bem\bm\bm\bmq\bq\bq\bq '\b'\b'\b'e\be\be\be '\b'\b'\b'(\b(\b(\b(a\ba\ba\ba d\bd\bd\bd f\bf\bf\bf g\bg\bg\bg a\ba\ba\ba x\bx\bx\bx)\b)\b)\b))\b)\b)\b)
+_\bn_\bi_\bl
+____________________________________________________________
+
+
+                                     Printed: March 23, 1982
+
+
+
+
+
+
+
+F\bF\bF\bFu\bu\bu\bun\bn\bn\bnc\bc\bc\bct\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bns\bs\bs\bs a\ba\ba\ban\bn\bn\bnd\bd\bd\bd M\bM\bM\bMa\ba\ba\bac\bc\bc\bcr\br\br\bro\bo\bo\bos\bs\bs\bs                                    8\b8\b8\b8-\b-\b-\b-1\b1\b1\b12\b2\b2\b2
+
+
+     The Fortran example will be much shorter since in  For-
+tran   you  can't  follow  pointers  as  you  can  in  other
+languages.  The Fortran function ffoo is given  three  argu-
+ments:  a  fixnum, a fixnum-block array and a flonum.  These
+arguments are printed out to verify that they  made  it  and
+then the first value of the array is modified.  The function
+returns a double precision value which  is  converted  to  a
+flonum  by  lisp  and  printed.   Note  that the entry point
+corresponding to the Fortran  function  ffoo  is  _ffoo_  as
+opposed to the C and Pascal convention of preceding the name
+with an underscore.
+
+____________________________________________________________
+
+
+% c\bc\bc\bca\ba\ba\bat\bt\bt\bt c\bc\bc\bch\bh\bh\bh8\b8\b8\b8a\ba\ba\bau\bu\bu\bux\bx\bx\bxf\bf\bf\bf.\b.\b.\b.f\bf\bf\bf
+        double precision function ffoo(a,b,c)
+        integer a,b(10)
+        double precision c
+        print 2,a,b(1),b(2),c
+2       format(' a=',i4,', b(1)=',i5,', b(2)=',i5,' c=',f6.4)
+        b(1) = 22
+        ffoo = 1.23456
+        return
+        end
+% f\bf\bf\bf7\b7\b7\b77\b7\b7\b7 -\b-\b-\b-c\bc\bc\bc c\bc\bc\bch\bh\bh\bh8\b8\b8\b8a\ba\ba\bau\bu\bu\bux\bx\bx\bxf\bf\bf\bf.\b.\b.\b.f\bf\bf\bf
+ch8auxf.f:
+   ffoo:
+0.9u 1.8s 0:12 22% 20+22k 54+48io 158pf+0w
+% l\bl\bl\bli\bi\bi\bis\bs\bs\bsp\bp\bp\bp
+Franz Lisp, Opus 33b
+-> (\b(\b(\b(c\bc\bc\bcf\bf\bf\bfa\ba\ba\bas\bs\bs\bsl\bl\bl\bl '\b'\b'\b'c\bc\bc\bch\bh\bh\bh8\b8\b8\b8a\ba\ba\bau\bu\bu\bux\bx\bx\bxf\bf\bf\bf.\b.\b.\b.o\bo\bo\bo '\b'\b'\b'_\b_\b_\b_f\bf\bf\bff\bf\bf\bfo\bo\bo\boo\bo\bo\bo_\b_\b_\b_ '\b'\b'\b'f\bf\bf\bff\bf\bf\bfo\bo\bo\boo\bo\bo\bo "\b"\b"\b"r\br\br\bre\be\be\bea\ba\ba\bal\bl\bl\bl-\b-\b-\b-f\bf\bf\bfu\bu\bu\bun\bn\bn\bnc\bc\bc\bct\bt\bt\bti\bi\bi\bio\bo\bo\bon\bn\bn\bn"\b"\b"\b" "\b"\b"\b"-\b-\b-\b-l\bl\bl\blF\bF\bF\bF7\b7\b7\b77\b7\b7\b7 -\b-\b-\b-l\bl\bl\blI\bI\bI\bI7\b7\b7\b77\b7\b7\b7"\b"\b"\b")\b)\b)\b)
+/usr/lib/lisp/nld -N -A /usr/local/lisp -T 63000 ch8auxf.o -e _ffoo_
+-o /tmp/Li11066.0 -lF77 -lI77 -lc
+#6307c-"real-function"
+
+-> (\b(\b(\b(a\ba\ba\bar\br\br\brr\br\br\bra\ba\ba\bay\by\by\by t\bt\bt\bte\be\be\bes\bs\bs\bst\bt\bt\bt f\bf\bf\bfi\bi\bi\bix\bx\bx\bxn\bn\bn\bnu\bu\bu\bum\bm\bm\bm-\b-\b-\b-b\bb\bb\bbl\bl\bl\blo\bo\bo\boc\bc\bc\bck\bk\bk\bk 2\b2\b2\b2)\b)\b)\b)
+array[2]
+-> (\b(\b(\b(s\bs\bs\bst\bt\bt\bto\bo\bo\bor\br\br\bre\be\be\be (\b(\b(\b(t\bt\bt\bte\be\be\bes\bs\bs\bst\bt\bt\bt 0\b0\b0\b0)\b)\b)\b) 1\b1\b1\b10\b0\b0\b0)\b)\b)\b)
+10
+-> (\b(\b(\b(s\bs\bs\bst\bt\bt\bto\bo\bo\bor\br\br\bre\be\be\be (\b(\b(\b(t\bt\bt\bte\be\be\bes\bs\bs\bst\bt\bt\bt 1\b1\b1\b1)\b)\b)\b) 1\b1\b1\b11\b1\b1\b1)\b)\b)\b)
+11
+-> (\b(\b(\b(f\bf\bf\bff\bf\bf\bfo\bo\bo\boo\bo\bo\bo 3\b3\b3\b38\b8\b8\b85\b5\b5\b5 (\b(\b(\b(g\bg\bg\bge\be\be\bet\bt\bt\btd\bd\bd\bd '\b'\b'\b't\bt\bt\bte\be\be\bes\bs\bs\bst\bt\bt\bt)\b)\b)\b) 5\b5\b5\b5.\b.\b.\b.6\b6\b6\b67\b7\b7\b78\b8\b8\b8)\b)\b)\b)
+ a= 385, b(1)=   10, b(2)=   11 c=5.6780
+1.234559893608093
+-> (\b(\b(\b(t\bt\bt\bte\be\be\bes\bs\bs\bst\bt\bt\bt 0\b0\b0\b0)\b)\b)\b)
+22
+
+____________________________________________________________
+
+
+
+\e9
+
+\e9                                     Printed: March 23, 1982
+
+
+

diff --git a/usr/src/ucb/lisp/lisplib/manual/ch9.r b/usr/src/ucb/lisp/lisplib/manual/ch9.r
new file mode 100644 (file)
index 0000000..71fc9fd
--- /dev/null
+++ b/usr/src/ucb/lisp/lisplib/manual/ch9.r
@@ -0,0 +1,321 @@
+
+
+
+
+
+
+
+                         CHAPTER  9
+
+
+                           Arrays
+
+
+
+
+     Arrays in FRANZ LISP provide a programmable data struc-
+ture  access  mechanism.   One  possible  use for FRANZ LISP
+arrays is to implement Maclisp style arrays which are simple
+vectors of fixnums, flonums or general lisp values.  This is
+described in more detail in 9.3 but first we  will  describe
+how array references are handled by the lisp system.
+
+     The structure of an array object is given in 1.3.9  and
+reproduced here for your convenience.
+
+
+\e8_______________________________________________________________
+  Subpart name     Get value   Set value          Type
+
+\e8_______________________________________________________________\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b_______________________________________________________________
+ access function   getaccess   putaccess      binary, list
+                                                or symbol
+\e8_______________________________________________________________
+    auxiliary       getaux      putaux           lispval
+\e8_______________________________________________________________
+      data         arrayref     replace    block of contiguous
+                                  set            lispval
+\e8_______________________________________________________________
+     length        getlength   putlength         fixnum
+\e8_______________________________________________________________
+      delta        getdelta    putdelta          fixnum
+\e8_______________________________________________________________
+\e7\b|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|
+
+
+
+
+
+
+
+
+
+
+                |\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|
+
+
+
+
+
+
+
+
+
+
+                            |\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|
+
+
+
+
+
+
+
+
+
+
+                                        |\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|
+
+
+
+
+
+
+
+
+
+
+                                                              |\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+_\b9._\b1.  _\bg_\be_\bn_\be_\br_\ba_\bl _\ba_\br_\br_\ba_\by_\bs   Suppose  the  evaluator  is  told  to
+evaluate  (_\bf_\bo_\bo _\ba _\bb)  and the function cell of the symbol foo
+contains an array object (which we will  call  foo_arr_obj).
+First  the evaluator will evaluate and stack the values of _\ba
+and _\bb.  Next it will stack  the  array  object  foo_arr_obj.
+Finally  it  will  call  the access function of foo_arr_obj.
+The access function should be a lexpr[] or  a  symbol  whose
+function cell contains a  lexpr.   The  access  function  is
+responsible  for  locating  and  returning  a value from the
+array.  The array access function is free to  interpret  the
+arguments as it wishes.  The Maclisp compatible array access
+function which is provided in the standard FRANZ LISP system
+____________________
+\e9   []A lexpr is a function which accepts any number of argu-
+ments which are evaluated before the function is called.
+
+
+
+Arrays                                                   9-1
+
+
+
+
+
+
+
+Arrays                                                   9-2
+
+
+interprets the arguments as subscripts in the  same  way  as
+languages like Fortran and Pascal.
+
+     The array access function will also be called  upon  to
+store    elements    in    the    array.     For    example,
+(_\bs_\bt_\bo_\br_\be (_\bf_\bo_\bo _\ba _\bb) _\bc) will automatically expand to (foo c a b)
+and  when  the evaluator is called to evaluate this, it will
+evaluate the arguments _\bc, _\bb and _\ba.  Then it will  stack  the
+array  object  (which is stored in the function cell of foo)
+and call the array access function  with  (now)  four  argu-
+ments.   The array access function must be able to tell this
+is a store operation which it can by checking the number  of
+arguments  it  has  been  given  (a  lexpr  can do this very
+easily).
+
+
+
+
+_\b9._\b2.  _\bs_\bu_\bb_\bp_\ba_\br_\bt_\bs _\bo_\bf _\ba_\bn _\ba_\br_\br_\ba_\by _\bo_\bb_\bj_\be_\bc_\bt   An array is  created  by
+allocating  an  array object with _\bm_\ba_\br_\br_\ba_\by and  filling in the
+fields.  Certain lisp functions interpret the values of  the
+subparts of the array object in special ways as described in
+the following text.  Placing illegal values  in  these  sub-
+parts may cause the lisp system to fail.
+
+
+
+
+_\b9._\b2._\b1.  _\ba_\bc_\bc_\be_\bs_\bs _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn   The purpose of the access function
+has  been described above.  The contents of the access func-
+tion should be a lexpr, either a binary (compiled  function)
+or  a  list (interpreted function).  It may also be a symbol
+whose function cell contains a  function  definition.   This
+subpart  is used by _\be_\bv_\ba_\bl, _\bf_\bu_\bn_\bc_\ba_\bl_\bl, and _\ba_\bp_\bp_\bl_\by when evaluating
+array references.
+
+
+
+
+_\b9._\b2._\b2.  _\ba_\bu_\bx_\bi_\bl_\bi_\ba_\br_\by   This can be used for any purpose. If  it
+is  a  list and the first element of that list is the symbol
+unmarked_array then the data subpart will not be  marked  by
+the  garbage collector (this is used in the Maclisp compati-
+ble array package and has the potential for causing  strange
+errors if used incorrectly).
+
+
+
+
+_\b9._\b2._\b3.  _\bd_\ba_\bt_\ba   This is either nil or points to  a  block  of
+data space allocated by _\bs_\be_\bg_\bm_\be_\bn_\bt or _\bs_\bm_\ba_\bl_\bl-_\bs_\be_\bg_\bm_\be_\bn_\bt.
+
+\e9
+
+\e9                                     Printed: March 23, 1982
+
+
+
+
+
+
+
+Arrays                                                   9-3
+
+
+_\b9._\b2._\b4.  _\bl_\be_\bn_\bg_\bt_\bh   This is a fixnum whose value is the  number
+of  elements in the data block.  This is used by the garbage
+collector and by _\ba_\br_\br_\ba_\by_\br_\be_\bf to determine if your index  is  in
+bounds.
+
+
+
+
+_\b9._\b2._\b5.  _\bd_\be_\bl_\bt_\ba   This is a fixnum whose value is  the  number
+of  bytes  in  each element of the data block.  This will be
+four for an array of fixnums or value cells, and  eight  for
+an  array of flonums.  This is used by the garbage collector
+and _\ba_\br_\br_\ba_\by_\br_\be_\bf as well.
+
+
+
+
+_\b9._\b3.  _\bT_\bh_\be _\bM_\ba_\bc_\bl_\bi_\bs_\bp _\bc_\bo_\bm_\bp_\ba_\bt_\bi_\bb_\bl_\be _\ba_\br_\br_\ba_\by _\bp_\ba_\bc_\bk_\ba_\bg_\be
+
+     A Maclisp style array is similar to what  are  know  as
+arrays  in other languages: a block of homogeneous data ele-
+ments which is indexed by one or more integers  called  sub-
+scripts.   The  data elements can be all fixnums, flonums or
+general lisp objects.  An array is created by a call to  the
+function  _\ba_\br_\br_\ba_\by  or  *_\ba_\br_\br_\ba_\by.   The  only  difference is that
+*_\ba_\br_\br_\ba_\by evaluates its arguments.  This call: (_\ba_\br_\br_\ba_\by _\bf_\bo_\bo  _\bt  _\b3
+_\b5)  sets  up  an array called foo of dimensions 3 by 5.  The
+subscripts are zero based. The first element  is  (_\bf_\bo_\bo _\b0 _\b0),
+the  next  is  (_\bf_\bo_\bo _\b0 _\b1)  and  so on up to (_\bf_\bo_\bo _\b2 _\b4).  The t
+indicates a general lisp object array which means each  ele-
+ment  of  foo can be any type.  Each element can be any type
+since all that is stored in the array is a pointer to a lisp
+object,  not the object itself.  _\bA_\br_\br_\ba_\by does this by allocat-
+ing an array object with _\bm_\ba_\br_\br_\ba_\by and then allocating  a  seg-
+ment  of  15  consecutive value cells with _\bs_\bm_\ba_\bl_\bl-_\bs_\be_\bg_\bm_\be_\bn_\bt and
+storing a pointer to that segment in the data subpart of the
+array  object.   The  length  and delta subpart of the array
+object are filled in (with 15 and 4  respectively)  and  the
+access  function  subpart is set to point to the appropriate
+array access function.  In this  case  there  is  a  special
+access function for two dimensional value cell arrays called
+arrac-twoD, and this access function is used.  The auxiliary
+subpart  is set to (t 3 5) which describes the type of array
+and the bounds of the subscripts. Finally this array  object
+is  placed in the function cell of the symbol foo.  Now when
+(_\bf_\bo_\bo _\b1 _\b3) is evaluated, the array access function is invoked
+with  three  arguments: 1, 3 and the array object.  From the
+auxiliary field of the array object it gets a description of
+the  particular  array.   It  then  determines which element
+(_\bf_\bo_\bo _\b1 _\b3) refers to  and uses arrayref to extract that  ele-
+ment.   Since this is an array of value cells, what arrayref
+returns is a value cell whose value is what we want,  so  we
+evaluate  the  value  cell  and  return  it  as the value of
+
+
+                                     Printed: March 23, 1982
+
+
+
+
+
+
+
+Arrays                                                   9-4
+
+
+(_\bf_\bo_\bo _\b1 _\b3).
+
+     In Maclisp the call  (_\ba_\br_\br_\ba_\by _\bf_\bo_\bo _\bf_\bi_\bx_\bn_\bu_\bm _\b2_\b5)  returns  an
+array whose data object is a block of 25 memory words.  When
+fixnums are stored in this array,  the  actual  numbers  are
+stored  instead  of  pointers  to the numbers as are done in
+general lisp object arrays.  This is efficient under Maclisp
+but  inefficient  in FRANZ LISP since every time a value was
+referenced from an array it had to be copied and  a  pointer
+to the copy returned to prevent aliasing[].  Thus t,  fixnum
+and  flonum  arrays  are all implemented in the same manner.
+This should not affect  the  compatibility  of  Maclisp  and
+FRANZ  LISP.   If  there  is an application where a block of
+fixnums or flonums is required, then the exact  same  effect
+of  fixnum  and  flonum arrays in Maclisp can be achieved by
+using fixnum-block and flonum-block arrays.  Such arrays are
+required  if you want to pass a large number of arguments to
+a Fortran or C coded function and then get answers back.
+
+     The Maclisp compatible array package is just one  exam-
+ple  of  how  a  general  array  scheme  can be implemented.
+Another type of array you could implement  would  be  hashed
+arrays.  The subscript could be anything, not just a number.
+The access function would hash the  subscript  and  use  the
+result  to  select an array element.  With the generality of
+arrays also comes extra cost; if you just want a simple vec-
+tor  of  (less  than  128) general lisp objects you would be
+wise to look into using hunks.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+____________________
+\e9   []Aliasing is when  two  variables  are  share  the  same
+storage  location.   For  example  if  the copying mentioned
+weren't done then after (_\bs_\be_\bt_\bq _\bx (_\bf_\bo_\bo _\b2)) was done, the value
+of x and (foo 2) would share the same location.  Then should
+the value of (foo 2) change, x's value would change as well.
+This  is  considered  dangerous and as a result pointers are
+never returned into the data space of arrays.
+
+
+
+\e9                                     Printed: March 23, 1982
+
+
+