|| HEADER FOR LIST  PROCESSING  PACKAGE    DAT 23/11/79

||----------------------------------------------------------------------
||The KRC system is Copyright (c) D. A. Turner 1981
||All  rights reserved.  It is distributed as free software under the
||terms in the file "COPYING", which is included in the distribution.
||----------------------------------------------------------------------

GLOBAL $( GO:100; CONS:101; STONUM:102;  GETNUM:103; MKATOM:104
          PRINTNAME:105; BUFCH:106; PACKBUFFER:107; ISCONS:108
          ISATOM:109; ISNUM:110; BASES:111; ATGC:112; SPACE.ERROR:113
          GCSTATS:114; RESETGCSTATS:115; LISTPM:116; ALFA.LS:117
          MEMBER:118; LENGTH:119; ELEM:120; APPEND:121; EQUAL:122
          PRINTOB:123; FORCE.GC:124; REVERSE:125
          SHUNT:126; SUB1:127
       $)

MANIFEST $( HD=0; TL=1; VAL=1; NIL=#X40000000
         $)

GLOBAL $( HOLD.INTERRUPTS:130; RELEASE.INTERRUPTS:131
         ||ESSENTIAL THAT DEFINITIONS OF THE ABOVE SHOULD BE PROVIDED IF
         ||THE PACKAGE IS TO BE USED IN AN INTERACTIVE PROGRAM
         HAVEPARAM:132   ||FOR PICKING UP SYSTEM PARAMETERS PASSED TO PROGRAM
       $)

|| PACKAGE SPECIFICATIONS:

|| "GO" "BASES" "SPACE.ERROR"      MUST BE DEFINED BY THE USER
|| ALL THE OTHER FUNCTIONS ETC ARE DEFINED BY THE PACKAGE

|| "GO()"   IS THE MAIN ROUTINE OF THE USERS PROGRAM (NECESSARY BECAUSE
|| THE PACKAGE HAS ITS OWN  "START" ROUTINE)
|| "BASES" IS USED TO INFORM THE PACKAGE WHICH OF THE USERS OFF-STACK
|| VARIABLES ARE BASES FOR GARBAGE COLLECTION - IT SHOULD BE DEFINED
|| THUS -  "LET BASES(F) BE $( F(@A); F(@B); ... $)" WHERE A, B ETC.
|| ARE THE RELEVANT VARIABLES.  SEE NOTE 1 BELOW.
|| "SPACE.ERROR()" DEFINES THE ACTION THE USER WISHES TO TAKE WHEN LIST
|| SPACE IS EXHAUSTED (E.G. PRINT A MESSAGE AND CALL FINISH)

|| "CONS(X,Y)" CREATES A LIST CELL, Z SAY, WITH X AND Y FOR ITS FIELDS
|| AND "HD!Z", "TL!Z" GIVE ACCESS TO THE FIELDS

|| "STONUM(N)" STORES AWAY THE NUMBER N AS A LIST OBJECT AND "GETNUM(X)"
|| GETS IT OUT AGAIN.  SEE NOTE 2 BELOW.

|| "MKATOM(S)" CREATES AN ATOM FROM BCPL STRING S  - ATOMS ARE STORED
|| UNIQUELY, MKATOM USES A HASHING ALGORITHM TO ACCOMPLISH THIS 
|| EFFICIENTLY.  "PRINTNAME(X)" RECOVERS THE BCPL STRING. THERE IS A LIST
|| VALUED FIELD "VAL!A" ASSOCIATED WITH EACH ATOM A, INITIALLY 
|| CONTAINING "NIL".

|| "BUFCH(CH)" PUTS THE CHARACTER CH INTO A BUFFER, "PACKBUFFER()"
|| EMPTIES THE BUFFER AND RETURNS AN ATOM FORMED FROM THE CHARACTERS
|| WHICH HAD BEEN PLACED IN IT(BY CALLING "MKATOM")

|| THE FUNCTIONS "ISCONS(X)", "ISATOM(X)", "ISNUM(X)" DISTINGUISH
|| THE THREE DIFFERENT KINDS OF CONSTRUCTED LIST OBJECT.
|| NOTE THAT THE SPECIAL OBJECT "NIL" IS NEITHER AN ATOM NOR A LIST.
|| (SO REMEMBER THAT "NIL" HAS NO PRINTNAME AND NO "VAL" FIELD.)
|| THERE IS A FIFTH KIND OF VALUE WHICH CAN BE STORED IN A LIST FIELD
|| NAMELY A SMALL INTEGER (WHERE "SMALL" IS AN IMPLEMENTATION DEPENDENT
|| ADJECTIVE MEANING SMALL ENOUGH NOT TO BE CONFUSED WITH ONE OF THE
|| THREE ABOVE MENTIONED TYPES OF LIST OBJECT - SEE NOTE 3, BELOW).

|| "ATGC" IS A FLAG, INITIALLY SET TO "FALSE", IF SET TO "TRUE" IT
|| CAUSES A MESSAGE TO BE PRINTED AT EACH GARBAGE COLLECTION.

|| "GCSTATS()" PRINTS A MESSAGE ABOUT TOTAL STORE UTILISATION SINCE
|| SYSTEM INITIALISATION OR SINCE THE LAST CALL OF"RESETGCSTATS()"

|| "LISTPM()" GIVES A DUMP OF SELECTED INFORMATION ABOUT THE STATE OF
|| LISTSPACE.

|| "ALFA.LS(A,B)" TESTS ATOMS FOR ALPHABETICAL ORDER
|| "LENGTH(X)" GIVES THE LENGTH OF LIST X
|| "MEMBER(X,A)" SAYS IF "A" IS = AN ELEMENT OF X
|| "APPEND(X,Y)" APPENDS (A COPY OF) LIST X TO THE FRONT OF LIST Y
|| "EQUAL(X,Y)" DETERMINES IF LIST OBJECTS X AND Y ARE ISOMORPHIC
|| "ELEM(X,N)" RETURNS THE N'TH ELEMENT OF LIST X
|| "PRINTOB(X)" PRINTS AN ARBITRARY LIST OBJECT X
|| "FORCE.GC()" FORCES A GARBAGE COLLECTION
|| "REVERSE(X)" REVERSES THE LIST X
|| "SHUNT(X,Y)" APPENDS REVERSE(X) TO THE LIST Y
|| "SUB1(X,A)" REMOVES A FROM THE LIST X (DESTRUCTIVELY) IF PRESENT

|| NOTES FOR 2960/EMAS IMPLEMENTATION AT UKC:

|| NOTE 1
|| AT GARBAGE COLLECTION TIME THE BCPL STACK IS SEARCHED AND ANY VALUE
|| WITHIN THE ADDRESS RANGE OF LIST OBJECTS IS TREATED AS A BASE AND 
|| POSSIBLY RELOCATED.  IT IS THEREFORE ESSENTIAL THAT THERE SHOULD BE
|| NO INTEGERS ON THE STACK LARGE ENOUGH TO BE CONFUSED WITH A BCPL
|| ADDRESS - INTEGERS LESS THAN 8 MEG ARE SAFE.

|| NOTE 2
|| THE NUMBERS STORED AND RECOVERED BY MKNUM AND GETNUM ARE 32 BIT 
|| INTEGERS - TAKE CARE NOT TO LEAVE THEM ON THE STACK.

|| NOTE 3
|| "SMALL" HERE MEANS LESS THAN 8 MEG

