adoc/p_create.adoc

   1 // compile.asm: WORD p_create,'CREATE',fasm
   2
   3 anchor:p_create[]
   4
   5 === Word: CREATE
   6
   7
   8 ....
   9 Data stack: ( char* n -- tfa )
  10 ....
  11
  12 "CREATE" is a function word that allocates a "word header" with the
  13 indicated [n:char*] print name, and returns the "TFA" (Token Field
  14 Address) of the word. The header memory layout is as follows:
  15
  16 ====
  17 ----
  18 struct WORD
  19 TFA  8 link ; tfa of previous word
  20 pCFA 8 cfap ; CFA = Code Field Address of this word
  21      8 flags ;
  22 PFA  8 length ; length of pname representation
  23      ? pname ; the pname bytes
  24      1 nul ; a forced nul byte following the pname
  25 pTFA 8 tfap ; TFA = Token Field Address of this word
  26 OFF  8 doff ; entry offset for FORTH level execution
  27 CFA  8 doer ; word execution semantics
  28 DFA  0 content ; DFA = Data Field Address
  29 end_struct
  30 ----
  31 ====
  32
  33 A "word" is generally understod as a marker in memory for some content
  34 as held in the memory space following the DFA (Data Field Address).
  35
  36 The words CFA (Code Field Address) is the most important field for
  37 RRQFORTH execution, as holding a jump address to the assembly code
  38 that implements the particular execution semantics for the word.
  39 "CREATE" will assign this as "dovariable", which makes the word push
  40 its DFA when executed. This is changed to "doforth" for RRQFORTH
  41 function words initiated by ":" (aka "COLON") or changed to "dovalue"
  42 for RRQFORTH constants created by "CONSTANT".
  43
  44 ====
  45 .Word: CREATE
  46 [caption='Definition concept {counter:exec}: ']
  47 ----
  48 HERE @ R> ( save tfa on RS )
  49   R@ CURRENT-WORD @ DUP @ , ! ( link in a new word )
  50   DUP 49 + R@ + ,             ( pCFA )
  51   0 ,                         ( flags )
  52   DUP , ( length )
  53   HERE @ ROT ROT MEMCPY 0 C,  ( pname + NUL )
  54   R@ ,                        ( pTFA )
  55   0 ,                         ( OFF )
  56   doVARIABLE                  ( CFA, default semantics )
  57 ----
  58 ====
  59
  60 .Usage example: a possible definition of CONSTANT
  61 ****
  62 : CONSTANT READ-WORD CREATE TFA>DFA doVALUE OVER 8 - ! ! ;
  63 ****
  64
  65 See also <<p_put,!>>, <<p_plus,+>>, <<p_comma>>, <<p_get,@>>,
  66 <<p_Ccomma>>, <<p_current_word,CURRENT-WORD>>, <<p_dup,DUP>>,
  67 <<p_here,HERE>>, <<p_herememcpy,HERE>>, <<p_Rget,R@>>, <<p_rot,ROT>>,
  68 and <<p_dovariable,doVARIABLE>>,
  69 as well as <<p_execute,EXECUTE>>
  70 about the range of "doer" assignments and their meanings.