Return to manual.ms CVS log

Up to [CSRG BSD Unix] / 43BSD / ucb / lisp / pearl

Annotation of 43BSD/ucb/lisp/pearl/manual.ms, revision 1.1

1.1     ! root        1: .ND
        !             2: .nr LL 75n
        !             3: .nr LT 80n
        !             4: .rm CF
        !             5: .ds LH PEARL Documentation
        !             6: .rm CH
        !             7: .ds RH Page %
        !             8: .po 1.00i
        !             9: .ls 1
        !            10: .hy 14
        !            11: .RP
        !            12: .TL
        !            13: .LG
        !            14: .LG
        !            15: Using the PEARL AI Package
        !            16: .sp 1
        !            17: .SM
        !            18: \fR(\fIP\fRackage for \fIE\fRfficient \fIA\fRccess to \fIR\fRepresentations in \fIL\fRisp)*
        !            19: .NL
        !            20: .FS
        !            21: * This research was sponsored in part by the Office of Naval Research
        !            22: under contract N00014-80-C-0732 and the National Science Foundation
        !            23: under grant MCS79-06543.
        !            24: .FE
        !            25: .AU
        !            26: Michael Deering
        !            27: Joseph Faletti
        !            28: Robert Wilensky
        !            29: .AI
        !            30: Computer Science Division
        !            31: Department of EECS
        !            32: University of California, Berkeley
        !            33: Berkeley, California 94720
        !            34: .sp 1
        !            35: February 1982
        !            36: .AB
        !            37: This document is a tutorial and manual for PEARL
        !            38: (Package for Efficient Access to Representations in Lisp),
        !            39: an AI language developed with space and time efficiencies in mind.
        !            40: PEARL provides a set of functions for creating hierarchically-defined
        !            41: slot-filler representations and for efficiently and flexibly inserting
        !            42: and fetching them from a forest of associative data bases.
        !            43: In addition to providing the usual facilities such as demons and matching,
        !            44: PEARL introduces stronger typing on slots and user-assisted hashing
        !            45: mechanisms.
        !            46: .AE
        !            47: .NH 0
        !            48: Introduction
        !            49: .PP
        !            50: PEARL (Package for Efficient Access to Representations in Lisp) is
        !            51: a set of functions for creating hierarchically-defined slot-filler
        !            52: representations and for efficiently and flexibly inserting and fetching
        !            53: them from a forest of data bases.
        !            54: Its intended use is in AI programming and it has been used at Berkeley
        !            55: in the development of several AI programs including PAM [7] and
        !            56: PANDORA [8].
        !            57: .PP
        !            58: PEARL has the expressive power found in other AI knowledge
        !            59: representation languages, but is extremely time-space efficient.
        !            60: For example, using a data base of 4000 entries, PEARL takes only
        !            61: about 4.2 CPU milliseconds for an average unsuccessful query and
        !            62: 7.3 CPU milliseconds of an average successful query on a PDP-10.
        !            63: .PP
        !            64: This document describes PEARL's use and is intended for the
        !            65: beginning user.
        !            66: (A description of the implementation of PEARL will be available
        !            67: shortly.)
        !            68: The best way to approach PEARL is to read this document up through
        !            69: section 11 and then to take it to a terminal and reread it, typing
        !            70: in the examples and observing their effects.
        !            71: .PP
        !            72: PEARL was implemented by Michael Deering and Joseph Faletti.
        !            73: It was originally developed on a DEC PDP-10 under UCI Lisp
        !            74: and was subsequently moved to a DEC VAX 11/780 under Franz Lisp
        !            75: with help from Douglas Lanam and Margaret Butler.
        !            76: Both PEARL and its documentation are still
        !            77: being developed, improved, and debugged.
        !            78: Any comments or suggestions will be appreciated.
        !            79: Send them to Joe Faletti via Arpanet or Unix mail
        !            80: (Kim\fB.\fRFaletti\fB@\fRBerkeley or ucbvax\fB!\fRkim\fB.\fRfaletti).
        !            81: .bp
        !            82: .DS
        !            83: .sp 5
        !            84: .DE
        !            85: .NH
        !            86: Running PEARL
        !            87: .PP
        !            88: PEARL is implemented as a set of functions compiled and
        !            89: loaded into Lisp.
        !            90: Thus the full power of Lisp is available in addition to the added
        !            91: power of PEARL.
        !            92: .PP
        !            93: Since PEARL runs under two different Lisps on two different machines,
        !            94: there are a few differences between versions.
        !            95: Most of these differences are in the method of starting PEARL up
        !            96: and in the names of external files accessed by PEARL.
        !            97: The two parts of this section describe how to start up PEARL either
        !            98: under Franz Lisp or under UCI Lisp.
        !            99: You need only read the section which is applicable to your Lisp.
        !           100: .NH 2
        !           101: Under Franz Lisp
        !           102: .PP
        !           103: To access PEARL, simply run the core version of Lisp
        !           104: containing PEARL. On Berkeley Unix, this is available by typing
        !           105: the command:
        !           106: .DS
        !           107:   %  ~bair/bin/pearl
        !           108: .DE
        !           109: or, if ~bair/bin is in your search path, simply:
        !           110: .DS
        !           111:   %  pearl
        !           112: .DE
        !           113: During the startup process, PEARL will read in two
        !           114: files, \fB.init.prl\fR and \fB.start.prl\fR, if they exist.
        !           115: These files are designed for purposes similar to those
        !           116: of \fI.lisprc\fR.
        !           117: However, they split these functions into two groups.
        !           118: In your \fI.init.prl\fR file you should include any
        !           119: expressions which change the user-settable parameters to PEARL.
        !           120: (For example, methods for setting the size of data bases,
        !           121: the print function, and the prompt are described below.)
        !           122: .PP
        !           123: When you wish to have other files read in at startup time,
        !           124: this usually needs to be done after PEARL's parameters are set.
        !           125: PEARL is set up so that after the reading of \fI.init.prl\fR, it sets
        !           126: any necessary parameters which you have not set in your .init.prl
        !           127: and then reads in the file \fI.start.prl\fR if you have one.
        !           128: This is where any processing which requires the
        !           129: attention of PEARL (such as the existence of its data bases)
        !           130: should be placed.
        !           131: Thus \fI.init.prl\fR is primarily for initializing PEARL
        !           132: and \fI.start.prl\fR is for starting up your use of PEARL.
        !           133: \fBNote:\fR unlike most Unix programs which look for startup files
        !           134: only in your home directory, thereby limitting you to only one
        !           135: environment for each program, PEARL looks for each file first in
        !           136: the current directory and if there is none, then it looks in your
        !           137: home directory.
        !           138: This allows you to tailor invocations of PEARL to the kind of work
        !           139: you do in a particular directory.
        !           140: .bp
        !           141: .PP
        !           142: After reading in these two files, PEARL will then place you in a
        !           143: modified prompt-read-eval-print loop, with a default prompt of "PEARL>  ".
        !           144: This can be changed by setting the special variable
        !           145: \fB*pearlprompt*\fR to the desired value.
        !           146: If you want the standard Lisp prompt "->  " to be used by PEARL,
        !           147: you must set \fI*pearlprompt*\fR to \fInil\fR in your \fI.init.prl\fR
        !           148: and PEARL will do the right thing.
        !           149: .PP
        !           150: The primary feature of the PEARL prompt-read-eval-print loop is that
        !           151: it uses a different print function.
        !           152: The default function is
        !           153: .DS
        !           154: (lambda (*printval*)
        !           155:         (valprint  *printval*  4) )
        !           156: .DE
        !           157: but this can be changed to whatever you desire by giving 
        !           158: a new function definition to \fBpearlprintfn\fR.
        !           159: The PEARL prompt-read-eval-print loop also contains a number of
        !           160: features to improve upon the standard Lisp top level.
        !           161: These include a history mechanism and are described in chapter 25.
        !           162: .PP
        !           163: There are quite a few functions from UCI Lisp which have been added
        !           164: to PEARL to make it easier to move programs to Franz Lisp.
        !           165: A list of these with brief documentation of differences is
        !           166: included in an appendix.
        !           167: .NH 2
        !           168: Under UCI Lisp
        !           169: .PP
        !           170: To access PEARL, simply run the core version of Lisp containing PEARL. 
        !           171: On the Berkeley KL-10 system, this is available by typing the system call
        !           172: .DS
        !           173: RU  PEARL[5500,504,PEARL]
        !           174: .DE
        !           175: During the startup process, PEARL will read in two files,
        !           176: INIT.PRL and START.PRL, if they exist.
        !           177: The file INIT.PRL is designed for purposes similar to those
        !           178: of INIT.LSP.
        !           179: In this file you should include any expressions which
        !           180: change the user-settable parameters to PEARL.
        !           181: (For example, methods for setting the size of data bases,
        !           182: the print function, and the prompt are described below.)
        !           183: If you wish to use the REALLOC function to
        !           184: enlarge your memory space, this call should be the
        !           185: last call in your INIT.PRL file.
        !           186: .PP
        !           187: When you wish to have other files read in at startup
        !           188: time, this usually needs to be done after the REALLOC.
        !           189: The common kludge with UCI Lisp to solve this is to define
        !           190: an INITFN (initialization function) which does this and then
        !           191: to reset the INITFN to \fInil\fR which returns you to the
        !           192: standard Lisp prompt-read-eval-print loop.
        !           193: However, PEARL sets the INITFN for its own purposes so
        !           194: that this common "solution" will not work.
        !           195: Instead, PEARL is set up so that after the reading of INIT.PRL,
        !           196: it sets any necessary parameters which you have not set in your
        !           197: INIT.PRL and then reads in the file START.PRL if you have one.
        !           198: This is where any processing which requires the
        !           199: attention of PEARL should be placed.
        !           200: Thus INIT.PRL is primarily for initializing PEARL and
        !           201: START.PRL is for starting up your use of PEARL.
        !           202: .PP
        !           203: After reading in these two files, PEARL will then place you in a
        !           204: modified prompt-read-eval-print loop, with a default prompt of "PEARL>  ".
        !           205: The ">" portion is the (modified) Lisp prompt which is printed
        !           206: whenever \fIread\fR is invoked and can be changed
        !           207: with the UCI Lisp function INITPROMPT.
        !           208: The "PEARL" is PEARL's addition and can be set by
        !           209: setting the special variable \fB*pearlprompt*\fR
        !           210: to the desired value.
        !           211: If you do not want any prompt added by PEARL other than the Lisp
        !           212: prompt you must set \fI*pearlprompt*\fR to \fInil\fR in your
        !           213: INIT.PRL and PEARL will do the right thing.
        !           214: .PP
        !           215: The main feature of the PEARL prompt-read-eval-print loop is
        !           216: that it uses a different print function.
        !           217: The default function is
        !           218: .DS
        !           219: (lambda (*printval*)
        !           220:         (valprint  *printval*  4) )
        !           221: .DE
        !           222: but this can be changed to whatever you desire by giving the
        !           223: function \fBpearlprintfn\fR a new definition.
        !           224: Note that \fIdskin\fR and the break package have been
        !           225: changed slightly to also use of this print function.
        !           226: Also, although the functions names and examples below are in
        !           227: lower case, PEARL in UCI Lisp expects them all in upper
        !           228: case, just as the rest of the UCI Lisp functions.
        !           229: .NH
        !           230: Creating Simple Objects.
        !           231: .PP
        !           232: PEARL allows four basic types of objects.
        !           233: The first two are integers and arbitrary Lisp objects
        !           234: and are created in the usual Lisp fashion.
        !           235: The second two are structured types provided by PEARL,
        !           236: and are stored in an internal form as blocks of memory.
        !           237: These latter types are called \fBsymbols\fR and \fBstructures\fR.
        !           238: .NH 2
        !           239: Defining Symbols
        !           240: .PP
        !           241: \fBSymbol\fRs are PEARL's internal atomic symbols.
        !           242: Semantically they are like Lisp atoms, but are represented
        !           243: and used differently to make PEARL more efficient.
        !           244: Before they are used, symbols must
        !           245: be declared (and thus defined to PEARL) by a call to the function
        !           246: \fBsymbol\fR, which takes as arguments any number of atoms
        !           247: whose names will be used to create symbols.
        !           248: For example,
        !           249: .DS
        !           250: (symbol  John)
        !           251: .DE
        !           252: creates one symbol called John and
        !           253: .DS
        !           254: (symbol  Bob  Carol  Ted  Alice  Home
        !           255:          Office  School  Healthy  NewYork)
        !           256: .DE
        !           257: creates several symbols at one time.
        !           258: \fISymbol\fR is an nlambda (fexpr) and returns
        !           259: a list containing the names of the symbols it created.
        !           260: A one-argument lambda (expr) version is available as \fBsymbole\fR.
        !           261: .PP
        !           262: There are two ways to get at the actual (unique) symbol:
        !           263: you can use the function \fBgetsymbol\fR or you can evaluate the
        !           264: atom whose name is built out of the symbol name with the characters
        !           265: \fBs:\fR on the front.
        !           266: The function \fBsymatom\fR will build this atom for you when
        !           267: given a symbol name.
        !           268: For example, to set B to the symbol Bob use any of:
        !           269: .DS
        !           270: (setq  B  (getsymbol  'Bob) )
        !           271: (setq  B  s:Bob)
        !           272: (setq  B  (eval (symatom 'Bob))
        !           273: .DE
        !           274: .LP
        !           275: Given an internal symbol, you can find out its print name by passing
        !           276: it to the function \fBpname\fR (which also will return the print name
        !           277: of other types of PEARL objects).
        !           278: .NH 2
        !           279: Defining Structures
        !           280: .PP
        !           281: \fBStructure\fRs in PEARL provide the ability to define and manipulate
        !           282: logical groupings of heterogeneous data and are essentially objects
        !           283: with slots and slot fillers.
        !           284: As such, they act more like "records"
        !           285: in Pascal or "structures" in C than Lisp lists.
        !           286: In reality they are more than both, but for the moment the reader
        !           287: should keep records in mind.
        !           288: .PP
        !           289: Just as you must define the form
        !           290: of a record in Pascal before defining the value of a variable whose
        !           291: type is that kind of record, it is necessary to define each particular
        !           292: form of structure you wish to use in PEARL before creating an
        !           293: object with that form.
        !           294: PEARL provides one function called \fBcreate\fR which
        !           295: is used both to define kinds of structures and to
        !           296: create individual instances of these structures.
        !           297: (One function is provided for both because a special individual
        !           298: is created as a side effect of each definition.
        !           299: More on this is provided in section 7 on defaults.)
        !           300: The first argument to \fIcreate\fR distinguishes
        !           301: between a call which defines and one which creates an individual.
        !           302: There are three kinds of defining calls (\fIbase\fR, \fIexpanded\fR
        !           303: and \fIfunction\fR) and two kinds of instance-creating calls
        !           304: (\fIindividual\fR, \fIpattern\fR) to \fIcreate\fR.
        !           305: Only one of each (\fIbase\fR and \fIindividual\fR) is described
        !           306: in this section.
        !           307: The rest are left for later.
        !           308: .PP
        !           309: To start off with an example, let us suppose that you wish to represent
        !           310: the conceptual act "PTrans" from the Conceptual Dependency (CD) notation
        !           311: of Schank.
        !           312: (The examples in this documentation assume a passing
        !           313: familiarity with CD but lack of this should not hurt you too badly
        !           314: and PEARL itself does not restrict you in any way to CD.
        !           315: PTrans stands for Physical Transfer which has four "cases": actor doing
        !           316: the transfer, object being transferred, original location and final
        !           317: location.)
        !           318: First we must define the form which PTrans structures will take.
        !           319: In C this would be a type definition for the type PTrans as
        !           320: follows (assuming a system-provided definition of the type \fIsymbol\fR):
        !           321: .DS
        !           322: struct  PTrans {
        !           323:         symbol  Actor;
        !           324:         symbol  Object;
        !           325:         symbol  From;
        !           326:         symbol  To;
        !           327: };
        !           328: .DE
        !           329: In Pascal this would be
        !           330: .DS
        !           331: type  PTrans  =  record
        !           332:                      Actor  :  symbol;
        !           333:                     Object  :  symbol;
        !           334:                     From  :  symbol;
        !           335:                     To  :  symbol
        !           336:                  end;
        !           337: .DE
        !           338: .LP
        !           339: In PEARL,
        !           340: .DS
        !           341: (create base  PTrans
        !           342:        (Actor  symbol)
        !           343:        (Object  symbol)
        !           344:        (From  symbol)
        !           345:        (To  symbol) )
        !           346: .DE
        !           347: does the job.
        !           348: Note first of all that in order to define a new form
        !           349: of structure, the first argument to \fIcreate\fR must be \fBbase\fR.
        !           350: Note also that the second argument to \fIcreate\fR is the name of the
        !           351: structure form to be created.
        !           352: Following this is a list of (<slotname> <type>) pairs.
        !           353: Structures are currently allowed to have up to 32 slots
        !           354: in Franz PEARL or 18 in UCI Lisp PEARL as long as all slots
        !           355: within a particular structure have mutually distinct names.
        !           356: Different structures may have slots of the same name.
        !           357: Thus in applications of PEARL to CD twenty different structure
        !           358: types might all have an Actor slot.
        !           359: .PP
        !           360: Five types are allowed for slots: \fBsymbol\fR, \fBstruct\fR,
        !           361: \fBint\fR, \fBlisp\fR, and \fBsetof <type>\fR.
        !           362: \fISymbol\fR and \fIstruct\fR are the types just described.
        !           363: \fIInt\fR is a normal Lisp integer value.
        !           364: The type \fIlisp\fR allows arbitrary \fBnon-atomic\fR Lisp values.
        !           365: Finally, \fIsetof <type>\fR allows you to define sets consisting
        !           366: of all symbols (\fIsetof symbol\fR) or all structures (\fIsetof struct\fR)
        !           367: and can be done recursively (\fIsetof setof struct\fR).
        !           368: .NH
        !           369: Creating Individual Instances of Defined Structures
        !           370: .PP
        !           371: Once you have defined a specific form of structure like PTrans, you
        !           372: can create an individual PTrans using \fBindividual\fR as the first
        !           373: argument to \fIcreate\fR and the name of the base structure you want
        !           374: an individual instance of as the second argument.
        !           375: The rest of the arguments are (<slotname> <value>) pairs in which
        !           376: the <value> must be of the type that the slot was declared to be.
        !           377: The slots may be listed in any order and need not be in the same
        !           378: order as defined.
        !           379: For example, to create an instance of John going home
        !           380: from the office (i.e., John PTransing himself from the office to
        !           381: home) you would use this call to \fIcreate\fR:
        !           382: .DS
        !           383: (create individual  PTrans
        !           384:        (Actor  John)
        !           385:        (Object  John)
        !           386:        (From  Office)
        !           387:        (To  Home) )
        !           388: .DE
        !           389: \fICreate\fR will return an object of type PTrans, with the slots filled
        !           390: in as indicated.
        !           391: The object returned has been created and stored as
        !           392: a \fIhunk\fR of memory in Franz Lisp or a block of memory in Binary
        !           393: Program Space in the UCI Lisp (rather than Free Storage where most
        !           394: Lisp objects are stored).
        !           395: Since you are using the PEARL prompt-read-eval-print loop,
        !           396: the object returned by \fIcreate\fR will be printed in an external list
        !           397: form, something like the above.
        !           398: However, if you print a structure using the standard Lisp print
        !           399: functions (as for example some break packages will do), it will
        !           400: be printed by Franz Lisp in the normal way it prints hunks.
        !           401: (Warning: Since the structure actually contains a circular
        !           402: reference to another hunk, this will cause problems with programs
        !           403: which do not set \fIprinlevel\fR in Franz Lisp so general packages which
        !           404: you wish to add to PEARL should be modified to use some PEARL
        !           405: print function.)
        !           406: With UCI Lisp's normal print function, it will show up as an
        !           407: address in Binary Program Space, looking something like "#31534".
        !           408: .PP
        !           409: As with any Lisp function that returns an object,
        !           410: we must store (a pointer to) the result of \fIcreate\fR somewhere
        !           411: (for example, in the atom Trip)
        !           412: if we wish to reference it in the future.
        !           413: Otherwise, the created object will be inaccessible.
        !           414: (This point is clearer if you consider
        !           415: that Pascal would insist that you do something with the result
        !           416: of the function call, although PEARL and many languages like Lisp
        !           417: and C in which every subprogram is a value-returning function allow
        !           418: you to construct a value and then blithely go on your way without
        !           419: using it.)
        !           420: .PP
        !           421: To store (a pointer to) the instance returned by \fIcreate\fR in
        !           422: the atom Trip, you could do the following:
        !           423: .DS
        !           424: (setq  Trip  (create individual  PTrans
        !           425:                     (Actor  John)
        !           426:                     (Object  John)
        !           427:                     (From  Office)
        !           428:                     (To  Home) ) )
        !           429: .DE
        !           430: Since this is a common operation, \fIcreate\fR provides the option of
        !           431: having (a pointer to) the newly created instance automatically
        !           432: assigned to a Lisp atom.
        !           433: This is accomplished by including the
        !           434: name of the atom as the third argument to \fIcreate\fR.
        !           435: If the third argument to \fIcreate\fR is an atom rather than a
        !           436: (<slotname> <value>) pair, \fIcreate\fR stores the new
        !           437: object in this atom.
        !           438: Thus the effect of the previous example can be achieved by:
        !           439: .DS
        !           440: (create individual  PTrans  Trip
        !           441:        (Actor  John)
        !           442:        (Object  John)
        !           443:        (From  Office)
        !           444:        (To  Home) )
        !           445: .DE
        !           446: (In addition, when \fIcreate base PTrans\fR is used, an assignment is
        !           447: automatically made to the atom PTrans, thus making the defaultinstance
        !           448: of a structure easily available.
        !           449: To preserve this, calls to create of the form
        !           450: \fI(create individual PTrans PTrans ...)\fR are disallowed (that
        !           451: is, ignored).
        !           452: In case you should actually wish to use the atom PTrans for other
        !           453: purposes, evaluating the atom built by prepending \fBi:\fR onto
        !           454: the structure name will give you the default instance of a base
        !           455: structure and evaluating the atom built by prepending \fBd:\fR
        !           456: will give you the actual definition.
        !           457: Changing the value of these atoms is \fBvery dangerous\fR.
        !           458: Given the name of a structure, the functions \fBinstatom\fR and
        !           459: \fBdefatom\fR will construct these atoms for you.
        !           460: For more information about the item assigned to \fIPTrans\fR
        !           461: and \fIi:PTrans\fR, see the section 7 on defaults.)
        !           462: .PP
        !           463: PTrans is an example of a structure whose slots are all
        !           464: of the type \fIsymbol\fR.
        !           465: A more complex example is that of MTrans (Mental Transfer:
        !           466: an actor transfering a concept (Mental Object) from one place
        !           467: to another (usually from himself to someone else).
        !           468: The MObject slot is some other act and so would be of
        !           469: type \fIstruct\fR resulting in the following definition:
        !           470: .DS
        !           471: (create base  MTrans
        !           472:        (Actor  symbol)
        !           473:        (MObject  struct)
        !           474:        (From  symbol)
        !           475:        (To  symbol) )
        !           476: .DE
        !           477: A sample instance of MTrans is \fIJohn told Carol that he
        !           478: was going home from the office\fR and would be created with
        !           479: .DS
        !           480: (create individual  MTrans  InformLeaving
        !           481:        (Actor  John)
        !           482:        (MObject  (PTrans  Leaving
        !           483:                           (Actor  John)
        !           484:                           (Object  John)
        !           485:                           (From  Office)
        !           486:                           (To  Home) ) )
        !           487:        (From  John)
        !           488:        (To  Carol) )
        !           489: .DE
        !           490: .LP
        !           491: Note that to fill a slot of type \fIstruct\fR (or \fIsetof struct\fR)
        !           492: with a structure value within a
        !           493: \fIcreate\fR one just embeds the appropriate arguments for a recursive
        !           494: call to \fIcreate\fR, \fIexcept\fR that you \fBmay\fR leave out
        !           495: \fIindividual\fR since it would just be repetitive.
        !           496: If you should want to create an object of another type within
        !           497: an individual or base structure, you must include the alternative
        !           498: argument (\fIindividual\fR, \fIbase\fR, \fIpattern\fR, \fIexpanded\fR,
        !           499: or \fIfunction\fR) before the type name.
        !           500: This is particularly useful when you wish to create a pattern
        !           501: with an individual instance in one of its slots.
        !           502: .PP
        !           503: The optional third argument of an atom name for storing
        !           504: in may be included at each level if you wish.
        !           505: In the example above, \fIcreate\fR actually will create two
        !           506: new instances, an MTrans which will be stored in InformLeaving,
        !           507: and a PTrans which is pointed to by the MObject slot of the
        !           508: MTrans and is also pointed to by Leaving.
        !           509: In this case, neither InformLeaving nor Leaving is required.
        !           510: If Leaving were left out, then one would still have a way
        !           511: to get at the PTrans via the MObject slot of the MTrans that 
        !           512: InformLeaving points to.
        !           513: However, if InformLeaving were left out and the
        !           514: result of the call to \fIcreate\fR were not stored any other way,
        !           515: there is one more way that the MTrans would be accessible.
        !           516: The value of the most recently created object is always
        !           517: stored in the special variable \fB*lastcreated*\fR by
        !           518: \fIcreate\fR so the value of the MTrans would remain
        !           519: accessible until the next call to \fIcreate\fR.
        !           520: Note that if there are recursive calls to \fIcreate\fR during this
        !           521: time in order to process structure values in slots, the value of
        !           522: \fI*lastcreated*\fR is continually changing to the most recent
        !           523: one and the setting of \fI*lastcreated*\fR is the last thing
        !           524: \fIcreate\fR does.
        !           525: There is also a special variable called \fB*currenttopcreated*\fR
        !           526: which is set by \fIcreate\fR at the top level call as soon as
        !           527: the space for an individual or default instance is allocated.
        !           528: Since it is sometimes handy for a piece of user code which
        !           529: runs during \fIcreate\fR (see the sections on !, $, predicates and
        !           530: demons) to be able to access the topmost object,
        !           531: \fI*currenttopcreated*\fR is sometimes quite useful.
        !           532: .PP
        !           533: As in C and Pascal, one can embed to any level.
        !           534: \fICreate\fR does not have facilities
        !           535: for more complex networks of structures, as there are other
        !           536: functions in PEARL which allow their construction.
        !           537: \fICreate\fR is mainly used to create objects for other
        !           538: functions to manipulate.
        !           539: .NH
        !           540: Accessing Slots of Structures
        !           541: .PP
        !           542: In C and Pascal one can access the slots of a record or structure by
        !           543: using dot notation.
        !           544: For example, in Pascal the To slot of the MObject slot of
        !           545: the MTrans pointed to by InformLeaving would be accessed
        !           546: with the expression InformLeaving.MObject.To (or perhaps
        !           547: more accurately InformLeaving\fB^\fR.MObject\fB^\fR.To
        !           548: since slots really contain pointers to objects).
        !           549: In Pascal and C, there are essentially only two things that
        !           550: one can do to a slot of a record or structure: access it
        !           551: (get its value) and assign to it (give it a new value).
        !           552: In PEARL the macro \fBpath\fR provides
        !           553: a large number of ways to access and/or change the values
        !           554: in slots of individual structures.
        !           555: (In the UCI Lisp version this is called \fIppath\fR
        !           556: to distinguish it from the system function \fIpath\fR.)
        !           557: A call to \fIpath\fR is of the following general form:
        !           558: .DS
        !           559: (path  <Selector>  <Structure>  <Slot-Name-or-List>  <Value>)
        !           560: .DE
        !           561: <Selector> determines the action to be performed
        !           562: and is not evaluated.
        !           563: <Structure> should evaluate to the object in which the slot
        !           564: occurs (or in whose depths the object occurs).
        !           565: <Slot-Name-or-List> should evaluate either to the atom name of the
        !           566: slot desired in <Structure> or a list of the slot names
        !           567: which one must follow to get down to the slot.
        !           568: <Value> (which is only needed when it makes sense) 
        !           569: should evaluate to the value to be put into the slot
        !           570: (or otherwise used in performing the function).
        !           571: At this point, we will only describe the two <Selector>s
        !           572: corresponding to accessing and assigning.
        !           573: These are \fBget\fR and \fBput\fR respectively.
        !           574: Thus to access the value of a slot, you would use
        !           575: .DS
        !           576: (path  get  <Structure>  <Slot-Name-or-List>)
        !           577: .DE
        !           578: (No value is needed;
        !           579: the purpose of this call is to get the value.)
        !           580: To assign a value to a slot, you would use
        !           581: .DS
        !           582: (path  put  <Structure>  <Slot-Name-or-List>  <Value>)
        !           583: .DE
        !           584: For example, to access the Actor slot of the PTrans in Trip, either of
        !           585: the following is appropriate:
        !           586: .DS
        !           587: (path  get  Trip  'Actor)
        !           588: (path  get  Trip  '(Actor) )
        !           589: .DE
        !           590: This is essentially equivalent to a reference to
        !           591: \fITrip\fB^\fI.Actor\fR in Pascal.
        !           592: .PP
        !           593: To access a slot within a structure in a slot of type \fIstruct\fR, 
        !           594: add the slot names to the <Slot-Name-or-List>, just as we access
        !           595: embedded fields within fields in Pascal by adding more slots
        !           596: to the accessing expression.
        !           597: For example, to access the place
        !           598: John told Carol he was going in our MTrans example above, we
        !           599: want the To slot of the MObject slot of the MTrans stored in
        !           600: InformLeaving:
        !           601: .DS
        !           602: (path  get  InformLeaving  '(MObject To) )
        !           603: .DE
        !           604: This is essentially equivalent to a reference to
        !           605: \fIInformLeaving\fB^\fI.MObject\fB^\fI.To\fR in Pascal.
        !           606: PEARL will check each slot reference, and will indicate if
        !           607: a slot name is not found (perhaps due to a misspelling or an
        !           608: unbound slot).
        !           609: .PP
        !           610: Similarly, to change the Actor of our PTrans in Trip to be Bob:
        !           611: .DS
        !           612: (path  put  Trip  '(Actor)   (getsymbol  'Bob) )
        !           613: .DE
        !           614: and to change the To slot within the MObject of the MTrans:
        !           615: .DS
        !           616: (path  put  InformLeaving  '(MObject  To)   (getsymbol  'School) )
        !           617: .DE
        !           618: which is essentially equivalent to assigning a value to
        !           619: \fIInformLeaving\fB^\fI.MObject\fB^\fI.To\fR in Pascal.
        !           620: Note that the order of the arguments to these functions is in
        !           621: \fBnot like\fR the argument ordering of \fIputprop\fR.
        !           622: .PP
        !           623: \fBCAUTION\fR:
        !           624: \fIPath\fR does not check values to ensure that they are of the
        !           625: correct type before putting them in a slot.
        !           626: Also, a change in a structure with \fIpath\fR
        !           627: does not cause it to be reinserted in the data base
        !           628: (see the next section).
        !           629: Thus, before changing a structure, one should remove it from
        !           630: the data base and then reinsert it after the change.
        !           631: .PP
        !           632: These functions were gathered under the macro \fIpath\fR because of
        !           633: their similarity.
        !           634: However, if you prefer to have the action being performed lead off the
        !           635: function name in keeping with \fIputprop\fR, \fIget\fR, \fIputd\fR,
        !           636: \fIgetd\fR, etc., these two functions are also available as
        !           637: \fBputpath\fR and \fBgetpath\fR with similar names also provided for
        !           638: all the other forms of path described below.
        !           639: Thus the name "path" may be tacked onto the end of one of the action
        !           640: selectors to \fIpath\fR but the rest of the arguments to these
        !           641: functions remain the same.
        !           642: .PP
        !           643: There are quite a few other operations which are allowed through
        !           644: \fIpath\fR which you will not need or understand until you have read
        !           645: the rest of this documentation.
        !           646: We describe them here for completeness but suggest you skip
        !           647: to the next section during your first reading.
        !           648: If you feel there is one missing, feel free to suggest it since
        !           649: they are easy to add.
        !           650: .IP
        !           651: \fIpath \fBclear\fR or \fBclearpath\fR -- sets the selected path to
        !           652: the standard default value for its type (\fInilsym\fR,
        !           653: \fInilstruct\fR, zero or \fInil\fR).
        !           654: Note that this is only the standard default and does
        !           655: not inherit a default from above.
        !           656: See section 7 for more on default values.
        !           657: .IP
        !           658: \fIpath \fBaddset\fR or \fBaddsetpath\fR -- add the specified value to
        !           659: a slot of type \fIsetof\fR.
        !           660: .IP
        !           661: \fIpath \fBdelset\fR or \fBdelsetpath\fR -- delete the specified value
        !           662: from a slot of type \fIsetof\fR.
        !           663: .IP
        !           664: \fIpath \fBgetpred\fR or \fBgetpredpath\fR -- get the list of
        !           665: predicates on the slot.
        !           666: .IP
        !           667: \fIpath \fBaddpred\fR or \fBaddpredpath\fR -- add the specified
        !           668: predicate to the predicates on the slot.
        !           669: .IP
        !           670: \fIpath \fBdelpred\fR or \fBdelpredpath\fR -- delete the specified
        !           671: predicate from the predicates on the slot.
        !           672: .IP
        !           673: \fIpath \fBgethook\fR or \fBgethookpath\fR -- get the assoc-list of 
        !           674: hooks (demons) on the slot.
        !           675: .IP
        !           676: \fIpath \fBapply\fR or \fBapplypath\fR -- arguments to this function
        !           677: are a <Function-or-Lambda-Body>, followed by the <Structure>, and
        !           678: <Slot-Name-or-List>.
        !           679: The <Function-or-Lambda-Body> is applied to the value of the slot.
        !           680: (In the UCI Lisp version, \fIapply#\fR is used so that macros will work.
        !           681: In the Franz Lisp version, a PEARL-supplied version of \fIapply\fR
        !           682: called \fBapply*\fR is used which also handles macros "right".)
        !           683: .PP
        !           684: (Skip this next paragraph until you have read about hashing and
        !           685: the data bases.)
        !           686: The method of processing the path in \fBpath\fR functions allows a
        !           687: form of indirection through the data base that is sometimes
        !           688: helpful when you use symbols in slots as unique pointers to
        !           689: other structures.
        !           690: Suppose you had the following definitions:
        !           691: .DS
        !           692: (create base  Person
        !           693:        (* Identity  symbol)
        !           694:        (   Name  lisp) )
        !           695: .DE
        !           696: .DS
        !           697: (dbcreate individual  Person
        !           698:          (Identity  John)
        !           699:          (Name  (John  Zappa) )
        !           700: .DE
        !           701: and you want to ask \fI"what is the Name of the Person in the
        !           702: Actor slot of Trip (above)"\fR which you might normally write as:
        !           703: .DS
        !           704: (getpath  (fetch  (create pattern  Person
        !           705:                          (Identity  !  (getpath  Trip  'Actor) ) ) )
        !           706:           'Name)
        !           707: .DE
        !           708: This is very hard to understand.
        !           709: A shorthand for this is the following:
        !           710: .DS
        !           711: (getpath  Trip  '(Actor  Person  Name) )
        !           712: .DE
        !           713: which behaves like this:  when \fIpath\fR gets to the symbol in
        !           714: the Actor slot of Trip, it notices that there is still more path
        !           715: to follow.
        !           716: It then interprets the next symbol in the path as the
        !           717: name of a type and does a quick equivalent of fetch of a Person
        !           718: with its first slot set to John.
        !           719: It then continues to follow the path specified in this new
        !           720: structure, finishing up with the value of the Name slot
        !           721: of the structure.
        !           722: (Note that this depends on Person structures being hashed by the
        !           723: relevant slot and will fail otherwise.
        !           724: Also note that the tendency of most users of PEARL has been away
        !           725: from the use of symbols as indirections to larger structures and
        !           726: toward actually putting the larger structure in the slot.
        !           727: In this case this would imply putting the Person structure in the
        !           728: Actor slot of PTrans and eliminate the need for "Person" in the
        !           729: path list.)
        !           730: .NH
        !           731: Storing In and Retrieving From the Data Base -- The Simplest Way
        !           732: .PP
        !           733: So far we have shown how to create structures and have treated
        !           734: them pretty much like C structures or Pascal records.
        !           735: However, PEARL's most important departures from these languages
        !           736: involve its data base facilities.
        !           737: PEARL's data base can be thought of as one large
        !           738: bag into which any structure can be placed.
        !           739: The data base can hold hundreds, even thousands of separate objects.
        !           740: There are two basic operations that can be performed upon
        !           741: the data base, inserting with the function \fIinsertdb\fR
        !           742: and retrieving with a combination of the functions
        !           743: \fIfetch\fR and \fInextitem\fR.
        !           744: .NH 2
        !           745: Storing In the Data Base: \fIInsertdb\fR and \fIRemovedb\fR
        !           746: .PP
        !           747: While the simplest forms of these actions are
        !           748: relatively straightforward, the power and efficiency of PEARL
        !           749: derives from the nuances and controls available with these
        !           750: functions which take up much of the rest of this document.
        !           751: Much of the power develops from knowledge provided by the user about
        !           752: how each kind of structure is likely to be retrieved (and therefore
        !           753: how it should be stored).
        !           754: Thus, the data base benefits from knowing as much as possible
        !           755: in advance about the objects that will be placed within it.
        !           756: This information is provided by using a large variety
        !           757: of extra flags during definition calls to \fIcreate\fR.
        !           758: It is used by \fIinsertdb\fR to hash objects into a specific
        !           759: \fIhash bucket\fR in the data base, by \fIfetch\fR to retrieve the
        !           760: correct hash bucket from the data base, and by \fInextitem\fR
        !           761: to filter the desired objects from this bucket.
        !           762: .PP
        !           763: PEARL allows the construction and use of multiple data bases which are
        !           764: described in detail later.
        !           765: Without exerting any effort, a data base is automatically created
        !           766: called \fB*maindb*\fR and pointed to by the special variable \fB*db*\fR.
        !           767: In general, all PEARL functions which deal with a data base have an
        !           768: optional last argument which specifies which data base to use.
        !           769: If it is missing, then the default data base pointed to by
        !           770: \fI*db*\fR is assumed.
        !           771: Thus you can change the default data base
        !           772: simply by assigning the desired data base to \fI*db*\fR.
        !           773: For simplicity, this optional data base argument is not
        !           774: mentioned in the following discussion.
        !           775: .PP
        !           776: The function \fBinsertdb\fR takes a single structure argument and
        !           777: inserts it into the data base.
        !           778: In its simplest form \fIinsertdb\fR requires no user flags on the
        !           779: definitions of structures.
        !           780: In this case, \fIinsertdb\fR simply hashes on the type of the
        !           781: structure regardless of its specific contents so that each
        !           782: entry ends up in a bucket with all other entries of that type.
        !           783: For example, to insert into the data base the PTrans which was
        !           784: saved in the Lisp variable Trip above, you simply provide it as an
        !           785: argument to \fIinsertdb\fR:
        !           786: .DS
        !           787: (insertdb  Trip)
        !           788: .DE
        !           789: We could also put the PTrans (saved in Leaving whose To slot
        !           790: was changed to School) which was the MObject of the MTrans above
        !           791: in the data base with:
        !           792: .DS
        !           793: (insertdb  Leaving)
        !           794: .DE
        !           795: Since no information has been provided by the user about how to
        !           796: efficiently distinguish PTranses in general, these two will be stored
        !           797: in the same bucket (as will all PTranses).
        !           798: When inserting an item into a bucket, \fIinsertdb\fR will check
        !           799: to ensure that this specific item is not already in that bucket
        !           800: (using \fIeq\fR) and will only insert it if
        !           801: it is not already there, thus avoiding duplicates.
        !           802: .PP
        !           803: The function \fBremovedb\fR takes a single structure argument
        !           804: and removes it from any place in the data base where it has been
        !           805: put using \fIeq\fR to determine equality.
        !           806: .PP
        !           807: Since one often wants to create an individual and then insert it into
        !           808: the data base, there is a macro \fBdbcreate\fR provided whose
        !           809: arguments are precisely like \fIcreate\fR.
        !           810: Thus, \fI(dbcreate individual PTrans ....)\fR expands into
        !           811: \fI(insertdb (create individual PTrans ....) )\fR.
        !           812: .NH 2
        !           813: Retrieving Hash Buckets From the Data Base: Fetch
        !           814: .PP
        !           815: .hy next-item
        !           816: The simplest case of fetching from the data base is
        !           817: equivalent to asking if a particular, completely defined
        !           818: object is in the data base.
        !           819: This is performed by a combination of the functions 
        !           820: fIfetch\fR and \fInextitem\fR.
        !           821: The first step is to retrieve the hash bucket(s) for the object.
        !           822: For example, to determine whether the object stored in Trip is in the
        !           823: data base, the first step is to call the function \fBfetch\fR and
        !           824: store what it returns (the form of what is returned is described
        !           825: below):
        !           826: .DS
        !           827: (setq  PotentialTrips  (fetch  Trip) )
        !           828: .DE
        !           829: .PP
        !           830: The function \fIfetch\fR takes a single structure argument which is
        !           831: called the \fBpattern\fR.
        !           832: What \fIfetch\fR returns includes this pattern and the hash bucket(s)
        !           833: from the data base which contain those structures which are
        !           834: most likely to "match".
        !           835: The rules of "matching" are fairly complex and are described in
        !           836: detail in section 20, but for the moment it is enough to know that
        !           837: two structures match if their respective slots contain equal values.
        !           838: Thus matching is closer to Lisp's \fIequal\fR than to \fIeq\fR.
        !           839: .NH 2
        !           840: Accessing the Results of a Fetch: Nextitem.
        !           841: .PP
        !           842: Conceptually, what \fIfetch\fR returns is a restricted type of \fBstream\fR.
        !           843: A stream is a "virtual" list, whose items are computed only as needed.
        !           844: When a fetch from the data base is performed, the pattern provided
        !           845: is only used to construct a stream containing that pattern and the
        !           846: appropriate hash bucket from the data base;
        !           847: no matching (comparing)
        !           848: between the pattern and objects in the data base occurs.
        !           849: Thus the stream contains pointers to all data base items in the
        !           850: same hash bucket, regardless of their likelihood of matching the pattern.
        !           851: Therefore, the \fIstream\fR or "virtual list" returned by \fIfetch\fR is
        !           852: in fact bigger than the list of actual items which match.
        !           853: (For this reason, the default PEARL print function only prints how
        !           854: many potential items are in the stream.)
        !           855: .PP
        !           856: For our purposes, you should regard the object that \fIfetch\fR
        !           857: returns to be a funny sort of black box, whose only use is as
        !           858: an argument to the function \fBnextitem\fR.
        !           859: \fINextitem\fR will compute the next element to be removed from the stream.
        !           860: When elements are extracted from the stream with the function \fInextitem\fR,
        !           861: the pattern is "matched" against successive items from the hash bucket
        !           862: until one matches (and is returned) or until the potential items run out
        !           863: (and \fInil\fR is returned).
        !           864: .PP
        !           865: \fINextitem\fR is very much like the function \fIpop\fR in Lisp because it
        !           866: updates the status of the stream to reflect the
        !           867: extraction of the "topmost element" similar to the way \fIpop\fR replaces
        !           868: its list argument with its \fIcdr\fR.
        !           869: \fINextitem\fR does this by destructively modifying the stream
        !           870: (but not the hash bucket);
        !           871: once the top item
        !           872: has come off it is no longer a part of the stream.
        !           873: Like \fIpop\fR, \fInextitem\fR returns \fInil\fR if the stream is empty.
        !           874: .PP
        !           875: A stream, as returned by \fIfetch\fR in PotentialTrips,
        !           876: will \fBnever\fR be \fInil\fR but instead will be a list.
        !           877: In all cases, the first element will be the atom \fB*stream*\fR.
        !           878: In most cases, the second element (\fIcadr\fR) is the pattern (object
        !           879: being fetched) and the rest (\fIcddr\fR) is
        !           880: the hash bucket that the object hashes to.
        !           881: However, it is entirely possible for the hash bucket to either
        !           882: fail to contain any instances of the object, or to contain
        !           883: multiple instances of the object.
        !           884: The form that is printed by PEARL's default print function is:
        !           885: the atom \fB*stream:*\fR, the object being fetched,
        !           886: and the number of potential items in the stream,
        !           887: avoiding the prining of a lengthy result.
        !           888: (If the pattern is actually a function structure, then the atom
        !           889: used is \fB*function-stream:*\fR.)
        !           890: .PP
        !           891: Thus, to actually determine whether the object in Trip is in the data
        !           892: base, it is necessary to ask for the \fInextitem\fR in the bucket of
        !           893: the stream PotentialTrips (that is, in the \fIcddr\fR)
        !           894: which matches the object being fetched (that is, the \fIcadr\fR
        !           895: of PotentialTrips):
        !           896: .DS
        !           897: (setq  FirstResult  (nextitem  PotentialTrips) )
        !           898: (setq  SecondResult  (nextitem  PotentialTrips) )
        !           899: .DE
        !           900: If nothing matching Trip occurred in the data base, FirstResult would
        !           901: contain \fInil\fR;
        !           902: otherwise, it would contain an object in the data base
        !           903: which matches Trip.
        !           904: If you have typed in all the examples we have shown you above,
        !           905: then FirstResult will contain the same value as Trip.
        !           906: SecondResult will be \fInil\fR.  (The only other object in the same
        !           907: bucket is the value of Leaving, but that does not match because
        !           908: its To slot contains School after the \fIpath put\fR above.)
        !           909: If the two structures in Trip and Leaving both contained
        !           910: the same slot fillers, they would both match Trip and each
        !           911: would be returned by \fInextitem\fR on successive calls.
        !           912: .PP
        !           913: This is essentially the only type of fetching that is
        !           914: useful with the information presented so far,
        !           915: but more powerful types will be described shortly.
        !           916: .PP
        !           917: Since the functions \fIcreate\fR, \fIfetch\fR, and \fInextitem\fR
        !           918: are often used in combination, several macros combining them are
        !           919: provided by PEARL:
        !           920: .IP
        !           921: When you wish to create a pattern only long enough to use it as an
        !           922: argument to \fIfetch\fR, you can use the macro \fBfetchcreate\fR
        !           923: which is defined in such a way that \fI(fetchcreate blah)\fR is
        !           924: equivalent to \fI(fetch (create blah) )\fR ).
        !           925: .IP
        !           926: If you want to do a \fIfetchcreate\fR in a function definition and
        !           927: you wish the pattern to be created only once but used each time
        !           928: this function is called (a potential savings in space and time),
        !           929: the macro \fBinlinefetchcreate\fR will call \fIcreate\fR when it
        !           930: expands and then expand to a call to fetch with this pattern.
        !           931: .IP
        !           932: If you want to do a \fIcreate\fR in a function definition and
        !           933: you wish the object to be created only once,
        !           934: the macro \fBinlinecreate\fR will call \fIcreate\fR when it
        !           935: expands and effectively replace itself with the result.
        !           936: .IP
        !           937: When you wish to fetch but only need the resulting stream long
        !           938: enough to use it as an argument to \fInextitem\fR, you can use
        !           939: the macro \fBfirstfetch\fR which is defined in such a way that
        !           940: \fI(firstfetch blah)\fR is equivalent to \fI(nextitem (fetch blah) )\fR ).
        !           941: .IP
        !           942: If your only goal in fetching some fully-specified object is to
        !           943: test for its existence in the data base, the function \fBindb\fR
        !           944: which expects a single structure argument will return \fInil\fR
        !           945: if it is not there, and non-\fInil\fR if it is.
        !           946: (Note that \fIindb\fR uses \fIstrequal\fR rather than \fImatch\fR.)
        !           947: .IP
        !           948: It is sometimes convenient to have a list of all the items which would be
        !           949: returned by successive calls to \fInextitem\fR on a stream.
        !           950: The function \fBstreamtolist\fR expects a stream argument and
        !           951: returns a list of the items which the stream would produce.
        !           952: .NH
        !           953: The Default Values for Unspecified Slots
        !           954: .PP
        !           955: When creating an instance of a given type, one may not always
        !           956: wish to fill in all the slots of the structure, either because
        !           957: the slot value is unknown or immaterial.
        !           958: PEARL has a mechanism for filling unfilled slots with default values.
        !           959: The simplest form of defaulting involves two
        !           960: predefined objects, \fBnilsym\fR and \fBnilstruct\fR.
        !           961: \fINilsym\fR is a \fIsymbol\fR, and roughly corresponds to Lisp's
        !           962: \fInil\fR when \fInil\fR is viewed as an atom.
        !           963: \fINilstruct\fR is a structure without any slots,
        !           964: and corresponds to a null structure.
        !           965: In the absence of a specified value, PEARL will fill in slots
        !           966: of an individual instance of a structure being created
        !           967: with \fInilsym\fR if the slot type is \fIsymbol\fR,
        !           968: \fInilstruct\fR if the slot type is \fIstruct\fR, zero if the slot
        !           969: is of type \fIint\fR, and Lisp \fInil\fR
        !           970: if the slot is of type \fIlisp\fR or \fIsetof <any type>\fR.
        !           971: Note that it is up to the user to decide upon the meaning of
        !           972: \fInilsym\fR and \fInilstruct\fR during further processing.
        !           973: For example, you must decide for your own application whether
        !           974: a \fInilstruct\fR filling the MObject slot of a MTrans indicates
        !           975: that nothing was said or that what was said is unknown.
        !           976: .PP
        !           977: Often you may desire closer control over the default values of
        !           978: a particular slot within individual instances.
        !           979: For example, suppose you had a definition of Person that
        !           980: includes several pieces of information about a person:
        !           981: .DS
        !           982: (create base  Person
        !           983:        (Identity  symbol)
        !           984:        (Age  int)
        !           985:        (Salary  int)
        !           986:        (Health  symbol) )
        !           987: .DE
        !           988: The Identity slot would be filled in with a unique symbol for
        !           989: that person (such as the symbol John), the Age slot would contain
        !           990: the age in years, the Salary slot would get the person's monthy salary
        !           991: in dollars, and the Health slot would contain a \fIsymbol\fR indicating
        !           992: their state of health.
        !           993: Now in creating an individual instance of a Person
        !           994: the Identity slot should be always filled in, but we may desire the
        !           995: other slots to be defaulted to 30 (years), 20000 (dollars) and Healthy.
        !           996: However, under the default system described so far, these would be
        !           997: defaulted to zero, zero and \fInilsym\fR.
        !           998: PEARL provides the ability to specify individual defaults for
        !           999: each slot of a particular structure type.
        !          1000: This is done at \fIbase\fR creation time by following the type
        !          1001: within a slot with the new default value.
        !          1002: Thus our definition of Person would be:
        !          1003: .DS
        !          1004: (create base  Person
        !          1005:        (Identity  symbol)
        !          1006:        (Age  int  30)
        !          1007:        (Salary  int  20000)
        !          1008:        (Health  symbol  Healthy) )
        !          1009: .DE
        !          1010: Although the main purpose of a call to \fIcreate base\fR is to define
        !          1011: a structure, it also creates a special individual of the type
        !          1012: being defined which has its slots filled with the default values.
        !          1013: For this reason this individual is called the \fBdefault instance\fR
        !          1014: of that type.
        !          1015: It is a structure instance like any other, only a
        !          1016: pointer to it is kept with the type definition, and it is consulted
        !          1017: whenever an instance of that type is constructed.
        !          1018: Thus the default values (either the user-defined defaults or
        !          1019: the standard defaults) will always be used whenever the user
        !          1020: declines to fill in a slot of a structure instance.
        !          1021: For more on defaults, see the discussion of inheriting in
        !          1022: section 19 on creating expanded structures.
        !          1023: .NH
        !          1024: Using Patterns For More Flexible and Powerful Retrieval
        !          1025: .PP
        !          1026: If the fetching mechanisms described so far were the
        !          1027: only sort of fetching that we could do, \fIfetch\fR
        !          1028: (and PEARL) would not be very useful.
        !          1029: What is needed is a way to only partially specify the
        !          1030: values in the structure to be fetched.
        !          1031: Note that the default mechanism does not accomplish this,
        !          1032: since all slots are specified at creation time, even if they
        !          1033: get \fInilsym\fR, \fInilstruct\fR, or \fInil\fR for a value.
        !          1034: What is needed is the ability to specify a \fIdon't care\fR
        !          1035: value for slots whose values should not affect the matching
        !          1036: process during retrieval.
        !          1037: The easiest way to accomplish this in PEARL is to create
        !          1038: a type of object called a \fBpattern\fR.
        !          1039: A \fIpattern\fR is similar to an \fIindividual\fR instance of
        !          1040: a structure except that a special pattern-matching variable
        !          1041: called \fB?*any*\fR which means \fIdon't care\fR or \fImatch anything\fR
        !          1042: is used as the default value for unspecified slots.
        !          1043: (The reason for its name will be clear after the description
        !          1044: of pattern-matching variables later in this section.
        !          1045: Even more detail on pattern-matching variables and more powerful
        !          1046: patterns is provided in sections 21-23 on the matching process,
        !          1047: blocks, lexically scoped variables, and the
        !          1048: unbinding of variables.)
        !          1049: .PP
        !          1050: Patterns are created with \fIcreate\fR using \fIpattern\fR
        !          1051: as the first argument.
        !          1052: Other than this, their syntax is exactly the same as individuals.
        !          1053: An example of a \fIpattern\fR creation is:
        !          1054: .DS
        !          1055: (create pattern  PTrans  JohnWentSomewhere
        !          1056:        (Actor  John)
        !          1057:        (Object  John) )
        !          1058: .DE
        !          1059: This pattern would match any instance of PTrans in which John
        !          1060: was both the actor and the object being moved.
        !          1061: (Note that this pattern is stored in the Lisp variable
        !          1062: JohnWentSomewhere in the same way as other individuals.)
        !          1063: The main use of patterns is as arguments to \fIfetch\fR, as in:
        !          1064: .DS
        !          1065: (setq  PotentialGoings  (fetch  JohnWentSomewhere) )
        !          1066: .DE
        !          1067: \fIFetch\fR will return a stream containing all PTranses in the
        !          1068: data base in which John was the actor and object, regardless
        !          1069: what the From and To slots contain.
        !          1070: More complex examples can be created.
        !          1071: Patterns can be embedded as in:
        !          1072: .DS
        !          1073: (create pattern  MTrans  InformJohnGoingSomewhere
        !          1074:        (MObject  (PTrans  (Actor  John)
        !          1075:                           (Object  John) ) ) )
        !          1076: .DE
        !          1077: Since all unspecified slots are filled with ?*any*, this pattern
        !          1078: will return any MTranses concerning any of John's PTranses
        !          1079: when passed to \fIfetch\fR.
        !          1080: Thus, if we insert InformLeaving from above in the data base:
        !          1081: .DS
        !          1082: (insertdb  InformLeaving)
        !          1083: .DE
        !          1084: then the following will fetch that object:
        !          1085: .DS
        !          1086: (nextitem  (fetch  InformJohnGoingSomewhere) )
        !          1087: .DE
        !          1088: .PP
        !          1089: Usually one is interested in a more specific piece of information.
        !          1090: For example, if you knew that John told Carol something and wanted
        !          1091: to find out what it was, then you could do this two ways.
        !          1092: One is to create a pattern, fetch it and look at the MObject slot of
        !          1093: the result:
        !          1094: .DS
        !          1095: (create pattern  MTrans  WhatDidJohnTellCarol
        !          1096:        (Actor  John)
        !          1097:        (From  John)
        !          1098:        (To  Carol) )
        !          1099: (setq  Result  (firstfetch  WhatDidJohnTellCarol) )
        !          1100: (path  get  Result  'MObject)
        !          1101: .DE
        !          1102: However, you might prefer to use a pattern which explicitly
        !          1103: shows that you want that value and gives you a slightly easier
        !          1104: way to get at it.
        !          1105: In this case, you can specify a pattern-matching variable
        !          1106: in the MObject slot of the pattern.
        !          1107: A pattern-matching variable is created by preceding an atom with a
        !          1108: question mark \fB?\fR as in \fI?What\fR.
        !          1109: The question mark is a read macro character which reads the next
        !          1110: atom and builds the list \fI(*var* What)\fR out of it (or
        !          1111: \fI(*global* What)\fR if \fIWhat\fR has previously been declared
        !          1112: global to PEARL;
        !          1113: see below for more on global variables.).
        !          1114: During matching, this variable will get bound to the value
        !          1115: of the slot it gets matched against:
        !          1116: .DS
        !          1117: (create individual  MTrans  WhatDidJohnTellCarol
        !          1118:        (Actor  John)
        !          1119:        (MObject  ?What)
        !          1120:        (From  John)
        !          1121:        (To  Carol) )
        !          1122: (firstfetch  WhatDidJohnTellCarol)
        !          1123: .DE
        !          1124: To access the value of a pattern-matching variable in
        !          1125: a structure, one uses either the function \fBvalueof\fR
        !          1126: (which is an expr) or the fexpr \fBvarvalue\fR.
        !          1127: Both functions have two arguments: the name of the
        !          1128: pattern-matching variable whose value you want and
        !          1129: the structure it occurs in (which is evaluated internally
        !          1130: by \fIvarvalue\fR).
        !          1131: Thus both of the following are equivalent:
        !          1132: .DS
        !          1133: (valueof   \fB'\fRWhat  WhatDidJohnTellCarol)
        !          1134: (varvalue  What  WhatDidJohnTellCarol)
        !          1135: .DE
        !          1136: .NH
        !          1137: Marking Structures During Creation For More Efficient Retrieval
        !          1138: .PP
        !          1139: Besides specifying what type each structure is, the simplest
        !          1140: piece of information that \fIinsertdb\fR would like the user
        !          1141: to give it through \fIcreate\fR concerns which slot(s) of
        !          1142: a type would be most likely to contain unique information
        !          1143: about a particular instance of that type.
        !          1144: This information is used to differentiate instances of the
        !          1145: type from each other, so that they will be hashed into
        !          1146: different hash buckets.
        !          1147: This is similar to the "keys" that many data base systems ask for.
        !          1148: For PTrans, the Actor slot is often the best choice for this role.
        !          1149: For Person, the Identity slot would be the best choice for this role.
        !          1150: Such unique slots are indicated to \fIcreate\fR when defining a
        !          1151: type by placing an asterisk '*' before the slotname in a
        !          1152: (<slotname> <type>) pair.
        !          1153: For example, our new definitions of PTrans and Person
        !          1154: to take advantage of this would look like:
        !          1155: .DS
        !          1156: (create base  PTrans
        !          1157:        (* Actor  symbol)
        !          1158:        (   Object  symbol)
        !          1159:        (   From  symbol)
        !          1160:        (   To  symbol) )
        !          1161: (create base  Person
        !          1162:        (* Identity  symbol)
        !          1163:        (   Age  int  30)
        !          1164:        (   Salary  int  20000)
        !          1165:        (   Health  symbol  Healthy) )
        !          1166: .DE
        !          1167: If you execute this when you have already executed the other examples
        !          1168: in this document, PEARL will warn you that you are redefining the
        !          1169: base structures PTrans and Person.
        !          1170: This is all right, since that is precisely what we want to happen.
        !          1171: However, the previous instances of PTrans will remain hashed in the
        !          1172: more inefficient way and will not match any later PTrans structures
        !          1173: that are defined. 
        !          1174: If you find these warnings annoying when redefining structures,
        !          1175: they may be turned off by setting the special variable
        !          1176: \fB*warn*\fR to \fInil\fR instead of the initial \fIt\fR.
        !          1177: (Note that the Lisp scanner requires a space (or other
        !          1178: white space) to separate the asterisk from the slotname.
        !          1179: Otherwise one would have the slotname \fI*Actor\fR).
        !          1180: .PP
        !          1181: Any number of starred slots may be provided within a structure
        !          1182: definition, but usually only one or two are necessary.
        !          1183: How one decides which slots should be starred is an
        !          1184: art, and depends significantly on your application and the nature
        !          1185: of your data.
        !          1186: The basic rule of thumb is to choose those slots
        !          1187: whose values vary the most widely from instance to instance.
        !          1188: A bad choice will not usually cause the system to bomb or
        !          1189: operate incorrectly in any way, but when it comes time to
        !          1190: fetch an object back out of the data base the system may have
        !          1191: to take the time to scan a large amount of the data base
        !          1192: rather than finding the desired object very rapidly.
        !          1193: Thus execution time is usually the only penalty one pays
        !          1194: for an improper choice of slots to star.
        !          1195: .PP
        !          1196: However, there is one type of use of a slot which can cause
        !          1197: problems in combination with hashing information.
        !          1198: It involves the use of pattern-matching variables and will
        !          1199: serve as a useful example of how to use variables and of how
        !          1200: \fIinsertdb\fR and \fIfetch\fR use the hashing
        !          1201: information to insert and find objects.
        !          1202: The key difference between them is that while \fIinsertdb\fR
        !          1203: inserts an object in as many places as it can, \fIfetch\fR only
        !          1204: looks for it in the \fBbest\fR place.
        !          1205: (What we mean by best will be more obvious after section 13.)
        !          1206: .PP
        !          1207: The problem situation occurs when you wish to insert items
        !          1208: into the data base which contain a variable in the starred
        !          1209: slot (representing general knowledge) and then use,
        !          1210: as a pattern, a structure with that slot filled.
        !          1211: Thus, the following sequence will fail to find Thing
        !          1212: in the data base and instead will return \fInil\fR:
        !          1213: .DS
        !          1214: (create base  Thing
        !          1215:        (*  One  int) )
        !          1216: .DE
        !          1217: .DS
        !          1218: (dbcreate individual  Thing  DBThing
        !          1219:          (One  ?O)
        !          1220:          (Two  2) )
        !          1221: .DE
        !          1222: .DS
        !          1223: (nextitem (fetchcreate individual  Thing  PatThing
        !          1224:                       (One  1)
        !          1225:                       (Two  2) )
        !          1226: .DE
        !          1227: This fails \fIsimply because of the hashing\fR.
        !          1228: Let us see why.
        !          1229: When \fIinsertdb\fR is asked to put something into the data base,
        !          1230: it seeks to put it as many places as the hashing information
        !          1231: indicates are good places to want to look for it.
        !          1232: With no hashing information at all, the only thing \fIinsertdb\fR
        !          1233: can do is to put the object with all other objects of its type.
        !          1234: Thus, with no hashing information, all Things are put together in
        !          1235: the same hash bucket.
        !          1236: With the hashing information, \fIinsertdb\fR would like to put
        !          1237: DBThing in a second (and better) place based on the fact that it
        !          1238: is a Thing \fIand\fR on the value of its One slot.
        !          1239: Unfortunately, its One slot has an unbound variable in it and does
        !          1240: not provide any information which is useful.
        !          1241: Thus the hashing process puts DBThing into the data base in 
        !          1242: only one place.
        !          1243: However, when \fIfetch\fR indexes PatThing, it uses the hashing
        !          1244: information to determine that it should look in the data base
        !          1245: under the best combination which is \fIThing + 1\fR.
        !          1246: Since DBThing is not there, it is not found.
        !          1247: If we remove the asterisk, this sequence will return
        !          1248: DBThing with ?O bound to 1 because both DBThing and PatThing will
        !          1249: get indexed into the same spot (along with all other Things).
        !          1250: Thus you should be very careful when determining how to hash 
        !          1251: types of structures when you intend to insert them into
        !          1252: the data base with variables in them.
        !          1253: (An alternative solution which could be more efficient if used
        !          1254: carefully is to use the function \fIfetcheverywhere\fR which is
        !          1255: described in section 13.
        !          1256: This problem can also sometimes be solved with the use of adjunct
        !          1257: variables, described in section 14.)
        !          1258: .PP
        !          1259: After more of the system has been described and examples of fetching
        !          1260: and inserting have been given the user will have a better
        !          1261: understanding of this process.
        !          1262: .PP
        !          1263: As another example, let us now create and insert an instance
        !          1264: of our new PTrans which has the Actor slot starred:
        !          1265: .DS
        !          1266: (dbcreate individual  PTrans  Trip
        !          1267:          (Actor  John)
        !          1268:          (Object  John)
        !          1269:          (From  Office)
        !          1270:          (To  Home) ) 
        !          1271: .DE
        !          1272: This would insert Trip with all other PTranses and, because of the
        !          1273: starred slot Actor, also with any other PTranses with a value of
        !          1274: John in the Actor slot.
        !          1275: Next we redefine and recreate the MTrans:
        !          1276: .DS
        !          1277: (create base  MTrans 
        !          1278:        (*  Actor  symbol)
        !          1279:        (    MObject  struct)
        !          1280:        (    From  symbol)
        !          1281:        (    To  symbol) )
        !          1282: .DE
        !          1283: .DS
        !          1284: (create individual  MTrans  InformLeaving
        !          1285:        (Actor  John)
        !          1286:        (MObject  (PTrans  Leaving
        !          1287:                           (Actor  John)
        !          1288:                           (Object  John)
        !          1289:                           (From  Office)
        !          1290:                           (To  Home) ) )
        !          1291:        (From  John)
        !          1292:        (To  Carol) )
        !          1293: .DE
        !          1294: reinsert the PTrans from the MTrans:
        !          1295: .DS
        !          1296: (insertdb  Leaving)
        !          1297: .DE
        !          1298: and finally create and insert two other instances of a PTrans,
        !          1299: one with different values in the From and To slots
        !          1300: and one with different values in the Actor and Object slot:
        !          1301: .DS
        !          1302: (create individual  PTrans  Trip
        !          1303:        (Actor  John)
        !          1304:        (Object  John)
        !          1305:        (From  Home)
        !          1306:        (To  School) ) 
        !          1307: .DE
        !          1308: .DS
        !          1309: (create individual  PTrans
        !          1310:        (Actor  Ted)
        !          1311:        (Object  Ted)
        !          1312:        (From  Office)
        !          1313:        (To  Home) )
        !          1314: .DE
        !          1315: Note that this last PTrans will be indexed under the combination
        !          1316: of PTrans and Ted and thus will not be in the same hash bucket we
        !          1317: look in when fetching Trip (which is indexed by PTrans and John):
        !          1318: .DS
        !          1319: (setq  PotentialTrips  (fetch  Trip) )
        !          1320: (setq  Result  (nextitem  PotentialTrips)
        !          1321: PotentialTrips
        !          1322: .DE
        !          1323: Notice the form of the stream PotentialTrips at this point.
        !          1324: .NH
        !          1325: Printing Structures, Symbols and Other PEARL Objects
        !          1326: .PP
        !          1327: As mentioned in the beginning, PEARL stores symbols and
        !          1328: structures (and their definitions) in hunks of memory
        !          1329: that are circularly linked.
        !          1330: Lisp cannot print out the contents of these blocks in a useful way.
        !          1331: Franz Lisp sometimes goes into an infinite loop trying to print them
        !          1332: and the best UCI Lisp can do is tell you its address,
        !          1333: like #2934, which is not very informative.
        !          1334: As mentioned above, the PEARL prompt-read-eval-print loop knows how
        !          1335: to print these in symbolic form.
        !          1336: However, when you want your own programs to print
        !          1337: them, PEARL provides you with two pairs of functions
        !          1338: to convert these blocks into more readable form.
        !          1339: The first we will discuss is the function \fBvalform\fR.
        !          1340: \fIValform\fR takes a \fIstruct\fR, a \fIsymbol\fR or any other type
        !          1341: of PEARL or Lisp object as an argument and returns a
        !          1342: Lisp S-expression describing the object.
        !          1343: Thus if one calls \fIvalform\fR on our PTrans in Trip:
        !          1344: .DS
        !          1345: (setq  TripAsList  (valform  Trip) )
        !          1346: .DE
        !          1347: the Lisp variable TripAsList will contain the S-expression:
        !          1348: .DS
        !          1349: (PTrans (Actor John) (Object John) (From Home) (To School) )
        !          1350: .DE
        !          1351: Note that \fIvalform\fR does not cause the PTrans to be printed out
        !          1352: at the user's terminal, it is merely a function that returns an
        !          1353: S-expression (just as the Lisp function \fIlist\fR does.)
        !          1354: PEARL functions will operate upon structures and symbols only
        !          1355: when they are in their internal form, so the primary reason
        !          1356: for converting structures to S-expressions is to print them
        !          1357: (or to modify them for use as new input to \fIcreate\fR).
        !          1358: So PEARL provides a more useful function \fBvalprint\fR
        !          1359: that is effectively \fI(sprint (valform <argument>) )\fR.
        !          1360: (\fBSprint\fR is a function provided by UCI Lisp or Franz PEARL
        !          1361: which prints a Lisp expression in a nicely indented form.
        !          1362: There are more details on \fIsprint\fR in the appendix on UCI Lisp
        !          1363: functions added to PEARL.)
        !          1364: \fIValprint\fR is normally used within a Lisp program to
        !          1365: print out any PEARL construct onto the user's terminal
        !          1366: and it is also used by the default print function in the
        !          1367: PEARL prompt-read-eval-print loop.
        !          1368: Try typing the following and notice that they are the
        !          1369: same except that the second value is slightly indented.
        !          1370: .DS
        !          1371: (valprint  Trip)
        !          1372: Trip
        !          1373: .DE
        !          1374: Like \fIsprint\fR, \fIvalprint\fR will accept a second integer
        !          1375: argument telling it which column to start printing in.
        !          1376: The default \fIpearlprintfn\fR uses a value of 4 for this argument
        !          1377: to make the items typed by the user more distinguisable from the 
        !          1378: results typed by PEARL.
        !          1379: .PP
        !          1380: There is one other form of each of these two functions.
        !          1381: The functions \fBfullform\fR and \fBfullprint\fR are
        !          1382: like \fIvalform\fR and \fIvalprint\fR but they print
        !          1383: more complete information.
        !          1384: If you type
        !          1385: .DS
        !          1386: (fullprint  Trip)
        !          1387: .DE
        !          1388: you will notice that the result has two mysterious
        !          1389: \fInil\fRs in each slot.
        !          1390: These represent other forms of information (predicates
        !          1391: and hooks or demons) which can be added to structures
        !          1392: and which will be described later.
        !          1393: At the moment therefore, \fIvalform\fR and \fIvalprint\fR
        !          1394: are all that the user need remember.
        !          1395: .PP
        !          1396: Note also from above that when a pattern with \fI?*any*\fR is printed,
        !          1397: only the name of that variable is printed, and not its value.
        !          1398: (Try typing JohnWentSomewhere and InformJohnGoingSomewhere
        !          1399: if you do not remember what this looked like.)
        !          1400: If a PEARL pattern-matching variable has not been bound,
        !          1401: PEARL indicates this by printing no value.
        !          1402: If a variable is bound, both the variable name and
        !          1403: its value are printed.
        !          1404: Later when you learn how to put your own variables
        !          1405: in slots, this will become more useful.
        !          1406: .PP
        !          1407: When given a data base, these functions assume that the user does
        !          1408: not really want the complete contents of the data base printed out
        !          1409: and so simply print \fI(database: <databasename>)\fR.
        !          1410: To actually have the complete contents of a data base printed out,
        !          1411: use the function \fBprintdb\fR.
        !          1412: With no argument, it prints the default data base.
        !          1413: Otherwise, it expects its argument to evaluate to a data base.
        !          1414: A print function which prints all the internal information contained
        !          1415: in a structure or its definition is \fBdebugprint\fR.
        !          1416: .NH
        !          1417: Error Messages, Bugs, and Error Handling Abilities
        !          1418: .PP
        !          1419: Due to the complex implemention of PEARL and the lack
        !          1420: of facilities in Lisp for easily distinguishing between
        !          1421: types of input, a user's error in using PEARL will not
        !          1422: show up as soon as it occurs, but may instead cause some
        !          1423: unfathomable part of PEARL to bomb out sometime later.
        !          1424: If this should happen, the user might try using the Lisp
        !          1425: trace facilities, but will often find little useful information.
        !          1426: This sad state of affairs is currently unavoidable due to the 
        !          1427: difficulty of catching user errors where they first occur.
        !          1428: This is partly due to our inability to predict what kinds of
        !          1429: errors users are most likely to make.
        !          1430: .PP
        !          1431: PEARL checks as much as it can, but many features are impossible
        !          1432: or prohibitively expensive to check.
        !          1433: The best strategy for the
        !          1434: user to follow is to examine his last interaction with PEARL.
        !          1435: If the error occurred in the bowels of \fIcreate\fR, then there is a
        !          1436: good chance that the user did something wrong in the details of
        !          1437: a slot description in the call to \fIcreate\fR, since gross structural
        !          1438: errors in such calls are checked for.
        !          1439: Inspect your call closely.
        !          1440: .PP
        !          1441: Other errors can be even more difficult, since a function call
        !          1442: may blow up or fail to produce the desired result due to bad
        !          1443: data passed to \fIcreate\fR several calls ago.
        !          1444: A general rule of thumb to use in tracking down mystifying
        !          1445: errors is to check out the definitions of the structures
        !          1446: involved in the function that failed.
        !          1447: Thus if \fIpath\fR blows up, one should determine the type of
        !          1448: the structure passed to \fIpath\fR, and then check the 
        !          1449: \fIcreate\fR call that defined that type.
        !          1450: .PP
        !          1451: Sometimes PEARL may appear to the user to be doing the wrong thing,
        !          1452: but due to PEARL's complex semantics, the user is really at fault.
        !          1453: To make matters worse, there is of course always the chance that
        !          1454: the error really \fBis\fR in PEARL.
        !          1455: Every effort has been made to minimize this chance, and at the
        !          1456: moment there are no known major errors (except those indicated
        !          1457: in this documentation), but as with any complex evolving
        !          1458: software system there is always the chance of obscure errors.
        !          1459: It has been our experience that most errors
        !          1460: are due to the user (including the implementors) not completely
        !          1461: understanding the semantics of some PEARL feature.
        !          1462: This documentation is an effort to minimize this type of error.
        !          1463: For any error which you commit in which PEARL gives what
        !          1464: you consider an unreasonable response, feel free to report
        !          1465: it and we will consider trying to catch it.
        !          1466: These or any other complaints, bugs or suggestions should be
        !          1467: mailed to Joe Faletti via Arpanet or Unix mail
        !          1468: (Kim.Faletti@Berkeley or ucbvax!kim.faletti).
        !          1469: .NH
        !          1470: Short-Circuiting and Redirecting Create Using !, $ and Atoms
        !          1471: .PP
        !          1472: Sometimes, when creating an individual structure,
        !          1473: one may want to fill a slot with an already created structure
        !          1474: that is pointed to by some atom or returned by some function
        !          1475: (or with whatever type of value the slot requires).
        !          1476: In this case, one does not wish to (or cannot) describe the
        !          1477: value for a slot as a list of atoms.
        !          1478: To handle this situation, PEARL allows you to list a Lisp expression
        !          1479: which evaluates to the desired internal form (that is, a form
        !          1480: which needs no processing by \fIcreate\fR), preceding it with
        !          1481: an exclamation point \fB"!"\fR.
        !          1482: The structure (or other object) resulting from evaluating
        !          1483: the Lisp expression will be tested to ensure it is the right type
        !          1484: of value and, if it is, inserted in the newly created structure
        !          1485: as the value of that slot.
        !          1486: (The mnemonic idea of this symbol is as a sort
        !          1487: of "barrier" meaning \fIStop processing here!!! and take this
        !          1488: (almost) literally!!!\fR)  For example, after using
        !          1489: .DS
        !          1490: (create individual  PTrans  Ptrans23
        !          1491:        (Actor  John)
        !          1492:        (Object  John)
        !          1493:        (To  Home) )
        !          1494: .DE
        !          1495: to create an individual PTrans, leaving it in internal form in the
        !          1496: atom Ptrans23, you can then insert this PTrans into a new MTrans
        !          1497: with:
        !          1498: .DS
        !          1499: (create individual  MTrans
        !          1500:        (Actor  Bob)
        !          1501:        (MObject  !  Ptrans23)
        !          1502:        (To  Carol) )
        !          1503: .DE
        !          1504: .PP
        !          1505: At other times the user may want to take the result of evaluating
        !          1506: some Lisp code and splice it into the Lisp expression describing the
        !          1507: structure being created at the point where the description of the
        !          1508: value of a slot would occur.
        !          1509: In this case, you wish some Lisp code to be evaluated and then
        !          1510: you wish \fIcreate\fR to build a value for this slot
        !          1511: by further processing (scanning) the result of this evaluation.
        !          1512: To this end, PEARL will evaluate any slot value preceded by a
        !          1513: \fB"$"\fR and insert its result into the \fIcreate\fR call,
        !          1514: proceeding to process it just as if
        !          1515: the user had typed it in directly.
        !          1516: So if one stores the atom Alice in Name with
        !          1517: .DS
        !          1518: (setq  Name  'Alice) ; the atom Alice, not the symbol Alice
        !          1519:                     ;   (or the value of s:Alice).
        !          1520: .DE
        !          1521: or possibly
        !          1522: .DS
        !          1523: (setq  Name  (read) )
        !          1524: .DE
        !          1525: with the user having typed \fIAlice\fR, then \fI$  Name\fR in
        !          1526: .DS
        !          1527: (create individual  PTrans
        !          1528:        (Actor  $  Name)
        !          1529:        (Object  $  Name)
        !          1530:        (From  Home)
        !          1531:        (To  NewYork) )
        !          1532: .DE
        !          1533: is equivalent to having Alice typed as the Actor and Object
        !          1534: values: \fIcreate\fR evaluates Name and then processes its
        !          1535: value \fIAlice\fR as input.
        !          1536: Thus, the PTrans will be equivalent to
        !          1537: .DS
        !          1538: (create individual  PTrans
        !          1539:        (Actor  Alice)
        !          1540:        (Object  Alice)
        !          1541:        (From  Home)
        !          1542:        (To  NewYork) )
        !          1543: .DE
        !          1544: The power of this construct occurs when Name is a atom whose
        !          1545: value changes at run time (as when it is read above) or the
        !          1546: \fIcreate\fR call is within a loop in which Name takes on many
        !          1547: different values.
        !          1548: .PP
        !          1549: In summary, both ! and $ cause the evaluation of the Lisp
        !          1550: expression following them.
        !          1551: However, ! stops the usual processing and expects an
        !          1552: internal value, whereas $ continues the usual
        !          1553: processing and expects a Lisp description of the value.
        !          1554: When you need either ! or $, you will know it!
        !          1555: Until then, do not worry if you do not understand them very well!
        !          1556: .PP
        !          1557: If the expression you want evaluated is simply an atom
        !          1558: bound to a value of the appropriate type, you need not use the !.
        !          1559: Whenever \fIcreate\fR is looking for a value of a particular
        !          1560: type, and finds a bound atom instead, it evaluates the atom and
        !          1561: if it is bound to the correct type of value, that value is used.
        !          1562: This is only done in \fIsymbol\fR slots when the atom is not a
        !          1563: symbolname and in \fIinteger\fR slots if the atom is not from
        !          1564: the ordinal type (if any) associated with the slot.
        !          1565: .NH
        !          1566: More Flexible Hash Selection
        !          1567: .PP
        !          1568: The use of stars (asterisks *) to indicate useful slots for hashing
        !          1569: described earlier is only one of many hashing schemes that PEARL allows.
        !          1570: This section describes the others, and how the user can control them.
        !          1571: The first point to note is that even with the star hashing a single
        !          1572: structure can be hashed in several different ways.
        !          1573: Thus if one thinks that in a particular program PTrans will be
        !          1574: frequently fetched from the data base given only the
        !          1575: Actor \fBor\fR only the Object (that is, the program might only
        !          1576: know the Actor and desire the whole PTrans, or know only
        !          1577: the Object and desire the whole PTrans) the user should
        !          1578: star \fBboth\fR the Actor and Object slots within
        !          1579: the definition of PTrans.
        !          1580: When PEARL stores a PTrans into the data base, it will index
        !          1581: it under both (PTrans + Actor) and (PTrans + Object) in addition
        !          1582: to the usual indexing with all other PTranses.
        !          1583: In general, any number of slots can be starred.
        !          1584: .PP
        !          1585: Another type of hashing does not use the type of the structure in
        !          1586: creating a hash index.
        !          1587: If the symbol colon (:) is used before the
        !          1588: name of a slot, objects of that type will be hashed under that slot
        !          1589: value only.
        !          1590: Thus if the Actor slot of the PTrans definition was
        !          1591: preceded by a colon instead of a star, then instances of PTrans
        !          1592: would be hashed under the value of the Actor slot alone rather the
        !          1593: value of the (PTrans + Actor).
        !          1594: This would be useful in the case in which one were interested in
        !          1595: fetching any structure in which a particular value, say the
        !          1596: symbol John, appered in a coloned slot.
        !          1597: For example all structures in which John appeared in the Actor slot
        !          1598: could be fetched at once (and very efficiently).
        !          1599: .PP
        !          1600: A third type of hashing is \fBstar-star\fR or \fBdouble-star (**)
        !          1601: hashing\fR.
        !          1602: If a double star is used instead of a single star,
        !          1603: PEARL will use \fBtriple hashing\fR.
        !          1604: Only one triple hashing is allowed per structure.
        !          1605: Triple hashing requires that two, and only two slots be double starred.
        !          1606: If PTrans were to be defined in the following way:
        !          1607: .DS
        !          1608: (create base  PTrans
        !          1609:        (**  Actor  symbol)
        !          1610:        (**  Object  symbol)
        !          1611:        (      From  symbol)
        !          1612:        (      To  symbol) )
        !          1613: .DE
        !          1614: then when an instance of a PTrans is created, it will be hashed
        !          1615: into the data base under a combination of the three values
        !          1616: (PTrans + Actor + Object).
        !          1617: As with all hashing, if a slot is necessary to a particular type
        !          1618: of hashing but is unfilled (or filled with \fInilsym\fR or
        !          1619: \fInilstruct\fR) the hashing will not occur.
        !          1620: Triple hashing is used when one wants fast access to all
        !          1621: individuals of a particular type with two slots likely to have
        !          1622: fairly unique values.
        !          1623: In the case of PTrans, this would allow one fast access to all
        !          1624: PTranses in which John PTranses Mary somewhere.
        !          1625: Distinctions this fine are not usually necessary, and as it
        !          1626: is slightly more expensive at creation and fetching time,
        !          1627: it should only be used when the user is sure of the need for it.
        !          1628: .PP
        !          1629: A fourth type of hashing is \fBcolon-colon\fR or \fBdouble colon (::)
        !          1630: hashing\fR.
        !          1631: It has the same relation to colon hashing as double star
        !          1632: hashing has to star hashing.
        !          1633: If the **'s in the above are replaced with ::, the hashing will be
        !          1634: on (Actor + Object) ignoring the fact that the structure is a PTrans.
        !          1635: This might be useful in fetching all structures involving John and Mary.
        !          1636: As with double star hashing, double colon hashing should be used
        !          1637: sparingly and only one such hashing pair may be used in a type.
        !          1638: .PP
        !          1639: However, it is possible to combine the use of any of these
        !          1640: hashing methods in a single structure.
        !          1641: Thus one could have both double colon hashing and double star
        !          1642: hashing, as well as several * and : hashings as well.
        !          1643: Given several ways, PEARL uses the one
        !          1644: which the most complex one is used during
        !          1645: fetching, since that should provide the greatest degree of
        !          1646: discrimination between items (that is, most likely to narrow
        !          1647: down the choices).
        !          1648: If the value in a slot intended to take part in hashing is unbound
        !          1649: or otherwise not useful, then the next most specific method it used.
        !          1650: Given the values which are considered useful and the hashing
        !          1651: information for the type of structure, the hierarchy of buckets
        !          1652: to be chosen is as follows:
        !          1653: .DS
        !          1654: **  hashing
        !          1655: ::  hashing
        !          1656: *  hashing
        !          1657: :  hashing
        !          1658: .DE
        !          1659: .PP
        !          1660: In section 9 we discussed a problem that arises when the pattern
        !          1661: you are using is more specific than the structures in the data base.
        !          1662: In this case, \fIfetch\fR looks in the data base in the most
        !          1663: specific place and does not find what it is looking.
        !          1664: One alternative is to eliminate the hashing that causes this problem
        !          1665: but this will force \fIfetch\fR to look through a large number of items.
        !          1666: If you do not intend to look all the way through the stream
        !          1667: returned by \fIfetch\fR, there is a version of fetch which will
        !          1668: build the stream out of all the ways the pattern could be fetched.
        !          1669: This function is called \fBfetcheverywhere\fR and will return a
        !          1670: stream made up of the (up to five) hash buckets that its pattern
        !          1671: could be -- potentially expensive if you intend to process the
        !          1672: whole thing.
        !          1673: .PP
        !          1674: In addition to these four methods of hashing, and the simplest one
        !          1675: based on the type of structure only, there are several
        !          1676: hashing labels which are modifiers on these methods and
        !          1677: affect what values are used to compute the index.
        !          1678: .PP
        !          1679: The remaining hashing flags do not introduce any new types
        !          1680: of hashing, but rather modify the way the existing types work.
        !          1681: To motivate these, consider the implementation of Goal withing CD.
        !          1682: In early versions of CD, there were several different types of
        !          1683: goals, including Delta-Prox (goal of being near something),
        !          1684: Delta-Poss (goal of possessing something), and so on.
        !          1685: In general these delta goals were of the form
        !          1686: (Delta-<some CD primitive> (Actor ...) (Objective ...) ).
        !          1687: This lead to an explosion of Delta-goals
        !          1688: (e.g. Delta-Move-Fingers-Within-Telephone-Dial),
        !          1689: and a new way of handling goals was established.
        !          1690: This was simply that all Goals were to have the form:
        !          1691: .DS
        !          1692: (create base  Goal
        !          1693:        (Planner  symbol)
        !          1694:        (Objective  struct) )
        !          1695: .DE
        !          1696: where the Objective would be filled with the appropriate structure,
        !          1697: whether it was a simple Poss or the $DialPhone script.
        !          1698: This change makes CD much cleaner, but poses somewhat of
        !          1699: a problem for hashing.
        !          1700: One of the major uses of hashing within some AI programs
        !          1701: written in PEARL is to associate plans with goals.
        !          1702: So it is best if this process is efficient.
        !          1703: .PP
        !          1704: As an example of this problem (using the early form of Delta-goals):
        !          1705: .DS
        !          1706: ; Declaration of PlanFor rules.
        !          1707: (create base  PlanFor
        !          1708:        (*  Objective  struct)
        !          1709:        (*  Plan  struct) )
        !          1710: .DE
        !          1711: .DS
        !          1712: (create base  Delta-Prox
        !          1713:        (Planner  symbol)
        !          1714:        (Location  symbol) )
        !          1715: .DE
        !          1716: .DS
        !          1717: (create base  Walk-Plan
        !          1718:        (Planner  symbol)
        !          1719:        (From  symbol)
        !          1720:        (To  symbol) )
        !          1721: .DE
        !          1722: .DS
        !          1723: ; Store in the data base the fact that walking is a way of accomplishing
        !          1724: ;    a Delta-Prox goal.
        !          1725: (dbcreate individual  PlanFor
        !          1726:           (Goal  (Delta-Prox  (Planner  ?X)
        !          1727:                              (Location  ?Y) ) )
        !          1728:           (Plan  (Walk-Plan  (Planner  ?X)
        !          1729:                             (From  nilsym)
        !          1730:                             (To  ?Y) ) ) )
        !          1731: .DE
        !          1732: This structure simply says the fact that if one has a goal of being
        !          1733: somewhere, then one plan for doing this is to walk.
        !          1734: Or, using the rule in reverse, if you note that someone is
        !          1735: walking to some location, then you might infer that they had
        !          1736: a goal of being at that location.
        !          1737: Note that after being put into the data base, the rule can be easily
        !          1738: fetched by presenting either half of it as a pattern.
        !          1739: .PP
        !          1740: Thus if a planning program has a goal of doing the action in
        !          1741: the atom GoalAct, then it can query the data base for
        !          1742: any direct plans for doing Act by:
        !          1743: .DS
        !          1744: (fetchcreate individual  PlanFor
        !          1745:             (Goal  !  GoalAct)
        !          1746:             (Plan  ?*any*) )
        !          1747: .DE
        !          1748: So if GoalAct happened to be a Delta-Prox goal, then the
        !          1749: rule above would be fetched.
        !          1750: However the revised form of goals hides the unique nature of
        !          1751: the Delta-goal, and the best one could do is fetch all PlanFor rules
        !          1752: that have a structure of type Goal in their Goal slot.
        !          1753: This is a serious loss since \fIall PlanFors\fR have a Goal
        !          1754: in their Goal slot;
        !          1755: thus the system would have to look through all
        !          1756: PlanFors whenever it was trying to fetch one.
        !          1757: What is needed is a way of telling PEARL that when hashing on Goals,
        !          1758: never hash the structure type Goal, but rather use the
        !          1759: item that fills the Objective slot of the Goal.
        !          1760: This would solve our problem nicely, as now all
        !          1761: PlanFors would be hashed on the name of the Objective (Prox,
        !          1762: Dial-Phone, etc.), and a list of all PlanFors would not have to be
        !          1763: searched to find a particular one, rather the system could just hash
        !          1764: directly to it.
        !          1765: .PP
        !          1766: To indicate to PEARL that this \fBhash aliasing\fR is desired,
        !          1767: place an ampersand '&' before the slot name to be substituted
        !          1768: for the structure name when defining the structure.
        !          1769: Thus Goal would be declared:
        !          1770: .DS
        !          1771: (create base  Goal
        !          1772:        (    Planner  symbol)
        !          1773:        (&  Objective  struct) )
        !          1774: .DE
        !          1775: Naturally only one slot can be selected for hash aliasing.
        !          1776: .PP
        !          1777: In this way, Goals change the way in which other structures
        !          1778: use them to index but the way in which Goals themselves
        !          1779: are indexed will not be affected.
        !          1780: Since many other types of structures are likely to contain Goals,
        !          1781: we must be careful about how this affects the hashing of all of them.
        !          1782: It might be the case that PlanFor was the only structure
        !          1783: indexed based on Goals which would benefit from hash aliasing
        !          1784: and that some structures would actually be hurt by this
        !          1785: because they expected Goals to be only one of many types
        !          1786: of values.
        !          1787: In this case, putting the control of how Goals get used by
        !          1788: other structures into the definition of Goal is a bad idea.
        !          1789: Instead, the control can be moved up into only the
        !          1790: problematic structures.
        !          1791: These structures can simply add the \fB">"\fR hash label to
        !          1792: a starred slot, causing PEARL to use the first starred
        !          1793: slot of the slot-filling structure instead of its type.
        !          1794: For example, when we put a both \fB"*"\fR and \fB">"\fR on the Goal
        !          1795: slot of PlanFor then it will always use the first starred
        !          1796: slot of the Goal in its Goal slot:
        !          1797: .DS
        !          1798: (create base  Goal
        !          1799:        (    Planner  symbol)
        !          1800:        (*  Objective  struct))
        !          1801: .DE
        !          1802: .DS
        !          1803: (create base  PlanFor
        !          1804:        (*  >  Goal  struct)
        !          1805:        (        Plan  struct))
        !          1806: .DE
        !          1807: Thus, the use of \fB">"\fR hashing is called \fBforced aliasing\fR since
        !          1808: the structure filling a slot has very little control over it.
        !          1809: .PP
        !          1810: However, there is one way for a structure to affect
        !          1811: how forced aliasing happens.
        !          1812: If the user wanted to also star the Planner slot of Goal,
        !          1813: but wanted the Objective slot to be used in cases of forced
        !          1814: aliasing, then the use of an \fB"^"\fR on the Objective slot will
        !          1815: allow that:
        !          1816: .DS
        !          1817: (create base  Goal
        !          1818:        (*       Planner  symbol)
        !          1819:        (*  ^  Objective  struct))
        !          1820: .DE
        !          1821: thus allowing Goals inserted directly into the data base to be
        !          1822: indexed by the combinations \fIGoal + Planner\fR and
        !          1823: \fIGoal + Objective\fR while other objects containing Goals would
        !          1824: use the Objective slot rather than Goal \fIOtherObject + Objective\fR.
        !          1825: .PP
        !          1826: On the other hand, if most structures containing Goals would
        !          1827: benefit from the use of the hash aliasing label \fB"&"\fR in Goal,
        !          1828: but only one or two are hurt by it, the use of \fB"&"\fR in Goal
        !          1829: can be overridden by the structures which will contain Goals
        !          1830: by adding the \fB"<"\fR hash label to the starred slot to produce
        !          1831: \fBanti-aliasing\fR.
        !          1832: This gives the controlling structure the last word
        !          1833: over how it is hashed.
        !          1834: .DS
        !          1835: (create base  Goal
        !          1836:        (    Planner  symbol)
        !          1837:        (&  Objective  struct))
        !          1838: .DE
        !          1839: .DS
        !          1840: (create base  OffendedStructure
        !          1841:        (*  <  Slot  struct))
        !          1842: .DE
        !          1843: Thus, the anti-aliasing \fB"<"\fR means \fIjust for this hashing, turn
        !          1844: off hash aliasing (if any) of any structure filling this slot\fR.
        !          1845: .PP
        !          1846: The proper use of hash aliasing and anti-aliasing,
        !          1847: like all the hashing specifiers is an art that must be learned by
        !          1848: applying them to real systems, and the correct hash directives
        !          1849: for a particular system rely critically upon the statistics of
        !          1850: that particular system operating upon a particular set of data.
        !          1851: The hashing mechanism was designed to give the user benefit in
        !          1852: proportion to the effort expended in determining hash labels.
        !          1853: With no effort, the structure type provides some help.
        !          1854: With the addition of each label or pair of labels,
        !          1855: an item to be inserted into the data base is indexed into
        !          1856: another location in the hash table.
        !          1857: Thus the cost of \fIextra\fR labels is simply the time to
        !          1858: find another hash bucket (a few adds and multiplies), and add
        !          1859: the item to the front of the list implying the time and
        !          1860: space incurred by one cons-cell.
        !          1861: .NH
        !          1862: Using Predicates to Constrain Fetching
        !          1863: .PP
        !          1864: Sometimes when you are creating a pattern to fetch a structure,
        !          1865: giving the overall form of the structure is not specific enough.
        !          1866: In particular, it is often desirable to restrict the value of a
        !          1867: slot to a subrange.
        !          1868: For example, using the structure Health:
        !          1869: .DS
        !          1870: (create base  Health
        !          1871:        (Actor  symbol)
        !          1872:        (Level  int) )
        !          1873: .DE
        !          1874: one might want to find out who is sick by creating a pattern
        !          1875: that only matches those Health structures in which the Level
        !          1876: is less than -1 (on a scale from -10 to 10 perhaps).
        !          1877: This can be done by simply writing a predicate (say Sick)
        !          1878: which expects to be given the value of the slot being matched
        !          1879: against as its one argument:
        !          1880: .DS
        !          1881: (de Sick  (Num)
        !          1882:     (lessp  Num  -1) )
        !          1883: .DE
        !          1884: Then you simply add its name after the value
        !          1885: within the <slotname filler> pair of the pattern:
        !          1886: .DS
        !          1887: (create pattern  Health  HealthPattern
        !          1888:        (Actor  ?Person)
        !          1889:        (Level  ?Level  Sick) )
        !          1890: .DE
        !          1891: Given these definitions, a (fetch HealthPattern) would pass
        !          1892: the Level slotfiller of each Health structure it
        !          1893: found in the data base to the predicate Sick.
        !          1894: If Sick returned true (non-\fInil\fR) then it would
        !          1895: consider the slot to have matched whereas a
        !          1896: \fInil\fR from Sick would be considered a mismatch.
        !          1897: There are no standard predicates for users to use for these
        !          1898: purposes, but they are relatively easy to create as needed.
        !          1899: .PP
        !          1900: However, one often has a predicate which has more than one
        !          1901: argument only one (or none) of which are the slot value.
        !          1902: For example, one might want to include a special variable
        !          1903: or the value of some other slot of the structure or the
        !          1904: structure itself.
        !          1905: To make this easy PEARL allows predicates to be arbitrary
        !          1906: s-expressions which may contain any of several special forms
        !          1907: for which PEARL substitutes the current slot or structure.
        !          1908: .PP
        !          1909: If a predicate includes an asterisk \fB*\fR, this is replaced by
        !          1910: the value of the current slot (in the structure being matched
        !          1911: against).
        !          1912: If it includes a double asterisk \fB**\fR, this is replaced
        !          1913: by the whole structure being matched against.
        !          1914: If you want the value of another slot in the current structure,
        !          1915: precede its name with an equal sign (as in \fB=SlotName\fR to
        !          1916: have the value of the slot named SlotName inserted).
        !          1917: There is a readmacro \fB"="\fR which converts \fI=S\fR into 
        !          1918: \fI(*slot* S)\fR, just as the readmacro \fB"?"\fR converts ?X into
        !          1919: \fI(*var* X)\fR (or \fI(*global* X)\fR) for pattern-matching variables.
        !          1920: While processing predicates before executing them, PEARL will
        !          1921: look for these three constructs and replace any of them with the
        !          1922: appropriate value, so pattern-matching variables can also be
        !          1923: used in predicates.
        !          1924: .PP
        !          1925: If there are several predicates on a slot, they are run in
        !          1926: succession until one returns nil or they have all been run.
        !          1927: Thus, a list of predicates provides the effect of a conditional
        !          1928: \fIand\fR.
        !          1929: Thus, although PEARL knows nothing special about logical
        !          1930: connectives like \fIor\fR and \fIand\fR, the effect of a
        !          1931: the usual Lisp \fIand\fR is automatically implied and
        !          1932: the conditional \fIor\fR of Lisp can be had by using the
        !          1933: s-expression type of predicate.
        !          1934: If you wish things to run regardless of their results,
        !          1935: providing the effect of unconditional \fIand\fR, use hooks (demons).
        !          1936: .PP
        !          1937: The above was one of two types of predicates available.
        !          1938: To motivate the other type, consider the case of wanting
        !          1939: to fetch all MTranses about the occurence of a PTrans.
        !          1940: This could be accomplished in one of two ways.
        !          1941: The first is:
        !          1942: .DS
        !          1943: ; In this pattern example, all slots are automatically filled
        !          1944: ;     with ?*any* except the MObject which must be a PTrans.
        !          1945: (create pattern  MTrans
        !          1946:        (MObject  (PTrans) ) )
        !          1947: .DE
        !          1948: Since this method actually results in \fI?*any*\fR being
        !          1949: matched against the fillers in each of the PTrans's
        !          1950: slots, it is a bit inefficient.
        !          1951: .PP
        !          1952: The second way uses \fBstructure predicates\fR
        !          1953: to avoid this matching by specifying merely that the filler
        !          1954: of the MObject slot must be a PTrans structure.
        !          1955: This is done by listing the name of a previously
        !          1956: defined structure after a pattern-matching variable:
        !          1957: .DS
        !          1958: (create pattern  MTrans
        !          1959:        (MObject  ?Obj  PTrans) )
        !          1960: .DE
        !          1961: PEARL will then bind Obj to any structure that is a PTrans
        !          1962: (or expanded PTrans) and match successfully without
        !          1963: examining any of the slots of that PTrans.
        !          1964: PEARL can tell the difference between these two types of
        !          1965: predicates since one will have some sort of function declaration
        !          1966: and the other will be the name of a defined structure.
        !          1967: In the case of a function with the
        !          1968: same name as a structure (which the user should never do as it
        !          1969: invites errors) the name's structure role takes precedence.
        !          1970: .PP
        !          1971: Since a similar effect is sometimes desired on slots of type
        !          1972: \fIsymbol\fR, a similar but more complex mechanism is provided
        !          1973: with symbols and with structures which failed the above test.
        !          1974: If the name of a predicate on a slot of type symbol or structure
        !          1975: is the name of a type of structure, PEARL will assume that what
        !          1976: you want to know about the value in this slot is whether there
        !          1977: is anything in the data base of the type specified by the structure
        !          1978: predicate with the slot value in its first slot.
        !          1979: Thus, if the data base contains an item saying that the symbol
        !          1980: John represents a person:
        !          1981: .DS
        !          1982: (symbol  John)
        !          1983: (dbcreate individual  Person
        !          1984:          (Identity  John))
        !          1985: .DE
        !          1986: then fetching a pattern with a symbol slot which has a Person
        !          1987: predicate on it:
        !          1988: .DS
        !          1989: (fetchcreate pattern  Thing
        !          1990:             (Slot  ?X  Person))
        !          1991: .DE
        !          1992: will cause the equivalent of a fetch from the (default) data base
        !          1993: of the pattern (Person (Identity John)).
        !          1994: Note that this implies that the first slot of a structure enjoys
        !          1995: somewhat of a pre-eminence and that this means that one should
        !          1996: carefully choose which slot to put first.
        !          1997: For efficiency however, \fIfetch\fR is not actually used.
        !          1998: The function actually used is \fBdisguisedas\fR which expects
        !          1999: the slot filler, the structure definition (not default instance)
        !          2000: and an optional data base to look in.
        !          2001: Slot filler may be either a symbol or structure.
        !          2002: .PP
        !          2003: This second type of predicate can also result in a kind of
        !          2004: inefficiency which you might like to avoid.
        !          2005: By putting a variable in the MObject slot of the MTrans along with
        !          2006: a PTrans structure predicate, we preclude PEARL from hashing the
        !          2007: object in any useful way, forcing it to look through all MTranses
        !          2008: instead of only MTranses with PTranses in their MObject slot.
        !          2009: Since patterns are most often less specific than the objects in
        !          2010: the data base, this can make a big difference.
        !          2011: Another problem with a variable plus a structure predicate is that the
        !          2012: structure predicate is either based on fetches and the first slot or it
        !          2013: is limitted to matching the type only.
        !          2014: We might sometimes want a more complicated structure to be used
        !          2015: as a predicate.
        !          2016: However, if we opt instead for the more efficient fetching and
        !          2017: matching by putting a structure in the slot, we have lost the
        !          2018: ability to have a variable bound during the match.
        !          2019: .PP
        !          2020: To allow you both to help improve the hashing and matching of a
        !          2021: structure and also to bind a variable as a side effect, PEARL
        !          2022: provides a mechanism to attach an \fBadjunct variable\fR to the slot.
        !          2023: This adjunct variable in a slot is bound as a side effect whenever the
        !          2024: values in the slot of the two structures were already bound, have
        !          2025: already been matched successfully and all predicates and slot hooks
        !          2026: have been run.
        !          2027: Adjunct variables may be local, lexically scoped or global, just
        !          2028: as any other variable.
        !          2029: To use an adjunct variable, include the variable \fIafter\fR the
        !          2030: value preceded by a colon and preceding any predicates or slot hooks.
        !          2031: For example, 
        !          2032: .DS
        !          2033: (create pattern  MTrans
        !          2034:        (MObject  (PTrans  (Actor  John) )  :  ?Obj) )
        !          2035: .DE
        !          2036: would match any MTrans about John PTransing something, and also
        !          2037: bind the adjunct variable ?Obj to the actual PTrans structure
        !          2038: that applied.
        !          2039: .PP
        !          2040: Since PEARL uses hunks to create so many types of values of its
        !          2041: own, it also provides a set of predicates to test an item to see
        !          2042: what type it is.
        !          2043: Many of them are quite definitely kludges since they depend upon
        !          2044: certain bizarre structures existing only in PEARL-created items
        !          2045: and not in user-created items and thus should not be depended
        !          2046: upon totally.
        !          2047: These functions are \fBstreamp\fR, \fBdatabasep\fR, \fBblockp\fR,
        !          2048: \fBdefinitionp\fR, \fBpsymbolp\fR (to distinguish from Franz Lisp
        !          2049: \fIsymbolp\fR), \fBstructurep\fR,
        !          2050: \fBsymbolnamep\fR, and \fBstructurenamep\fR.
        !          2051: .NH
        !          2052: More Useful Slot Types
        !          2053: .PP
        !          2054: These last few examples begin to show the restricted nature of basic
        !          2055: integer values and of labelling slots as being of type \fIstruct\fR.
        !          2056: If the values in an integer slot will range between -10 and 10,
        !          2057: then you would like to say that.
        !          2058: If the values which will fill a slot of type structure will
        !          2059: be Events or Acts or States, you would like to specify that.
        !          2060: PEARL provides mechanisms to fill both of these needs.
        !          2061: .PP
        !          2062: In the case of an integer slot to be filled with values from a range
        !          2063: of -10 to 10, these integer values do not represent "levels of health"
        !          2064: very well either.
        !          2065: Rather than saying that a person's "health level"
        !          2066: is -2, you might like to say it was "Sick".
        !          2067: In fact, you would
        !          2068: probably like to say that the values of the slot will be one from
        !          2069: among the set of values "Dead, Critical, Sick, OK, Healthy and InThePink".
        !          2070: Moreover, you might like to specify that these values are to be
        !          2071: associated with integer values in such a way that the ordering
        !          2072: you specified holds and you may or may not want to specify precisely
        !          2073: what integer values should be associated with these atoms.
        !          2074: In other words, you would like a type which consists of a set of
        !          2075: values with a linear ordering on them, similar to the Pascal scalar or
        !          2076: enumeration type.
        !          2077: .PP
        !          2078: Such a type exists in PEARL and is created by a call to
        !          2079: the function \fBordinal\fR.
        !          2080: For example, to create an ordered set of values to represent
        !          2081: levels of various states when you want the actual
        !          2082: integer values to be created by PEARL, you would say:
        !          2083: .DS
        !          2084: (ordinal  Levels  (Low  Middle  High))
        !          2085: .DE
        !          2086: which would associate the numbers 1, 2, and 3 with Low, Middle and
        !          2087: High respectively.
        !          2088: If you want to specify the values to be associated with each name,
        !          2089: you simply list the value after each name.
        !          2090: Thus, to create a set of values for use in the integer Level
        !          2091: slot of Health above, you might say the following (the values need
        !          2092: not be listed in order):
        !          2093: .DS
        !          2094: (ordinal  HealthLevels  (Dead -10  Critical -6  Sick -2  OK 2
        !          2095:                                   Healthy 6  InThePink 10))
        !          2096: .DE
        !          2097: Among the actions that \fIordinal\fR performs are the following:
        !          2098: .IP 1.
        !          2099: The assoc-list of names and values for the ordinal type can be
        !          2100: accessed by evaluating the atom built by prepending \fBo:\fR to
        !          2101: the name of the ordinal type.
        !          2102: Given the name of an ordinal type, the function \fBordatom\fR builds
        !          2103: this atom.
        !          2104: Thus \fIo:Levels\fR contains (and \fI(eval (ordatom 'Levels))\fR returns)
        !          2105: the value \fI((Low . 1) (Middle . 2) (High . 3))\fR.
        !          2106: .IP 2.
        !          2107: Atoms consisting of the name of the ordinal type concatenated
        !          2108: with a colon and the value name are created and set to the value
        !          2109: they represent.
        !          2110: Thus \fILevels:Low\fR is set to 1, \fILevels:Middle\fR is set to 2, etc.
        !          2111: .IP 3.
        !          2112: Two atoms with \fB:min\fR and \fB:max\fR concatenated to the
        !          2113: name of the ordinal type are created and set to the lowest
        !          2114: and highest integer values in the type.
        !          2115: Thus \fIHealthLevels:min\fR is -10, and \fIHealthLevels:max\fR is 10.
        !          2116: .IP 4.
        !          2117: The name of the ordinal type is added the list of all ordinal type
        !          2118: names kept in the special variable \fB*ordinalnames\fR*.
        !          2119: .IP 5.
        !          2120: The name of the ordinal type is stored with the slot
        !          2121: so that the print functions can convert from the
        !          2122: integer value back into the name.
        !          2123: Since the default value for integers is zero but most
        !          2124: ordinals will not have a zero value, the print functions will
        !          2125: print \fB*zero-ordinal-value*\fR instead of zero.
        !          2126: .PP
        !          2127: Having created an ordinal type, it is then possible to declare in
        !          2128: a structure definition that a slot will contain values of that type.
        !          2129: The use of values from this type is \fBnot enforced\fR
        !          2130: by PEARL but allows the definitions of integer slots to be
        !          2131: more readable, allows the use of the names of values instead
        !          2132: of their associated integers when creating individuals and
        !          2133: allows PEARL to print the more readable information when
        !          2134: printing an integer slot.
        !          2135: The special atoms created allow predicates, hooks (demons) and
        !          2136: other functions to refer to these values without knowing
        !          2137: their associated integers.
        !          2138: We can now redefine Health to use HealthLevels:
        !          2139: .DS
        !          2140: (create base  Health
        !          2141:        (Actor  symbol)
        !          2142:        (Level  HealthLevels) )
        !          2143: .DE
        !          2144: and create an individual which says that John is in
        !          2145: the pink of health:
        !          2146: .DS
        !          2147: (create individual  Health
        !          2148:        (Actor  John)
        !          2149:        (Level  InThePink) )
        !          2150: .DE
        !          2151: .PP
        !          2152: Declaring a slot to be of type \fIstruct\fR is similarly
        !          2153: unenlightening, so PEARL will accept the name of a
        !          2154: structure type in its place.
        !          2155: For example, we can make the following definitions:
        !          2156: .DS
        !          2157: (create base  Person
        !          2158:        (*  Identity  symbol) )
        !          2159: (create base  Health
        !          2160:        (Actor  Person)
        !          2161:        (Level  HealthLevels) )
        !          2162: .DE
        !          2163: and the Actor slot of Health will be of type \fIstruct\fR.
        !          2164: However, there is currently no extra type checking implied
        !          2165: by this declaration (although it is being considered), but
        !          2166: again it improves the readability of declarations tremendously.
        !          2167: .NH
        !          2168: Attaching Hooks to Structures (If-Added Demons)
        !          2169: .PP
        !          2170: A fairly old construct within AI is that of demons.
        !          2171: In their pure form they could be thought of as asynchronous
        !          2172: parallel processes that watch everything going on within a
        !          2173: system, lying in wait for a particular set of conditions to occur.
        !          2174: These conditions might be a block-manipulating program stacking
        !          2175: some blocks too high to be stable, or a data base program violating
        !          2176: a consistency constraint.
        !          2177: The main problem with classical demons was that in their most flexible
        !          2178: form they gobble up far too much system time, as well as being very
        !          2179: hard to program as it was hard to see just when they might pop up
        !          2180: during the execution of a program.
        !          2181: .PP
        !          2182: In an attempt to control the implementation of demons and at the same
        !          2183: time provide the user with increased control over the built-in PEARL
        !          2184: functions, PEARL allows the user to attach pieces of code to
        !          2185: structures that will be run when specific PEARL (or user) functions
        !          2186: access particular types of data or pieces of data at particular
        !          2187: places in the code.
        !          2188: Thus, PEARL provides a general but restricted and fairly efficient
        !          2189: ability to control the operation of specific functions on specific
        !          2190: pieces of data by providing \fBhooks\fR in the PEARL functions
        !          2191: which check for requests within structures that certain functions
        !          2192: be run when they are accessed in certain ways.
        !          2193: Thus PEARL has two useful sub-breeds of \fBhooks\fR which
        !          2194: watch over either
        !          2195: .IP a.
        !          2196: the value of a particular slot of a particular individual structure,
        !          2197: referred to as \fIslot hooks\fR.
        !          2198: .IP b.
        !          2199: operations upon all individuals of a particular base structure type
        !          2200: referred to as \fIbase hooks\fR.
        !          2201: .PP
        !          2202: Like predicates, hooks can either be the name of a function to
        !          2203: run or a Lisp s-expression to be evaluated.
        !          2204: If an s-expression, they can include the special forms 
        !          2205: \fB**\fR representing the current structure or \fB*\fR representing
        !          2206: the value of the current slot on slot hooks and of the current
        !          2207: structure on base hooks.
        !          2208: Variables or slot names preceded by \fB=\fR are also allowed
        !          2209: (just as in predicates), referring to variables or slots in
        !          2210: the current structure.
        !          2211: If hooks are run by functions which take two items as arguments,
        !          2212: like \fImatch\fR, then the special form \fB>**\fR may
        !          2213: be used to represent the \fBother\fR structure (which \fB>\fR is
        !          2214: meant to suggest) and \fB>*\fR may be used for the value in this
        !          2215: slot of the other structure.
        !          2216: (In the case of functions of only one argument, \fI>*\fR and
        !          2217: \fI>**\fR are the same as \fI**\fR and \fI*\fR.)
        !          2218: In functions which take two arguments, the special form \fB?\fR
        !          2219: may be used to represent the result that the function intends to
        !          2220: return.
        !          2221: (This will be \fI*pearlunbound*\fR in hooks which run before the
        !          2222: function has done its job.)
        !          2223: .PP
        !          2224: When hooks run in the context of a call to \fIpath\fR,
        !          2225: two special variables are available: \fB*pathtop*\fR which
        !          2226: is the topmost structure passed to path and \fB*pathlocal*\fR
        !          2227: which is the current innermost structure whose slot is
        !          2228: being accessed.
        !          2229: When hooks are run in the context of a call to a function which
        !          2230: deals with a data base, then the special variable \fBdb\fR
        !          2231: will contain the data base currently being used.
        !          2232: .PP
        !          2233: The functions used to fill in the special forms like *, **, =slot,
        !          2234: and variables before evaluation come in two flavors and are
        !          2235: called \fBfillin1\fR and \fBfillin2\fR.
        !          2236: \fIFillin1\fR is designed for hooks which run on single structures
        !          2237: and expects as arguments:
        !          2238: .IP a.
        !          2239: the function (s-expression) to fill in,
        !          2240: .IP b.
        !          2241: the slot value (or item if a base hook) to use for \fI*\fR,
        !          2242: .IP c.
        !          2243: the structure to use for \fI**\fR, and
        !          2244: .IP d.
        !          2245: the definition for the item provided as the third argument
        !          2246: (for interpretation of \fI=slot\fR forms).
        !          2247: .PP
        !          2248: \fIFillin2\fR is designed for hooks which run on two structures and
        !          2249: produce a result and expects as arguments:
        !          2250: .IP a.
        !          2251: the function (s-expression) to fill in,
        !          2252: .IP b-c.
        !          2253: the slot values (or structures if a base hook) to use for \fI*\fR and \fI>*\fR,
        !          2254: .IP d-e.
        !          2255: the structures to use for \fI**\fR and \fI>**\fR,
        !          2256: .IP f.
        !          2257: the definition for the structure provided as the fourth argument, and
        !          2258: .IP g.
        !          2259: the result the function intends to return to use for \fI?\fR.
        !          2260: .PP
        !          2261: Four functions for running hooks are provided for the user, two
        !          2262: for running slot hooks and base hooks for single items and two for
        !          2263: running slot hooks and base hooks for pairs of items.
        !          2264: \fBRunslothooks1\fR expects to be given the invoking function's
        !          2265: name, the structure and name of the slot on which to run the slot
        !          2266: hooks, and the value to be used for \fI*\fR.
        !          2267: \fBRunslothooks2\fR expects to be given the invoking function's
        !          2268: name, the two structures and name of the slot in them on which to
        !          2269: run the slot hooks, and the values to be used for \fI*\fR and \fI>*\fR.
        !          2270: \fBRunbasehooks1\fR expects to be given the invoking function's name
        !          2271: and the structure whose base hooks are to be run.
        !          2272: \fBRunbasehooks2\fR expects the invoking function's name, the two
        !          2273: structures whose base hooks are to be run and the result the
        !          2274: calling function plans to return.
        !          2275: .PP
        !          2276: If present, base hooks are run by most major PEARL functions.
        !          2277: If a base hook is labelled with \fI<foo\fR then the function
        !          2278: \fIfoo\fR will execute the hook just after entry and whatever
        !          2279: initialization is necessary.
        !          2280: If a base hook is labelled with \fI>foo\fR then the function \fIfoo\fR
        !          2281: will execute the hook just before exitting.
        !          2282: Slot hooks are run by most major PEARL functions which look through
        !          2283: the slots of a structure.
        !          2284: If a slot hook is labelled with \fI<foo\fR then the function \fIfoo\fR
        !          2285: will execute the hook just before processing the slot.
        !          2286: If a slot hook is labelled with \fI>foo\fR then the function \fIfoo\fR
        !          2287: will execute the hook just after processing the slot.
        !          2288: .PP
        !          2289: However, hooks can be turned off selectively or completely.
        !          2290: By setting the atoms \fB*runallslothooks*\fR and
        !          2291: \fB*runallbasehooks*\fR to nil, you can completely disable
        !          2292: the running of all hooks.
        !          2293: This is useful for debugging and also helps improve efficiency
        !          2294: a bit if you do not use hooks at all.
        !          2295: There is also an atom to go with each PEARL function (of the form
        !          2296: \fB*run...hooks*\fR) which can be used to disable hooks for selected
        !          2297: functions.
        !          2298: The following is a complete table of what PEARL functions run hooks
        !          2299: and the names of the labels that invoke them and the atoms that
        !          2300: control their running:
        !          2301: .LD
        !          2302: Base hooks are run by:                 \kminvoked by hooks labelled:
        !          2303:     create expanded                    \h'|\nmu'<expanded or >expanded 
        !          2304:     create individual                  \h'|\nmu'<individual or >individual 
        !          2305:     create pattern                     \h'|\nmu'<pattern or >pattern 
        !          2306:     smerge                             \h'|\nmu'<smerge or >smerge 
        !          2307:     nextitem                           \h'|\nmu'<nextitem or >nextitem 
        !          2308:     standardfetch *                    \h'|\nmu'<fetch or >fetch 
        !          2309:     expandedfetch *                    \h'|\nmu'<fetch or >fetch 
        !          2310:     fetcheverywhere *                  \h'|\nmu'<fetch or >fetch 
        !          2311:     insertdb                           \h'|\nmu'<insertdb or >insertdb 
        !          2312:     removedb                           \h'|\nmu'<removedb or >removedb 
        !          2313:     nextequal                          \h'|\nmu'<nextequal or >nextequal 
        !          2314:     indb                               \h'|\nmu'<indb or >indb 
        !          2315:     standardmatch                      \h'|\nmu'<match or >match 
        !          2316:     basicmatch                         \h'|\nmu'<match or >match 
        !          2317:     strequal                           \h'|\nmu'<strequal or >strequal 
        !          2318: _________
        !          2319: * \fIfetch\fR does not run hooks on function structures.
        !          2320: .sp 2
        !          2321: Slot hooks are run by:                 \h'|\nmu'invoked by hooks labelled:
        !          2322:     standardmatch                      \h'|\nmu'<match or >match
        !          2323:     basicmatch                         \h'|\nmu'<match or >match
        !          2324:     strequal                           \h'|\nmu'<strequal or >strequal
        !          2325:     path put                           \h'|\nmu'<put or >put
        !          2326:     path clear                         \h'|\nmu'<clear or >clear
        !          2327:     path addset                                \h'|\nmu'<addset or >addset
        !          2328:     path delset                                \h'|\nmu'<delset or >delset
        !          2329:     path addpred                       \h'|\nmu'<addpred or >addpred
        !          2330:     path delpred                       \h'|\nmu'<delpred or >delpred
        !          2331:     path get                           \h'|\nmu'<get or >get
        !          2332:     path getpred                       \h'|\nmu'<getpred or >getpred
        !          2333:     path gethook                       \h'|\nmu'<gethook or >gethook
        !          2334:     path apply                         \h'|\nmu'<apply or >apply
        !          2335: .sp 2
        !          2336: Hooks of both kinds are controlled by these atoms, initially t:
        !          2337:     *runallslothooks*  -- controls all slot hooks.
        !          2338:     *runallbasehooks*  -- controls all base hooks.
        !          2339:     *runputpathhooks*                  \h'|\nmu'*runclearpathhooks*
        !          2340:     *runaddsetpathhooks*               \h'|\nmu'*rundelsetpathhooks*
        !          2341:     *runaddpredpathhooks*              \h'|\nmu'*rundelpredpathhooks*
        !          2342:     *rungetpathhooks*                  \h'|\nmu'*rungetpredpathhooks*
        !          2343:     *rungethookpathhooks*              \h'|\nmu'*runapplypathhooks*
        !          2344:     *runmatchhooks*                    \h'|\nmu'*runsmergehooks*
        !          2345:     *runindividualhooks*               \h'|\nmu'*runexpandedhooks*
        !          2346:     *runpatternhooks*                  \h'|\nmu'*runnextitemhooks*
        !          2347:     *runfetchhooks*                    \h'|\nmu'*runinsertdbhooks*
        !          2348:     *runremovedbhooks*                 \h'|\nmu'*runindbhooks*
        !          2349:     *runnextequalhooks*                        \h'|\nmu'*runstrequalhooks*
        !          2350: .DE
        !          2351: .PP
        !          2352: It is likely that hooks attached to a particular function would like to run
        !          2353: the same function in such a way that hooks will not be invoked.
        !          2354: Or in general, it is possible that you will want to run some PEARL function
        !          2355: in such a way that it is "hidden" from hooks.
        !          2356: To make this easy, a macro is provided called \fBhidden\fR which temporarily
        !          2357: sets the atom \fI*run...hooks*\fR to nil, runs a command and then restores
        !          2358: the former value of that atom.
        !          2359: For this to work correctly, you \fBmust\fR invoke the function you wish hidden
        !          2360: with the name corresponding to the "..." in its \fI*run...hooks*\fR atom.
        !          2361: Thus, you can hide the creation of an individual from hooks by executing:
        !          2362: .DS
        !          2363: (hidden (individual PTrans ....) )
        !          2364: .DE
        !          2365: (see Section 27 for the macro \fIindividual\fR) but \fBnot\fR by executing:
        !          2366: .DS
        !          2367: (hidden (create individual PTrans ....) )
        !          2368: .DE
        !          2369: A parallel function \fBvisible\fR temporarily sets the associated
        !          2370: atom to \fIt\fR before evaluating the function.
        !          2371: .PP
        !          2372: One of the reasons that hooks are checked for both before and after
        !          2373: a PEARL function does its job is to provide the user with the
        !          2374: opportunity to affect the result of the particular task.
        !          2375: In the simplest case, a hook simply executes a piece of code
        !          2376: and does not directly affect the function it is labelled with.
        !          2377: However, if the value returned by a hook is a list whose \fIcar\fR
        !          2378: is either \fB*done*\fR, \fB*fail*\fR, and \fB*use*\fR, then the action
        !          2379: of that function will be modified.
        !          2380: If the result of a hook which runs before the task starts with
        !          2381: \fI*done*\fR, then the hook is presumed to have accomplished what the
        !          2382: PEARL function was supposed to have done and the function will return
        !          2383: immediately with the \fIcadr\fR of the hook's result if there is
        !          2384: one, or else with the structure being operated on (for base hooks)
        !          2385: or the value in the slot (for slot hooks).
        !          2386: If the result of a hook which runs after the task starts with
        !          2387: \fI*done*\fR, then the function will return immediately with the
        !          2388: \fIcadr\fR of the hook's result if there is one, or else with
        !          2389: the result that was going to be return anyway.
        !          2390: .PP
        !          2391: If the result of a hook which runs before the task starts with
        !          2392: \fI*fail*\fR, then the hook is presumed to have determined that the
        !          2393: PEARL function should quit and the function will return
        !          2394: immediately with the \fIcadr\fR of the hook's result if there is one,
        !          2395: or else with the atom \fI*fail*\fR.
        !          2396: If the result of a hook which runs after the task starts with
        !          2397: \fI*fail*\fR, then the function will return immediately with the
        !          2398: \fIcadr\fR of the hook's result (which may be nil).
        !          2399: .PP
        !          2400: If the result of a hook which runs before the task starts with
        !          2401: \fI*use*\fR, then the hook is presumed to have determined that the
        !          2402: PEARL function should use a different value instead of the originally
        !          2403: provided one and the function will use the \fIcadr\fR of the hook's
        !          2404: result for the rest of the task.
        !          2405: If the result of a hook which runs after the task starts with
        !          2406: \fI*use*\fR, then the function will replace its intended result with
        !          2407: the \fIcadr\fR of the hook's result (which may be nil).
        !          2408: Thus, for example, a slot hook labelled with \fI<match\fR can
        !          2409: short-circuit the matching of a slot and one labelled with
        !          2410: \fI<match\fR can reverse the decision made by matching of a slot.
        !          2411: Similarly, a base hook labelled with \fI<match\fR can use its own matching
        !          2412: algorithm and one labelled with \fI>match\fR can modify the result of the
        !          2413: whole match.
        !          2414: .PP
        !          2415: Obviously, these all should be used with great care.
        !          2416: Note that \fIreturn immediately\fR means without even running
        !          2417: any other slot hooks on that slot for slot hooks or without
        !          2418: running any other base hooks on that structure for base hooks.
        !          2419: .PP
        !          2420: For example consider the case of a structure representing someone's
        !          2421: order in a Chinese restaurant.
        !          2422: As items are added to the order, it would be nice if there was a
        !          2423: magical slot TotalBill that contained the current
        !          2424: running total of the cost of the items ordered.
        !          2425: Demons, being such magical creatures, fill the bill nicely.
        !          2426: However, we only wish to have our demon-like hooks
        !          2427: activated when particular slots are filled (added to or accessed).
        !          2428: First consider the simple case in which an order consists of
        !          2429: three items only, the name of the soup and one or two entrees:
        !          2430: .DS
        !          2431: (create base  Chinese-Food-Entree
        !          2432:        (Name  lisp)
        !          2433:        (Price  int) )
        !          2434: .DE
        !          2435: .DS
        !          2436: (create base  Chinese-Dinner-Order
        !          2437:        (Soup  Chinese-Food-Entree)
        !          2438:        (Entree1  Chinese-Food-Entree)
        !          2439:        (Entree2  Chinese-Food-Entree)
        !          2440:        (TotalBill  int) )
        !          2441: .DE
        !          2442: .DS
        !          2443: (create individual  Chinese-Food-Entree
        !          2444:        (Name  (Hot And Sour Soup) )
        !          2445:        (Price  323) )
        !          2446: .DE
        !          2447: .DS
        !          2448: (create individual  Chinese-Food-Entree
        !          2449:        (Name  (Sizzling Rice Soup) )
        !          2450:        (Price  349) )
        !          2451: .DE
        !          2452: .DS
        !          2453: (create individual  Chinese-Food-Entree
        !          2454:        (Name  (Lingnan Beef) )
        !          2455:        (Price  399) )
        !          2456: .DE
        !          2457: .DS
        !          2458: (create individual  Chinese-Food-Entree
        !          2459:        (Name  (Mandarin Chicken) )
        !          2460:        (Price  367) )
        !          2461: .DE
        !          2462: .DS
        !          2463: (create individual  Chinese-Food-Entree
        !          2464:        (Name  (Shrimp Cantonese) )
        !          2465:        (Price  479) )
        !          2466: .DE
        !          2467: .DS
        !          2468: ; an undetermined meal is created.
        !          2469: (create individual  Chinese-Dinner-Order Meal
        !          2470:        (Soup  ^  if  >put  (Maintain-Total  *  **  =TotalBill) )
        !          2471:        (Entree1  ^  if  >put  (Maintain-Total  *  **  =TotalBill) )
        !          2472:        (Entree2  ^  if  >put  (Maintain-Total  *  **  =TotalBill) )
        !          2473:        (TotalBill  0) )
        !          2474: .DE
        !          2475: Note that a slot hook is put after the value in a slot by using
        !          2476: the word \fBif\fR (or \fBhook\fR) followed by the appropriate label
        !          2477: for the invoking function followed by the function name or
        !          2478: s-expression to be evaluated.
        !          2479: Note also that when you want to put hooks on slots of an individual but
        !          2480: do not want to specify a value, the use of \fB"^"\fR will instruct
        !          2481: \fIcreate\fR to copy the default value instead.
        !          2482: If the Maintain-Total function is properly specified, whenever
        !          2483: one replaces one of the food slots with a real dish using
        !          2484: the \fIputpath\fR function, the Maintain-Total function would be
        !          2485: activated and would add the price of that meal to the running total
        !          2486: in the TotalBill slot.
        !          2487: If one changed one's mind a lot, it would be necessary to include
        !          2488: another hook Remove-Price which would be activated by a \fIclearpath\fR.
        !          2489: This would require adding the \fIif-cleared\fR hook
        !          2490: \fI"if >clear Remove-Price"\fR after the \fIif-put\fR hook:
        !          2491: .DS
        !          2492: (create individual  Chinese-Dinner-Order  ChangingMeal
        !          2493:        (Soup  ^  if  >put  (Maintain-Total  *  **  =TotalBill)
        !          2494:                  if  >clear  (Remove-Price  *  **  =TotalBill) )
        !          2495:        (Entree1  ^ if  >put  (Maintain-Total  *  **  =TotalBill)
        !          2496:                    if  >clear  (Remove-Price  *  **  =TotalBill) )
        !          2497:        (Entree2  ^ if  >put  (Maintain-Total  *  **  =TotalBill)
        !          2498:                    if  >clear  (Remove-Price  *  **  =TotalBill) )
        !          2499:        (TotalBill  0) )
        !          2500: .DE
        !          2501: The code for the two hooks follows:
        !          2502: .DS
        !          2503: (de Maintain-Total  (Food  Meal  CurrentMealTotal)
        !          2504:     (putpath  Meal  '(TotalBill)
        !          2505:              (*plus  CurrentTotal
        !          2506:                      (getpath  Food  '(Price) ) ) ) )
        !          2507: .DE
        !          2508: .DS
        !          2509: (de Remove-Price  (Food  Meal  CurrentMealTotal)
        !          2510:     (putpath  Meal  '(TotalBill)
        !          2511:              (*plus  CurrentTotal
        !          2512:                      (getpath  Food  '(Price) ) ) ) )
        !          2513: .DE
        !          2514: .PP
        !          2515: A more flexible meal order structure would not have three slots
        !          2516: for food, but rather a single slot of type \fIsetof struct\fR.
        !          2517: Then entries would be added by the \fIaddsetpath\fR functions,
        !          2518: and the \fIif-put\fR hook would be an \fIif-addset\fR hook but the
        !          2519: code would essentially be the same.
        !          2520: .PP
        !          2521: To attach a base hook to a structure, the first "slot" in its definition
        !          2522: must start with one of the atoms \fBif\fR or \fBhook\fR.
        !          2523: The rest of the slot must then contain a sequence of labels for invoking
        !          2524: functions and function names or s-expressions to be evaluated.
        !          2525: For example, to invoke \fIvalprint\fR before and a user function called
        !          2526: \fIverify\fR afterwards whenever a PTrans is inserted into the data base,
        !          2527: you would define PTrans as follows:
        !          2528: .DS
        !          2529: (create base  PTrans
        !          2530:        (if <insertdb (valprint * 5)
        !          2531:            >insertdb (verify *))
        !          2532:        (* Actor  symbol)
        !          2533:        (   Object  symbol)
        !          2534:        (   From  symbol)
        !          2535:        (   To  symbol) )
        !          2536: .DE
        !          2537: .PP
        !          2538: Recall that PEARL provides a print function called \fBfullprint\fR
        !          2539: which for most structures seen so far printed two extra \fInil\fRs
        !          2540: in each slot.
        !          2541: If a slot has predicates, the first \fInil\fR will be replaced by
        !          2542: a list of them.
        !          2543: If the slot has hooks, the second \fInil\fR will be
        !          2544: replaced by a list of cons-cells with the invoking function in the
        !          2545: \fIcar\fR and the hook in the \fIcdr\fR.
        !          2546: .PP
        !          2547: The invocation of hooks labelled with other forms of \fIpath\fR are similar
        !          2548: except for \fIapply\fR.
        !          2549: If \fI(path <apply Fcn ...)\fR or \fI(path >apply Fcn ...)\fR is executed,
        !          2550: then any hooks which are labelled with Fcn will be run.
        !          2551: .PP
        !          2552: At this point the syntax of a slot in a definition or individual has become
        !          2553: quite complicated, so we summarize with the following BNF grammar:
        !          2554: .DS
        !          2555: { a b c }      means select one of a, b, or c.
        !          2556: [ XXX ]                means optionally XXX.
        !          2557: XXX *          means zero or more XXX's
        !          2558: x | y          means x or y
        !          2559: .DE
        !          2560: .ID
        !          2561: <BaseSlot> ::=  (
        !          2562:                <HashLabels>
        !          2563:                <SlotName>
        !          2564:                <SlotType>
        !          2565:                <InheritOrValue>
        !          2566:                <AdjunctVariable>
        !          2567:                <PredicatesAndHooks>
        !          2568:                )
        !          2569: <IndividualSlot> ::=  (
        !          2570:                      <SlotName>
        !          2571:                      <InheritOrValue>
        !          2572:                      <AdjunctVariable>
        !          2573:                      <PredicatesAndHooks>
        !          2574:                      )
        !          2575: <ExpandedSlot> ::= <BaseSlot> | <IndividualSlot>
        !          2576: .sp 1
        !          2577: <HashLabels>  ::=  { "&" "^" "*" "**" ":" "::" ">" "<" } * 
        !          2578: <SlotType>  ::=  { "struct" "symbol" "int" "lisp" }  |
        !          2579:                 "setof" <SlotType>  |  <OrdinalName>  |
        !          2580:                 <StructureName>
        !          2581: <InheritOrValue>  ::=  <Value>  |  "^"  |  "nil"  |
        !          2582:                      "==" <Value>  |  ":=" <Value>
        !          2583: <Value> ::= <integer>  |  <atom>  |  <list>  |  <Variable>
        !          2584: <AdjunctVariable>  ::=   [ ":" <Variable> ]
        !          2585: <Variable>  ::=  ?<atom>
        !          2586: <PredicatesAndHooks>  ::=  { <Predicate>  |  <Hook> } *
        !          2587: <Predicate>  ::=  <StructureName>  |  <S-Expression>
        !          2588: <Hook>  ::=  "if" <atom> <HookFunction>
        !          2589: <HookFunction>  ::=  <atom>  |  <S-Expression>
        !          2590: .DE
        !          2591: .NH
        !          2592: Creating and Manipulating Multiple Data Bases
        !          2593: .PP
        !          2594: Without any effort on the user's part, a single data base of a
        !          2595: default size exists in PEARL when it starts up.
        !          2596: It is called \fB*maindb*\fR and is pointed to by the special
        !          2597: variable \fB*db*\fR which is assumed by all functions which use a
        !          2598: data base to point to the default data base (that is, the data
        !          2599: base to be used when an expected data base argument is missing).
        !          2600: .PP
        !          2601: To build another data base, choose a name for it and call the
        !          2602: function \fBbuilddb\fR which is an nlambda (fexpr) expecting
        !          2603: the name of the new data base.
        !          2604: You may build as many as you wish and store whichever one you want
        !          2605: in \fI*db*\fR.
        !          2606: .PP
        !          2607: Sometimes one may wish to clear out the data base and start out with a
        !          2608: clean slate.
        !          2609: To make this easy, there is a special function \fBcleardb\fR
        !          2610: which expects either zero or one data bases as arguments
        !          2611: and does the job.
        !          2612: If it receives no arguments, then the default data base is cleared.
        !          2613: \fICleardb\fR removes everything from the data base,
        !          2614: but does not actually delete (or reclaim the storage space of) the
        !          2615: objects within the data base.
        !          2616: But if the objects inside are not pointed to by any program
        !          2617: variables, they are gone for good.
        !          2618: (\fICleardb\fR clears out \fIonly\fR the named data base and not
        !          2619: data bases that it may be built upon as described in the next section.)
        !          2620: .PP
        !          2621: Data bases contain two parts, referred to as \fIdb1\fR and \fIdb2\fR.
        !          2622: \fIDb1\fR contains items which are indexed under only their type
        !          2623: or using single-colon hashing.
        !          2624: Its default size is 29.
        !          2625: \fIDb2\fR contains items which are indexed under two or three
        !          2626: values.
        !          2627: Its default size is 127.
        !          2628: These sizes are chosen to be prime numbers which are just barely
        !          2629: smaller than a power of two.
        !          2630: (This choice was made to take full advantage of hunks in Franz Lisp
        !          2631: which are always allocated to be a power of two.)
        !          2632: The ratio between the two sizes is approximately 1 to 4.
        !          2633: The size for data bases may be chosen by specifying the
        !          2634: power of two that you wish \fIdb2\fR to close to.
        !          2635: .PP
        !          2636: The function \fBsetdbsize\fR expects an integer between 2 and 13
        !          2637: representing the power to which two should be raised.
        !          2638: The default data base size is thus the result of calling
        !          2639: \fIsetdbsize\fR with an argument of 7.
        !          2640: To change the default size, you should call \fIsetdbsize\fR
        !          2641: in your \fI.init.prl\fR file, before creating any data bases of your
        !          2642: own.
        !          2643: \fISetdbsize\fR rebuilds \fI*maindb*\fR (without putting
        !          2644: anything into the new one) and releases all other data bases.
        !          2645: Thus, it should not \fInormally\fR be used at any time after the
        !          2646: processing of the \fI.init.prl\fR file.
        !          2647: (In the Franz Lisp version, although this full range of values is
        !          2648: accepted, the largest a data base in the 1 to 4 ratio can be
        !          2649: is 29 + 127 since hunks are limitted to 128 words.
        !          2650: However, an argument of 9 to \fIsetdbsize\fR will set the sizes
        !          2651: of both data bases to 127.)
        !          2652: Related special variables are \fB*db1size*\fR and
        !          2653: \fB*db2size*\fR which are set by \fIsetdbsize\fR and
        !          2654: \fB*availablesizes*\fR which contains the assoc-list used
        !          2655: to associate the power of two to a size.
        !          2656: .NH
        !          2657: Creating a Forest of Data Bases
        !          2658: .PP
        !          2659: Although having multiple data bases which are unconnected is often
        !          2660: enough, it is sometimes convenient to build onto an already
        !          2661: existing data base in a tree-like fashion.
        !          2662: For example, in a story understanding program, one might want
        !          2663: to have the default data base containing long-term knowledge
        !          2664: and then add a data base to contain the knowledge specific to a
        !          2665: particular story being processed.
        !          2666: In large applications, it can also help to split up special kinds
        !          2667: of knowledge to improve efficiency even more than PEARL's hashing
        !          2668: already does.
        !          2669: With only the ability to build separate data bases, searching for
        !          2670: a fact which might be either general knowledge or specific
        !          2671: knowledge learned from the story would require two fetches, one
        !          2672: from each data base.
        !          2673: However, if the story data base is built on top of the main data
        !          2674: base then simply fetching an item from the story data base will
        !          2675: also include fetching from the main data base.
        !          2676: To build another data base upon an existing one, use the function
        !          2677: \fBbuilddb\fR with two arguments, the name of the new data base
        !          2678: and the name of the old one to build onto:
        !          2679: .DS
        !          2680: (builddb  *story*  *maindb*)
        !          2681: (builddb  *future*  *maindb*)
        !          2682: .DE
        !          2683: These two statements will build two data bases on top of the main
        !          2684: one such that fetching from *story* will look both in it and in
        !          2685: *maindb* but not in *future*.
        !          2686: You can then build further upon any of these if you wish.
        !          2687: Note however, that the second argument must be \fIthe name of the
        !          2688: data base to build upon\fR and cannot be \fI*db*\fR to build upon
        !          2689: the default data base.
        !          2690: Also, if the second argument is missing, then the new data base is
        !          2691: isolated, not built on top of the default data base.
        !          2692: .PP
        !          2693: If your program builds many data bases, it is likely that some of
        !          2694: them will be temporary ones.
        !          2695: If this is so, it is possible to release a data base so that the
        !          2696: space can be garbage collected or reused for a later data base.
        !          2697: To release a data base, pass the actual data base (not its name)
        !          2698: to the function \fBreleasedb\fR.
        !          2699: If the data base is not a leaf of the data base tree, then the
        !          2700: space will not actually be released until all its children
        !          2701: are released also but PEARL will no longer accept it as a data
        !          2702: base argument.
        !          2703: .PP
        !          2704: A list of the names of the currently active data bases is
        !          2705: maintained by PEARL in the special variable \fB*activedbnames*\fR.
        !          2706: .NH
        !          2707: Creating Expanded Subtypes of Previously Defined Objects
        !          2708: .PP
        !          2709: Within CD, as in many applications, you may have many different structures
        !          2710: with some slots with the same name.
        !          2711: PEARL allows this, as it can always tell which type of structure
        !          2712: you are using, and thus it behaves just as if you had used
        !          2713: unique names for all slots.
        !          2714: But sometimes the fact that two different structure types have
        !          2715: slots with the same names is more than a coincidence:
        !          2716: there may be various semantic similarities
        !          2717: between the similar parts of the two structures.
        !          2718: PEARL has a mechanism for creating such structures using the
        !          2719: \fBexpanded\fR selector to \fIcreate\fR.
        !          2720: Basically, you must first define a base structure that contains
        !          2721: all the identical parts of two or more structures, and then you
        !          2722: must define the structures themselves as \fIthe base plus the differences\fR.
        !          2723: A good example of this from CD involves Acts.
        !          2724: All Acts within CD have an Actor slot, and all of
        !          2725: these slots have the same meaning.
        !          2726: That is, whatever is going on, the person in the actor slot is the
        !          2727: motivating force.
        !          2728: So we may first define this common part as a normal
        !          2729: base structure:
        !          2730: .DS
        !          2731: (create base  Act
        !          2732:        (*  Actor  symbol) )
        !          2733: .DE
        !          2734: and then we can define the various acts as expansions upon this base:
        !          2735: .DS
        !          2736: (create expanded  Act  PTrans
        !          2737:        (Object  symbol)
        !          2738:        (From  symbol)
        !          2739:        (To  symbol) )
        !          2740: .DE
        !          2741: .DS
        !          2742: (create expanded  Act  MTrans
        !          2743:        (MObject  struct)
        !          2744:        (From  symbol)
        !          2745:        (To  symbol) )
        !          2746: .DE
        !          2747: .DS
        !          2748: (create expanded  Act  ATrans
        !          2749:        (Object  symbol)
        !          2750:        (From  symbol)
        !          2751:        (To  symbol) )
        !          2752: .DE
        !          2753: .DS
        !          2754: (create expanded  Act  Injest
        !          2755:        (Object  symbol)
        !          2756:        (Through  symbol) )
        !          2757: .DE
        !          2758: Note that we did \fBnot\fR have to list the Actor slot,
        !          2759: it was \fBinherited\fR from the base structure Act.
        !          2760: The structure to be expanded need not be a base structure,
        !          2761: but could itself be an \fIexpanded\fR structure.
        !          2762: Thus we can capture the similarities of the various Transfers with:
        !          2763: .DS
        !          2764: (create expanded  Act  Trans
        !          2765:        (From  symbol)
        !          2766:        (To  symbol) )
        !          2767: .DE
        !          2768: followed by
        !          2769: .DS
        !          2770: (create expanded  Trans  PTrans
        !          2771:        (Object  symbol) )
        !          2772: .DE
        !          2773: .DS
        !          2774: (create expanded  Trans  MTrans
        !          2775:        (MObject  symbol) )
        !          2776: .DE
        !          2777: .DS
        !          2778: (create expanded  Trans  ATrans
        !          2779:        (Object  symbol) )
        !          2780: .DE
        !          2781: In expanded definitions as in base definitions one can
        !          2782: specify hashing and default information in the usual way.
        !          2783: However one can selectively inherit some of this
        !          2784: information from the structure being expanded.
        !          2785: Thus in our first Act example, since we specified star hashing on the
        !          2786: Actor slot, all the structures that we defined in terms of Act
        !          2787: have star hashing on their Actor slot by default.
        !          2788: If we had not wanted this for ATrans, we could have specified this
        !          2789: simply by listing the Actor slot over again without the asterisk.
        !          2790: However, since PEARL requires old slots in expanded structures
        !          2791: to also provide a new value, we need some way to say \fIinherit the
        !          2792: same old value\fR.
        !          2793: This is done by putting an up-arrow \fB"^"\fR where PEARL expects
        !          2794: to find a value, just as when you want to inherit the default
        !          2795: value but add hooks or predicates when creating individuals.
        !          2796: .DS
        !          2797: (create expanded  Act  ATrans
        !          2798:        (Actor  ^)
        !          2799:        (From  symbol) )
        !          2800: .DE
        !          2801: We also could have added colon hashing to the Actor slot by
        !          2802: listing it above as normal.
        !          2803: However, we cannot change the type of a slot and including a type
        !          2804: name after \fIActor\fR will cause PEARL to try to interpret that
        !          2805: type name as a value, (resulting in any of several errors,
        !          2806: depending on the type).
        !          2807: Thus, the hashing information for any slot is inherited from
        !          2808: above, \fIunless\fR it the slot appears in the expanded structure.
        !          2809: .PP
        !          2810: Default values are inherited in almost the same way.
        !          2811: The exception is that if in the original structure
        !          2812: the default is preceded by the symbol \fB":="\fR (rather than being
        !          2813: preceded by either nothing or the symbol \fB"=="\fR), expansions of that
        !          2814: structure will not inherit this value, but instead will get the
        !          2815: standard default for that type.
        !          2816: So if one defines:
        !          2817: .DS
        !          2818: (symbol  Pandora)
        !          2819: .DE
        !          2820: .DS
        !          2821: (create base  Act
        !          2822:        (Actor  symbol  Pandora) )
        !          2823: 
        !          2824:                or
        !          2825: .DE
        !          2826: .DS
        !          2827: (create base  Act
        !          2828:        (Actor  symbol  ==  Pandora) )
        !          2829: .DE
        !          2830: .DS
        !          2831: (create expanded  Act  PTrans
        !          2832:        (From  symbol) )
        !          2833: .DE
        !          2834: then all PTranses will have Pandora as their default Actor, whereas with:
        !          2835: .DS
        !          2836: (create base  Act
        !          2837:        (Actor  symbol  :=  Pandora) )
        !          2838: .DE
        !          2839: .DS
        !          2840: (create expanded  Act  PTrans
        !          2841:        (From  symbol) )
        !          2842: .DE
        !          2843: only the default instance of Act will have Pandora in its Actor
        !          2844: slot and the default Actor of PTrans will just be the usual
        !          2845: default for \fIsymbol\fR-valued slots which is \fInilsym\fR.
        !          2846: Which type of default inheritance to use depends upon the
        !          2847: application, and must be decided on a case by case basis.
        !          2848: .PP
        !          2849: Given this hierarchy, it is often useful to check whether an
        !          2850: object is of a certain type or an expanded version of it.
        !          2851: Two functions provide this ability with slightly different
        !          2852: arguments.
        !          2853: \fBIsa\fR expects an item and the name of the type you want to
        !          2854: check for.
        !          2855: \fBIsanexpanded\fR expects two instances.
        !          2856: Thus the following are always true for any structure X:
        !          2857: .DS
        !          2858: (isa  X  (pname X))
        !          2859: (isanexpanded  X  X)
        !          2860: .DE
        !          2861: Two related functions are \fBnullstruct\fR and \fBnullsym\fR which
        !          2862: are functions for testing for \fInilstruct\fR and \fInilsym\fR
        !          2863: (similar to \fInull\fR for \fInil\fR).
        !          2864: .NH
        !          2865: Fetching Expanded Structures
        !          2866: .PP
        !          2867: To make the extra information that \fIexpanded\fR structures provide
        !          2868: more useful, a special version of \fIfetch\fR called \fBexpandedfetch\fR
        !          2869: is provided which takes the hierarchy of structures defined into
        !          2870: account when fetching.
        !          2871: For example, using the above hierarchical
        !          2872: definitions of Act, Trans, PTrans, MTrans, and ATrans, you can insert
        !          2873: three different Transes into the data base:
        !          2874: .DS
        !          2875: (dbcreate individual  PTrans
        !          2876:          (Actor  Pandora)
        !          2877:          (Object  Pandora) )
        !          2878: .DE
        !          2879: .DS
        !          2880: (dbcreate individual  MTrans
        !          2881:          (Actor  Pandora)
        !          2882:          (To  Pandora) )
        !          2883: .DE
        !          2884: .DS
        !          2885: (dbcreate individual  ATrans
        !          2886:          (Actor  Pandora)
        !          2887:          (From  Pandora) )
        !          2888: .DE
        !          2889: and then to fetch all Transes performed by Pandora, you could use:
        !          2890: .DS
        !          2891: (create pattern  Trans  TransPattern
        !          2892:        (Actor  Pandora) )
        !          2893: .DE
        !          2894: .DS
        !          2895: (expandedfetch  TransPattern)
        !          2896: .DE
        !          2897: Once you start using expanded structures, you usually want to be
        !          2898: able to use the function name \fIfetch\fR and mean \fIexpandedfetch\fR. 
        !          2899: To this end, the standard fetch function is actually called
        !          2900: \fBstandardfetch\fR.
        !          2901: This leaves the function \fBfetch\fR to be bound to whichever
        !          2902: fetch function you wish.
        !          2903: It is initially given the same function definition as
        !          2904: \fIstandardfetch\fR.
        !          2905: .NH
        !          2906: How Two Objects Match
        !          2907: .PP
        !          2908: When a fetch from the data base is performed, the pattern provided
        !          2909: is only used to construct a stream containing that pattern and the
        !          2910: appropriate hash bucket from the data base;
        !          2911: no matching (comparing)
        !          2912: between the pattern and objects in the data base occurs.
        !          2913: Thus the stream contains pointers to all data base items in the
        !          2914: same hash bucket, regardless of their likelihood of
        !          2915: matching the pattern.
        !          2916: When elements are extracted from the stream with the function
        !          2917: \fInextitem\fR, the pattern is "matched" against successive
        !          2918: items from the hash bucket until one matches (and is returned)
        !          2919: or until the potential items run out (and \fInil\fR is returned).
        !          2920: .NH 2
        !          2921: When Is a Pattern Not a Pattern?
        !          2922: .PP
        !          2923: To understand the process with which two objects are
        !          2924: matched, it is necessary to understand what is meant by
        !          2925: a \fIpattern\fR in the context of matching.
        !          2926: The term \fIpattern\fR has been used in two ways in PEARL.
        !          2927: It has been used previously in this documentation in
        !          2928: a specialized sense which is only relevant in the context
        !          2929: of creating a \fIpattern\fR.
        !          2930: The use of the \fIpattern\fR selector to \fIcreate\fR is simply a
        !          2931: variation on \fIcreate individual\fR which uses the match-anything
        !          2932: variable ?*any* as the default for unspecified slots instead
        !          2933: of the usual default values (either the one inherited from the
        !          2934: base definition or the default for the type of slot).
        !          2935: It is called creating a \fIpattern\fR because the
        !          2936: change of default is usually only useful for constructing a pattern.
        !          2937: .PP
        !          2938: However, the use of the function \fIcreate\fR with object
        !          2939: selector \fIpattern\fR is \fBnot\fR the only way to create a
        !          2940: pattern which can be matched;
        !          2941: in fact, it is only useful for
        !          2942: forming simple patterns.
        !          2943: \fBAny\fR individual structure in PEARL can be used as a pattern.
        !          2944: If a fully specified structure (that is, one with an actual value
        !          2945: in all of its slots) is used as a pattern for fetching, it will
        !          2946: only match objects which are equal to it in a manner similar to
        !          2947: \fIequal\fR (versus \fIeq\fR) in Lisp.
        !          2948: (An exception to this occurs when patterns with pattern-matching
        !          2949: variables are stored in the data base.)
        !          2950: Thus a fully specified pattern is only useful for
        !          2951: determining whether a particular fact (object) is in the data base.
        !          2952: Any object is a pattern but the interesting patterns will not
        !          2953: be fully specified;
        !          2954: rather, they will have unspecified slots
        !          2955: which contain pattern-matching variables instead of values.
        !          2956: The details of the matching process will now be described.
        !          2957: .NH 2
        !          2958: The Matching Process
        !          2959: .PP
        !          2960: In general, the matching procedure takes two structures and either,
        !          2961: neither or both may contain pattern-matching variables.
        !          2962: So conceptually, both are patterns.
        !          2963: If the structures are not definitionally the same type
        !          2964: then the match fails automatically.
        !          2965: Otherwise, each structure is viewed as a sequence of slots
        !          2966: which are successively "matched" between the two structures.
        !          2967: Two structures of the same type match if and only if each of
        !          2968: their slots "matches" the corresponding slot of the other structure.
        !          2969: Each slot is of one of four types (\fIstruct\fR, \fIsymbol\fR, \fIint\fR,
        !          2970: or \fIlisp\fR), or is a \fIsetof\fR one of these types.
        !          2971: Regardless of its type, each slot is filled in one of four ways:
        !          2972: .IP (1)
        !          2973: The slot may contain an actual value of its type (for example,
        !          2974: a slot of type \fIstruct\fR may contain a PTrans).
        !          2975: .IP (2)
        !          2976: The slot may contain a variable which is local to the structure
        !          2977: (pattern-matching variables are local unless otherwise specified).
        !          2978: .IP (3)
        !          2979: The slot may contain a global variable, declared previously by a
        !          2980: call to the function \fIglobal\fR with the variable's name as argument.
        !          2981: .IP (4)
        !          2982: The slot may contain the special match-anything variable ?*any*.
        !          2983: .LP
        !          2984: If the slot contains a variable (other than ?*any*) which has not
        !          2985: been bound then it may become bound as a side effect of the
        !          2986: matching process.
        !          2987: All local pattern-matching variables are unbound at the start
        !          2988: of the matching process.
        !          2989: When a local variable is bound to a real
        !          2990: value during the matching process (it will never be bound to a
        !          2991: variable), it will not be unbound again but for the purposes of
        !          2992: matching will be treated as if the slot were filled with that value.
        !          2993: .PP
        !          2994: Let us now examine each of the pairings of slot values
        !          2995: which may occur and how they are matched.
        !          2996: If either of the two slots being matched contains the
        !          2997: special variable ?*any*, then the slots match by definition,
        !          2998: regardless of the contents of the other slot.
        !          2999: If both slots contain variables that are unbound, the slots
        !          3000: do not normally match, (even if the two variables are textually
        !          3001: the same name).
        !          3002: (Since some users want two unbound variables to match,
        !          3003: the value to be returned in this case is stored in the
        !          3004: special variable \fB*matchunboundsresult*\fR whose
        !          3005: initial value is \fInil\fR.
        !          3006: Setting this variable to non-\fInil\fR will cause two unbound
        !          3007: variables to match immediately but will not cause their
        !          3008: predicates to be run.)
        !          3009: If one slot contains an unbound variable (and the other
        !          3010: a bound variable or a value), then the predicates and
        !          3011: restrictions of the slot with the unbound variable are
        !          3012: tested, and hooks on that slot labelled
        !          3013: with \fImatch\fR are run to see if the unbound variable
        !          3014: should be bound to the bound value.
        !          3015: If so, then the unbound variable is bound to the value
        !          3016: of the other slot, and the two slots match.
        !          3017: Note that only the predicates and hooks on the
        !          3018: structure containing the unbound variable are run while
        !          3019: the symbols *, **, and =<slotname> refer to the other
        !          3020: structure (with the bound value in it).
        !          3021: If the predicates or restrictions return \fInil\fR,
        !          3022: the two slots do not match, the variable
        !          3023: is not bound, and the entire match fails.
        !          3024: .PP
        !          3025: If both slots contain either bound variables or values, then the values
        !          3026: of the two slots are compared.  If the slot is of type \fIstruct\fR,
        !          3027: then the entire matching algorithm is recursively applied.
        !          3028: If the slot is of types \fIint\fR or \fIlisp\fR,
        !          3029: then \fIequal\fR is used.
        !          3030: If the type is \fIsymbol\fR, then the two values must
        !          3031: be the same symbol.
        !          3032: Regardless of the type, restrictions associated with the slot
        !          3033: are executed until one fails or there are no more to run.
        !          3034: All must succeed for the match to succeed.
        !          3035: If the match succeeds, then any hooks
        !          3036: with the label \fImatch\fR are run.
        !          3037: .PP
        !          3038: The difference between the two types of variables is one of scope.
        !          3039: Normal variables (for PEARL) do not need to be declared, and
        !          3040: may be used in any structure by typing in \fI?<var>\fR during a
        !          3041: \fIcreate\fR (note that \fIputpath\fR is incapable of
        !          3042: installing variables).
        !          3043: The scope of these variables is only over the structure
        !          3044: in which they are typed.
        !          3045: Thus the variable \fI?V\fR typed into two different creations of
        !          3046: structures are in no way connected (in the same manner as two
        !          3047: local variables V in different Pascal subroutines are unrelated.)
        !          3048: If one becomes bound, the other is unaffected.
        !          3049: On the other hand, if a variable name is previously declared
        !          3050: as \fBglobal\fR:
        !          3051: .DS
        !          3052: (global  G)
        !          3053: .DE
        !          3054: then all instances of the variable name ?G are the same
        !          3055: (similar to global variables in Pascal).
        !          3056: The list of global variables is kept in the special variable \fB*globallist*\fR.
        !          3057: .PP
        !          3058: As mentioned before, when two structures are matched, all
        !          3059: normal (local) variables in both structures are unbound
        !          3060: (bound to the value \fI*pearlunbound*\fR) before any
        !          3061: slots are compared.
        !          3062: This is to ensure that any bindings induced by a previous
        !          3063: unsuccessful (or successful for that matter) match are removed.
        !          3064: This rule is useful because the type of matching that
        !          3065: early PEARL users have needed is in matching most
        !          3066: patterns against fully-specified values (that is, cases
        !          3067: in which one slot is always bound and the other either
        !          3068: bound or unbound).
        !          3069: Global variables are \fBnot\fR unbound before each match,
        !          3070: so they can be used to reflect global contexts.
        !          3071: They are given the value *\fIpearlunbound*\fR at the
        !          3072: time they are declared and remain bound thereafter unless
        !          3073: explicitly unbound by the user.
        !          3074: To unbind a global variable, you may use use the function
        !          3075: \fBunbind\fR, a fexpr which requires
        !          3076: the name of a (previously declared) global variable:
        !          3077: .DS
        !          3078: (unbind  G)
        !          3079: .DE
        !          3080: or use \fIsetq\fR and the function \fBpunbound\fR which
        !          3081: simply returns the atom \fI*pearlunbound*\fR:
        !          3082: .DS
        !          3083: (setq  G  (punbound) )
        !          3084: .DE
        !          3085: The function \fBpboundp\fR will test the value of a Lisp
        !          3086: (not PEARL) variable to see if it is \fI*pearlunbound*\fR.
        !          3087: The function \fBglobalp\fR will determine whether the variable
        !          3088: passed to it has been declared global.
        !          3089: .PP
        !          3090: Global variables should be used with care so that
        !          3091: they are not set by unsuccessful matches.
        !          3092: Generally this is achieved by first collecting the value
        !          3093: desired into a local variable via a series of matches
        !          3094: (only the last of which succeed), and then using the result of
        !          3095: this success to cause a further action which is guaranteed to
        !          3096: correctly bind the value of the global variable.
        !          3097: (These actions may be hooks which rebind the global
        !          3098: variable every time the local one is bound.
        !          3099: Effectively, this is a way to say \fIalways unbind this particular
        !          3100: global variable before matches\fR.
        !          3101: The action also could be performed by the user's program
        !          3102: when the right value is found.)
        !          3103: .PP
        !          3104: Each structure or tree of structures built by a call to \fIcreate\fR
        !          3105: constructs an individual assoc(association)-list of all the local
        !          3106: variables in that structure.
        !          3107: This assoc-list is stored with the root of the tree, thus
        !          3108: achieving local uniqueness of variables within a structure.
        !          3109: Global variables are bound values of the Lisp atom of
        !          3110: the same name and are accessed in the usual way.
        !          3111: To access the value of a local variable in a structure,
        !          3112: one uses either the function \fBvalueof\fR (which is an expr)
        !          3113: or the fexpr \fBvarvalue\fR both of which have two
        !          3114: arguments: the name of the variable whose value
        !          3115: you want and the structure it occurs in (evaluated internally by
        !          3116: \fIvarvalue\fR).
        !          3117: For example, to get the value of ?G in X, use either of:
        !          3118: .DS
        !          3119: (valueof  'G  X)
        !          3120: (varvalue  G  X)
        !          3121: .DE
        !          3122: Thus PEARL uses both deep and shallow binding.
        !          3123: .PP
        !          3124: The match algorithm is available to the user as a
        !          3125: separate function by the name \fBstandardmatch\fR.
        !          3126: This function unbinds all local variables before
        !          3127: proceeding with the match (using the macro \fBunbindvars\fR)
        !          3128: and again afterwards if the match failed.
        !          3129: A function which assumes that all local variables have been
        !          3130: unbound already and proceeds just as \fIstandardmatch\fR
        !          3131: would is \fBbasicmatch\fR.
        !          3132: The function name used to access the matching function by
        !          3133: \fInextitem\fR and all other built-in PEARL functions is
        !          3134: \fBmatch\fR which is normally given the same function definition
        !          3135: as \fIstandardmatch\fR but can be bound to whichever match function
        !          3136: you wish.
        !          3137: A function which compares two structures for equality without
        !          3138: affecting the values of their variables is available as
        !          3139: \fBstrequal\fR.
        !          3140: Since it does not bind variables, it also does not execute
        !          3141: predicates although it does run base hooks and slot hooks labelled
        !          3142: with \fIstrequal\fR.
        !          3143: A function parallel to \fInextitem\fR which uses \fIstrequal\fR
        !          3144: instead of \fImatch\fR is available as \fBnextequal\fR.
        !          3145: .PP
        !          3146: This rest of this section covers other ways to access and affect
        !          3147: the values of variables.
        !          3148: It will make more sense after reading the next section on blocks
        !          3149: but fits in better here so you should probably leave it for your
        !          3150: second reading.
        !          3151: .PP
        !          3152: Recall that the question mark read macro expands into either
        !          3153: \fI(*var* <varname>)\fR or \fI(*global* <varname>)\fR.
        !          3154: These two forms are not normally meant to be evaluated.
        !          3155: However, for convenience, there are two functions \fB*var*\fR and
        !          3156: \fB*global*\fR which return the value of the variable whose name
        !          3157: is their argument.
        !          3158: That is, if \fI?X\fR expands into \fI(*global* X)\fR, executing it
        !          3159: will returned the value of the atom X.
        !          3160: Thus \fIX\fR and \fI?X\fR are equivalent for a global variable.
        !          3161: For a local or lexically scoped variable, in which \fI?X\fR
        !          3162: expands into \fI(*var* X), the function \fI*var*\fR looks in
        !          3163: three places for a variable with the name \fIX\fR.
        !          3164: .IP 1.
        !          3165: First it looks to see if the special variable
        !          3166: \fB*currentstructure*\fR has been bound to a structure by
        !          3167: the user, and if so, looks in its variable list.
        !          3168: .IP 2.
        !          3169: If this fails, it looks in the special variable
        !          3170: \fB*currentpearlstructure*\fR for a structure.
        !          3171: This variable is set by various PEARL functions like
        !          3172: \fIcreate\fR, \fIfetch\fR, \fIpath\fR, and \fInextitem\fR
        !          3173: to the top level structure they last operated on.
        !          3174: .IP 3.
        !          3175: If this fails, it looks in the currently open block on
        !          3176: top of \fI*blockstack*\fR if there is one.
        !          3177: .IP 4.
        !          3178: If this fails, it returns \fInil\fR.
        !          3179: .LP
        !          3180: Note that the atom \fI*currentstructure*\fR is there simply for
        !          3181: the use of the user and is never set by PEARL.
        !          3182: .PP
        !          3183: A related function is \fBsetv\fR which takes a question-mark
        !          3184: variable, a value and an optional environment and sets that
        !          3185: variable in that environment or else in the default environment
        !          3186: described above to that value.
        !          3187: The environment can be either a structure or a block.
        !          3188: This stops with an error message if it fails to find a variable 
        !          3189: by that name in the specified or default environment.
        !          3190: .NH
        !          3191: Binding Blocks of Structures Together Via Common Variables
        !          3192: .PP
        !          3193: It is sometimes the case that you wish to create a group of
        !          3194: structures which are closely related in some way and which you
        !          3195: wish to tie together via pattern-matching variables.
        !          3196: For example, a \fIframe\fR might be considered such a loosely
        !          3197: connected group of structures.
        !          3198: In this case what is desired is for the pattern-matching variables
        !          3199: to \fIactually be the same\fR.
        !          3200: Normally however, if you create several structures in PEARL with
        !          3201: variables having the same name, each has its own local variable
        !          3202: with that name and they are totally unrelated.
        !          3203: If on the other hand, you declared them to be global, then all
        !          3204: structures having variables with that name would refer to the same
        !          3205: variable and it would no be unbound before matching.
        !          3206: For this purpose, PEARL provides variables of an intermediate
        !          3207: nature which are local to only a small group of structures and
        !          3208: which are all unbound before any one of the structures takes
        !          3209: parting in matching.
        !          3210: .PP
        !          3211: These variables are called \fBlexically scoped\fR (although if
        !          3212: the related functions \fIblock\fR and \fIendblock\fR are called
        !          3213: dynamically, they also provide a breed of dynamic scoping).
        !          3214: To declare a set of lexically-scoped variables, thus opening a
        !          3215: (nested) scope for them, use the function \fBblock\fR,
        !          3216: so named because of the similarity to the concept of a block
        !          3217: in Algol-like languages.
        !          3218: The function \fIblock\fR is a fexpr which in its simplest form
        !          3219: expects one argument which should be a list of new variables:
        !          3220: .DS
        !          3221: (block  (A  B  C))
        !          3222: .DE
        !          3223: Such a call to \fIblock\fR creates an unnamed block containing
        !          3224: these variables and any occurrences of variables with these
        !          3225: names in any structures \fIcreated\fR after this call will
        !          3226: refer to these lexically-scoped variables.
        !          3227: Thus, no structure created after the above call to \fIblock\fR
        !          3228: can contain a local variable called A, B, or C.
        !          3229: (However, if a variable has been previously declared to be global
        !          3230: this overrides \fBall\fR future declarations with \fIblock\fR.
        !          3231: Once again, global pattern-matching variables are to be
        !          3232: used with \fIextreme caution\fR.)
        !          3233: .PP
        !          3234: If you use several blocks, especially nested blocks,
        !          3235: it is helpful to give them names.
        !          3236: For this purpose, \fIblock\fR will accept two arguments, the first
        !          3237: an atom to name the block and the second the list of new variables.
        !          3238: For example:
        !          3239: .DS
        !          3240: (block  Name  (A  B  C))
        !          3241: .DE
        !          3242: .PP
        !          3243: To end the most recent block, use the fexpr \fBendblock\fR.
        !          3244: This function accepts any of three types of arguments.
        !          3245: If last block was unnamed, simply use:
        !          3246: .DS
        !          3247: (endblock)
        !          3248: .DE
        !          3249: If the last block was named, you must provide \fIendblock\fR
        !          3250: with this name:
        !          3251: .DS
        !          3252: (endblock  Name)
        !          3253: .DE
        !          3254: This is provided as a protection against unbalanced calls to
        !          3255: \fIblock\fR and \fIendblock\fR.
        !          3256: If you wish to end the most recent block, regardless of what
        !          3257: its name is, use
        !          3258: .DS
        !          3259: (endblock  *)
        !          3260: .DE
        !          3261: To end several blocks at once, you can use the fexpr
        !          3262: \fBendanyblocks\fR which ends all blocks back through
        !          3263: the one whose name matches its argument.
        !          3264: Again no argument (\fInil\fR) means the last unnamed block.
        !          3265: An argument of \fB"*"\fR causes PEARL to end all currently
        !          3266: open blocks.
        !          3267: A shorthand for \fI(endanyblocks *)\fR is \fB(endallblocks)\fR.
        !          3268: .PP
        !          3269: The function \fIblock\fR builds an assoc-list of
        !          3270: the variables listed.
        !          3271: If the block is nested, the assoc-list of the enclosing block is
        !          3272: hooked to the end of its assoc-list, thus providing a complete
        !          3273: assoc-list of all the variables available in the block.
        !          3274: A side effect of \fIblock\fR is that this assoc-list is bound to
        !          3275: the name of the block.
        !          3276: The block itself (the block's name plus this assoc-list) is available
        !          3277: as \fIb:<blockname>\fR so that the above call to block binds
        !          3278: \fIName\fR to
        !          3279: .DS L
        !          3280: ((A  .  *pearlunbound*)  (B  .  *pearlunbound*)  (C  .  *pearlunbound*))
        !          3281: .DE
        !          3282: and \fIb:Name\fR to
        !          3283: .DS
        !          3284: (Name  (A  .  *pearlunbound*)  (B  .  *pearlunbound*)
        !          3285:        (C  .  *pearlunbound*))
        !          3286: .DE
        !          3287: If a block is unnamed, PEARL calls it \fIunnamedblock\fR and the
        !          3288: corresponding variables are set.
        !          3289: The special variable \fB*blockstack*\fR contains a stack of all the
        !          3290: currently active blocks.
        !          3291: The effect of ending a block is to pop it off this stack.
        !          3292: Once a block is closed, it is still accessible through the Lisp
        !          3293: variable \fIb:<blockname>\fR.
        !          3294: Given the name of a block, the function \fBblockatom\fR will build
        !          3295: this atom for you.
        !          3296: .PP
        !          3297: It is possible to return to the scope of an earlier block with the
        !          3298: fexpr \fBsetblock\fR which expects the name of a named block.
        !          3299: This will have the effect of ending all currently open blocks and
        !          3300: setting the current block stack to contain this block.
        !          3301: Note that this block will contain all the variables of any blocks
        !          3302: it is nested in but that it is not possible to close off these
        !          3303: block selectively.
        !          3304: Thus, the block stack will contain only one block with all the
        !          3305: variables in its complete assoc-list.
        !          3306: .NH
        !          3307: Controlling the Unbinding of Variables by Match
        !          3308: .PP
        !          3309: It is sometimes desireable to use the filled-in result pattern
        !          3310: of a \fIfetch\fR or \fImatch\fR as a pattern for a further
        !          3311: \fIfetch\fR (or \fImatch\fR) or to otherwise store and restore
        !          3312: the current values of variables (for example, to allow
        !          3313: backtracking algorithms and/or hypothetical assertions).
        !          3314: Since all bound local variables would normally be unbound during this
        !          3315: further fetching or matching, this would not be possible given the
        !          3316: mechanism described so far.
        !          3317: To accomplish this action, which can be considered as "pushing"
        !          3318: the context of the current assoc-list,
        !          3319: you should use one of several functions provided for this purpose.
        !          3320: The function \fBfreezebindings\fR takes a structure as argument
        !          3321: and moves all bound variables from its normal assoc-list to a
        !          3322: backup so that \fIfetch\fR will not unbind them.
        !          3323: The function \fBthawbindings\fR takes a structure as argument and
        !          3324: will undo this action, restoring the assoc-list to its complete state.
        !          3325: These two functions affect the structure plus any bound variables
        !          3326: in all enclosing blocks.
        !          3327: To freeze or thaw only a single structure, use \fBfreezestruct\fR
        !          3328: and \fBthawstruct\fR.
        !          3329: To freeze or thaw only a single block, use \fBfreezeblock\fR
        !          3330: and \fBthawblock\fR which expect the name of a block as an
        !          3331: argument.
        !          3332: .PP
        !          3333: Above it was mentioned that two structures will match if
        !          3334: and only if they both are of the same type.
        !          3335: Actually the system has been extended to allow the matching
        !          3336: of a structure of one type with another of a type derived
        !          3337: from the first via a \fIcreate expanded\fR.
        !          3338: The extra slots of the larger (expanded)
        !          3339: structure are ignored during the match.
        !          3340: .PP
        !          3341: Lastly it should be mentioned that the matching rules are
        !          3342: an evolving system, and may be amended as experience
        !          3343: with their use is accumulated.
        !          3344: The rules may seem a bit complex at first, but in use they
        !          3345: are fairly natural.
        !          3346: The rules are biased towards efficiency (like much of PEARL).
        !          3347: The designers felt that hiding exponential time-complexity
        !          3348: processing within the language would lead users to
        !          3349: construct inefficient programs without realizing it.
        !          3350: Thus several "features" of other complex AI matchers are not built in.
        !          3351: The user must implement these individually at a higher level.
        !          3352: It has been our experience that this leads to much cleaner designs.
        !          3353: .NH
        !          3354: Function Structures
        !          3355: .PP
        !          3356: In using PEARL, it is sometimes handy to escape into Lisp in
        !          3357: a "\fIstructure\fRd" way.
        !          3358: Although PEARL allows ad hoc escapes by way of its hooks
        !          3359: and the ! and $ evaluation operators defined above,
        !          3360: the philosophy in PEARL \fBfunction structures\fR
        !          3361: is to allow structured escapes that restrict the generality
        !          3362: of the escape to the minimum necessary for the task.
        !          3363: At times you may wish to equate Lisp functions with their expected
        !          3364: arguments with PEARL structures with their associated slots.
        !          3365: For example while you may wish to describe an action in a program
        !          3366: as fetching an item from the data base, you may actually be
        !          3367: unable to describe the item as a structure and/or be unable or
        !          3368: unwilling to actually store it in the data base.
        !          3369: Instead, you will sometimes want the value to be provided by
        !          3370: a function called at fetching time instead of a structure in the
        !          3371: data base.
        !          3372: .PP
        !          3373: Take as an example the case of keeping track of whether any two
        !          3374: objects are near each other.
        !          3375: One possible way to do this is to keep structures in the data base
        !          3376: which record for each pair of objects that are near each other the
        !          3377: fact that they are near each other:
        !          3378: .DS
        !          3379: (create base  Near
        !          3380:        (Object1  struct)
        !          3381:        (Object2  struct))
        !          3382: .DE
        !          3383: Then determining whether two objects are near each other would
        !          3384: require a simple fetch.
        !          3385: However, if you are dealing with a large number of objects which
        !          3386: are moving around quite a bit but only want to know about nearness
        !          3387: once in a while, it might be easier or more efficient to compute
        !          3388: whether two objects are near each other only on demand.
        !          3389: In this case, you might like to write a function called Near
        !          3390: which expects two arguments.
        !          3391: However, for consistency, you may not want to design your program
        !          3392: so that it knows what things can be fetched and what things need
        !          3393: computing.
        !          3394: So you would like to define a structure which looks like our
        !          3395: definition of Near above but which actually invokes the
        !          3396: function Near.
        !          3397: .PP
        !          3398: To do this, one may create the function Near (which must be an
        !          3399: expr) and also a structure of type \fIfunction\fR named Near:
        !          3400: .DS
        !          3401: (de Near  (x  y)
        !          3402:     ... mechanism to actually determine nearness ... )
        !          3403: 
        !          3404: (create function  Near
        !          3405:        (Object1  struct)
        !          3406:        (Object2  struct))
        !          3407: .DE
        !          3408: and then can create an individual of it for fetching:
        !          3409: .DS
        !          3410: (create individual  Near  IsNear
        !          3411:        (Object1  John)
        !          3412:        (Object2  Office))
        !          3413: 
        !          3414: (fetch  IsNear)
        !          3415: .DE
        !          3416: Note that the format of function structures within PEARL
        !          3417: is the same as that of structures.
        !          3418: However, the name of the actual Lisp function to be called must
        !          3419: match the type name of the \fIfunction\fR structure, and the
        !          3420: arguments must occur in the same order and be of the same types
        !          3421: as the slots which will contain the actual arguments to the function.
        !          3422: .PP
        !          3423: As another simple example, to define a \fIfunction\fR structure
        !          3424: to correspond to the function \fIgetpath\fR, we would use the following:
        !          3425: .DS
        !          3426: (create function  getpath
        !          3427:        (Item  struct)
        !          3428:        (Path  lisp) )
        !          3429: .DE
        !          3430: and then an actual instance:
        !          3431: .DS
        !          3432: (create individual  getpath  Minst
        !          3433:        (Item  !  Mtrans1)
        !          3434:        (Path  '(MObject) ) )
        !          3435: .DE
        !          3436: This example is not too useful.
        !          3437: As a more realistic use, consider a program to return all
        !          3438: the MObjects of all MTranses that are in the data base:
        !          3439: .DS
        !          3440: (create function  nextitem
        !          3441:        (Stream  lisp) )
        !          3442: .DE
        !          3443: .DS
        !          3444: (create pattern  MTrans  MPat1
        !          3445:        (MObject  ?X) )
        !          3446: .DE
        !          3447: .DS
        !          3448: (global  MStream)
        !          3449: (setq  MStream  (fetch  MPat1) )
        !          3450: .DE
        !          3451: .DS
        !          3452: (create individual  getpath  Minst2
        !          3453:        (Item  (nextitem  (Stream  ?MStream) ) )
        !          3454:        (Path  '(MObject) )
        !          3455: .DE
        !          3456: .DS
        !          3457: (setq  Stream1  (fetch  Minst2) )
        !          3458: .DE
        !          3459: Note the recursive use of the data base: the \fIfetch\fR of
        !          3460: Minst2 will cause a \fIgetpath\fR to be executed.
        !          3461: But PEARL must first get the two arguments to pass on to
        !          3462: \fIgetpath\fR which causes the function \fInextitem\fR
        !          3463: to be evaluated, getting the next MTrans in MStream to
        !          3464: pass to \fIgetpath\fR. 
        !          3465: .PP
        !          3466: Thus, function structures provide a way to describe a function and
        !          3467: its arguments through a PEARL structure and then to include,
        !          3468: in a pattern to fetch or in a structure slot,
        !          3469: a function call which will provide the desired value
        !          3470: at fetching time.
        !          3471: However, this only works during fetching.
        !          3472: .PP
        !          3473: The function used by PEARL to execute a function
        !          3474: structure is \fBevalfcn\fR.
        !          3475: It takes an item as its argument and returns the result of
        !          3476: applying the associated expr to its slot values if the item
        !          3477: is a function structure.
        !          3478: If the item is a single structure it returns the item untouched.
        !          3479: If the item is a list of structures, it applies itself
        !          3480: recursively with \fImapcar\fR.
        !          3481: No other PEARL functions currently know about function structures
        !          3482: as being any different than other individual structures.
        !          3483: .NH
        !          3484: More About the PEARL Top Level Loop and History Mechanism
        !          3485: .PP
        !          3486: The PEARL prompt-read-eval-print loop includes two features which
        !          3487: make PEARL easier to work with than the usual top level of Lisp.
        !          3488: Both features were designed in imitation of the Berkeley Unix
        !          3489: shell program \fIcsh\fR.
        !          3490: .PP
        !          3491: The first is an aliasing mechanism which provides the ability to
        !          3492: use various atoms as aliases for commonly executed s-expressions.
        !          3493: If you type an atom to the top level and it has the property
        !          3494: \fBalias\fR, the value of its \fIalias\fR property will be
        !          3495: evaluated instead.
        !          3496: Thus, if you do a
        !          3497: .DS
        !          3498: (putprop  'dir  '(dir)  'alias)  ; in UCI Lisp
        !          3499:          or
        !          3500: (putprop  'ls  '(exec  ls)  'alias)  ; in Franz Lisp
        !          3501: .DE
        !          3502: then if you type the atom \fIdir\fR or \fIls\fR repectively
        !          3503: to the top level, you will get the contents of your
        !          3504: directory printed out.
        !          3505: Two such built-in atoms are \fBhistory\fR which will
        !          3506: run the function \fIhistory\fR and print out your last
        !          3507: 64 commands (see below) and \fBh\fR which will print the last 22
        !          3508: commands (one crt screenful).
        !          3509: The aliasing mechanism can be turned off (saving a \fIget\fR for
        !          3510: each atom you use at the top level) by setting the special
        !          3511: variable \fB*usealiases*\fR to \fInil\fR.
        !          3512: .PP
        !          3513: PEARL's top level also includes a simplified command-history mechanism.
        !          3514: As you type in expressions to the top level of PEARL, they are
        !          3515: stored away for future reference.
        !          3516: The results of evaluating each expression are also kept.
        !          3517: The commands and their results are kept in two hunks
        !          3518: whose default size is 64.
        !          3519: The hunk containing the commands is kept in the special
        !          3520: variable \fB*history*\fR and the hunk containing the results
        !          3521: is kept in the special variable \fB*histval*\fR
        !          3522: To change the number of commands remembered, set the special
        !          3523: variable \fB*historysize*\fR to something other than 64
        !          3524: in your \fI.init.prl\fR.
        !          3525: It cannot be changed later.
        !          3526: (If you are a novice user of PEARL, we recommend that you not
        !          3527: change it to be smaller, since the history command can sometimes
        !          3528: be helpful to someone helping you to debug something after you
        !          3529: have fiddled with it a while.)
        !          3530: .PP
        !          3531: The commands you type are squirrelled away so that you can ask
        !          3532: PEARL to re-execute them, thus saving the pain of retyping
        !          3533: a complicated expression.
        !          3534: To access the previous commands, the readmacro \fB"!"\fR is
        !          3535: provided.
        !          3536: To access the results of the previous commands,
        !          3537: the readmacro \fB"$"\fR is provided.
        !          3538: (The exclamation point is in imitation of the cshell;
        !          3539: the dollar sign is meant to suggest "value".)
        !          3540: These readmacros peek at the next character to determine what to do.
        !          3541: We discuss the variations available on these two readmacros in
        !          3542: parallel, since many of them coincide.
        !          3543: .PP
        !          3544: The simplest and most useful forms are \fB"!!"\fR and \fB"$$"\fR
        !          3545: which effectively re-execute and reprint the last command or its result.
        !          3546: Actually, both forms are executed, but the dollard sign macro
        !          3547: always returns its value quoted so that its effect is usually to
        !          3548: just reprint the result of the previous command.
        !          3549: Note that since these are readmacros which simply return the
        !          3550: last s-expression typed or its value, you can use them to build up
        !          3551: more complex commands.
        !          3552: For example:
        !          3553: .DS
        !          3554: pearl>  (fetch  Item)
        !          3555:     (*stream:*  . . .)
        !          3556: pearl>  (nextitem  !!)
        !          3557: .DE
        !          3558: will cause the fetch to be repeated and then do a \fInextitem\fR on it.
        !          3559: However, it is much more efficient to use the \fI$$\fR form in
        !          3560: this case, since what you really want is to do a \fInextitem\fR
        !          3561: on the result of the \fIfetch\fR in the last command:
        !          3562: .DS
        !          3563: pearl>  (fetch  Item)
        !          3564:     (*stream:*  . . .)
        !          3565: pearl>  (nextitem  $$)
        !          3566: .DE
        !          3567: .PP
        !          3568: The commands are numbered as you type them, starting with zero.
        !          3569: Although the values wrap around in the hunks, the \fIhistory number\fR
        !          3570: continues to climb.
        !          3571: The current history number is available in the special
        !          3572: variable \fB*historynumber*\fR.
        !          3573: To access a particular command or its value, you may type you may
        !          3574: follow an exclamation point or dollar sign with the number of the
        !          3575: command.
        !          3576: Thus \fB!23\fR and \fB$23\fR are the 23rd command and its result.
        !          3577: If you don't remember the command's number you can use the
        !          3578: function name or a prefix of it.
        !          3579: Thus \fB!fetch\fR and \fB$fetch\fR will access the last \fIfetch\fR
        !          3580: or its value.
        !          3581: Or \fB!fe\fR and \fB$fe\fR will access the last command starting
        !          3582: with \fIfe\fR or its value.
        !          3583: If there was a reference to an atom (instead of a list) with that
        !          3584: name or with that as a prefix somewhere, then the atom will be
        !          3585: evaluated again.
        !          3586: For exclamation point, this is a waste of typing except for long
        !          3587: atom names.
        !          3588: For dollar sign, it provides you a way of recovering the value of
        !          3589: a variable that has since changed.
        !          3590: (As a side effect of implementing this, PEARL contains a function
        !          3591: \fBprefix\fR which expects two lists and determines whether the
        !          3592: first is a prefix of the second, considered as a list of atoms.
        !          3593: Thus, PEARL just calls \fIprefix\fR on the results of \fIexplode\fRing
        !          3594: two atoms.)
        !          3595: .PP
        !          3596: Here the parallel between the two macros ends.
        !          3597: .PP
        !          3598: There are five forms which work only with exclamation point and
        !          3599: refer only to the last s-expression typed.
        !          3600: They are essentially ways to pick individual top-level elements
        !          3601: out of the last command:
        !          3602: .DS
        !          3603: \fB!^\fR       the first argument
        !          3604: \fB!$\fR       the last argument
        !          3605: \fB!*\fR       the complete set of arguments
        !          3606: \fB!:0\fR      the function name
        !          3607: \fB!:n\fR      the nth argument
        !          3608: .DE
        !          3609: Both macros are splicing macros so that their values may be
        !          3610: spliced into the current s-expression.
        !          3611: \fB!*\fR is designed so that the following will work:
        !          3612: .DS
        !          3613: pearl>  (add  1  2  3  4)
        !          3614:     10
        !          3615: pearl>  (times  !*)
        !          3616: (times  1  2  3  4)
        !          3617:     24
        !          3618: .DE
        !          3619: .PP
        !          3620: To see the last 64 commands you gave printed out, use the function
        !          3621: \fBhistory\fR (or type the atom \fBhistory\fR).
        !          3622: If you don't want all 64 commands, \fIhistory\fR will accept an
        !          3623: integer argument telling how many you want.
        !          3624: Thus the aliases on \fIhistory\fR and \fIh\fR are:
        !          3625: .DS
        !          3626: (putprop  'history  '(history)  'alias)
        !          3627: (putprop  'h  '(history  22)  'alias)
        !          3628: .DE
        !          3629: If you use the command numbers often, you might like to have the
        !          3630: history number printed out before each command.
        !          3631: To have the history number printed just before the PEARL prompt,
        !          3632: set the special variable \fB*printhistorynumber*\fR to a
        !          3633: non-\fInil\fR value.
        !          3634: The default value is f\Inilf\R.
        !          3635: .PP
        !          3636: Whenever you use the ! or $ history mechanisms, the line you type in
        !          3637: will be reprinted in its expanded form on the next line using
        !          3638: the current \fIpearlprintfn\fR.
        !          3639: If you wish to modify your own read macros so that they also will
        !          3640: cause this reprinting, simply have them set the special
        !          3641: variable \fB*readlinechanged*\fR to a non-\fInil\fR value.
        !          3642: .PP
        !          3643: It is sometimes useful to have a function return no value.
        !          3644: That is, you often do not want the value of the function to be
        !          3645: printed by the top level loop.
        !          3646: In particular, functions which print values often return ugly
        !          3647: values afterward.
        !          3648: To get around this problem, the PEARL top level disables printing
        !          3649: of the value returned by a function if it returns the atom
        !          3650: \fB*invisible*\fR.
        !          3651: All of the PEARL print functions return this value.
        !          3652: .PP
        !          3653: It is sometimes useful to be able to save the current state of a
        !          3654: PEARL run for later.
        !          3655: There are two functions to allow this.
        !          3656: If you wish to save a version which will continue exactly where
        !          3657: you left off (at the top level), use the function
        !          3658: \fBsavecontinue\fR which expects zero, one or two arguments.
        !          3659: If you wish to save a version which will read in
        !          3660: the \fI.start.prl\fR file when it starts up, use \fBsavefresh\fR.
        !          3661: (If you also want \fI.init.prl\fR read in, change the value of the
        !          3662: special variable \fB*firststartup*\fR to \fIt\fR beforehand but
        !          3663: be careful not to put functions which may only be run once in it.)
        !          3664: Note however that you cannot save Franz PEARL on top of the file
        !          3665: you are running;
        !          3666: trying to will result in the \fIDumplisp failed\fR
        !          3667: error message from Franz Lisp.
        !          3668: Note also that a saved PEARL uses about 1500 blocks or 750kbytes on
        !          3669: the disk so this should be used sparingly.
        !          3670: (Exceeding the disk quota will result in the same error message.)
        !          3671: In the Franz Lisp version, if the number of arguments to either of
        !          3672: these functions is:
        !          3673: .IP 0:
        !          3674: It will be saved as \fIpearl\fR in the current directory.
        !          3675: .IP 1:
        !          3676: The argument is assumed to be a (relative) file name to save under.
        !          3677: .IP 2:
        !          3678: The result of concatenating the two arguments together with a
        !          3679: \fB/\fR between them will be the file name used.
        !          3680: (This is for UCI Lisp compatibility.)
        !          3681: .LP
        !          3682: In the UCI Lisp version, if the number of arguments is:
        !          3683: .IP 0:
        !          3684: It will be saved as \fIpearl\fR in the current directory.
        !          3685: .IP 1:
        !          3686: The argument is assumed to be a file name for the current directory.
        !          3687: .IP 2:
        !          3688: They must be a directory and a file name to save in.
        !          3689: .NH
        !          3690: Looping and Copying Functions
        !          3691: .PP
        !          3692: PEARL includes several loop macros.
        !          3693: The first two were included simply for use by the implementation but
        !          3694: might be useful to the user.
        !          3695: They are the \fBfor\fR and \fBwhile\fR macros which both expand
        !          3696: into a \fIprog\fR wrapped around a \fIprogn\fR.
        !          3697: A call to the \fIwhile\fR macro should be of the form:
        !          3698: .DS
        !          3699: (while <test>
        !          3700:        EXPR1
        !          3701:        EXPR2
        !          3702:        ...
        !          3703:        EXPRn)
        !          3704: .DE
        !          3705: The <test> is evaluated before each execution of the loop.
        !          3706: If it is non-\fInil\fR, the EXPRi are evaluated in sequence.
        !          3707: This continues until <test> return nil in which case the last
        !          3708: value returned by EXPRn is returned.
        !          3709: Since the while expands into a \fIprog\fR, any of the EXPRi may
        !          3710: call the function \fIreturn\fR, terminating the loop prematurely
        !          3711: and returning the value given to \fIreturn\fR.
        !          3712: .PP
        !          3713: A call to the \fIfor\fR macro should be of the form:
        !          3714: .DS
        !          3715: (for <var> <initial> <final>
        !          3716:      EXPR1
        !          3717:      EXPR2
        !          3718:      ...
        !          3719:      EXPRn)
        !          3720: .DE
        !          3721: <initial> and <final> should evaluate to integers.
        !          3722: The EXPRi are repeatedly evaluated in sequence with <var> being
        !          3723: set to the values ascending from <initial> to <final>.
        !          3724: If <initial> is greater than <final>, nothing is done.
        !          3725: <var> is a prog variable which disappears after the \fIfor\fR
        !          3726: executes.
        !          3727: The value returned is the last value of EXPRn and \fIreturn\fR
        !          3728: provides a premature exit with a value as in \fIwhile\fR.
        !          3729: .PP
        !          3730: The fexpr \fBforeach\fR expects a stream and a function (or macro)
        !          3731: and applies the function to each element returned by successive
        !          3732: calls to \fInextitem\fR on the stream.
        !          3733: Unfortunately it only returns \fInil\fR at this time.
        !          3734: Eventually, other useful looping structures may be provided.
        !          3735: .PP
        !          3736: Since PEARL provides several new types of values, it provides a
        !          3737: few functions to copy them.
        !          3738: In particular, the standard Lisp function \fBcopy\fR has been
        !          3739: redefined to avoid trying to copy anything that is not a cons-cell.
        !          3740: There are several ways to copy structures, described below.
        !          3741: The rest of PEARL values either are too complicated to copy
        !          3742: (data bases), can be copied with \fIcopy\fR (streams) or else
        !          3743: make no sense to copy (symbols, blocks).
        !          3744: .PP
        !          3745: For copying structures, there are currently two functions.
        !          3746: The one you are most likely to want is \fBscopy\fR which expects a
        !          3747: single structure argument and returns a new structure with the
        !          3748: same values in it.
        !          3749: However, the new structure will differ from the old in several
        !          3750: important ways.
        !          3751: First of all, copying a bound variable will result in the actual
        !          3752: value being inserted in the new copy.
        !          3753: When copying an unbound variable, the new structure will receive
        !          3754: a local variable with the same name and this variable will
        !          3755: be installed in the slot.
        !          3756: All variables so installed will be installed in the top level
        !          3757: structure regardless of where they came from in the original.
        !          3758: The only exception to this is lexically-scoped variables.
        !          3759: When the new structure is built, it will be built within any
        !          3760: currently open blocks and any of its unbound variables whose names
        !          3761: match variables from the current block(s) will be identified with
        !          3762: those block variables.
        !          3763: Global variables are similarly reinstalled only if they are unbound.
        !          3764: Adjunct variables are also installed \fIonly if\fR they are
        !          3765: unbound, since if they are bound their purpose will already have
        !          3766: been served and their bound values installed in other slots
        !          3767: referring to them.
        !          3768: .PP
        !          3769: A variation on \fIscopy\fR which replaces all unbound
        !          3770: variables from the original with \fI?*any*\fR is called
        !          3771: \fBpatternize\fR.
        !          3772: After (and during) the running of these copying functions, the
        !          3773: resulting top-level structure is kept in the special variable
        !          3774: \fB*currenttopcopy*\fR.
        !          3775: .PP
        !          3776: The situation sometimes arises where you have already built a
        !          3777: structure and have a new structure with information that should be
        !          3778: merged into the old one.
        !          3779: Rather than use \fIpath\fR to copy each relevant slot, you can use
        !          3780: \fBsmerge\fR which expects as arguments the old structure to merge
        !          3781: into and the new structure from which to take values.
        !          3782: All unfrozen variables in the old structure are unbound first and
        !          3783: then any unbound variable whose counterpart in the new structure
        !          3784: is bound gets replaced (\fBnot set\fR) with this value.
        !          3785: The old structure being merged into must be of the same type or
        !          3786: an expanded version of the new structure.
        !          3787: .NH
        !          3788: Miscellaneous Variations and Abbreviations
        !          3789: .PP
        !          3790: People very quickly get tired of typing the relatively long
        !          3791: function names that PEARL uses.
        !          3792: As a result, a large number of abbreviations and macros have
        !          3793: been included in PEARL.
        !          3794: We recommend that the shortest ones be used primarily at
        !          3795: the top level, since they are easily subject to typographic
        !          3796: errors.
        !          3797: Most the abbreviations are in \fIcreate\fR and are summarized by
        !          3798: the following table:
        !          3799: .DS
        !          3800:    The function or atom:       May \kmbe abbreviated:
        !          3801:        create                     \h'|\nmu'cr
        !          3802:        individual                 \h'|\nmu'ind
        !          3803:        pattern                    \h'|\nmu'pat
        !          3804:        expanded                   \h'|\nmu'exp
        !          3805:        function                   \h'|\nmu'fn
        !          3806: .DE
        !          3807: Thus, \fI(cr pat ....)\fR is equivalent to
        !          3808: \fI(create pattern ....)\fR.
        !          3809: .PP
        !          3810: In addition, a large number of macros for popular combinations of
        !          3811: functions are included:
        !          3812: .ID
        !          3813:     The s-expression:               Is exp\kmanded into by the macro:
        !          3814: (create base ...)              \h'|\nmu'(cb  ...)
        !          3815:                                \h'|\nmu'(base  ...)
        !          3816: (create individual ...)                \h'|\nmu'(ci  ...)
        !          3817:                                \h'|\nmu'(individual  ...)
        !          3818:                                \h'|\nmu'(ind  ...)
        !          3819: (create expanded ...)          \h'|\nmu'(ce  ...)
        !          3820:                                \h'|\nmu'(expanded  ...)
        !          3821:                                \h'|\nmu'(pexp  ...)
        !          3822: (create pattern ...)           \h'|\nmu'(cp  ...)
        !          3823:                                \h'|\nmu'(pattern  ...)
        !          3824:                                \h'|\nmu'(pat  ...)
        !          3825: (create function ...)          \h'|\nmu'(cf  ...)
        !          3826:                                \h'|\nmu'(pfunction  ...)
        !          3827:                                \h'|\nmu'(fn  ...)
        !          3828: .sp 1
        !          3829: (insertdb  (create  ...)  nil) \h'|\nmu'(dbcreate  ...)
        !          3830:                                \h'|\nmu'(dbcr  ...)
        !          3831: `(quote  ,(create  ...))       \h'|\nmu'(inlinecreate  ...)
        !          3832: (fetch  (create  ...) nil)     \h'|\nmu'(fetchcreate  ...)
        !          3833: `(fetch  (quote  ,(create  ...))  nil) \h'|\nmu'(inlinefetchcreate  ...)
        !          3834: (nextitem  (fetch  ...) )      \h'|\nmu'(firstfetch  ...)
        !          3835: .sp 1
        !          3836: (valprint  ...)                                \h'|\nmu'(vp  ...)
        !          3837: (fullprint  ...)                       \h'|\nmu'(fp  ...)
        !          3838: .DE
        !          3839: (\fIpexp\fR and \fIpfunction\fR are so named to avoid conflict
        !          3840: with the exponential function \fIexp\fR and the function quoting
        !          3841: function \fIfunction\fR.)
        !          3842: .PP
        !          3843: The automatic setq feature of \fIcreate\fR that causes an atom
        !          3844: to be bound to the item created is available throughout
        !          3845: \fIcreate\fR.
        !          3846: In all cases, the special variable \fB*lastcreated*\fR is
        !          3847: set to the item.
        !          3848: In addition:
        !          3849: .DS
        !          3850: This combination:          Causes \kmthis atom to be set:
        !          3851: (create base  X ...            \h'|\nmu'X
        !          3852: (create base  X Y ...          \h'|\nmu'Y
        !          3853: (create expanded  X Y ...      \h'|\nmu'Y
        !          3854: (create expanded  X Y Z ...    \h'|\nmu'Z
        !          3855: (create individual  X ...      \h'|\nmu'(none)
        !          3856: (create individual  X Y ...    \h'|\nmu'Y
        !          3857: (create individual  X X ...    \h'|\nmu'(none, the second X is ignored)
        !          3858: (create pattern  X ...         \h'|\nmu'(none)
        !          3859: (create pattern  X Y ...       \h'|\nmu'Y
        !          3860: (create pattern  X X ...       \h'|\nmu'(none, the second X is ignored)
        !          3861: .DE
        !          3862: .PP
        !          3863: When creating an object, wherever a recursive call to \fIcreate\fR
        !          3864: is implied by a structure in a slot of type structure, you may start
        !          3865: with one of the types \fIindividual\fR, \fIpattern\fR, \fIbase\fR,
        !          3866: \fIexpanded\fR, \fIfunction\fR to change the type of object
        !          3867: being created.
        !          3868: Whenever it isn't given, the type of the toplevel \fIcreate\fR,
        !          3869: which is kept in the special variable
        !          3870: \fB*currentcreatetype*\fR is used.
        !          3871: For example, in
        !          3872: .DS
        !          3873: (create pattern  x
        !          3874:        (a  (individual  y))
        !          3875:        (b  (base  z  (s1  ...)  ...))
        !          3876:        (c  (w)))
        !          3877: .DE
        !          3878: where a, b, and c are all slots of type structure, slot a
        !          3879: will contain an individual y which the attendant defaults
        !          3880: filled in, slot b will contain the default instance of a
        !          3881: newly created type z, and slot c will contain a pattern w
        !          3882: with \fI?*any*\fR as defaults.
        !          3883: .PP
        !          3884: Since each Lisp stores its functions in a different place, PEARL
        !          3885: includes a macro \fBaliasdef\fR which expects the names of an new
        !          3886: and a old function name and copies the function definition of the
        !          3887: old one to the new one.
        !          3888: In the case of Lisps which store the function definition on the
        !          3889: property list, \fIaliasdef\fR requires a third argument which is
        !          3890: the name of the property that the definition is kept under.
        !          3891: .NH
        !          3892: Low Level Access Functions.
        !          3893: .PP
        !          3894: There are a large number of functions for setting and accessing
        !          3895: the various part of structures, symbols, and data bases which are
        !          3896: primarily intended for the use of PEARL.
        !          3897: In general, the access functions are called \fBget...\fR where
        !          3898: "..." is the name of the information about the structure.
        !          3899: The functions which change information are called \fBput...\fR.
        !          3900: It is not generally safe to use the \fIput...\fR functions but the
        !          3901: \fIget...\fR functions can sometimes be useful to the user.
        !          3902: For a complete list of the functions, see the index.
        !          3903: If you don't recognize the function by name, you don't need it so
        !          3904: we don't bother to further document them.
        !          3905: Since most of them expect a slot number, it is useful to know
        !          3906: about the macro \fBnumberofslot\fR which requires the name of a
        !          3907: slot and the definition of a structure (which can be accessed
        !          3908: with \fIdefatom\fR or \fId:<structurename>\fR.) and returns the
        !          3909: corresponding slot number.
        !          3910: .bp
        !          3911: .NH
        !          3912: Appendix of UCI Lisp functions added to Franz PEARL
        !          3913: .PP
        !          3914: Since PEARL was originally written in UCI Lisp, there are many functions
        !          3915: from UCI Lisp that it needed.
        !          3916: We also wrote others to move our other programs.
        !          3917: The number is too great to document each one.
        !          3918: If the function is described with an equal sign, as in
        !          3919: \fI"fn = other"\fR then the function definition of the Franz Lisp
        !          3920: function \fIother\fR has been put under \fIfn\fR.
        !          3921: Thus it might not behave quite the same as in UCI Lisp.
        !          3922: If no equivalence is given, it was written from scratch which is
        !          3923: slightly more likely to mimic UCI Lisp.
        !          3924: In this case, see the UCI Lisp manual for details.
        !          3925: .PP
        !          3926: The functions used for the PEARL top level loop in the Franz Lisp
        !          3927: version plus changes to the fixit debugger and the trace package
        !          3928: are briefly described here also.
        !          3929: .PP
        !          3930: The Franz Lisp version of PEARL is normally loaded with both the Fixit
        !          3931: debugger and the trace package already loaded.
        !          3932: This is done to avoid getting the versions which do not know how to print
        !          3933: PEARL objects.
        !          3934: In addition, the Fixit debugger is attached to all available hooks for
        !          3935: going into the break package, since it is much more similar to the UCI Lisp
        !          3936: break package than the standard Franz Lisp break package is.
        !          3937: Both the debugger and trace package use the function
        !          3938: \fBbreakprintfn\fR to print values.
        !          3939: The \fImsg\fR function uses the function \fBmsgprintfn\fR
        !          3940: to print values.
        !          3941: Either can be bound to whatever function you wish.
        !          3942: To disengage the Fixit debugger, read the Franz manual chapter on exception
        !          3943: handling.
        !          3944: See Note 4 below for more on features added to the Fixit debugger.
        !          3945: .LP
        !          3946: .nf
        !          3947: Atoms and Variables:
        !          3948: *dskin* -- special variable -- initial value: t.  See Note 1 below.
        !          3949: *file* -- special variable -- initial value: nil.  Used by \fIdskin\fR
        !          3950:        and function definition functions.
        !          3951: *invisible* -- special atom -- not printed by \fIdskin\fR if returned
        !          3952:            by a value when it is evaluated.
        !          3953: 
        !          3954: Functions:
        !          3955: *append = append
        !          3956: (breakprintfn value lmar rmar) -- used by \fItrace\fR and \fIdebug\fR.
        !          3957: *dif = diff
        !          3958: *eval = eval
        !          3959: *great = greaterp
        !          3960: *less = lessp
        !          3961: *max = max
        !          3962: (msgprintfn value lmar rmar) -- used by \fImsg\fR.
        !          3963: *nconc = nconc
        !          3964: *plus = plus
        !          3965: *times = times
        !          3966: (addprop 'id 'value 'prop)
        !          3967: (allsym itemorpair) -- fexpr
        !          3968: (apply* 'fcn 'args) -- macro -- This is provided to act like UCI Lisp's
        !          3969:        \fIapply#\fR.  The asterisk is used because of the special meaning
        !          3970:        of # in Franz Lisp.  Unlike Franz Lisp's \fIfuncall\fR and
        !          3971:        \fIapply\fR, this does what you would expect with macros!
        !          3972: atcat = concat
        !          3973: (boundp 'item)
        !          3974: clrbfi = drain
        !          3975: consp = dtpr
        !          3976: (de fcnname arglist &rest body) -- macro -- See Note 2 below.
        !          3977: (debug-replace-function-name 'cmd 'frame) -- Used by the modified
        !          3978:        Fixit debugger to handle the "> newfcnname" facility.
        !          3979: (defp 'to 'from [prop]) -- macro -- Ignores \fIprop\fR and just
        !          3980:       copies the function definition.
        !          3981: (defv var val) -- fexpr
        !          3982: (df fcnname arglist &rest body) -- macro -- See Note 2 below.
        !          3983: (dm fcnname arglist &rest body) -- macro -- See Note 2 below.
        !          3984: (dremove 'elmt 'l)
        !          3985: (drm char lambda) -- macro -- See Note 2 below.
        !          3986: (dskin filename1 filename2 ....) -- See Note 1 below.
        !          3987: (dskin1 '*file*)
        !          3988: (dskin2 'port)
        !          3989: (dsm char lambda) -- macro -- See Note 2 below.
        !          3990: (enter 'v 'l)
        !          3991: (every 'fcn 'args) -- macro -- Potential problem when compiled.
        !          3992: expandmacro = macroexpand
        !          3993: (funl &rest body) -- macro -- Expands into (function (lambda ...)).
        !          3994: (ge 'x) -- macro
        !          3995: (gensym1 'ident 'val)
        !          3996: gt = >
        !          3997: (initsym atomorpair1 ...) -- fexpr
        !          3998: (intersection 'set1 'set2)
        !          3999: (islambda 'fcn) -- Is \fIfcn\fR a lambda (expr)?
        !          4000: (le 'x) -- macro
        !          4001: (length '*u*)
        !          4002: lineread = readl (below)
        !          4003: (litatom 'x) -- macro
        !          4004: lt = <
        !          4005: mapcl = mapcar
        !          4006: memb = member
        !          4007: (msg ...) -- macro -- Some features may be missing.  The function
        !          4008:          used to print is \fImsgprintfn\fR, initially bound to 
        !          4009:               (or (eq '*invisible* ...)
        !          4010:                   (patom (valform ...)))
        !          4011: (nconc1 'l 'elmt)
        !          4012: (nequal 'arg1 'arg2)
        !          4013: (newsym atom) -- fexpr
        !          4014: noduples = union (below)
        !          4015: (nth 'l 'num)
        !          4016: (oldsym atomorpair) -- fexpr
        !          4017: (pearl-break-err-handler) -- Should be tied to ER%tpl if you want the
        !          4018:        standard Franz Lisp break (not much of a) package.
        !          4019:        Same as standard Franz Lisp \fIbreak-err-handler\fR except
        !          4020:        that it uses the function \fIbreakprintfn\fR.
        !          4021: (pearl-top-level) -- The PEARL top level loop.
        !          4022: (pearl-top-level-init) -- The initial function called when PEARL starts up.
        !          4023:        This is the code that reads in the init files and sets any unset
        !          4024:        PEARL parameters.
        !          4025: peekc = tyipeek
        !          4026: (pop q) -- macro
        !          4027: (push var 'val) -- macro
        !          4028: (readl ['flag]) -- fexpr
        !          4029: (readl1 'flag)
        !          4030: remove = delete
        !          4031: (remprops 'item 'proplist)
        !          4032: (remsym atomorpairlist) -- fexpr
        !          4033: (save fcnname) -- fexpr -- Saves function or macro definition under 
        !          4034:        the property \fIolddef\fR.  Saves macro character definitions
        !          4035:        under \fIoldmacro\fR.
        !          4036: (selectq ...) -- macro
        !          4037: (some 'fcn 'list) -- macro -- Potential problem when compiled.
        !          4038: (sprint 'item ['lmar ['rmar]]) -- See Note 3 below.
        !          4039: (subset 'fcn 'list) -- macro
        !          4040: (timer (defun timer fexpr (request)$?
        !          4041: (unbound) -- macro
        !          4042: (union 'list1 ['list2 ...])
        !          4043: (unsave fcnname) -- fexpr -- See \fIsave\fR.
        !          4044: .fi
        !          4045: .PP
        !          4046: \fBNote 1:\fR A simplified but extended imitation of the UCI Lisp function
        !          4047: \fBdskin\fR is provided in PEARL.
        !          4048: It is an nlambda which requires the file extensions to be provided.
        !          4049: There is a special variable \fB*dskin*\fR which controls whether
        !          4050: the expression read in is printed and/or whether the result of
        !          4051: evaluating it is printed.
        !          4052: .DS L
        !          4053: *dskin* = nil  means neither
        !          4054: *dskin* = t    means result only
        !          4055: *dskin* = 'name        means the name of the variable in setq \fIor\fR the name
        !          4056:                of the function in de, df, dm, dsm, drm, defmacro,
        !          4057:                defun, or def \fIor\fR the name of the type in create.
        !          4058: *dskin* = 'both        means both t and 'name.
        !          4059: .DE
        !          4060: The default value of *dskin* is t.
        !          4061: .PP
        !          4062: File names are always printed before they are opened.
        !          4063: The print function used for values is the current function
        !          4064: definition of \fBdskprintfn\fR.
        !          4065: The default function definition in PEARL is:
        !          4066: .DS
        !          4067: (de dskprintfn  (*printval*)
        !          4068:     (cond  ((atom  *printval*)  (patom  *printval*))
        !          4069:           (  t  (print  (valform  *printval*)))))
        !          4070: .DE
        !          4071: .PP
        !          4072: \fBNote 2:\fR  For better compatibility with UCI Lisp, PEARL contains
        !          4073: macros for the function and read macro definition functions 
        !          4074: \fBde, df, dm, dsm,\fR and \fBdrm\fR.
        !          4075: They have been defined to save the old definitions automatically
        !          4076: and to return \fI(fcnname Redefined)\fR when this is the case.
        !          4077: \fIDe, df,\fR and \fIdm\fR save the old definition under the
        !          4078: property '\fIolddef\fR.
        !          4079: \fIDsm\fR and \fIdrm\fR save the old definition under the
        !          4080: property '\fIoldmacro\fR.
        !          4081: (The current definition of a readmacro is kept by Franz under the
        !          4082: property '\fImacro\fR.)
        !          4083: If the function definition is read in by \fIdskin\fR,
        !          4084: then the current file name which is in the special variable
        !          4085: \fB*file*\fR is put under the property '\fIsourcefile\fR.
        !          4086: .PP
        !          4087: \fBNote 3:\fR  A function similar to the UCI Lisp \fBsprint\fR is included,
        !          4088: including the printmacro facility and the optional second argument
        !          4089: saying which column to start in.
        !          4090: In addition, there is an optional third argument saying which column
        !          4091: to try not to go beyond (that is a right margin).
        !          4092: A slight addition has been made to the printmacro feature (feature 1 below).
        !          4093: During \fIsprinting\fR, if the atom in the function position in a list
        !          4094: has the printmacro property one of four things will happen during
        !          4095: \fIsprinting\fR:
        !          4096: .IP 1.
        !          4097: If the printmacro property value is a string and the item to be
        !          4098: printed has a nil \fIcdr\fR, then the string will be printed instead
        !          4099: of the item.
        !          4100: .IP 2.
        !          4101: If the printmacro property value is a string and the item to be
        !          4102: printed has two items in it, then the string will be printed followed
        !          4103: immediately by the \fIcadr\fR of the item.
        !          4104: .IP 3.
        !          4105: If the printmacro property value is a string but the item to be
        !          4106: printed is longer than two elements, then it will be \fIsprinted\fR in
        !          4107: the normal fashion (i.e., the printmacro will be ignored).
        !          4108: .IP 4.
        !          4109: Otherwise, the printmacro property value will be applied
        !          4110: to the rest of the arguments.
        !          4111: It should be a function which expects three arguments, the item
        !          4112: to be printed, a left column to start in and a right column to
        !          4113: try not to go beyond.
        !          4114: A good default value for the right column argument seems to be zero.
        !          4115: If the function under the printmacro property returns nil,
        !          4116: then \fIsprint\fR assumes that it decided not to print the item
        !          4117: and prints it in the usual way.
        !          4118: .PP
        !          4119: \fBNote 4:\fR  The Fixit debugger now accepts a command of the
        !          4120: form \fB>  newname\fR whenever either an undefined function or
        !          4121: unbound variable error occurs.  As in UCI Lisp, newname is not
        !          4122: evaluated in the case of an undefined function but is evaluated
        !          4123: in the case of an unbound variable.
        !          4124: Note that the blank is required (unlike UCI Lisp).
        !          4125: This is not guaranteed to work if you move around the stack first.
        !          4126: .bp
        !          4127: .NH
        !          4128: Appendix of Franz Lisp functions added to UCI Lisp PEARL
        !          4129: .PP
        !          4130: The following is a summary of the functions added to the UCI Lisp
        !          4131: version of PEARL to make it compatible with Franz Lisp.
        !          4132: Where the details are not obvious, see the Franz Lisp manual.
        !          4133: \fBNote:\fR Most \fImacros\fR listed in the index which are
        !          4134: labelled with asterisks are not available in UCI Lisp PEARL, since
        !          4135: the implementor must specifically request that they stick around.
        !          4136: .PP
        !          4137: \fIDskin\fR, the break package, and \fImsg\fR have been changed
        !          4138: to use the functions \fBdskprintfn\fR, \fBbreakprintfn\fR,
        !          4139: \fBmsgprintfn\fRfor printing.
        !          4140: .LP
        !          4141: .nf
        !          4142: (addtoaddress 'n 'address) -- expr -- Used by \fIcxr\fR and
        !          4143:        \fIrplacx\fR.  Written in LAP code.
        !          4144: (apply* 'fcn 'args) -- macro -- Equivalent to \fIapply#\fR.
        !          4145: (buildalist ...) --- expr --- Used by \fIdefmacro\fR.
        !          4146: (combineskels ...) -- expr -- Used by \fIquasiquote\fR.
        !          4147: (convert ...) --- expr --- Used by \fIdefmacro\fR.
        !          4148: (cxr 'index 'hunk) -- expr -- A hunk is a block of memory.  Provides
        !          4149:        random access to a single cell of a hunk.  (Uses
        !          4150:        \fIaddtoaddress\fR and \fIeven\fR.)
        !          4151: (defmacro macroname arglist body) -- macro -- \fIDefmacro\fR provides
        !          4152:        a slightly more intelligent macro facility.  \fIBody\fR is
        !          4153:        processed to look for occurrences of the arguments in
        !          4154:        \fIarglist\fR which are replaced with the appropriate form
        !          4155:        of \fIca..r\fR.  If an argument is preceded by \fI&rest\fR,
        !          4156:        then it gets the list of the rest of the arguments.
        !          4157:        The Franz Lisp version has many more features not included
        !          4158:        in the PEARL version.
        !          4159: (even 'x) -- expr -- Is \fIx\fR even? Used by \fIcxr\fR and
        !          4160:        \fIrplacx\fR to determine which half of a cons-cell to use.
        !          4161: (isconst ...) -- expr -- Used by \fIquasiquote\fR.
        !          4162: (makhunk 'size) -- expr -- Calls the UCI Lisp function \fIgetblk\fR,
        !          4163:        requesting a block of memory which is half of \fIsize\fR, since
        !          4164:        each piece of a UCI Lisp block of core is a cons-cell.
        !          4165: (msg ...) -- fexpr -- Modified to use \fImsgprintfn\fR to print
        !          4166:        values of evaluated elements of the print list.
        !          4167: (pearl-top-level) -- the PEARL top level loop. 
        !          4168: (pearl-top-level-init) -- The initial function called when PEARL starts up.  
        !          4169: (rplacx 'index 'hunk 'val) -- expr -- Provides random access storage into
        !          4170:        a block of memory.  (Uses \fIaddtoaddress\fR and \fIeven\fR.)
        !          4171: (quasiquote 'skel) -- expr -- called by the quasi-quote readmacro
        !          4172:        character backquote \fB`\fR.  Equivalent to the quasiquote
        !          4173:        functions defined in Charniak[2] with different invoking
        !          4174:        characters to match those of Franz Lisp.
        !          4175:        Unquote is comma \fB","\fR and splice-unquote is \fB",@"\fR.
        !          4176:        Uses \fIcombineskels\fR and \fIisconst\fR.
        !          4177: .fi
        !          4178: .bp
        !          4179: .NH
        !          4180: Bibliography
        !          4181: .SM
        !          4182: .IP [1]
        !          4183: Bobrow, D., and Winograd, T. "An Overview of KRL, a Knowledge
        !          4184: Representation Language."
        !          4185: \fICognitive Science\fR 1:1 (1977).
        !          4186: .IP [2]
        !          4187: Charniak, E., Riesbeck, C., and McDermott, D.
        !          4188: \fIArtificial Intelligence Programming\fR.
        !          4189: Hillsdale, New Jersey: Lawrence Erlbaum Associates, 1980.
        !          4190: .IP [3]
        !          4191: Faletti, J., and Wilensky, R. "The Implementation of PEARL:
        !          4192: A Package for Efficient Access to Representations In Lisp",
        !          4193: forthcoming ERL technical report, UCB.
        !          4194: .IP [4]
        !          4195: Greiner, R., and Lenat, D. "A Representation Language Language."
        !          4196: In \fIProc. First NCAI\fR. Stanford, CA, August, 1980,
        !          4197: 165-169.
        !          4198: .IP [5]
        !          4199: Roberts, I., and Goldstein, R.
        !          4200: "NUDGE, A Knowledge-Based Scheduling Program."
        !          4201: In \fIProc. IJCAI-77\fR. Cambridge, MA, August, 1977, 257-263.
        !          4202: .IP [6]
        !          4203: Schank, R. \fIConceptual Information Processing\fR.
        !          4204: Amsterdam: North Holland, 1975.
        !          4205: .IP [7]
        !          4206: Wilensky, R. "Understanding Goal-Based Stories",
        !          4207: Technical Report 140, Computer Science Department,
        !          4208: Yale University, New Haven, CT, September 1978.
        !          4209: .IP [8]
        !          4210: Wilensky, R.
        !          4211: "Meta-Planning: Representing and Using Knowledge about Planning in Problem
        !          4212: Solving and Natural Language Understanding."
        !          4213: \fICognitive Science\fR 5:3 (1981).
        !          4214: .bp
        !          4215: .nr PS 9
        !          4216: .nr VS 11p
        !          4217: .ps 9
        !          4218: .vs 11p
        !          4219: .NH
        !          4220: Index of Global Variables and Functions With Their Arguments
        !          4221: .PP
        !          4222: All functions are exprs (or lexprs) unless otherwise listed.
        !          4223: Functions with one or more asterisks for a page number are not
        !          4224: documented other than in this index because they were not
        !          4225: actually intended for use by the PEARL user.
        !          4226: A single asterisk * means it is primarily intended for use by
        !          4227: PEARL but might be useful and will generally work right.
        !          4228: A double asterisk ** means it will generally only work
        !          4229: within PEARL's code, since it expects certain
        !          4230: external prog variables to exist and be set correctly.
        !          4231: A triple asterisk *** means it is dangerous to use.
        !          4232: Note that it is dangerous to redefine any functions in this list,
        !          4233: although it should be all right to redefine any macros.
        !          4234: .LP
        !          4235: .nr PS 8
        !          4236: .nr VS 10p
        !          4237: .ps 8
        !          4238: .vs 10p
        !          4239: .nf
        !          4240: *activedbnames* -- special variable -- initial value: nil                          \ki40
        !          4241: *any*conscell* -- special variable -- value: '(*any* . *pearlunbound*) \h'|\niu'*
        !          4242: *availablesizes* -- special variable -- value: \h'|\niu'39
        !          4243:        ((-1. . 1.) (0. . 1.) (1. . 1.) (2. . 3.) (3. . 7.)
        !          4244:         (4. . 13.) (5. . 29.) (6. . 61.) (7. . 127.) . . . .
        !          4245:                Franz Lisp: . . . (8. . 127.) (9. . 127.) (10. . 127.)
        !          4246:                                  (11. . 127.) (12. . 127.) (13. . 127.))
        !          4247:                UCI Lisp:  . . .  (8. . 251.) (9. . 509.) (10. . 1021.)
        !          4248:                                  (11. . 2039.) (12. . 4093.) (13. . 8191.))
        !          4249: *blockstack* -- special variable -- initial value: nil \h'|\niu'48
        !          4250: *currentcreatetype* -- special variable -- initial value: base \h'|\niu'56
        !          4251: *currentpearlstructure* -- special variable -- initial value: nil      \h'|\niu'46
        !          4252: *currentstructure* -- special variable -- initial value: nil   \h'|\niu'46
        !          4253: *currenttopcopy* -- special variable -- initial value: <UNBOUND>       \h'|\niu'55
        !          4254: *currenttopcreated* -- special variable -- initial value: (nilstruct)  \h'|\niu'8
        !          4255: .sp
        !          4256: db -- special variable -- default initial value: <UNBOUND>     \h'|\niu'33
        !          4257: *db* -- special variable -- default value: the *maindb* data base      \h'|\niu'12
        !          4258: *db1size* -- special variable -- default initial value: 29     \h'|\niu'39
        !          4259: *db2size* -- special variable -- default initial value: 127    \h'|\niu'39
        !          4260: *done* -- special atom \h'|\niu'35
        !          4261: .sp
        !          4262: *fail* -- special atom \h'|\niu'35
        !          4263: *file* -- special variable -- initial value: nil       \h'|\niu'60
        !          4264: *firstartup* -- special variable -- initial value: t   \h'|\niu'53
        !          4265: *function-stream:* -- special atom     \h'|\niu'13
        !          4266: *globallist* -- special variable -- initial value: nil \h'|\niu'45
        !          4267: .sp
        !          4268: *history* -- special variable -- value: command history hunk   \h'|\niu'51
        !          4269: *historynumber* -- special variable -- initial value: 0        \h'|\niu'52
        !          4270: *historysize* -- special variable -- default value: 64 \h'|\niu'51
        !          4271: *histval* -- special variable -- value: value history hunk     \h'|\niu'51
        !          4272: *invisible* -- special atom    \h'|\niu'53
        !          4273: .sp
        !          4274: *lastcreated* -- special variable -- initial value: (nilstruct)        \h'|\niu'8
        !          4275: *lastsymbolnum* -- special variable -- initial value: -1       \h'|\niu'*
        !          4276: *maindb* -- special variable -- default value: the main data base      \h'|\niu'11
        !          4277: *matchunboundsresult* -- special variable -- initial value: nil        \h'|\niu'44
        !          4278: *ordinalnames* -- special variable -- initial value: nil       \h'|\niu'31
        !          4279: .sp
        !          4280: *pathlocal* -- special variable -- initial value: <UNBOUND>    \h'|\niu'33
        !          4281: *pathtop* -- special variable -- initial value: <UNBOUND>      \h'|\niu'33
        !          4282: *pearlprompt* -- special variable -- default value: "pearl> "  \h'|\niu'3, 4
        !          4283: *pearlunbound* -- special atom \h'|\niu'45
        !          4284: *printhistorynumber* -- special variable -- initial value: nil \h'|\niu'53
        !          4285: .sp
        !          4286: *readlinechanged* -- special variable -- initial value: nil    \h'|\niu'53
        !          4287: *runaddpredpathhooks* -- special variable -- initial value: t  \h'|\niu'34
        !          4288: *runaddsetpathhooks* -- special variable -- initial value: t   \h'|\niu'34
        !          4289: *runallbasehooks* -- special variable -- initial value: t      \h'|\niu'33
        !          4290: *runallslothooks* -- special variable -- initial value: t      \h'|\niu'33
        !          4291: .sp
        !          4292: *runapplypathhooks* -- special variable -- initial value: t    \h'|\niu'34
        !          4293: *runclearpathhooks* -- special variable -- initial value: t    \h'|\niu'34
        !          4294: *rundelpredpathhooks* -- special variable -- initial value: t  \h'|\niu'34
        !          4295: *rundelsetpathhooks* -- special variable -- initial value: t   \h'|\niu'34
        !          4296: *runexpandedhooks* -- special variable -- initial value: t     \h'|\niu'34
        !          4297: *runfetchhooks* -- special variable -- initial value: t        \h'|\niu'34
        !          4298: *rungethookpathhooks* -- special variable -- initial value: t  \h'|\niu'34
        !          4299: *rungetpathhooks* -- special variable -- initial value: t      \h'|\niu'34
        !          4300: *rungetpredpathhooks* -- special variable -- initial value: t  \h'|\niu'34
        !          4301: *runindbhooks* -- special variable -- initial value: t \h'|\niu'34
        !          4302: *runindividualhooks* -- special variable -- initial value: t   \h'|\niu'34
        !          4303: *runinsertdbhooks* -- special variable -- initial value: t     \h'|\niu'34
        !          4304: *runmatchhooks* -- special variable -- initial value: t        \h'|\niu'34
        !          4305: *runnextequalhooks* -- special variable -- initial value: t    \h'|\niu'34
        !          4306: *runnextitemhooks* -- special variable -- initial value: t     \h'|\niu'34
        !          4307: *runpatternhooks* -- special variable -- initial value: t      \h'|\niu'34
        !          4308: *runputpathhooks* -- special variable -- initial value: t      \h'|\niu'34
        !          4309: *runremovedbhooks* -- special variable -- initial value: t     \h'|\niu'34
        !          4310: *runsmergehooks* -- special variable -- initial value: t       \h'|\niu'34
        !          4311: *runstrequalhooks* -- special variable -- initial value: t     \h'|\niu'34
        !          4312: .sp
        !          4313: *stream* -- special atom       \h'|\niu'13
        !          4314: *stream:* -- special atom      \h'|\niu'13
        !          4315: *toplevelp* -- special variable -- initial value: <UNBOUND>    \h'|\niu'*
        !          4316: *unhashablevalues* -- special variable -- initial value:       \h'|\niu'*
        !          4317:        (0 unbound *pearlunbound* nilsym (nilstruct))
        !          4318: *use* -- special atom  \h'|\niu'35
        !          4319: *usealiases* -- special variable -- initial value: t   \h'|\niu'51
        !          4320: *warn* -- special variable -- initial value: t \h'|\niu'17
        !          4321: *zero-ordinal-value* -- special variable -- initial value: 0   \h'|\niu'31
        !          4322: .sp
        !          4323: ! -- splicing macro    \h'|\niu'52
        !          4324: $ -- splicing macro    \h'|\niu'52
        !          4325: = -- read macro        \h'|\niu'28
        !          4326: ? -- read macro        \h'|\niu'16
        !          4327: .sp
        !          4328: (addalist 'var 'inst) -- macro \h'|\niu'*
        !          4329: (addbasehook 'conscell 'item) -- macro \h'|\niu'*
        !          4330: (addhistory 'line)     \h'|\niu'*
        !          4331: (addpredpath 'item 'path 'pred)        \h'|\niu'10
        !          4332: (addsetpath 'item 'path 'value)        \h'|\niu'10
        !          4333: .sp
        !          4334: (addtoexpansionlists) -- macro \h'|\niu'**
        !          4335: (adjvarset 'var 'val) -- macro \h'|\niu'*
        !          4336: (allocdef numofslots) -- macro \h'|\niu'*
        !          4337: (allocval numofslots) -- macro \h'|\niu'*
        !          4338: (applypath 'fcn 'item 'path)   \h'|\niu'10
        !          4339: .sp
        !          4340: (base name [storage] slot1 ...) -- macro       \h'|\niu'56
        !          4341: (basicmatch 'item1 'item2)     \h'|\niu'46
        !          4342: (block [blockname] varlist) -- fexpr   \h'|\niu'47
        !          4343: (blockatom 'symbol)    \h'|\niu'48
        !          4344: (blockp 'potblock)     \h'|\niu'30
        !          4345: .sp
        !          4346: (breakprintfn '*printval*)     \h'|\niu'58, 59
        !          4347: (builddb newdb [olddb]) -- fexpr       \h'|\niu'38
        !          4348: (buildintvalue 'intval 'bppset) -- macro       \h'|\niu'*
        !          4349: (buildslot) -- macro   \h'|\niu'**
        !          4350: (buildstructvalue 'structdesc) -- macro        \h'|\niu'*
        !          4351: (buildsymbolvalue 'symname) -- macro   \h'|\niu'*
        !          4352: (buildvalue 'value 'typenum 'ppset)    \h'|\niu'*
        !          4353: .sp
        !          4354: (cb name [storage] slot1 ...) -- macro \h'|\niu'56
        !          4355: (ce basename newname [storage] slot1 ...) -- macro     \h'|\niu'56
        !          4356: (cf name [storage] slot1 ...) -- macro \h'|\niu'56
        !          4357: (checkandrunbasehooks2 'fcn 'item1 'item2) -- macro    \h'|\niu'**
        !          4358: (checkandrunslothooks2 'fcn 'hooks 'val1 'val2 'item1 'item2) -- macro \h'|\niu'**
        !          4359: (checkrunhandlebasehooks1 'fcn 'runhooksatom) -- macro \h'|\niu'**
        !          4360: (checkrunhandleslothooks1 'fcn 'runhooksatom) -- macro \h'|\niu'**
        !          4361: (ci basename [storage] slot1 ...) -- macro     \h'|\niu'56
        !          4362: .sp
        !          4363: (cleardb ['db])        \h'|\niu'39
        !          4364: (cleardb1 'db) \h'|\niu'39
        !          4365: (cleardbactive 'db) -- macro   \h'|\niu'*
        !          4366: (clearhashandformat 'slotnum 'defblock) -- macro       \h'|\niu'*
        !          4367: (clearpath 'item 'path)        \h'|\niu'10
        !          4368: .sp
        !          4369: (compatible 'slotnum 'item1 'item2) -- macro   \h'|\niu'*
        !          4370: (connectdb 'newdb 'olddb)      \h'|\niu'*
        !          4371: (consistentvalue 'val 'predlist 'typenum 'item) -- macro       \h'|\niu'*
        !          4372: (constructvalue) -- macro      \h'|\niu'**
        !          4373: (convertpreds 'pred)   \h'|\niu'*
        !          4374: (copy 'list)   \h'|\niu'54
        !          4375: (copypatternslot) -- macro     \h'|\niu'**
        !          4376: (copyslice) -- macro   \h'|\niu'**
        !          4377: (copyslot 'nameblock) -- macro \h'|\niu'**
        !          4378: .sp
        !          4379: (cp basename [storage] slot1 ...) -- macro     \h'|\niu'56
        !          4380: (cr selector ...) -- fexpr     \h'|\niu'55
        !          4381: (create selector ...) -- fexpr \h'|\niu'5
        !          4382: (createbase 'newname 'slots)   \h'|\niu'*
        !          4383: (createexpanded 'oldname 'newname 'slots)      \h'|\niu'*
        !          4384: (createfunction 'fcnname 'slots)       \h'|\niu'*
        !          4385: (createindividual 'basename 'slots)    \h'|\niu'*
        !          4386: (createpattern 'basename 'slots)       \h'|\niu'*
        !          4387: .sp
        !          4388: (databasep 'potdb)     \h'|\niu'30
        !          4389: (dbcr selector ...) -- macro   \h'|\niu'56
        !          4390: (dbcreate selector ...) -- macro       \h'|\niu'12, 56
        !          4391: (debugprint 'item)     \h'|\niu'21
        !          4392: (defatom 'symbol)      \h'|\niu'7
        !          4393: .sp
        !          4394: (defaultfortype 'typenum) -- macro     \h'|\niu'*
        !          4395: (definitionp 'potdef)  \h'|\niu'30
        !          4396: (delpredpath 'item 'path 'pred)        \h'|\niu'10
        !          4397: (delsetpath 'item 'path 'value)        \h'|\niu'10
        !          4398: (disguisedas 'filler 'struct ['db])    \h'|\niu'29
        !          4399: (disguisedas1 'filler 'struct 'db)     \h'|\niu'29
        !          4400: .sp
        !          4401: (dobasehooks2< 'fcn 'runhookatom) -- macro     \h'|\niu'**
        !          4402: (dobasehooks2> 'fcn 'runhookatom) -- macro     \h'|\niu'**
        !          4403: (doslothooks2< 'fcn 'runhookatom) -- macro     \h'|\niu'**
        !          4404: (doslothooks2> 'fcn 'runhookatom) -- macro     \h'|\niu'**
        !          4405: (dskprintfn '*printval*)       \h'|\niu'60
        !          4406: .sp
        !          4407: (endallblocks) \h'|\niu'48
        !          4408: (endanyblocks blockname) -- fexpr      \h'|\niu'48
        !          4409: (endblock [blockname]) -- fexpr        \h'|\niu'47
        !          4410: (enforcetype 'value 'typenum)  \h'|\niu'*
        !          4411: (equalvalue 'xval 'yval 'typenum) -- macro     \h'|\niu'*
        !          4412: (evalfcn 'item)        \h'|\niu'51
        !          4413: .sp
        !          4414: (executehook1 fcn value item defblock) -- macro        \h'|\niu'**
        !          4415: (executehook2 fcn val1 val2 item1 item2 defblock result) -- macro      \h'|\niu'**
        !          4416: (expanded basename newname [storage] slot1 ...) -- macro       \h'|\niu'56
        !          4417: (expandedfetch 'item ['db])    \h'|\niu'42
        !          4418: (expandedfetch1 'item 'db)     \h'|\niu'42
        !          4419: .sp
        !          4420: (fcnslot) -- macro     \h'|\niu'**
        !          4421: (fetch 'item ['db])    \h'|\niu'12, 43
        !          4422: (fetch1 'item 'db)     \h'|\niu'12, 43
        !          4423: (fetcheverywhere 'item ['db])  \h'|\niu'19, 25
        !          4424: (fetcheverywhere1 'item 'db)   \h'|\niu'19, 25
        !          4425: (fetchcreate selector ...) -- macro    \h'|\niu'14, 56
        !          4426: (fillbaseslot) -- macro        \h'|\niu'**
        !          4427: (fillin1 'fcn 'value 'item 'defblock)  \h'|\niu'33
        !          4428: (fillin2 'fcn 'val1 'val2 'item1 'item2 'defblock 'result)     \h'|\niu'33
        !          4429: (fillindivslot) -- macro       \h'|\niu'**
        !          4430: .sp
        !          4431: (findnextblockstart) -- macro  \h'|\niu'**
        !          4432: (findslotnum) -- macro \h'|\niu'**
        !          4433: (findstructsymbolpair 'defblock 'symbol) -- macro      \h'|\niu'**
        !          4434: (firstfetch pattern) -- macro  \h'|\niu'14, 56
        !          4435: (fn name [storage] slot1 ...) -- macro \h'|\niu'56
        !          4436: .sp
        !          4437: (followpath 'item 'path)       \h'|\niu'*
        !          4438: (for val 'init 'final &rest 'body) -- macro    \h'|\niu'54
        !          4439: (foreach 'stream fcn) -- fexpr \h'|\niu'54
        !          4440: (fp 'item ['lmar ['rmar]])     \h'|\niu'56
        !          4441: (freezebindings 'struct)       \h'|\niu'48
        !          4442: (freezeblock 'blockname)       \h'|\niu'49
        !          4443: (freezestruct 'struct) \h'|\niu'49
        !          4444: .sp
        !          4445: (fullform 'item)       \h'|\niu'20
        !          4446: (fullprint 'item ['lmar ['rmar]])      \h'|\niu'20, 37
        !          4447: (fullprint1 'item 'lmar 'rmar) \h'|\niu'20, 37
        !          4448: (fullslotform) -- macro        \h'|\niu'**
        !          4449: .sp
        !          4450: (getalist 'inst) -- macro      \h'|\niu'57
        !          4451: (getalistcp 'inst) -- macro    \h'|\niu'57
        !          4452: (getbasehooks 'defblock) -- macro      \h'|\niu'57
        !          4453: (getdb1 'db) -- macro  \h'|\niu'57
        !          4454: (getdb2 'db) -- macro  \h'|\niu'57
        !          4455: (getdbactive 'db) -- macro     \h'|\niu'57
        !          4456: (getdbchildren 'db) -- macro   \h'|\niu'57
        !          4457: (getdbname 'db) -- macro       \h'|\niu'57
        !          4458: (getdbparent 'db) -- macro     \h'|\niu'57
        !          4459: (getdefaultinst 'defblock)     \h'|\niu'57
        !          4460: (getdefinition 'valblock)      \h'|\niu'57
        !          4461: (getenforce 'slotnum 'defblock) -- macro       \h'|\niu'57
        !          4462: (getexpansionlist 'defblock) -- macro  \h'|\niu'57
        !          4463: (getformatinfo 'slotnum 'defblock) -- macro    \h'|\niu'57
        !          4464: (gethash* 'slotnum 'defblock) -- macro \h'|\niu'57
        !          4465: (gethash** 'slotnum 'defblock) -- macro        \h'|\niu'57
        !          4466: (gethash1 'num1 'db1) -- macro \h'|\niu'57
        !          4467: (gethash2 'num1 'num2 'db2) -- macro   \h'|\niu'57
        !          4468: (gethash3 'num1 'num2 'num3 'db2) -- macro     \h'|\niu'57
        !          4469: (gethash: 'slotnum 'defblock) -- macro \h'|\niu'57
        !          4470: (gethash:: 'slotnum 'defblock) -- macro        \h'|\niu'57
        !          4471: (gethash< 'slotnum 'defblock) -- macro \h'|\niu'57
        !          4472: (gethash> 'slotnum 'defblock) -- macro \h'|\niu'57
        !          4473: (gethashalias 'defblock) -- macro      \h'|\niu'57
        !          4474: (gethashinfo 'slotnum 'defblock) -- macro      \h'|\niu'57
        !          4475: (gethashvalue 'slotnum 'item 'defblock)        \h'|\niu'*
        !          4476: .sp
        !          4477: (gethookpath 'item 'path)      \h'|\niu'10
        !          4478: (getisa 'valblock) -- macro    \h'|\niu'57
        !          4479: (getpath 'item 'path)  \h'|\niu'10
        !          4480: (getpname 'defblock) -- macro  \h'|\niu'57
        !          4481: (getppset 'slotnum 'defblock) -- macro \h'|\niu'57
        !          4482: (getpred 'slotnum 'inst) -- macro      \h'|\niu'57
        !          4483: (getpredpath 'item 'path)      \h'|\niu'10
        !          4484: .sp
        !          4485: (getsinglevalue 'slotnum 'item)        \h'|\niu'*
        !          4486: (getslot 'slotnum 'inst) -- macro      \h'|\niu'57
        !          4487: (getslothooks 'slotnum 'inst) -- macro \h'|\niu'57
        !          4488: (getslotname 'slotnum 'defblock) -- macro      \h'|\niu'57
        !          4489: (getslottype 'slotnum 'defblock) -- macro      \h'|\niu'57
        !          4490: (getstructlength 'defblock) -- macro   \h'|\niu'57
        !          4491: (getstructorsymnum 'strsym) -- macro   \h'|\niu'57
        !          4492: .sp
        !          4493: (getsymbol 'symname)   \h'|\niu'4
        !          4494: (getsymbolpname 'symbolitem) -- macro  \h'|\niu'57
        !          4495: (getuniquenum 'defblock) -- macro      \h'|\niu'57
        !          4496: (getvalue 'slotnum 'inst)      \h'|\niu'57
        !          4497: (getvarandvalue 'slotnum 'inst 'var)   \h'|\niu'57
        !          4498: (getvarval 'slotnum 'inst) -- macro    \h'|\niu'57
        !          4499: .sp
        !          4500: (*global* varname) -- fexpr    \h'|\niu'46
        !          4501: (global variable) -- fexpr     \h'|\niu'45
        !          4502: (globalp 'variable)    \h'|\niu'45
        !          4503: (handlehookresult 'oldval 'newval) -- macro    \h'|\niu'**
        !          4504: (hashablevalue 'slotnum 'item 'defblock) -- macro      \h'|\niu'**
        !          4505: (hashslot) -- macro    \h'|\niu'**
        !          4506: .sp
        !          4507: (hidden 'command) -- macro     \h'|\niu'35
        !          4508: (higheroreq 'item1 'item2) -- macro    \h'|\niu'*
        !          4509: (history ['num])       \h'|\niu'53
        !          4510: (ind basename [storage] slot1 ...) -- macro    \h'|\niu'56
        !          4511: (indb 'item ['db])     \h'|\niu'14
        !          4512: (indb1 'item 'db)      \h'|\niu'14
        !          4513: (individual basename [storage] slot1 ...) -- macro     \h'|\niu'56
        !          4514: .sp
        !          4515: (inheritvalue 'structdef) -- macro     \h'|\niu'**
        !          4516: (inlinecreate selector ...) -- macro   \h'|\niu'14, 56
        !          4517: (inlinefetchcreate selector ...) -- macro      \h'|\niu'14, 56
        !          4518: (insertdb 'item ['db]) \h'|\niu'12
        !          4519: (insertdb1 'item 'db)  \h'|\niu'12
        !          4520: .sp
        !          4521: (insidecreate selector ...) -- fexpr   \h'|\niu'**
        !          4522: (insidefetch patdef expdefs) -- macro  \h'|\niu'**
        !          4523: (insidefetcheverywhere patdef expdefs) -- macro        \h'|\niu'**
        !          4524: (insidepatternize 'item)       \h'|\niu'**
        !          4525: (insidescopy 'item)    \h'|\niu'**
        !          4526: (installadjunct 'adjunctvar) -- macro  \h'|\niu'**
        !          4527: (installglobal 'globalvar) -- macro    \h'|\niu'**
        !          4528: (installvar 'varname) -- macro \h'|\niu'**
        !          4529: .sp
        !          4530: (instatom 'symbol)     \h'|\niu'7
        !          4531: (isa 'item1 'name)     \h'|\niu'42
        !          4532: (isanexpanded 'item1 'item2)   \h'|\niu'42
        !          4533: (islambda 'fcnname)    \h'|\niu'*
        !          4534: .sp
        !          4535: (match 'item1 'item2)  \h'|\niu'46
        !          4536: (msgprintfn '*printval*)       \h'|\niu'58, 62
        !          4537: (newnum) -- macro      \h'|\niu'*
        !          4538: (nextequal 'stream)    \h'|\niu'46
        !          4539: (nextitem 'stream)     \h'|\niu'13
        !          4540: (noalias) -- macro     \h'|\niu'**
        !          4541: .sp
        !          4542: (nullstruct 'item)     \h'|\niu'42
        !          4543: (nullsym 'item)        \h'|\niu'42
        !          4544: (numberofslot 'slotname 'defblock) -- macro    \h'|\niu'57
        !          4545: (onesymbol) -- macro   \h'|\niu'**
        !          4546: (ordatom 'symbol)      \h'|\niu'31
        !          4547: (ordinal name vallist) -- fexpr        \h'|\niu'30
        !          4548: .sp
        !          4549: (pat basename [storage] slot1 ...) -- macro    \h'|\niu'56
        !          4550: (path fcn 'item 'pathlist ['val]) -- macro     \h'|\niu'9
        !          4551: (pattern basename [storage] slot1 ...) -- macro        \h'|\niu'56
        !          4552: (patternize 'item) -- macro    \h'|\niu'55
        !          4553: (patternizeslot) -- macro      \h'|\niu'**
        !          4554: (pboundp 'a)   \h'|\niu'45
        !          4555: .sp
        !          4556: (pearlprintfn '*printval*)     \h'|\niu'3, 4
        !          4557: (pexp basename newname [storage] slot1 ...) -- macro   \h'|\niu'56
        !          4558: (pfunction name [storage] slot1 ...) -- macro  \h'|\niu'56
        !          4559: (pname 'item)  \h'|\niu'4
        !          4560: (ppsetform 'slotval 'ppsetname)        \h'|\niu'*
        !          4561: .sp
        !          4562: (prefix 'item1 'item2) \h'|\niu'52
        !          4563: (prefixcommandhistory) \h'|\niu'*
        !          4564: (prefixcommandvalue)   \h'|\niu'*
        !          4565: (printdb ['db])        \h'|\niu'21
        !          4566: (printdb1 'db) \h'|\niu'21
        !          4567: (psymbolp 'potsymbol)  \h'|\niu'30
        !          4568: (punbound)     \h'|\niu'45
        !          4569: .sp
        !          4570: (punboundatomp 'yyy)   \h'|\niu'*
        !          4571: (putalist 'alist 'inst) -- macro       \h'|\niu'*
        !          4572: (putalistcp 'alist 'inst) -- macro     \h'|\niu'*
        !          4573: (putbasehooks 'hooklist 'defblock) -- macro    \h'|\niu'*
        !          4574: (putdb1 'db1 'db) -- macro     \h'|\niu'***
        !          4575: (putdb2 'db2 'db) -- macro     \h'|\niu'***
        !          4576: (putdbchildren 'childlist 'db) -- macro        \h'|\niu'***
        !          4577: (putdbname 'name 'db) -- macro \h'|\niu'*
        !          4578: (putdbparent 'parent 'db) -- macro     \h'|\niu'***
        !          4579: (putdef 'defblock 'valblock) -- macro  \h'|\niu'***
        !          4580: (putdefaultinst 'valblock 'defblock) -- macro  \h'|\niu'***
        !          4581: (putenforce 'slotnum 'defblock) -- macro       \h'|\niu'***
        !          4582: (putexpansionlist 'explist 'defblock) -- macro \h'|\niu'***
        !          4583: (putformatinfo 'slotnum 'hashnum 'defblock) -- macro   \h'|\niu'***
        !          4584: (puthash* 'slotnum 'defblock) -- macro \h'|\niu'***
        !          4585: (puthash** 'slotnum 'defblock) -- macro        \h'|\niu'***
        !          4586: (puthash1 'num1 'db1 'item) -- macro   \h'|\niu'*
        !          4587: (puthash2 'num1 'num2 'db2 'item) -- macro     \h'|\niu'*
        !          4588: (puthash3 'num1 'num2 'num3 'db2 'item) -- macro       \h'|\niu'*
        !          4589: (puthash: 'slotnum 'defblock) -- macro \h'|\niu'***
        !          4590: (puthash:: 'slotnum 'defblock) -- macro        \h'|\niu'***
        !          4591: (puthash< 'slotnum 'defblock) -- macro \h'|\niu'***
        !          4592: (puthash> 'slotnum 'defblock) -- macro \h'|\niu'***
        !          4593: (puthashalias 'hashnum 'defblock) -- macro     \h'|\niu'***
        !          4594: (puthashinfo 'slotnum 'hashnum 'defblock) -- macro     \h'|\niu'***
        !          4595: (putisa 'isa 'valblock) -- macro       \h'|\niu'***
        !          4596: .sp
        !          4597: (putpath 'item 'path 'value)   \h'|\niu'10
        !          4598: (putpname 'name 'defblock) -- macro    \h'|\niu'***
        !          4599: (putppset 'slotnum 'setname 'defblock) -- macro        \h'|\niu'*
        !          4600: (putpred 'slotnum 'value 'inst) -- macro       \h'|\niu'*
        !          4601: (putslot 'slotnum 'value 'inst) -- macro       \h'|\niu'***
        !          4602: (putslothooks 'slotnum 'slothooklist 'inst) -- macro   \h'|\niu'*
        !          4603: (putslotname 'slotnum 'slotname 'defblock) -- macro    \h'|\niu'***
        !          4604: (putslottype 'slotnum 'typenum 'defblock) -- macro     \h'|\niu'***
        !          4605: (putstructlength 'size 'defblock) -- macro     \h'|\niu'***
        !          4606: (putsymbolpname 'name 'block) -- macro \h'|\niu'***
        !          4607: (putuniquenum 'num 'defblock) -- macro \h'|\niu'***
        !          4608: (putvarval 'slotnum 'value 'inst) -- macro     \h'|\niu'***
        !          4609: (reallitatom 'potatom) \h'|\niu'*
        !          4610: .sp
        !          4611: (releasedb 'db)        \h'|\niu'38
        !          4612: (removedb 'item ['db]) \h'|\niu'12
        !          4613: (removedb1 'item 'db)  \h'|\niu'12
        !          4614: (removeslot) -- macro  \h'|\niu'**
        !          4615: (revassq 'value 'alist)        \h'|\niu'*
        !          4616: (runbasehooks1 'fcn 'item)     \h'|\niu'33
        !          4617: (runbasehooks2 'fcn 'item1 'item2 'result)     \h'|\niu'33
        !          4618: (runslothooks1 'fcn 'item 'slotname 'value)    \h'|\niu'33
        !          4619: (runslothooks2 'fcn 'item1 'item2 'slotname 'val1 'val2)       \h'|\niu'33
        !          4620: .sp
        !          4621: (savecontinue 'directory 'name)        \h'|\niu'53
        !          4622: (savefresh 'directory 'name)   \h'|\niu'53
        !          4623: (savepearl)    \h'|\niu'*
        !          4624: (scopy 'item) -- macro \h'|\niu'55
        !          4625: (scopyslot) -- macro   \h'|\niu'**
        !          4626: (setblock blockname) -- fexpr  \h'|\niu'48
        !          4627: .sp
        !          4628: (setdbactive 'db) -- macro     \h'|\niu'***
        !          4629: (setdbsize 'poweroftwo)        \h'|\niu'39
        !          4630: (setv var 'val 'environment) -- fexpr  \h'|\niu'47
        !          4631: (slotequal 'slotnum 'item1 'item2)     \h'|\niu'*
        !          4632: (slotnametonumber 'slotname 'defblock) -- macro        \h'|\niu'**
        !          4633: (smerge 'build 'from)  \h'|\niu'55
        !          4634: .sp
        !          4635: (standardfetch 'item ['db])    \h'|\niu'43
        !          4636: (standardfetch1 'item 'db)     \h'|\niu'43
        !          4637: (standardmatch 'item1 'item2)  \h'|\niu'46
        !          4638: (streamp 'potstream)   \h'|\niu'30
        !          4639: (streamtolist 'stream) \h'|\niu'14
        !          4640: .sp
        !          4641: (strequal 'item1 'item2)       \h'|\niu'46
        !          4642: (structurenamep 'potname)      \h'|\niu'30
        !          4643: (structurep 'potstruct)        \h'|\niu'30
        !          4644: (symatom 'symbol)      \h'|\niu'4
        !          4645: (symbol name1 name2 ...) -- fexpr      \h'|\niu'4
        !          4646: (symbole 'symname)     \h'|\niu'4
        !          4647: (symbolnamep 'potname) \h'|\niu'30
        !          4648: .sp
        !          4649: (thawbindings 'struct) \h'|\niu'49
        !          4650: (thawblock 'blockname) \h'|\niu'49
        !          4651: (thawstruct 'struct)   \h'|\niu'49
        !          4652: (unbind globalvar) -- fexpr    \h'|\niu'45
        !          4653: (unbindvars 'structure) -- macro       \h'|\niu'46
        !          4654: (unboundatomp 'yyy)    \h'|\niu'*
        !          4655: .sp
        !          4656: (valform 'item)        \h'|\niu'20
        !          4657: (valprint 'item ['lmar ['rmar]])       \h'|\niu'20
        !          4658: (valprint1 'item 'lmar)        \h'|\niu'20
        !          4659: (valslotform) -- macro \h'|\niu'**
        !          4660: (valueof 'var 'struct) \h'|\niu'17
        !          4661: .sp
        !          4662: (*var* varname) -- fexpr       \h'|\niu'46
        !          4663: (varset 'var 'val) -- macro    \h'|\niu'*
        !          4664: (varvalue var 'val) -- fexpr   \h'|\niu'17
        !          4665: (visible 'command) -- macro    \h'|\niu'35
        !          4666: (vp 'item ['lmar ['rmar]])     \h'|\niu'56
        !          4667: (while 'val &rest 'body) -- macro      \h'|\niu'54
        !          4668: .fi
        !          4669: .bp
        !          4670: .nr PS 9
        !          4671: .nr VS 11p
        !          4672: .ps 9
        !          4673: .vs 11p
        !          4674: .NH
        !          4675: Concept Index
        !          4676: .LP
        !          4677: .nr PS 8
        !          4678: .nr VS 10p
        !          4679: .ps 8
        !          4680: .vs 10p
        !          4681: .nf
        !          4682: abbreviations                                                \ki55-56
        !          4683: accessing slots of structures  \h'|\niu'8-10
        !          4684: accessing structure default instances  \h'|\niu'7
        !          4685: accessing structure definitions        \h'|\niu'7
        !          4686: accessing symbols      \h'|\niu'4
        !          4687: .sp
        !          4688: adding slots to structures     \h'|\niu'40
        !          4689: adding to the data base        \h'|\niu'12
        !          4690: adjunct variables      \h'|\niu'30
        !          4691: affecting forced aliasing (^)  \h'|\niu'27
        !          4692: ako's (expanded structures)    \h'|\niu'40-42
        !          4693: .sp
        !          4694: aliasing of commands   \h'|\niu'51
        !          4695: aliasing in hashing    \h'|\niu'27
        !          4696: ampersand (&) hashing  \h'|\niu'26
        !          4697: and, in predicates     \h'|\niu'28
        !          4698: anti-aliasing in hashing (<)   \h'|\niu'27
        !          4699: *any*  \h'|\niu'15
        !          4700: automatic storing of structures        \h'|\niu'8, 56
        !          4701: .sp
        !          4702: base hooks     \h'|\niu'32-37
        !          4703: bases  \h'|\niu'5
        !          4704: blocks \h'|\niu'47-48
        !          4705: building structures    \h'|\niu'5
        !          4706: building upon data bases       \h'|\niu'38, 39
        !          4707: .sp
        !          4708: changing slots of structures   \h'|\niu'8
        !          4709: clearing data bases    \h'|\niu'39
        !          4710: colon (:) hashing      \h'|\niu'23
        !          4711: colon-colon (::) hashing       \h'|\niu'24
        !          4712: .sp
        !          4713: command aliasing       \h'|\niu'51
        !          4714: command history        \h'|\niu'51-53
        !          4715: command history, printing      \h'|\niu'53
        !          4716: compatibility functions (UCI, Franz)   \h'|\niu'58-62
        !          4717: .sp
        !          4718: controlling running of hooks   \h'|\niu'33-34
        !          4719: controlling results with hooks \h'|\niu'35
        !          4720: controlling unbinding of variables     \h'|\niu'48-49
        !          4721: converting from internal form  \h'|\niu'20
        !          4722: copy redefined \h'|\niu'54
        !          4723: copying structures     \h'|\niu'55
        !          4724: .sp
        !          4725: creating data bases    \h'|\niu'38, 39
        !          4726: creating patterns      \h'|\niu'15-16
        !          4727: creating base structures       \h'|\niu'5
        !          4728: creating individual structures \h'|\niu'6
        !          4729: creating symbols       \h'|\niu'4
        !          4730: .sp
        !          4731: data bases     \h'|\niu'11
        !          4732: data bases, building upon      \h'|\niu'39
        !          4733: data bases, clearing   \h'|\niu'39
        !          4734: data bases, creating   \h'|\niu'38
        !          4735: data bases, fetching from      \h'|\niu'12, 19, 25, 42, 43, 46
        !          4736: data bases, freeing    \h'|\niu'40
        !          4737: data bases, inserting into     \h'|\niu'12
        !          4738: data bases, printing   \h'|\niu'21
        !          4739: data bases, releasing  \h'|\niu'40
        !          4740: data bases, removing from      \h'|\niu'12
        !          4741: data bases, setting size of    \h'|\niu'39
        !          4742: .sp
        !          4743: debugging      \h'|\niu'21
        !          4744: debugging print        \h'|\niu'21
        !          4745: declaring global variables     \h'|\niu'45
        !          4746: .sp
        !          4747: default fetch function \h'|\niu'43
        !          4748: default instance for a structure       \h'|\niu'15
        !          4749: default instance, accessing    \h'|\niu'7
        !          4750: default match function \h'|\niu'46
        !          4751: default printing functions     \h'|\niu'20, 58, 60-61, 62
        !          4752: default values for slots       \h'|\niu'14-15
        !          4753: defaults, inherited    \h'|\niu'41-42
        !          4754: .sp
        !          4755: defining structures    \h'|\niu'5
        !          4756: defining symbols       \h'|\niu'4
        !          4757: definitions of structures, accessing   \h'|\niu'7
        !          4758: deleting from the data base    \h'|\niu'12
        !          4759: demons (hooks) \h'|\niu'32-37
        !          4760: .sp
        !          4761: disguising in path     \h'|\niu'10-11
        !          4762: disguising in predicates       \h'|\niu'29
        !          4763: don't-care matching variable   \h'|\niu'15
        !          4764: double-colon (::) hashing      \h'|\niu'24
        !          4765: double-star (**) hashing       \h'|\niu'24
        !          4766: dumping PEARL for later        \h'|\niu'53
        !          4767: .sp
        !          4768: efficiency despite variables   \h'|\niu'30
        !          4769: enumerated (ordinal) types     \h'|\niu'30
        !          4770: environment for variable evaluation    \h'|\niu'46-47
        !          4771: environment, top level \h'|\niu'51-53
        !          4772: environments, in hooks \h'|\niu'33
        !          4773: .sp
        !          4774: equality of structures \h'|\niu'46
        !          4775: equivalences of functions (UCI-Franz)  \h'|\niu'58-62
        !          4776: error messages \h'|\niu'21
        !          4777: evaluating function structures \h'|\niu'51
        !          4778: evaluating in create   \h'|\niu'22
        !          4779: expanded structures    \h'|\niu'40
        !          4780: expanded structures, fetching  \h'|\niu'42
        !          4781: .sp
        !          4782: feedback, sending      \h'|\niu'21
        !          4783: fetch, standard        \h'|\niu'46
        !          4784: fetching expanded structures   \h'|\niu'42
        !          4785: fetching from all buckets      \h'|\niu'19, 25
        !          4786: fetching from the data base    \h'|\niu'12 , 19, 25, 42, 43, 46
        !          4787: fetching with equality (not matching)  \h'|\niu'46
        !          4788: .sp
        !          4789: filling in special forms (in hooks)    \h'|\niu'33
        !          4790: for loop       \h'|\niu'54
        !          4791: forced aliasing (>)    \h'|\niu'26
        !          4792: forest of data bases   \h'|\niu'39-40
        !          4793: freeing data bases     \h'|\niu'40
        !          4794: freezing variables     \h'|\niu'48-49
        !          4795: .sp
        !          4796: function equivalences (UCI-Franz)      \h'|\niu'58-62
        !          4797: function structures    \h'|\niu'49-51
        !          4798: function structures, evaluating        \h'|\niu'51
        !          4799: getting symbols        \h'|\niu'4
        !          4800: global variables       \h'|\niu'45
        !          4801: greater-than (>) hashing       \h'|\niu'26
        !          4802: .sp
        !          4803: hash aliasing (&)      \h'|\niu'26
        !          4804: hash marking   \h'|\niu'17, 23-27
        !          4805: hashing problems       \h'|\niu'18
        !          4806: hashing with variables \h'|\niu'30
        !          4807: hiding functions from hooks    \h'|\niu'35
        !          4808: hierarchy of structures        \h'|\niu'40
        !          4809: .sp
        !          4810: history mechanism      \h'|\niu'51-3
        !          4811: history number, printing in prompt     \h'|\niu'53
        !          4812: hooks  \h'|\niu'32-37
        !          4813: hooks, affecting result with   \h'|\niu'35
        !          4814: hooks, controlling running of  \h'|\niu'33-34
        !          4815: hooks, hiding functions from   \h'|\niu'35
        !          4816: hooks, making functions visible to     \h'|\niu'35
        !          4817: hooks, multi-argument  \h'|\niu'28
        !          4818: hooks, running \h'|\niu'33-34
        !          4819: .sp
        !          4820: if-added functions (hooks)     \h'|\niu'32-37
        !          4821: indirection in path    \h'|\niu'10-11
        !          4822: individuals    \h'|\niu'6
        !          4823: inheritance in structures      \h'|\niu'41-42
        !          4824: (.)init.prl file       \h'|\niu'2-3
        !          4825: .sp
        !          4826: inserting in the data base     \h'|\niu'12
        !          4827: instances      \h'|\niu'6
        !          4828: integer slots  \h'|\niu'30
        !          4829: internal access functions      \h'|\niu'57
        !          4830: internal form printing \h'|\niu'21
        !          4831: .sp
        !          4832: invisible functions to hooks   \h'|\niu'35
        !          4833: invisible results from functions       \h'|\niu'53
        !          4834: isa's (expanded structures)    \h'|\niu'40-42
        !          4835: less-than (<) hashing  \h'|\niu'27
        !          4836: lexically scoped variables     \h'|\niu'47-48
        !          4837: .sp
        !          4838: looping functions      \h'|\niu'54
        !          4839: low level access functions     \h'|\niu'57
        !          4840: macros, special        \h'|\niu'56
        !          4841: main data base \h'|\niu'11
        !          4842: marking structures for hashing \h'|\niu'17, 23-27
        !          4843: .sp
        !          4844: match, standard        \h'|\niu'46
        !          4845: match, without unbinding variables     \h'|\niu'46
        !          4846: match-anything variable        \h'|\niu'15
        !          4847: matching process       \h'|\niu'44
        !          4848: matching two structures        \h'|\niu'43
        !          4849: matching unbound variables     \h'|\niu'44
        !          4850: matching-variables     \h'|\niu'16-17
        !          4851: .sp
        !          4852: merging structures     \h'|\niu'55
        !          4853: modified input line, printing  \h'|\niu'53
        !          4854: multi-argument matching predicates     \h'|\niu'28, 32
        !          4855: next item in a stream  \h'|\niu'13
        !          4856: nilstruct(ure) \h'|\niu'14
        !          4857: nilsym(bol)    \h'|\niu'14
        !          4858: .sp
        !          4859: or, in predicates      \h'|\niu'28
        !          4860: ordinal types  \h'|\niu'30-31
        !          4861: path functions \h'|\niu'10
        !          4862: path indirection       \h'|\niu'10-11
        !          4863: pattern-matching variables     \h'|\niu'16-17
        !          4864: .sp
        !          4865: patterns       \h'|\niu'12, 15, 43
        !          4866: patterns in matching   \h'|\niu'43
        !          4867: predicates for object types    \h'|\niu'30
        !          4868: predicates in matching \h'|\niu'27-29
        !          4869: predicates in matching, when run       \h'|\niu'44
        !          4870: predicates in matching, multi-argument \h'|\niu'28
        !          4871: .sp
        !          4872: print names    \h'|\niu'4
        !          4873: printing PEARL objects \h'|\niu'20
        !          4874: printing command history       \h'|\niu'53
        !          4875: printing data bases    \h'|\niu'21
        !          4876: printing functions     \h'|\niu'20
        !          4877: printing functions, standard   \h'|\niu'3-4, 58, 60-61, 62
        !          4878: printing history number in prompt      \h'|\niu'53
        !          4879: printing modified input line   \h'|\niu'53
        !          4880: printing warnings      \h'|\niu'17
        !          4881: .sp
        !          4882: processing a stream    \h'|\niu'13
        !          4883: prompt \h'|\niu'3-4
        !          4884: prompt-read-eval-print loop    \h'|\niu'2-3, 51
        !          4885: read-eval-print loop   \h'|\niu'2-3, 51
        !          4886: redirecting in create (! and $)        \h'|\niu'22
        !          4887: releasing data bases   \h'|\niu'40
        !          4888: removing from the data base    \h'|\niu'12
        !          4889: .sp
        !          4890: reporting bugs \h'|\niu'21
        !          4891: retrieving from the data base  \h'|\niu'12
        !          4892: returning invisible results    \h'|\niu'53
        !          4893: running hooks  \h'|\niu'33-34
        !          4894: running under Franz Lisp       \h'|\niu'2
        !          4895: running under UCI Lisp \h'|\niu'3
        !          4896: .sp
        !          4897: saving PEARL for later \h'|\niu'53
        !          4898: scalar types   \h'|\niu'30
        !          4899: short-circuiting in create     \h'|\niu'22
        !          4900: side effect setting of adjunct variables       \h'|\niu'30
        !          4901: size of data bases     \h'|\niu'39
        !          4902: .sp
        !          4903: slot hooks     \h'|\niu'32-37
        !          4904: slot names to numbers  \h'|\niu'57
        !          4905: slot types     \h'|\niu'6
        !          4906: slot types, more specific      \h'|\niu'30
        !          4907: slot values    \h'|\niu'8-10
        !          4908: slot values in hooks   \h'|\niu'32
        !          4909: slot values in predicates      \h'|\niu'28
        !          4910: .sp
        !          4911: special forms in hooks \h'|\niu'32
        !          4912: special forms in predicates    \h'|\niu'28
        !          4913: special forms, filling in      \h'|\niu'33
        !          4914: special macros \h'|\niu'56
        !          4915: standard fetch function        \h'|\niu'43
        !          4916: standard match function        \h'|\niu'46
        !          4917: .sp
        !          4918: star (*) hashing       \h'|\niu'17, 23
        !          4919: star-star (**) hashing \h'|\niu'24
        !          4920: (.)start.prl file      \h'|\niu'2-3
        !          4921: startup files  \h'|\niu'2-3
        !          4922: storing structures in the data base    \h'|\niu'12
        !          4923: storing of structures in atoms \h'|\niu'8, 56
        !          4924: streams        \h'|\niu'13
        !          4925: .sp
        !          4926: structure equality     \h'|\niu'46
        !          4927: structure matching     \h'|\niu'44-45
        !          4928: structure predicates   \h'|\niu'28-29
        !          4929: structure slots, further typing        \h'|\niu'30
        !          4930: structured escapes to Lisp     \h'|\niu'49-51
        !          4931: structures     \h'|\niu'5
        !          4932: structures, copying    \h'|\niu'55
        !          4933: structures, expanded   \h'|\niu'40
        !          4934: structures, function   \h'|\niu'49-51
        !          4935: structures, merging    \h'|\niu'55
        !          4936: .sp
        !          4937: symbols        \h'|\niu'4
        !          4938: testing for nilstruct  \h'|\niu'42
        !          4939: testing for nilsym     \h'|\niu'42
        !          4940: testing for object types       \h'|\niu'30
        !          4941: thawing variables      \h'|\niu'48-49
        !          4942: .sp
        !          4943: top level loop \h'|\niu'2-3, 51
        !          4944: top level loop functions       \h'|\niu'59, 62
        !          4945: triple (**) hashing    \h'|\niu'24
        !          4946: type tests for objects \h'|\niu'30
        !          4947: types in structure slots       \h'|\niu'31-2
        !          4948: .sp
        !          4949: unbinding global variables by match (lack of)  \h'|\niu'45
        !          4950: unbinding global variables by user     \h'|\niu'45
        !          4951: unbinding local variables by match     \h'|\niu'45-6
        !          4952: unbinding local variables by user      \h'|\niu'46
        !          4953: unbinding of variables, controlling    \h'|\niu'48-49
        !          4954: up-arrow (^) hashing   \h'|\niu'27
        !          4955: .sp
        !          4956: values of variables    \h'|\niu'17, 46
        !          4957: values of variables, setting   \h'|\niu'47
        !          4958: variables in hooks     \h'|\niu'32
        !          4959: variables in predicates        \h'|\niu'28
        !          4960: variables with hashing \h'|\niu'30
        !          4961: variable, accessing values     \h'|\niu'17, 46
        !          4962: variables, adjunct     \h'|\niu'30
        !          4963: variables, controlling unbinding       \h'|\niu'48-49
        !          4964: variables, freezing    \h'|\niu'48-49
        !          4965: variables, global      \h'|\niu'45
        !          4966: variables, lexically scoped    \h'|\niu'47-48
        !          4967: variable, setting values       \h'|\niu'47
        !          4968: variables, side effects        \h'|\niu'30
        !          4969: variables, thawing     \h'|\niu'48-49
        !          4970: variables, unbinding   \h'|\niu'46
        !          4971: .sp
        !          4972: visible functions to hooks     \h'|\niu'35
        !          4973: warnings       \h'|\niu'17
        !          4974: while loop     \h'|\niu'54
        !          4975: .fi
        !          4976: .nr PS 10
        !          4977: .nr VS 12p
        !          4978: .ps 10
        !          4979: .vs 12p
        !          4980: .bp 0
        !          4981: .DS C
        !          4982: .LG
        !          4983: \fBTable of Contents\fR
        !          4984: .SM
        !          4985: .DE
        !          4986: .DS L
        !          4987: 1.  Introduction                                                                                           \ka  1
        !          4988: 2.  Running PEARL               \h'|\nau'  2
        !          4989:       2.1.  Under Franz Lisp    \h'|\nau'  2
        !          4990:       2.2.  Under UCI Lisp      \h'|\nau'  3
        !          4991: 3.  Creating Simple Objects     \h'|\nau'  4
        !          4992:       3.1.  Defining Symbols               \h'|\nau'  4
        !          4993:       3.2.  Defining Structures            \h'|\nau'  5
        !          4994: 4.  Creating Individual Instances of Defined Structures \h'|\nau'  6
        !          4995: 5.  Accessing Slots of Structures \h'|\nau'  8
        !          4996: 6.  Storing In and Retrieving From the Data Base -- The Simplest Way \h'|\nau'11
        !          4997:       6.1  Storing In the Data Base: \fIInsertdb\fR and \fIRemovedb\fR\h'|\nau'11
        !          4998:       6.2  Retrieving Hash Buckets From the Data Base: \fIFetch\fR \h'|\nau'12
        !          4999:       6.3  Accessing the Results of \fIFetch\fR: \fINextitem\fR \h'|\nau'13
        !          5000: 7.  The Default Values for Unspecified Slots \h'|\nau'14
        !          5001: 8.  Using \fIPattern\fRs For More Flexible and Powerful Retrieval \h'|\nau'15
        !          5002: 9.  Marking Structures During Creation For More Efficient Retrieval \h'|\nau'17
        !          5003: 10. Printing Structures, Symbols and Other PEARL Objects \h'|\nau'20
        !          5004: 11. Error Messages, Bugs, and Error Handling Abilities \h'|\nau'21
        !          5005: 12. Short-Circuiting and Redirecting \fICreate\fR Using !, $ and Atoms \h'|\nau'22
        !          5006: 13. More Flexible Hash Selection \h'|\nau'23
        !          5007: 14. Using Predicates to Constrain Fetching \h'|\nau'27
        !          5008: 15. More Useful Slot Types \h'|\nau'30
        !          5009: 16. Attaching Hooks to Structures (If-Added Demons) \h'|\nau'32
        !          5010: 17. Creating and Manipulating Multiple Data Bases \h'|\nau'38
        !          5011: 18. Creating a Forest of Data Bases \h'|\nau'39
        !          5012: 19. Creating Expanded Subtypes of Previously Defined Objects \h'|\nau'40
        !          5013: 20. Fetching Expanded Structures \h'|\nau'42
        !          5014: 21. How Two Objects \fIMatch\fR \h'|\nau'43
        !          5015:       21.1  When Is a Pattern not a \fIPattern\fR? \h'|\nau'43
        !          5016:       21.2  The Matching Process \h'|\nau'44
        !          5017: 22. Binding Blocks of Structures Together Via Common Variables \h'|\nau'47
        !          5018: 23. Controlling the Unbinding of Variables by \fIMatch\fR \h'|\nau'48
        !          5019: 24. Function Structures \h'|\nau'49
        !          5020: 25. More About the PEARL Top Level Loop and History Mechanism \h'|\nau'51
        !          5021: 26. Looping and Copying Functions \h'|\nau'54
        !          5022: 27. Miscellaneous Variations and Abbreviations \h'|\nau'55
        !          5023: 28. Low Level Access Functions \h'|\nau'57
        !          5024: 29. Appendix of UCI Lisp functions added to Franz PEARL \h'|\nau'58
        !          5025: 30. Appendix of Franz Lisp functions added to UCI Lisp PEARL \h'|\nau'62
        !          5026: 31. Bibliography \h'|\nau'63
        !          5027: 32. Index of Global Variables and Functions With Their Arguments \h'|\nau'64
        !          5028: 33. Concept Index \h'|\nau'71
        !          5029: .DE

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.