home *** CD-ROM | disk | FTP | other *** search
/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / SIMTEL / CPMUG / CPMUG023.ARK / DICT.DOC < prev    next >
Text File  |  1984-04-29  |  8KB  |  266 lines
  1.  
  2.  
  3.  
  4. ***************************************************************************
  5. ** COPYRIGHT (C) MASSACHUSETTS INSTITUTE OF TECHNOLOGY AND HARVARD       **
  6. ** UNIVERSITY, BIOMEDICAL ENGINEERING CENTER 1977.  ALL RIGHTS RESERVED. **
  7. ***************************************************************************
  8.  
  9. DICTIONARY FORMAT
  10.  
  11.     THE STOIC DICTIONARY CONSISTS OF MULTIPLE LINKED
  12. LISTS OF ENTRIES, CALLED BRANCHES.  EACH BRANCH IS LINKED
  13. ONLY IN THE BACKWARD DIRECTION, NAMELY FROM MORE RECENT TO
  14. LESS RECENT DEFINITIONS.  EACH LIST IS TERMINATED BY AN
  15. ENTRY WITH A ZERO LINK WORD.  THE DICTIONARY MAY HAVE ANY
  16. NUMBER 1OF BRANCHES.
  17.  
  18.     EACH ENTRY CONTAINS A NAME FIELD WHICH CONSISTS
  19. OF THE NUMBER OF CHARACTERS IN THE NAME FOLLOWED BY
  20. THE FIRST FIVE CHARACTERS.  THE NAME IS FILLED OUT IF
  21. NECESSARY WITH NULLS (ASCII 0).  IN ADDITION, THERE IS
  22. A ONE BIT PRECEDENCE FIELD AND A CODE ADDRESS WORD WHOSE
  23. FUNCTIONS WILL BE DISCUSSED LATER.
  24.  
  25.     THE PARAMETER FIELD IS THE BODY OF THE ENTRY AND
  26. MAY BE ONE OR MORE WORDS LONG.  FOR A VARIABLE OR
  27. CONSTANT, IT IS A SINGLE WORD CONTAINING THE VALUE OF
  28. THE VARIABLE OR CONSTANT.  FOR A COLON DEFINITION, IT IS A
  29. LIST OF ADDRESSES OF THE PARAMETER FIELDS OF OTHER WORDS
  30. TO BE EXECUTED.  FOR A CODE DEFINITION, IT IS THE ACTUAL
  31. MACHINE INSTRUCTIONS TO BE EXECUTED.
  32.  
  33. DICTIONARY ENTRY FORMAT
  34.  
  35. WORD    BIT    CONTENTS
  36.  
  37. 0    0    PRECEDENCE (0 = LOW, 1 = HIGH)
  38.     1-7    NUMBER OF CHARACTERS IN NAME
  39.     8-15    FIRST ASCII CHARACTER OF NAME
  40.  
  41. 1        SECOND AND THIRD CHARACTERS OF NAME
  42.  
  43. 2        FOURTH AND FIFTH CHARACTERS OF NAME
  44.  
  45. 3        ADDRESS OF PREVIOUS ENTRY
  46.         0 IF END OF DICTIONARY CHAIN
  47.  
  48. 4        CODE ADDRESS
  49.  
  50. 5        FIRST WORD OF PARAMETER FIELD
  51.  
  52.  
  53. EXECUTION OF WORDS
  54.  
  55.     THE HEART OF STOIC IS A COMPACT SECTION OF CODE
  56. WHICH EXECUTES THE NEXT WORD.  IT MAKES USE OF AN INSTRUCTION
  57. POINTER CALLED ".I" WHICH IS HELD A MEMORY LOCATION.  AT ALL
  58. TIMES, IT POINTS TO THE LOCATION PRECEDING THE ONE ABOUT TO
  59. BE EXECUTED NEXT.
  60.  
  61.     ON THE 8080,  THE INTERPRETER CONSISTS OF THE
  62. FOLLOWING INSTRUCTIONS:
  63.  
  64. NEXT:    LHLD .I        ;GET ".I"
  65.     INX H        ;INCREMENT BY 2
  66.     INX H
  67.     SHLD .I        ;STORE UPDATED VALUE
  68.     MOV E,M        ;GET WORD ADDRESSED BY ".I" IN (D,E)
  69.     INX H        ;(ADDR OF PARAMETER FIELD OF NEXT WORD)
  70.     MOV D,M
  71.     MOV H,D        ;COPY (D,E) TO (H,L)
  72.     MOV L,E
  73.     DCX H        ;LOAD (H,L) WITH CODE ADDRESS FIELD
  74.     MOV A,M
  75.     DCX H
  76.     MOV L,M
  77.     MOV H,A
  78.     PCHL        ;JUMP TO CODE ADDRESS
  79.  
  80. WHAT THIS DOES IS TO INCREMENT ".I", LOAD (D,E) WITH THE
  81. ADDRESS OF THE PARAMETER FIELD OF THE NEXT WORD TO BE
  82. EXECUTED, AND JUMP TO THE LOCATION ADDRESSED BY
  83. THE CODE ADDRESS FIELD OF THAT WORD.
  84.  
  85.     SP IS USED TO HOLD THE PARAMETER STACK POINTER
  86. AND MUST NOT BE DESTROYED BY ANY WORD I.E., IF USED,
  87. ITS VALUE MUST BE SAVED AND RESTORED.
  88.  
  89.  
  90. THE CODE ADDRESS WORD
  91.  
  92.     THE CODE ADDRESS FOR A CONSTANT POINTS TO CODE
  93. WHICH PUSHES THE VALUE OF THE CONSTANT ON THE STACK:
  94.  
  95.     XCHG        ;MOVE ADDR OF PARAMETER FIELD TO (H,L)
  96.     MOV E,M        ;LOAD (D,E) WITH CONTENTS OF PARAMETER FIELD
  97.     INX H
  98.     MOV D,M
  99.     PUSH D        ;PUSH IT
  100.     JMP NEXT    ;EXECUTE NEXT WORD
  101.  
  102.     THE CODE ADDRESS FOR A VARIABLE POINTS TO CODE
  103. WHICH PUSHES THE ADDRESS OF THE VARIABLE ON THE STACK:
  104.  
  105.     PUSH D        ;PUSH ADDR OF PARAMETER FIELD
  106.     JMP NEXT    ;EXECUTE NEXT WORD
  107.  
  108.     THE CODE ADDRESS FOR A COLON DEFINITION POINTS TO
  109. CODE WHICH PUSHES ".I" ON THE RETURN STACK, AND SETS ".I"
  110. TO POINT TO THE WORD PRECEDING THE FIRST WORD OF THE
  111. PARAMETER FIELD OF THE CURRENT WORD:
  112.  
  113. (:):    LHLD .I        ;MOVE .I TO (D,E)
  114.     XCHG
  115.     DCX H        ;SET .I TO W-2
  116.     DCX H
  117.     SHLD .I
  118.     LHLD .R        ;INCREMENT RETURN STACK PTR BY 2
  119.     INX H
  120.     INX H
  121.     SHLD .R
  122.     MOV M,E        ;STORE .I ON END OF RETURN STACK
  123.     INX H
  124.     MOV M,D
  125.     JMP NEXT    ;EXECUTE NEXT WORD
  126.  
  127.     THE RETURN STACK POINTER IS KEPT IN THE LOCATION
  128.     LABELLED ".R".
  129.  
  130.     AT THE END OF EVERY COLON DEFINITION IS THE ADDRESS
  131. OF A NAMELESS DICTIONARY ENTRY WHICH POPS ".I" FROM THE
  132. RETURN STACK:
  133.  
  134. (;):    LHLD .R        ;RETURN STACK POINTER
  135.     MOV E,M        ;LOAD (D,E) WITH TOP OF RETURN STACK
  136.     INX H
  137.     MOV D,M
  138.     DCX H
  139.     DCX H        ;DECREMENT RETURN STACK POINTER BY 2
  140.     DCX H
  141.     SHLD .R        ;STORE UPDATED VALUE
  142.     XCHG        ;SET ".I" TO TOP OF RETURN STACK
  143.     SHLD .I
  144.     JMP NEXT    ;EXECUTE NEXT WORD
  145.  
  146.     THE CODE ADDRESS FOR A CODE DEFINITION POINTS
  147. TO THE FOLLOWING WORD, I.E. THE FIRST WORD OF THE
  148. DEFINITION.
  149.  
  150.  
  151. THE PRECEDENCE BIT
  152.  
  153.     THE PRECEDENCE BIT IS USED DURING COMPILATION TO CAUSE
  154. CERTAIN WORDS TO BE EXECUTED IMMEDIATELY INSTEAD OF BEING
  155. COMPILED.  THIS FACILITY MAKES POSSIBLE COMPILATION OF THE
  156. FORWARD AND BACKWARD REFERENCES WHICH ARE NECESSARY FOR
  157. CONDITIONALS AND ITERATION.
  158.  
  159.     WHEN STOIC IS COMPILING A WORD INTO THE COMPILE BUFFER,
  160. IF ITS PRECEDENCE BIT IS ZERO, THE ADDRESS OF THE PARAMETER FIELD
  161. OF THE WORD IS STORED IN THE COMPILE BUFFER.  IF ITS PRECEDENCE
  162. BIT IS NON-ZERO, THE WORD IS EXECUTED DIRECTLY.
  163.  
  164. EXAMPLE:
  165.  
  166.     BEGIN X @ EQZ END ;
  167.  
  168.     THIS GENERATES THE FOLLOWING CODE IN THE COMPILE BUFFER:
  169.  
  170.     LOOP:    ADDRESS OF X
  171.         ADDRESS OF @
  172.         ADDRESS OF EQZ
  173.         ADDRESS OF (IF)
  174.         LOOP-2-.
  175.  
  176.     (IF) TESTS THE TOP OF THE STACK AND, IF ZERO,
  177.     ADDS TO ".I" THE CONTENTS OF THE NEXT WORD; IF
  178.     NON-ZERO, ".I" IS INCREMENTED BY 2.
  179.  
  180.     "BEGIN" AND "END" HAVE THE PRECEDENCE BIT
  181.     SET IN THEIR DICTIONARY ENTRIES.
  182.  
  183.     "BEGIN", IS EXECUTED SINCE ITS PRECEDENCE BIT IS
  184.     SET, AND CAUSES THE CURRENT COMPILE BUFFER OUTPUT
  185.     POINTER (WHOSE VALUE IS NOW "LOOP") - 2 TO BE SAVED
  186.     ON THE PARAMETER STACK.
  187.  
  188.     THE ADDRESSES OF "X", "@", AND "EQZ" ARE COMPILED
  189.     DIRECTLY INTO THE COMPILE BUFFER SINCE THEIR PRECEDENCE
  190.     IS ZERO.
  191.  
  192.     "END" IS EXECUTED, CAUSING THE ADDRESS OF "(IF)"
  193.     TO BE OUTPUT TO THE COMPILE BUFFER, FOLLOWED BY THE
  194.     SAVED DICTIONARY POINTER MINUS THE CURRENT VALUE OF
  195.     THE COMPILE BUFFER OUTPUT POINTER ("LOOP"-2-.).
  196.  
  197.     WHEN THE ABOVE COMPILED CODE IS EXECUTED, THE WORDS
  198.     "X", "@", AND "EQZ" ARE EXECUTED.  "(IF)" THEN
  199.     CAUSES A CONDITIONAL BRANCH BACK TO "LOOP" IF
  200.     THE TOP OF THE STACK IS ZERO, OTHERWISE CONTROL
  201.     PASSES ON TO THE NEXT WORD.
  202.  
  203.  
  204.     THE USER MAY SET THE PRECEDENCE BIT HIMSELF, USING
  205.     THE FOLLOWING WORD:
  206.  
  207.     IMMEDIATE    SET THE PRECEDENCE BIT OF THE
  208.             MOST RECENTLY DEFINED WORD.
  209.  
  210.     EXAMPLE:
  211.  
  212.     'ZERO : 0 = ; IMMEDIATE
  213.  
  214.     THIS DEFINES A WORD CALLED "ZERO" WHICH TYPES
  215.     A "0" WHEN COMPILED.  IT GENERATED NO CODE AT COMPILE
  216.     TIME.  THUS,
  217.  
  218.     'TEST : ZERO ;
  219.  
  220.     CAUSES A "0" TO BE TYPED WHILE LEAVING THE
  221.     DEFINITION OF TEST EMPTY.
  222.  
  223.     THE FOLLOWING WORD PERMITS MORE COMPLICATED
  224.     SEQUENCES OF WORDS TO BE EXECUTED WHILE
  225.     COMPILING A DEFINITION:
  226.  
  227.     //    COMPLEMENT STATE (HAS PRECEDENCE BIT SET)
  228.  
  229.     THUS:
  230.  
  231.     'TEST : // 0 = // ;
  232.  
  233.     IS EQUIVALENT TO THE ABOVE EXAMPLE.
  234.  
  235.  
  236. COLON DEFINITIONS
  237.  
  238.     THE COMPILATION OF A COLON DEFINITION IS ONLY SLIGHTLY
  239. DIFFERENT FROM NORMAL COMPILATION OUTSIDE A COLON DEFINITION.
  240. THE WORD ":" HAS NON-ZERO PRECEDENCE AND CAUSES THE ADDRESS OF
  241. "((:))" TO BE OUTPUT TO THE COMPILE BUFFER FOLLOWED BY A ZERO WORD.
  242. ":" ALSO CHECKS TO MAKE SURE THAT THE NESTING DEPTH IS ZERO
  243. AND THEN INCREMENTS THE NESTING DEPTH BY ONE.
  244.  
  245.     THE WORD ";" ALSO HAS NON-ZERO PRECEDENCE AND CAUSES
  246. THE ADDRESS OF "(;)" TO BE OUTPUT TO THE COMPILE BUFFER.
  247. IT THEN STORES IN THE ZERO WORD FOLLOWING "((:))" THE
  248. NUMBER OF BYTES COMPILED SINCE THE START OF THE COLON
  249. DEFINITION.  ";" ALSO CHECKS FOR ZERO NESTING DEPTH.
  250.  
  251.     WHEN EXECUTED, THE WORD "((:))" CREATES THE FIRST FIVE
  252. WORDS FOR THE NEW DICTIONARY ENTRY USING THE STRING WHOSE
  253. ADDRESS IS AT THE TOP OF THE STACK AND THEN COPIES THE FOLLOWING
  254. N BYTES FROM THE COMPILE BUFFER INTO THE DICTIONARY WHERE N IS
  255. THE CONTENTS OF THE FOLLOWING WORD IN THE COMPILE BUFFER.  SINCE
  256. ALL ADDRESS CONTAINED IN THE COMPILED CODE ARE EITHER ABSOLUTE
  257. ADDRESSES OF WORDS IN THE DICTIONARY OR OFFSETS RELATIVE TO
  258. ".I", THE CODE IS POSITION INDEPENDENT AND WILL EXECUTE
  259. PROPERLY EITHER IN THE COMPILE BUFFER OR WHEN RELOCATED TO
  260. THE END OF THE DICTIONARY.
  261.  
  262.  
  263.  
  264. ***EOF***
  265.  
  266.