Home Building DHTML Scripting Using Diaperglu Documention Key Script Commands Reference C Library API Reference Handy References About License Contact Forth Draft Standard
Directory Documentation key   C Functions dg_forthnewdefinition dg_forthgetswordhead dg_forthtohead dg_forthlinkdefinition dg_forthnewsubroutinedefinition dg_forthnewvariabledefinition dg_forthnewconstantdefinition dg_forthgetnewestdefinitioninwordlist dg_forthgetnextdefinition dg_forthfinddefinitioninwordlist dg_forthfinddefinitioninsearchorder dg_forthputnewestdefinitioncompiletype dg_forthcreateov dg_forthcreateoc dg_forthlatest dg_forthbracketlatest dg_forthgetcompileroutine dg_forthsetcompileroutine dg_forthgetodf dg_forthsetodf dg_forthtoorder dg_forthorderfrom dg_forthdotwordname dg_forthshowwordlist dg_forthshowsortedwordlist dg_forthshowallwords dg_forthforthwords dg_forthbufferwords dg_fortherrorwords dg_forthenvironmentwords dg_forthstringwords dg_forthlibrarywords dg_forthuserwords dg_forthsafe dg_forthiscolon dg_forthisoto dg_forthisobto dg_forthispto dg_forthiscallproc dg_forthiscallprocretuint128 dg_forthiscompilecall dg_forthstringtonewprocword dg_forthstringtonewobword dg_forthemptywordlist dg_forthtocurrent dg_forthcurrentfrom WORDLIST. CREATE-[WORDLIST.]
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthnewdefinition ( NEWDEFINITION NEWWORD )
//
// C prototype:
//  void dg_forthnewdefinition (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle*  pBHarrayhead      pointer to a Bufferhandle structure which is 
//                                    used as the bufferhandle for the array where the  
//                                    other bufferhandles are stored         
//
// Stack action shorthand:
//  ( compilebufoffset compilebufid databufoffset databufid pname namelength -- 
//     executiontoken )
//
// Data stack in:
//  compilebufoffset                 compile type routine's buffer offset
//  compilebufid                     compile type routine's buffer id
//  databufoffset                    data's buffer offset 
//                                    (or in some cases, the data low 64 bits)
//  databufid                        data's buffer id     
//                                    (or in some cases, the data hi 64 bits)
//  pname                            pointer to the name string
//  namelength                       length of the name string in characters (bytes)
//
// Data stack out:
//  executiontoken                   unique identifier for this definition
//
// Action:
//  this creates a new definition using the parameters
//
// Note: 
//  this does not link the definition into a word list
//
// Failure cases:
//  error getting a pointer to the data stack
//  data stack underflow
//  error creating the new definition (the subroutine pushes an error)
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthgetswordhead ( GETPDEFINITION GETSWORDHEAD )
//
// C prototype:
//  void dg_forthgetswordhead (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle*  pBHarrayhead      pointer to a Bufferhandle structure which is 
//                                    used as the bufferhandle for the array where the 
//                                    other bufferhandles are stored         
//
// Stack action shorthand:
//  ( xt -- addr u )
//
// Data stack in:
//  xt                               unique identifier for the word
//
// Data stack out:
//  addr                             pointer to the word's header
//  u                                length of the word's header in bytes
//
// Action:
//  this returns a pointer to the word's header and it's length
//
// Failure cases:
//  error getting a pointer to the data stack
//  data stack underflow
//  error creating the pointer to the definition (subroutine returns an error)
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthtohead ( >HEAD )
//
// C prototype:
//  void dg_forthtohead (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle*  pBHarrayhead      pointer to a Bufferhandle structure which is 
//                                    used as the bufferhandle for the array where the 
//                                    other bufferhandles are stored         
//
// Stack action shorthand:
//  ( xt -- addr )
//
// Data stack in:
//  xt                               unique identifier for the word
//
// Data stack out:
//  addr                             pointer to the word's header
//
// Action:
//  this returns a pointer to the word's header
//
// Failure cases:
//  error calling dg_forthgetpdefinition
//  calling dg_forthdrop
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthlinkdefinition ( LINKDEFINITION LINKWORD )
//
// C prototype:
//  void dg_forthlinkdefinition (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle*  pBHarrayhead      pointer to a Bufferhandle structure which is 
//                                    used as the bufferhandle for the array where the 
//                                    other bufferhandles are stored         
//
// Stack action shorthand:
//  ( executiontoken wordlistid -- )
//
// Data stack in:
//  executiontoken                   unique identifier for the word
//  wordlistid                       the word is added to this word list
//
// Action:
//  links the word onto the end of the word list
//
// Failure cases:
//  error getting a pointer to the data stack
//  data stack underflow
//  error linking the definition into the word list (subroutine returns an error)
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthnewsubroutinedefinition ( NEWSUBROUTINEDEFINITION )
//
// C prototype:
//  void dg_forthnewsubroutinedefinition (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle*  pBHarrayhead      pointer to a Bufferhandle structure which is 
//                                    used as the bufferhandle for the array where the 
//                                    other bufferhandles are stored         
//
// Stack action shorthand:
//  ( pname namelength -- executiontoken )
//
// Data stack in:
//  pname                            pointer to character string containing name for the 
//                                    new subroutine
//  namelength                       length of the name in characters (bytes)
//
// Data stack out:
//  executiontoken                   unique identifier for the definition                     
//
// Action:
//  Creates a new subroutine threaded definition with the name. 
//  The compile type routine is call subroutine in execute mode and
//   compile call subroutine in compile mode.
//  The data pointer is set to point to the next unused byte in the current compile 
//   buffer.
//
// Note: 
//   A subroutine definition does NOT get linked into a word list at time of creation
//   This is to allow you to make a new definition with the same name that calls the 
//    old definition, among other things.
//
// Failure cases:
//  error getting a pointer to the data stack
//  data stack underflow
//  error creating the definition (subroutine returns an error)
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthnewvariabledefinition ( NEWVARIABLEDEFINITION )
//
// C prototype:
//  void dg_forthnewvariabledefinition (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle*  pBHarrayhead      pointer to a Bufferhandle structure which is 
//                                    used as the bufferhandle for the array where the 
//                                    other bufferhandles are stored         
//
// Stack action shorthand:
//  ( pname namelength -- executiontoken )
//
// Data stack in:
//  pname                            pointer to character string containing name for the 
//                                    new variable
//  namelength                       length of the name in characters (bytes)
//
// Data stack out:
//  executiontoken                   unique identifier for the definition                     
//
// Action:
//  Creates a new variable definition with the name. 
//  The compile type routine is calculate and push address in execute mode and
//   compile calculate and push address in compile mode.
//  The data pointer is set to point to the next unused byte in the current new 
//   variable buffer.
//  Links the definition to the current new definition word list.
//
// Failure cases:
//  error getting a pointer to the data stack
//  data stack underflow
//  error creating the definition (subroutine returns an error)
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthnewconstantdefinition ( NEWCONSTANTDEFINITION )
//
// C prototype:
//  void dg_forthnewconstantdefinition (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle*  pBHarrayhead      pointer to a Bufferhandle structure which is 
//                                    used as the bufferhandle for the array where the 
//                                    other bufferhandles are stored         
//
// Stack action shorthand:
//  ( constant pname namelength -- executiontoken )
//
// Data stack in:
//  constant                         integer (64 bits)
//  pname                            pointer to character string containing name for the 
//                                    new variable
//  namelength                       length of the name in characters (bytes)
//
// Data stack out:
//  executiontoken                   unique identifier for the definition                     
//
// Action:
//  Creates a new constant definition with the name. 
//  The compile type routine is push integer (32 bit) to data stack in execute mode 
//   and compile push integer (32 bit) to data stack in compile mode.
//  The data pointer's offset is set to the value of the intger and the data 
//   pointer's buffer id is set to 0 and not used.
//  Links the definition to the current new definition word list.
//
// Failure cases:
//  error getting a pointer to the data stack
//  data stack underflow
//  error creating the definition (subroutine returns an error)
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthgetnewestdefinitioninwordlist ( GETNEWESTDEFINITIONINWORDLIST )
//
// C prototype:
//  void dg_forthgetnewestdefinitioninwordlist (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle*  pBHarrayhead      pointer to a Bufferhandle structure which is 
//                                    used as the bufferhandle for the array where the 
//                                    other bufferhandles are stored         
//
// Stack action shorthand:
//  ( wordlistid -- executiontoken )
//
// Data stack in:
//  wordlistid                       identifier of wordlist
//
// Data stack out:
//  executiontoken                   unique identifier for the definition                     
//
// Action:
//  Removes wordlistid from the data stack and pushes the executiontoken of the 
//   last created definition in the word list to the data stack.
//
// Failure cases:
//  error getting a pointer to the data stack
//  data stack underflow
//  error getting the latest definition (subroutine returns an error)
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthgetnextdefinition ( GETNEXTDEFINITION )
//
// C prototype:
//  void dg_forthgetnextdefinition (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle*  pBHarrayhead      pointer to a Bufferhandle structure which is 
//                                    used as the bufferhandle for the array where the 
//                                    other bufferhandles are stored         
//
// Stack action shorthand:
//  ( executiontoken -- nextexecutiontoken )
//
// Data stack in:
//  executiontoken                   unique identifier for the definition
//
// Data stack out:
//  nextexecutiontoken               unique identifier for the next definition in the 
//                                    word list's linked list of definitions                    
//
// Action:
//  Execution tokens get linked into a word list's linked list. This routine removes  
//   the execution token from the data stack and pushes the next execution token in 
//   the linked list to the data stack.
//
// Failure cases:
//  error getting a pointer to the data stack
//  data stack underflow
//  error getting the next definition (subroutine returns an error)
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthfinddefinitioninwordlist ( FINDDEFINITIONINWORDLIST )
//
// C prototype:
//  void dg_forthfinddefinitioninwordlist (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle*  pBHarrayhead      pointer to a Bufferhandle structure which is 
//                                    used as the bufferhandle for the array where the 
//                                    other bufferhandles are stored         
//
// Stack action shorthand:
//  ( wordlistid pname namelength -- executiontoken )
//
// Data stack in:
//  wordlistid                       identifier of wordlist
//  pname                            pointer to string containing name to look up
//  namelength                       number of characters (bytes) in name
//  
// Data stack out:
//  executiontoken                   unique identifier for the definition or 
//                                    ENDOFWORDLIST  if not found
//
// Action:
//  Removes parameters from the data stack.
//  Looks up name in the word list's linked list of definitions.
//  If the name is found the execution token of the name is pushed to the data stack.
//  If the name is not found ENDOFWORDLIST is pushed to the data stack.
//
// Failure cases:
//  error getting a pointer to the data stack
//  data stack underflow
//  error finding the definition in the word list (subroutine returns an error)
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthfinddefinitioninsearchorder ( FINDDEFINITIONINSEARCHORDER )
//
// C prototype:
//  void dg_forthfinddefinitioninsearchorder (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle*  pBHarrayhead      pointer to a Bufferhandle structure which is 
//                                    used as the bufferhandle for the array where the 
//                                    other bufferhandles are stored         
//
// Stack action shorthand:
//  ( pname namelength -- executiontoken )
//
// Data stack in:
//  pname                            pointer to string containing name to look up
//  namelength                       number of characters (bytes) in name
//  
// Data stack out:
//  executiontoken                   unique identifier for the definition or 
//                                    ENDOFWORDLIST if not found
//
// Action:
//  Removes parameters from the data stack.
//  Looks up name in each of the current search order's word lists.
//  If the name is found the execution token of the name is pushed to the data stack.
//  If the name is not found ENDOFWORDLIST is pushed to the data stack.
//
// Failure cases:
//  error getting a pointer to the data stack
//  data stack underflow
//  error finding the definition in the search order (subroutine returns an error)
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthputnewestdefinitioncompiletype ( PUTNEWESTDEFINITIONCOMPILETYPE )
//
// C prototype:
//  void dg_forthputnewestdefinitioncompiletype (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle*  pBHarrayhead      pointer to a Bufferhandle structure which is 
//                                    used as the bufferhandle for the array where the  
//                                    other bufferhandles are stored         
//
// Stack action shorthand:
//  ( compilebuffoffset compilebufid -- )
//
// Data stack in:
//  compilebufoffset                 offset of compile type routine in its buffer 
//                                    (or its address if it's not in a buffer)
//  compilebufid                     the buffer id of the compile type routine 
//                                    (or DG_CORE_BUFFERID if it's not in a buffer)
//
// Action:
//  Replaces the pointer to the compile type routine of the last created definition 
//   with this.
//
// Failure cases:
//  error getting a pointer to the data stack
//  data stack underflow
//  error changing the compile routine of the last created definition 
//   (subroutine returns an error)
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthcreateov ( CREATEOV )
//
// C prototype:
//  void dg_forthcreateov (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//  
// Stack action shorthand:
//  ( "<delimiters>word<delimiters>morestuff" -currentinputbuffer-
//     "<delimiters>morestuff" )
//  ( -masterdefinitionarray- newovdefinition )
//  ( -currentnewwordwordlist- newovdefinition )
//
// Current input buffer's current offset in:
//  "<delimiters>word<delimiters>morestuff" 
//
// Current input buffer's current offset out:
//  "<delimiters>morestuff"           
//                                                            
// Action:
//  Moves the current offset pointer for the current input buffer to the character after 
//   the next word or to the end of the current input buffer if no word is found
//  Then creates a new definition in the current wordlist that:
//   in execute mode, pushes the offset and bufferid of the current new variable 
//    buffer's current length
//   in compile mode, compiles code to push the offset and bufferid of the current 
//    compile new variable buffer's current length
//    the current length used is the length at the time CREATEOV is called, and 
//    is the length from the user's pointer of view... so in other words, the 
//    definition created will contain the offset and buffer id of the next stuff 
//    reserved with ALLOT C, or , in the current new variable buffer.
//
// Note:
//
//  When Diaperglu first starts, the current compile buffer and current new variable 
//   buffer point to the same buffer and this buffer's' size is locked to not grow 
//   so you don't have to worry about it moving. This is so Diaperglu will be 
//   compatible with older Forth programs which may keep pointers around for a long 
//   time. If you change PCURRENTNEWVARIABLEBUFFER or PCURRENTCOMPILEBUFFER,
//   then you have to worry about the life of the pointers from variables you CREATE 
//   in the new buffer.
//   Using CREATEOC and CREATEOV is one way to get around the problem of your 
//   pointers going bad when the current compile buffer or current new variable 
//   buffer moves while growing.
//  
//   This routine and it's partner CREATEOV are more generic versions of CREATE and 
//   let you specify which buffer the new definition is for. NEWDEFINITION can give 
//   you even more control.
//
// Failure cases:
//  error getting current input buffer id
//  error gettint a pointer to the current input buffer
//  error getting the current data space buffer id
//  error getting a pointer to the current data space buffer
//  next word in input buffer wasn't found 
//   (no more non delimiters before the end of the input buffer)
//  error creating the new constant definition
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthcreateoc ( CREATEOC )
//
// C prototype:
//  void dg_forthcreateoc (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//  
// Stack action shorthand:
//  ( "<delimiters>word<delimiters>morestuff" -currentinputbuffer-
//     "<delimiters>morestuff" )
//  ( -masterdefinitionarray- newovdefinition )
//  ( -currentnewwordwordlist- newovdefinition )
//
// Current input buffer's current offset in:
//  "<delimiters>word<delimiters>morestuff" 
//
// Current input buffer's current offset out:
//  "<delimiters>morestuff"           
//                                                            
// Action:
//  Moves the current offset pointer for the current input buffer to the character after 
//   the next word or to the end of the current input buffer if no word is found
//  Then creates a new definition in the current wordlist that:
//   in execute mode, pushes the offset and bufferid of the current compile buffer's
//    current length 
//   in compile mode, compiles code to push the offset and bufferid of the current 
//    compile buffer's current length. The current length used is the length at the 
//    time CREATEOC is called, and is the length from the user's pointer of view... 
//    so in other words, the definition created will contain the offset and buffer id 
//    of the next stuffthat will be compiled to the current compile buffer.
//
//
// Note:
//
//  When Diaperglu first starts, the current compile buffer and current new variable 
//   buffer point to the same buffer and this buffer's' size is locked to not grow so 
//   you don't have to worry about it moving. This is so Diaperglu will be compatible
//   with older Forth programs which may keep pointers around for a long time. If you
//   change PCURRENTNEWVARIABLEBUFFER or PCURRENTCOMPILEBUFFER, then you have to worry
//   about the life of the pointers from variables you CREATE in the new buffer.
//   Using CREATEOC and CREATEOV is one way to get around the problem of your pointers 
//   going bad when the current compile buffer or current new variable buffer moves 
//   while growing.
//  
//   This routine and it's partner CREATEOV are more generic versions of CREATE and 
//    let you specify which buffer the new definition is for. NEWDEFINITION can give 
//    you even more control.
//
// Failure cases:
//  error getting current input buffer id
//  error gettint a pointer to the current input buffer
//  error getting the current data space buffer id
//  error getting a pointer to the current data space buffer
//  next word in input buffer wasn't found 
//   (no more non delimiters before the end of the input buffer)
//  error creating the new constant definition
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthlatest ( LATEST )  
//
// C prototype:
//  void dg_forthlatest (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- executiontoken )
//
// Data stack out:
//  executiontoken                unique identifier for a word
//                                                            
// Action:
//  Pushes the execution token of the last defined word onto the data stack.
//
// Failure cases:
//  not checked
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthbracketlatest ( [LATEST] )  
//
// C prototype:
//  void dg_forthbracketlatest (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- )
//
// Compiled code does:
//  ( -- executiontoken )
//
// Compiled code data stack out:
//  executiontoken                unique identifier for a word
//                                                            
// Action:
//  Compiles code that pushes the execution token of the last defined word onto the
//   data stack.
//
// Failure cases:
//  not checked
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthgetcompileroutine ( GETOCR )
//
// C prototype:
//  void dg_forthgetcompileroutine (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the
//                                 other bufferhandles are stored.
//  
// Stack action shorthand:
//  ( executiontoken -- compileroutineoffset compileroutinebufferid )
//
// Data stack in:
//  executiontoken                execution token of a word
//
// Data stack out:
//  compileroutineoffset          offset of compile routine
//  compileroutinebufferid        bufferid of compile routine           
//                                                            
// Action:
//  Gets the compile routine for the word having executiontoken as it's unique
//   identifier. 
//  The compile routine is the action the script interpreter takes when the word with  
//   this execute token is parsed. 
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthsetcompileroutine ( SETOCR )
//
// C prototype:
//  void dg_forthsetcompileroutine (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( offset bufferid executetoken -- )
//
// Data stack in:
//  offset                        offset of compile routine
//  bufferid                      bufferid of compile routine
//  executetoken                  execution token of word to change           
//                                                            
// Action:
//  Changes the compile routine for the word with executetoken. This is the action the 
//   script interpreter takes when the word with this execute token is parsed. 
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthgetodf ( GETODF )
//
// C prototype:
//  void dg_forthgetodf (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//  
// Stack action shorthand:
//  ( executiontoken -- datafieldoffset datafieldbufferid )
//
// Data stack in:
//  executiontoken               execution token of a word
//
// Data stack out:
//  datafieldoffset              offset of data field
//  datafieldbufferid            bufferid of data field
//                                                            
// Action:
//  Gets the data field for the word having execution token as it's unique identifier.
//
// Note:
//  The data field is passed to the action function for this execution token
//   when the script interpreter parses the word associated with this
//   execute token.
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthsetodf ( SETODF )
//
// C prototype:
//  void dg_forthsetodf (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( offset bufferid executetoken -- )
//
// Data stack in:
//  offset                        offset of data field
//  bufferid                      bufferid of data field
//  executetoken                  execution token of word to change           
//                                                            
// Action:
//  Changes the data field for the word with this executetoken.
//
// Note:
//  The data field is passed to the action function for this execution token
//   when the script interpreter parses the word associated with this
//   execute token.
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
// dg_forthtoorder ( >SEARCH-ORDER )
//
// C prototype:
//  void dg_forthtoorder (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( wid -- )
//  ( ... -order- ... wid )
// 
// Data stack in:
//  wid                           word list id 
//                     
// Action:
//  Pops a word list id off the data stack and pushes it onto the end of the search 
//   order stack.
//
// Failure cases:
//  error popping the data stack
//  error pushing to the search order stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthorderfrom ( SEARCH-ORDER> )
//
// C prototype:
//  void dg_forthorderfrom (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( wid ... -order- ... )
//  ( -- wid )
// 
// Data stack out:
//  wid                           word list id 
//                     
// Action:
//  Pops a word list id off the end of the search order stack and pushes it onto the 
//   data stack.
//
// Failure cases:
//  error popping the search order stack 
//  error pushing to the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthdotwordname ( .NAME )  
//
// C prototype:
//  void dg_forthdotwordname (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( executiontoken -- )
//  
// Data stack buffer in:
//  executiontoken                unique identifier of a definition
//                                                           
// Action:
//  displays the name associated with the definition's execution token
//
// Failure cases:
//  not checked
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthshowwordlist ( SHOW-WORDLIST )  
//
// C prototype:
//  void dg_forthshowwordlist (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( wordlistid -- )
//
// Data stack in:
//  wordlistid                    unique identifier of a word list
//                                                            
// Action:
//  displays the names of the words in the word list
//
// Failure cases:
//  not checked
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthshowsortedwordlist ( SHOW-SORTED-WORDLIST )
//
// C prototype:
//  void dg_forthshowsortedwordlist (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the other 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( wordlistid -- )
//
// Data stack in:
//  wordlistid                    unique identifier of a word list
//                                                            
// Action:
//  Displays the names of the words in the word list in sorted order.
//  This routine also shows a message after words that are out of order or that
//   are duplicates.
//
// Note:
//  Duplicates are ok. The last added one, (which is the last one shown) will be the
//   one found during a FIND.
//  If you see an out of order message, that means your word list is corrupt. This will
//   break how FIND works and some words will not be able to be found. You'll need to
//   fix it in order to use that wordlist... (you'll probably need to fix the source
//   code that created the wordlist and recompile.)
//
// Failure cases:
//  not checked
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthshowallwords ( SHOW-ALL-WORDS )
//
// C prototype:
//  void dg_forthshowallwords (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the  
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- )
//                                                            
// Action:
//  For each wordlist:
//   Displays the names of the words in each word list in sorted order.
//   This routine also shows a message after words that are out of order or that
//    are duplicates in a wordlist.
//
// Failure cases:
//  not checked
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthforthwords ( FORTH-WORDS )  
//
// C prototype:
//  void dg_forthforthwords (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- )
//                                                            
// Action:
//  shows the names of the definitions in the FORTH-WORDLIST
//
// Failure cases:
//  not checked
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_fortherrorwords ( ERROR-WORDS )  
//
// C prototype:
//  void dg_fortherrorwords (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- )
//                                                            
// Action:
//  shows the names of the definitions in the ERROR-WORDLIST
//
// Failure cases:
//  not checked
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthenvironmentwords ( ENVIRONMENT-WORDS )  
//
// C prototype:
//  void dg_forthenvironmentwords (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- )
//                                                            
// Action:
//  shows the names of the definitions in the ENVIRONMENT-WORDLIST
//
// Failure cases:
//  not checked
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthbufferwords ( BUFFER-WORDS )  
//
// C prototype:
//  void dg_forthbufferwords (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- )
//                                                            
// Action:
//  shows the names of the definitions in the BUFFER-WORDLIST
//
// Failure cases:
//  not checked
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthstringwords ( $-WORDS )  
//
// C prototype:
//  void dg_forthstringwords (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- )
//                                                            
// Action:
//  shows the names of the definitions in the STRING-WORDLIST
//
// Failure cases:
//  not checked
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthlibrarywords ( OS-WORDS )  
//
// C prototype:
//  void dg_forthlibrarywords (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the  
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- )
//                                                            
// Action:
//  shows the names of the definitions in the WINDOWS-WORDLIST
//
// Failure cases:
//  not checked
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthuserwords ( USER-WORDS )  
//
// C prototype:
//  void dg_forthuserwords (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- )
//                                                            
// Action:
//  shows the names of the definitions in the WINDOWS-WORDLIST
//
// Failure cases:
//  not checked
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthsafe ( SAFE )
//
// C prototype:
//  void dg_forthsafe (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- )
//                                                              
// Action:
//  If the compile type of the last defined word in the current create wordlist was 
//   dg_forthdocompiletypesubroutine, it is changed to 
//   dg_forthdocompiletypesafesubroutine. 
//  When a call to this last defined word is compiled, it uses this word's offset and 
//   bufferid for a return address instead of the actual address in case the buffer 
//   moves during this last defined word's execution.
//
// Failure cases:
//  error getting current vocabulary id
//  error getting latest definition execute token
//  error getting pointer to the latest definition 
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthiscolon ( IS-: )
//
// C prototype:
//  void dg_forthiscolon (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the  
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- )
//                                                              
// Action:
//   The compile type of the last defined word is changed to
//     dg_forthdocompiletypesubroutine.
//
// Failure cases:
//  error getting current vocabulary id
//  error getting latest definition execute token
//  error getting pointer to the latest definition 
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthisoto ( IS-O> )
//
// C prototype:
//  void dg_forthisoto (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- )
//                                                              
// Action:
//   The compile type of the last defined word is changed to
//     dg_forthdocompiletypedpushn.
//
// Failure cases:
//  error getting current vocabulary id
//  error getting latest definition execute token
//  error getting pointer to the latest definition 
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthisobto ( IS-OB> )
//
// C prototype:
//  void dg_forthisobto (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- )
//                                                              
// Action:
//   The compile type of the last defined word is changed to
//     dg_forthdocompiletypedpushdn.
//
// Failure cases:
//  error getting current vocabulary id
//  error getting latest definition execute token
//  error getting pointer to the latest definition 
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthispto ( IS-P> )
//
// C prototype:
//  void dg_forthispto (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the  
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- )
//                                                              
// Action:
//   The compile type of the last defined word is changed to
//     dg_forthdocompiletypedpushp.
//
// Failure cases:
//  error getting current vocabulary id
//  error getting latest definition execute token
//  error getting pointer to the latest definition 
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthiscallproc ( IS-CALL-PROC )
//
// C prototype:
//  void dg_forthiscallproc (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- )
//                                                              
// Action:
//   The compile type of the last defined word is changed to
//     dg_forthdocompiletypecdecl.
//
// Failure cases:
//  error getting current vocabulary id
//  error getting latest definition execute token
//  error getting pointer to the latest definition 
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthiscallprocretuint64 ( IS-CALL-PROC-RET-UINT64 )
//
// C prototype:
//  void dg_forthiscallprocretuint64 (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the  
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- )
//                                                              
// Action:
//   The compile type of the last defined word is changed to
//     dg_forthiscallprocretuint64.
//
// Failure cases:
//  error getting current vocabulary id
//  error getting latest definition execute token
//  error getting pointer to the latest definition 
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthiscompilecall ( IS-COMPILE-CALL )
//
// C prototype:
//  void dg_forthiscompilecall (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the  
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- )
//                                                              
// Action:
//   The compile type of the last defined word is changed to
//     dg_forthdocompiletypecall.
//
// Failure cases:
//  error getting current vocabulary id
//  error getting latest definition execute token
//  error getting pointer to the latest definition 
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthstringtonewprocword ( $>NEW-PROC-WORD )
//
// C prototype:
//  void dg_forthstringtonewprocword (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- )
//                                                              
// Action:
//   Creates a new word with compile type dg_forthdocompiletypecdecl.
//    The data offset and bufferid of this word is the current offset
//    in the current compile buffer.
//
// Failure cases:
//  error getting current vocabulary id
//  error getting latest definition execute token
//  error getting pointer to the latest definition 
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthstringtonewobword ( $>NEW-OB-WORD )
//
// C prototype:
//  void dg_forthstringtonewobword (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- )
//                                                              
// Action:
//   Creates a new word with compile type dg_forthdocompiletypedpushdn.
//    The data offset and bufferid of this word is the current offset
//    in the current compile buffer.
//
// Failure cases:
//  error getting current vocabulary id
//  error getting latest definition execute token
//  error getting pointer to the latest definition 
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthemptywordlist ( EMPTY-WORDLIST )
//
// C prototype:
//  void dg_forthemptywordlist (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( wid -- )
//                                                              
// Action:
//  Removes all the words from a word list.
//  Wordlists are stored in hierarchical lists and this action is equivalent to
//   pruning the word list element of all it's children, and the children's children,
//   etc. So if a word list is a child of this word list, the child word list and
//   all it's children are freed.
//
// Failure cases:
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthtocurrent ( >CURRENT )
//
// C prototype:
//  void dg_forthtocurrent (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the  
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//   ( oldestcurrent ... 2ndlatestcurrent -currentnewwordwordliststack- 
//     oldestcurrent ... 2ndlatestcurrent latestcurrent )
//   ( wid -- ) 
// 
// Data stack in:
//  wid                           identifier of new current new word word list  
//                              
// Action:
//  Pushes the current new word wordlist identifier to the current new word
//   wordlist identifier stack.
//  Pops word list identifier from the data stack.
//  Sets the current new word word list to this identifier.
//   (This is the word list where newly created words go.)
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthcurrentfrom ( CURRENT> )
//
// C prototype:
//   void dg_forthcurrentfrom (Bufferhandle* pBHarrayhead) 
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//   ( oldestcurrent ... 2ndlatestcurrent latestcurrent -currentnewwordwordliststack- 
//     oldestcurrent ... 2ndlatestcurrent )
//   ( -- wid )
// 
// Data stack out: 
//  wid                           identifier of the word list where newly defined
//                                  words were recently added
//                                                            
// Action:
//  Pushes the word list id of the current wordlist where newly defined words are 
//   added to the data stack.
//  Then pops the latest current new word wordlist from the current new word
//   wordlist stack and sets the current new word wordlist to this wordlist.
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthwordlistdot ( WORDLIST. )
//
// C prototype:
//   void dg_forthwordlistdot (Bufferhandle* pBHarrayhead) 
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//   ( "<delimiters>word<delimiters>morestuff" -currentinputbuffer-
//     "<delimiters>morestuff" )
//   ( wordlistid -- )
// 
// Data stack in: 
//  wordlistid                    identifier of the word list to search
//                                                            
// Action:
//  Pops the top UINT64 off the data stack and uses it as the wordlist id of the
//   wordlist to search.
//  Then parses the next wordname in the current input buffer. 
//  Then searches the wordlist for the wordname.
//  If the wordname is found, this executes the word.
//  If the wordname is not found, this pushes an error to the error stack.  
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthcreatebracketwordlistdot ( CREATE-[WORDLIST.] )
//
// C prototype:
//   void dg_forthcreatebracketwordlistdot (Bufferhandle* pBHarrayhead) 
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//   ( "<delimiters>word<delimiters>morestuff" -currentinputbuffer-
//     "<delimiters>morestuff" )
//   ( wordlistid -- )
// 
// Data stack in: 
//  wordlistid                    identifier of the word list
//                                                            
// Action:
//  Pops the top UINT64 off the data stack and uses it as the wordlist id.
//  Then parses the next wordname in the current input buffer.
//  Then creates a new immediate word in the current new word wordlist that does:
//   Searches the wordlist of wordlistid for the wordname.
//   If the wordname is found, it is executed.
//    (In compile mode, the compile time action of the parsed word is done.)
//   If the wordname is not found, this pushes an error to the error stack.
//
// Note:
//  You can use this word to make things that have name spaces, like structures,
//   easier to use. 
//
// //////////////////////////////////////////////////////////////////////////////////////