github.com/PDP-10.its
1
0
Fork 0
mirror of https://github.com/PDP-10/its.git synced 2026-04-27 04:37:20 +00:00
Code Issues Releases Wiki Activity

Move documentation files to doc.

Browse Source
This commit is contained in:
Lars Brinkhoff
2018-05-07 07:20:01 +02:00
parent cef2305dbe
commit d6fa4be81a
18 changed files with 0 additions and 1422 deletions
Download Patch File Download Diff File Expand all files Collapse all files

79
doc/libdoc/fasdmp.info Executable file
View File

@@ -0,0 +1,79 @@
FASDUMP Documentation -- Richard L. Bryan (RLB) 23 APR 1975
FASDUMP is a set of Lisp functions to dump, in
FASL format, s-expressions to be eval'ed at FASLOAD
time. Provision is made for preserving, when desired or
necessary, the EQness of common subexpressions.
The calling form is
(FASDUMP targetfile noneqlist eqlist fasdumpalist)
i.e., a SUBR of four arguments. The args are as follows:
TARGETFILE: File spec describing destination of
output data. If it is an atom, it specifies the first
filename. If it is a list, it specifies a UREAD-type file
spec, with second file name defaulting to FASL. I guess
that makes it a FASLOAD-type file spec.
NONEQLIST: This is a list of forms to be eval'ed at
FASLOAD time. These forms are not examined for EQ
subexpressions, so EQness is not preserved for these forms.
EQLIST: This is another list of forms to be eval'ed at
FASLOAD time. These forms and their subforms are
effectively interned on an internal obarray so that EQness
of all subforms in all forms in this list is preserved.
Subforms which are EQUAL but not EQ are not EQified.
FASDUMPALIST: This alist provides information to
convert subforms to something determinable only by evaluation at
load time. For example, many Macsyma expressions contain the
form (MPLUS SIMP), all occurrences of such form supposedly
being EQ to (GET 'MPLUS 'MSIMPIND).
If such forms are dumped without special processing, then all
such forms upon loading will be EQ to each other, but not to
the "real" one. Thus, when saving a Macsyma expression
suspected of containing such forms, one member of the list
passed as the last arg to FASDUMP would be:
(CONS (GET 'MPLUS 'MSIMPIND) '(GET 'MPLUS 'MSIMPIND)).
It should be noted that the interning process for each form
in the EQLIST requires making several passes over each
form, and requires one cons for each unique subexpression plus
one cons for each unique subexpression appearing more than once;
hence EQness preservation can be expensive for large expressions.
The FASDUMP code lives in MC:RLB%;FASDMP >, and a
compiled version can be found in MC:MACSYM;FASDMP FASL.
As an example of FASDUMP usage, consider a function
to save specified atoms on a specified file. The following
definition, typed off the top of my head and untested, might do
the job.
;;;SAVE ATOM VALUES AND PROPS WITHOUT EQNESS PRESERVATION:
;;;USE LIKE (ATOMSAVE <FILESPEC> A1 A2 A3 ...)
(DEFUN ATOMSAVE FEXPR (ARG)
(FASDUMP (CAR ARG)
(DO ((FL) (AL (CDR ARG) (CDR AL)))
((NULL AL) (NREVERSE FL))
;;SAVE ATOM VALUE, IF ANY
(AND (BOUNDP (CAR AL))
(SETQ FL (CONS (LIST 'SETQ
(CAR AL)
(SYMEVAL (CAR AL)))
FL)))
;;SAVE ATOM'S PLIST, IF ANY
(DO ((PL (PLIST (CAR AL)) (CDDR PL)))
((NULL PL))
(SETQ FL (CONS (LIST 'DEFPROP
(CAR AL)
(CADR PL)
(CAR PL))
FL))))
NIL ;DON'T BOTHER WITH EQNESS PRESERVATION
NIL))
Another example of usage can be found in Macsyma's $FASSAVE
command in MC:JPG;DSKFN >.

40
doc/libdoc/faslre.info Executable file
View File

@@ -0,0 +1,40 @@
FASLREA is a package of functions for reading s-expressions and other
information from a FASL file (see also FASDMP). The source is MC:RLB;FASLRE >.
The three main functions are:
(FASLREADOPEN <file spec>) which opens the file, initializes, and
returns a FASL-OBJ for use by FASLREAD and FASLREADCLOSE.
(FASLREAD <FASL-obj>) which reads an item and returns it, with a type code
consed onto its front:
EVAL - the item was an "EVAL Mungeable". The CDR is the item.
ENTRY - the CDR is (<subr name> <subr type> <args prop>)
EOF - the end of the FASL file was reached.
(FASLREADCLOSE <FASL-obj>) which closes the file and flushes all
associated arrays.
An additional function (QFASLREAD <fas-obj>) reads an object and returns
it, with a code consed on its front:
ENTRY - the CDR is the subr name
EXT - the CDR is the symbol subject to the call
EOF - the end of the FASL file was reached.
DDT symbols are needed for the following LAP symbols:
BNCONS
In Lisp versions > /1567, DDT symbols won't be needed.
------------------------------------------------------------------
IMPLEMENTATION --
A FASL-OBJ is a Lisp T-type array with 6 entries:
(0) is byte-obj, a Lisp FIXNUM array with 9. entries storing the
relocation bytes
(1) is index indicating current (next) relocation type byte
(2) is Newio file object
(3) is the atom table, a Lisp T-type array
(4) is the maximum subscript for the atom table (1- size)
(5) is the greatest used subscript in the atom table.
For a discussion of FASL format, relocation bytes, and atom table,
see .INFO.FASBIN FORMAT .

275
doc/libdoc/for.info Executable file
View File

@@ -0,0 +1,275 @@
;;;-*-Lisp-*-
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; ITERATION FUNCTIONS ;;;
;;; Peter Szolovits (PSZ @ MIT-ML) ;;;
;;; July 16, 1976 ;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; revised by PSZ & RAMESH on Mar. 22, 1979 ;;;
;;; revised by LH@MIT-ML on May 9, 1979 ;;;
;;; revised again by BYRON@MIT-ML on July 12, 1979 ;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;This package defines a set of functions to provide an
;;;approximation of INTERLISP's iteration statement facility
;;;within a MACRO package for MACLISP.
;;;
;;;
;;;For the simplest exposition of its use and utility, here are
;;;a few examples of how the iterations statements may be used:
;;;
;;; (FOR I FROM 1 TO 3 COLLECT I) ==> (1 2 3)
;;;
;;; (COLLECT (CONS I X) FOR X IN '(A B C D E) AS I BY 3)
;;; ==> ((1 . A) (4 . B) (7 . C) (10 . D) (13 . E))
;;;
;;; (UNLESS (ATOM X) JOIN X FOR X IN '((A B C) (D E) F (G)))
;;; ==> (A B C D E G)
;;;
;;; (FOR X ON '(A B C D) AS I FROM 1 ADJOIN (PRINT I) X)
;;; 1
;;; 2
;;; 3
;;; 4
;;; ==> (A B C D B C D C D D)
;;;
;;; (FIRST (SETQ FOO '(A B (C D) E))
;;; WHILE (ATOM (CAR FOO)) DO (SETQ FOO (CDR FOO)) (PRINT FOO))
;;; (B (C D) E)
;;; ((C D) E)
;;; ==> NIL
;;;
;;; (BIND X (FOO '(A B (C D) E))
;;; WHILE (ATOM (SETQ X (CAR FOO)))
;;; COLLECT (SETQ FOO (CDR FOO)) (CONS X X))
;;; ==> ((A . A) (B . B))
;;;
;;; (FOR X IN '(A B C D) FIRST-TIME (MEMQ X '(E F G C 1 2 3)))
;;; ==> (C 1 2 3)
;;;
;;;FOR now supports LET-type "destructuring" wherever variables are
;;; explicitly bound (by BIND, FOR, or AS) so:
;;;
;;; (FOR (X Y) IN '((1 2) (3 4)) COLLECT (+ X Y) ==> (3 7)
;;;
;;; (BIND ((X Y) '(2 4)) FOR I FROM 1 TO 2 COLLECT (+ X Y I)) ==> (7 8)
;;;
;;*page
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; GENERAL DESCRIPTION ;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;
;;; An ITERATION is a convenient manner of writing a complex
;;;LISP looping expression when control is desired of various
;;;aspects of the iteration which make the system-provided
;;;functions (e.g., MAPCAR, DO) too rigid or too cumbersome.
;;;
;;; An iteration statement consists of a number of clauses,
;;;described below, written in succession within a single S-EXPR.
;;;
;;; Every iteration has at most one MAIN CLAUSE, which
;;;controls what, if anything, is collected as the result of the
;;;iteration. The default provided main clauses are:
;;;
;;; DO (or DOING) -- evaluated for side-effect only; return is
;;; NIL.
;;; COLLECT -- A list of the values of every evaluation of the
;;; main clause is returned (c.f. MAPCAR).
;;; JOIN -- The values of every evaluation of the main clause
;;; are NCONCed together to form the value (c.f.
;;; MAPCAN).
;;; ADJOIN -- Like JOIN, but joining is by APPEND rather than
;;; NCONC. Every joined segment is copied exactly
;;; once, even if there is only one segment.
;;; COUNT -- The number of non-NIL values of the evaluations of
;;; the main clause is returned.
;;; SUM -- The sum of the values of the evaluations of the main
;;; clause is returned.
;;; FIRST-TIME -- The value of the iteration is the first
;;; non-NIL value of the main clause, and iteration
;;; terminates when and if this occurs.
;;; PRINT (or PRINTING) -- PRINT's the values of the evaluations
;;; of the main clause.
;;; RESULT -- Sets the RESULT variable to the value of the expression
;;; and exits.
;;;
;;;Other main clauses may be added. Each must be signalled by a
;;;keyword marked by the !FUNCTION property with an appropriate
;;;function to fill in the iteration template for it.
;;;
;;;
;;; The binding of LOOP VARIABLES and AUXILLIARY VARIABLES is
;;;controlled by the BIND, FOR and AS clauses. The BIND keyword is
;;;followed by the variables or (variable initial-val) or
;;;(variable-structure initial-val) <as in LET> forms to be
;;;bound. Those variables are bound, and the initial-vals are evaluated
;;;before any of the bindings for this iteration. The FOR and AS
;;;clauses are equivalent and provide a way to have several loop
;;;variables. The keyword is followed by the name of the variable, and
;;;optionally by FIXNUM, FLONUM, or NOTYPE. NOTYPE is the default
;;;except for numeric (FROM, TO, DOWNTO, BY) variables, for which it is
;;;FIXNUM. An appropriate declaration to the compiler is made. The rest
;;;of each variable clause has one of the following forms:
;;;
;;; FROM e1 TO e2 BY e3 -- This is the numeric iteration clause.
;;; Its terms may appear in any order. Instead of
;;; the TO, we may have a DOWNTO term to indicate
;;; that the loop is for decrementing the var. FROM
;;; defaults to 1, BY to 1 with TO and -1 with
;;; DOWNTO. Incrementing is assumed if neither is
;;; stated. (Currently, no checking is performed to
;;; see that the types of args are consistent, and
;;; the type of arithmetic used is determined by the
;;; type specified. NOTYPE implies general
;;; arithmetic, and the default is FIXNUM.)
;;; IN list -- This is iteration over a list. The var gets
;;; successive elements of the list.
;;; ON list -- This is iteration over successive tails of the
;;; list.
;;; STARTING e1 STEPPING e2 -- This is a general form for giving
;;; initial and incremental values. The terms may
;;; be in either order. STARTING defaults to NIL,
;;; and if STEPPING is omitted, no stepping action
;;; is set up.
;;; TRAILING v1, or TRAILS v1 -- The iteration variable will take on the
;;; value that v1 had on the previous iteration. V1 should
;;; be some other iteration variable of this iteration. On
;;; the first iteration, since there is no previous value of
;;; v1, we use NIL.
;;; SET-TO e1, or = e1 -- On each iteration, e1 is evaluated and
;;; assigned to the variable. This is most useful when e1
;;; is expressed in terms of some other iteration
;;; variable(s). E1 is always computed in terms of the new
;;; values of the iteration variables, not the old.
;;; BEING pathname OF e1, or
;;; BEING e1 AND ITS pathname -- These are the exclusive and
;;; inclusive forms of the PATH ITERATION.
;;; Pathnames must be explicitly marked by the
;;; !PATH-FUNCTION property with a function to
;;; process them. This is a special feature, most
;;; useful for LMS and OWL, and in this package
;;; there are no paths defined by default. The
;;; keyword ALONG is synonymous with BEING. Note
;;; that there are variants of these subclauses, not
;;; described here, that are specifically tailored
;;; for iterating through the objects in a zone of
;;; an LMS node; these variants are recognized by
;;; the fact that EACH occurs where the pathname or
;;; ITS would normally have occurred.
;;;
;;; The sub-keywords like FROM, IN, etc., are recognized by having an
;;;!ITER-FUNCTION property; thus, others may be added to the package.
;;;
;;; TERMINATION CLAUSES allow specification of additional
;;; iteration termination conditions beyond any that are
;;; implied by FOR and AS clauses. The following exist:
;;;
;;; WHILE e1 -- e1 is evaluated at the beginning of each
;;; iteration, and the iteration terminates when e1
;;; is NIL.
;;; UNTIL e1 -- like WHILE but terminates when e1 is non-NIL.
;;; REPEAT-WHILE e1 -- e1 is evaluated at the end of each
;;; iteration, and the iteration terminates when e1
;;; is NIL; this guarantees at least one
;;; iteration.
;;; REPEAT-UNTIL e1 -- like REPEAT-WHILE but terminates when e1 is
;;; non-NIL.
;;;
;;;
;;; A SELECTION-CLAUSE is a filter on which iteration the
;;;main clause should be evaluated. A conjunction is implied if more
;;; than one selection exists. The following exist:
;;; WHEN e1 -- The main clause is evaluated if e1 is non-NIL.
;;; UNLESS e1 -- The main clause is evaluated if e1 is NIL.
;;;
;;;
;;; The PERIPHERAL CLAUSES are of three kinds:
;;;
;;; FIRST e1 -- Evaluates e1 after initially binding the vars
;;; but before starting the first iteration.
;;; FINALLY e1 -- Evaluates e1 after exiting the last iteration
;;; but before returning the answer. If the main
;;; clause is a value-returning clause, the result
;;; to be returned is in the variable RESULT (see notes).
;;; EACH-TIME e1 -- Evaluates e1 on every iteration of the loop,
;;; whether or not the selection test is passed.
;;;
;;*page
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; CAVEATS ;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;
;;;
;;; A few notes should be made about implementation features
;;;which affect the evaluation of iteration forms:
;;;
;;; 1. Like in the LISP DO, initialization and updating of the
;;;iteration variables takes place in parallel. Only SET-TO varaibles
;;;and their internally generated equivalents (e.g., "X in Y") are done
;;;after the others, and these should never lead to trouble. This is a
;;;significant change from earlier versions of the FOR package.
;;;
;;; 2. The iteration statement is translated to a LISP DO. In
;;;particular, this means that a (RETURN val) form may be
;;;evaluated at any place to return that particular val as the
;;;value of the iteration. If it is desired that any FINALLY
;;;clauses be evaluated and the value returned, then the
;;; following may be done:
;;; (SETQ RESULT val), if appropriate and if the main clause
;;; is value-returning
;;; (TERMINATE-ITERATION)
;;;Note that the RESULT clause may be used in many cases where this is
;;;desired.
;;;
;;; 3. Wherever possible, the order of evaluation of
;;;expressions whose evaluation order is not otherwise
;;;constrained is that suggested by the order of writing them in
;;;the iteration statement. This is only of significance if
;;;significant use of side effects is made.
;;;
;;; 4. Wherever a single expression may appear, more than one
;;;may appear. They will be implicitly surrounded by a PROGN,
;;;so all but the last will be evaluated for side effect only.
;;;
;;; 5. The name RESULT, in which the value of value-collecting
;;;iterations is built up, is selected only by default. If the
;;;value of the variable !RESULT-NAME is bound, that will be
;;;used instead.
;;;
;;; 6. Almost no error checking is currently done, so it is
;;;possible to get weird errors if the iterative statement is
;;;not well-formed.
;;;
;;; 7. This code is written using (I think) only one macro,
;;;!PUSH, which is not part of the standard LISP complement.
;;;!PUSH is defined herein to be equivalent to PUSH with its
;;;arguments reversed, except that it only works for simple
;;;(atomic) variables.
;;;
;;; 8. For efficiency, translations produced by these macros
;;;are saved in the array !MACRO-EXPANSIONS and further calls on
;;;the same form are translated by retrieval rather than
;;;recomputation. This, however, may cause some problems: For
;;;efficiency considerations (i.e., SXHASH or EQUAL are slow),
;;;retrieval is done by EQ comparison on the form. Thus, if the
;;;form has been edited since its original translation, an
;;;incorrect translation will be retrieved. Further, since all
;;;translated forms are referred to from !MACRO-EXPANSIONS, many
;;;un-garbage-collectable obsolete copies of a form can be
;;;retained during debugging runs. (E.g., if one keeps
;;;redefining some function which includes macro calls. For
;;;anyone who thinks they can solve this problem by retrieval on
;;;the MAKNUM of the form or by making the array untraced by the
;;;GC, be warned that either "fix" causes mis-translations.) The
;;;function !MACRO-FLUSH is provided to flush all existing
;;;translations and guarantee that new translations of all these
;;;macro forms are made. This also releases for
;;;garbage-collection all the "old" forms which are only pointed
;;;at by this translation mechanism.

74
doc/libdoc/graphs.usage Executable file
View File

@@ -0,0 +1,74 @@
This is an archive of graphics utilities written sometime
during 1980 by George Carrette. Files marked with a "*"
are used by the CONSTANCE II mirror-confined plasma experiment
data-analysis system written by Michael Mauel.
* GRAPH$ Floating-point graphics.
GRAPH3 3-d graphics.
* GRAPHA Ards hardware support.
GRAPHM Declarations and Macro support for package.
* GRAPHS Generic runtime support and autoload defs.
GRAPHT Tektronics 4010 hardware support.
PLOT 2-d plotting examples.
PLOT3 3-d plotting examples.
Summary of graphics package. -George Carrette.
Load the GRAPHM module at compile-time to get all
the needed declarations.
Load the GRAPHS module at runtime to get the basic entry
points and autoload definitions.
(MAKE-ARDS-STREAM <SFA-OR-FILE-OBJECT>) ; Return a STREAM taking FIXNUMS
(MAKE-TEK-STREAM <SFA-OR-FILE-OBJECT>) ; Return a STREAM taking FIXNUMS
[Both give streams, which are implemented using hunks or lists
depending upon what the compile-time setting in GRAPHM was.]
(MAKE-GRAPHICS-STREAM <STREAM>)
Gives a floating-point stream, complete with windows and
viewports.
Operations on all streams:
(SET-PEN <STREAM> X Y) ; Sets the pen.
(MOVE-PEN <STREAM> X Y) ; Draws a line from last setting.
(VECTOR-PEN <STREAM> X Y) ; Relative MOVE-PEN
(DRAW-POINT <STREAM> X Y) ; Draw a line of zero length.
(DRAW-LINE <STREAM> X0 Y0 X1 Y1) ; Most popular operation.
The above all do mapping if X and Y are both lists or arrays.
Operations specific to GRAPHICS-STREAM:
(SET-VIEWPORT <STREAM> X0 X1 Y0 Y1) ; FIXNUM range to feed to ARDS or TEK.
(SET-WINDOW <STREAM> X0 X1 Y0 Y1) ; FLONUM domain of stream.
(GET-WINDOW <STREAM>)
(DRAW-FRAME <STREAM>) ; Calls GET-WINDOW to do the obvious thing.
Operations specific to the low-level ARDS and TEK streams.
(CALL <STREAM> 'BOUNDARIES) ; returns maximum allowed for SET-VIEWPORT
Utilities:
(MAKE-BROADCAST-SFA <SFA-OR-FILE-OBJECT1> <SFA-OR-FILE-OBJECT2> ...)
(MAKE-BROADCAST-STREAM <STREAM1> <STREAM2> ...)
3d-Graphics:
(MAKE-Z-PERSPECTIVE-STREAM <GRAPHICS-STREAM>) ; 3d=>2d mapping.
(MAKE-Z-CLIP-STREAM <3D-STREAM>) ; 3d=>3d plane clipping.
(MAKE-ORTHOGONAL-3D-STREAM <3D-STREAM>) ; 3d=>3d rotation.
Other:
(PLOTF '(<f1> <f2> ...) X0 X1 N) ; plots some functions.
The plot functions are meant to serve as example usage.

11
doc/libdoc/save.notes Executable file
View File

@@ -0,0 +1,11 @@
;;; SAVE Package Bugs
;;;
;;; [Source: DR (07/11/80)] Re: UNSAVE vs INCLUDEF
;;; When i loaded ((dsk liblsp)save fasl) , then did (setq save-verbose t)
;;; and then finally (unsave filename), where this filename had
;;; includef's, apparently unsave didn't read in from the "includef"
;;; files, or in any event, all the functions from these files turned out
;;; to be undefined.
;;;
;;; [Source: WGD (1/3/81)]
;;; loses grossly when one tries to save vectors.

124
doc/libdoc/stack.info Executable file
View File

@@ -0,0 +1,124 @@
;;; FRIDAY NOV 19,1976 10:51:28
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; STACK DEBUGGING TOOLS
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; These routines are for crawling around in the LISP stack. For
;;;any meaningful stack information to be available *RSET must be set to
;;;T. Further, only minimal information will be present for compiled
;;;calls unless NOUUO is T. This package takes up 376. decimal words.
;;; The variable *FRAME*-*POINTER* (hereafter called the CURSOR) is
;;;always bound to a "stack frame 4-tuple". Each tuple is the value of
;;;an EVALFRAME function call. All the functions described below,
;;;unless otherwise noted, have as their value the current CURSOR.
;;; The CURSOR is either of the form:
;;; (EVAL <pdl-ptr> <form> <spec-pdl-ptr>) or
;;; (APPLY <pdl-ptr> (<operator> <arglist>) <spec-pdl-ptr>)
;;;The first atom is a keyword identifier indicating the format of the
;;;third entry. EVAL means that the form is an entity that is being
;;;EVAL'ed and the user could EVAL to see the effect. APPLY means that
;;;the third element is the list of the operator and its argument list.
;;;The argument list has been evaluated and is ready for the operator to
;;;be APPLY'ed to it. The user can do the latter by hand to see the
;;;effect.
;;; The <pdl-ptr> and <spec-pdl-ptr> print as FIXNUM's. They are
;;;pointers that are meaningful for EVALFRAME, FRETURN, EVAL, APPLY and
;;;a few other commands. The reader is refered to the MACLISP manual
;;;for a more detailed discussion.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; COMMANDS
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;TOP (no args)
;;; Set the CURSOR to the "top" of the stack. The "top" is closest
;;;to the break. Like a plant the growing point of a stack is at its
;;;top.
;;;BOT (no args)
;;; Set the CURSOR to the "bottom" of the stack. The "bottom" is
;;;the frame of the last call from "command line".
;;;UP (fexpr)
;;; Move the CURSOR another frame towards the top. Falling off the
;;;top of the stack causes an error message to be printed. The CURSOR
;;;is not changed. (Thus the value of UP will be EQ to its previous
;;;value).
;;;DN (fexpr)
;;; Move the CURSOR another frame towards the bottom. Falling off
;;;the bottom of the stack causes an error message to be printed. The
;;;CURSOR is not changed. (Thus the value of DN will be EQ to its
;;;previous value).
;;;both UP and DN
;;;take the following arguments:
;;; <some number> do the operation that many times
;;; <some function> go to the frame where that function was invoked
;;; the letter F move the CURSOR until the first user function
;;; call is encountered
;;; the letter I move the CURSOR until the first non-compiled
;;; user function call is encountered
;;; the letter C move the CURSOR until the first compiled user
;;; function call is encountered
;;; the letter M move the CURSOR until the first user macro call
;;;FR (lexpr)
;;; Given no argument, its value is simply the CURSOR.
;;; Given an argument, it will reset the CURSOR to the argument.
;;;FM (no args)
;;; Return only the FORM of the stack frame. This is the third
;;;element of the CURSOR structure.
;;;RET (lexpr)
;;; no arg - reexecute the form at the cursor and unwind the stack
;;; Only this type execution of RET evaluates in the
;;; original (CURSOR) lambda variable binding environment
;;; one arg - return the arg in place of computing the value of the
;;; form at the CURSOR.
;;; two arg - as above, but use (arg 2) in place of the CURSOR.
;;;EV (lexpr)
;;; one arg - evaluate the arg in the binding environment of the
;;; CURSOR frame.
;;; two arg - as above, but use (arg 2) in place of the CURSOR.
;;;EVQ (fexpr)
;;; The evalquote version of the above function.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; HINTS
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; When the CURSOR 4-tuple is of the EVAL type (the first element
;;;of the tuple is EVAL), the form component is EQ to the piece of code
;;;that is in the actual function being executed. Thus RPLAC operators
;;;on this form wil make patches to the function.
;;; RET is most useful to return the correct value for some
;;;evaluation sequence that has gone amuck and proceed with the overall
;;;processing. It eliminates the necessity of starting again from the
;;;beginning because of some "simple" bug.
;;; To evaluate a number of variables and forms in some frame
;;;context it is often easier to do a (EVQ (BREAK FOO)) rather than
;;;repetitive EVQ's. The former expression places a BREAK "at an
;;;earlier place in the evaluation". Obviously this BREAK should be
;;;$P'ed, when it is no longer needed.

144
doc/libdoc/struct.news Executable file
View File

@@ -0,0 +1,144 @@
-*-Text-*- 5/27/82 Alan
New features in defstruct:
There are three new defstruct options:
1) print
This allows the user to control the printed representation of his structure in
an implementation independent way:
(defstruct (foo named
(print "#<Foo ~S ~S>" (foo-a foo) (foo-b foo)))
foo-a
foo-b)
The arguments to the print option are arguments to the format function (except
for the stream of course!). They are evaluated in an environment where the
name symbol of the structure (foo in this case) is bound to the instance of the
structure to be printed.
Note, please, that this option presently only works on LispMachines and in NIL.
We hope to make it work in PDP-10 MacLisp soon. In Multics MacLisp, this
option is ignored.
2) predicate
The predicate option causes defstruct to generate a predicate to recognize
instances of the structure. Naturally it only works for some defstruct types.
Currently it works for all the named types as well as the types sfa (MacLisp
and NIL only) and extend (NIL only). The argument to the predicate option is
the name of the predicate. If it is present without an argument, then the name
is formed by concatenating "-p" to the end of the name symbol of the structure.
If the option is not present, then no predicate is generated. Example:
(defstruct (foo named predicate)
foo-a
foo-b)
defines a single argument function, foo-p, that is true only of instances of
this structure.
3) copier
This option causes defstruct to generate a single argument function that will
copy instances of this structure. Its arguemnt is the name of the copying
function. If the option is present without an argument, then the name is
formed by concatenating "copy-" with the name of the structure. Example:
(defstruct (foo (type list) copier)
foo-a
foo-b)
Generates a function approximately like:
(defun copy-foo (x)
(list (car x) (cadr x)))
Inprovements:
It is now impossible (I believe) to confuse defstruct by typing or not typing
colons in front of various defstruct options and keywords. defstruct, in Lisps
without a package system, knows how to compensate for people who spell their
keywords with a colon as the first character, and in Lisps with packages, it
knows how to find the symbol the user meant to type in the keyword package.
It is now possible to use alterant macros on defstruct types whose accessors
require additional arguments (like the old grouped-array type). The
additional arguments are given to the alterant macro in exactly the same order
they are given to the accessors, before the "setq-style" list of slots and new
values.
Remnants removed:
The old displace defstruct option has now been completely flushed. The current
story on when defstruct-defined macros displace is that they NEVER displace.
This is because there isn't even a remotely compatible theory on displacement
between various dialects. Someday we'll figure one out, but until then
defstruct just plays it safe.
Multics MacLisp:
It now works to have defstruct loaded into lcp without the rest of the Mathlab
macrology. Previously it was necessary to load the Mathlab environment in
order to ensure that macros defined by defstruct actually got defined in the
object segment. No one seems to have noticed this except me, so I presume that
you are all loading the Mathlab stuff, or you are always keeping your structure
definitions in the same files that use them, or you are not compiling your
defstructs.
NIL:
defstruct is now supported in the NIL dialect of Lisp. defstruct types
specifically intended for NIL are: vector, named-vector, and extend. The
extend type is a named type. Vectors are what you get by default (no type
specified in the defstruct header), and if you ask for a named type (by just
using the named option) you get an extend. The extend type is the one that
knows how to print itself smartly.
LispMachine:
The new make-array keyword :initial-value is supported. Note that the slots of
an array-type structure are initialized by the constructor code AFTER the array
is initialized by make-array.
Two new options to defstruct-define-type:
1) predicate
The predicate option to defstruct-define-type is how defstruct is told how to
produce predicates for a particular type. Its syntax is:
(predicate (<description> <name>)
<body>)
The variable <description> will be bound to the defstruct-description structure
maintained for the structure we are to generate a predicate for. The variable
<name> is bound to the symbol that is to be defined as a predicate. <body> is
a piece of code to evaluate to return the defining form for the predicate. A
typical use of this option might look like:
(predicate (description name)
`(defun ,name (x)
(and (frobbozp x)
(eq (frobbozref x 0)
',(defstruct-description-name)))))
2) copier
defstruct knows how to use the constructor and reference macro code that must
be provided with any new defstruct type to generate a copying function.
Nevertheless it is sometimes desirable to specify a specific method of copying
a particular defstruct type. The copier option to defstruct-define-type allow
this to be done:
(copier (<description> <name>)
<body>)
Similar to the predicate option, <description> is bound to an instance of the
defstruct-description structure, <name> is bound to the symbol to be defined,
and <body> is some code to evaluate to get the defining form. For example:
(copier (description name)
`(fset-carefully ',name 'copy-frobboz))

392
doc/libdoc/window.info Executable file
View File

@@ -0,0 +1,392 @@
.xgp
.squish
.font 1 31vr
.font 2 31vgb
.font 3 40vg
.sinch 8.5,6.5,11,8.5,1
.ad
.ss
.vsp 14
.ce
3THE LISP WINDOW SLAVE1
.space 2
.ce
by
.ce
Chuck Rieger
.ce
November 1975
.space 2
There exist today AI systems which are so marvelously complex and sophisticated that
it is a shame to have to communicate with them in the one-dimensional paradigm of
the classical teletype-like device. There also exist AI programs so profoundly
worthless that it is a shame to have to communicate with them at all, unless there
is something intrinsically fun or soporific about the communication process. Since
every program fits exactly one of these descriptions, it logically
follows that it's a shame
not to have some better paradigm for human-computer interaction than that offered
by the classical teletype-like device. Shame, shame. Hence, the notion of windows.
There is now a collection of LISP functions on AI:LIBLSP;WINDOW CJR1, with a
LISP-loadable
FASL counterpart which slithers out when you say (FASLOAD WINDOW FASL AI LIBLSP).
The functions in the "window slave" package on this file
make it possible to segment the screen of a Datapoint or TV terminal
into an arbitrary number of "windows". Each window can then serve as a logically
independent I/O channel through which individual LISP functions can communicate with the
outside world without disturbing the states of other windows.
The slave makes the assumption that it has exclusive control over the state of
the display screen. Of course, if you graft new window-oriented code into an existing
program which does not know about the slave, this assumption will not be valid (eg.
non-window I/O will write wherever it pleases).
Since it will often be desirable to use existing programs without modification, the
window slave repertoire includes a function, (WSANITIZE <window-name>), which will
automatically "sanitize" the lisp environment in a way which is both undoable (via
WUNSANITIZE) and compatible with the window slave. WSANITIZE basically snaps all
links to the LISP I/O functions, and redefines them to route non-window I/O through
a specified window.
On the other hand, the slave is smart
enough to do approximations to the right things when you run a window-oriented
program on a non-display terminal. Thus, using the window slave does not preclude
running your window-oriented program on less exotic devices.
.space 2
.block 8
.ce
3GENERAL INFORMATION1
The Datapoint or TV
screen is viewed as a raster of characters, with (0,0) denoting the top left
character, X increasing to the right, Y increasing toward the bottom.
A window manifests itself on the screen as a collection of components: a (possibly
invisible frame), an active interior region (everything inside the frame), possibly
a name (displayed in the center of the top edge of the frame), and possibly
a line cursor,
displayed on the left edge of the frame. You may overlap window regions, but the
slave isn't very clever about this in that it will simply overwrite.
Internally, a window is simply an atom which has the following properties:
.nofill
2WINDOW1 the atom is a window iff this property is non-NIL
2X1 the X-coordinate of the left edge of the active portion
of the window. "Active" means the region inside the frame.
2Y1 the Y-coordinate of the top edge of the active portion of
the window
2DX1 the width of the active region of the window
2DY1 the height of the active region of the window
2CX1 the X-coordinate of the window's cursor
2CY1 the Y-coordinate of the window's cursor
2NAMED1 the display name of the window, if any
2FRAME1 the nature of the frame (visible, invisible)
2CURSOR1 a property used by the cursor-mover
2HOLD1 a flag to indicate whether or not the window is to
be "held" after each output (see WHOLD)
2SHOWCUR1 a flag indicating whether or not the window's cursor is
to be displayed
2READPROMPT1 the prompt to be printed when this window requests input
(see WREAD)
2CRLFPURGE1 a flag indicating whether or not to check for
carriage-returns and line-feeds when printing
(see WPRINC)
2ECHO1 a flag indicating whether or not to echo the results
of window reads into the window (see WREAD)
.fill
.ad
Text written to a window exists only in the operating system's display logic.
In other words, there is no internal buffer associated with a window, and once
something has been written, it's not readable or regenerable. Adding the buffer
feature would be straightforward, but space-consuming.
The slave defines and uses the following global variables:
.nofill
2W-WINDOWS1 a list of all active windows
2W-BOTTOM1 the Y coordinate of a line on the screen which separates
the slave-usable area from the system-usable area. The
lines of the screen below W-BOTTOM are the "garbage" I/O
area, where non-window I/O (eg. interactions with LISP's
top level) is handled. If your program hasn't been properly
sanitized, and someone tries to write too much in this
area, the system will wrap you around to the top, messing
up the window area. W-BOTTOM is initialized to give you 4 or
5 lines of garbage space at the bottom.
2W-ACTIVE1 a flag which, if non-NIL, tells the slave to do its thing.
If nil, the slave emulates normal I/O. When the slave is loaded,
it pokes around to determine the type of device and sets
W-ACTIVE appropriately. You may turn the slave on and off
simply by manipulating this variable.
2TV1 an array, mapped onto the PDP-11's display buffer when
the window slave is used in a TV environment
.fill
.ad
In addition, the value of the LISP global variable TTY is consulted to determine
the output device type (TV= 5, Datapoint= 1,2).
.space 2
.block 8
.ce
3THE FUNCTIONS1
All the window slave functions are EXPR's. For each of the following functions which
expects the <name> of some window, calling that function with <name>= NIL causes
the function to emulate normal TTY I/O, or simply do nothing, as appropriate.
.space 2
.block 5
2INDIVIDUAL WINDOW DEFINITION AND STATUS-SETTING FUNCTIONS1
(2WOPEN1 <name> <x> <y> <dx> <dy> <frame> <d-name> <now>)
.in 5
Opens a window of size <dx> by <dy> named <name>, with top left corner at
(<x>,<y>). If <frame> is NIL, makes the frame invisible, otherwise draws a
visible frame. The size you specify is the size of the entire window,
including the frame. The active interior area will be 2 units smaller in
each dimension, regardless of whether the frame is visible. Thus, the
smallest meaningful window is 3 by 3. Inside the window,
the top left cell of the active region is (1,1), with increasing X to the right
and increasing Y toward the bottom. If <d-name> is non-NIL, WOPEN displays <d-name>
in the center of the top edge of the frame. Otherwise, the window will have
no visible name. If <now> is non-NIL, WOPEN actually paints the window on the
screen. Otherwise, WOPEN does not actually cause the window to be displayed.
This latter mode is useful when
you wish to declare lots of windows, then paint them all at once via a
WRESTART. WOPEN clears the active region and initializes the <name>'s
cursor to the top left of the active region. If <name> is already open,
WOPEN behaves like a WRESET.
.in 0
(2WCLOSE1 <name>)
.in 5
Removes window <name> from the screen and discards it logically.
.in 0
(2WCLEAR1 <name>)
.in 5
Clears <name>'s active region and resets its cursor to the top left of
the active region.
.in 0
(2WRESET1 <name>)
.in 5
WCLEAR's <name>, but also refreshes the border, name and line cursor.
WRESET is useful for refreshing an accidentally-clobbered window.
.in 0
(2WNAME1 <name> <display-name>)
.in 5
Gives window <name> the new display name <display-name>. <display-name>= NIL
causes no name to be displayed for <window>.
.in 0
(2WSHOWCUR1 <name> <mode>)
.in 5
If <mode> is non-NIL, the cursor for window <name> will henceforth
be visible on the left
edge of <name>'s frame. Otherwise, displaying of the cursor will be inhibited.
.in 0
(2WFLASH1 <name>)
.in 5
If the terminal is a TV, momentarily bit-complements the interior region of window
<name> to call attention to I/O activity in the window. If the terminal is not a
TV, WFLASH does nothing.
.in 0
.space 2
.block 5
2OVERALL DISPLAY-STATE FUNCTIONS1
(2WRESTART1)
.in 5
Clears the entire screen, WRESET's all currently active windows (those on
W-ACTIVE), and draws a line across the screen at Y coordinate (W-BOTTOM)-1
to separate the window slave region (above the line) from the normal I/O
garbage region (below the line). Thus, a typical window slave setup consists
of WOPENing a herd of windows, then doing a WRESTART.
.in 0
(2WBOTTOM1 <y>)
.in 5
Sets W-BOTTOM to <y>. W-BOTTOM separates the window area (above) from
the garbage I/O area (below). 32 (decimal) is the default setting of
W-BOTTOM on TV's, 20 (decimal) on Datapoints.
.in 0
(2W-OFF1)
.in 5
Turns the window slave off by setting W-ACTIVE to NIL and doing a WUNSANITIZE, then
clears the screen.
.in 0
(2W-ON1 <name>)
.in 5
Turns the window slave on by setting W-ACTIVE non-NIL and calling WRESTART. If
<name> is non-NIL, W-ON does a (WSANITIZE <name>), otherwise it does not.
.in 0
.space 2
.block 5
2OUTPUT RELATED FUNCTIONS1
(2WPRINC1 <name> <e>)
.in 5
Expression <e> is PRINC'd to window <name>, starting at the position to
the immediate right of <name>'s cursor. New lines are begun as needed and the
cursor is left pointing at the last character written. When characters would
fall off the bottom of the window, wrap-around to the top occurs. WPRINC
piecewise butchers <e> so that it fits within <name>'s active region.
.in 0
(2WPRINT1 <name> <e>)
.in 5
Expression <e> is PRINT'd to window <name>. WPRINT functions by calling
WPRINC, then positioning the cursor at the beginning of the next line,
which is wiped clean at that time.
.in 0
(2WTYO1 <name> <n>)
.in 5
TYO's <n> to window <name>.
.in 0
(2WCRLFPURGE1 <name> <mode>)
.in 5
If it is expected that the print stream to <window> will occasionally contain
carriage-returns and line-feeds, characters which tend to wreck the display,
WCRLFPURGE should be called with <mode> non-NIL. When in this mode, the window output
functions will sanitize all output to <window>
by deleting carriage-returns and line-feeds. Since this is fairly time consuming,
this mode should be used only when dealing with unknown output-generating sources.
The default is <mode>= NIL.
.in 0
(2WINC1 <name> <amt>)
.in 5
If <amt> is zero, WINC simply guarantees the cursor to be positioned at
the beginning of a new line. If it already is, nothing else happens. If
<amt> is positive, <amt> number of TERPRI's are simulated on the window,
clearing intermediate lines as they are passed over, and
leaving the cursor at the beginning of a fresh line.
If <amt> is negative, the simulated TERPRI's
go backward, from bottom to top. (WINC <name> -1) is a convenient way of
implementing a "pop" if you are using a window to display a stack.
.in 0
(2WSETPOS1 <name> <y> <x>)
.in 5
Positions <name>'s cursor at (<y>.<x>). If <x> or <y> is NIL
WSETPOS leaves the respective coordinate alone.
.in 0
(2WHOLD1 <name> <mode>)
.in 5
If <mode> is non-NIL, WHOLD causes all subsequent WPRINC's and WPRINT's
to pause after printing and wait for a go-ahead from the TTY. A pause
message is printed in the garbage area of the screen. Typing any character
gives the go-ahead, and furthermore, if that character is "C", the hold is removed
from the window, causing future prints not to pause. Calling WHOLD with
<mode>= NIL causes <name> to be uh-held.
.in 0
.space 2
.block 5
2INPUT RELATED FUNCTIONS1
(2WREAD1 <name>)
.in 5
Prints (in the garbage area of the screen) a message that window <name> is
waiting for input, waits for an S-expression to be typed there, then copies
the typed S-expression into the named window ("for the record") and returns
the S-expression to the calling function.
.in 0
(2WREADCH1 <name>)
.in 5
To WREAD as READCH is to READ.
.in 0
(2WTYI1 <name>)
.in 5
Does a TYI to window <name>, printing a prompt as do WREAD and WREADCH.
.in 0
(2WREADPROMPT1 <name> <prompt>)
.in 5
If <prompt> is non-NIL, it is used as the prompt for all WREAD's, WREADCH's and
WTYI's done by window <name>. If <prompt> is NIL, a standard prompt is printed.
.in 0
(2WECHO1 <name> <mode>)
.in 5
Sets the "echo" satus of window <name> to <mode>. If <mode> is non-NIL, the
results of all WREAD's, WREADCH's and WTYI's to <window> will be echoed (WPRINTed)
to <window>. Otherwise, no echoing occurs. <mode>= T is the default.
.in 0
.space 2
.block 5
2INFORMATION FUNCTIONS1
(2WINDOWP1 <name>)
.in 5
Returns non-NIL if <name> is a window, NIL otherwise.
.in 0
(2WSIZE1 <name>)
.in 5
Returns the size of the active interior region of window <name> in the form
(COLUMNS.LINES).
.in 0
(2WCURPOS1 <name>)
.in 5
Returns the current coordinates of <name>'s cursor in the form (LINE.COLUMN). These are
the relative coordinates (within the active region of the window), not the
absolute coordinates relative to the entire screen. The top left character
in the active region is (1,1).
.in 0
.space 2
.block 5
2SANITIZING FUNCTIONS1
(2WSANITIZE1 <name>)
.in 5
Snaps all the uuolinks to the basic LISP I/O functions, and redefines
the functions
to route them to the display slave. Henceforth (until a (WUNSANITIZE)), all I/O
that would have been printed normally is confined to window <name>. The affected
functions are: PRINT, PRINC, TYO, TERPRI, READCH, READ, TYI, and CURSORPOS. Care
has been taken to emulate these faithfully, but there are no blanket guarantees.
In particular, they are known not to work when I/O to files is involved (ie. when
more than the basic argument is given to one of these functions). The patch isn't
complicated; it just hasn't been done.
.in 0
(2WUNSANITIZE1)
.in 5
Undoes what WSANITIZE does by restoring the original I/O functions' definitions.
Uuolinks are not repaired, but otherwise, things are as they were. It is a good
practice to do a WUNSANITIZE before using LEDIT, since LEDIT tickles the problem
mentioned above.
.in 0
.space 2
.block 8
.ce
3CAVEATS1
Obviously, you pay a price for the goods. The principal loss of speed is from the
piecewise butchering that must be done on every expression printed to a window
(basically a TYO inside a DO-loop munching on the EXPLODEN'd expression). I know of
no better way, short of modifying the LISP printers. When you are getting around 30%
of the CPU time, you stop noticing the slowdown; but still, output is probably slowed
by a factor of 2.
The other thing you need to know is that, after you've FASLOAD'd the window slave into
a LISP image which is talking to a TV, you can't successfully
(SUSPEND), :PDUMP and subsequently reload your image.
(That's usually a gross thing to do anyway.)
This is because some PDP-11 memory mapping hair
has transpired and this becomes a source of confusion for the poor loader. There's
probably a way to undo the hair to permit dump/load's, but I don't know how to do it.
There. I've given you some rope; now go hang yourself and enjoy, enjoy.