
		BERGMAN PROCEEDINGS EXTENDING STANDARD LISP.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Copyright (C) 1996,1997 Joergen Backelin
%%
%% Bergman is distributed in the hope that it will be useful,
%% but WITHOUT ANY WARRANTY.  No author or distributor
%% accepts responsibility to anyone for the consequences of using it
%% or for whether it serves any particular purpose or works at all,
%% unless (s)he says so in writing.  Refer to the Bergman General
%% Public License for full details.

%% Everyone is granted permission to copy, modify and redistribute
%% bergman, but only under the conditions described in the
%% Bergman General Public License.   A copy of this license is
%% supposed to have been given to you along with bergman so you
%% can know your rights and responsibilities.  It should be in a
%% file named copyright.  Among other things, the copyright notice
%% and this notice must be preserved on all copies.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


	Introduction

 Bergman is written in Standard Lisp, as defined by the Standard
Lisp report (1).  This contains (on purpose) a rather restricted
number of procedures.  In some cases I have felt it simplifying or
even necessary to go outside the scope of Standard Lisp.  I then
have defined procedures of `general lispic' type, and collected
them in the source file slext.sl.

 Many of these procedures actually exist in psl (but often under
other names).  For such reasons I have provided alternative
definitions to most of them, copying definitions from or calling
existing procedures when available, and else defining them by
means of "pure" Standard Lisp.

 In order to sustain the multiple definitions, I use a very rough
`version handler', for obvious reasons written in Standard Lisp.
It consists of a number of macros and global variables, such that
depending on the variable settings some of them evaluate their
arguments but others just return NIL.  (Smoother version handlers
are available in some `modern' lisps, and of course in
preprocessors for c and similar languages.  In their effect, the
version handler macros are similar to c preprocessor #ifdef ...
#ifndef ... constructions, but in one sense they are completely
different: All is handled by the Standard Lisp top loop, which
actually is handled the suggested procedure definitions, but
takes no action on them.)  The handler macros are defined in
versmacr.sl, and the variables are set in a file specmode.sl
(which is created at the bergman installation with due respect
to the `environment'.)

 In this document, we list (hopefully) all the (general lisp)
extensions of Standard Lisp alphabeticallky, with short
explanations of their actions; we discuss deviations from the
Standard in the bergman sources; and we briefly discuss some
(potential) problems in the standard itself, and in the way it
does or does not provide a good basis for e.g. Reduce
implementations.

 All descriptions (here as in the manual) are in Standard Lisp
syntax, but they have rlisp (i.e., symbolic mode) correspondences
in Reduce.  In order to have maximal benefit from them, a reader
who wishes to do some deeper level bergman programming should be
acquainted with Standard Lisp (or symbolic mode).



	Fast variant Standard Lisp extensions.

BMI!+ <--> PLUS2
BMI!- <--> DIFFERENCE
BMI!* <--> TIMES2
BMI!/ <--> QUOTIENT
BMI!< <--> LESSP
BMI!= <--> EQ
BMI!> <--> GREATERP
FASTGETV <--> GETV

 The EXPRs or MACROs to the left operate as those to the right, with
the following two exceptions: Input need not be typechecked, and input
and (for the first six ones) resulting numbers should be "INUMs", i.e.,
fairly small integers. Thus, the compiled code may use fast integer
arithmetics on them. (You may note that in the sources, these macros
are used on coefficients who are known to be of limited size and on
degree numbers and variable indices, while the right ones are used
on integer coefficients of indefinite size and e.g. on coefficients
in series calculations, where BIGNUMs may appear.)


	General Standard Lisp extensions.

(ADDINTTOLIST int lint)
 int should be a number, and lint a list (i_1 i_2 i_3 ...) of numbers.
The list (i_1+int i_2+i i_3+i ...) is returned.

(APPENDLCHARTOID lch id): EXPR
 lch should be a list of characters, id an identifier. Returns an
interned identifier, whose print name consists of the characters on
lsh followed by the print name of id. [Thus perhaps PREPENDLCHARTOID
would be a better name!]

(APPENDNUMBERTOSTRING numb strng): EXPR
 A new string is formed, consisting of the characters in the string
strng followed by the characters (sign if negative, digits, et cetera)
in the print form of the number numb.

(APPLYIFDEF0 lexprid): EXPR
 lexprid should be a list of identifiers. Each of these (in order)
is tested for a function definition, and if one is found, the function
is applied on an empty list. (Thus any one of the identifiers being
defined should be an EXPR with no arguments.)

(ASSIGNSTRING id string): EXPR
 Checks if string is a string, and then assignis it as the value of
id, returning the old value.  Else, prints a warning message, and
returns NIL. id is neither checked for being an identifier, nor for 
having a value.

(ATSOC any alist): EXPR
 As ASSOC, but tests if any equals the car of a dotted pair on alist
with EQ instead of EQUAL.

(BMDATING): EXPR
 If available returns a string informing on the present date and time.
(If not available, the returned string informs on this fact.)

(CALLSHELL filstr lst): EXPR
 (Only partially available.)
 Make a system call with the calling command name given by the string
filstr and the arguments by the items of the list lst. (These items
are represented by their print forms.)

(CIRCLENGTH any): EXPR ; Sets !*CSTRUCTURE!*
 Extends length measurement from ordinary lists to arbitrary
s-expressions, including circular lists. Returns the number of
CDR's possible until an atom is achieved (in which case
!*CSTRUCTURE!* is set to NIL), or a former CDR is repeated
(in which case !*CSTRUCTURE!* is set to T). Thus, (1 2 3 4)
has circlength 4; (1 2 . 3) has circlength 2; and if
A = (1 2 3 4 3 4 3 4 ...) (with (CDDR A) EQ to (CDDDDR A),
then A has circlength 2.


(CDRADD1 alist): EXPR
 alist should be an association list with numeric CDRs of items. Each
such CDR c is replaced by (ADD1 c). (Unspecified return value.)

(CONSTANTLIST2STRING lst): EXPR
 Returns a string consisting of the print forms of the items on the list
lst, separated by spaces.

(COPY any): EXPR
 Returns a recursively constructed copy of the S-expression any. (Dotted
pairs are copied to new ones, until atoms are encountered. In other
words, COPY behaves as if defined by
(DE COPY (any)
 (COND  ((PAIRP any) (CONS (COPY (CAR any)) (COPY (CDR any))))
	(T any))) .)

(COPYD (imgid srcid): EXPR
 Both arguments should be identifiers; the second one should be a
function name. COPYD copies the function definition from srcid to
imgid. (Unspecified return value.)

(DEFP id): MACRO
 Returns non-NIL iff has a function definition.

(DELQ lst any): EXPR
 As DELETE, but tests if any equals an item on lst with EQ instead of
EQUAL.

 [(DELETIP itm list) is deprecated. Works as in psl.]

(DEGLIST2LIST dlist)
 Returns the items of a degree list (but not the degree numbers) in
one list, ordered in the way they come in the degree list. (In the
terms explained in the file types.txt, a dlXXX object is turned into
an lXXX object.)

(DPLISTCOPY alist): EXPR
 Returns a copy of the association list alist; but copying is done on
the top list level and on the alist dotted pair items top level. (In
other words, in (DPLISTCOPY '(((1 2) 3 4))), the old and new ((1 2) 3 4)
parts won't be EQ, but both the (1 2) and the (3 4) parts will be.)

(DPLISTP any): EXPR
 Returns non-NIL iff any is an association list (i.e., a list of
dotted pairs).
 
(DSKIN filen): EXPR
 Open the file with name filen; reads, evals, and prints successively
each s-expression therein (if not redirected as some evaluation side
effect) until end-of-file is reached, and closes the file.
(Unspecified return value.)

(EVENP no): EXPR or MACRO
 Returns non-NIL iff the integer no is even.

(FASTGETV vect no): MACRO
 Returns (GETV vect no) if the input is correct, but may be faster due
to the elimination of some error checks. (See the Fast Variants section
above.)

(FILEP filstr): EXPR or MACRO
 Returns non-NIL if filstr is a legal file name of an existing file.
(In some versions, where this is not so easily done, it may always
returns non-NIL.)

(FLIPSWITCH id boole): EXPR
Id must be an identifier, and be assigned a value. Id is
assigned NIL if boole is NIL, T else; and the old value of id
is returned.

(FLUSHCHANNEL chn): MACRO
 Flush the output to the output channel (stream) chn.

(IBIDNOOPFCN any): EXPR
 Just returns any. (Useful with COPYD in case some no-operator
variants are wanted in some modes.)

(LAPIN filen): EXPR
 Open the file with name filen; reads and evals successively
each s-expression therein (if not redirected as some evaluation side
effect) until end-of-file is reached, and closes the file.
(Unspecified return value.)

(LASTCAR lst): EXPR
 Returns the last item of the list lst.

(LASTPAIR (list) (COND ((NULL (CDR list)) list)
 Returns the last top level pair (consisting of the last item and NIL)
of the list lst.

(LCONC ptr lst): EXPR
 ptr should be a dotted pair consisting of a list and of its
LASTPAIR. This list is concatenated with the list lst, and the CDR of
ptr is changed to the LASTPAIR of the prolonged list. (lst may be NIL.)
(Unspecified return value.)

(LISTCOPY lst): EXPR
 Returns a copy of the list lst; but copying is done only on the top
list level.

(LISTONENOOPFCN0): EXPR
(LISTONENOOPFCN1 any): EXPR
(LISTONENOOPFCN2 any1 any2): EXPR
 Just returns a freshly constructed list (1). (Useful with COPYD in case
some no-operator variants are wanted in some modes.)

(LOADIFMACROS lid): FEXPR
 For each identifier (member of lid), check whether this is function
bound to a macro, defined as a lambda expression. If so, eval this
expression (with NIL bound as argument).
 This is only intended for 'self loading MACROs', where it efficiently
forces the intended loading (and replacement of the MACRO definition
by an EXPR or FEXPR one), without or before calling the function.
(Useful in case self loading MACROs are called in compiled code as
EXPRs or FEXPRs. Since the 'self loading MACRO' trick is principally
intended for use with top level procedures, this should rarely happen.)

(MERGESTRINGS string string): EXPR
Returns the concatenation of the two strings.

(MINUSP no): EXPR or MACRO
 Returns non-NIL iff the number no is negative.
 (COMMENT: For the discussion on whether or not to regard MINUSP as an
extension of Standard Lisp, see the <slisp document criticism> part.)

(NCONS any): EXPR or MACRO
 Returns (CONS any NIL).

(NILNOOPFCN0): EXPR
(NILNOOPFCN1 any): EXPR
(NILNOOPFCN2 any1 any2): EXPR
(NILNOOPFCN3 any1 any2 any3): EXPR
(NILNOOPFCN4 any1 any2 any3 any4): EXPR
 Just returns NIL. (Useful with COPYD in case some no-operator
variants are wanted in some modes.)

(OFF id): FEXPR
 SETs the identifier whose name is the name of the identifier id
preceeded by an asterisk ( * ) to NIL. (Unspecified return value.)
 (Comment: For potentional difficulties together with Reduce, see
<... section> below.)

(ON id): FEXPR
 SETs the identifier whose name is the name of the identifier id
preceeded by an asterisk ( * ) to T. (Unspecified return value.)
 (Comment: For potentional difficulties together with Reduce, see
<... section> below.)

(ONENOOPFCN1 any): EXPR
(ONENOOPFCN2 any1 any2): EXPR
 Just returns 1. (Useful with COPYD in case some no-operator
variants are wanted in some modes.)

(PAIRCOPYD alist): EXPR
 alist should be an association list of identifiers; the second one in
each pair should be a function name. PAIRCOPYD copies the function
definition from the second identifier to the first one in each of the
pairs. (Unspecified return value.)

(PNTH lst no): EXPR
 lst should be a list of LENGTH greater than or equal to the positive
integer no. Returns the no'th top level pair of the list (so that
(PNTH lst 1) is EQ to lst, (PNTH lst 2) is EQ to (CDR lst), et cetera).

(PRINTX any): EXPR
 Sometimes succeeds in printing an 'unprintable object'.

(PROMPTREAD string): EXPR
 A READ is performed, and the result returned. If reading is connected
with prompting, the string should be used for prompt.

(PRUNEFIRSTDEGREEITEM dlany int): EXPR
 dlany must be a non-empty degree list. (Cf. types.txt.) If the first
degree appearing on dlany is int, then (CDR dlany) is returned; else,
dlany is returned.

(RECLAIM): EXPR or MACRO
 Perform a garbage collection. (May be a no-operator in some versions.)
(Unspecified return value.)

(SETVECTPROG id no): EXPR
 Creates a new vector of length no + 1 and name id, and successively
reads the next no + 1 s-expressions (without evaluation), assigning
the vector entries to these. (Unspecified return value.) (Useful for
reading in very large vectors without overtaxing the recursive depth
of the lisp reader.)

(SETPROMPT string): EXPR
 Set the prompt string to prompt.

(STRIPEXPLODE atm): EXPR
 Returns the same as EXPLODE on the atom atm, except that if atm is
a string its enclosing double quotes are removed.

(TCONC ptr any): EXPR
 ptr should be either a dotted pair consisting of a list and of its
LASTPAIR, or NIL. This list is concatenated with a new dotted pair
formed by any and NIL, and the CDR of ptr is changed to this dotted
pair. If ptr is NIL, then a list of the one element any is formed,
and the dotted pair of this list and its LASTPAIR (i.e., itself)
is returned; else (the modified) ptr is returned.

(TCONCPTRCLEAR ptr): EXPR
 ptr should be a dotted pair consisting of a list and of its
LASTPAIR, as returned by successive applications of TCONC. This is
modified by removing all after the first element of the list. The
modified ptr (which now is EQUAL to the result of (TCONC NIL (CAAR ptr)))
is returned.

(TIME): EXPR or MACRO
 Returns an integer more or less measuring the "cpu time" of the
bergman session until now. (Not necessarily available in all
versions.)

(TNOOPFCN1 any): EXPR
 Just returns T. (Useful with COPYD in case some no-operator
variants are wanted in some modes.)

(UNION lst1 lst2): EXPR
 Returns a list containing the elements in the list lst1 and lst2,
avoiding repetitions of EQUAL members of both lists. (If several
members in one of the lists are equal, then however this `redundancy'
may be carried over to the new list.)

(ZEROP any): EXPR
 Returns non-NIL iff any is EQN to the number 0.
 (COMMENT: For the discussion on whether or not to regard ZEROP as an
extension of Standard Lisp, see the <slisp document criticism> part.)




	References

(1) Jed Marti, A. C. Hearn, M. L. Griss, C. Griss: The Standard
    Lisp Report, Salt Lake City, 197?. Reduce owners should have
    a copy of this in their reduce/doc directory.
