* AI FUNCTIONS match, mgu, DEFschema, forward-chain, bchain, save-world, 
  DEFrule, interpret, find, assert, deny, how, why, DEFviewpoint, DEFhypothesis

   (HELP 'symbol) PROVIDE HELP ON GIVEN FUNCTION OR TOPIC
      symbol   function name or topic
      HELP provides printed text on how to use a given function
      or provides definition of terms or categories.  The * line above
      names related subjects.   This text file is input to the HELP function.
  
   (AI)  ARTIFICIAL INTELLIGENCE  
      use help on above functions
 
   (EXPERT) EXPERT SYSTEMS 
      use help on above functions

* SYNTAX AND TOPICS TO DO WITH IMPLICATOR(c) fact pattern data predicate
variable wildcards rule argument grammers parser network inference connectives

   (CONNECTIVES)  OPERATORS TO COMBINE ATOMIC FORMULAS
      Implicator builds more complicated formulas from atomic formulas
      by combining them with so called connectives.  So, if p and q
      are formulas in the language, then (and p q), (or p q),
      !p [not p], and p -> q are also formulas.  P and q can be any
      facts or propositions and thus describes the general case.  This
      is similar to the use of variables in standard mathematical 
      arguments.  For example: "let n be a number, the 2n will be an
      even number".  However, p and q range over statements in the
      predicate calculus rather than numbers.  Implicator allows several
      methods for implementing connectives and a few cases follow.
      (and p q)    ---  (defrule r1  p q  -> z)
      (or  p q)    ---  (defrule r1.1 p   -> z)
         (defrule r1.2 q   -> z)
      !p      ---  (not (present p))
      p -> q   ---  (defrule r1  p -> q)
      There are numerous other ways to build compound formulas in 
      Implicator.      

   (INFERENCE)  THE PROCESS OF GENERATING NEW FACTS
      To draw an inference is to create a new fact on the basis of
      other facts.  There are many kinds of inference.  The best
      understood is deduction.  Deduction is logically correct inference.
      This means that a deduction from true facts is guaranteed to result
      in a true conclusion.  Types of inference supported by
      Implicator are transitivity, inheritance, abduction, 
      universal and existential quantification, implication, 
      modus ponens, universal instantiation, unification. 
      See match, mgu, forward-chain, fc-with-agenda, present, find.

   (TRANSITIVITY)       A TYPE OF INFERENCE
      Transitivity inference says that if thing X is related to thing Y
      and thing Y is related to thing Z, then thing X is related to
      thing Z in the same way.  For example:
      -
      (defrule transitive
           (related $x $y)
           (related $y $z)
          ->
           (related $x $z)) 
      -
      Transitive rules involve predicates of type RELATION_P.

   (INHERITANCE)        A TYPE OF INFERENCE
      Inheritance always involves two types of predicates, RELATION_P
      and PROPERTY_P.  Inheritance frequently occurs when the 
      relationship predicate is "a-kind-of" or "is-a".  Inheritance
      deals with specific traits or properties that are contained in
      a "class" of objects.  A specific "instance" of a class will
      inherit those class traits or properties.  Inheritance works
      also for sub-classes of a class.  For example, all airplanes
      possess the property or trait of having a wing.  Jets, by virtue
      of their being a type of airplane inherit the property of 
      possessing a wing.  An F18, by virtue of its being a jet, inherits
      the property of possessing a wing.
      -
      (defrule inheritance
           (related  $x $y)
           (property $x $property_value)
          ->
           (property $y $property_value))
      -
      Inheritance is often associated with transitivity, because
      Implicator actually follows a transitivity chain to follow
      an inheritance chain. See TRANSITIVITY, SCHEMA.

   (IMPLICATION)        A LOGICAL OPERATION RANGING OVER FORMULAS
      In predicate calculus, a truth value connective.  Its truth
      table, with p and q being valid predicates ranging over statements
      of fact in the Short Term Memory, is as follows:
      p   q   p -> q
      t   t     t
      t   f     f
      f   t     t
      f   f     t
      p -> q, is the same as "p implies q" or "if p then q" or "p is
      sufficient for q and q is necessary for p".  "IF" is a truth
      value connective and has no connotation of causation.

   (MODUS_PONENS)       A TYPE OF INFERENCE
      Modus ponens is the mathematical term for deduction.  
      From:   p  and (defrule rule p -> q)
      infer:  q
      Forward-chaining is a generalization of Modus Ponens using
      implicit quantification.
      From:   p' and (defrule rule p -> q)
      infer:  q'
      p UNIFIES with p' and a resulting substitution is applied to
      q to give q'.
      Implicator 'implicitly' quantifies an expression by unification
      of the variables in a rule with facts from Short Term Memory.
      This is allowable (or logically correct) by the law of universal
      instantiation.
      See FORWARD-CHAIN, UNIFICATION, MATCH, MATCHES, FIND, PRESENT,
      PROLOG, UNIVERSAL_INSTANTIATION.

   (UNIVERSAL_INSTANTIATION)  A TYPE OF INFERENCE
      If something is true of everything, then it is true for one
      specific thing.

   (ABDUCTION)      A TYPE OF INFERENCE
      Abduction is the process that generates explanations.
      From:   q  and (defrule rule p -> q)
      infer:  p
      Unlike deduction, abduction is not a legal inference.  Abduction
      allows false conclusions.  Medical diagnosis is really just the
      careful use of abduction.  Abduction assumes a causation to 
      implication.  When it is said that someone "understands" a story,
      it is typically meant that the correct explanatory facts were
      abduced.  See BCHAIN.

   (QUANTIFICATION)      A TYPE OF INFERENCE
      There are two types of useful quantification that are inherent
      in Implicator.  Universal and existential quantification.
      Universal quantifiers say that something is true for all 
      possible values of a variable.  See FORALL.
      Existential quantification says that there is a value present
      for which p is true.  See PRESENT, ALLPRESENT.

   (FACT) A LOGICAL or DECLARITIVE STATEMENT
      A fact is made up of one or more formulas of the form:
      (predicate [arg0] ... [argN])
      It is declaritive in nature.  Although implemented as a lisp list,
      it is usually considered atomic.  Conjunctive and Disjunctive
      connectors are used to build larger structures called topics or
      scripts.  Implicator is unique among expert system shells in that
      it allows the use of second order predicate calculus. 
      See predicate, formula, pattern.

   (FORMULAS) THE ATOMIC UNITS OF IMPLICATOR
      The formulas of Implicator are:
      * A predicate applied to the correct number of terms
      * If p and q are formulas then:
        p -> q     p and q   p or q   !p   !q
      See fact, predicate, pattern, inference, connectors,
      predicate_calculus, match, present, forall, mgu.

   (PATTERN) A TEMPLATE DESCRIBING A FACT OR FACTS
      The template is used to describe a set of facts in short term 
      memory.  It is used in the inference engines and in some short
      term memory functions to manipulate the database.  Symbols used in
      the pattern symbols are:
      *    =  wildcard, i.e.  (a * z) matches (a b c d e ... x y z)
      ?    =  wildcard, i.e.  (a ? c) matches (a b c)
      $x   =  a variable binding, i.e. (a $x c) with (a b c) binds b to
          $x
      $$x   =  a list binding, i.e. (a $$x) with (a b c) binds (b c) to
          $$x
      !atom =  a ! in front of an atom tells the matcher it is anything
          but that atom (or term). 

   (VARIABLES) SYMBOLS USED IN PATTERNS WHICH ARE INPUT TO AI FUNCTIONS
      $variable_name  = atom variable, i.e. (a $x)  matches (a b)
      $$variable_name = list variable, i.e. (a $$x) matches (a b c d ..)
      Variables are used in patterns and in antecedent or conditional
      facts in rules. They are local in the scope of rules.
      The first instance of the variable in a match assigns the value
      of the data to the variable. On subsequent occurances of the
      variable, the matcher substitues the initial binding for the
      variable in the pattern and continues.  For Example, Given:
      -
      (defrule example 
           (The value is $X)
          ->
           ($x is not bound here, but substituted)
           ($x was bound in the antecedent))
      -
      (assert (The value is 5))  ;ADD TO SHORT TERM MEMORY
      (forward-chain)      ;INVOKE FORWARD CHAINER
      (pstm)          ;CHECK THE RESULTS
      -     
      1: (5 was bound in the antecedent)     ;THE RESULTS
      2: (5 is not bound here, but substituted)   ;   .
      3: (The value is 5)          ;   .
      -
      See also defrule, matches, flush, present, allpresent, pattern.

   (WILDCARDS) SYMBOLS USED IN PATTERNS WHICH ARE INPUT TO AI FUNCTIONS
      *    =  wildcard, i.e.  (a * z) matches (a b c d e ... x y z)
      ?    =  wildcard, i.e.  (a ? c) matches (a b c)
      Wildcards are used in patterns of lists that are input to
      functions such as matches, flush, present, allpresent.  They
      are also used in antecedent or conditional facts in rules.
      See also defrule, matches, flush, present, allpresent, pattern.

   (RULE)   A STRUCTURE DEFINING ACTIONS FOR GENERALIZED SITUATIONS
      Often referred to as situation-action rules or LONG TERM MEMORIES.
      Defined using defrule or inferred using learnfrom, and manipulated
      with a series of defined operations. 
      (see Defrule learnfrom).  The syntax is:
      (rulename 
      (if   ([(pattern) | (fact)] ...[(pattern) | (fact)])
      (then ([(fact) | (fact)])))
      It is the primary declaration of generalize knowledge.

   (PREDICATE) A LIST THAT DECLARES A FACT OR IDEA.
      A predicate is simply something that asserts a fact about one or
      more entities.  An 'entity' is simply something (an object) that
      exists in some form or another.  Entities are modelled very well
      using schemas (see SCHEMA). Predicates are descriptive of a   
      premise that is asserted by the formula and modifies or is 
      modified by their arguments.  To be strictly formal, a predicate
      must be a member of the set of all legal predicates.  Arguments
      must be filled by a term.  A predicate plus the proper number
      of arguments (terms) is the simplest kind of formula, called
      an atomic formula.  There are five types of standard predicates:
      1. type     see type_p
      2. property     see property_p
      3. relationship  see relation_p
      4. database     see database_p
      5. probability   see probability_p
      Predicates have the form (predicate arg1 ... argN).  

   (TYPE_P)  TYPE PREDICATE
      Type predicates have one argument which is a thing.  The predicate
      gives the class the thing belongs to. 
      i.e. (class thing)  or (ship tarawa)

   (PROPERTY_P) PROPERTY PREDICATE
      Property predicates have two arguments which are a thing and a 
      property.  This predicate states a property of the thing.
      i.e. (property_name thing property_value) or
       (color tarawa grey) or (location tarawa 14N35E)

   (RELATION_P) RELATIONSHIP PREDICATE
      Relationship predicates have two arguments which are things.  This
      predicate establishes a relationship between two things.  
      i.e. (relationship thing thing) or
      (a_kind_of tarawa ship) or (is_a tarawa ship)
      The last fact means "Tarawa is a ship" and is semantically the
      same as (ship tarawa) but syntactically different.  "Kind_of",
      "part_of" and "is_a" relationships are frequently modelled using
      type predicates.  See type_p.

   (DATABASE_P) DATABASE PREDICATE
      Database predicates have one or more arguments.  This is a sort
      of information record where the template can be user established.
      i.e. (record_type field1 field2 ... fieldn) or
      (ship tarawa gray 14N35E)

   (PROBABILITY_P) PROBABILITY PREDICATE
      Probability predicates consist of a predicate of which the first
      part is one of any of the other types of predicates with a
      probability of the fact being true.
      i.e. ((predicate) probability)
      Probability predicates are one method of dealing with uncertainty.
      The probability itself must be between 0.0 and 1.0
 
   (PREDICATE_CALCULUS)  A CALCULUS USED TO GENERATE FACTS
      The language of the calculus consists of:
      * A set of constant terms
      * A set of variables
      * A set of predicates, each taking a specified # of arguments
      * A set of functions,  each taking a specified # of arguments
      * The connectives 'if' 'and' 'or' and 'not'
      * The quantifiers 'exists' and 'forall'
      The terms of the language consist of:
      * constant terms
      * variables
      * functions applied to the correct # of arguments
      The formulas of the language are:
      * A predicate applied to the correct number of terms
      * p and q are formulas then:
      p -> q     p and q   p or q   !p   !q

   (SCHEMA)  A FRAME BASED METHODOLOGY FOR ENTITY REPRESENTATION 
      A schema is a template for knowledge representation using
      frames or slots that are named.  An instantiation of a schema
      consists of a template of frames or slots with values stored
      in the frames or slots.  An instance of a schema may inherit
      slots and slot values from another instance of a schema.
      See DEFSCHEMA, GETSLOT, PUT-SLOT-VALUE, GET-SLOT-VALUE,
      FACTS<-SLOTS.

   (GRAMMERS) A SERIES OF REWRITE RULES USED TO GENERATE SENTENCES 
      A standard way to formalize knowledge of the structure of
      a language by providing a series of rewrite rules.  The
      rules consist of nonterminal nodes (or constituents) and
      terminal nodes (the actual input stream or sentence).  A
      nonterminal node is one that appears only in the interior
      of a parse tree structure.  Terminal nodes are 'terminal'
      leafs of the parse tree.  Parsers use grammers to analyze
      input streams by creating parse trees which diagram the
      constituents of the input stream.  See also parser, atn,
      defnet, defword, analyzetree, reducetree, squash.

   (CONSTITUENT) A TERMINAL OR NONTERMINAL NODE IN A PARSED INPUT STREAM
      See grammers, parser, atn, analyzetree.

   (POP-11)  AI LANGUAGE, EDINBOURGH, SCOTLAND
      Algol like syntax with prolog and lisp interface.  Successor of
      POP, and POP-2.  It is a stack driven interpreter.  Pretty neat.

* AUGMENTED TRANISITION NETWORK PARSER  DEFnet, atn, DEFfeature, defword
reducetree, analyzetree, prttree

   (ATN *input* *agenda*) PARSE INPUT USING STARTING NETNAME
      *input*     The input sentence - a nonlocal variable.
      *agenda* -   The the first action to parse the grammer.
      Frequently, a typical action is (parse language) where
      language is a name of a Network defined by defnet.
      Returns true or false for condition of the parse.
      If true, as a side-effect, builds a parse tree in *parsetree* 
      to be manipulated by PRTTREE, ANALYZETREE and SQUASH.
      See INTERNALS_ATN for the ATN algorith.

   (INTERNALS_ATN)     THE OPERATIONAL ALGORITHM USED BY THE ATN PARSER
      The ATN algorithm:
      loop: Until either no more actions on actions or an action fails.
      Remove first action from actions and eval it.
      case: category, word, peek, = etc: If test
      is successful, then continue.
      otherwise report failure to atn.
      seq:   Put all of the subactions on front of actions.
      either: pick one of the possibilities "at random"
      and put it on the front of actions.
      For each alt action, store a choice-point 
      with (a) current INPUT STREAM
      (b) the alt action added to actions.
      parse:  Add a done action to actions.  Put the network
      associated with the constituent to be parsed
      on actions.
      done:   The parser has completed a constituent.  If 
      there are not further actions, then, 
      if INPUT STREAM is empty, report back success,
      else if INPUT STREAM has things left on it,
      report back failure.

   (REDUCETREE tree) STRIPS NONTERMINALS FROM PARSE TREE
      returns a tree of terminal symbols only

   (ANALYZETREE tree) STRIPS TERMINALS AND NONTERMINALS FROM PARSE TREE
      returns a tree of the lowest level nonterminal symbols only

   (SQUASH tree) FLATTENS A TREE
      returns a linear list of symbols

   (DEFNET net-name network)  DEFINE A NETWORK TO THE ATN PARSER
      net-name   The name of the network
      network   the network consists of statements of control
      functions and tests on arcs. For example:
      (defnet sentence (seq (parse noun_phrase)(parse verb_phrase))) 

   (DEFFEATURE dimension  default-values  other-values) DEFINE DIMENSIONS
      dimension      the feature or dimension allowed terminal symbols 
      default-values  default value of the feature or dimension
      other-values   other allowable values of the feature or dimension
      The parser uses dimensions and features to understand the context
      of the defined grammer.

   (DEFWORD word root-form type-of-terminal-symbol &rest features)
      word       A terminal word in the grammer
      root-form   The root-word tested by WORD
      type-of-terminal The terminal type tested by CATEGORY
      features    The (feature value) (feature value) ....
      the legal features of the terminal symbol defined by DEFFEATURE
      The *dictionary* stores each allowable word of the grammer,
      its part of the grammer, any nondefault values for its features
      and presumably something about its meaning.  DEFWORD defines
      and records the legal allowable words of the grammer.  
      DEFSEMANTICS defines its meaning.
   
* AUGMENTED TRANISITION NETWORK PARSER   *** flow of control functions ***
  seq, either, optional, and optional*    

   (SEQ -tests-)   SEQUENCE OF NODES   
      -tests-  tests on arcs (i.e. category, parse, peek & word)
      The connective SEQ is used to represent a sequence of nodes
      each of which has only one test.  For example:
      (seq (parse Noun_phrase) (parse Verb_phrase))

   (EITHER -tests-) DECISION POINT COMING OUT OF ONE NODE
      -tests-  tests on arcs (i.e. category, parse, peek & word)
      The connective either is used when there are several tests
      coming out of one node.  For example:
      (either (category proper-noun) (category pronoun))

   (OPTIONAL* -tests-) 
      -tests-  tests on arcs (i.e. category, parse, peek & word)
      used to test for something in the input that may or not occur
      more than once.  (See optional).

   (OPTIONAL -tests-) 
      -tests-  tests on arcs (i.e. category, parse, peek & word)
      used to test for something in the input that may or not be there
      OPTIONAL* is used if it may occur more than once

* AUGMENTED TRANISITION NETWORK PARSER   *** context-free test on arcs ***
  category, parse, peek, and word

   (CATEGORY terminal-symbol) TEST NEXT INPUT AS A TYPE "terminal-symbol" 
      terminal-symbol   previously defined in defword
      the parser checks to see if the next symbol in the input
      stream is of type terminal-symbol.  If true, the parse continues
      and the symbol in the input stream is consumed.

   (PARSE nonterminal-symbol) TEST INPUT FOR A NONTERMINAL TYPE
      nonterminal-symbol    previously defined by defnet
      The parser goes to the sub-network named by the nonterminal-symbol
      and follows it to finish parsing.

   (PEEK terminal-symbol)    LIKE CATEGORY BUT DOES NOT CONSUME INPUT
      terminal-symbol   previously defined using defword
      Next word of input is a terminal-symbol

   (WORD keyword)       TESTS INPUT TO SEE IF INPUT HAS ROOT keyword
      keyword      previously defined by defword

* AUGMENTED TRANISITION NETWORK PARSER  DEFnet, atn, DEFfeature, defword

   (THE dimension of constituent)

* AUGMENTED TRANISITION NETWORK PARSER topics of interest and definitions 
  network parser transition    

   (NETWORK)  see transition

   (PARSER)  a machine that syntactically analyzes complex knowledge
      structures.  The rules used in the analysis are referred to as
      the grammer, or grammatical structure of the objects to be
      analyzed.  Certain knowledge structures (such as English) contain
      knowledge in its "fuctional structure".  Therefore parsing also
      allows semantic inferences to be deduced.  Grammers (the group
      of rules or syntax), specify the legal syntactic structures for
      a knowledge representation system.  See grammers, parse_tree, atn.

   (PARSE_TREE) A DATA TYPE CONTAINING STRUCTURE KNOWLEDGE OF A LANGUAGE 
      In the tree, each nonterminal constituent is attached to lower
      constituents via lines and this indicates how it was structured.
      See constituents, parser, grammers, prttree, analyzetree, atn.

   (TRANSITION NETWORK)  a system for mapping grammers using arcs (or
      transitting paths) and nodes (which are discrete and measurable
      states in the parsing process).  Nodes, or states, are
      transitioned thru along arcs using test terms (category, parse,
      peek, and word) and flow-of-control terms (seq, either, optional,
      and optional*) in a textual representation of the system.
      A good reference is "Introduction to Artificial Intelligence",
      Charniak and McDermott,Addison-Wesley Publishing Co. 1986 
          
* INFERENCE ENGINES match matches mgu 

   (MATCH '(pattern) '(data) [(symboltable)])  MATCH A PATTERN WITH A FACT
      (pattern)    a list of which    $x = variable   *,? = wildcards and
      !value = not some value  and   $$x = a list variable.
      (data)   the list of which a pattern is matched with
      (symboltable) the table of variable value pairs associated with a
      match.
      returns true/ variable-value pairs if matched
      or nil if not a match.

   (MATCHES '(pattern) '(data)) MATCHES A PATTERN WITH A FACT
      (pattern)    same as match
      (data)       same as match
      behaves like match except it globally interns the variables with
      their assigned values from the match if it is a match as a side
      effect.
      returns true if a match or false otherwise.

   (MGU '(fact) '(fact))  FIND THE MOST GENERAL UNIFIER OF TWO EXPRESSIONS
      (fact)   a list where atoms beginning with '$' are variables
      returns the Most General Unifier of the two facts or null if
      unable to unify the two facts.  See INTERNALS_UNIFY for further
      details on the unification algorithm used.

   (INTERNALS_UNIFY)  THE UNIFICATION ALGORITHM USED BY IMPLICATOR
      input:   t1 and t2,  two terms to be unified, i.e.(MGU t1 t2).
      output:  theta, the most general unifier of t1 and t2, or nil
      -
      Initialize theta to nil, the stack to the equation t1 = t2,
      and failure to false.
      While stack not empty and not failure do:
      -
      pop x = y from the stack
      case 
      x  is a var that does not occur in y:
      substitute y for x in the stack and in theta
      add x = y to theta.
      y  is a variable that does not occur in x:
      substitute x for y in the stack and in theta
      add y = x to theta.
      x and y are identical constants or variables:
      continue.
      x is f(x1, ... , xN) and y is f(y1, ... , yN)
      for some functor f and n > 0:
      push xi = yi, i = 1, ... , N on the stack.
      otherwise  failure = true.
      if failure, then output failure else output theta.

* SCHEMA FUNCTIONS  DEFschema getslot put-slot-value make-object
   DEFrelation fact(-slots DEFmessage DEFmethod DEFdemon send-message

   (DEFSCHEMA sym sym [([(sym value)|sym] ...)]) DEFINE SCHEMA
      sym  name of the schema being DEFined.
      sym  super class that the schema belongs to 
      (sym value)  slot name and DEFault slot value in schema
      sym  slot name in schema
      This is a special form, all sym's are unquoted.

   (GETSLOT 'sym 'sym)   GET THE SLOT VALUE OF SCHEMA SLOT
      sym  schema name
      sym  slot name
      returns the value of the schema's slot.

   (GET-SLOT-VALUE 'sym 'sym)   GET THE SLOT VALUE OF SCHEMA SLOT
      sym  schema name
      sym  slot name
      returns the value of the schema's slot.

   (PUT-SLOT-VALUE 'sym 'sym value) PUT VALUE INTO SCHEMA SLOT  
      sym  schema name
      sym  slot name
      value the value to plug in the slot
      returns t

   (MAKE-OBJECT 'sym ['(sym value) ...]) INSTANTIATE A SCHEMA
      sym    schema name
      sym    slot name
      value  slot value
      returns a unique instance of a schema (an object)

   (DEFRELATION 'sym 'relation 'sym) DEFINE A RELATION ON OBJECTS
      sym      an instantiated schema
      relation the relation 
      sym      an instatiated schema
      The relation is not reflexive, that is, if A r B, it does not
      necessarily follow that B r A.
      DEFines a relation from object one onto object two.

   (FACTS<-SLOTS 'sym)  TRANSLATE SLOT/FRAME REPRESENTATION TO FACTS
      sym          an instatiated schema
      Translates slot/frame representation of a schema to fact form used
      by the inference engines.  See make-object on how to instantiate
      schemas.

   (DEFMESSAGE (:sym1 sym2) (arg-list) (expression)) DEFINE A MESSAGE 
      sym1         the message handle (convention to use : as first char)
      sym2         the schema the message belongs to  
      (arg-list)   the argument list
      (expression) the closure
      Objects may perform operations using messages/methods.
      Special form, sym's are not quoted.

   (DEFDEMON :sym1 keyword :sym2) DESIGNATE A MESSAGE AS A DEMON
      sym1      the name of the message to become a demon
      keyword   either :before or :after
      sym2      the message that will invoke the demon
      Demons are messages that are activated before or after a message
      is sent to an object.  Multiple demons may be invoked before,
      after, or during the sending of a single message.
      Demons may also invoke other demons.

   (SEND-MESSAGE 'sym :message [argument ...]) SEND AN OBJECT A MESSAGE
      sym          an instance of a schema
      message      the message priorly DEFined with DEFMESSAGE
      argument     the arguments of the message
      Sending a message causes an object to invoke a method to
      perform some action.  Using message passing, schema's are
      no longer considered passive data structures.
 
* FORWARD CHAINER FUNCTIONS forward-chain fc-with-agenda bchain abduce
  
   (FORWARD-CHAIN [(number)]) INVOKE FORWARD CHAINING INFERENCE
      (number)    optional number of cycles to forward chain
      forward chains matching assertions with rules until (number)
      of cycles or until no more assertions can be inferred

   (FC-WITH-AGENDA)  INVOKE AGENDA BASED FORWARD CHAINING
      Forward chains using agenda based candidate rules for 
      matching.  Forward chains until agenda is empty.
      Faster than FORWARD-CHAIN but, *** caution ***
      CAN MISS A VALID INFERENCE.  FORWARD-CHAIN WILL NOT.

   (BCHAIN '(fact))   FORWARD CHAIN BACK TO A CONCLUSION
      (fact)     the fact to begin forward chaining on.
      For Each Rule, Invert the antecedents and consequences,
      then forward chain starting with the argument.
      Prints all inferences arrived at by doing this.
      Is only temporary.  Typing (continue) restores world to
      conditions before BCHAIN was invoked.  ABDUCTION.
      Can be incorporated into a viewpoint.  Caution, abduction
      is not a valid inference.  Some conclusions arrived at by
      this process may be false.
      
   (ABDUCE '(fact) '(pattern)) ABDUCE FROM THE FACT - PATTERN MATCH
      (fact)     the fact to abduce from.
      (pattern)   the pattern to search for.
      For each rule, invert. Then forward chain starting with the
      arguments.  Finds all facts matching the pattern that can be
      abduced.
      CAUTION --- Not a valid inference.  See ABDUCTION.
      All facts found are stored in the global variable 'them'.

   (LEARNFROM iset fset) INFER RULES THAT WILL MAP AN ISET ACROSS FSET
      iset   the initial set of facts
      fset   the set of facts generated by forward-chaining
      Returns all rules that can be inferred to map the iset of facts
      across the conclusion set.  

   (ABSTRACT-RULE rule rule) INFER A MORE GENERAL RULE FROM TWO RULES
      rule   a properly defined rule
      Returns a rule that is a generalization of a common thread in
      the two rules or nil if no common thread can be found.

   (GENERALIZE)  CREATE GENERAL RULES FROM LTM (ONE PASS)
      Learns all general rules by identifying common threads between
      rules.  Makes one pass over the rules. Returns t if able
      to find a new rule or nil if unsuccessfule.


   (GENERALIZE-ALL)  CREATE ALL POSSIBLE GENERAL RULES FROM LTM
      Learns all general rules by identifying common threads between
      rules.  Generates rules from generated rules.  Continues until
      no more rules can be inferred. Returns t once done.

* BACKWARD CHAINER FUNCTIONS interpret find prologlist internals_prolog

   (INTERPRET)  INVOKE THE PROLOG INTERPRETER
      When this function is evaluated, a prompt begins for a query of
      the form (fact) where fact is a list composed of atoms lists or
      variables. See internals_prolog

   (FIND '(pattern)) FIND A FACT THAT CAN BE DEDUCED FROM THE PATTERN
      When this function is evaluated, the (pattern) is unified with the
      current rules and facts in the database to assertain if
      it can be deduced.  
      returns the fact with all variables replaced with values if found
      or nil if it is not present.  Stores the fact in the global 
      variable 'it'.  SEE fact, pattern, unification, mgu, findall.

   (FINDALL '(pattern)) FIND ALL FACTS THAT ARE DEDUCED FROM THE PATTERN
      When this function is evaluated, the (pattern) is unified with the
      current rules and facts in the database to assertain if
      it can be deduced.  
      returns the all facts with all variables replaced with values
      if found or nil if it is not present.  Stores the facts in the
      global variable 'them'. SEE fact, pattern, unification, find.

   (PROLOGLIST ['(predicate)]) LIST THE CURRENT BACKWARD CHAINING DATABASE
      (predicate)  when this optional arg is used only lists all
      rules in the database that begin with this predicate, otherwise,
      prints the whole database.

   (INTERNALS_PROLOG) THE BACK CHAINING INFERENCE ENGINE ALGORITHM
      An abstract interpreter for logic programs
      Input:    A logic program P
      A goal     G
      Output:   G-theta, if this was the instance of G deduced from P 
      or
      failure if failure has occured.
      Algorithm: Initialize the resolvent to be G, the input goal.
      1  While resolvent is not empty do:
      Choose a goal A from the resolvent and a 
      renamed clause A' <- B1,B2, ... ,Bn, n>=0, from P
      such that A and A' unify with mgu theta
      or
      Exit if no such goal and clause exist.
      Remove A from and add B1,B2, ... ,Bn to the
      resolvent.
      Apply theta to the resolvent and to G.
      2  If the resolvent is empty output G,
      else output failure.
  
* LONGTERM MEMORY FUNCTIONS DEFrule prules pltm nthltm clearltm
			   deleterules putexpl getexpl

   (DEFRULE sym [(antecedent)] ...  ->  [(consequent)] ...) DEFINE RULE
      sym     name of the rule DEFined
      (antecedent) conditions that must be true before rule fires
      ->      delimiter of antecedents and begins consequences
      (consequent) facts that are deduced if rule is fired
      See pattern, match, fact, rule, wildcards, variables,
      forward-chain, inference,  .

   (LEARN iset fset) INFER RULES THAT WILL MAP AN ISET ACROSS FSET
      iset   the initial set of facts
      fset   the set of facts generated by forward-chaining
      Defines all rules that can be inferred to map the iset of facts
      across the conclusion set.  

   (PRULES sym [sym] ...) PRINT RULES IN LONGTERM MEMORY
      sym   name of the rule to be printed

   (DELETERULES sym [sym] ...) DELETE RULES IN LONGTERM MEMORY
      sym   name of the rule or rules to be deleted

   (PLTM)  PRINT ALL RULES IN LONGTERM MEMORY

   (NTHLTM (n)) RETURN THE NTH RULE IN LONGTERM MEMORY	

   (CLEARLTM) CLEAR LONG TERM MEMORY
           erases all of longterm memory - clears all rules   

   (PUTEXPL sym string)  'PUT' AN EXPLAINATION OF A RULE
      sym   name of the rule the explaination is for
      string    a string of text that is the explaination

   (GETEXPL sym)  'GET' THE EXPLAINATION OF A RULE
      sym   name of the rule 
      returns     the plain text explaination or nil if no previous
      
* SHORTTERM MEMORY FUNCTIONS assert asserted deny pstm nmdeny clearstm 
       how why present allpresent flush recall   

   (ASSERT (fact) [(fact)] ...) CAUSE A FACT TO BE KNOWN
      (fact)     fact to be asserted
      returns	true

   (ASSERTED '(fact))  IS THIS FACT PRESENT IN SHORT TERM MEMORY?
      (fact)     fact to test if it is known

   (PRESENT '(pattern))  IS A MATCHING  FACT IN SHORT TERM MEMORY?
      (pattern)   pattern to test if it is known
      returns true if the pattern is found     
      the global variable it contains the first fact matching the pattern
      An implementation of existential quantification.

   (FORALL '(pattern))   DOES THIS PATTERN RANGE OVER ALL FACTS IN STM
      (pattern)   pattern to test across the range of short term memory
      Returns true if this statement is true across the range of all
      Facts.  Universal Quantification.  See Quantification.

   (ALLPRESENT '(pattern))  ARE MATCHING FACTS PRESENT IN STM?
      (pattern)     pattern to test if it is known
      returns true if a fact matching the pattern is found
      the global variable them contains all facts matching the pattern

   (HOW '(fact) | number) HOW DID FORWARD-CHAIN DEDUCE THAT ? 
      (fact)     fact to be explained
      number     number of fact to be explained
      prints     the assertions that allowed the deduction of the fact

   (WHY '(fact) | number) WHY DID FORWARD-CHAIN NEED THAT FACT ?
      (fact)     fact to be explained
      number     number of fact to be explained
      prints     the assertions that are justified by this fact

   (DENY '(fact) | number ['(fact) | number] ...) DENY A FACT EXISTENCE
      (fact)     fact to be deleted
      number     the number of a fact displayed by PSTM

   (FLUSH '(pattern)) DENY ALL FACTS MATCHING THE PATTERN
      (pattern)   pattern identifying facts to be deleted
      expunges shortterm memory of all facts matching the pattern

   (NMDENY '(fact) | number) ['(fact) | number] ...) DENY A FACT EXISTENCE
      (fact)     fact to be deleted
      number     the number of a fact displayed by PSTM
      non-monotonic deny will deny the fact **** and ****
      all the facts that depended upon that fact for existence
  
   (PSTM)  PRINT SHORT TERM MEMORY  print all known facts or assertions

   (CLEARSTM) CLEAR SHORT TERM MEMORY erase all facts known from stm

* HYPOTHETICAL UNIVERSES DEFviewpoint invalidate-viewpoint DEFhypothesis
recall-viewpoint DEFuniverse hypothesize whatif believe  merge-viewpoints

   (DEFUNIVERSE 'viewpoint)  DEFINE A "REAL" WORLD
      'viewpoint   name of the viewpoint which contains the existing,
      or "known" or "real" world.  This saves what is real now.
 
   (DEFVIEWPOINT 'viewpoint) DEFINE A VIEWPOINT 
      'viewpoint   name of the viewpoint or attitude or opinion.
      Allows hypothetical world or situation without having to
      retract it all later.  Allows Brainstorming.

   (INVALIDATE-VIEWPOINT 'viewpoint) Disallow the viewpoint
      'viewpoint   name of previously DEFined viewpoint.
      Retracts it, disallows it, destroys that "world".

   (DEFHYPOTHESIS sym 'viewpoint [(ifs)] ... -) [(thens)] ...) 
      sym    Name of hypothetical rule in a viewpoint or "world"
      'viewpoint   a previously DEFined viewpoint
      (ifs)      All facts that must hold to fire the hypothetical rule
      (thens)    Facts that become true in viewpoint when hypothesis
      "fires", or holds true.
      This rule is tested only during a "whatif" session.

   (DISPLAY-VIEWPOINT 'viewpoint)  DISPLAY A PARTICULAR VIEWPOINT
      'viewpoint   a previously DEFined viewpoint
      Displays all rules facts and rules used in this "world".

   (HYPOTHESIZE 'viewpoint (fact) [(fact)] ...) Assert facts in a "world".
      'viewpoint   a previously DEFined viewpoint
      (fact)      fact to be asserted in this particular "world" or 
      viewpoint.   Allows statements of axioms or truths.

   (WHATIF 'viewpoint) FORWARD-CHAIN using a particular viewpoint
      'viewpoint   a previously DEFined viewpoint
      Infers using forward-chain in this particular world.

   (ASK-NOSHARING  'viewpoint (pattern)) BACKWARD-CHAIN using a viewpoint
      'viewpoint   a previously DEFined viewpoint
      (pattern)    assertion or goal to find in this particular "world" or
      viewpoint.  Exclusive consultation of a viewpoint to develop
      a Multiple Knowledge System (MKS) paridigm. 
      Returns the first instantiation found of the pattern in this "world"
      or $FAIL if it is not deducible.  See ASK-SHARING.

   (ASK-SHARING  'viewpoint (pattern)) BACKWARD-CHAIN using a viewpoint
      'viewpoint   a previously DEFined viewpoint
      (pattern)    assertion or goal to find using known world and the
      viewpoint.  Allows consultation of A viewpoint to develop
      a Multiple Knowledge System (MKS) paridigm. 
      Returns the first instantiation found of the pattern in "world" plus
      viewpoint or $FAIL if it is not deducible.  

   (BELIEVE 'viewpoint) MERGE A VIEWPOINT INTO THE KNOWN WORLD SPACE
      'viewpoint   a previously DEFined viewpoint
      incorporates all "beliefs" in this viewpoint to the center or
      permanent belief structure.

   (SAVE-VIEWPOINT 'viewpoint) SAVE A VIEWPOINT TO DISK
      viewpoint   a previously DEFined viewpoint
      save all "beliefs" in this viewpoint to disk.

   (RECALL-VIEWPOINT 'viewpoint) RECALL A VIEWPOINT FROM DISK
      'viewpoint   a previously DEFined viewpoint
      recalls all "beliefs" in this viewpoint from disk.

   (MERGE-VIEWPOINTS 'viewpoint 'viewpoint) MERGES TWO KNOWN VIEWPOINTS
      'viewpoint   a previously DEFined viewpoint
      Incorporates second viewpoint into first viewpoint.
 

* MANIPULATING WORLDS  save-world  erase-world init-world
  These functions require symbols when prompted for the world name

   (SAVE-WORLD)  save the current world to disk.
   
   (INIT-WORLD)  restore a world from disk.

   (ERASE-WORLD) erase the existing world from memory.

* EVALUATION FUNCTIONS eval apply funcall quote function backquote lambda

   (EVAL <expr>)  EVALUATE AN XLISP EXPRESSION
      <expr>      the expression to be evaluated
      returns     the result of evaluating the expression

   (APPLY <fun> <args>)  APPLY A FUNCTION TO A LIST OF ARGUMENTS
      <fun>       the function to apply (or function symbol)
      <args>      the argument list
      returns     the result of applying the function to the arguments

   (FUNCALL <fun> [<arg>]...)  CALL A FUNCTION WITH ARGUMENTS
      <fun>       the function to call (or function symbol)
      <arg>       arguments to pass to the function
      returns     the result of calling the function with the arguments

   (QUOTE <expr>)  RETURN AN EXPRESSION UNEVALUATED
      <expr>      the expression to be quoted (quoted)
      returns     <expr> unevaluated

   (FUNCTION <expr>)  QUOTE A FUNCTION
      <expr>      the function to be quoted (quoted)
      returns     a function closure

   (BACKQUOTE <expr>)  FILL IN A TEMPLATE
      <expr>      the template
      returns     a copy of the template with comma and comma-at
      expressions expanded

   (LAMBDA <args> [<expr>]...)  MAKE A FUNCTION CLOSURE
      <args>      the argument list (quoted)
      <expr>      expressions of the function body
      returns     the function closure

* SYMBOL FUNCTIONS set setq setf defun defmacro gen-sym hash
		   intern make-symbol symbol-name symbol-value symbol-plist

   (SET <sym> <expr>)  SET THE VALUE OF A SYMBOL
      <sym>       the symbol being set
      <expr>      the new value
      returns     the new value

   (SETQ [<sym> <expr>]...)  SET THE VALUE OF A SYMBOL
      <sym>       the symbol being set (quoted)
      <expr>      the new value
      returns     the new value

   (SETF [<place> <expr>]...)  SET THE VALUE OF A FIELD
      <place>     the field specifier (quoted):
      <sym>          set value of a symbol
      (car <expr>)         set car of a list node
      (cdr <expr>)         set cdr of a list node
      (nth <n> <expr>)     set nth car of a list
      (aref <expr> <n>)    set nth element of an array
      (get <sym> <prop>)   set value of a property
      (symbol-value <sym>) set value of a symbol
      (symbol-plist <sym>) set property list of a symbol
      <value>     the new value
      returns     the new value

   (DEFUN <sym> <fargs> [<expr>]...)  DEFINE A FUNCTION
   (DEFMACRO <sym> <fargs> [<expr>]...)  DEFINE A MACRO
      <sym>       symbol being defined (quoted)
      <fargs>     list of formal arguments (quoted)
      this list is of the form:
      ([<farg>]...
      [&optional [<oarg>]...]
      [&rest <rarg>]
      [&aux [<aux>]...])
      where
      <farg>      is a formal argument
      <oarg>      is an optional argument
      <rarg>      bound to the rest of the arguments
      <aux>       is an auxiliary variable
      <expr>      expressions constituting the body of the
      function (quoted)
      returns     the function symbol

   (GENSYM [<tag>])  GENERATE A SYMBOL
      <tag>       string or number
      returns     the new symbol

   (INTERN <pname>)  MAKE AN INTERNED SYMBOL
      <pname>     the symbol's print name string
      returns     the new symbol

   (MAKE-SYMBOL <pname>)  MAKE AN UNINTERNED SYMBOL
      <pname>     the symbol's print name string
      returns     the new symbol

   (SYMBOL-NAME <sym>)  GET THE PRINT NAME OF A SYMBOL
      <sym>       the symbol
      returns     the symbol's print name

   (SYMBOL-VALUE <sym>)  GET THE VALUE OF A SYMBOL
      <sym>       the symbol
      returns     the symbol's value

   (SYMBOL-PLIST <sym>)  GET THE PROPERTY LIST OF A SYMBOL
      <sym>       the symbol
      returns     the symbol's property list

   (HASH <sym> <n>)  COMPUTE THE HASH INDEX FOR A SYMBOL
      <sym>       the symbol or string
      <n>         the table size (integer)
      returns     the hash index (integer)

* PROPERTY LIST FUNCTIONS get putprop remprop


   (GET <sym> <prop>)  GET THE VALUE OF A PROPERTY
      <sym>       the symbol
      <prop>      the property symbol
      returns     the property value or nil

   (PUTPROP <sym> <val> <prop>)  PUT A PROPERTY ONTO A PROPERTY LIST
      <sym>       the symbol
      <val>       the property value
      <prop>      the property symbol
      returns     the property value

   (REMPROP <sym> <prop>)  REMOVE A PROPERTY
      <sym>       the symbol
      <prop>      the property symbol
      returns     nil

* ARRAY FUNCTIONS aref make-array


   (AREF <array> <n>)  GET THE NTH ELEMENT OF AN ARRAY
      <array>     the array
      <n>         the array index (integer)
      returns     the value of the array element

   (MAKE-ARRAY <size>)  MAKE A NEW ARRAY
      <size>      the size of the new array (integer)
      returns     the new array

* LIST FUNCTIONS car cdr cons list reverse append member last assoc
		 length remove nth nthcdr mapc mapcar mapl maplist subst sublis

   (CAR <expr>)  RETURN THE CAR OF A LIST NODE
      <expr>      the list node
      returns     the car of the list node

   (CDR <expr>)  RETURN THE CDR OF A LIST NODE
      <expr>      the list node
      returns     the cdr of the list node

   (CXXR <expr>)  ALL CxxR COMBINATIONS
   (CXXXR <expr>)  ALL CxxxR COMBINATIONS
   (CXXXXR <expr>)  ALL CxxxxR COMBINATIONS

   (CONS <expr1> <expr2>)  CONSTRUCT A NEW LIST NODE
      <expr1>     the car of the new list node
      <expr2>     the cdr of the new list node
      returns     the new list node

   (LIST [<expr>]...)  CREATE A LIST OF VALUES
      <expr>      expressions to be combined into a list
      returns     the new list

   (APPEND [<expr>]...)  APPEND LISTS
      <expr>      lists whose elements are to be appended
      returns     the new list

   (REVERSE <expr>)  REVERSE A LIST
      <expr>      the list to reverse
      returns     a new list in the reverse order

   (LAST <list>)  RETURN THE LAST LIST NODE OF A LIST
      <list>      the list
      returns     the last list node in the list

   (MEMBER <expr> <list> [<key> <test>])  FIND AN EXPRESSION IN A LIST
      <expr>      the expression to find
      <list>      the list to search
      <key>       the keyword :test or :test-not
      <test>      the test function (defaults to eql)
      returns     the remainder of the list starting with the expression

   (ASSOC <expr> <alist> [<key> <test>])  FIND AN EXPRESSION IN AN A-LIST
      <expr>      the expression to find
      <alist>     the association list
      <key>       the keyword :test or :test-not
      <test>      the test function (defaults to eql)
      returns     the alist entry or nil

   (REMOVE <expr> <list> [<key> <test>])  REMOVE AN EXPRESSION
      <expr>      the expression to delete
      <list>      the list
      <key>       the keyword :test or :test-not
      <test>      the test function (defaults to eql)
      returns     the list with the matching expressions deleted

   (LENGTH <expr>)  FIND THE LENGTH OF A LIST OR STRING
      <expr>      the list or string
      returns     the length of the list or string

   (NTH <n> <list>)  RETURN THE NTH ELEMENT OF A LIST
      <n>         the number of the element to return (zero origin)
      <list>      the list
      returns     the nth element or nil if the list isn't that long

   (NTHCDR <n> <list>)  RETURN THE NTH CDR OF A LIST
      <n>         the number of the element to return (zero origin)
      <list>      the list
      returns     the nth cdr or nil if the list isn't that long

   (MAPC <fcn> <list1> [<list>]...)  APPLY FUNCTION TO SUCCESSIVE CARS
      <fcn>       the function or function name
      <listn>     a list for each argument of the function
      returns     the first list of arguments

   (MAPCAR <fcn> <list1> [<list>]...)  APPLY FUNCTION TO SUCCESSIVE CARS
      <fcn>       the function or function name
      <listn>     a list for each argument of the function
      returns     a list of the values returned

   (MAPL <fcn> <list1> [<list>]...)  APPLY FUNCTION TO SUCCESSIVE CDRS
      <fcn>       the function or function name
      <listn>     a list for each argument of the function
      returns     the first list of arguments

   (MAPLIST <fcn> <list1> [<list>]...)  APPLY FUNCTION TO SUCCESSIVE CDRS
      <fcn>       the function or function name
      <listn>     a list for each argument of the function
      returns     a list of the values returned

   (SUBST <to> <from> <expr> [<key> <test>])  SUBSTITUTE EXPRESSIONS
      <to>        the new expression
      <from>      the old expression
      <expr>      the expression in which to do the substitutions
      <key>       the keyword :test or :test-not
      <test>      the test function (defaults to eql)
      returns     the expression with substitutions

   (SUBLIS <alist> <expr> [<key> <test>])  SUBSTITUTE WITH AN A-LIST
      <alist>     the association list
      <expr>      the expression in which to do the substitutions
      <key>       the keyword :test or :test-not
      <test>      the test function (defaults to eql)
      returns     the expression with substitutions

* DESTRUCTIVE LIST FUNCTIONS rplaca rplacd nconc delete


   (RPLACA <list> <expr>)  REPLACE THE CAR OF A LIST NODE
      <list>      the list node
      <expr>      the new value for the car of the list node
      returns     the list node after updating the car

   (RPLACD <list> <expr>)  REPLACE THE CDR OF A LIST NODE
      <list>      the list node
      <expr>      the new value for the cdr of the list node
      returns     the list node after updating the cdr

   (NCONC [<list>]...)  DESTRUCTIVELY CONCATENATE LISTS
      <list>      lists to concatenate
      returns     the result of concatenating the lists

   (DELETE <expr> <list> [<key> <test>])  DELETE AN EXPRESSION FROM A LIST
      <expr>      the expression to delete
      <list>      the list
      <key>       the keyword :test or :test-not
      <test>      the test function (defaults to eql)
      returns     the list with the matching expressions deleted

* PREDICATE FUNCTIONS atom symbolp numberp null not listp consp minusp boundp
		      zerop plusp evenp oddp eql equal eq

   (ATOM <expr>)  IS THIS AN ATOM?
      <expr>      the expression to check
      returns     t if the value is an atom, nil otherwise

   (SYMBOLP <expr>)  IS THIS A SYMBOL?
      <expr>      the expression to check
      returns     t if the expression is a symbol, nil otherwise

   (NUMBERP <expr>)  IS THIS A NUMBER?
      <expr>      the expression to check
      returns     t if the expression is a number, nil otherwise

   (NULL <expr>)  IS THIS AN EMPTY LIST?
      <expr>      the list to check
      returns     t if the list is empty, nil otherwise

   (NOT <expr>)  IS THIS FALSE?
      <expr>      the expression to check
      return      t if the expression is nil, nil otherwise

   (LISTP <expr>)  IS THIS A LIST?
      <expr>      the expression to check
      returns     t if the value is a list node or nil, nil otherwise

   (CONSP <expr>)  IS THIS A NON-EMPTY LIST?
      <expr>      the expression to check
      returns     t if the value is a list node, nil otherwise

   (BOUNDP <sym>)  IS THIS A BOUND SYMBOL?
      <sym>       the symbol
      returns     t if a value is bound to the symbol, nil otherwise

   (MINUSP <expr>)  IS THIS NUMBER NEGATIVE?
      <expr>      the number to test
      returns     t if the number is negative, nil otherwise

   (ZEROP <expr>)  IS THIS NUMBER ZERO?
      <expr>      the number to test
      returns     t if the number is zero, nil otherwise

   (PLUSP <expr>)  IS THIS NUMBER POSITIVE?
      <expr>      the number to test
      returns     t if the number is positive, nil otherwise

   (EVENP <expr>)  IS THIS NUMBER EVEN?
      <expr>      the number to test
      returns     t if the number is even, nil otherwise

   (ODDP <expr>)  IS THIS NUMBER ODD?
      <expr>      the number to test
      returns     t if the number is odd, nil otherwise

   (EQ <expr1> <expr2>)  ARE THE EXPRESSIONS IDENTICAL?
      <expr1>     the first expression
      <expr2>     the second expression
      returns     t if they are equal, nil otherwise

   (EQL <expr1> <expr2>)  ARE THE EXPRESSIONS IDENTICAL?
        (WORKS WITH NUMBERS AND STRINGS)
      <expr1>     the first expression
      <expr2>     the second expression
      returns     t if they are equal, nil otherwise

   (EQUAL <expr1> <expr2>)  ARE THE EXPRESSIONS EQUAL?
      <expr1>     the first expression
      <expr2>     the second expression
      returns     t if they are equal, nil otherwise

* CONTROL CONSTRUCTS 	cond and or if case
			let let* catch throw

   (COND [<pair>]...)  EVALUATE CONDITIONALLY
      <pair>      pair consisting of:
      (<pred> [<expr>]...)
      where
      <pred>      is a predicate expression
      <expr>      evaluated if the predicate
      is not nil
      returns     the value of the first expression whose predicate
      is not nil

   (AND [<expr>]...)  THE LOGICAL AND OF A LIST OF EXPRESSIONS
      <expr>      the expressions to be ANDed
      returns     nil if any expression evaluates to nil,
      otherwise the value of the last expression
      (evaluation of expressions stops after the first
      expression that evaluates to nil)

   (OR [<expr>]...)  THE LOGICAL OR OF A LIST OF EXPRESSIONS
      <expr>      the expressions to be ORed
      returns     nil if all expressions evaluate to nil,
      otherwise the value of the first non-nil expression
      (evaluation of expressions stops after the first
      expression that does not evaluate to nil)

   (IF <texpr> <expr1> [<expr2>])  EXECUTE EXPRESSIONS CONDITIONALLY
      <texpr>     the test expression
      <expr1>     the expression to be evaluated if texpr is non-nil
      <expr2>     the expression to be evaluated if texpr is nil
      returns     the value of the selected expression

   (CASE <expr> [<case>]...)  SELECT BY CASE
      <expr>      the selection expression
      <case>      pair consisting of:
      (<value> [<expr>]...)
      where:
      <value>     is a single expression or a list of
      expressions (unevaluated)
      <expr>      are expressions to execute if the
      case matches
      returns     the value of the last expression of the matching case

   (LET ([<binding>]...) [<expr>]...)  CREATE LOCAL BINDINGS
   (LET* ([<binding>]...) [<expr>]...)  LET WITH SEQUENTIAL BINDING
      <binding>   the variable bindings each of which is either:
      1)  a symbol (which is initialized to nil)
      2)  a list whose car is a symbol and whose cadr
      is an initialization expression
      <expr>      the expressions to be evaluated
      returns     the value of the last expression

   (CATCH <sym> [<expr>]...)  EVALUATE EXPRESSIONS AND CATCH THROWS
      <sym>       the catch tag
      <expr>      expressions to evaluate
      returns     the value of the last expression the throw expression

   (THROW <sym> [<expr>])  THROW TO A CATCH
      <sym>       the catch tag
      <expr>      the value for the catch to return (defaults to nil)
      returns     never returns

* LOOPING CONSTRUCTS 	do do* dolist dotimes

   (DO ([<binding>]...) (<texpr> [<rexpr>]...) [<expr>]...)
   (DO* ([<binding>]...) (<texpr> [<rexpr>]...) [<expr>]...)
      <binding>   the variable bindings each of which is either:
      1)  a symbol (which is initialized to nil)
      2)  a list of the form: (<sym> <init> [<step>])
      where:
      <sym>  is the symbol to bind
      <init> is the initial value of the symbol
      <step> is a step expression
      <texpr>     the termination test expression
      <rexpr>     result expressions (the default is nil)
      <expr>      the body of the loop (treated like an implicit prog)
      returns     the value of the last result expression

   (DOLIST (<sym> <expr> [<rexpr>]) [<expr>]...)  LOOP THROUGH A LIST
      <sym>       the symbol to bind to each list element
      <expr>      the list expression
      <rexpr>     the result expression (the default is nil)
      <expr>      the body of the loop (treated like an implicit prog)

   (DOTIMES (<sym> <expr> [<rexpr>]) [<expr>]...)  LOOP FROM ZERO TO N-1
      <sym>       the symbol to bind to each value from 0 to n-1
      <expr>      the number of times to loop
      <rexpr>     the result expression (the default is nil)
      <expr>      the body of the loop (treated like an implicit prog)

* THE PROGRAM FEATURE	prog prog* go return prog1 prog2 progn


   (PROG ([<binding>]...) [<expr>]...)  THE PROGRAM FEATURE
   (PROG* ([<binding>]...) [<expr>]...)  PROG WITH SEQUENTIAL BINDING
      <binding>   the variable bindings each of which is either:
      1)  a symbol (which is initialized to nil)
      2)  a list whose car is a symbol and whose cadr
      is an initialization expression
      <expr>      expressions to evaluate or tags (symbols)
      returns     nil or the argument passed to the return function

   (GO <sym>)  GO TO A TAG WITHIN A PROG CONSTRUCT
      <sym>       the tag (quoted)
      returns     never returns

   (RETURN [<expr>])  CAUSE A PROG CONSTRUCT TO RETURN A VALUE
      <expr>      the value (defaults to nil)
      returns     never returns

   (PROG1 <expr1> [<expr>]...)  EXECUTE EXPRESSIONS SEQUENTIALLY
      <expr1>     the first expression to evaluate
      <expr>      the remaining expressions to evaluate
      returns     the value of the first expression

   (PROG2 <expr1> <expr2> [<expr>]...)  EXECUTE EXPRESSIONS SEQUENTIALLY
      <expr1>     the first expression to evaluate
      <expr2>     the second expression to evaluate
      <expr>      the remaining expressions to evaluate
      returns     the value of the second expression

   (PROGN [<expr>]...)  EXECUTE EXPRESSIONS SEQUENTIALLY
      <expr>      the expressions to evaluate
      returns     the value of the last expression (or nil)

* DEBUGGING AND ERROR HANDLING	error cerror break clean-up evalhook
				top-level continue errset baktrace

   (ERROR <emsg> [<arg>])  SIGNAL A NON-CORRECTABLE ERROR
      <emsg>      the error message string
      <arg>       the argument expression (printed after the message)
      returns     never returns

   (CERROR <cmsg> <emsg> [<arg>])  SIGNAL A CORRECTABLE ERROR
      <cmsg>      the continue message string
      <emsg>      the error message string
      <arg>       the argument expression (printed after the message)
      returns     nil when continued from the break loop

   (BREAK [<bmsg> [<arg>]])  ENTER A BREAK LOOP
      <bmsg>      the break message string (defaults to "**BREAK**")
      <arg>       the argument expression (printed after the message)
      returns     nil when continued from the break loop

   (CLEAN-UP)  CLEAN-UP AFTER AN ERROR
      returns     never returns

   (TOP-LEVEL)  CLEAN-UP AFTER AN ERROR AND RETURN TO THE TOP LEVEL
      returns     never returns

   (CONTINUE)  CONTINUE FROM A CORRECTABLE ERROR
      returns     never returns

   (ERRSET <expr> [<pflag>])  TRAP ERRORS
      <expr>      the expression to execute
      <pflag>     flag to control printing of the error message
      returns     the value of the last expression consed with nil
      or nil on error

   (BAKTRACE [<n>])  PRINT N LEVELS OF TRACE BACK INFORMATION
      <n>         the number of levels (defaults to all levels)
      returns     nil

   (EVALHOOK <expr> <ehook> <ahook> [<env>])  EVALUATE WITH HOOKS
      <expr>      the expression to evaluate
      <ehook>     the value for *evalhook*
      <ahook>     the value for *applyhook*
      <env>       the environment (default is nil)
      returns     the result of evaluating the expression

* ARITHMETIC FUNCTIONS	truncate float  +  -  *  /  1+  1- exp expt
			rem min max abs random sin cos tan sqrt

   (TRUNCATE <expr>)  TRUNCATES A FLOATING POINT NUMBER TO AN INTEGER
      <expr>      the number
      returns     the result of truncating the number

   (FLOAT <expr>)  CONVERTS AN INTEGER TO A FLOATING POINT NUMBER
      <expr>      the number
      returns     the result of floating the integer

   (+ <expr>...)  ADD A LIST OF NUMBERS
      <expr>      the numbers
      returns     the result of the addition

   (- <expr>...)  SUBTRACT A LIST OF NUMBERS OR NEGATE A SINGLE NUMBER
      <expr>      the numbers
      returns     the result of the subtraction

   (* <expr>...)  MULTIPLY A LIST OF NUMBERS
      <expr>      the numbers
      returns     the result of the multiplication

   (/ <expr>...)  DIVIDE A LIST OF NUMBERS
      <expr>      the numbers
      returns     the result of the division

   (1+ <expr>)  ADD ONE TO A NUMBER
      <expr>      the number
      returns     the number plus one

   (1- <expr>)  SUBTRACT ONE FROM A NUMBER
      <expr>      the number
      returns     the number minus one

   (REM <expr>...)  REMAINDER OF A LIST OF NUMBERS
      <expr>      the numbers
      returns     the result of the remainder operation

   (MIN <expr>...)  THE SMALLEST OF A LIST OF NUMBERS
      <expr>      the expressions to be checked
      returns     the smallest number in the list

   (MAX <expr>...)  THE LARGEST OF A LIST OF NUMBERS
      <expr>      the expressions to be checked
      returns     the largest number in the list

   (ABS <expr>)  THE ABSOLUTE VALUE OF A NUMBER
      <expr>      the number
      returns     the absolute value of the number

   (RANDOM <n>)  COMPUTE A RANDOM NUMBER BETWEEN 1 and N-1
      <n>         the upper bound (integer)
      returns     a random number

   (SIN <expr>)  COMPUTE THE SINE OF A NUMBER
      <expr>      the floating point number
      returns     the sine of the number

   (COS <expr>)  COMPUTE THE COSINE OF A NUMBER
      <expr>      the floating point number
      returns     the cosine of the number

   (TAN <expr>)  COMPUTE THE TANGENT OF A NUMBER
      <expr>      the floating point number
      returns     the tangent of the number

   (EXPT <x-expr> <y-expr>)  COMPUTE X TO THE Y POWER
      <x-expr>    the floating point number
      <y-expr>    the floating point exponent
      returns     x to the y power

   (EXP <x-expr>)  COMPUTE E TO THE X POWER
      <x-expr>    the floating point number
      returns     e to the x power

   (SQRT <expr>)  COMPUTE THE SQUARE ROOT OF A NUMBER
      <expr>      the floating point number
      returns     the square root of the number

* BITWISE LOGICAL FUNCTIONS	logand logior logxor lognot


   (LOGAND <expr>...)  THE BITWISE AND OF A LIST OF NUMBERS
      <expr>      the numbers
      returns     the result of the and operation

   (LOGIOR <expr>...)  THE BITWISE INCLUSIVE OR OF A LIST OF NUMBERS
      <expr>      the numbers
      returns     the result of the inclusive or operation

   (LOGXOR <expr>...)  THE BITWISE EXCLUSIVE OR OF A LIST OF NUMBERS
      <expr>      the numbers
      returns     the result of the exclusive or operation

   (LOGNOT <expr>)  THE BITWISE NOT OF A NUMBER
      <expr>      the number
      returns     the bitwise inversion of number

* RELATIONAL FUNCTIONS	<  >  <=  =  >=  /=

        The relational functions can be used to compare integers,
        floating point numbers or strings.

   (< <e1> <e2>)  TEST FOR LESS THAN
      <e1>        the left operand of the comparison
      <e2>        the right operand of the comparison
      returns     the result of comparing <e1> with <e2>

   (<= <e1> <e2>)  TEST FOR LESS THAN OR EQUAL TO
      <e1>        the left operand of the comparison
      <e2>        the right operand of the comparison
      returns     the result of comparing <e1> with <e2>

   (= <e1> <e2>)  TEST FOR EQUAL TO
      <e1>        the left operand of the comparison
      <e2>        the right operand of the comparison
      returns     the result of comparing <e1> with <e2>

   (/= <e1> <e2>)  TEST FOR NOT EQUAL TO
      <e1>        the left operand of the comparison
      <e2>        the right operand of the comparison
      returns     the result of comparing <e1> with <e2>

   (>= <e1> <e2>)  TEST FOR GREATER THAN OR EQUAL TO
      <e1>        the left operand of the comparison
      <e2>        the right operand of the comparison
      returns     the result of comparing <e1> with <e2>

   (> <e1> <e2>)  TEST FOR GREATER THAN
      <e1>        the left operand of the comparison
      <e2>        the right operand of the comparison
      returns     the result of comparing <e1> with <e2>

* STRING FUNCTIONS 	char string strcat substr


   (CHAR <string> <index>)  EXTRACT A CHARACTER FROM A STRING
      <string>    the string
      <index>     the string index (zero relative)
      returns     the ascii code of the character

   (STRING <expr>)  MAKE A STRING FROM AN INTEGER ASCII VALUE
      <expr>      the integer
      returns     a one character string

   (STRCAT [<expr>]...)  CONCATENATE STRINGS
      <expr>      the strings to concatenate
      returns     the result of concatenating the strings

   (SUBSTR <expr> <sexpr> [<lexpr>]) EXTRACT A SUBSTRING
      <expr>      the string
      <sexpr>     the starting position
      <lexpr>     the length (default is rest of string)
      returns     substring starting at <sexpr> for <lexpr>

* INPUT/OUTPUT FUNCTIONS read print prin1 princ terpri flatsize flatc


   (READ [<source> [<eof> [<rflag>]]])  READ AN XLISP EXPRESSION
      <source>    the input source (default is standard input)
      <eof>       the value to return on end of file (default is nil)
      <rflag>     recursive read flag (default is nil)
      returns     the expression read

   (PRINT <expr> [<sink>])  PRINT A LIST OF VALUES ON A NEW LINE
      <expr>      the expressions to be printed
      <sink>      the output sink (default is standard output)
      returns     the expression

   (PRIN1 <expr> [<sink>])  PRINT A LIST OF VALUES
      <expr>      the expressions to be printed
      <sink>      the output sink (default is standard output)
      returns     the expression

   (PRINC <expr> [<sink>])  PRINT A LIST OF VALUES WITHOUT QUOTING
      <expr>      the expressions to be printed
      <sink>      the output sink (default is standard output)
      returns     the expression

   (TERPRI [<sink>])  TERMINATE THE CURRENT PRINT LINE
      <sink>      the output sink (default is standard output)
      returns     nil

   (FLATSIZE <expr>)  LENGTH OF PRINTED REPRESENTATION USING PRIN1
      <expr>      the expression
      returns     the length

   (FLATC <expr>)  LENGTH OF PRINTED REPRESENTATION USING PRINC
      <expr>      the expression
      returns     the length


* FILE I/O FUNCTIONS 	openi openo close read-char peek-char
			write-char read-line

   (OPENI <fname>)  OPEN AN INPUT FILE
      <fname>     the file name string or symbol
      returns     a file pointer

   (OPENO <fname>)  OPEN AN OUTPUT FILE
      <fname>     the file name string or symbol
      returns     a file pointer

   (CLOSE <fp>)  CLOSE A FILE
      <fp>        the file pointer
      returns     nil

   (READ-CHAR [<source>])  READ A CHARACTER FROM A FILE OR STREAM
      <source>    the input source (default is standard input)
      returns     the character (integer)

   (PEEK-CHAR [<flag> [<source>]])  PEEK AT THE NEXT CHARACTER
      <flag>      flag for skipping white space (default is nil)
      <source>    the input source (default is standard input)
      returns     the character (integer)

   (WRITE-CHAR <ch> [<sink>])  WRITE A CHARACTER TO A FILE OR STREAM
      <ch>        the character to put (integer)
      <sink>      the output sink (default is standard output)
      returns     the character (integer)

   (READ-LINE [<source>])  READ A LINE FROM A FILE OR STREAM
      <source>    the input source (default is standard input)
      returns     the input string

* SYSTEM FUNCTIONS load transcript gc expand mem alloc
		   type-of peek poke address-of exit

   (LOAD <fname> [<vflag> [<pflag>]])  LOAD AN XLISP SOURCE FILE
      <fname>     the filename string or symbol
      <vflag>     the verbose flag (default is t)
      <pflag>     the print flag (default is nil)
      returns     the filename

   (TRANSCRIPT [<fname>])  CREATE A FILE WITH A TRANSCRIPT OF A SESSION
      <fname>     file name string or symbol
      (if missing, close current transcript)
      returns     t if the transcript is opened, nil if it is closed

   (GC)  FORCE GARBAGE COLLECTION
      returns     nil

   (EXPAND <num>)  EXPAND MEMORY BY ADDING SEGMENTS
      <num>       the number of segments to add
      returns     the number of segments added

   (ALLOC <num>)  CHANGE NUMBER OF NODES TO ALLOCATE IN EACH SEGMENT
      <num>       the number of nodes to allocate
      returns     the old number of nodes to allocate

   (MEM)  SHOW MEMORY ALLOCATION STATISTICS
      returns     nil

   (TYPE-OF <expr>)  RETURNS THE TYPE OF THE EXPRESSION
      <expr>      the expression to return the type of
      returns     nil if the value is nil otherwise one of the symbols:
      :SYMBOL for symbols
      :OBJECT for objects
      :CONS   for conses
      :SUBR   for built-ins with evaluated arguments
      :FSUBR  for built-ins with unevaluated arguments
      :STRING for strings
      :FIXNUM for integers
      :FLONUM for floating point numbers
      :FILE   for file pointers
      :ARRAY  for arrays

   (PEEK <addrs>)  PEEK AT A LOCATION IN MEMORY
      <addrs>     the address to peek at (integer)
      returns     the value at the specified address (integer)

   (POKE <addrs> <value>)  POKE A VALUE INTO MEMORY
      <addrs>     the address to poke (integer)
      <value>     the value to poke into the address (integer)
      returns     the value

   (ADDRESS-OF <expr>)  GET THE ADDRESS OF AN XLISP NODE
      <expr>      the node
      returns     the address of the node (integer)

   (EXIT)  EXIT XLISP
      returns     never returns

