adoc/p_create.adoc

   1 anchor:p_create[]
   2
   3 Word: CREATE
   4 ------------
   5
   6 ----
   7 compile.asm:    WORD p_create,'CREATE',fasm
   8 ----
   9
  10 Data stack: ( char* n -- tfa )
  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 See "<<p_execute,EXECUTE>>" about range of +doer+ assignments and
  45 their meanings.
  46
  47 .Execution semantics expressed in RRQFORTH
  48 ====
  49 HERE @ R> ( save tfa on RS )
  50   R@ CURRENT-WORD @ DUP @ , ! ( link in a new word )
  51   DUP 49 + R@ + ,             ( pCFA )
  52   0 ,                         ( flags )
  53   DUP , ( length )
  54   HERE @ ROT ROT MEMCPY 0 C,  ( pname + NUL )
  55   R@ ,                        ( pTFA )
  56   0,                          ( OFF )
  57   doVARIABLE                  ( CFA, default semantics )
  58 ====
  59
  60 .Usage example
  61 ====
  62 \ A possible definition of the word CONSTANT
  63 : CONSTANT
  64   READ-WORD CREATE TFA>DFA doVALUE OVER 8 - ! !
  65 ;
  66 ====
  67