BSD 4_3 development

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

                        CHAPTER  13


         The CMU User Toplevel and the File Package



This documentation was written by Don Cohen, and  the  func-
tions described below were imported from PDP-10 CMULisp.

_\bN_\bo_\bn _\bC_\bM_\bU _\bu_\bs_\be_\br_\bs _\bn_\bo_\bt_\be: this is not the default  top  level  for
your  Lisp system.  In order to start up this top level, you
should type (_\bl_\bo_\ba_\bd '_\bc_\bm_\bu_\be_\bn_\bv).




   13.1.  User Command Input Top Level

      The top-level is the  function  that  reads  what  you
      type, evaluates it and prints the result.  The _\bn_\be_\bw_\bl_\bi_\bs_\bp
      top-level was inspired by the CMULisp top-level (which
      was  inspired  by interlisp) but is much simpler.  The
      top-level is a function (of zero arguments)  that  can
      be  called  by  your  program.   If you prefer another
      top-level, just redefine the  top-level  function  and
      type  "(reset)" to start running it.  The current top-
      level simply calls the functions  tlread,  tleval  and
      tlprint  to  read, evaluate and print.  These are sup-
      posed to be replaceable by the  user.   The  only  one
      that  would  make  sense  to replace is tlprint, which
      currently uses a function that refuses to go  below  a
      certain  level  and prints "...]" when it finds itself
      printing a circular list.  One might want  to  pretty-
      print  the  results  instead.   The  current top-level
      numbers the lines that you type to it,  and  remembers
      the  last  n  "events"  (where  n  can  be  set but is
      defaulted to 25).  One can refer to  these  events  in
      the following "top-level commands":













\e9

\e9The CMU User Toplevel and the File Package              13-1







The CMU User Toplevel and the File Package              13-2



    ____________________________________________________

    _\bT_\bO_\bP_\bL_\bE_\bV_\bE_\bL _\bC_\bO_\bM_\bM_\bA_\bN_\bD _\bS_\bU_\bM_\bM_\bA_\bR_\bY

    ??      prints events - both the input and the result.  If you just type
            "??" you will see all of the recorded events.  "?? 3" will show
            only event 3, and "?? 3 6" will show events 3 through 6.

    redo    pretends that you typed the same thing that was typed before.  If
            you type "redo 3" event number 3 is redone.  "redo -3" redoes the
            thing 3 events ago.  "redo" is the same as "redo -1".

    ed      calls the editor and then does whatever the editor returns.  Thus
            if you want to do event 5 again except for some small change, you
            can type "ed 5", make the change and leave the editor.  "ed -3"
            and "ed" are analogous to redo.
    ____________________________________________________



Finally, you can get the value of event 7 with the  function
(valueof 7).  The other interesting feature of the top-level
is that it makes outermost parentheses superfluous  for  the
most  part.   This  works the same way as in CMULisp, so you
can use the help for an explanation.  If you're not sure and
don't  want  to  risk  it  you  can  always just include the
parentheses.


(top-level)

     SIDE EFFECT: _\bt_\bo_\bp-_\bl_\be_\bv_\be_\bl is the  LISP top level function.
                  As well as  being the  top level  function
                  with  which  the user interacts, it can be
                  called  recursively  by  the   user or any
                  function.  Thus, the   top  level  can  be
                  invoked  from  inside  the  editor,  break
                  package, or a user  function to  make  its
                  commands available to the user.

     NOTE: The  CMU FRANZ  LISP  top-level    uses  _\bl_\bi_\bn_\be_\br_\be_\ba_\bd
           rather   than _\br_\be_\ba_\bd.  The difference will not usu-
           ally be noticeable.  The principal  thing  to  be
           careful   about is that input  to the function or
           system being called cannot appear   on  the  same
           line as the  top-level call.  For example, typing
           (_\be_\bd_\bi_\bt_\bf _\bf_\bo_\bo)_\bf_\bP _\bo_\bn _\bo_\bn_\be   _\bl_\bi_\bn_\be  _\bw_\bi_\bl_\bl  _\be_\bd_\bi_\bt  _\bf_\bo_\bo  _\ba_\bn_\bd
           _\be_\bv_\ba_\bl_\bu_\ba_\bt_\be  _\bP, _\bn_\bo_\bt _\be_\bd_\bi_\bt _\bf_\bo_\bo _\ba_\bn_\bd _\be_\bx_\be_\bc_\bu_\bt_\be _\bt_\bh_\be  _\bp _\bc_\bo_\bm_\b-
           _\bm_\ba_\bn_\bd _\bi_\bn _\bt_\bh_\be _\be_\bd_\bi_\bt_\bo_\br.  _\bt_\bo_\bp-_\bl_\be_\bv_\be_\bl  _\bs_\bp_\be_\bc_\bi_\ba_\bl_\bl_\by  _\br_\be_\bc_\bo_\bg_\b-
           _\bn_\bi_\bz_\be_\bs _\bt_\bh_\be _\bf_\bo_\bl_\bl_\bo_\bw_\bi_\bn_\bg _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\bs:

\e9

\e9                                      Printed: July 21, 1983







The CMU User Toplevel and the File Package              13-3


(valueof '_\bg__\be_\bv_\be_\bn_\bt_\bs_\bp_\be_\bc)

     RETURNS: the value(s)  of  the  event(s)  specified  by
              g_eventspec.   If a single event is specified,
              its value will be returned.  If more than  one
              event  is specified, or an event has more than
              one subevent (as for _\br_\be_\bd_\bo,  etc),  a  list  of
              vlaues will be returned.




   13.2.  The File Package

      Users typically define functions in lisp and then want
      to  save  them  for  the  next  session.   If  you  do
      (_\bc_\bh_\ba_\bn_\bg_\be_\bs), a list of  the  functions  that  are  newly
      defined  or  changed  will  be printed.  When you type
      (_\bd_\bs_\bk_\bo_\bu_\bt_\bs), the functions associated with files will be
      saved in the new versions of those files.  In order to
      associate functions with files you can either add them
      to  the  _\bf_\bi_\bl_\be_\bf_\bn_\bs  list of an existing file or create a
      new file to hold them.  This is  done  with  the  _\bf_\bi_\bl_\be
      function.   If  you  type  (_\bf_\bi_\bl_\be  _\bn_\be_\bw) the system will
      create a variable called  _\bn_\be_\bw_\bf_\bn_\bs.   You  may  add  the
      names of the functions to go into that file to _\bn_\be_\bw_\bf_\bn_\bs.
      After you do (_\bc_\bh_\ba_\bn_\bg_\be_\bs), the functions which are in  no
      other  file  are  stored  in  the  value  of  the atom
      _\bc_\bh_\ba_\bn_\bg_\be_\bs.  To put these all  in  the  new  file,  (_\bs_\be_\bt_\bq
      _\bn_\be_\bw_\bf_\bn_\bs  (_\ba_\bp_\bp_\be_\bn_\bd  _\bn_\be_\bw_\bf_\bn_\bs  _\bc_\bh_\ba_\bn_\bg_\be_\bs)).   Now  if  you  do
      (_\bc_\bh_\ba_\bn_\bg_\be_\bs), all of  the  changed  functions  should  be
      associated  with  files.  In order to save the changes
      on the files, do (_\bd_\bs_\bk_\bo_\bu_\bt_\bs).  All of the changed  files
      (such  as  NEW)  will  be written.  To recover the new
      functions the next time you run FRANZ LISP, do  (_\bd_\bs_\bk_\bi_\bn
      _\bn_\be_\bw).
















\e9

\e9                                      Printed: July 21, 1983







The CMU User Toplevel and the File Package              13-4



    ____________________________________________________

    Script started on Sat Mar 14 11:50:32 1981
    $ newlisp
    Welcome to newlisp...
    1.(defun square (x) (* x x))            ; define a new function
    square
    2.(changes)                             ; See, this function is associated
                                            ; with no file.
    <no-file>      (square)nil
    3.(file 'new)                           ; So let's declare file NEW.
    new
    4.newfns                                ; It doesn't have anything on it yet.
    nil
    5.(setq newfns '(square))               ; Add the function associated
    (square)                                ; with no file to file NEW.
    6.(changes)                             ; CHANGES magically notices this fact.

    new            (square)nil
    7.(dskouts)                             ; We write the file.
    creating new
    (new)
    8.(dskin new)                           ; We read it in!
    (new)
    14.Bye
    $
    script done on Sat Mar 14 11:51:48 1981

    ____________________________________________________





(changes s_flag)

     RETURNS: Changes computes a list  containing  an  entry
              for  each  file  which defines atoms that have
              been marked changed.  The entry  contains  the
              file   name  and  the  changed  atoms  defined
              therein.  There is also a  special  entry  for
              changes  to atoms which are not defined in any
              known file.  The global variable _\bf_\bi_\bl_\be_\bl_\bs_\bt  con-
              tains  the  list of "known" files.  If no flag
              is passed this  result  is  printed  in  human
              readable  form  and the value returned is t if
              there were any changes and nil if not.  Other-
              wise  nothing is printed and the computer list
              is returned.  The global variable _\bc_\bh_\ba_\bn_\bg_\be_\bs con-
              tains  the  atoms which are marked changed but
              not yet associated with any file.  The _\bc_\bh_\ba_\bn_\bg_\be_\bs
              function  attempts  to  associate  these names


                                      Printed: July 21, 1983







The CMU User Toplevel and the File Package              13-5


              with files, and any that  are  not  found  are
              considered  to belong to no file.  The _\bc_\bh_\ba_\bn_\bg_\be_\bs
              property is the means by which  changed  func-
              tions  are associated with files.  When a file
              is read in or written out its _\bc_\bh_\ba_\bn_\bg_\be_\bs property
              is removed.

(dc s_word s_id [ g_descriptor1  ... ] <text> <esc>)

     RETURNS: _\bd_\bc defines comments.   It  is  exceptional  in
              that  its  behavior is very context dependent.
              When _\bd_\bc  is  executed  from  _\bd_\bs_\bk_\bi_\bn  it  simply
              records  the fact that the comment exists.  It
              is expected that in interactive mode  comments
              will  be  found via _\bg_\be_\bt_\bd_\be_\bf - this allows large
              comments which do not take up  space  in  your
              core image.  When _\bd_\bc is executed from the ter-
              minal it expects you to type a comment. _\bd_\bs_\bk_\bo_\bu_\bt
              will  write  out  the comments that you define
              and also copy the comments on the old  version
              of the file, so that the new version will keep
              the old comments even though they  were  never
              actually  brought  into core.  The optional id
              is  a  mechanism  for   distinguishing   among
              several  comments  associated  with  the  same
              word.  It defaults to  nil.   However  if  you
              define  two  comments  with  the  same id, the
              second is considered to be a  replacement  for
              the first. The behavior of _\bd_\bc is determined by
              the value of the global variable  _\bd_\be_\bf-_\bc_\bo_\bm_\bm_\be_\bn_\bt.
              _\bd_\be_\bf-_\bc_\bo_\bm_\bm_\be_\bn_\bt  contains  the  name of a function
              that is run.  Its arguments are the  word,  id
              and  attribute  list. _\bd_\be_\bf-_\bc_\bo_\bm_\bm_\be_\bn_\bt is initially
              _\bd_\bc-_\bd_\be_\bf_\bi_\bn_\be.  Other functions rebind it  to  _\bd_\bc-
              _\bh_\be_\bl_\bp,  _\bd_\bc-_\bu_\bs_\be_\br_\bh_\be_\bl_\bp,  and  the  value of _\bd_\bs_\bk_\bi_\bn-
              _\bc_\bo_\bm_\bm_\be_\bn_\bt.  The comment property of an atom is a
              list  of  entries,  each representing one com-
              ment.  Atomic entries are assumed to be  iden-
              tifiers of comments on a file but not in core.
              In-core comments are represented by a list  of
              the  id,  the  attribute  list and the comment
              text.  The comment text is an uninterned atom.
              Comments  may be deleted or reordered by edit-
              ing the comment property.








\e9

\e9                                      Printed: July 21, 1983







The CMU User Toplevel and the File Package              13-6


(dskin l_filenames)

     SIDE EFFECT: READ-EVAL-PRINTs  the  contents  of    the
                  given  files.  This is the function to use
                  to read files created  by  _\bd_\bs_\bk_\bo_\bu_\bt.   _\bd_\bs_\bk_\bi_\bn
                  also  declares the files that it reads (if
                  a _\bf_\bi_\bl_\be-_\bf_\bn_\bs list is defined and the file is
                  otherwise  declarable  by  _\bf_\bi_\bl_\be ), so that
                  changes to it can be recorded.


(dskout s_file1 ...)

     SIDE EFFECT: For each file  specified,  _\bd_\bs_\bk_\bo_\bu_\bt  assumes
                  the   list  named  filenameFNS (i.e.,  the
                  file  name,   excluding  extension,   con-
                  catenated   with  _\bf_\bn_\bs )  contains  a  list
                  of function names, etc., to be loaded  Any
                  previous  version  of  the  file  will  be
                  renamed  to have extension ".back".

(dskouts s_file1 ...)

     SIDE EFFECT: applies _\bd_\bs_\bk_\bo_\bu_\bt to and  prints the name  of
                  each  s_filei    (with    no    additional
                  arguments,   assuming filenameFNS to be  a
                  list  to  be loaded) for  which s_file_\bi is
                  either not in _\bf_\bi_\bl_\be_\bl_\bs_\bt  (meaning  it  is  a
                  new   file not previously declared by _\bf_\bi_\bl_\be
                  or  given  as  an   argument   to   _\bd_\bs_\bk_\bi_\bn,
                  _\bd_\bs_\bk_\bo_\bu_\bt_\bs,  or _\bd_\bs_\bk_\bo_\bu_\bt_\bs) or is in _\bf_\bi_\bl_\be_\bl_\bs_\bt and
                  has some recorded changes  to  definitions
                  of  atoms  in  filenameFNS, as recorded by
                  _\bm_\ba_\br_\bk!_\bc_\bh_\ba_\bn_\bg_\be_\bd and  noted  by  changes.   If
                  _\bf_\bi_\bl_\bei  is not  specified, _\bf_\bi_\bl_\be_\bl_\bs_\bt  will be
                  used.  This  is the  most common   way  of
                  using  dskouts.   Typing   (_\bd_\bs_\bk_\bo_\bu_\bt_\bs)  will
                  save  every  file  reported  by  (_\bc_\bh_\ba_\bn_\bg_\be_\bs)
                  to have changed definitions.


(dv s_atom g_value)

     EQUIVALENT TO: (_\bs_\be_\bt_\bq   _\ba_\bt_\bo_\bm    '_\bv_\ba_\bl_\bu_\be).     _\bd_\bv    calls
                    _\bm_\ba_\br_\bk!_\bc_\bh_\ba_\bn_\bg_\be_\bd.







\e9

\e9                                      Printed: July 21, 1983







The CMU User Toplevel and the File Package              13-7


(file 's_file)

     SIDE EFFECT: declares its argument to be a file  to  be
                  used  for  reporting and saving changes to
                  functions by adding the  file  name  to  a
                  list  of  files,  _\bf_\bi_\bl_\be_\bl_\bs_\bt.  _\bf_\bi_\bl_\be is called
                  for each file argument of  _\bd_\bs_\bk_\bi_\bn,  _\bd_\bs_\bk_\bo_\bu_\bt,
                  and _\bd_\bs_\bk_\bo_\bu_\bt_\bs.

(file-fns 's_file)

     RETURNS: the name of the  fileFNS  list  for  its  file
              argument s_file.

(getdef 's_file ['s_i1 ...])

     SIDE EFFECT: selectively executes definitions for atoms
                  s_i1  ... from the specified file.  Any of
                  the words to be defined which end with "@"
                  will be treated as patterns in which the @
                  matchs any suffix (just like the  editor).
                  _\bg_\be_\bt_\bd_\be_\bf  is driven by _\bg_\be_\bt_\bd_\be_\bf_\bt_\ba_\bb_\bl_\be (and thus
                  may be programmed).  It looks for lines in
                  the  file  that  start  with a word in the
                  table.  The first character must be a  "("
                  or "[" followed by the word, followed by a
                  space, return or something else that  will
                  not  be considered as part of the identif-
                  ier by _\br_\be_\ba_\bd, e.g.,  "("  is  unacceptable.
                  When  one  is found the next word is read.
                  If it matches one of  the  identifiers  in
                  the call to _\bg_\be_\bt_\bd_\be_\bf then the table entry is
                  executed.  The table entry is  a  function
                  of  the  expression starting in this line.
                  Output from _\bd_\bs_\bk_\bo_\bu_\bt is in acceptable format
                  for _\bg_\be_\bt_\bd_\be_\bf.  _\bg_\be_\bt_\bd_\be_\bf

     RETURNS: a list of the words which match  the  ones  it
              looked for, for which it found (but, depending
              on the table, perhaps did not execute) in  the
              file.

     NOTE: _\bg_\be_\bt_\bd_\be_\bf_\bt_\ba_\bb_\bl_\be is the table that drives _\bg_\be_\bt_\bd_\be_\bf.   It
           is in the form of an association list.  Each ele-
           ment is a dotted pair consisting of the name of a
           function for which _\bg_\be_\bt_\bd_\be_\bf searches and a function
           of one argument to be executed when it is found.





\e9

\e9                                      Printed: July 21, 1983







The CMU User Toplevel and the File Package              13-8


(mark!changed 's_f)

     SIDE EFFECT: records the fact that  the  definition  of
                  s_f has been changed.  It is automatically
                  called by _\bd_\be_\bf, _\bd_\be_\bf_\bu_\bn, _\bd_\be, _\bd_\bf, _\bd_\be_\bf_\bp_\br_\bo_\bp, _\bd_\bm,
                  _\bd_\bv,  and  the  editor when a definition is
                  altered.













































\e9

\e9                                      Printed: July 21, 1983