DESCRIPTION OF 1108 MICRO-PLANNER  -  10/16/73
----------------------------------------------

THIS DOCUMENT SERVES AS A SUMMARY OF THE PRIMITIVES AVAILABLE IN THE
1108 LISP IMPLEMENTATION OF MICRO-PLANNER (HEREAFTER REFERRED TO AS
PLNR).  IT IS INTENDED TO BE USED IN CONJUNCTION WITH (1) BELOW, AND
THUS EXPLAINS IN DETAIL ONLY THE DIFFERENCES BETWEEN 1108 PLNR AND MIT
PLNR.  USEFUL (AND RELATIVELY ACCESSIBLE) SOURCES OF PLNR INFORMATION
INCLUDE THE FOLLOWING:

FOR A COMPLETE DESCRIPTION OF THE PRIMITIVES:

(1) SUSSMAN, G., T. WINOGRAD AND E. CHARNIAK:  MICRO-PLANNER REFERENCE
    MANUAL.  MIT AI LAB MEMO NO. 203A, DECEMBER 1971.

FOR AN OVERVIEW OF THE LANGUAGE:

(2) WINOGRAD, T.:  UNDERSTANDING NATURAL LANGUAGE (SEC. 6).  ACADEMIC
    PRESS, 1972.

(3) HEWITT, C.:  PROCEDURAL EMBEDDING OF KNOWLEDGE IN PLANNER.  PROCEED-
    INGS OF THE 2ND IJCAI, SEPTEMBER 1971.

FOR DETAILS ABOUT THE IMPLEMENTATION:

(4) BAUMGART, B.:  MICRO PLANNER ALTERNATE REFERENCE MANUAL.  STANFORD
    AI LAB OPERATING NOTE NO. 67, APRIL 1972.

LOADING PLNR
------------

PLNR IS LOADED BY TYPING (TO EXEC-8):

              @ADD LISP*LIB.STRTPLNR

THIS WILL START LISP RUNNING, CHANGE THE COMMENT CHARACTER FROM '?' TO
';', LOAD IN THE COMPILED VERSIONS OF PLNR, PRETTYP AND EDIT, DO A
(GROW 30) TO GET YOU SOME MORE CORE, AND THEN DO A (PLNR) TO GET PLNR
RUNNING.  YOU WILL THEN BE COMMUNICATING WITH A NEW LEVEL OF LISP
SUPERVISION WHICH ACTS AS A READ-THVAL-PRINT LOOP (INSTEAD OF THE
NORMAL READ-EVAL-PRINT).  ALL LISP CONTROL CARDS ARE RECOGNIZED, EXCEPT
THAT A RETURN TO THE SUPERVISOR RETURNS YOU TO THE PLNR SUPERVISOR (E.G.
IF YOU GET INTO TROUBLE, :LISP WILL RETURN YOU TO PLNR).  YOU MAY RETURN
TO THE NORMAL LISP SUPERVISOR VIA (RETURN <EXPR>), AND MAY RE-ENTER PLNR
VIA (PLNR).

PLNR PRIMITIVES
---------------

THIS SECTION DESCRIBES THE PLNR PRIMITIVES WHICH ARE CURRENTLY AVAIL-
ABLE.  COMMENTS ARE APPENDED ONLY WHEN THERE ARE DIFFERENCES BETWEEN
THIS IMPLEMENTATION AND MIT PLNR.  NOTE THAT META-LINGUISTIC VARIABLES
ARE ENCLOSED IN ANGLE BRACKETS (<>), AND ARGUMENTS WHICH ARE EVALUATED
BEFORE THE PRIMITIVE IS APPLIED ARE INDICATED BY PRECEDING THEM WITH
A QUOTE-SIGN ('<>).

(PLNR)
         THIS FUNCTION ENTERS A NEW LEVEL OF PLNR SUPERVISION, JUST
         AS (LISP) ENTERS A NEW LEVEL OF LISP SUPERVISION.  YOU MAY
         RETURN FROM PLNR TO LISP (VIA [RETURN]), AND THEN RE-ENTER
         PLNR WITHOUT AFFECTING THE PLNR DATA BASE.

(THAMONG <PLNR-VAR> '<LIST>)

(THAND <E1> <E2> ...)

(THANTE <THM-NAME> <VAR-DECLARATIONS> <PATTERN> <BODY>)  ::  ($TA ...)

(THAPPLY <THM-NAME> <DATUM>)

(THASSERT <SKELETON> <REC1> <REC2> ...)  ::  ($A ...)

         <RECS> :: (THPSEUDO)
                   (THPROP '<EXPR>)
                   (THTBF <FILTER>)       [$T :: (THTBF THTRUE)]
                   (THUSE <TH1> <TH2> ...)

(THASSERTLIST <<SKELETON> <LIST>> <REC1> <REC2> ...)  ::  ($AL ...)

         THIS NEW PRIMITIVE ALLOWS ONE TO GENERATE A NUMBER OF RELATED
         ASSERTIONS.  FOR EXAMPLE,

              ($AL (ROSES ARE (RED PINK PRETTY)) <RECS>)

         IS EQUIVALENT TO

              (THDO ($A (ROSES ARE RED) <RECS>)
                    ($A (ROSES ARE PINK) <RECS>)
                    ($A (ROSES ARE PRETTY) <RECS>))

(THASVAL <PLNR-VAR>)

(THBKPT '<E1> '<E2> ...)

         EACH <E> WILL BE EVALED AND, IF THBKPTS ARE BEING THTRACED,
         PRINTED SEPARATED BY BLANKS.  E.G.,

              (THBKPT 'X 'IS 'NOW $?X)

(THBREAK '<E1> '<E2> ...)

         EACH <E> WILL BE EVALED AND PRINTED SEPARATED BY BLANKS, AND
         THEN A READ-EVAL-PRINT LOOP IS ENTERED.  THE LOOP IS EXITED
         (WITH A VALUE OF T) WHEN T IS READ.

(THCOND <PAIR1> <PAIR2> ...)

(THCONSE <THM-NAME> <VAR-DECLARATIONS> <PATTERN> <BODY>)  ::  ($TC ...)

(THDATA)
      
         THE DATA READ SHOULD BE OF THE FORM ((AN ASSERTION)),
         ((AN ASSERTION) . PROP), OR (THM-NAME).  THE LOOP ENDS WHEN
         AN ATOM IS READ, WHICH IS RETURNED AS THE VALUE OF [THDATA].

(THDO <E1> <E2> ...)

(THDUMP '<FILENAME>)

         <FILENAME> MUST BE A DATA-FILE WHICH IS CURRENTLY ASSIGNED.
         [THDUMP] DOES A [THPRETTYP] OF ALL CURRENT PLNR THEOREMS,
         AND THEN A (THSTATE) INTO THE INDICATED FILE.  AN
         @ADD <FILENAME> AT SOME LATER DATE WILL THEN RESTORE EVERY-
         THING TO ITS CURRENT STATE.  (THDUMP) WILL PRINT OUT ALL THE
         ABOVE ON THE TTY.

(THEDIT <THM-NAME>)

         ALLOWS ONE TO EDIT A PLNR THEOREM (SEE EDIT-D FOR DETAILS
         CONCERNING USE OF THE EDITOR).

(THERASE <SKELETON> <REC1> <REC2> ...)  ::  ($E ...)

         (SEE [THASSERT] FOR AVAILABLE RECOMMENDATIONS).

(THERASING <THM-NAME> <VAR-DECLARATIONS> <PATTERN> <BODY>)  ::  ($TE ..)

(THERT <COMMENT>)

         PRINTS OUT <COMMENT> (UNEVALUATED) AND, UNLIKE MIT PLNR,
         CAUSES FAILURE TO PROPOGATE ALL THE WAY BACK TO THE PLNR
         SUPERVISOR.

(THEV <EXPR>)  ::  $&<EXPR>

         THIS IS EQUIVALENT TO (THVAL '<EXPR> THALIST).  NOTE THAT IT
         IS ABBREVIATED $&<EXPR> INSTEAD OF $E<EXPR>.  IT MAY BE USED
         BOTH IN PATTERNS OR AS A STAND-ALONE FUNCTION (E.G., IF YOU
         WANT <E> THVALED INSTEAD OF EVALED WHEN IN A THBREAK LOOP,
         TYPE $&<E>).

(THFAIL <ARG1> <ARG2> <ARG3>)

         (THFAIL THTAG <TAG> T)
         (THFAIL THTAG <TAG>)
         (THFAIL THPROG)
         (THFAIL THEOREM)     CAUSES THE CURRENT THEOREM TO FAIL, EVEN
                              IF THERE ARE NESTED THPROGS.
         (THFAIL THMESSAGE <MESSAGE>)
         (THFAIL)

(THFAIL? '<PREDICATE> '<ACTION>)

(THFINALIZE <ARG1> <ARG2>)

         (THFINALIZE THTAG <TAG>)
         (THFINALIZE THPROG)
         (THFINALIZE THEOREM)     FINALIZES EVERYTHING DONE IN CURRENT
                                  THEOREM, EVEN IF THERE ARE NESTED
                                  THPROGS.

(THFIND <MODE> <SKELETON> <VAR-DECLARATIONS> <BODY>)

         <MODE> :: ALL
                   <N>
                   (EXACTLY <N>)
                   (AT-LEAST <N>)
                   (AT-MOST <N>)
                   (AS-MANY-AS <N>)
                   (AT-LEAST <N1> AT-MOST <N2>)
                   (AT-LEAST <N1> AS-MANY-AS <N2>)

(THFLUSH <IND1> <IND2> ...)

         (THFLUSH) :: (THFLUSH THASSERTION $TC $TA $TE)

(THGO <TAG>)  ::  (THSUCCEED THTAG <TAG>)

(THGOAL <PATTERN> <REC1> <REC2> ...)  ::  ($G ...)

         <RECS> :: (THNODB)
                   (THDBF <FILTER>)
                   (THTBF <FILTER>)       [$T :: (THTBF THTRUE)]
                   (THUSE <TH1> <TH2> ...)
                   (THANUM <N>)  ::  $N<N>
                   (THNUM <N>)

(THMATCH '<EXPR1> '<EXPR2>)

(THMESSAGE <VAR-DECLARATIONS> <PATTERN> <BODY>)

(THNOHASH <ATOM> <IND1> <IND2> ...)

         (THNOHASH <ATOM>) :: (THNOHASH <ATOM> THASSERTION $TC $TA $TE)

(THNOT <EXPR>)  ::  (THCOND [<EXPR> (THFAIL)] [(THSUCCEED)])

(THNV <VARIABLE>)  ::  $=<VARIABLE>

(THOR <E1> <E2> ...)

(THPRETTYP '<THM-NAMES> '<FILE>)

         THE LIST OF PLNR THEOREMS INDICATED BY <THM-NAMES> WILL BE
         PRETTYPRINTED TO THE DATA-FILE <FILE> (IF <FILE> IS ABSENT
         THEY ARE PRINTED ON THE TTY).

(THPROG <VAR-DECLARATIONS> <BODY>)

(THPUT '<ATR> '<IND> '<VALUE>)

         (1108 LISP ARGUMENT ORDER)

(THPUTPROP '<ATR> '<VALUE> '<IND>)

(THREMPROP '<ATR> '<IND>)
      
(THRESTRICT <PLNR-VAR> <LISP-FN1> <LISP-FN2> ...)  ::  ($R ...)

(THRETURN '<EXPR>)  ::  (THSUCCEED THPROG '<EXPR>)

(THRPLACA '<DOTTED-PAIR> '<NEW-CAR>)

(THRPLACD '<DOTTED-PAIR> '<NEW-CDR>)

(THSETQ <VAR1> '<E1> <VAR2> '<E2> ...)

(THSTATE <IND1> <IND2> ...)

         (THSTATE) :: (THSTATE THASSERTION $TC $TA $TE)

(THSUCCEED <ARG1> <ARG2>)

         (THSUCCEED)
         (THSUCCEED THTAG <TAG>)  ::  (THGO <TAG>)
         (THSUCCEED THPROG '<E>)  ::  (THRETURN '<E>)
         (THSUCCEED THPROG)
         (THSUCCEED THEOREM '<E>)     CAUSES THE CURRENT THEOREM TO
         (THSUCCEED THEOREM)          SUCCEED, EVEN IF THERE ARE NESTED
                                      THPROGS.

(THTRACE <IND1> <IND2> ...)

         <INDS> :: <ATOM>
                   (<ATOM> <TRACE PREDICATE>)
                   (<ATOM> <TRACE PREDICATE> <BREAK PREDICATE>)
         <ATOM> :: <THM-NAME>, THEOREM, $G, $A, $E, THBKPT

         [THBREAK] IS USED IF THE <BREAK PREDICATE> EVALS TO NON-NIL.
         TYPE T TO EXIT FROM THE BREAK LOOP.

(THUNTRACE <ATOM1> <ATOM2> ...)

         (THUNTRACE) :: UNTRACE EVERYTHING THAT'S TRACED

(THUNIQUE '<EXPR1> '<EXPR2> ...)

(THV <VARIABLE>)  ::  $?<VARIABLE>

(THVAL '<EXPR> '<ALIST>)

(THVDO <E1> <E2> ...)

         THIS NEW PRIMITIVE ACTS LIKE THDO, EXCEPT IT IS NOT UNDONE
         ON FAILURE BACKUP.  IT IS EQUIVALENT TO

              (THPROG NIL (THDO <E1> <E2> ...) (THFINALIZE THPROG))

(THVSETQ <VAR1> '<E1> <VAR2> '<E2> ...)

ABBREVIATIONS
-------------

THE FOLLOWING ABBREVIATIONS MAY BE USED TO SAVE YOUR THFINGERS FROM
TYPING MANY LONG THNAMES:

         $?<X> :: (THV <X>)
         $=<X> :: (THNV <X>)
         $&<X> :: (THEV <X>)
         $N<N> :: (THANUM <N>)
         $T    :: (THTBF THTRUE)
         $G    :: THGOAL
         $A    :: THASSERT
         $AL   :: THASSERTLIST
         $E    :: THERASE
         $R    :: THRESTRICT
         $TC   :: THCONSE
         $TA   :: THANTE
         $TE   :: THERASING

THSTUFF YOU SHOULD KNOW
-----------------------

MOST PLNR ERROR MESSAGES ARE DESCRIBED IN (1).  NOTE, HOWEVER, THAT 1108
PLNR SIMPLY THFAILS BACK TO THE PLNR SUPERVISOR AFTER AN ERROR OCCURS.

ALL PLNR VARIABLES ($?<X> OR $=<X>) MUST BE BOUND BEFORE THEY ARE
REFERENCED, EITHER BY APPEARING IN A <VAR-DECLARATIONS> LIST IN A
THEOREM, THPROG, THFIND OR THMESSAGE, OR BY EXPLICITLY CREATING A GLOBAL
BINDING (E.G., (THSETQ $?X 'THUNASSIGNED)).

LISP EXPRESSIONS MAY BE USED WITH RELATIVE IMPUNITY WITHIN PLNR EXPRES-
SIONS  -  THE RULE IS THAT IF IT EVALS TO NIL IT FAILS (LIKE (THFAIL)),
OTHERWISE IT SUCCEEDS.  TO EVALUATE A LISP EXPRESSION WHICH RETURNS A
VALUE OF NIL WITHOUT FAILING, YOU MUST THEREFORE DO SOMETHING LIKE
(THDO <EXPR>) OR (DO <EXPR> T).

NOTE, HOWEVER, THAT COMPLEX PLNR PRIMITIVES SHOULD NEVER BE PLACED
INSIDE OF A LISP EXPRESSION.  FOR EXAMPLE, A [COND] MAY APPEAR IN A
THPROG, BUT IT MAY NOT CONTAIN ANY THGOALS (USE [THCOND] INSTEAD).
SIMPLE PLNR PRIMITIVES LIKE [THV] AND [THASVAL] MAY APPEAR IN LISP
EXPRESSIONS (E.G., (PRINT $?X) IS OK).  WHEN IN DOUBT, YOU MAY ALWAYS
DO AN EXPLICIT $&<EXPR>.

SINCE PLNR MAKES RATHER EXTENSIVE USE OF THE QUESTION-MARK CHARACTER,
THE LISP COMMENT CHARACTER IS CHANGED TO SEMI-COLON WHEN PLNR IS LOADED.
YOU MAY TEMPORARILY CHANGE IT BACK TO '?' (E.G., TO @ADD IN SOME
CODE THAT CONTAINS COMMENTS) BY TYPING:

         (READMAC "?" (READMAC ";" F))
         (DELIM "?" (DELIM ";" F))

USER, MEET PLNR ...
-------------------

THE BEST WAY TO GET FAMILIAR WITH AN INTERACTIVE PROGRAMMING SYSTEM IS
TO SIT DOWN AND PLAY WITH IT FOR AWHILE.  AS A PRELIMINARY INTRODUCTION
TO THE USAGE OF PLNR, TRY THE FOLLOWING CONVERSATION (DESCRIBED MORE
FULLY IN (1)):

@ADD LISP*LIB.STRTPLNR
         ;(WAIT FOR THVAL: TO APPEAR)

($A (HUMAN TURING))
         ;TURING IS HUMAN
      
($TC (X) (FALLIBLE $?X) ($G (HUMAN $?X)))
         ;ALL HUMANS ARE FALLIBLE

($G (FALLIBLE TURING))
         ;IS TURING FALLIBLE?
         ;NO?  AHA - WE FORGOT TO TELL PLNR TO USE AVAILABLE THEOREMS

($G (FALLIBLE TURING) $T)
         ;THAT'S BETTER

(THPROG (Y) ($G (FALLIBLE $?Y) $T) (THRETURN $?Y))
         ;IS ANYTHING FALLIBLE?

[THDO ($A (HUMAN SOCRATES)) ($A (GREEK SOCRATES)) ($A (HUMAN NEWTON]
         ;ADD SOME MORE FACTS

(THSTATE)
         ;CHECK THE DATA BASE

(THDUMP)
         ;A MORE COMPLETE PICTURE OF THE DATA BASE

(THTRACE THEOREM $G)
         ;LET'S WATCH PLNR WORK
 
(THFIND 1 $?X (X) ($G (FALLIBLE $?X) $T) ($G (GREEK $?X)))
         ;FIND A FALLIBLE GREEK - NOTE THE BACKTRACKING

(THUNTRACE)
         ;NOTE THAT IT TELLS YOU WHAT WAS UNTRACED

(RETURN 'DONE)

:STOP