home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / forth / compiler / fpc / help / kernel3.hlp < prev    next >
Encoding:
Text File  |  1989-06-02  |  20.2 KB  |  567 lines
  1. KERNEL3.HLP            Edited by J. McKnight    1988-01-30 23:32
  2.  
  3. >TYPE           ( adr len -- )
  4.         TYPE for multitasking systems.
  5.  
  6. .(              ( -- )
  7.         Type the following string on the terminal.
  8.  
  9. (               ( -- )
  10.         The Forth Comment Character. The input stream is skipped
  11.         until a ) is encountered.
  12.  
  13. TRAVERSE        ( adr direction -- adr' )
  14.         Run through a name field in the specified direction.
  15.         Terminate when a byte whose high order bit is on is detected.
  16.  
  17. DONE?           ( n -- f1 )
  18.         True if the input stream is exhaused or state doesn't match.
  19.  
  20. CNHASH          ( cfa -- yadr )
  21.         Given cfa, get pointer into >NAME hash table in YSEG.
  22.  
  23. CNSRCH          ( cfa ya maxyadr -- nfa failf )
  24.         Search for cfa between yadr and maxyadr in YSEG. Return nfa and
  25.         failure flag.
  26.  
  27. N>LINK          ( nfa -- lfa)
  28.         Go from name field address nfa to link field address lfa.
  29.  
  30. L>NAME          ( lfa -- nfa )
  31.         Go from link field address lfa to name field address lfa.
  32.  
  33. BODY>           ( body -- cfa )
  34.         Go from body address to code field address cfa.
  35.  
  36. NAME>           ( nfa -- cfa )
  37.         Go from name field address nfa to code field address cfa.
  38.  
  39. LINK>           ( lfa -- cfa )
  40.         Go from link field address lfa to code field address cfa.
  41.  
  42. >BODY           ( cfa -- body )
  43.         Go from code field address cfa to body address.
  44.  
  45. NO-NAME         ( -- )
  46.         A dummy name, whose name field address is returned by >NAME
  47.         when the real name field can not be found.
  48.  
  49. >NAME           ( cfa -- nfa )
  50.         Go from code field address cfa to name field address nfa.
  51.  
  52. >LINK           ( cfa -- lfa )
  53.         Go from code field address cfa to link field address lfa.
  54.  
  55. >VIEW           ( cfa -- vfa )
  56.         Go from code field address cfa to view field address vfa.
  57.  
  58. VIEW>           ( vfa -- cfa )
  59.         Go from view field address vfa to code field address cfa.
  60.  
  61. HASH            ( str-adr voc-ptr -- thread )
  62.         Given a string address and a pointer to a set of vocabulary chains,
  63.         returns the actual thread. The hash algorithm used is as follows:
  64.  
  65.                 (((firstchar*2)+secondchar)*2)+count)and(#threads-1)
  66.  
  67.         This seems to provide a good distribution across the 64 threads in
  68.         1000 word FORTH vocabulary.
  69.  
  70.  
  71. (FIND)          ( here lfa -- cfa flag | here false )
  72.         Does a search of the dictionary based on a pointer to a vocabulary
  73.         thread and a string.  If it finds the string in the chain, it
  74.         returns a pointer to the cfa field inside the header. This field
  75.         contains the code field address of the body. If it was an immediate
  76.         word the flag returned is a 1. If it is non-immediate the flag
  77.         returned is a -1. If the name was not found, the string address is
  78.         returned along with a flag of zero. Note that links point to links,
  79.         and are absolute addresses.
  80.  
  81. DROP.CONTEXT.I2*+@DUP   ( a1 -- n1 )
  82.         An auxiliary speed-up word whose function is denoted by its name.
  83.  
  84. PRIOR.CHECK     ( n1 -- n1 f1 )
  85.         Equivalent to the sequence
  86.                     DUP PRIOR @ OVER PRIOR ! =
  87.         converted to code for speeding up FIND .
  88.  
  89. OVER.SWAP.HASH.@   ( n1 n2 -- n1 n1 n2 n3 )
  90.         Another speed-up for FIND .
  91.  
  92. %%FIND          ( addr false #vocs 0 -- cfa flag | addr false )
  93.         Actual high level search loop primitive, calls (FIND) for each
  94.         word through the vocabulary chain until found or until the end of
  95.         the chain is reached.
  96.  
  97. %FIND           ( adr -- cfa flag | adr false )
  98.         The default version of FIND ( see below ).  This CODE primitive
  99.         does the setup for %%FIND then calls it if the name is not of zero
  100.         length.
  101.  
  102. FIND            ( adr -- cfa flag | adr false )
  103.         Run through the vocabulary list searching for the name whose
  104.         address is supplied on the stack. If the name is found, return the
  105.         code field address of the name and a non-zero flag. The flag is -1
  106.         if the word is non-immediate and 1 if it is immediate. If the name
  107.         is not found, the string address is returned along with a false
  108.         flag.
  109.  
  110. DEFINED         ( -- here 0 | adr false )
  111.         Look up the next word in the input stream. Return true if it
  112.         exists, otherwise false. Maybe ignore case.
  113.  
  114. STACKUNDER      ( -- )
  115.         Abort with an error message "Stack underflow".
  116.  
  117. STACKOVER       ( -- )
  118.         Abort with an error message "Stack overflow".
  119.  
  120. WARNOVER        ( -- )
  121.         Print a warning message "Running out of CODE memory!" .
  122.  
  123. (?STACK)        ( -- )
  124.         Default version of ?STACK to check stack depth for overfkow,
  125.         underflow, or if we ar close to running out of memory.
  126.  
  127. ?STACK          ( -- )
  128.         Check for parameter stack underflow or overflow and issue
  129.         appropriate error message if detected.
  130.  
  131. STATUS          ( -- )
  132.         Indicate the current status of the system.
  133.  
  134. INTERP          ( -- )
  135.         The default Forth Interpret Loop .
  136.  
  137. INTERPRET       ( -- )
  138.         The Forth Interpret Loop. If the next word is defined, execute it,
  139.         otherwise convert it to a number and push it onto the stack.
  140.  
  141. PRINT           ( | <words-to-be-interpreted> -- )
  142.         Interpret the following words, and output to printer.
  143.  
  144. ALLOT           ( n -- )
  145.         Allocate more space in the dictionary.
  146.  
  147. ,               ( n -- )
  148.         Set the contents of the dictionary to the arbitrary 16-bit value on
  149.         the stack. 
  150.  
  151. C,              ( char -- )
  152.         Same as , except uses an 8-bit value.
  153.  
  154. PARAGRAPH     ( offset -- paragraph-inc )
  155.         Align the offset to a paragraph boundary.
  156.  
  157. ALIGN           ( -- )
  158.         Used to force even addresses. A noop on the 8086.
  159.  
  160. EVEN            ( n1 -- n2 )
  161.         Makes the top of the stack an EVEN number. A noop on the 8086.
  162.  
  163. COMPILE         ( | <name> -- )
  164.         Compile the (typically not-immediate) following word <name> when
  165.         this definition executes. Name is later compiled into the LIST
  166.         dictionary space.
  167.  
  168. IMMEDIATE       ( -- )
  169.         Mark the last Header as an Immediate word.
  170.  
  171. LITERAL         ( n -- )
  172.         Compile the single integer from the stack as a literal.
  173.  
  174. DLITERAL        ( d# -- )
  175.         Compile the double integer from the stack as a literal. 
  176.  
  177. ASCII           ( | <char> -- n )
  178.         Compile the next character in the input stream as a literal ASCII
  179.         integer.
  180.  
  181. CONTROL         ( | <char> -- n )
  182.         Compile the next character in the input stream as a literal ASCII
  183.         Control Character.
  184.  
  185. CRASH           ( -- )
  186.         Default routine called by execution vectors.
  187.  
  188. ?MISSING        ( f1 -- )
  189.         Tell user the word does not exist.
  190.  
  191. '               ( | <name> -- cfa )
  192.         Return the code field address of the next word <name>.
  193.  
  194. [']             ( | <name> -- )
  195.         Like ' only used while compiling
  196.  
  197. [COMPILE]       ( | <name> -- )
  198.         Force compilation of an immediate word
  199.  
  200. "BUF            ( -- adr )
  201.         Address of a string buffer in normal memory.
  202.  
  203. XEVEN           ( xdp -- xdp_even ) 
  204.         Convert an offset in list space to next even value, if not
  205.         already even.
  206.  
  207. XALIGN          ( -- ) 
  208.         Align the pointer XDP to the next even address, if not already
  209.         even.
  210.  
  211. X>"BUF          ( -- "buf )
  212.         Move an in-line string in list space to code space.        
  213.  
  214. (")             ( | <string> -- adr len )
  215.         Return the address and length of the inline string, and continue
  216.         execution after the string.
  217.  
  218. (X")            ( -- adr len )
  219.         Move a compiled string from list space to "BUF in code space,
  220.         and return the address and count of the string.
  221.  
  222. %(.")           ( -- )
  223.         Type the inline string, and continue execution after the string.
  224.  
  225. (.")            ( -- )
  226.         Type the inline compiled string, and continue execution after the
  227.         string. This is a defered word.
  228.  
  229. ,"              ( | <string> -- )
  230.         Add the following text string till a " to the dictionary in CODE
  231.         space.
  232.  
  233. X,"             ( | <string> -- )
  234.         Add the following text string till a " to LIST space.
  235.  
  236. ."              ( | <string> -- )
  237.         Compile the string till a " to be typed out later. The string is
  238.         placed into LIST space. It is also displayed from LIST space.
  239.  
  240. "               ( | <string> -- )
  241.         Compile the string into CODE space. Return address and length at
  242.         runtime.
  243.  
  244. ""              ( | <string> -- )
  245.         Compile the string into LIST space. String is moved to CODE space
  246.         at runtime returning address and length.
  247.  
  248. ">$             ( a1 len -- a2 )
  249.         Convert address a1 and length len of a string created with "
  250.         into a counted string address a2.  This word relys on the fact
  251.         that " really creates counted strings, but converts them to
  252.         address and length on execution.
  253.  
  254. FENCE   is the limit address for forgetting.
  255.  
  256. TRIM            ( fadr voc-adr -- )
  257.         Change the hash pointers in a vocabulary so that they are all
  258.         less than a specified value, fadr.
  259.  
  260. (FRGET)         ( code-adr relative-link-adr -- )
  261.         Forgets part of the dictionary. Both the code address and the
  262.         header address are specified, and may be independent. (FRGET)
  263.         resets all of the links and releases the space.
  264.  
  265. FORGET          ( | <name> -- )
  266.         Forget all of the code and headers before <name>. FORGET must be
  267.         used with caution, if you are using DEFERS or UDEFERS, FORGET will
  268.         not know about these chains, so they must be unlinked before using
  269.         FORGET or disaster WILL strike.
  270.  
  271. ?ERROR          ( a1 n1 f1 -- )
  272.         If f1 true, display message a1,n1 and QUIT. Change this to alter
  273.         the way ABORT" works.
  274.  
  275. (?ERROR)        ( a1 n1 f1 -- )
  276.         Default for ?ERROR. If f1 true, display message a1,n1 reset stacks,
  277.         turn off printing and QUIT.
  278.  
  279. (ABORT")        ( f1 -- )
  280.         The Runtime code compiled by ABORT". Uses ?ERROR, and resets
  281.         return stack.
  282.  
  283. ABORT"          ( f1 | <message" -- )
  284.         If the flag is true, issue <message> and ABORT.
  285.  
  286. ABORT           ( -- )
  287.         Clear the data stack and QUIT; no message is displayed.
  288.  
  289. ?CONDITION      ( f1 -- )
  290.         Simple compile time error checking. Usually adequate.
  291.  
  292. >MARK           ( -- adr )
  293.         Set up for a Forward Branch.
  294.  
  295. >RESOLVE        ( adr -- )
  296.         Resolve a Forward Branch.
  297.  
  298. <MARK           ( -- adr )
  299.         Set up for a Backwards Branch.
  300.  
  301. <RESOLVE        ( adr -- )
  302.         Resolve a Backwards Branch.
  303.  
  304. ?>MARK          ( -- f1 adr )
  305.         Set up a forward Branch with Error Checking.
  306.  
  307. ?>RESOLVE       ( f1 adr -- )
  308.         Resolve a forward Branch with Error Checking.
  309.  
  310. ?<MARK          ( -- f1 adr )
  311.         Set up for a Backwards Branch with Error Checking. 
  312.  
  313. ?<RESOLVE       ( f1 adr -- )
  314.         Resolve a backwards Branch with Error Checking.
  315.  
  316. LEAVE           ( -- )
  317.         Immediately exit a DO-LOOP.
  318.  
  319. ?LEAVE          ( f1 -- )
  320.         Immediately exit a DO-LOOP if the flag is true; else continue
  321.         looping.
  322.  
  323. BEGIN           ( -- )
  324.         Used in the form:           BEGIN ... AGAIN, 
  325.                                 or  BEGIN ... flag UNTIL, 
  326.                                 or  BEGIN ... flag WHILE ... REPEAT
  327.  
  328. AGAIN           ( -- )
  329.         Unconditional jump to just after BEGIN in a BEGIN ... AGAIN loop.
  330.  
  331. UNTIL           ( f1 -- )
  332.         Marks end of a BEGIN ... UNTIL loop; terminate if flag f1 is true.
  333.  
  334. WHILE           ( f1 -- )
  335.         Used in the form  BEGIN <loop> flag WHILE <true> REPEAT.
  336.         Repeat <loop> and <true> clauses while the flag f1 is true (really,
  337.         non-zero).
  338.         
  339. REPEAT          ( -- )
  340.         Unconditional backward branch to just after BEGIN in a  
  341.         BEGIN  <loop>  flag WHILE  <true>  REPEAT   loop. 
  342.  
  343. DO              ( limit start -- )
  344.         Initialize a loop structure with index running from start to limit-1. 
  345.         Used in the form   DO ... LOOP   or  DO ... +LOOP
  346.  
  347. ?DO             ( limit start -- )
  348.         Same as DO except that the loop will not be executed if start = lim.
  349.  
  350. LOOP            ( -- )
  351.         Terminate a loop structure. Increment loop index by one and repeat
  352.         <loop-body> until loop index crosses the boundary between limit and
  353.         limit - 1.
  354.         Used in the form   DO <loop-body> LOOP.
  355.  
  356. +LOOP           ( n -- )
  357.         Terminate a loop structure. Increment loop index by n and repeat
  358.         <loop-body> until loop index crosses the boundary between limit and
  359.         limit - 1.
  360.         Used in the form   DO <loop-body> LOOP.
  361.  
  362. IF              ( f1 -- )
  363.         Used in the form: f1 IF <true> ELSE <false> THEN  (ELSE is
  364.         optional). If f1 is false, branches forward to <false> or after
  365.         THEN.
  366.  
  367. ELSE            ( -- )
  368.         Used in the form: flag IF <true> ELSE <false> THEN. If flag is
  369.         false, branches forward to <false>.
  370.  
  371. THEN            ( -- )
  372.         Terminate a branch structure.
  373.         Used in the form   flag IF ... ELSE ... THEN
  374.  
  375. FORWARD         ( -- )
  376.         Do not use this word.  It may well be deleted in the future!
  377.  
  378. CONTINUE        ( -- )
  379.         Do not use this word.  It may well be deleted in the future!
  380.  
  381. BREAK           ( -- ) 
  382.         Do not use this word.  It may well be deleted in the future!
  383.  
  384. AFT             ( -- )
  385.         Do not use this word.  It may well be deleted in the future!
  386.  
  387. FOR             ( n1 -- )
  388.         Begin a count-down loop.  The index  I  inside the loop is
  389.         set initially to n1 .
  390.  
  391. NEXT            ( -- )
  392.         If the loop counter I is non-zero, decrement it and loop back
  393.         the the code following the matching  FOR .  If the loop counter
  394.         is zero, discard it and continue execution.
  395.  
  396. ,VIEW           ( -- )
  397.         Calculate and compile the VIEW field of the header. 
  398.  
  399. NOHEADROOM      ( -- )
  400.         Print an error message indicating that Head space is exhausted.
  401.  
  402. NOLISTROOM      ( -- )
  403.         Print an error message indicating that List space is exhausted.
  404.  
  405. SPCHECK         ( -- f1 f2 )
  406.         Check stack and list space.
  407.  
  408. %ALREADY_DEF    ( a1 -- a1 ) 
  409.         If the word at address a1 is already defined, print a warning
  410.         message.
  411.  
  412. ?ALREADY_DEF    ( a1 -- a1 ) 
  413.         If the word at address a1 is already defined, print a warning
  414.         message.
  415.  
  416. "HEADER         ( | <name> -- )
  417.         The string <name> to make a header, and initialize  the code field.
  418.         First we check for duplicates. Then we make  entry in >NAME hash
  419.         table if appropriate. Next lay down the  view field. Then we hook
  420.         in to the correct thread an make the  link field. We set up LAST so
  421.         that it points to our name  field. Then we copy the name to YSEG and
  422.         delimit the name  field bits. Then we make the pointer in the YSEG to
  423.         the CFA.  Then we add a stopper entry to >NAME hash table in case of
  424.         a large ALLOT or end of dictionary. Does all of its work in HEAD
  425.         space, has no effect on CODE space whatsoever.
  426.  
  427. ,CALL           ( -- )
  428.         Compiles a CALL to address ZERO, the actual branch address is set
  429.         later by ;USES or ;CODE.  See CREATE, VARIABLE, CONSTANT & :
  430.  
  431. ,JUMP           ( -- )
  432.         Compiles a JMP to address ZERO, the actual jump address is set
  433.         later by ;USES or ;CODE.  See CREATE, VARIABLE, CONSTANT & :
  434.  
  435. <HEADER>        ( | name -- )
  436.         Creates a NAME header in HEAD space, but compiles absolutely
  437.         nothing in CODE space.  The head created, does point at HERE
  438.         though.
  439.         
  440. HEADER          ( | <name> -- )
  441.         Creates a NAME header in HEAD space, but compiles absolutely
  442.         nothing in CODE space.  The head created, does point at HERE
  443.         though.  A defered word.
  444.  
  445. "CREATE         ( str-adr -- )
  446.         Make a header for the word pointed to at the string address.
  447.  
  448. CREATE          ( | <name> -- )
  449.         Make a header for the next word in the input stream.
  450.  
  451. !CSP            ( -- )
  452.         Save the current stack level for error checking. 
  453.  
  454. ?CSP            ( -- )
  455.         Issue error message if stack has changed.
  456.  
  457. HIDE            ( -- )
  458.         Removes the Last definition from the Header Dictionary.
  459.  
  460. REVEAL          ( -- )
  461.         Activates the Last definition in the Header Dictionary.
  462.  
  463. (;USES)         ( -- )
  464.         Set the code field to the contents of following cell 
  465.  
  466. ;USES           ( -- )
  467.         Similar to the traditional ;CODE except used when  run time code has
  468.         been previously defined.
  469.  
  470. (;CODE)         ( -- )
  471.         Set the code field to the address of the following. 
  472.  
  473. ;CODE           ( -- )
  474.         Used for defining the run time portion of a defining  word in low
  475.         level code.
  476.  
  477. DOES>           ( -- )
  478.         Specifies the run time of a defining word in high  level Forth.
  479.  
  480. ASSEMBLER       ( -- )
  481.         The VOCABULARY that contains all of the assembler definitions.
  482.  
  483. [               ( -- )
  484.         Stop compiling and start interpreting.
  485.  
  486. ]               ( -- )
  487.         The Compiling Loop. First sets Compile State. Looks up the next word
  488.         in the input stream and either executes it or compiles it depending
  489.         upon whether or not it is immediate. If the word is not in the
  490.         dictionary, it converts it to a number, either single or double
  491.         precision depending on whether or not any punctuation was present.
  492.         Continues until input stream is empty or state changes.
  493.  
  494. MAKEDUMMY       ( | <name> -- )
  495.         Make a dummy : definitions out of <name>.  Effectively a NOOP,
  496.         used by ANEW.
  497.  
  498. ANEW            ( | <name> -- )
  499.         Define A NEW definition <name>.  If <name> already exists, then
  500.         we FORGET it before making the new one.  A nice utility to allow
  501.         re-loading a file again and again for debugging purposes.  I don't
  502.         know where this furst originated, but I learned of it from
  503.         RAY ISAAC at CALOS, a real neat trick.
  504.  
  505. (:)             ( -- )
  506.         Begin a colon definition.
  507.  
  508. :               ( -- )
  509.         Defines a colon definition. The definition is hidden until it is
  510.         completed, or the user desires recursion. The runtime for : adds a
  511.         nesting level.
  512.  
  513. ;               ( -- )
  514.         Terminates a colon definition. Compiles the runtime code to remove a
  515.         nesting level, and changes STATE so that compilation will terminate.
  516.  
  517. RECURSIVE       ( -- )
  518.         Allow the current definition to be self referencing.
  519.  
  520. CONSTANT        ( n | <name> -- )
  521.         A defining word that creates constants. At runtime the value of the
  522.         constant is placed on the stack.
  523.  
  524. VALUE           ( n | <name> -- )
  525.         A defining word that creates values.  At runtime the contents of the
  526.         value is placed on the stack.  The contents of the value may be 
  527.         changed by using =: .
  528.  
  529. VARIABLE        ( | <name> -- )
  530.         A defining word to create variables. At runtime the address of the
  531.         variable is placed on the stack.
  532.  
  533. DEFER           ( | <name> -- )
  534.         Define a vectored execution word. These are initially set to display
  535.         an error message. They are initialized with IS. 
  536.  
  537. VOCABULARY      ( -- )
  538.         Defines a new Forth vocabulary. 
  539.  
  540. DEFINITIONS     ( -- )
  541.         Subsequent definitions will be placed into CURRENT. 
  542.  
  543. 2CONSTANT       ( d# | <name> -- )
  544.         Create a double number constant.
  545.  
  546. 2VARIABLE       ( | <name> -- )
  547.         Create a double length variable.
  548.  
  549. <RUN>           ( -- )
  550.         Interpret or compile whatever is in the TERMINAL INPUT BUFFER.
  551.         Tests STATE, and does the appropriate thing.
  552.  
  553. RUN             ( -- )
  554.         Interpret or compile whatever is in the TERMINAL INPUT BUFFER.
  555.         Tests STATE, and does the appropriate thing.  A defered word.
  556.  
  557. ERRFIX          ( -- )
  558.         A defered word to handle certain error conditions.
  559.  
  560. (?ERROR)        ( adr len f1 -- )
  561.         If the flag f1 is false, drop the other two parameters.  If the
  562.         flag is true, restore  RUN  to its default value, execute ERRFIX , 
  563.         initialize the stack pointer, set PRINTING off, display the
  564.         message at adr, then execute  QUIT .
  565.  
  566.  
  567.