projects / unix-history / blob
? search:
summary | tags | clone url | shortlog | log | commit | commitdiff | tree
blame | history | raw | HEAD
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
Continuous source code history from original PDP-7 UNIX to FreeBSD 2, the first fully unencumbered FreeBSD release.