09/24/83  MR10.2 lisp changes

Several extensions were made to Multics Maclisp in Multics
Release 10.2.  These mostly involve the release of several
packages that define functions used in PDP-10 Maclisp, allowing
greater compatibility between the dialects.  No Multics
documentation is currently provided for the individual functions
and macros defined in these packages (other than what little
documentation is provided here).  However, they are all
documented in "The Revised Maclisp Manual" (aka the "Pitmanual")
available from the Massachussetts Institute of Technology
Laboratory for Computer Science as MIT/LCS/TR-295, or other
MIT/LCS documents as noted below.  Most of these extensions are
also compatible with Zetalisp, the Lisp Machine dialect of
Maclisp, and are therefore documented in "The Lisp Machine
Manual", which is available from the MIT Artificial Intelligence
Laboratory, Lisp Machines, Inc., and Symbolics, Inc.


New builtins: The following functions were added to the
interpreter and compiler:

first, second, third, fourth: equivalent to car, cadr, caadr, and
caaadr, respectively, but which have more mnemonic names.

rest1, rest2, rest3, and rest4: equivalent to cdr, cddr, cdddr,
cddddr.


(nthcdr N LIST): takes the cdr of LIST N times, i.e.
	(nthcdr 0 LIST) = LIST
	(nthcdr 2 LIST) = (cddr LIST)
	(nthcdr 8 LIST) = (rest4 (rest4 LIST))

(nth N LIST): equivalent to (car (nthcdr N LIST)), i.e.
	(nth 0 LIST) = (car LIST)
	(nth 3 LIST) = (cadddr LIST)
	(nth 7 LIST) = (cadddr (cddddr LIST))

Note that (nth 1 LIST) is not the same as (first LIST), since nth
is 0-based.

(displace OLD-CONS NEW): if NEW is a list, rplaca's OLD-CONS with
(car NEW) and rplacd's it with (cdr NEW), thus making OLD-CONS
"look like" NEW.  If NEW is an atom, (progn NEW) is used as the
patter to displace into OLD-CONS.  OLD-CONS is returned.


includef: like include and %include, except that it evaluates its
argument.  In the compiler it is interpreted in the compiler's
environment.

cursorpos: an interface to video terminals (it only works when
the video system has been invoked).  See the Revised Maclisp
Manual for the complete description.


Non-default extensions:
The rest of these extensions are not loaded or autoloaded into
the default Lisp environment.  To use them you should %include
the module in which the extension is defined.  You may also do
(%include library) in order to load in all the extensions.


Module: defmacro:
This module defines the two special forms "macro" and "defmacro",
which make macro writing easier.


Module: defstruct:
This module defines the special forms "defstruct" and
"defstruct-define-type".  These are documented in detail in
MIT/LCS/TM-203, "Maclisp Extensions," but there is ample
documentation for defstruct in The Revised Maclisp Manual.


Module: defun:
This module defines an extended version of the special form
"defun", which provides a simple interface to optional arguments,
default values, and local variables.  See one of the manuals for
details.


Module: destructuring_let:
This module defines an extended form of the special form "let",
which provides "destructuring".  This means that the VAR in each
(VAR VALUE) pair may be replaced with an s-expression pattern,
and the symbols in the pattern will be bound to the matching
elements of the VALUE structure.  This module also defines
"let*", a sequential version of "let", and "desetq", a
destructuring version of "setq".


Module: loop:
This module defines the "loop" special form and a number of
functions and special forms for writing loop extensions.  Loop is
an English-style language for writing iterative forms.  It is
summarized in the Revised Maclisp Manual, and described fully in
MIT/LCS/TM-169, "LOOP Iteration Macro."


Module: macro_macros:
This module defines macros that are useful when writing macros.
Currently, only "once-only" is defined.  Since this does not seem
to be documented anyplace but the Lisp Machine Manual, I will
reproduce its documentation here:

A once-only form looks like
	(once-only VAR-LIST
	  FORM1
	  FORM2
	  ...)


VAR-LIST is a list of variables.  The FORMs are a Lisp Program
that presumably uses the values of those variables.  When the
form resulting from the expansion of the once-only is evaluated,
the first thing it does is to inspect the values of each of the
variables in VAR-LIST: these values are assumed to be Lisp forms.
For each of the variables, it binds that variable either to its
current value, if the current value is a trivial form, or to a
generated symbol.  Next, once-only evaluates the FORMs in this
new binding environment and, when they have been evaluated, it
undoes the bindings.  The result of the evaluation of the last
FORM is presumed to be a Lisp form, typically the expansion of a
macro.  If all the variables have been bound to trivial forms,
then once-only just returns that result.  Otherwise, once-only
returns the result wrapped in a lambda-combination that binds the
generated symbols to the result of evaluating the respective
non-trivial forms.


The effect is that the program produced by evaluating the
once-only form is coded in such a way that each of the forms
which was the value of one of the variables in VAR-LIST will be
evaluated only once, unless the form is such as to have no side
effects.  At the same time, no unnecessary temporary variables
appear in the generated code, but the body of the once-only is
not cluttered up with extraneous code to decide whether temporary
variables are needed.


Module: other_other:
This module defines a number of random special forms for
compatibility with other Maclisp dialects.  The following is a
summary of the functions provided:

logand, logior, logxor, lognot, bit-test, bit-set, bit-clear: these
perform bitwise logical operations on fixnums (a la "boole").

fifth, sixth, seventh, eighth, rest5, rest6, rest7, rest8: these
extend the range of the primitive list examining functions.

evenp, neq, nequal, fixnump, flonump, listp, <=, >=: some
predicates with obvious functions.

copylist: returns a list whose elements are the elements of a
given list.


aref, aset: the modern array referencing functions.

ITS-if, ITS-ifn: the standard Maclisp "if" form.  These will be
on "if" and "ifn" unless you have previously loaded in the
Multics Emacs "if" (defined in e-macros.incl.lisp), as they are
incompatible.

when, unless: simple conditionals.

push, pop: for using lists as stacks, supporting the generalized
variable feature (see "setf", below).

incf, decf, negf, notf: for incrementing, decrementing,
arithmetically and logically negating generalized variables.


case, caseq, select, selectq, select-equal, selectq-equal:
dispatching functions.  Selectq is documented in the Revised
Maclisp Manual.  Caseq is also documented there, but on Multics
it is equivalent to selectq.  Select and case are like selectq,
except that the elements of the tests are evaluated; see the Lisp
Machine Manual for documentation of select.  The -equal forms are
similar, but use an equal comparison instead of eq; these only
exist on Multics, and are therefore not documented in any of the
MIT manuals.

dotimes, dolist: macros for common iterations.

defconst, ITS-defvar: for declaring special variables with
optional initializations.  The latter will be defined as "defvar"
only if e-macros-.incl.lisp has not been loaded, as they are
incompatible.


*catch, *throw: versions of catch and throw in which the tag is
evaluated.

psetq: parallel setq.

lexpr-funcall: like funcall, except that the last argument must
be a list and it is spread in the call.

without-interrupts, without-tty-interrupts: execute code with
interrupts disabled.  The second is not documented in any of the
manuals.

with-open-file: execute code with a specified variable bound to a
file object, which is automatically opened and closed.
Documented in the Lisp Machine Manual.


circular-list: constructs a circular list with the given
arguments as the elements, repeated infinitely.  Documented in
the Lisp Machine Manual.


Module: runtime:
This module defines a number of random special forms for
compatibility with other Maclisp dialects.  The following is a
summary of the functions provided:

fboundp, fmakunbound, fsymeval, fset: for manipulating and
examining the functional value of a symbol in a
dialect-independent manner (some dialects do not use the property
list).  Documented in the Lisp Machine Manual, and fboundp is
documented in MIT/LCS/TM-203.

ldb, dpb: byte manipulation.

firstn, butlast, nbutlast: return pieces of a list.  Documented
in the Lisp Machine Manual.

make-list: creates a list of a given length.


mem, find-position-in-list: for searching lists.  Documented in
the Lisp Machine Manual.

ass, rassq, rassoc: for searching association lists.  Documented
in the Lisp Machine Manual.

del, rem, remq, remove: for deleting elements from lists.  The
"rem" versions are non-destructive.  Documented in the Lisp
Machine Manual.

circular-list-last: rotates a circular list backwards.  Not
documented anywhere.

symbolconc: returns a symbol whose pname is the concatenation of
the pnames of the arguments.


bignum-ash, fixnum-ash, ash: arithmetic shift.  By default "ash"
is equivalent to "bignum-ash", which is compatible with the Lisp
Machine; on the PDP-10 it is equivalent to "fixnum-ash".


Module: setf:
This module defines the "setf" generalized variable facility,
which allows the use of any accessor to specify a cell which is
to be given a new value.  It also defines the "defsetf" special
form, which allows the user to extend "setf".


Module: sharpsign:
This module defines the sharpsign (#) reader macro, whose
function depends upon the following character.  Also defines the
"sharpsign-set-syntax" function, which is like
"setsyntax-sharp-macro" (documented in the Revised Maclisp
Manual) except that it does not take the optional readtable
argument, and "defsharp", a special form for defining a sharpsign
character.


Module: format:
This module defines "format", a function for producing formatted
output (similar to the Multics ioa_ subroutine).  Also defines
the function "?format" and the special form "define-format-op"
for extending the format facility.


                                          -----------------------------------------------------------


Historical Background

This edition of the Multics software materials and documentation is provided and donated
to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. 
as a contribution to computer science knowledge.  
This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology,
Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL
and BULL HN Information Systems Inc. to the development of this operating system. 
Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970),
renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership
of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture 
for managing computer hardware properly and for executing programs. Many subsequent operating systems 
incorporated Multics principles.
Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., 
as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. .

                                          -----------------------------------------------------------

Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without
fee is hereby granted,provided that the below copyright notice and historical background appear in all copies
and that both the copyright notice and historical background and this permission notice appear in supporting
documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining
to distribution of the programs without specific prior written permission.
    Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc.
    Copyright 2006 by BULL HN Information Systems Inc.
    Copyright 2006 by Bull SAS
    All Rights Reserved