BSD 4_3 development

[unix-history] / usr / lib / lisp / manual / ch8.r

                         CHAPTER  8


              Functions, Fclosures, and Macros






   8.1.  valid function objects

           There are many different objects which can occupy
      the  function field of a symbol object.  Table 8.1, on
      the following page, shows all  of  the  possibilities,
      how  to recognize them, and where to look for documen-
      tation.



   8.2.  functions

           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 functions 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 argu-
      ments it has been passed.  This is usually  the  wrong
      thing  to  do,  as it will not 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 can
      then access 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 parameter unless that formal parameter has been
      declared _\bs_\bp_\be_\bc_\bi_\ba_\bl (see 12.3.2.2).


Functions, Fclosures, and Macros                         8-1







Functions, Fclosures, and Macros                         8-2





\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\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_________________________________________________________________
      fclosure            vector with _\bv_\bp_\br_\bo_\bp            8.4
                           _\be_\bq to fclosure
\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.5
     subroutine          of "subroutine"[|\b-]
\e8_________________________________________________________________
      foreign          binary with discipline          8.5
      function            of "function"[|\b-]
\e8_________________________________________________________________
      foreign          binary with discipline          8.5
  integer function    of "integer-function"[|\b-]
\e8_________________________________________________________________
      foreign          binary with discipline          8.5
   real function        of "real-function"[|\b-]
\e8_________________________________________________________________
      foreign          binary with discipline          8.5
     C function          of "c-function"[|\b-]
\e8_________________________________________________________________
      foreign          binary with discipline          8.5
  double function     of "double-c-function"[|\b-]
\e8_________________________________________________________________
      foreign          binary with discipline          8.5
 structure function   of "vector-c-function"[|\b-]
\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|\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|\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|\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|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|\b\e7|









































\e9                         Table 8.1

____________________
\e9   [|\b-]Only the first character of the string is significant (i.e "s"
is ok for "subroutine")



\e9                                   Printed: January 31, 1984







Functions, Fclosures, and Macros                         8-3


           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.3.  macros

           An important feature of Lisp is  its  ability  to
      manipulate  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  Pas-
      cal)  and  refer  to  elements of those records by the
      field names.  The _\bs_\bt_\br_\bu_\bc_\bt package imported from Maclisp
      does  this.   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.  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.3.1.  macro forms

              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


                                   Printed: January 31, 1984







Functions, Fclosures, and Macros                         8-4


         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)), which _\be_\bv_\ba_\bl evaluates.  The value  _\ba
         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, the first of which is a call to the
         macro  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  evalua-
         tions  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.3.2.  defmacro

              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 def-
         macro 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.




\e9

\e9                                   Printed: January 31, 1984







Functions, Fclosures, and Macros                         8-5


      8.3.3.  the backquote character macro

              The default syntax for  FRANZ  LISP  has  four
         characters  with  associated character macros.  One
         is semicolon for  comments.   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 useful  for  creating  macro  defini-
         tions.  In the simplest case, a backquote acts just
         like a single quote:

         ->`(_\ba _\bb _\bc _\bd _\be)
         (a b c d e)

         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  ele-
         ment  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  macros 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

\e9

\e9                                   Printed: January 31, 1984







Functions, Fclosures, and Macros                         8-6


      8.3.4.  sharp sign character macro

              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.3.4.1.  conditional inclusion

            If you plan to run one source file in more  than
            one environment then you may want to some pieces
            of code to be included  or not included  depend-
            ing  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 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 _\bn_\ba_\bm_\be)
          (_\bp_\ba_\bt_\bo_\bm " _\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


                                   Printed: January 31, 1984







Functions, Fclosures, and Macros                         8-7


                        _\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.3.4.2.  fixnum character equivalents

            When working with fixnum equivalents of  charac-
            ters,  it  is  often hard to remember the number
            corresponding to a character.  The form
                            _\b#_\b/_\bc
            is equivalent to the  fixnum  representation  of
            character c.


    ____________________________________________________

    ; 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.3.4.3.  read time evaluation

            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.











\e9

\e9                                   Printed: January 31, 1984







Functions, Fclosures, and Macros                         8-8



    ____________________________________________________

    ; 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.4.  fclosures

           Fclosures are a type of functional  object.   The
      purpose  is  to  remember the values of some variables
      between invocations of the functional  object  and  to
      protect this data from being inadvertently overwritten
      by other Lisp  functions.   Fortran  programs  usually
      exhibit  this behavior for their variables.  (In fact,
      some versions of Fortran would require  the  variables
      to  be  in COMMON).  Thus it is easy to write a linear
      congruent random number generator in  Fortran,  merely
      by keeping the seed as a variable in the function.  It
      is much more risky to do so in Lisp, since any special
      variable you picked, might be used by some other func-
      tion.  Fclosures are an attempt to provide most of the
      same  functionality  as closures in Lisp Machine Lisp,
      to users of FRANZ LISP.  Fclosures are related to clo-
      sures in this way:
      (fclosure '(a b) 'foo) <==>
              (let ((a a) (b b)) (closure '(a b) 'foo))



      8.4.1.  an example

____________________________________________________________

% lisp
Franz Lisp, Opus 38.60
->(defun code (me count)
  (print (list 'in x))
  (setq x (+ 1 x))
  (cond ((greaterp count 1) (funcall me me (sub1 count))))
  (print (list 'out x)))
code
->(defun tester (object count)
  (funcall object object count) (terpri))


                                   Printed: January 31, 1984







Functions, Fclosures, and Macros                         8-9


tester
->(setq x 0)
0
->(setq z (fclosure '(x) 'code))
fclosure[8]
-> (tester z 3)
(in 0)(in 1)(in 2)(out 3)(out 3)(out 3)
nil
->x
0
____________________________________________________________





              The function _\bf_\bc_\bl_\bo_\bs_\bu_\br_\be  creates  a  new  object
         that  we  will  call  an  fclosure, (although it is
         actually a vector).  The fclosure contains a  func-
         tional  object, and a set of symbols and values for
         the symbols.  In the above  example,  the  fclosure
         functional object is the function code.  The set of
         symbols and values just contains the symbol `x' and
         zero,  the  value  of  `x'  when  the  fclosure was
         created.

         When an fclosure is funcall'ed:

         1)   The Lisp system lambda binds  the  symbols  in
              the fclosure to their values in the fclosure.

         2)   It continues the  funcall  on  the  functional
              object of the fclosure.

         3)   Finally, it un-lambda binds the symbols in the
              fclosure  and  at  the  same  time  stores the
              current values of the symbols in the fclosure.


              Notice that the fclosure is saving  the  value
         of  the  symbol  `x'.   Each  time  a  fclosure  is
         created, new space  is  allocated  for  saving  the
         values  of the symbols. Thus if we execute fclosure
         again, over the same  function,  we  can  have  two
         independent counters:

____________________________________________________________

-> (setq zz (fclosure '(x) 'code))
fclosure[1]
-> (tester zz 2)
(in 0)(in 1)(out 2)(out 2)
-> (tester zz 2)


                                   Printed: January 31, 1984







Functions, Fclosures, and Macros                        8-10


(in 2)(in 3)(out 4)(out 4)
-> (tester z 3)
(in 3)(in 4)(in 5)(out 6)(out 6)(out 6)
____________________________________________________________







      8.4.2.  useful functions

              Here are some quick some  summaries  of  func-
         tions  dealing  with  closures.  They are more for-
         mally defined in 2.8.4.  To  recap,  fclosures  are
         made by (_\bf_\bc_\bl_\bo_\bs_\bu_\br_\be '_\bl__\bv_\ba_\br_\bs '_\bg__\bf_\bu_\bn_\bc_\bo_\bb_\bj).  l_vars is a
         list of symbols (not containing nil), g_funcobj  is
         any  object  that can be funcalled.  (Objects which
         can be funcalled, include compiled Lisp  functions,
         lambda  expressions,  symbols,  foreign  functions,
         etc.) In general, if you want a  compiled  function
         to  be closed over a variable, you must declare the
         variable  to  be  special  within   the   function.
         Another example would be:

                     (fclosure '(a b) #'(lambda (x) (plus x a)))

         Here, the #' construction will  make  the  compiler
         compile the lambda expression.

              There are times when you want to  share  vari-
         ables  between  fclosures.  This can be done if the
         fclosures  are  created  at  the  same  time  using
         _\bf_\bc_\bl_\bo_\bs_\bu_\br_\be-_\bl_\bi_\bs_\bt.  The function _\bf_\bc_\bl_\bo_\bs_\bu_\br_\be-_\ba_\bl_\bi_\bs_\bt returns
         an assoc list giving the symbols and values in  the
         fclosure.   The  predicate  _\bf_\bc_\bl_\bo_\bs_\bu_\br_\be_\bp returns t iff
         its  argument  is  a  fclosure.   Other   functions
         imported  from  Lisp  Machine  Lisp are _\bs_\by_\bm_\be_\bv_\ba_\bl-_\bi_\bn-
         _\bf_\bc_\bl_\bo_\bs_\bu_\br_\be,   _\bl_\be_\bt-_\bf_\bc_\bl_\bo_\bs_\be_\bd,    and    _\bs_\be_\bt-_\bi_\bn-_\bf_\bc_\bl_\bo_\bs_\bu_\br_\be.
         Lastly,  the function _\bf_\bc_\bl_\bo_\bs_\bu_\br_\be-_\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn returns the
         function argument.



      8.4.3.  internal structure

              Currently, closures are  implemented  as  vec-
         tors, with property being the symbol fclosure.  The
         functional object is the first entry.  The  remain-
         ing  entries are structures which point to the sym-
         bols and values for the closure, (with a  reference
         count  to  determine  if  a  recursive  closure  is


                                   Printed: January 31, 1984







Functions, Fclosures, and Macros                        8-11


         active).



   8.5.  foreign subroutines and functions

           FRANZ LISP has the ability  to  dynamically  load
      object  files  produced by other compilers and to call
      functions defined in those files.  These functions are
      called _\bf_\bo_\br_\be_\bi_\bg_\bn functions.* There are  seven  types  of
      foreign functions.  They are characterized by the type
      of result they  return,  and  by  differences  in  the
      interpretation of their arguments.  They come from two
      families: a group  suited  for  languages  which  pass
      arguments  by  reference  (e.g.  Fortran), and a group
      suited for languages which  pass  arguments  by  value
      (e.g. C).


      There are four types in the first group:

      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.


      There are three types in the second group:

      c-function
           This is like an integer function, except for  its
           different interpretation of arguments.


____________________
\e9   *This topic is also discussed in Report  PAM-124  of  the
Center  for  Pure  and  Applied  Mathematics,  UCB, entitled
``Parlez-Vous Franz?  An Informal Introduction to  Interfac-
ing Foreign Functions to Franz LISP'', by James R. Larus



\e9                                   Printed: January 31, 1984







Functions, Fclosures, and Macros                        8-12


      double-c-function
           This is like a real-function.

      vector-c-function
           This is for C functions which return a structure.
           The  first  argument  to such functions must be a
           vector (of type vectori), into which  the  result
           is  stored.  The second Lisp argument becomes the
           first argument to the C function, and so on

      A foreign function is accessed through a binary object
      just like a compiled Lisp function.  The difference is
      that the discipline field of a  binary  object  for  a
      foreign  function is a string whose first character is
      given in the following table:


\e8                   ____________________________
                    letter         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____________________________
                      s         subroutine
\e8                   ____________________________
                      f          function
\e8                   ____________________________
                      i      integer-function
\e8                   ____________________________
                      r       real-function.
\e8                   ____________________________
                      c         c-function
\e8                   ____________________________
                      v      vector-c-function
\e8                   ____________________________
                      d      double-c-function
\e8                   ____________________________
\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|












      Two functions  are  provided  for  setting-up  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 are more than one function in an object file,
      _\bg_\be_\bt_\ba_\bd_\bd_\br_\be_\bs_\bs can be used to set  up  additional  foreign
      function objects.

           Foreign  functions are  called  just  like  other
      functions,  e.g  (_\bf_\bu_\bn_\bn_\ba_\bm_\be _\ba_\br_\bg_\b1 _\ba_\br_\bg_\b2).  When a function
      in the Fortran group  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
      temporary 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
      the argument is an array object, 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 func-
      tion).  If a binary object is an argument,  the  entry


\e9                                   Printed: January 31, 1984







Functions, Fclosures, and Macros                        8-13


      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).

           When a function in the C group is called,  fixnum
      and flownum arguments are passed by value.  For almost
      all other arguments, the address is merely provided to
      the  C  routine.   The  only exception arises when you
      want to invoke a C routine which  expects  a  ``struc-
      ture''  argument.  Recall that a (rarely used) feature
      of the C language is the ability to pass structures by
      value.   This  copies  the  structure  onto the stack.
      Since the Franz's nearest equivalent to a C  structure
      is  a  vector, we provide an escape clause to copy the
      contents of an immediate-type vector by value.  If the
      property  field  of  a vectori argument, is the symbol
      "value-structure-argument", then the  binary  data  of
      this immediate-type vector is copied into the argument
      list of the C routine.

           The method a foreign function uses to access  the
      arguments   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 Fortran.  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.
      The first (cfoo in C, pfoo in Pascal)  is  given  four
      arguments,  a  fixnum, a flonum-block array, a hunk of
      at least two fixnums and a list of at least  two  fix-
      nums.   To  demonstrate  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 Pas-
      cal) 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
      bold,  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
% cat ch8auxc.c
/* 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;


                                   Printed: January 31, 1984







Functions, Fclosures, and Macros                        8-14


};

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);
}


_\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
% cat ch8auxp.p
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]^);


                                   Printed: January 31, 1984







Functions, Fclosures, and Macros                        8-15


   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
% cc -c ch8auxc.c
1.0u 1.2s 0:15 14% 30+39k 33+20io 147pf+0w
% pc -c ch8auxp.p
3.0u 1.7s 0:37 12% 27+32k 53+32io 143pf+0w


% lisp
Franz Lisp, Opus 38.60
_\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.
-> (cfasl 'ch8auxc.o '_cfoo 'cfoo "integer-function")
/usr/lib/lisp/nld -N -A /usr/local/lisp -T 63000 ch8auxc.o -e _cfoo -o /tmp/Li7055.0  -lc
#63000-"integer-function"
-> (cfasl 'ch8auxp.o '_pfoo 'pfoo "integer-function" "-lpc")
/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
-> (getaddress '_cmemq 'cmemq "function" '_pmemq 'pmemq "function")
#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.
-> (setq testarr (array nil flonum-block 2))
array[2]
-> (store (funcall testarr 0) 1.234)
1.234
-> (store (funcall testarr 1) 5.678)
5.678
-> (cfoo 385 testarr (hunk 10 11 13 14) '(15 16 17))
a: 385, b[0]: 1.234000, b[1]: 5.678000


                                   Printed: January 31, 1984







Functions, Fclosures, and Macros                        8-16


 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.
-> (funcall testarr 1)
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.
-> (array test flonum-block 2)
array[2]
-> (store (test 0) 1.234)
1.234
-> (store (test 1) 5.678)
5.678
-> (pfoo 385 (getd 'test) (hunk 10 11 13 14) '(15 16 17))
 a:       385 b[0]:  1.23400000000000E+00 b[1]:  5.67800000000000E+00
 c (first):        10 c (second):        11
 (         15        16 ...)
3
-> (test 1)
3.1415926

 _\bN_\bo_\bw _\bt_\bo _\bt_\be_\bs_\bt _\bo_\bu_\bt _\bt_\bh_\be _\bm_\be_\bm_\bq'_\bs
-> (cmemq 'a '(b c a d e f))
(_\ba _\bd _\be _\bf)
-> (pmemq 'e '(a d f g a x))
_\bn_\bi_\bl
____________________________________________________________





           The Fortran example will be much shorter since in
      Fortran  you can't follow pointers as you can in other
      languages.  The Fortran function ffoo is  given  three
      arguments:  a  fixnum, a fixnum-block array and a flo-
      num.  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.

____________________________________________________________


% cat ch8auxf.f


                                   Printed: January 31, 1984







Functions, Fclosures, and Macros                        8-17


        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
% f77 -c ch8auxf.f
ch8auxf.f:
   ffoo:
0.9u 1.8s 0:12 22% 20+22k 54+48io 158pf+0w
% lisp
Franz Lisp, Opus 38.60
-> (cfasl 'ch8auxf.o '_ffoo_ 'ffoo "real-function" "-lF77 -lI77")
/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"

-> (array test fixnum-block 2)
array[2]
-> (store (test 0) 10)
10
-> (store (test 1) 11)
11
-> (ffoo 385 (getd 'test) 5.678)
 a= 385, b(1)=   10, b(2)=   11 c=5.6780
1.234559893608093
-> (test 0)
22

____________________________________________________________



















\e9

\e9                                   Printed: January 31, 1984