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_forthstore dg_forthnumbersign dg_forthnumbersigngreater dg_forthnumbersigns dg_forthscreate dg_forthtick dg_forthparen dg_forthstar dg_forthstarslash dg_forthstarslashmod dg_forthplus dg_forthplusloop dg_forthplusstore dg_forthcomma dg_forthminus dg_forthdot dg_forthdotquotes dg_forthslash dg_forthslashmod dg_forthzeroless dg_forthzeroequals dg_forthoneplus dg_forthoneminus dg_forthtwostore dg_forthtwostar dg_forthtwoslash dg_forthtwofetch dg_forthtwodrop dg_forthtwodup dg_forthtwoover dg_forthtwoswap dg_forthcolon dg_forthsemicolon dg_forthlessthan dg_forthlessthannumbersign dg_forthequals dg_forthgreaterthan dg_forthtobody dg_forthtoin dg_forthtonumber dg_forthtor dg_forthquestiondup dg_forthfetch dg_forthabort dg_forthabortquotes dg_forthabs dg_forthaccept dg_forthalign dg_forthaligned dg_forthallot dg_forthand dg_forthbase dg_forthbegin dg_forthbl dg_forthcstore dg_forthccomma dg_forthcfetch dg_forthcellplus dg_forthcells dg_forthchar dg_forthcharplus dg_forthchars dg_forthcmove dg_forthcmoveto dg_forthconstant dg_forthcount dg_forthcr dg_forthcreate dg_forthdecimal dg_forthdepth dg_forthdo dg_forthdoes dg_forthdrop dg_forthdup dg_forthelse dg_forthemit dg_forthenvironmentquery dg_forthevaluate dg_forthexecute dg_forthexit dg_forthfill dg_forthfind dg_forthfmslashmod dg_forthhere dg_forthhold dg_forthi dg_forthif dg_forthimmediate dg_forthinvert dg_forthj dg_forthkey dg_forthleave dg_forthliteral dg_forthloop dg_forthlshift dg_forthmstar dg_forthmax dg_forthmin dg_forthmod dg_forthmove dg_forthnegate dg_forthor dg_forthover dg_forthpostpone dg_forthquit dg_forthrfrom dg_forthrfetch dg_forthrecurse dg_forthrepeat dg_forthrot dg_forthrshift dg_forthsquotes dg_forthstod dg_forthsign dg_forthsmslashrem dg_forthsource dg_forthspace dg_forthspaces dg_forthstate dg_forthswap dg_forththen dg_forthtype dg_forthudot dg_forthulessthan dg_forthumstar dg_forthumslashmod dg_forthunloop dg_forthvariable dg_forthwhile dg_forthword dg_forthxor dg_forthleftbracket dg_forthbrackettick dg_forthbracketchar dg_forthrightbracket   dg_forthnumbertib dg_forthzeronotequals dg_forthzerogreater dg_forthdotparen dg_forthdotr dg_forthnotequals dg_forthtwotor dg_forthtworfrom dg_forthcolonnoname dg_forthquerydo dg_forthagain dg_forthcquote dg_fortherase dg_forthfalse dg_forthhex dg_forthnip dg_forthparse dg_forthlinesparse dg_forthparsebuffer dg_forthparsenames dg_forthlinesparsenames dg_forthparseword dg_forthparsewords dg_forthparseline dg_forthpick dg_forthroll dg_forthtib dg_forthto dg_forthtrue dg_forthtuck dg_forthugreaterthan dg_forthvalue dg_forthlinecomment
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthstore ( ! U64! )
//
// C prototype:
//  void dg_forthstore (Bufferhandle* pBHarrayhead)
//
// Inputs:  
//  pBHarrayhead         64 bit pointer to a Bufferhandle structure which is 
//                        used as the buffer handle for the array where the other
//                        buffer handles are kept
//
// Stack action shorthand:
//  ( u c-addr -- )
//
// Data stack inputs:
//  u                    UINT64 data value
//  c-addr               64 bit memory address pointer
//
// Action:
//  puts u into memory at address c-addr then removes u and c-addr from the data 
//   stack
//
// Forth standard: 
//  6.1.0010
//
// Handling of ambiguous conditions:
//  dg_forthstore works for unaligned addresses the same as for aligned addresses
//
// Success case:
//  ( u c-addr -- )
//
// Failure cases:
//  error getting pointer to the datastack
//   { -- } datastack does not exist
//   ( -error- dg_forthstorename )
//
//  one or both of data and address are missing
//   ( ? -- )
//   ( -error- dg_datastackunderflowerror dg_forthstorename )
//
//  address is not in process space or is read only
//   ( u c-addr -- )
//   ( -error- dg_badmemoryerror dg_forthstorename )
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthnumbersign ( # )
//
// C prototype:
//  void dg_forthnumbersign (Bufferhandle* pBHarrayhead)
//
// Inputs:  
//  pBHarrayhead       64 bit pointer to a Bufferhandle structure which is 
//                      used as the buffer handle for the array where the other
//                      buffer handles are kept
//
// Stack action shorthand:
//  ( ud1 -- ud2 )
//  ( number$1 -hold- number$2 )
//
// Datastack in:
//  ud1             unsigned double number (64 bit lo hi) to convert
//
// Datastack out:
//  ud2             unsigned double number (64 bit lo hi) = ud1/base
//
// Hold buffer in:
//  number$1        char (byte) array containing string representation of partially 
//                   converted number
//
// Hold buffer out:
//  number$2        now has next converted digit inserted at beginning
//                                                              
// Action:
//  converts the next digit of ud1 to a string by doing the following:
//   divides ud1 by value of base variable, 
//   converts remainder to an ascii digit,
//   inserts the ascii digit into the beginning of the pad buffer which
//    is used to hold the result string
//   replaces ud1 with the quotient from the divide
// 
// Forth standard:
//  6.1.0030
//
// Handling of ambiguous conditions:
//  If # is done outside of a <# #> pair, this routine still does the same
//   action as above.
//
// Diaperglu specific:
//  Base values from 2 to 201 are supported. Digit values greater than 9 
//   are converted to an ascii character using ascii value = digit value + 0x37.
//  
// Failure cases:
//  error getting pointer to the datastack
//  ud1 is missing from the data stack
//  error getting base
//  base is out of range (<2 for now, may add max base later)
//  error inserting character to pad
//
// Possible future improvement:
//  Instead of inserting to the beginning of buffer, which does a blockmove,
//   use the buffer pointer and work back from the end of a fixed sized buffer
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthnumbersigngreater ( #> )
//
// C prototype:
//  void dg_forthnumbersigngreater (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:
//  ( ud1 -- c-addr u )
//  ( number$ -hold- number$ )
//
// Datastack in:
//  ud1                          unsigned double number (64 bits lo hi) left over from 
//                                 conversion - most likely 0 0
//
// Datastack out:
//  c-addr                       pointer to the pad buffer which contains the converted 
//                                number string
//  u                            length of the converted number string which is also 
//                                the length of the pad buffer
//
// Hold buffer in:
//  number$                      char array containing string representation of  
//                                partially converted number
// Hold buffer out:
//  number$                      unchanged
//                                                              
// Action:
//  removes ud1 from the data stack and replaces it with the address and length of the 
//   converted number string
//
// Forth standard:
//  6.1.0040
//
// Failure cases:
//  error getting length of the datastack
//  u1 is missing from the datastack
//  error growing the data stack
//  error getting pointer to the datastack
//  error get point to the pad buffer
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthnumbersigns ( #S )
//
// C prototype:
//  void dg_forthnumbersigns (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:
//  ( ud1 -- 0 0 )
//  ( number$1 -hold- number$2 )
//
// Datastack in:
//  ud1             unsigned double number (64 bits lo hi) to convert
//
// Datastack out:
//  0 0             double number 0 (64 bit)
//
// Hold buffer in:
//  number$1        char array containing string representation of partially 
//                   converted number
//
// Hold buffer out:
//  number$2        now has remaining converted digits inserted at beginning
//                                                              
// Action:
//  converts the remaining digits of ud1 according to the algorithm of 
//   # until ud1 is 0
//
// Forth standard:
//  6.1.0050
//
// Handling of ambiguous conditions:
//  If #S is done outside of a <# #> pair, this routine still does the same
//   action as above.
// 
// Failure cases:
//  error getting pointer to the datastack
//  ud1 is missing from the data stack
//  error doing dg_forthnumbersign
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthscreate ( $CREATE )
//
// C prototype:
//  void dg_forthscreate (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:
//  ( c-addr u -- )
//  
// Data stack in:
//  c-addr                        pointer to word name
//  u                             length of word name in characters (bytes)           
//                                                            
// Action:
//  Pops the address and length of the name to use for the new word off of the data 
//   stack.
//  Then creates a new word in the current new word wordlist using the name that: 
//   In execute mode pushes the address of a variable onto the data stack. 
//   In compile mode compiles code that pushes the address of a variable onto the 
//    data stack.
//  The address of the variable used is the address of the next unused byte in the 
//   current data space buffer.
//
// Forth standard:
//  None. But its the same as CREATE except this word does not parse for the name.
//
// Note
//  This routine will calculate the address of the variable from the variable's buffer
//   id and offset at the time the code is called.
//  If the buffer the variable is in moves, the address will become invalid. For this
//   reason, to be compatible with the old Forth commands, I suggest making the data 
//   space buffer of fixed size so it will not move if you are using  ALLOT , C, and 
//   VARIABLE and do not want to have to worry about when your pointers become obsolete.
//  Either that or be done using the pointer before the next call to something that may
//   cause the buffer to move such as doing ALLOT , C, or VARIABLE. If you use the
//   pointer right away and it's not pushing something to the new variable buffer then
//   you don't have to worry about it.
//
//  When Diaperglu first starts, the size of the current new variable buffer is of 
//   fixed size so you do not have to worry about it moving. This is for compatibility
//   with older Forth programs which may keep the pointers around for a long time. 
//   Unfortunately I also made the current new variable buffer the same as
//   the current compile buffer which means you will likely run out of memory if you 
//   have a large program. I recommend changing them. PCURRENTCOMPILEBUFFER points
//   to the current compile buffer and PCURRENTNEWVARIABLEBUFFER points to the
//   current data space buffer.
//
//  If you change PCURRENTNEWVARIABLEBUFFER to point to a buffer than can grow, 
//   then you have to worry about the life of the pointers from variables you CREATE 
//   in the new buffer.
// 
//  P.S. if you don't like how , and C, allocate memory in the data space area instead 
//   of the code space area, take this up with the Forth standards people :-). 
//   Either that or set the current compile buffer to be the same as the current 
//   variable buffer. This way code and variable memory allocations use the same 
//   pointer in the same buffer.
//  
//  For example: ( using CREATE to make the pointer for this example ):
//
//   ( Diaperglu first starts )
//   CREATE PCOWS
//   PCOWS         ( address of PCOWS variable is on the data stack )
//   4 ALLOT       ( PCOWS address on the data stack is still valid because the default 
//                    new variable buffer was initialized with growby = maxsize )
//
//
//   100 1000 dg_newbuffer CONSTANT MYBUF
//   MYBUF PCURRENTNEWVARIABLEBUFFER !
//   CREATE PCATS
//   PCATS         ( address of PCATS variable is on the data stack )
//   100 ALLOT     ( base address of MYBUF has not moved yet because initial allocation )
//                 (  = growby )
//   1 ALLOT       ( OS may have moved base address of MYBUF )
//                 ( address of PCATS variable on the data stack is now invalid! )
//                 ( address of PCOWS is still valid because it is in the other buffer )
// 
//   DROP          ( getting rid of bad PCATS pointer )
//   PCATS         ( Diaperglu calculates the new address of PCATS, this one is valid )
//                 (  for now )
//                 (  quick! use the pointer before it becomes invalid! )
// 
//   100 ALLOT     ( buffer may have moved again, new address of PCATS on data stack is )
//                 (  invalid )
//
// 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_forthtick ( ' )
//
// C prototype:
//  void dg_forthtick (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")
//  ( -- xt )
//            
// Current input buffer at current offset in:
//  "<spaces>word<spaces>morestuff"                     
//
// Current input buffer at current offset out:
//  "<spaces>morestuff"
//
// Data stack out:
//  xt                           execution token which is the unique identifier for 
//                                the word  
//                                                              
// Action:
//  Current offset pointer for the current input buffer is moved from it's current 
//   position to the character after the end of the next word or to the end of the 
//   buffer if no word is found.
//  If the word is found, the execution token is looked up in the current search 
//   order and pushed to the data stack.
//  If the execution token for the word is not found ENDOFWORDLIST ( -1 ) 
//   is returned instead.
//
// Forth standard:
//  6.1.0070
//
// Handling of ambiguous conditions:
//  If the execution token for the word is not found, ENDOFWORDLIST ( -1 ) 
//   is returned instead.  
//
// Failure cases:
//  error getting the current input buffer id
//  error getting the pointer to the current input buffer
//  end of the input buffer reached before finding a word
//  error searching for the definition with the word as it's name
//  errpr pushing the definition's execution token to the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthparen ( ( )
//
// C prototype:
//  void dg_forthparen (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:
//  ( "somestuff<right paren>morestuff" -currentinputbuffer- 
//     "morestuff" )
//        
// Current input buffer at current offset in:
//  "somestuff<right paren>morestuff"                    
//
// Current input buffer at current offset out:
//  "morestuff"
//                                                            
// Action:
//  current offset pointer for the current input buffer is moved from it's current 
//   position to the character after the end of the next right parenthesis 
//   character ')' or to the end of the buffer (which ever
//   comes first) if no right parenthesis is found
//
// Forth standard:
//  6.1.0080 with 11.6.1.0080
//
// Failure cases:
//  error getting current input buffer id
//  error getting pointer to current input buffer
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthstar ( * )
//
// C prototype:
//  void dg_forthstar (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:
//  ( n1|u1 n2|u2 -- n3|u3 )
//           
// Data stack in:
//  n1 and n2 or u1 and u2        two numbers (64 bit) to be multiplied,
//                                 note: the calculation for two signed integers is the 
//                                 same as for two unsigned numbers
// 
// Data stack out:
//  n3 or u3                      the result of the multiplication
//                                                              
// Action:
//  multiplies n1 by n2, removes n1 and n2 from the data stack and replaces them with n3
//
// Forth standard:
//  6.1.0090
//
// Failure cases:
//  error getting pointer to the data stack
//  one or both of n1 and n2 missing from the datastack
//  
// //////////////////////////////////////////////////////////////////////////////////////      
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthstarslash ( */ )
//
// C prototype:
//  void dg_forthstarslash (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:
//  ( n1 n2 n3 -- n4 )
//
// Data stack in:
//  n1, n2, and n3               three signed integers for calculation
// 
// Data stack out:
//  n4                           the result of the calculation with symmetric divide
//                                                              
// Action:
//  n1 is scaled by n2/n3. That is, n4 = (n1 * n2)/n3 using symmetric divide
//
// Forth standard:
//  6.1.0100
//
// Handling of ambiguous conditions:
//  In the event n3 is 0 or result is greater than the largest positive INT64,
//   the largest possible positive INT64 is returned which is 0x7fffffffffffffff.
//  In the event the result is less than the largest negative INT64,
//   the largest possible negative INT64 is returned which is 0x8000000000000000.
//
// Failure cases:
//  error getting pointer to the data stack
//  n1, n2, or n3 is missing from the datastack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthstarslashmod ( */MOD )
//
// C prototype:
//  void dg_forthstarslashmod (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:
//  ( n1 n2 n3 -- remainder n4 )
//
// Data stack in:
//  n1, n2, and n3               three numbers for calculation
// 
// Data stack out:
//  remainder n4                 the results of the calculation
//                                                              
// Action:
//  n1 is scaled by n2/n3. That is, n4 = (n1 * n2)/n3
//  the remainder is the remainder from the scaling operation
//
// Forth standard:
//  6.1.0110
//
// Handling of ambiguous conditions:
//  In the event n3 is 0 or result is greater than the largest positive INT64,
//   n4 = the largest possible positive INT64 which is 0x7fffffffffffffff.
//  In the event the result is less than the largest negative INT64,
//   n4 = the largest possible negative INT64 which is 0x8000000000000000.
//
// Failure cases:
//  error getting pointer to the data stack
//  n1, n2, or n3 is missing from the datastack
//
// Note: if n3 = 0, or if result wont fit into n4, remainder and n4 are set to max 
//  UINT64 values
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthplus ( + )
//
// C prototype:
//  void dg_forthplus (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:
//  ( n1|u1 n2|u2 -- n3|u3 )
//
// Data stack in:
//  n1 and n2 or u1 and u2        the two numbers to add
// 
// Data stack out:
//  n3 or u3                      the result of the calculation
//                                                              
// Action:
//  n3 = n1 + n2
//
// Note:
//  the calculation for two signed numbers is the same as for two unsigned numbers
//   and overflow is not checked
//
// Forth standard:
//  6.1.0120
//
// Failure cases:
//  error getting pointer to the data stack
//  n1 or n2 is missing from the datastack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthplusstore ( +! )
//
// C prototype:
//  void dg_forthplusstore (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:
//  ( n|u a-addr -- )
//
// Data stack in:
//  n or u                        the 64 bit number to add to the number at the 
//                                 address
//  addr                          contains the target address for the add
// 
// Action:
//  the contents of address = the contents of adress + n1
//
// Note:                          
//  the calculation for two signed numbers is the same as for two unsigned numbers
//   and overflow is not checked
//
// Forth standard:
//  6.1.0130
//
// Handling of ambiguous conditions:
//  dg_forthplusstore works for unaligned address the same as for aligned addresses
//                                                              
// Failure cases:
//  error getting pointer to the data stack
//  data stack underflow
//  address is not in processes address space or is read only
//  
// //////////////////////////////////////////////////////////////////////////////////////
UINT64 dg_checkplusloopdone (Bufferhandle* pBHarrayhead)
//                             ( index limit -r- | index limit )
//                             ( loopstep -- )
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthplusloop ( +LOOP )
//
// C prototype:
//  void dg_forthplusloop (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:
//  ( do-sys -- )
//
//  ( compiles code that does: ) 
//    ( loopstep -- ) 
//    ( loop-sys1 -controlflowstack- ) if loop ends
//    ( loop-sys1 -controlflowstack- loop-sys1' ) if loop does not end
// 
// Data stack in:
//  do-sys                        offset to loop back to from DO 
//                                                           
// Action:
//  compiles code to check loop done condition and branch if it isn't
//   compiled code calls dg_checkloopdone which sees if the loop is done.
//     If the loopstep is positive, the loop is done if 0 < index - limit <= loopstep
//     If the loopstep is negative, the loop is done if loopstep <= index - limit < 0 
//   If the loop is done, the limit and index are dropped from the rstack. 
//   If the loop is not done, the index is incremented and then the compiled 
//     code branches back to the DO offset
//
// Note:
//   There is some dispute in the Forth community on how to handle negative loop
//     steps. Since the documentation in the standard says the loop exits when
//     the loop crosses the boundary of the limit - 1, some Forths interpret that
//     literally and will do an extra iteration when the loopstep is -1. This Forth
//     interprets it as 'if you cross the boundary of being within 1 of the limit
//     based on the direction of approach, the loop is done'.
//
// Forth standard:
//  6.1.0140
//
// Handling of ambiguous conditions:
//  If the loop control parameters are not available, dg_rstackunderflowerror is 
//   pushed to the error stack and the loop exits.
//
// Failure cases:
//  error getting current compile buffer id
//  error popping beginoffset from the data stack
//  error growing the current compile buffer
//  error getting the pointer to the current compile buffer
//  error getting the pointer to the leave stack
//  error resolving the leave branch
//  error growing the current compile buffer a second time
//  error getting the pointer to the current compile buffer the second time
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthcomma ( , U64, )
//
// C prototype:
//  void dg_forthcomma (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:
//  ( n1 -- )
//  ( -currentdataspacebuffer- n1 )
//           
// Data stack in:
//  n1                            integer (64 bit) to push onto the end of the current 
//                                 compile buffer
//                                                              
// Action:
//  puts n1 onto end of the current data space buffer
//
// Forth standard:
//  6.1.0150
//
// Handling of ambiguous conditions:
//  If the 'data-space' pointer is not aligned, dg_forthcomma still works the same as 
//   the aligned case and exactly 64 bits of space are used.
//
// Failure cases:
//  error getting pointer to the data stack
//  n1 missing from data stack
//  error getting current data space buffer id
//  error pushing to the current data space buffer
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthminus ( - )
//
// C prototype:
//  void dg_forthminus(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:
//  ( n1 n2 -- n1-n2 )
//
// Data stack in:
//  n1 and n2                     the two integers (64 bit) to subtract
// 
// Data stack out:
//  n3                            the result of the calculation
//                                                             
// Action:
//  n3 = n1 - n2
//
// Forth standard:
//  6.1.0160
//
// Note:                          
//  the calculation for two signed integers is the same as for two unsigned integers
//  this calculation does not check for overflow
// 
// Failure cases:
//  error getting pointer to the data stack
//  n1 or n2 is missing from the datastack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthdot ( . )
//
// C prototype:
//  void dg_forthdot (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:
//  ( n -- )
// 
// Data stack in:
//  n                             signed integer to convert and display
//                                                              
// Action:
//  converts n to a character string representation and displays in the Forth free 
//   field format
//
// Forth standard:
//  6.1.0180
//
// Failure cases:
//  error calling <#
//  error calling DUP
//  error calling ABS
//  error calline #S
//  error calling SIGN
//  error calling #>
//  error calling TYPE
//  error calling SPACE
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthdotquotes ( ." )
//
// C prototype:
//  void dg_forthdotquotes (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:
//  ( "<delimiter>stuff<double quote>morestuff" 
//     -currentinputbuffer- "morestuff" )
// 
// Current input buffer at current offset in:
//  "stuff<double quote>morestuff"
//
// Current input buffer at current offset out:
//   "morestuff"
//
// Forth standard:
//  6.1.0190 (specifies compile state behavior only)
//                                                         
// Action:
//  (The character after ." is already skipped and not included.)
//  Moves the current offset pointer of the current input buffer to: 
//   Skip all characters until the character after the next occurence of ", the
//    next occurence of a line terminator delimiter, or the end of the buffer, 
//    whichever comes first.
//   The skipped characters up to the character before the next " or line 
//    terminator delimiter is the target string.
//  If the interpreter is in state execute, the target string is sent to stdout;
//   otherwise this routine compiles code to send a copy of the target string to 
//   stdout. 
//
//  Examples:
//   ." potato chip"
//    Sends the string 'potato chip' to stdout. (Quotes are not sent.)
//
//   : test ." potato chip" ;
//    Compiles a word called 'test' which when later executed will send the string 
//     'potato chip' to stdout. (Quotes are not sent.)
//
//  Note:
//   There is operating system overhead involved in sending data to stdout. 
//   It is likely faster to send one large string to stdout instead of many smaller 
//    ones.
//   You can use S" and $"$ to build and join smaller strings on the 
//    string stack and then use .$ to send the final string to stdout.
//   If you forget your ending <double quotes>, and you have more ." or 
//    $" later in your script, you will likely see a word not found error for 
//    the first word of that next ." or $" string.
//   If you forget your ending <double quotes> and you don't have any more
//    <double quotes> in your script, the rest of your script will be skipped.
// 
// Failure cases:
//  error calling compiled S" code
//  error getting current compile buffer id
//  error growing the current compile buffer
//  error getting the pointer to the current compile buffer
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthslash ( / )
//
// C prototype:
//  void dg_forthslash (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:
//  ( n1 n2 -- n1/n2 )
//              
// Data stack in:
//  n1 and n2                     the two signed integers (64 bit) to divide
// 
// Data stack out:
//  n3                            the result of the calculation using symmetric division
//                                      
// Action:
//  n3 = n1 / n2                  
//
// Handling of ambiguous conditions:
//  If n2 is 0 and n1 is positive, then n3 = most positive INT64 (0x7FFFFFFFFFFFFFFF)
//  If n2 is 0 and n1 is negative, then n3 = most negative INT64 (0x8000000000000000)
//  Uses symmetric division for oppositely signed values
//  
// Forth standard:
//  6.1.0230
//
// Tested cases: 
//  -5/2 = -2
//  -65536/1 = -65536
//  65535/-1 = -65535
//
// Failure cases:
//  error getting pointer to the data stack
//  n1 or n2 is missing from the datastack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthslashmod ( /MOD )
//
// C prototype:
//  void dg_forthslashmod (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:
//  ( n1 n2 -- remainder quotient )
//
// Data stack in:
//  n1, n2                        two signed integers for calculation
// 
// Data stack out:
//  remainder n3                  the results of the calculation using symmetric divide
//                                                              
// Action:
//  n1 is divided by n3. using symmetric division 
//  the remainder is the remainder from the divide
//
// Forth standard:
//  6.1.0240
//
// Handling of ambiguous conditions:
//  If n2 is 0 and n1 is positive, then n3 = remainder = most positive INT64 
//   (0x7FFFFFFFFFFFFFFF)
//  If n2 is 0 and n1 is negative, then n3 = remainder = most negative INT64 
//   (0x8000000000000000)
//  Uses symmetric division for oppositely signed values
//
// Failure cases:
//  error getting pointer to the data stack
//  n1, n2 is missing from the datastack
//  
// //////////////////////////////////////////////////////////////////////////////////////     
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthzeroless ( 0< )
//
// C prototype:
//  void dg_forthzeroless (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:
//  ( n1 -- flag )
//            
// Data stack in:
//  n1                            signed integer (64 bit) to check for less than 0
// 
// Data stack out:
//  flag                          TRUE (-1) if less than 0, 
//                                FALSE (0) if greater or equal to 0
//
// Action:
//  compare n1 with 0 and replace n1 with forth true if n1 < 0 or forth false 
//   flag if n1 >= 0
//
// Forth standard:
//  6.1.0250
//
// Failure cases:
//  error getting pointer to the data stack
//  n1 is missing from the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////     
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthzeroequals ( 0= )
//
// C prototype:
//  void dg_forthzeroequals (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:
//  ( n1 -- flag )
//            
// Data stack in:
//  n1                            signed integer (64 bit) to check for less than 0
// 
// Data stack out:
//  flag                          TRUE (-1) if equal to 0, FALSE (0) if not equal to 0
//
// Forth standard:
//  6.1.0270
//
// Action:
//  compare n1 with 0 and replace n1 with dg_forth true if n1 is 0 or forth false 
//   flag if n1 is not 0
//
// Failure cases:
//  error getting pointer to the data stack
//  n1 is missing from the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////   
// ////////////////////////////////////////////////////////////////////////////////////// 
//
// dg_forthoneplus ( 1+ )
//
// C prototype:
//  void dg_forthoneplus (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:
//  ( n1 -- n1+1 )
//            
// Data stack in:
//  n1                            integer (32bit) to increment
// 
// Data stack out:
//  n2                            incremented number
//
// Action:
//  n2 = n1+1
//
// Forth standard:
//  6.1.0290
//                                                              
// Note:
//  Calculation is same for both signed and unsigned integers
//  This routine does not check for overflow
//
// Failure cases:
//  error getting pointer to the data stack
//  n1 is missing from the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////       
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthoneminus ( 1- )
//
// C prototype:
//  void dg_forthoneminus (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:
//  ( n1 -- n1-1 )
//            
// Data stack in:
//  n1                            integer (64 bit) to decrement
// 
// Data stack out:
//  n2                            decremented number
//                                                          
// Action:
//  n2 = n1-1
//
// Forth standard:
//  6.1.0300
//
// Note:
//  Calculation is same for both signed and unsigned integer
//  This routine does not check for overflow
//
// Failure cases:
//  error getting pointer to the data stack
//  n1 is missing from the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////      
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthtwostore ( 2! U128! )
//
// C prototype:
//  void dg_forthtwostore (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:
//  ( n1 n2 addr -- )
// 
// Datastack in:
//  n1 and n2                     64 bit integers
//  addr                          memory location in process space to put the integers
//                                                          
// Action:
//  Puts n1 and n2 into memory at address addr.
//  n1, n2 and address are removed from the datastack
//  n2 goes at address, n1 goes at address + cell size which is 4 in this 
//   implementation
//
// Forth standard:
//  6.1.0310
//
// Handling of ambiguous conditions:
//  dg_forthtwostore works for unaligned address the same as for aligned addresses
//
// Failure cases:
//  error getting pointer to the datastack
//  n1, n2, or address is missing
//  addresses are not in process space or are read only
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthtwostar ( 2* )
//
// C prototype:
//  void dg_forthtwostar(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:
//  ( n1 -- n1*2)
//            
// Data stack in:
//  n1                            integer to multiply by 2
// 
// Data stack out:
//  n2                            integer multiplied by 2
//
// Note:
//  for both signed and unsigned integers, the calculation is the same
//  overflow is not checked
//                                                         
// Action:
//  n2 = n1*2
//
// Forth standard:
//  6.1.0320
//
// Failure cases:
//  error getting pointer to the data stack
//  n1 is missing from the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthtwoslash ( 2/ )
//
// C prototype:
//  void dg_forthtwoslash (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:
//  ( n1 -- n1/2 )
//           
// Data stack in:
//  n1                            signed integer to divide by 2
// 
// Data stack out:
//  n2                            signed integer divided by 2
//                                                              
// Action:
//  n2 = n1/2
//
// Forth standard:
//  6.1.0330
//
// Note:
//  this routine is implemented with an arithmetic shift right
// 
// Failure cases:
//  error getting pointer to the data stack
//  n1 is missing from the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////     
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthtwofetch ( 2@ U128@ )
//
// C prototype:
//  void dg_forthtwofetch (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:
//  ( addr -- n1 n2 )
// 
// Datastack in:
//  addr                          memory location in process space to get the integers
//
// Datastack out:
//  n1 and n2                     integers from address (64 bit)
//                                                              
// Action:
//  gets n1 and n2 from address,  address is removed from the datastack and replaced 
//   with n1 n2. n2 is from address, n1 is from address + cell size which is 8 in this 
//   implementation
//
// Forth standard:
//  6.1.0350
//
// Handling of ambiguous conditions:
//  dg_forthtwofetch works for unaligned address the same as for aligned addresses
//
// Failure cases:
//  error getting pointer to the datastack
//  address is missing from data stack
//  error growing the data stack
//  addresses are not in process space 
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthtwodrop ( 2DROP )
//
// C prototype:
//  void dg_forthtwodrop (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:
//  ( n1 n2 -- )
//
// Datastack in:
//  n1 n2                         integers (64 bit) to remove from data stack
//                                                           
// Action:
//  removes n1 and n2 from the data stack
//
// Forth standard:
//  6.1.0370
// 
// Failure cases:
//  error getting pointer to the datastack
//  n1 or n2 is missing from the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////       
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthtwodup ( 2DUP )
//
// C prototype:
//  void dg_forthtwodup (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:
//  ( n1 n2 -- n1 n2 n1 n2 )
//  
// Datastack in:
//  n1 n2                         integers (64 bit) to duplicate
//
// Datastack out:
//  n1 n2 n1 n2                   n1 and n2 are duplicated     
//                                                              
// Action:
//  pushes copies of n1 and n2 to the data stack
//
// Forth standard:
//  6.1.0380
//
// Failure cases:
//  error getting pointer to the datastack
//  n1 or n2 is missing from the data stack
//  error growing the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthtwoover ( 2OVER )
//
// C prototype:
//  void dg_forthtwoover (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:
//  ( n1 n2 n3 n4 -- n1 n2 n3 n4 n1 n2 )
// 
// Datastack in:
//  n1 n2 n3 n4                   top four integers (64 bit) on the data stack are used 
//                                 for this
//
// Datastack out:
//  n1 n2 n3 n4 n1 n2             n1 and n2 are pushed to the stack over n3 and n4
//
// Action:
//  pushes copies of n1 and n2 to the data stack 'over' n3 and n4
//
// Forth standard:
//  6.1.0400
//                                              
// Failure cases:
//  error getting pointer to the datastack
//  n1 n2 n3 or n4 is missing from the data stack
//  error growing the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthtwoswap ( 2SWAP )
//
// C prototype:
//  void dg_forthtwoswap (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:
//  ( n1 n2 n3 n4 -- n3 n4 n1 n2 )
// 
// Datastack in:
//  n1 n2 n3 n4                   top four integers (64 bit) on the data stack are used 
//                                 for this operation
//
// Datastack out:
//  n3 n4 n1 n2                   n1 and n2 are swapped with n3 and n4
//
// Action:
//  swaps n3 n4 with n1 n2 on data stack
//
// Forth standard:
//  6.1.0430
//                                                            
// Failure cases:
//  error getting pointer to the datastack
//  n1 n2 n3 or n4 is missing from the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////      
// ////////////////////////////////////////////////////////////////////////////////////// 
//
// dg_forthcolon ( : )
//
// C prototype:
//  void dg_forthcolon (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>name<delimiters>morestuff" -currentinputbuffer-
//      "<delimiters>morestuff" )
//  ( -- executiontoken colonsys )
//
// Current input buffer in:
//  "<delimiters>name<delimiters>morestuff"  
//                                after removing leading delimiters, all characters 
//                                 up to the next delimiter is taken as the word
//                                 ('name') to be processed
//
// Current input buffer out:      
//  "<delimiters>morestuff" the current offset pointer for the current 
//                                 input buffer is moved to the delimiter after the  
//                                 word ('name') or to the end of the buffer if no word 
//                                 is found
//
// Action:
//  gets the current input buffer, 
//  then gets the next word from the input buffer
//  then creates a new dictionary definition header with the word as the name of the 
//   definition.
//   the dictionary definition header has a compile type of 'execute or compile code 
//    to execute' and the data buffer id and offset points to the end of the current 
//    compile buffer
//  then sets the state of the script processor to compile
//  then compiles code to stack the current error count
//  then clears a flag so that when ; is executed it will know if a call to a safe 
//   subroutine was compiled.
//
// Forth standard:
//  6.1.0450
//                                                           
// NOTE: with the name parsing algorithm this routine uses, the name has to be in the 
//  same input buffer as the :
//  so if you are entering lines from the console, it has to be on the same line as :
//  but if you are loading from a file, it can be on a later line in the file
//
//  Note: The default safe behavior errs on the side of caution. Only compiling words
//    and words that could be used to push to the current compile buffer need to be 
//    marked as safe. Safe subroutine calls execute slower but can handle the case 
//    where the buffer they are called from relocates while they are executing.
//
// Failure cases:
//  error getting current interpret buffer id
//  error pushing current interpret buffer id to the data stack
//  error getting next word from current interpret buffer to string stack
//  error creating a new subroutine threaded definition
//  error setting the script processing state to compile
//  error trying to push colonsys to the data stack
//  
// ////////////////////////////////////////////////////////////////////////////////////// 
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthsemicolon ( ; )
//
// C prototype:
//  void dg_forthsemicolon (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 colonsys | colonnonamesys -- )
//                                                             
// Action:
//  compiles return from subroutine at the end of the current compile buffer
//  sets the script processing state to execute
//  checks to make sure the colonsys from the : or the colonnonamesys from :NONAME is 
//   there
//  if colonsys is there then
//   links the executiontoken's word into the current new word wordlist'
//   removes colonsys and executetoken from the data stack
//  else
//   removes colonnonamesys from the data stack and leaves executetoken alone
//  endif
//  if a safe call to a subroutine was compiled since the last colon, the last
//    colon definition is marked as safe also.
//
// Forth standard:
//  6.1.0460
//
//  Note: The default safe behavior errs on the side of caution. Only compiling words
//    and words that could be used to push to the current compile buffer need to be 
//    marked as safe. Safe subroutine calls execute slower but can handle the case 
//    where the buffer they are called from relocates while they are executing.
//
// Failure cases:
//  error compiling return
//  error setting script processing state to execute
//  error getting pointer to the data stack
//  data stack underflow
//  data stack not balanced from : probably due to an unresolved branch
//  error getting current compile word list id
//  error linking definition to the current compile word list
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthlessthan ( < )
//
// C prototype:
//  void dg_forthlessthan (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:
//  ( n1 n2 -- flag )
// 
// Datastack in:
//  n1 n2                         signed integers (64 bit) to compare
//
// Datastack out:
//  flag                          n1 and n2 are replaced with a flag based on the 
//                                 comparison
//
// Action:
//  n1 and n2 are removed from the stack and a flag is push on
//  if n1 is less than n2, the flag is TRUE (-1) otherwise it is FALSE (0)
//
// Forth standard:
//  6.1.0480
//                                                             
// Failure cases:
//  error getting pointer to the datastack
//  n1 or n2 is missing from the data stack
//  
////////////////////////////////////////////////////////////////////////////////////////     
////////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthlessthannumbersign ( <# )
//
// C prototype:
//  void dg_forthlessthannumbersign (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:
//  ( -- )
//  ( number$ -hold- )
// 
// Hold buffer in:
//  number$                       if a numberstring is in the hold buffer, it is 
//                                 removed by this operation
//
// Action:
//  empties pad buffer
//
// Forth standard:
//  6.1.0490
//                                                            
// Failure cases:
//  error getting pointer to the pad buffer
//  
////////////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthequals ( = )
//
// C prototype:
//  void dg_forthequals (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:
//  ( n1 n2 -- flag )
// 
// Data stack in:
//  n1 n2                         integers (64 bit) to compare
//
// Data stack out:
//  flag                          n1 and n2 are replaced with a flag
//
// Action:
//  n1 and n2 are replaced with a flag
//  flag is TRUE (-1) if n1 and n2 are equal, FALSE (0) otherwise
//
// Forth standard:
//  6.1.0530
//                                                              
// Failure cases:
//  error getting pointer to the data stack
//  n1 or n2 missing from datastack
//  
////////////////////////////////////////////////////////////////////////////////////////       
////////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthgreaterthan ( > )
//
// C prototype:
//  void dg_forthgreaterthan (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:
//  ( n1 n2 -- flag )
// 
// Data stack in:
//  n1 n2                         signed integers (64 bit) to compare
//
// Data stack out:
//  flag                          n1 and n2 are replaced with a flag
//
// Action:
//  n1 and n2 are replaced with a flag
//  flag is TRUE (-1) if n1 is greater than n2, FALSE (0) otherwise
//
// Forth standard:
//  6.1.0540
//                                                           
// Failure cases:
//  error getting pointer to the data stack
//  n1 or n2 missing from datastack
//  
//////////////////////////////////////////////////////////////////////////////////////// 
////////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthtobody ( >BODY )
//
// C prototype:
//  void dg_forthtobody (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                            a word's execution token which is a unique identifier 
//                                 for that word                
//
// Data stack out:
//  addr                          address of the execution token's data field 
//
// Action:
//  converts execution token to it's data field address
//
// Forth standard:
//  6.1.0550
//
// Handling of ambiguous conditions:
//  If the execution token is for a word not defined using CREATE, this routine will 
//   incorrectly try to use the word's data offset and bufferid and try to convert it 
//   to an address.
//   In the likely event the bufferid is for a non-existant buffer, or the offset 
//   beyond the end of an existing buffer, this routine will push an error to the 
//   error stack indicating it could not calculate the address for the buffer offset.
//                                                            
// NOTE: doesn't work for constants or other words where data offset and bufferid 
//  isn't a pointer to a buffer offset. It will work for other words not defined 
//  using CREATE where the data offset and bufferid does point to a buffer offset.
//
// Warning!: The address returned is only valid until the next time the buffer this 
//   address is in moves.
//   Buffers may move when you add to their length. 
//    When you make a new VARIABLE or use , C, the current variable buffer may move. 
//    When you compile new code with : the current compile buffer may move. 
//    Buffers may also move when you push to them or grow them unless they are of 
//     fixed size which locks them down.
//     A buffer created using NEWBUFFER with its growby equal to its maxsize will 
//      be of fixed size and locked down.
//
// Failure cases:
//  error getting the current input buffer id
//  error getting pointer to the current input buffer
//  error growing the data stack
//  error getting pointer to the data stack
//  
//////////////////////////////////////////////////////////////////////////////////////// 
////////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthtoin ( >IN )
//
// C prototype:
//  void dg_forthtoin (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:
//  (  -- addr )
//
// Data stack out:
//  addr                          address of current input buffer's current offset 
//                                 variable
//
// Action:
//  Puts the address of the current input buffer's current offset variable onto the 
//   data stack.
//  This pointer to the current offset is part of the buffer handle, not the buffer 
//   and will remain valid until the array holding the buffer handles moves. 
//   The buffer handle array can move when new buffers are allocated using 
//   dg_forthnewbuffer ( NEWBUFFER ).
//  Freeing a target buffer will not invalidate a pointer to it's current offset 
//   variable.
//
// Forth standard:
//  6.1.0560
//
// Failure cases:
//  error getting the current input buffer id
//  error getting pointer to the current input buffer
//  error growing the data stack
//  error getting pointer to the data stack
//  
////////////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthtonumber ( >NUMBER )
//
// C prototype:
//  void dg_forthtonumber (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:
//  ( ud1 c-addr1 u1 -- ud2 c-addr2 u2)
//
// Data stack in:
//  ud1                           initial unsigned integer (64 bit lo hi) before 
//                                 conversion
//  c-addr1                       address of character string to convert to an unsigned 
//                                 integer
//  u1                            length of character string (64 bit)
//  
// Data stack out:
//  ud2                           result of conversion (64 bit lo hi)
//  c-addr2                       address of first unconverted character or c-addr1 + u1 
//                                 if all characters were converted
//  u2                            number of unconverted characters (64 bit)
//                                                              
// Action:
//  Converts the characters at c-addr1 for u1 to a 64 bit integer using the current BASE 
//   and appends the converted number to the end of ud1.
//  So if BASE is decimal, ud1 = 76, and the string at c-addr1 is "32", 
//   ud2 will be 7632.
//
// Forth standard:
//  6.1.0570
//
// Handling of ambiguous cases:
//  If the conversion overflows, conversion continues resulting in an incorrect result.
//  This overflow will not crash the system.
//
// Failure cases:
//  error getting pointer to the data stack
//  not enough elements on the data stack for this operation
//  error getting base
//  base out of valid range (<2 for now is invalid)
//  any address in the character string not in process space
//  conversion overflows (this failure goes unchecked but won't crash the system)
//  base is large enough to have digits in range of the lower case characters 
//   (goes unchecked for now but won't crash the system)
//  
////////////////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthtor ( >R )
//
// C prototype:
//  void dg_forthtor (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:
//  ( x1 -- )
//  ( -r- x1 )
//
// Data stack in:
//  x1                            integer (64 bit) to move to the rstack
//  
// R stack out:
//  x1                            integer (64 bit) moved from data stack
//
// Action:
//  pops an integer (64 bit) from the data stack and pushes it onto the rstack
//
// Forth standard:
//  6.1.0580
//                                                              
// Failure cases:
//  error popping the data stack
//  error pushing the return stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthquestiondup ( ?DUP )
//
// C prototype:
//  void dg_forthquestiondup (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:
//  ( n1 -- n1 ) if n1 = 0 or 
//  ( n1 -- n1 n1 ) if n1 != 0
//
// Data stack in:
//  n1                            integer (64 bit) to check
//  
// Data stack out:
//  x1  or x1 x1                  x1 if x1 is 0, x1 x1 if x1 isn't 0
//
// Action:
//  checks the top integer on the data stack to see if its 0, if it isn't a copy of 
//   it is pushed to the top of the data stack
//
// Forth standard:
//  6.1.0630
//                                                            
// Failure cases:
//  error popping the data stack
//  error pushing the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////   
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthfetch ( @ U64@ )
//
// C prototype:
//  void dg_forthfetch (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:
//  ( addr -- x )
//
// Data stack in:
//  addr                          pointer to data to get
//  
// Data stack out:
//  x                             this integer (64 bit) is fetched from the address  
//                                 and replaces the address on the data stack
//
// Action:
//  gets the integer at address and replaces address on the datastack with the 
//   integer
//
// Forth standard:
//  6.1.0650                                                            
//
// Handling of ambiguous conditions:
//  dg_forthfetch works for unaligned address the same as for aligned addresses
//
// Failure cases:
//  error getting pointer to the datastack
//  data stack is missing address
//  address isn't in process' space
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthabort ( ABORT )
//
// C prototype:
//  void dg_forthabort (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:
//  ( nx ... n2 n1 n0 -- )
//  ( mx ... m2 m1 m0 -r- )
//                                                              
// Action:
//  empties data stack and then does QUIT. QUIT empties the rstack, removes all nested 
//   routines from the return stack and does NOT return to ABORT
//
// Forth standard:
//  6.1.0670
//
// NOTE: calling this routine before freeing any temporary buffers you have allocated 
//  will leak memory. however, when the process terminates, all buffers are 
//  automatically freed for you
//
// Failure cases:
//  error clearing the datastack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthabortquotes ( ABORT" )
//
// C prototype:
//  void dg_forthabortquotes (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:
//  ( flag -- ) if flag = FALSE
//  ( nx ... n2 n1 n0 flag -- ) if flag = TRUE
//  ( mx ... m2 m1 m0 -r- ) if flag = TRUE
//                                                      
// Action:
//  Skips characters in the current input buffer to the character after the next
//   occurrence of a " character, the next line terminator delimiter, or the end
//   of the buffer, whichever comes first. The target string is the characters
//   skipped except for the end " or line terminator delimiter.
//  Compiles code to check top of data stack for a flag and display the target string 
//   and ABORT if the flag is true. 
//
// Forth standard:
//  6.1.0680
//
// Note: 
//  Calling the compiled code before freeing any temporary buffers you have 
//   allocated could leak memory however, when the process terminates all buffers 
//   are automatically freed for you.
//  The string uses the rules for PARSE. The string must be on one line.
// 
//  A line terminator delimiter is one of:
//   c shorthand      ascii code    name  
//   '\n'             0x0a          <line feed>
//   '\v'             0x0b          <vertical tab>
//   '\b'             0x08          <back space>
//   '\r'             0x0c          <carriage return>
//   '\f'             0x0f          <form feed>
//
//
// Failure cases:
//  error clearing the datastack
//  
// ////////////////////////////////////////////////////////////////////////////////////// 
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthabs ( ABS )
//
// C prototype:
//  void dg_forthabs (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:
//  ( n1 -- u1 )
//
// Data stack in:
//  n1                            signed integer
//  
// Data stack out:
//  u1                            unsigned integer of value in n1
//
// Forth standard:
//  6.1.0690
//
// Action:
//  signed integer n1 is replaced with the absolute value of n1
//
// Note:
//  if 0x8000000000000000 is passed in, 0x7FFFFFFFFFFFFFFF is returned
//
// Failure cases:
//  error getting pointer to the datastack
//  data stack is missing n1
//  
// //////////////////////////////////////////////////////////////////////////////////////  
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthaccept ( ACCEPT )
//
// C prototype:
//  void dg_forthaccept (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:
//  ( c-addr +n1 -- +n2 )
//
// Data stack in:
//  c-addr                        address of memory area to put input characters
//  +n1                           signed integer (64 bit) greater than 0
//                                 is maximum number of characters (bytes) to receive
//  
// Data stack out:
//  +n2                           number of characters received
//
// Forth standard:
//  6.1.0695 and A.6.1.0695
//                                                              
// Action:
//  gets characters from the OS and adds them to the end of the string at caddr until 
//   the maximum allowed number of characters has been received or a line terminator 
//   is received (0x10).
//
// Note: 
//  this routine allows the user to go over +n1 while editing the string and then just 
//   gets up to +n1 characters after the user enters the edited string. 
//   See standard A.6.1.0695
//
// Handling of ambiguous conditions:
//  Standard specifies an ambiguous condition if +n1 > 32767 but I believe this 
//   assumes a 16 bit system. This routine works as indicated for all positive values 
//   of +n1 which is a 64 bit entity in this system.
//  If +n1 is <=0 then dg_signedlengthlessthan0error is pushed to the error stack 
//   and no characters are retrieved from the operating system.
//
// Failure cases:
//  error getting pointer to the datastack
//  data stack is missing n1 or caddr
//  n1 <= 0 (not checking the > 32767 thing cause this is a 64 bit implementation 
//   and > 0 covers it)
//  OS i/o error
//  memory area at caddr to caddr +n1 isn't in process space
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthalign ( ALIGN FALIGN DFALIGN )
//
// C prototype:
// void dg_forthalign (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:
//  Calculates a pointer to the end of the data space buffer.
//  If the pointer is not aligned, this grows the data space buffer
//    to the next aligned address.
//
// Forth standard:
//  6.1.0705  12.6.1.1479  12.6.2.1205
//
// Notes: 
//  An aligned address is one that is evenly divisible by the cell size, which is the 
//   size of UINT64 in this implementation.
//  The data space buffer is the current new variable buffer.
//  By default, at the start, the current new variable buffer and the current new code 
//   buffer share the same fixed size buffer.
//  The size of UINT64 is 8.
//  Start addresses of buffers are multiples of the system page size. In Windows, 
//   this is 8, in Linux this is 1024, In Mac Os S this is 4096.
//   Since these are multiples of 8, when the length of the data space buffer is aligned, 
//   the address of the end is aligned.
//
// Failure cases:
//  error getting current current new variable buffer id
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthaligned ( ALIGNED FALIGNED DFALIGNED )
//
// C prototype:
//  void dg_forthaligned (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:
//  ( addr -- a-addr )
//
// Data stack in:
//  addr                          pointer to align
//  
// Data stack out:
//  a-addr                        aligned pointer
//                                                              
// Action:
//  this routine moves the address to the next multiple of UINT64 or FLOAT64 size 
//  (which is 64 bits on my system)
//
// Forth standard:
//  6.1.0706  12.6.1.1483  12.6.2.1207
//
// Failure cases:
//  none
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthallot ( ALLOT )
//
// C prototype:
//  void dg_forthallot (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:
//  ( n1 -- )
//  ( -currentnewvariablebuffer- +n1bytes )
//
// Data stack in:
//  n1                            number of bytes to allocate or remove from data space 
//                                 buffer
//                                                              
// Action:
//  if n1 > 0, n1 bytes are added to the end of the data space buffer 
//   (current new variable buffer)
//  if n1 < 0, n1 bytes are removed from the end of the data space buffer 
//  if n1 = 0, the length of the data space buffer is unchanged
//
// Forth standard:
//  6.1.0710
//
// Note:
//  The data space buffer is the current new variable buffer.
//  By default, at the start, the current new variable buffer and the current new code 
//   buffer share the same fixed size buffer.
//
// Failure cases:
//  unable to get pointer to the data stack
//  error trying to grow the data space buffer
//  error trying to shrink the data space buffer
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthand ( AND )
//
// C prototype:
//  void dg_forthand (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:
//  ( u1 u2 -- u1&u2 ) 
//
// Data stack in:
//  u1 u2                         two unsigned integers (64 bit) to bitwise and 
//                                 together
//
// Data stack out
//  u3                            u3 = u1 bitwiseand u2;
//                                                              
// Action:
//  bitwise ands u1 with u2, removes u1 u2 from the data stack and replaces them with 
//   the result
//
// Forth standard:
//  6.1.0720
//
// Failure cases:
//  unable to get pointer to the data stack
//  u1 or u2 missing from the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////  
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthbase ( BASE )
//
// C prototype:
//  void dg_forthbase (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:
//  ( -- a-addr )
//
// Data stack out
//  a-addr                        address of the base variable which is aligned to the
//                                 size of UINT64
//                                                              
// Action:
//  gets the address of the base variable
//
// Forth standard:
//  6.1.0750
//
// Note:
//  At the start, the default data space buffer is of fixed size and will not move. 
//  The base variable is allocated in this buffer which means the pointer returned 
//   from this function will always be valid. Unless of course you find some way to 
//   resize the default data space buffer.
//
// Failure cases:
//  unable to get pointer to the base variable
//  unable to push to the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthbegin ( BEGIN )
//
// C prototype:
//  void dg_forthbegin (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:
//  ( -- beginoffset )
//
// Data stack out
//  codespacepointer              offset in current compile buffer of next address
//                                                              
// Action:
//  pushes the current code space offset in the current compile buffer to the control 
//  flow stack (current code space = current compile buffer)
//
// Forth standard:
//  6.1.0760
//
// Failure cases:
//  unable to get the current compile buffer id
//  unable to get pointer to the current compile buffer
//  unable to push to the data stack
//
// Note: offset isn't an address
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthbl ( BL )
//
// C prototype:
//  void dg_forthbl  (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:
//  ( -- char )
//
// Data stack out
//  char                          UINT64 0x20 which is the ascii code for a space
//                                                              
// Action:
//  pushes the ascii code for a space to the data stack
//
// Forth standard:
//  6.1.0770
//
// Failure cases:
//  error pushing the ascii code for a space to the data stack
//
// //////////////////////////////////////////////////////////////////////////////////////    
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthcstore ( C! )
//
// C prototype:
//  void dg_forthcstore (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:
//  ( char c-addr -- )
// 
// Datastack in:
//  char            character to store ( in UINT64 format, high order bits ignored )
//  c-addr          memory location in process space to put the number
//                                                              
// Action:
//  puts the character (byte) into memory at the address, 
//  both char and c-addr are removed from the datastack
//
// Forth standard:
//  6.1.0850
//
// Handling of ambiguous cases:
//  All addresses are already character aligned since a character is 8 bits in this 
//   program.
//
// Failure cases:
//  error getting pointer to the datastack
//  one or both of char and address are missing
//  address is not in process space or is read only
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthccomma ( C, )
//
// C prototype:
//  void dg_forthccomma (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:
//  ( char -- )
//            
// Data stack in:
//  char                          character (byte in 64 bit format) to push to current 
//                                 data space buffer
//                                                              
// Action:
//  puts data onto end of current data space buffer
//
// Forth standard:
//  6.1.0860
//
// Handling of ambiguous cases:
//  All addresses are already character aligned since a character is 8 bits in this 
//   program.
//
// Failure cases:
//  error getting pointer to the data stack
//  char missing from data stack
//  error getting current compile buffer id
//  error pushing to the current data space buffer
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthcfetch ( C@ )
//
// C prototype:
//  void dg_forthcfetch (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:
//  ( c-addr -- char )
//
// Data stack in:
//  c-addr                        pointer to data to get
//  
// Data stack out:
//  char                          this character (byte) is fetched from address and 
//                                 replaces the address on the data stack (push to 
//                                 data stack as 64 bit integer)
//                                                              
// Action:
//  gets the character at address and replaces address on the datastack with the 
//   character (character is zero extended to a UINT64)
//
// Forth standard:
//  6.1.0870
//
// Handling of ambiguous cases:
//  All addresses are already character aligned since a character is 8 bits in this 
//   program.
//
// Failure cases:
//  error getting pointer to the datastack
//  data stack is missing address
//  address isn't in process' space
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthcellplus ( CELL+ DFLOAT+ FLOAT+ )
//
// C prototype:
//  void dg_forthcellplus (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:
//  ( a-addr1 -- a-addr2 )
//
// Data stack in:
//  a-addr1                       aligned address
//  
// Data stack out:
//  a-addr2                       new aligned address = a-addr1 + one cell size 
//                                                              
// Action:
//  adds the size of a cell (8 in this implementation) to the address on top of the 
//   data stack
//
// Forth standard:
//  6.1.0880  12.6.1.1555  12.6.2.1208
//
// Handling of ambiguous cases:
//  this routine works the same for both aligned and unaligned addresses and just 
//   adds 8
//
// Failure cases:
//  error getting pointer to the datastack
//  data stack is missing address
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthcells ( CELLS DFLOATS FLOATS )
//
// C prototype:
//  void dg_forthcells (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:
//  ( n1 -- n2 )
//
// Data stack in:
//  n1                            number of cells
//  
// Data stack out:
//  n2                            number of address units (bytes) in the number 
//                                 of cells
//                                                              
// Action:
//  replaces n1 with n1 * cell size (which is 8 in this implementation)
//
// Forth standard:
//  6.1.0890  12.6.1.1556  12.6.2.1209
//
// Failure cases:
//  error getting pointer to the datastack
//  data stack is missing address
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthchar ( CHAR ) 
//
// C prototype:
//  void dg_forthchar (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" )
//  ( -- char )
//
// Current input buffer's current offset in:
//  "<delimiters>word<delimiters>morestuff"
//  
// Current input buffer's current offset out:
//  <delimiters>morestuff"  
//
// Data stack out:
//  char                             first character (byte) of word (in UINT64 format)
//                                                              
// Action:
//  moves the current offset pointer of the current input buffer to the first delimiter 
//  after the next word or to the end of the buffer if no word is found. The ascii code 
//  for the first character of the word is pushed onto the data stack
//
// Forth standard:
//  6.1.0895
//
// Failure cases:
//  error getting the buffer id of the current input buffer
//  error getting pointer to the current input buffer
//  no more words left in the current input buffer (in this case 0 is returned on the 
//   data stack and no error is pushed)
//  error pushing to the data stack
//  
// ////////////////////////////////////////////////////////////////////////////////////// 
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthcharplus ( CHAR+ )
//
// C prototype:
//  void dg_forthcharplus (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:
//  ( c-addr1 -- c-addr2 )
//
// Data stack in:
//  c-addr1                       character aligned address
//  
// Data stack out:
//  c-addr2                       new character aligned address = c-addr1 + one char 
//                                 size (one byte)
//                                                              
// Action:
//  adds the size of a character in address units (1 in this implementation) to the 
//   address on top of the data stack
//
// Forth standard:
//  6.1.0897
//
// Failure cases:
//  error getting pointer to the datastack
//  data stack is missing address
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthchars ( CHARS )
//
// C prototype:
//  void dg_forthchars (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:
//  ( n1 -- n2 )
//
// Data stack in:
//  n1                            number of characters
//  
// Data stack out:
//  n2                            number of address units (bytes) in the number of 
//                                 characters
//                                                              
// Action:
//  replaces n1 with n1 * character size which is 1 in this implementation, 
//   so this really does nothing
//
// Forth standard:
//  6.1.0898
//
// Failure cases:
//  error getting pointer to the datastack
//  data stack is missing address
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthcmove ( CMOVE )
//
// C prototype:
//  void dg_forthcmove (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:
//  ( addr1 addr2 u -- )
// 
// Datastack in:
//  addr1              source
//  addr2              destination
//  u                  signed integer count of number of characters to move (64 bit)
//                                                              
// Action:
//  if u is greater than 0, this copies data from addr1 to addr2 for u 
//   characters (bytes)
//  if the source and destination overlap, the destination may not be exactly the 
//   same as the original source. The copy operation starts at the source and 
//   increments after each byte moved.
//
// Forth standard:
//  17.6.1.0910
//
// Failure cases:
//  error getting pointer to the datastack
//  addr1 addr2 or u is missing from the data stack
//  process doesn't own all the memory or some of the destination memory is read only
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthcmoveto ( CMOVE> )
//
// C prototype:
//  void dg_forthcmoveto (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:
//  ( addr1 addr2 u -- )
// 
// Datastack in:
//  addr1              source
//  addr2              destination
//  u                  signed integer count of number of characters to move (64 bit)
//                                                              
// Action:
//  if u is greater than 0, this copies data from addr1 to addr2 for u 
//   characters (bytes)
//  if the source and destination overlap, the destination may not be exactly the 
//   same as the original source. The copy operation starts at the source plus 
//   u - 1 and decrements after each byte moved.
//
// Forth standard:
//  17.6.1.0920
//
// Failure cases:
//  error getting pointer to the datastack
//  addr1 addr2 or u is missing from the data stack
//  process doesn't own all the memory or some of the destination memory is read only
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthconstant ( CONSTANT )
//
// C prototype:
//  void dg_forthconstant (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>name<delimiters>morestuff" 
//     -currentinputbuffer-  "<delimiters>morestuff" )
//  ( x -- )
//
// Data stack in:
//  x                             value of constant for new definition
//  
// Current input buffer's current offset in:
//  "<delimiters>word<delimiters>morestuff" 
//
// Current input buffer's current offset out:
//  "<delimiters>morestuff" 
//                                                            
// Action:
//  Moves the current input buffer's current offset to the delimeter after the next 
//   series of non delimeter characters or the end of buffer if that comes first and 
//   then creates a new word in the current new word wordlist using the series of non 
//   delimiter characters at the name that:
//    pushes x onto the data stack when the process is in execute mode
//    and compiles code that pushes x onto the data stack when the process is in 
//    compile mode
//
// Forth standard:
//  6.1.0950
//
// Failure cases:
//  error getting current input buffer id
//  error gettint a pointer to the current input buffer
//  error popping the data stack
//  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_forthcount ( COUNT )
//
// C prototype:
//  void dg_forthcount (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:
//  ( c-addr1 -- c-addr2 u )
//
// Data stack in:
//  c-addr1                       address of a counted string
//  
// Data stack out:
//  c-addr2                       c-addr1 + 1
//  u                             contents (byte) of c-addr1 which is supposed to be the 
//                                 length of the counted string
//                                                              
// Action:
//  gets the character (byte) at c-addr1 and pushes it to the datastack as a 64 bit 
//   unsigned integer and increments c-addr1 by one character which is one byte in this 
//   implementation
//
// Forth standard:
//  6.1.0980
//
// Failure cases:
//  error getting pointer to the datastack
//  data stack is missing address
//  error pushing character to the data stack
//  bad address
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthcr ( CR )
//
// C prototype:
//  void dg_forthcr (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:
//  Sends an ascii 0x13 character to the current output which
//  causes terminal output to move to the beginning of the next line in most systems.
//
// Forth standard:
//  6.1.0990
// 
// Failure cases:
//  error calling myfputc
//  
// //////////////////////////////////////////////////////////////////////////////////////       
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthcreate ( CREATE )
//
// C prototype:
//  void dg_forthcreate (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" )
//  
// 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 series of non delimiter characters or to the end of the buffer if 
//   the end of the buffer comes first.
//  Then creates a new word in the current new word wordlist using the series of 
//   non delimiter characters as the name that: 
//    pushes the address of a variable onto the data stack when the process is in 
//    execute mode and compiles code that pushes the address of a variable onto the 
//    data stack when the process is in compile mode.
//  The address of the variable used is the address of the next unused byte in the 
//   current data space buffer.
//
// Forth standard:
//  6.1.1000
//
// Note
//  This routine will calculate the address of the variable from the variable's buffer 
//   id and offset at the time the code is called.
//  If the buffer the variable is in moves, the address will become invalid. For this 
//   reason, to be compatible with the old Forth commands, I suggest making the data 
//   space buffer of fixed size so it will not move if you are using ALLOT , C, and 
//   VARIABLE and do not want to have to worry about when your pointers become obsolete.
//  Either that or be done using the pointer before the next call to something that may 
//   cause the buffer to move such as doing ALLOT , C, or VARIABLE.
//
//  When Diaperglu first starts, the size of the current new variable buffer is of fixed 
//   size so you do not have to worry about it moving. This is for compatibility with 
//   older Forth programs which may keep the pointers around for a long time. 
//   Unfortunately I also made the current new variable buffer the same as
//   the current compile buffer which means you will likely run out of memory if you 
//   have a large program. I recommend changing them. PCURRENTCOMPILEBUFFER
//
//  If you change PCURRENTNEWVARIABLEBUFFER, then you have to worry about the life of 
//   the pointers from variables you CREATE in the new buffer.
// 
//  P.S. if you don't like how , and C, allocate memory in the data space area instead 
//   of the code space area, take this up with the Forth standards people :-). Either 
//   that or set the current compile buffer to be the same as the current variable
//   buffer. This way code and variable memory allocations use the same pointer in the 
//   same buffer.
//  
//  For example:
//
//   ( Diaperglu first starts )
//   CREATE PCOWS
//   PCOWS         ( address of PCOWS variable is on the data stack )
//   4 ALLOT       ( PCOWS address on the data stack is still valid because the default 
//                    new variable buffer was initialized with growby = maxsize )
//
//
//   100 1000 dg_newbuffer CONSTANT MYBUF
//   MYBUF PCURRENTNEWVARIABLEBUFFER !
//   CREATE PCATS
//   PCATS         ( address of PCATS variable is on the data stack )
//   100 ALLOT     ( base address of MYBUF has not moved yet because initial allocation 
//                    = growby )
//   1 ALLOT       ( OS may have moved base address of MYBUF )
//                 ( address of PCATS variable on the data stack is now invalid! )
//                 ( address of PCOWS is still valid because it is in the other buffer )
// 
//   DROP          ( getting rid of bad PCATS pointer )
//   PCATS         ( Diaperglu calculates the new address of PCATS, this one is valid )
//                 (  for now. Quick! use the pointer before it becomes invalid! )
// 
//   100 ALLOT     ( buffer may have moved again, new address of PCATS on data stack is 
//                    invalid )
//
// 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_forthdecimal ( DECIMAL )
//
// C prototype:
//  void dg_forthdecimal (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:
//  Sets the BASE variable to 10
//
// Forth standard:
//  6.1.1170
// 
// Failure cases:
//  error putting 10 to the base variable
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthdepth ( DEPTH )
//
// C prototype:
//  void dg_forthdepth (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:
//  ( nx ... n2 n1 -- nx ... n2 n1 x )
// 
// Data stack out:
//   x                            number of integers on the stack before calling this 
//                                 routine
//                                                             
// Action:
//  pushes the number of integers (64 bit) on the data stack onto the data stack
//
// Forth standard:
//  6.1.1200
// 
// Failure cases:
//  error getting pointer to the data stack
//  error pushing to the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthdo ( DO )
//
// C prototype:
//  void dg_forthdo (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:
//  ( -- do-sys )
//
// Compiles code that does:
//  ( index limit -- ) 
//  ( -r- limit index )
// 
// Data stack out:
//  do-sys                        current compile buffer offset of beginning of loop                             
//                                                             
// Action:
//  compiles >R >R BEGIN
//
// Handling of ambiguous conditions:
//  For LOOP, index and limit are treated as UINT64s. 
//   When the index is one less than the limit, the loop exits.
//  For +LOOP, index, limit, and step size are treated as INT64s.
//   When the adding the step size to the index would make it cross or equal the
//    limit boundary, the loop exits.
//
// Forth standard:
//  6.1.1240
// 
// Failure cases:
//  error getting current compile buffer id
//  error growing the current compile buffer
//  error getting pointer to the current compile buffer
//  error doing BEGIN
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthdoes ( DOES> )
//
// C prototype:
//  void dg_forthdoes (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:
//  compiles code to change the compile routine of the latest definition to call the 
//   code compiled immediately after what this DOES> compiles
//  compiles a return
//  compiles code to convert the dataoffset databufid pair on the data stack to an 
//   address
//
// NOTE:
//  DOES> is used after a CREATE in a colon definition to change the compile 
//   routine from pushaddressorcompilepushaddress to the user defined code following 
//   DOES> up until the semicolon.
//  
//  The data address from the CREATE is passed in to the user routine so to the code 
//   following DOES> it looks like this:
//
//  void namelessusercompileroutine (Bufferhandle* pBHarrayhead)
//                                  ( dataaddress -- )
//  
//  The code between CREATE and DOES> is usually used to allocate and initialize 
//   data field memory for the new definitions.
//  
// SAMPLE USAGE:
//  : DOUBLEVARIABLE CREATE 8 ALLOT DOES> ;  // kind of the same as VARIABLE 4 ALLOT
//  
//  DOUBLEVARIABLE D1
//  DOUBLEVARIABLE D2
//  86 0 D1 2!
//
//  : DOUBLECONSTANT CREATE , , DOES> 2@ ;
//  345 01 DOUBLECONSTANT BIGNUM
//  BIGNUM . .                     // displays 01 345
//
//  : INHBYTE, CREATE , DOES> @ C, ;   // note: this assumes the current data space 
//                                        //  buffer (for new variables) and current 
//                                        //  compile space buffer (for new code) still 
//                                        //  share the same buffer according to the 
//                                        //  forth standard, C, and , operate on the 
//                                        //  current data space buffer only (current 
//                                        //  new variable buffer)
//
//  HEX 
//  C3 INHBYTE, RET,      // makes an 80386 assembler compiling word to compile RET
//  FA INHBYTE, CLI,      // makes an 80386 assembler compiling word to compile CLI
//  90 INHBYTE, NOP,      // makes an 80386 assembler compiling word to compile a NOP
//
// Forth standard:
//  6.1.1250
//
// Handling of ambiguous conditions:
//  If you use DOES> to modify a word name not created using CREATE, this routine 
//   will still do the same actions as above.
//
// Failure cases:
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthdrop ( DROP )
//
// C prototype:
//  void dg_forthdrop(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:
//  ( n -- )
// 
// Data stack in:
//  x                             integer (64 bit) to remove from the data stack
//                                                             
// Action:
//  removes the top integer from the data stack
//
// Forth standard:
//  6.1.1260
// 
// Failure cases:
//  error getting pointer to the data stack
//  data stack doesnt have anything on it
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthdup ( DUP )
//
// C prototype:
//  void dg_forthdup(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:
//  ( n1 -- n1 n1)
//
// Data stack in:
//  x1                            integer (64 bit) to duplicate
//  
// Data stack out:
//  x1 x1                         
//                                                              
// Action:
//  pushes a copy of the int on top of the data stack to the data stack
//
// Forth standard:
//  6.1.1290
//
// Failure cases:
//  error popping the data stack
//  error pushing the data stack
//  
// ////////////////////////////////////////////////////////////////////////////////////// 
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthelse ( ELSE ELSE, )
//
// C prototype:
//  void dg_forthelse (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:
//  ( ifoffset -- elseoffset )
// 
// Data stack in:
//  ifoffset                      next unused byte in current compile buffer from an IF
//                     
// Action: 
//  compiles an unresolved branch always and puts the offset of the unresolved branch onto 
//   the data stack resolves the unfinished branch from IF
//
// Forth standard:
//  6.1.1310
//
// NOTE:
//  This code assumes the current compile buffer wasn't changed since IF was done
//
// Failure cases:
//  error getting current compile buffer id
//  error getting a pointer to the data stack
//  missing the if offset from the data stack
//  error getting a pointer to the current compile buffer
//  error calling then
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthemit ( EMIT )
//
// C prototype:
//  void dg_forthemit (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:
//  ( n1 -- )
// 
// Data stack in:
//  n1                            integer (64 bit) representation of the character 
//                                 (8 bit) to output
//                                                              
// Action:
//  sends the low byte of n1 to the current output
//
// Forth standard:
//  6.1.1320
// 
// Failure cases:
//  
// //////////////////////////////////////////////////////////////////////////////////////          
// ////////////////////////////////////////////////////////////////////////////////////// 
//
// dg_forthenvironmentquery ( ENVIRONMENT? )
//
// C prototype:
//  void dg_forthenvironmentquery (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:
//  ( c-addr u -- false | i*x true )
// 
// Data stack in:
//  c-addr                        pointer to character string to look up
//  u                             length of character string (64 bit)
//                                                              
// Action:
//  Removes c-addr and u from the data stack
//  This routine looks up the string at c-addr in the ENVIRONMENT-WORDLIST
//  If the string is found, the action for the string is done and TRUE is pushed to 
//   the data stack otherwise FALSE is pushed to the data stack
//
// Forth standard:
//  6.1.1345
// 
// Failure cases:
//  error pushing wordlist id
//  error searching wordlist
//  
// ////////////////////////////////////////////////////////////////////////////////////// 
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthevaluate ( EVALUATE )
//
// C prototype:
//  void dg_forthevaluate (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:
//  ( c-addr u -- )
// 
// Data stack in:
//  c-addr                        pointer to character string to evaluate
//  u                             length of character string (64 bit)
//                                                              
// Action:
//  Removes c-addr and u from the data stack
//  Evaluates the string at c-addr u as if it were typed in from the console
//
// Forth standard:
//  6.1.1360
//  
// Failure cases:
//  error getting pointer to the data stack
//  data stack underflow
//  error getting a new buffer
//  error pushing the string to the new buffer (shouldn't happen)
// 
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthexecute ( EXECUTE )
//
// C prototype:
//  void dg_forthexecute (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 -- )
// 
// Data stack in:
//  xt                            index of the definition in the definition array                           
//                                                              
// Action:
//  gets the definition header from the definition array
//  then executes the word as if it appeared in an input script
//  
// Note: 
//  if the script is in compiling mode then this word will be compiled
//
// Forth standard:
//  6.1.1370
// 
// Failure cases:
//  error popping execute token from the data stack
//  error calling execute definition
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthexit ( EXIT )
//
// C prototype:
//  void dg_forthexit (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:
//  compiles a subroutine return at the current position in the current compile buffer
//
// Forth standard:
//  6.1.1380
//
// Failure cases:
//  eror compiling return at the end of the current compile buffer
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthfill ( FILL )
//
// C prototype:
//  void dg_forthfill (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:
//  ( c-addr n char -- )
// 
// Datastack in:
//  c-addr          first memory location in process space to put n of char
//  n               signed integer (64 bit) representing the number of characters 
//                   (8 bit) to store 
//  char            the character to store (8 bit in 64 bit format)
//                                                              
// Action:
//  stores n of char starting at c-addr
//
// Forth standard:
//  6.1.1540
//
// Failure cases:
//  error getting pointer to the datastack
//  c-addr n or char is missing from the data stack
//  one or more of the addresses is not in the process space or is read only
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthfind ( FIND )
//
// C prototype:
//  void dg_forthfind (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:
//  ( c-addr -- c-addr 0 ) if word not found
//  ( c-addr -- xt 1 ) if word found and it is immediate
//  ( c-addr -- xt -1 ) if word found and it is not immediate
// 
// Datastack in:
//  c-addr                        address of a forth "counted" string 
//                                 representing the name to find a counted string is a 
//                                 string where the first character (8 bit in this 
//                                 implementation) represents the length
//
// Datastack out:
//  c-addr 0                      if the name wasn't found c-addr is returned unchanged 
//                                 along with a 0
//  or xt 1                       if the name was found and it is immediate, 
//                                 the word's execute token along with 1 is returned
//  or xt -1                      if the name was found and it is not immediate, 
//                                 the word's execute token along with -1 is returned
//                                                              
// Action:
//  searches all word lists in the search order stack for the word having the same name 
//   as the counted string at c-addr and returns different flags and results based on 
//   what it finds
//
// Forth standard:
//  6.1.1550 and 16.6.1.1550
//
// Failure cases:
//  error popping c-addr from the data stack
//  c-addr is invalid
//  error finding definition in search order
//  error pushing c-addr 0 to the data stack
//  error pushing definition to the data stack
//  error getting pointer to the definition
//  error pushing execute flag to the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthfmslashmod ( FM/MOD )
//
// C prototype:
//  void dg_forthfmslashmod (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:
//  ( d1 n1 -- n2 n3 )
//
// Datastack in:
//  d1              double signed integer (128 bit lo hi) to be divided (top number)
//  n1              single signed integer (64 bit) used to divide (bottom number)
//
// Datastack out:
//  n2              single signed integer (64 bit) remainder
//  n3              single signed integer (64 bit) floored quotient
//                                                              
// Action:
//  divides d1 by n1 giving n3 remainder n2
//  if d1 and n1 have opposite signs, floored rounding rules apply 
//
// Forth standard:
//  6.1.1561
//
// Handling of ambiguous cases:
//  If n1 is 0, n3 and n2 are set to the largest possible signed integer 
//   with the same sign as d1.
//   (n2 = n3 = 0x7fffffffffffffff if positive, n2 = n3 = 0x8000000000000000 if 
//   negative)
//  If quotient is too big to fit into n3, n3 and n2 are set to the largest possible
//   signed integer with the same sign as the quotient.
//   (n2 = n3 = 0x7fffffffffffffff if positive, n2 = n3 = 0x8000000000000000 if 
//   negative)
//
// Failure cases:
//  error getting pointer to the datastack
//  d1 or n1 is missing from the data stack
//  
// Note:
//  in the event of overflow or divide by 0, the largest signed value is returned
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthhere ( HERE )
//
// C prototype:
//  void dg_forthhere (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:
//  ( -- addr )
//
// Datastack out:
//  addr                          current next free address in the data space area 
//                                 (current new variable buffer)
//                                                              
// Action:
//  gets the current address of the data space pointer 
//
// Forth standard:
//  6.1.1650
//
// NOTE:
//  If the data space buffer grows, it's base address can change rendering the address 
//   returned by HERE invalid so if you use HERE, make sure you either A) finish using 
//   the address returned by HERE before allocating any more data space memory with ,
//   C, or ALLOT and if you made the data space buffer the same as the compile space 
//   buffer, you also need to finish using here before compiling any more definitions.
//   or B) make sure the data space buffer won't grow while you are using the address. 
//   You can do this by making the data space buffer's growby equal to it's max size 
//   or pre-allocating all the memory you will use. You can pre-allocate by doing a 
//   big ALLOT and then - ALLOT what you just allotted.
//  When Diaperglu starts, the data space buffer is of fixed size and can not grow. 
//  If you allocate a new buffer where it's growby does not equal it's maxsize and 
//   assign it to PCURRENTNEWVARIABLEBUFFER you will have the above problem.
// 
// Failure cases:
//  error getting current data space buffer id
//  error getting pointer to the data space buffer
//  error pushing the address to the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthhold ( HOLD )
//
// C prototype:
//  void dg_forthhold (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:
//  ( char -- )
//  ( number$ -hold- <char>number$ )
// 
// Datastack in:
//  char            character (8 bit in 64 bit format) to insert into pad buffer
//
// Pad in:
//  number$         char array containing string representation of partially 
//                   converted number
//
// Pad out:
//  number$'        now has next character inserted at beginning
//                                                              
// Action:
//  inserts character at beginning of pad, character is a byte in this 
//   implimentation
//
// Forth standard:
//  6.1.1670
//
// Handling of ambiguous conditions:
//  If this routine is called outside of a number conversion it still does the same 
//   action, a character is still inserted into the beginning of the pad buffer.
//
// Failure cases:
//  error popping character from the data stack
//  error inserting in to pad
//  error putting character at beginning of pad
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthi ( I )
//
// C prototype:
//  void dg_forthi (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:
//  ( index limit -rstack- index limit )
//  ( -- index )
// 
// Control Flow Stack In:
//  index                          (innermost) loop index (64 bit)
//  
// Control Flow Stack Out:
//  index                          (innermost) loop index (64 bit)
//
// Data Stack Out:
//  n1                            copy of (innermost) loop index from control flow 
//                                 stack (64 bit)
//                                                           
// Action:
//  gets a copy of the (innermost) loop index from the control flow stack and 
//   pushes it to the data stack
//
// Forth standard:
//  6.1.1680
//
// Handling of ambiguous cases:
//  If the loop control parameters are unavailable, this routine pushes an error 
//   to the error stack. 
//  In the event of an underflowm, offset = dg_rstackunderflowerror and bufferid 
//   = DG_CORE_BUFFERID is pushed. ( RSTACKUNDERFLOWERROR ) 
//
// Failure cases:
//  error getting pointer to the control flow stack
//  loop index missing from the control flow stack
//  error pushing to the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthif ( IF )
//
// C prototype:
//  void dg_forthif (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:
//  ( -- ifoffset )
// 
// Data stack out:
//  branchresolutionoffset        next unused byte in current compile buffer which is 
//                                 used by THEN 
//                     
// Action:
//  compiles code to check for a 0 on the data stack, 
//  and compiles code that takes an unresolved branch if a 0 is found
//
// Note:
//  the compiled code doesn't check for an error from popping the data stack
//
// Forth standard:
//  6.1.1700
//
// Failure cases:
//  error getting current compile buffer id
//  error growing the current compile buffer
//  error getting a pointer to the current compile buffer
//  error pushing the branch resolution offset to the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthimmediate ( IMMEDIATE )
//
// C prototype:
//  void dg_forthimmediate (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 routine of the last word of the current compile word list was of 
//   execute in execute mode and compile subr call or safe subr call in compile mode, 
//   then the compile routine is replaced with execute in both modes.
//
// Forth standard:
//  6.1.1710
//
// Handling of abiguous cases:
//  The standard says it's an ambiguous if the latest definition does not have a name 
//   but I'm not sure how that can happen. In any case, the action above is done for 
//   the latest word defined regardless of how the word was created.
//
// Failure cases:
//  error getting current vocabulary id
//  error getting latest definition execute token
//  error getting pointer to the latest definition 
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthinvert ( INVERT )
//
// C prototype:
//  void dg_forthinvert (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:
//  ( x1 -- x2 )
//  
// Data Stack In:
//  x1                            integer (64 bit) to invert
//
// Data Stack Out:
//  x2                            x2 is x1 with all the bits flipped
//                                                            
// Action:
//  logically inverts all bits of the integer on the top of the data stack
//
// Forth standard:
//  6.1.1720
//
// Failure cases:
//  error getting pointer to the data stack
//  integer to invert missing from the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthj ( J )
//
// C prototype:
//  void dg_forthj (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:
//  ( index2 limit2 index1 limit1 -rstack- index2 limit2 index1 limit1 )
//  ( -- index2 )
// 
// Control Flow Stack In:
//  limit2 index2                 (next-outer) loop index (64 bit)
//  limit1 index1                 (innermost) loop index  (64 bit)
//
// Control Flow Stack Out:
//  limit2 index2                 (next-outer) loop index
//  limit1 index1                 (innermost) loop index
//
// Data Stack Out:
//  index2                        copy of (next-outer) loop index from control flow 
//                                 stack (64 bit)
//                                                           
// Action:
//  gets a copy of the (next-outer) loop index from the control flow stack and pushes 
//   it to the data stack
//
// Forth standard:
//  6.1.1730
//
// Handling of ambiguous cases:
//  If the loop control parameters of the next outer loop are unavailable, 
//   this routine pushes an error to the error stack. 
//  In the event of an underflowm, offset = dg_rstackunderflowerror and bufferid 
//   = DG_CORE_BUFFERID is pushed. ( RSTACKUNDERFLOWERROR ) 
//
// Failure cases:
//  error getting pointer to the control flow stack
//  next-outer loop index missing from the control flow stack
//  error pushing to the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthkey ( KEY )
//
// C prototype:
//  void dg_forthkey (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:
//  ( -- char )
//
// Data Stack Out:
//  char                          character (8 bit) representation of a key press
//                                                           
// Action:
//  Gets the next key press from the console input que or waits for the user to press 
//   a key then returns the character code for that key. This routine does not echo 
//   the keypress to the output nor does it wait for the user to enter an entire line 
//   before returning.
//
// Forth standard:
//  6.1.1750
//
// Note: 
//  The key code for 'a' is it's ascii code. Most of them work that way.
//  This word may not be implemented on non Microsoft operating systems.
//
// Failure cases:
//  error pushing the key code to the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthleave ( LEAVE )
//
// C prototype:
//  void  dg_forthleave (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:
//  ( -- ) 
//  ( -leavestack- leaveoffset )
//
// Leave Stack Out:
//  leaveoffset                   offset of next unused byte in current compile buffer 
//                                 (64 bit)
//                                                           
// Action:
//  Compiles an unresolved branch always to the current compile buffer
//  Pushed the buffer offset of the unresolved branch to the leave stack
//
// Forth standard:
//  6.1.1760
//
// Handling of ambiguous cases:
//  dg_forthloop ( LOOP ) and dg_forthplusloop ( +LOOP ) resolve the unresolved leave
//  branches to point to the portion of their code that handles the dropping of the 
//  loopsys from the return stack. In other words it does not matter to this routine
//  if loopsys is not available but it will matter in dg_forthloop and dg_forthplusloop.
//
// Failure cases:
//  error getting the current compile buffer id
//  error growing the current compile buffer
//  error getting the pointer to the current compile buffer
//  error pushing the branch resolution buffer offset to the leave stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthliteral ( LITERAL )
//
// C prototype:
//  void dg_forthliteral (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:
//  ( n1 -- )
//
// Compiles code that does:
//  ( -- n1 )
//  
// Data stack in:
//  n1                            number to compile (64 bit)
//                                                           
// Action:
//  compiles code to push n1 to data stack
//
// Forth standard:
//  6.1.1780
//
// Failure cases:
//  error getting current compile buffer id
//  error popping n1 from the data stack
//  error growing the current compile buffer
//  error getting the pointer to the current compile buffer
//  
// //////////////////////////////////////////////////////////////////////////////////////
UINT64 dg_checkloopdone (Bufferhandle* pBHarrayhead)
//       ( index limit -r- index limit | index+1 limit )
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthloop ( LOOP )
//
// C prototype:
//  void dg_forthloop (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:
//  ( do-sys -- )
//
// Compiled code does: 
//  ( loop-sys1 -controlflowstack- loop-sys1' ) 
//    if loop does not end and flow branches to where DO was executed
//  ( loop-sys1 -controlflowstack- ) if loop ends. LEAVE branches resolve to here
//
// Data Stack Out:
//  do-sys                        offset to loop back to from DO (64 bit)
//                                                           
// Action:
//  compiles code to check loop done condition and branch if it isn't
//   compiled code calls dg_checkloopdone which sees if index = limit - 1, 
//   if it is equal, dg_checkloopdone drops the limit and index from the rstack. 
//   If it isn't equal, dg_checkloopdone increments the index and then the compiled 
//    code branches back to the DO offset
//
// Forth standard:
//  6.1.1800
//
// Handling of ambiguous conditions:
//  If the loop control parameters are not available, dg_rstackunderflowerror is 
//   pushed to the error stack and the loop exits.
//
// Failure cases:
//  error getting current compile buffer id
//  error popping beginoffset from the data stack
//  error growing the current compile buffer
//  error getting the pointer to the current compile buffer
//  error getting the pointer to the leave stack
//  error resolving a leave
//  error growing the current compile bufer a second time
//  error getting the pointer to the current compile buffer the 2nd time
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthlshift ( LSHIFT )
//
// C prototype:
//  void dg_forthlshift (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:
//  ( x1 u -- x2 )
//
// Data stack in:
//  x1                            integer to shift to the left (64 bit)
//  u                             unsigned number of bit places to shift 
//                                  (64 bit but only low 5 bits are used, rest ignored )
// 
// Data stack out:
//  x2                            the result of the shift with 0 shifted into the 
//                                 vacated positions
//
// Note:                          
//  the calculation for a signed x1 is the same as for an unsigned x1
//  only the lowest 5 bits of u are used, the rest are ignored so if you
//  specify shifts larger than 31 bits, you will get a shift equal to u anded with 31
//                                                              
// Action:
//  x2 = x1 << u
//
// Forth standard:
//  6.1.1805
//
// Failure cases:
//  error getting pointer to the data stack
//  x1 or u is missing from the datastack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthmstar ( M* )
//
// C prototype:
//  void dg_forthmstar (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:
//  ( n1 n2 -- d )
//
// Data stack in:
//  n1                            first signed integer to multiply
//  n2                            second signed integer to multiply
// 
// Data stack out:
//  d (-- dlo dhi)                double cell signed double integer result of the 
//                                 signed multiply
//                                                              
// Action:
//  d = n1 * n2
//
// Forth standard:
//  6.1.1810
//
// Failure cases:
//  error getting pointer to the data stack
//  n1 or n2 is missing from the datastack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthmax ( MAX )
//
// C prototype:
//  void dg_forthmax (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:
//  ( n1 n2 -- n3 )
//            
// Data stack in:
//  n1                            first signed integer to compare (64 bit)
//  n2                            second signed integer to compare (64 bit)
// 
// Data stack out:
//  n3                            the greater of n1 or n2 (64 bit)
//                                                              
// Action:
//  Compares n1 with n2 and replaces them with the greater of the two.
//
// Forth standard:
//  6.1.1870
//
// Failure cases:
//  error getting pointer to the data stack
//  n1 or n2 is missing from the datastack
//  
// //////////////////////////////////////////////////////////////////////////////////////    
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthmin ( MIN )
//
// C prototype:
//  void dg_forthmin (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:
//  ( n1 n2 -- n3 )
//            
// Data stack in:
//  n1                            first signed integer to compare (64 bit)
//  n2                            second signed integer to compare (64 bit)
// 
// Data stack out:
//  n3                            the lesser of n1 or n2 (64 bit)
//                                                              
// Action:
//  compares n1 with n2 and replaces them with the lesser of the two
//
// Forth standard:
//  6.1.1880
//
// Failure cases:
//  error getting pointer to the data stack
//  n1 or n2 is missing from the datastack
//  
// //////////////////////////////////////////////////////////////////////////////////////    
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthmod ( MOD )
//
// C prototype:
//  void dg_forthmod (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:
//  ( n1 n2 -- n3 )
//
// Datastack in:
//  n1              signed integer to be divided (64 bit top number)
//  n2              single integer used to divide (64 bit bottom number)
//
// Datastack out:
//  n3              single signed integer remainder (64 bit)
//                                                              
// Action:
//  divides n1 by n2 giving remainder n3
//  if n1 and n2 have opposite signs, symmetric rounding rules apply 
//
// Forth standard:
//  6.1.1890
//  
// Failure cases:
//  error getting pointer to the datastack
//  d1 or n1 is missing from the data stack
//
//  Note: in the event of divide by 0 or overflow the largest signed integer is 
//   returned
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthmove ( MOVE )
//
// C prototype:
//  void dg_forthmove (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:
//  ( addr1 addr2 u -- )
// 
// Datastack in:
//  addr1              source
//  addr2              destination
//  u                  signed integer count of number of characters to move (64 bit)
//                                                              
// Action:
//  if u is greater than 0, this copies data from addr1 to addr2 for u characters 
//   (bytes) after the move addr2 contains exactly what was at addr1
//
// Forth standard:
//  6.1.1900
//
// Failure cases:
//  error getting pointer to the datastack
//  addr1 addr2 or u is missing from the data stack
//  process doesn't own all the memory or some of the destination memory is read only
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthnegate ( NEGATE )
//
// C prototype:
//  void dg_forthnegate (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:
//  ( n1 -- 0-n1 )
//  
// Data Stack In:
//  n1                            integer to negate (64 bit)
//
// Data Stack Out:
//  n2                            x2 is equal to 0 - x1 (64 bit)
//                                                            
// Action:
//  subtract n1 from 0 and replace n1 with the result
//
// Forth standard:
//  6.1.1910
//
// Failure cases:
//  error getting pointer to the data stack
//  integer to negate missing from the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////  
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthor ( OR )
//
// C prototype:
//  void dg_forthor (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:
//  ( x1 x2 -- x3 )
//
// Data stack in:
//  x1 x2                         two unsigned integers to bitwise or together (64 bit)
//
// Data stack out
//  x3                            x3 = x1 bitwiseor x2 (64 bit)
//                                                              
// Action:
//  bitwise ors x1 with x2, removes x1 x2 from the data stack and replaces them with 
//   the result
//
// Forth standard:
//  6.1.1980
//
// Failure cases:
//  unable to get pointer to the data stack
//  x1 or x2 missing from the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////             
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthover ( OVER )
//
// C prototype:
//  void dg_forthover (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:
//  ( n1 n0 -- n1 n0 n1 )
//
// Data stack in:
//  n1 n0                         two integers (64 bit) 
//
// Data stack out
//  n1 n0 n1                      n1 is copied over n0
//                                                              
// Action:
//  n1 is pushed to the data stack 'over' n0
//
// Forth standard:
//  6.1.1990
//
// Failure cases:
//  unable to get pointer to the data stack
//  n1 or n0 missing from the data stack
//  unable to push n1 to the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////          
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthpostpone ( POSTPONE )
//
// C prototype:
//  void dg_forthpostpone (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" )
//   
// Action:
//  look up definition of next word in input buffer and force compilation of the word
//  If the next word is always execute, postpone compiles it as a safe call.
//
// Forth standard:
//  6.1.2033
//
// Handling of ambiguous conditions:
//  If the word is not found in the current search order,
//   dg_wordnotfoundinsearchordererror ( WORDNOTFOUNDERROR ) and
//   dg_forthpostponename ( POSTPONE )
//   are pushed to the error stack.
//
//  Note: 
//   This routine errors on the side of caution.
//    Really only need to force safe compilation of always execute compiling
//    words such as EXIT.
//  
// Failure cases:
//  error calling tick
//  error popping the definition from the data stack
//  definition for the word not found
//  error getting the pointer to the definition
//  error pushing the data offset
//  error pushing the data buffer
//  error calling the compile routine
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthquit ( QUIT )
//
// C prototype:
//  void dg_forthquit (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:
//  ( ? -r-  )
//  ( firstquitstuff ... -ret- firstquitstuff )
//
// Action:
//  clears the rstack, and gets rid of all the nested subroutine info from the 
//   return stack since the first time QUIT was invoked.
//
// Forth standard:
//  6.1.2050
// 
// NOTE!!!: 
//  QUIT leaks memory after the first time it is called until Diaperglu exits.
//   It has no way of freeing the buffers that were allocated since QUIT was called 
//    the first time.
//   if you are interpreting a file using INCLUDEFILE$ or a string using EVALUATE, 
//   QUIT WILL leak the interpret buffer temporarily until the program exits.
//   Diaperglu will still free all buffers when it exits back to the operating system. 
//   
// Failure cases:
//  error getting was quit initialized flag
//  error getting saved esp from sp holder
//  error getting saved ebp from ebp holder
//  error clearing rstack
//  error setting script processing state variable to execute
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthrfrom ( R> )
//
// C prototype:
//  void dg_forthrfrom (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:
//  ( x1 -r- )
//  ( -- x1 )
//  
// Rstack In: 
//  x1                            integer (64 bit)
// 
// Data Stack Out:
//  x1                            integer (64 bit)
// 
// Action:
//  pops x1 from rstack and pushes it to the data stack
//
// Forth standard:
//  6.1.2060
//
// Failure cases:
//  Error popping x1 from the rstack
//  Error pushing x1 to the datastack
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthrfetch ( R@ )
//
// C prototype:
//  void dg_forthrfetch (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:
//  ( x1 -r- x1 )
//  ( -- x1 )
//  
// Rstack In: 
//  x1                            integer (64 bit)
// 
// Rstack Out:
//  x1                            integer (64 bit)
// 
// Data Stack Out:
//  x1                            integer (64 bit)
// 
// Action:
//  copies x1 from rstack and pushes it to the data stack
//
// Forth standard:
//  6.1.2070
//
// Failure cases:
//  Error getting pointer to rstack
//  x1 missing from rstack
//  Error pushing x1 to the datastack
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthrecurse ( RECURSE )
//
// C prototype:
//  void dg_forthrecurse (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:
//  Compiles a call to the currently compiling : routine. 
//
// Forth standard:
//  6.1.2120
//
// Handling of ambiguous conditions:
//  If RECURSE appears in a definition after a DOES>, RECURSE will still attempt to 
//   compile a call to the latest defined word. 
//   The method this routine uses is this:
//    get the execution token of the latest defined word, force STATE to compile mode,
//    and execute the token.
//
// Note:
//  FORTH needs RECURSE because the current routine does not appear in the current new 
//   word list until the ;
//  This is to allow you call an existing defintion's old behavior while you redefine
//   it.
//  At this time RECURSE doesn't check to make sure you are in a colon routine, nor 
//   does it make sure the last defined word was a call to a subroutine
//
// Failure cases:
//  Error getting pointer to rstack
//  x1 missing from rstack
//  Error pushing x1 to the datastack
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthrepeat ( REPEAT REPEAT, )
//
// C prototype:
//  void dg_forthrepeat (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:
//  ( whileoffset beginoffset -- )
//
// Data stack in:
//  beginoffset                   length of compile buffer at the time of the BEGIN
//  whileoffset                   length of current compile buffer at the time of a
//                                 WHILE
//                     
// Action:
//  compiles the jump back to BEGIN and resolves the unfinished branch from WHILE
//
// Forth standard:
//  6.1.2140
//
// NOTE:
//  This code assumes the current compile buffer wasn't changed since BEGIN or WHILE 
//   was done
//  This code assumes the branches are within +-2gig
//  This code assumes that the numbers popped from the data stack are the offsets 
//   from BEGIN and WHILE
//
// Failure cases:
//  error getting current compile buffer id
//  error getting the pointer to the data stack
//  data stack underflow
//  error growing the current compile buffer
//  error getting a pointer to the current compile buffer
//  error compiling THEN
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthrot ( ROT )
//
// C prototype:
//  void dg_forthrot (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:
//  ( n1 n2 n3 -- n2 n3 n1 )
//  
// Data Stack In: 
//  x1 x2 x3                      integers (64 bit)
// 
// Data Stack Out:
//  x2 x3 x1                      integers (64 bit)
// 
// Action:
//  Rearranges the top 3 integers on the data stack.
//
// Forth standard:
//  6.1.2160
//
// Failure cases:
//  Error getting pointer to the data stack
//  there aren't 3 items on the data stack
//
// //////////////////////////////////////////////////////////////////////////////////////           
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthrshift ( RSHIFT )
//
// C prototype:
//  void dg_forthrshift (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:
//  ( x1 u -- x2 )
//
// Data stack in:
//  x1                            integer to shift to the right (64 bit)
//  u                             number of bit places to right 
//                                (only 5 out of 64 bits used, the rest are ignored)
// 
// Data stack out:
//  x2                            the result of the shift with 0 shifted into the 
//                                 vacated positions
//                                                              
// Action:
//  x2 = x1 >> u
//
// Forth standard:
//  6.1.2162
//
// Notes:
//  if u is greater than 32, x1 is shifted only u anded with 31 positions
//
// Failure cases:
//  error getting pointer to the data stack
//  x1 or u is missing from the datastack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthsquotes  ( S" )
//
// C prototype:
//  void dg_forthsquotes (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:
//  ( "somestuff<quotes>morestuff" -currentinputbuffer- 
//     "morestuff" )
//
// Compiled code does:
//  ( -- c-addr u  )
//
// Current input buffer's current offset in:
//  "somestuff<quotes>morestuff"
//
// Current input buffer's current offset out:
//  "morestuff"
//
// Compiled code data stack out:
//  c-addr                       pointer to copy of "somestuff"
//  u                            length of "somestuff" in characters (bytes)
//                                                              
// Action:
//  In both compile and execute state:
//  Moves the current input buffer's current offset pointer to the next 
//   character after the next ", the character after the next line terminator
//   delimiter, or to the end of the buffer, whichever comes first.
//  Then compiles code to have the RIP skip over the counted string and push the 
//   address of the string to the return stack. (It's a call over the string.) 
//   Then compiles the string. Then this compiles code to pop the address off of
//   the return stack and push it to the data stack. Then compiles code to push
//   the length to the return stack.
//  I did it this way is so that if the buffer moves after it's compiled, the address 
//   will be calculated at runtime and be valid at the time this code is executed.
//
// Forth standard:
//  6.1.2165
//
// Note:
//  A line terminator delimiter is one of:
//   c shorthand      ascii code    name  
//   '\n'             0x0a          <line feed>
//   '\v'             0x0b          <vertical tab>
//   '\b'             0x08          <back space>
//   '\r'             0x0c          <carriage return>
//   '\f'             0x0f          <form feed>
//
// Failure cases:
//  error getting the current input buffer id
//  error getting the pointer to the current input buffer
//  error getting the current compile buffer id
//  error growing the current compile buffer
//  error getting the pointer to the current compile buffer
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthstod ( S>D )
//
// C prototype:
//  void dg_forthstod (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:
//  ( n -- d )
// 
// Datastack in:
//  n               single signed integer (64 bit) to be extended to double signed 
//                   integer
//
// Datastack out:
//  d               double signed integer (128 bit lo hi)
//                                                              
// Action:
//  extends single signed integer to double signed integer 
//
// Forth standard:
//  6.1.2170
//
// Failure cases:
//  error popping data stack
//  error pushing double number to data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthsign ( SIGN )
//
// C prototype:
//  void dg_forthsign (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:
//  ( n -- )
// 
// Datastack in:
//  n               number to check for sign (64 bit)
//
// Pad in:
//  "number$"       character array of 8 bit characters
// 
// Pad out:
//  "-number$"                   if n was negative
//  or "number$"                 if n was positive
//                                                                
// Action:
//  checks to see if n is negative and if it is, a '-' character is inserted at the 
//   beginning of the pictured numeric output string currently under construction 
//   in the pad buffer
//
// Forth standard:
//  6.1.2210
//
// Handling of ambiguous conditions:
//  If SIGN is used outside a delimited number conversion, this routine still works
//   the same and inserts a '-' character at the beginning of the pad buffer if needed.
//
// Failure cases:
//  error popping data stack
//  error calling hold
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthsmslashrem ( SM/REM )
//
// C prototype:
//  void dg_forthsmslashrem (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:
//  ( d1 n1 -- n2 n3 )
//
// Datastack in:
//  d1              double signed integer to be divided (128 bit lo hi top number)
//  n1              single signed integer used to divide (64 bit bottom number)
//
// Datastack out:
//  n2              single signed integer remainder (64 bit) 
//  n3              single signed integer symmetric quotient (64 bit)
//                                                              
// Action:
//  divides d1 by n1 giving n3 remainder n2
//  if d1 and n1 have opposite signs, symmetric rounding rules apply 
//
// Handling of ambiguous conditions:
//  If n2 is 0 and n1 is positive, then n3 = remainder = most positive INT64 
//   (0x7FFFFFFFFFFFFFFF)
//  If n2 is 0 and n1 is negative, then n3 = remainder = most negative INT64 
//   (0x8000000000000000)
//  If quotient is positive and greater than largest positive INT64, then
//   n3 = remainder = most positive INT64 (0x7FFFFFFFFFFFFFFF)
//  If quotient is negative and greater than largest negative INT64, then
//   n3 = remainder = most negative INT64 (0x8000000000000000)
//  Uses symmetric division for oppositely signed values
//
// Forth standard:
//  6.1.2214
//
// Failure cases:
//  error getting pointer to the datastack
//  d1 or n1 is missing from the data stack
//
// Note:
//   in the event of overflow or divide by 0, the largest signed integer is returned
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthsource ( SOURCE )
//
// C prototype:
//  void dg_forthsource (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:
//  ( -- c-addr u )
//
// Datastack out:
//  c-addr                        address of current input buffer
//  u                             number of characters in current input buffer (64 bit)
//                                                              
// Action:
//  pushes address and length of current input buffer to the data stack
//
// Note:
//  I wasn't sure if this is supposed to return the entire buffer, or only the remainder 
//   after >IN. I asked the standards people and it's supposed to return the entire
//   buffer, except the buffer is only supposed to represent one line of whatever it is
//   you are using.
//  This implementation returns the length of the entire buffer, and if it represents a
//   file, a pointer to the start of and the length of the entire file is returned.
//   (8/17/2020)
//  
//
// Forth standard:
//  6.1.2216
//
// Failure cases:
//  error getting the current input buffer id
//  error getting the pointer to the current input buffer
//  error pushing the pointer to the current input buffer to the data stack
//  error pushing the length of the current input buffer to the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthspace ( SPACE )
//
// C prototype:
//  void dg_forthspace (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:
//  Displays one space
//
// Forth standard:
//  6.1.2220
//
// Failure cases:
//  OS i/o error
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthspaces ( SPACES )
//
// C prototype:
//  void dg_forthspaces (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:
//  ( n -- )
// 
// Data stack in:
//  n                             number of spaces to display, if n is > 0 (64 bit)
//                                                              
// Action:
//  Displays n spaces if n is greater than 0
//
// Forth standard:
//  6.1.2230
//
// Failure cases:
//  error popping n from the data stack
//  error displaying a space
//  
// //////////////////////////////////////////////////////////////////////////////////////        
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthstate ( STATE )
//
// C prototype:
//  void dg_forthstate (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:
//  ( -- a-addr )
// 
// Data stack out:
//  a-addr                        64 bit pointer to the current interpret state 
//                                 variable
//                                                              
// Action:
//  pushes pointer to state variable onto the stack
//
// Forth standard:
//  6.1.2250
//
// Failure cases:
//  error getting pointer to the state variable
//  error pushing the pointer to the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthswap ( SWAP )
//
// C prototype:
//  void dg_forthswap(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:
//  ( n1 n2 -- n2 n1 )
// 
// Data stack in:
//  n1 n2                         integers to swap (64 bit)
//
// Data stack out:
//  n2 n1                         swapped integers
//                                                              
// Action:
//  Exchanges the position of the top two integers on the data stack
//
// Forth standard:
//  6.1.2260
//
// Failure cases:
//  error getting pointer to the data stack
//  not enough integers on the data stack to do the swap
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forththen ( THEN THEN, )
//
// C prototype:
//  void dg_forththen (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:
//  ( ifoffset -- )
//
// Data stack in:
//  ifoffset                      next unused byte in current compile buffer from 
//                                 an IF
//                     
// Action:
//  resolves an unfinished branch from an IF 
//
// Forth standard:
//  6.1.2270
//
// NOTE:
//  This code assumes the current compile buffer wasn't changed since IF was done.
//
// Failure cases:
//  error getting current compile buffer id
//  error getting a pointer to the current compile buffer
//  error popping the branch resolution offset from the data stack
//  branch resolution offset is past the end of the buffer
//  branch resolution offset is too close to the beginning of the buffer
//  branch opcode missing at branch resolution offset
//  branch displacement at branch resolution offset is not 0
//  branch displacement is too far, greater or equal to 2 gigs
//
// Changes to make:
//  Need to check current compile buffer against the one for the last :
//  Need to check offset against offset for beginning of :
//  Consider having a separate stack for branch offsets if it isn't against the 
//   standard
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthtype ( TYPE )
//
// C prototype:
//  void dg_forthtype (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:
//  ( c-addr n -- )
// 
// Data stack in:
//  c-addr                        start address of a string
//  n                             signed length of the string (64 bit)
//                                                              
// Action:
//  if n is greater than 0, this displays the character string specified by c-addr n
//
// Note:
//  if n is 0 nothing happens. (Changed for v5.3 2022 May 5)
//
// Forth standard:
//  6.1.2310
//
// Failure cases:
//  error getting pointer to the data stack
//  c-addr or u missing from the data stack
//  process doesn't own all the memory in the string
//  error sending character to the display
//  u is less than 0
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthudot ( U. )
//
// C prototype:
//  void dg_forthudot (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:
//  ( u -- )
// 
// Data stack in:
//  u                             unsigned integer to convert and display (64 bit)
//                                                              
// Action:
//  converts u to a character string representation and displays in the Forth free 
//   field format
//
// Forth standard:
//  6.1.2320
//
// Failure cases:
//  error calling <#
//  error calline #S
//  error calling #>
//  error calling TYPE
//  error calling SPACE
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthulessthan ( U< )
//
// C prototype:
//  void dg_forthulessthan (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:
//  ( u1 u2 -- flag )
// 
// Datastack in:
//  u1 u2                         unsigned integers to compare (64 bit)
//
// Datastack out:
//  flag                          u1 and u2 are replaced with a flag based on the 
//                                 comparison (64 bit)
//                                                              
// Action:
//  u1 and u2 are removed from the stack and a flag is push on
//  if u1 is less than u2, the flag is Forth true (-1) otherwise it is Forth false (0)
//
// Forth standard:
//  6.1.2340
//
// Failure cases:
//  error getting pointer to the datastack
//  u1 or u2 is missing from the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////     
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthumstar ( UM* )
//
// C prototype:
//  void dg_forthumstar (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:
//  ( u1 u2 -- ud )
//
// Data stack in:
//  u1                            first UINT64 to multiply (64 bit)
//  u2                            second UINT64 to multiply (64 bit)
// 
// Data stack out:
//  ud ( -- udlo udhi )           unsigned double integer result of the unsigned 
//                                 multiply (128bit 64lo 64hi)
//                                                              
// Action:
//  ud = u1 * u2
//
// Forth standard:
//  6.1.2360
//
// Failure cases:
//  error getting pointer to the data stack
//  n1 or n2 is missing from the datastack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthumslashmod ( UM/MOD )
//
// C prototype:
//  void dg_forthumslashmod (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:
//  ( ud u1 -- u2 u3 )
// 
// Datastack in:
//  ud              double UINT64 to be divided (128 bit lo hi top number)
//  u1              single UINT64 used to divide (128 bit bottom number)
//
// Datastack out:
//  u2              single UINT64 remainder (64 bit)
//  u3              single UINT64 quotient (64 bit)
//                                                              
// Action:
//  divides ud by u1 giving u3 remainder u2 
//
// Forth standard:
//  6.1.2370
//
// Handling of ambiguous conditions:
//  If n2 is 0 then n3 = remainder = most positive UINT64 (0xFFFFFFFFFFFFFFFF)
//  If quotient is greater than largest positive UINT64, then
//   n3 = remainder = most positive UINT64 (0xFFFFFFFFFFFFFFFF)
//
// Failure cases:
//  error getting pointer to the data stack
//  ud or u1 is missing from the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthunloop ( UNLOOP )
//
// C prototype:
//  void dg_forthunloop (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:
//  ( limit index -rstack- )
// 
// Rstack in:
//  limit index                   innermost DO loop-sys (64 bit limit, 64 bit index)
//                     
// Action:
//  Drops the innermost DO loop index and limit from the rstack
//
// Forth standard:
//  6.1.2380
//
// Handling of ambiguous conditions:
//  If the loop control parameters are not available, dg_rstackunderflowerror is 
//   pushed to the error stack.
// 
// Failure cases:
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthuntil ( UNTIL )
//
// C prototype:
//  void dg_forthuntil (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:
//  ( beginoffset -- )
//
// Data stack in:
//  beginoffset                   offset in current compile buffer from BEGIN (64 bit)
//                     
// Action:
//  compiles code to check for a 0 on the data stack, and compiles a resolved branch 
//   that is taken if a 0 is found the compiled code doesn't check for an error while 
//   popping the data stack
//
// Forth standard:
//  6.1.2390
//
// Failure cases:
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthvariable ( VARIABLE )
//
// C prototype:
//  void dg_forthvariable (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" )
//  ( -currentnewvariablebuffer- +sizeofUINT64 )
//  
// Current input buffer's current offset in:
//  "<delimiters>word<delimiters>morestuff" 
//
// Current input buffer's current offset out:
//  "<delimiters>morestuff"          
// 
// Current data space buffer in:
//  previously allocated variables
// 
// Current data space buffer out:
//  previously allocated variables + a new variable of one address cell size 
//   (sizeof UINT64)
//
// Forth standard:
//  6.1.2410
//                                                          
// Action:
//  moves the current offset pointer for the current input buffer to the character 
//   after the next word or to the end of the buffer if no word is found
//  creates a new definition in the current vocabulary that pushes the address of  
//   a variable onto the data stack when the process is in execute mode
//  and compiles code that calculates the address from the variable's bufferid and 
//   offset and pushes it onto the data stack when the process is in compile mode
//  the address of the variable used is the address of the next unused byte in the 
//   current data space buffer
//  then this routine allocates one cell size worth of memory (4 bytes) in the data 
//   space buffer (current new variable buffer)
//
// Note
//  Please see CREATE for a discussion on the life of the pointer to the VARIABLE
//   
// Failure cases:
//  error calling CREATE
//  error getting the current new variable buffer id
//  error growing the current new variable buffer
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthwhile ( WHILE )
//
// C prototype:
//  void dg_forthwhile (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:
//  ( beginoffset -- whileoffset beginoffset )
// 
// Data stack in:
//  beginoffset                   length of current compile buffer at time of last 
//                                 BEGIN
//
// Data stack out:
//  whileoffset                   current length of current compile buffer
//  beginoffset                   length of current compile buffer at time of last BEGIN
//
// Forth standard:
//  6.1.2430
//                     
// Action:
//  compiles code to check for a 0 on the data stack, and compiles an unresolved
//   branch that is taken if a 0 is found the compiled code doesn't check for an 
//   error while popping the data stack
//
// Failure cases:
//  error doing IF
//  error doing SWAP
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthword ( WORD )
//
// C prototype:
//  void dg_forthword (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:
//  ( "<chars>word<char>morestuff" -currentinputbuffer- 
//     "<char>morestuff")
//        ( char -- c-addr )
//        ( -wordbuffer- "word" )
//            
// Current input buffer's current offset in:
//  "<chars>word<char>morestuff"                    
//
// Current input buffer's current offset out:
//  "<char>morestuff"
//
// Data stack in:
//  char                         UINT64 representation of 8 bit ascii character to 
//                                use as the delimiter for this parse operation
// Data stack out:
//  c-addr                       address of the counted string copy of the word
//                                                              
// Action:
//  current offset pointer for the current input buffer is moved by
//   skipping leading occurences of <char>
//   moving it to the next occurence of <char> after the leading <chars> 
//   or to the end of the buffer if no further occurences of <char> are found
//  if a word is found, it is copied to the word buffer and the length of the word 
//   is inserted  at the beginning to make the word a counted string and 
//   then the address of the counted string is returned
//
// Forth standard:
//  6.1.2450
//
// Note:
//  This routine is limited in many ways. You might consider using PARSE or 
//   PARSE-WORD or PARSE-NAMES instead
//
// Failure cases:
//  error popping the delimiter from the data stack
//  error getting current input buffer id
//  error getting pointer to the current input buffer
//  end of the buffer was reached before a word was found
//  word is too long (>255 characters)
//  error getting the pointer to the word buffer
//  error growing the word buffer (you shouldn't get this error because the word 
//   buffer's growby = maxsize)
//  error getting a pointer to the word buffer again (you shouldnt get this error
//   because it shouldn't move)
//  error pushing pointer to the word buffer 
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthxor ( XOR )
//
// C prototype:
//  void dg_forthxor (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:
//  ( x1 x2 -- x3 )
//
// Data stack in:
//  x1 x2                         two unsigned integers to bitwise or together (64 bit)
//
// Data stack out
//  x3                            x3 = x1 bitwiseor x2;
//                                                              
// Action:
//  bitwise ors x1 with x2, removes x1 x2 from the data stack and replaces them with 
//   the result
//
// Forth standard:
//  6.1.2490
//
// Failure cases:
//  unable to get pointer to the data stack
//  x1 or x2 missing from the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////             
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthleftbracket ( [ )
//
// C prototype:
//  void dg_forthleftbracket (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:
//  sets the script processing state to interpretting
//
// Forth standard:
//  6.1.2500
//
// Failure cases:
//  error putting state to state variable
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthbrackettick ( ['] )
//
// C prototype:
//  void dg_forthbrackettick (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>name<delimiters>morestuff"  
//     -currentinputbuffer- "<delimiters>morestuff" )
//  ( -- )
//
// Compiled code does:
//  ( -- xt )
//
// Compiled code data stack out:
//  xt                            execution token of the named word
//                                                              
// Action:
//  does ', then compiles code to push the execute token to the data stack
//
// Forth standard:
//  6.1.2510
//
// Failure cases:
//  error doing '
//  error doing LITERAL
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthbracketchar ( [CHAR] )
//
// C prototype:
//  void dg_forthbracketchar (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>name<delimiters>morestuff" 
//     -currentinputbuffer- "<delimiters>morestuff" )
//  ( -- )
//
// Compiled code does:
//  ( -- char )
//
// Compiled code data stack out:
//  char                          first character of name
//                                                   
// Action:
//  does CHAR, then compiles code to push the character (byte) to the data stack 
//   as a UINT64
//
// Forth standard:
//  6.1.2520
//
// Failure cases:
//  error doing CHAR
//  error doing LITERAL
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthrightbracket ( ] )
//
// C prototype:
//  void dg_forthrightbracket (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:
//  sets the script processing state to compiling
//
// Forth standard:
//  6.1.2540
//
// Failure cases:
//  error putting state to state variable
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthnumbertib ( #TIB )
//
// C prototype:
//  void dg_forthnumbertib (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:
//  ( -- pccbuflength )
//
// Data stack out:
//  pccbuflength                  pointer to current compile buffer length in bytes
//
// Forth standard:
//  6.2.0060
//
// Action:
//  This function returns a pointer to the in use length of the current interpret 
//   buffer.
//  This is the length from the beginning of the buffer to the end, not what
//   is left from the current interpret offset.
//
// Note:
//  Standard says this word is obsolete.
//  The standard suggests using SOURCE instead.
//
// Failure cases:
//  error getting current interpret buffer id
//  error getting pointer to the current interpret buffer and
//   a pointer to the current interpret buffer length
//  error pushing pointer to current interpret buffer length to the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////    
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthzeronotequals ( 0<> )
//
// C prototype:
//  void dg_forthzeronotequals (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:
//  ( n1 -- flag )
//            
// Data stack in:
//  n1                            signed integer (64 bit) to check for less than 0
// 
// Data stack out:
//  flag                          TRUE (-1) if not equal to 0, FALSE (0) if equal to 0
//
// Forth standard:
//  6.2.0260
//
// Action:
//  compare n1 with 0 and replace n1 with forth true if n1 is not 0 or forth false 
//   flag if n1 is 0
//
// Failure cases:
//  error getting pointer to the data stack
//  n1 is missing from the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////   
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthzerogreater ( 0> )
//
// C prototype:
//  void dg_forthzerogreater (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:
//  ( n1 -- flag )
//            
// Data stack in:
//  n1                            signed integer (64 bit) to check for greater than 0
// 
// Data stack out:
//  flag                          TRUE (-1) if greater than 0, FALSE (0) if less than 
//                                 or equal to 0
//
// Action:
//  compare n1 with 0 and replace n1 with forth true if n1 > 0 or forth false flag 
//   if n1 <= 0
//
// Forth standard:
//  6.2.0280
//
// Failure cases:
//  error getting pointer to the data stack
//  n1 is missing from the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////    
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthdotparen ( .( )
//
// C prototype:
//  void dg_forthdotparen (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:
//  ( "somestuff<right paren>morestuff" -currentinputbuffer- 
//     "morestuff" )
//        
// Current input buffer at current offset in:
//  "somestuff<right paren>morestuff"                    
//
// Current input buffer at current offset out:
//  "morestuff"
//                                                            
// Action:
//  The current offset pointer for the current input buffer is moved from it's current 
//   position to the character after the next right parenthesis character ')', the
//   next line terminator delimiter, or the end of the buffer, which ever comes first.
//  Then the skipped characters except for the end ')' or line terminator delimiter 
//   are sent to stdout.
//
// Forth standard:
//  6.2.0200
//
// Note:
//  A line terminator delimiter is one of:
//   c shorthand      ascii code    name  
//   '\n'             0x0a          <line feed>
//   '\v'             0x0b          <vertical tab>
//   '\b'             0x08          <back space>
//   '\r'             0x0c          <carriage return>
//   '\f'             0x0f          <form feed>
//
// Failure cases:
//  error getting current input buffer id
//  error getting pointer to current input buffer
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthdotr ( .R )
//
// C prototype:
//  void dg_forthdotr (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:
//  ( n fieldwidth -- )
// 
// Data stack in:
//  n                             signed integer to convert and display (64 bit)
//  fieldwidth                    minimum number of characters to use to display n
//                                                              
// Action:
//  converts n to a character string representation and displays in the Forth fixed 
//   field format. This means the string is displayed with at least fieldwidth
//   characters and is right adjusted in that field. Spaces are used for leading
//   characters in the field.
//
// Forth standard:
//  6.2.0210
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthnotequals ( <> )
//
// C prototype:
//  void dg_forthnotequals (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:
//  ( n1 n2 -- flag )
// 
// Data stack in:
//  n1 n2                         integers (64 bit) to compare
//
// Data stack out:
//  flag                          n1 and n2 are replaced with a flag
//
// Action:
//  n1 and n2 are replaced with a flag
//  flag is TRUE (-1) if n1 and n2 are not bitwise equal, FALSE (0) otherwise
//
// Forth standard:
//  6.2.0500
//                                                              
// Failure cases:
//  error getting pointer to the data stack
//  n1 or n2 missing from datastack
//  
// //////////////////////////////////////////////////////////////////////////////////////      
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthtwotor ( 2>R )
//
// C prototype:
//  void dg_forthtwotor (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:
//  ( x1 x2 -- )
//  ( -r- x1 x2 )
//
// Data stack in:
//  x1                            integer (64 bit) to move to the rstack
//  x2                            integer (64 bit) to move to the rstack
//  
// R stack out:
//  x1                            integer (64 bit) moved from data stack
//  x2                            integer (64 bit) moved from data stack
//
// Action:
//  pops two integers (64 bit) from the data stack and pushes them onto the rstack
//
// Forth standard:
//  6.2.0340
//                                                              
// Failure cases:
//  error popping the data stack
//  error pushing the return stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthtworfrom ( 2R> )
//
// C prototype:
//  void dg_forthtworfrom (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:
//  ( x1 x2 -r- )
//  ( -- x1 x2 )
//  
// Rstack In: 
//  x1                            integer (64 bit)
//  x2                            integer (64 bit)
// 
// Data Stack Out:
//  x1                            integer (64 bit)
//  x2                            integer (64 bit)
// 
// Action:
//  pops x1 and x2 from rstack and pushes them to the data stack
//
// Forth standard:
//  6.2.0410
//
// Failure cases:
//  Error popping x1 or x2 from the rstack
//  Error pushing x1 or x2 to the datastack
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthtworfetch ( 2R@ )
//
// C prototype:
//  void dg_forthtworfetch (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:
//  ( x1 x2 -r- x1 x2 )
//  ( -- x1 x2 )
//  
// Rstack In: 
//  x1                            integer (64 bit)
//  x2                            integer (64 bit)
// 
// Data Stack Out:
//  x1                            integer (64 bit)
//  x2                            integer (64 bit)
// 
// Action:
//  copies x1 and x2 from rstack and pushes them to the data stack
//
// Forth standard:
//  6.2.0415
//
// Failure cases:
//  Error copying x1 or x2 from the rstack
//  Error pushing x1 or x2 to the datastack
//
// //////////////////////////////////////////////////////////////////////////////////////
// ////////////////////////////////////////////////////////////////////////////////////// 
//
// dg_forthcolonnoname ( :NONAME )
//
// C prototype:
//  void dg_forthcolonnoname (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 colonnonamesys )
//
// Action:
//  creates a new dictionary definition header with 'NONAME' as the name of the 
//   definition.
//   the dictionary definition header has a compile type of 'execute or compile code 
//    to execute' and the data buffer id and offset points to the end of the current 
//    compile buffer
//  then sets the state of the script processor to compile
//  then compiles code to stack the current error count
//  then clears a flag so that when ; is executed it will know if a call to a safe 
//   subroutine was compiled.
//
// Forth standard:
//  6.2.0455
//
//  Note: The default safe behavior errs on the side of caution. Only compiling words
//    and words that could be used to push to the current compile buffer need to be 
//    marked as safe. Safe subroutine calls execute slower but can handle the case 
//    where the buffer they are called from relocates while they are executing.
//
// Failure cases:
//  error creating a new subroutine threaded definition
//  error setting the script processing state to compile
//  error trying to push colonsys to the data stack
//  
// ////////////////////////////////////////////////////////////////////////////////////// 
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthquerydo ( ?DO )
//
// C prototype:
//  void dg_forthquerydo (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:
//  ( -- do-sys )
//  ( -leave- do-sys ) 
//
// Compiles code that does:
//  ( index limit -- ) 
//  ( -r- limit index )
// 
// Data stack out:
//  do-sys                        current compile buffer offset of beginning of loop                             
//                                                             
// Action:
//  compiles >R >R
//  compiles code to check if the top two values on the rstack are equal and an unresolved
//   forward branch that is taken if they are equal. The after branch offset is equal to 
//   the BEGIN offset and is pushed to the leave stack 
//   (this means that if the loop indexes are equal to each other at the start of the loop,
//    the loop is not done)
//  compiles BEGIN
//
// Handling of ambiguous conditions:
//  For LOOP, index and limit are treated as UINT64s. 
//   When the index is one less than the limit, the loop exits.
//  For +LOOP, index, limit, and step size are treated as INT64s.
//   When the adding the step size to the index would make it cross or equal the
//    limit boundary, the loop exits.
//
// Forth standard:
//  6.2.0620
// 
// Failure cases:
//  error getting current compile buffer id
//  error growing the current compile buffer
//  error getting pointer to the current compile buffer
//  error doing BEGIN
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthagain ( AGAIN )
//
// C prototype:
//  void dg_forthagain (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:
//  ( beginoffset -- )
//
// Data stack in:
//  beginoffset                   offset in current compile buffer from BEGIN (64 bit)
//                     
// Action:
//  Compiles a resolved branch back to the begin offset that is always taken.
//
// Forth standard:
//  6.2.0700
//
// Failure cases:
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthcquote  ( C" )
//
// C prototype:
//  void dg_forthcquote (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:
//  ( "somestuff<quotes>morestuff" -currentinputbuffer- 
//     "morestuff" )
//
// Compiled code does:
//  ( -- c-addr )
//
// Current input buffer's current offset in:
//  "somestuff<quotes>morestuff"
//
// Current input buffer's current offset out:
//  "morestuff"
//
// Compiled code data stack out:
//  c-addr                       pointer to a length byte followed by
//                                a copy of "somestuff"
//                                                              
// Action:
//  In both compile and execute state:
//   Moves the current input buffer's current offset pointer to the next 
//    character after the next ", the character after the next line terminator
//    delimiter, or to the end of the buffer, which ever comes first. The target
//    string is the skipped characters except for the end " or line terminator
//    delimiter.
//   Then compiles code to have the RIP skip over the counted string and push the 
//    address of the counted string to the return stack. (It's a call over the counted 
//    string.) Then compiles the counted string. A counted string is a length byte 
//    followed by the string data. Then this compiles code to pop the address off of
//    the return stack and push it to the data stack. 
//   I did it this way is so that if the buffer moves after it's compiled, the address 
//    will be calculated at runtime and be valid at the time this code is executed.
//
// Forth standard:
//  6.2.0855
//
// Note:
//  A line terminator delimiter is one of:
//   c shorthand      ascii code    name  
//   '\n'             0x0a          <line feed>
//   '\v'             0x0b          <vertical tab>
//   '\b'             0x08          <back space>
//   '\r'             0x0c          <carriage return>
//   '\f'             0x0f          <form feed>
//
// Failure cases:
//  error getting the current input buffer id
//  error getting the pointer to the current input buffer
//  error getting the current compile buffer id
//  error growing the current compile buffer
//  error getting the pointer to the current compile buffer
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_fortherase ( ERASE )
//
// C prototype:
//  void dg_fortherase (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:
//  ( addr x -- )
//                                                              
// Action:
//  As long as x is greater than 0, the memory at addr for x bytes is erased.
// 
// Forth Standard:
//  6.2.1350
//
// Failure cases:
//  Error popping paramenters from data stack.
//  Process doesn't have write access to all the memory being erased.
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// ( FALSE )
//
// C prototype:
//  none, this is implemented as a constant
//
// Stack action shorthand:
//  ( -- FALSE )
//                                                              
// Action:
//  Pushes the value for FALSE to the data stack, which is a 0.
// 
// Forth Standard:
// 6.2.1485
//
// Failure cases:
//  Error pushing a 0 to the data stack.
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthhex ( HEX )
//
// C prototype:
//  void dg_forthhex (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:
//  Sets the BASE variable to 16
//
// Forth Standard:
//  6.2.1660
//
// Failure cases:
//  error putting 16 to the base variable in the data space buffer
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthnip ( NIP )
//
// C prototype:
//  void dg_forthnip (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:
//  ( x1 x2 -- x2 )
//                                                              
// Action:
//  Removes the number on the data stack under the top of the data stack.
//
// Forth Standard:
//  6.2.1930
// 
// Failure cases:
//  Error getting pointer to datastack.
//  Not enough parameters on datastack.
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthpad ( PAD )
//
// C prototype:
//  void dg_forthpad (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:
//  ( -- ppad )
//                                                              
// Action:
//  Pushes a pointer to the pad buffer onto the data stack. 
//
// Note: 
//  The pad buffer is not used by any Diaperglu words and is reserved for user use.
//
// Forth Standard: 
//  6.2.2000
// 
// Failure cases:
//  Error getting a pointer to the pad buffer.
//  Error pushing a pointer to the pad buffer onto the data stack.
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthparse ( PARSE )
//
// C prototype:
//  void dg_forthparse(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:
//  ( "string<char>morestuff" -currentinputbuffer- 
//     "morestuff" )
//  ( char -- c-addr u )
//
// Data stack in:
//  char                          end 8 bit ascii character for parse in UINT64 format
//
// Data stack out:
//  c-addr                        start address of "stuff" in current input
//                                 buffer which is the address at the current offset 
//                                 in the current input buffer
//  u                             length of "stuff" in characters (bytes) 
//                                 in the current input buffer, does not include the 
//                                 end char
//
// Action:
//  Moves the current offset pointer in the current input buffer to the character
//   after the first occurrence of <char> the first occurence of a <line 
//   terminator delimiter> or the end of the buffer, whichever comes first.
//  Then returns a pointer to the address of the current offset before it was moved
//   and the distance moved not counting the terminating <char> or <line 
//   terminator delimiter>
//  In the event end of buffer is reached first before finding <char> or a 
//   <g;line terminator delimiter>, the length returned is the remaining 
//   number of characters (bytes) in the buffer.
//
// Forth standard:
//  6.2.2008
//
// Note:
//  A line terminator delimiter is one of:
//   c shorthand      ascii code    name  
//   '\n'             0x0a          <line feed>
//   '\v'             0x0b          <vertical tab>
//   '\b'             0x08          <back space>
//   '\r'             0x0c          <carriage return>
//   '\f'             0x0f          <form feed>
//
// Failure cases:
//  Bufferhandle array head is missing
//  Could not pop char off data stack
//  Could not get the current input buffer id
//  Could not get a pointer to the current input buffer
//  (can't get an error pushing addr)
//  Could not push length to data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthlinesparse ( LINES-PARSE )
//
// C prototype:
//  void dg_forthlinesparse(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:
//  ( "string<char>morestuff" -currentinputbuffer- 
//     "morestuff" )
//  ( char -- c-addr u )
//
// Data stack in:
//  char                          end 8 bit ascii character for parse in UINT64 format
//
// Data stack out:
//  c-addr                        start address of "stuff" in current input
//                                 buffer which is the address at the current offset 
//                                 in the current input buffer
//  u                             length of "stuff" in characters (bytes) 
//                                 in the current input buffer, does not include the 
//                                 end char
//
// Action:
//  Moves the current offset pointer in the current input buffer to the character
//   after the first occurrence of <char> or the end of the buffer, whichever 
//   comes first.
//  Then returns a pointer to the address of the current offset before it was moved
//   and the distance moved not counting the terminating <char> 
//  In the event end of buffer is reached first before finding <char>
//   the length returned is the remaining number of characters (bytes) in the buffer.
//
// Forth standard:
//  none
//
// Failure cases:
//  Bufferhandle array head is missing
//  Could not pop char off data stack
//  Could not get the current input buffer id
//  Could not get a pointer to the current input buffer
//  (can't get an error pushing addr)
//  Could not push length to data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthparsebuffer ( PARSE-BUFFER )
//
// C prototype:
//  void dg_forthparsebuffer(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:
//  ( "string<char>morestuff" -currentinputbuffer- 
//     "morestuff" )
//  ( char -- c-addr u )
//
// Data stack in:
//  char                          end 8 bit ascii character for parse in UINT64 format
//
// Data stack out:
//  c-addr                        start address of "stuff" in current input
//                                 buffer which is the address at the current offset 
//                                 in the current input buffer
//  u                             length of "stuff" in characters (bytes) 
//                                 in the current input buffer, does not include the 
//                                 end char
//
// Action:
//  Moves the current offset pointer in the current input buffer to the character
//   after the first occurrence of <char> or the end of the buffer, 
//   whichever comes first.
//  Then returns a pointer to the address of the current offset before it was moved
//   and the distance moved not counting the terminating <char> or <line 
//   terminator delimiter>
//  In the event end of buffer is reached first before finding <char>, the 
//   length returned is the remaining number of characters (bytes) in the buffer.
//
// Forth standard:
//  6.2.2008 except for not ending parse at end of line
//
// Failure cases:
//  Bufferhandle array head is missing
//  Could not pop char off data stack
//  Could not get the current input buffer id
//  Could not get a pointer to the current input buffer
//  (can't get an error pushing addr)
//  Could not push length to data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthparseword ( PARSE-NAME PARSE-WORD )
//
// C prototype:
//  void dg_forthparseword(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" )
//  ( -- c-addr ulength )
//
// Data stack in:
//  none
//                                 
// Data stack out:
//  c-addr                        start address of word in current input buffer
//  ulength                       length of word in characters (bytes) in the 
//                                 current input buffer
//
// Action:
//  Moves the current offset pointer in the current input buffer to skip 
//   any leading white space delimiters or to the end of the buffer if that comes 
//   first to find the start of the next word.
//  Then moves the current offset pointer in the current input buffer to after the
//   next occurrence of a white space delimiter or to the end of the buffer if that 
//   comes first, to find the end of the word.
//  Then pushes a pointer to the address of the current offset at the start of the 
//   word and the length of the word in characters (bytes) onto the data stack. 
//
// Forth standard:
//  A.6.2.2008
//
// Note:
//  This routine does not skip the first character like WORD
//   because it assumes the previous word in the current input buffer was 
//   terminated with a white space delimeter.
//
//  A white space delimiter is one of:
//   c shorthand      ascii code    name 
//   ' '              0x20          <space> 
//   '\n'             0x0a          <line feed>
//   '\t'             0x09          <tab>
//   '\v'             0x0b          <vertical tab>
//   '\b'             0x08          <back space>
//   '\r'             0x0c          <carriage return>
//   '\f'             0x0f          <form feed>
//
// Failure cases:
//  Bufferhandle array head is missing
//  Could not get the current input buffer id
//  Could not get a pointer to the current input buffer
//  Word length is 0
//  Could not push addr to data stack
//  Could not push length to data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthparsewords ( PARSE-WORDS PARSE-NAMES )
//
// C prototype:
//  void dg_forthparsewords(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" |
//     "<delimiters>word<enddelimiter>morestuff"
//     -currentinputbuffer- "<delimiters>morestuff" )
//  ( uenddelimiter -- ufoundendflag c-addr ulength )
//
// Data stack in:
//  uenddelimiter                 an character (byte) that will end the parsing
//                                 in addition to the whitespace delimiter list
//                                 
// Data stack out:
//  ufoundendflag                 FORTH_TRUE if the parse ended on uenddelimiter or
//                                 the parse ended on a line terminator or
//                                 the parse reached the end of the current input
//                                 buffer 
//
//  c-addr                        start address of word in current input buffer
//  ulength                       length of word in characters (bytes) in the 
//                                 current input buffer
//
// Action:
//  Moves the current offset pointer in the current input buffer to:
//   the character after any leading delimiters 
//   or to the character after uenddelimiter 
//   or to the end of the buffer 
//   or to the character after a line terminator delimiter 
//   which ever comes first to find the start of the next word
//  If uenddelimiter was found
//   or if a line termintor was found
//   or the end of the buffer was reached then this 
//    pushes a ufoundendflag of TRUE for reaching the end, 
//    pushes the end parse offset in the current input buffer 
//    and pushes a ulength of 0 and then exits.
//  Else this moves the current offset pointer in the current input buffer to:
//   after the next occurrence of a delimiter
//   or to the character after a line terminator delimiter
//   or to the end of the buffer 
//   which ever comes first, to find the end of the word.
//  Then pushes TRUE to the data stack if 
//   uenddelimiter was found
//   or if a line terminator delimiter was found
//   or the end of the current input buffer was reached. 
//  Otherwise FALSE is pushed to the data stack.
//  Then pushes a pointer to the address of the current offset at the start of 
//   the word and the length of the word in characters (bytes) onto the data 
//   stack. The length of the word does not include the end delimiter
//
// Forth standard:
//  not yet
//
// Note:
//  This routine does not skip the first character like WORD
//   because it assumes the previous word in the current input buffer was 
//   terminated with a delimeter.
//
//  A delimiter is one of:
//   uenddelimiter 
//    or
//   c shorthand      ascii code    name 
//   ' '              0x20          <space> 
//
//  A line terminator delimiter is one of
//   c shorthand      ascii code    name
//   '\n'             0x0a          <line feed>
//   '\t'             0x09          <tab>
//   '\v'             0x0b          <vertical tab>
//   '\b'             0x08          <back space>
//   '\r'             0x0c          <carriage return>
//   '\f'             0x0f          <form feed>
//   
// Failure cases:
//  Bufferhandle array head is missing
//  Could not get the current input buffer id
//  Could not get a pointer to the current input buffer
//  Could not push c-addr to data stack
//  Could not push ulength to data stack
//  Could not push ufoundendflag to data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthlinesparsenames ( LINES-PARSE-NAMES )
//
// C prototype:
//  void dg_forthlinesparsenames(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" |
//     "<delimiters>word<enddelimiter>morestuff"
//     -currentinputbuffer- "<delimiters>morestuff" )
//  ( uenddelimiter -- ufoundendflag c-addr ulength )
//
// Data stack in:
//  uenddelimiter                 an character (byte) that will end the parsing
//                                 in addition to the whitespace delimiter list
//                                 
// Data stack out:
//  ufoundendflag                 FORTH_TRUE if the parse ended on uenddelimiter or
//                                 the parse ended on a line terminator or
//                                 the parse reached the end of the current input
//                                 buffer 
//
//  c-addr                        start address of word in current input buffer
//  ulength                       length of word in characters (bytes) in the 
//                                 current input buffer
//
// Action:
//  Moves the current offset pointer in the current input buffer to:
//   the character after any leading delimiters 
//   or to the character after uenddelimiter 
//   or to the end of the buffer  
//   which ever comes first to find the start of the next word
//  If uenddelimiter was found
//   or the end of the buffer was reached then this 
//    pushes a ufoundendflag of TRUE for reaching the end, 
//    pushes the end parse offset in the current input buffer 
//    and pushes a ulength of 0 and then exits.
//  Else this moves the current offset pointer in the current input buffer to:
//   after the next occurrence of a delimiter
//   or to the end of the buffer 
//   which ever comes first, to find the end of the word.
//  Then pushes TRUE to the data stack if 
//   uenddelimiter was found
//   or the end of the current input buffer was reached. 
//  Otherwise FALSE is pushed to the data stack.
//  Then pushes a pointer to the address of the current offset at the start of 
//   the word and the length of the word in characters (bytes) onto the data 
//   stack. The length of the word does not include the end delimiter
//
// Forth standard:
//  not yet
//
// Note:
//  This routine does not skip the first character like WORD
//   because it assumes the previous word in the current input buffer was 
//   terminated with a delimeter.
//
//  A delimiter is one of:
//   uenddelimiter 
//    or
//   c shorthand      ascii code    name 
//   ' '              0x20          <space>
//   '\n'             0x0a          <line feed>
//   '\t'             0x09          <tab>
//   '\v'             0x0b          <vertical tab>
//   '\b'             0x08          <back space>
//   '\r'             0x0c          <carriage return>
//   '\f'             0x0f          <form feed>
//
//   
// Failure cases:
//  Bufferhandle array head is missing
//  Could not get the current input buffer id
//  Could not get a pointer to the current input buffer
//  Could not push c-addr to data stack
//  Could not push ulength to data stack
//  Could not push ufoundendflag to data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthparseline ( PARSE-LINE )
//
// C prototype:
//  void dg_forthparseline(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:
//  ( "stuff<terminator>morestuff"
//     -currentinputbuffer- "morestuff" )
//  ( -- c-addr ulength )
//
// Data stack in:
//  none
//                                 
// Data stack out:
//  c-addr                        start address of line in current input buffer
//  ulength                       length of line in characters (bytes) in the 
//                                 current input buffer
//
// Action:
//  Moves the current offset pointer in the current input buffer to after the
//   next occurrence of a line terminator or to the end of the buffer if 
//   that comes first, to find the end of the line.
//  Then pushes a pointer to the address of the current offset of where this 
//   started parsing and the length of the line in characters (bytes) onto the 
//   data stack. The length of the line does not include the line terminator
//   character(s).
//  If the line is terminated with a carriage return, and the next character
//   after the carriage return is a line feed, then the current offset pointer
//   is moved to the character after the line feed.
//
//  A line terminator is one of:
//   c shorthand      ascii code    name  
//   '\n'             0x0a          <line feed>
//   '\v'             0x0b          <vertical tab>
//   '\b'             0x08          <back space>
//   '\r'             0x0c          <carriage return>
//   '\f'             0x0f          <form feed>
//
//  or 
//   '\r\n'           0x0c 0x0a     <carriage return><line feed>
//
// Failure cases:
//  Bufferhandle array head is missing
//  Could not get the current input buffer id
//  Could not get a pointer to the current input buffer
//  Could not push addr to data stack
//  Could not push length to data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthpick ( PICK )
//
// C prototype:
//  void dg_forthpick(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:
//  ( nidx ... n2 n1 n0 idx -- nidx ... n2 n1 n0 nidx )
// 
// Datastack in:
//  n2 n1 n0 idx                  integers (64 bit)
//
// Datastack out:
//  n2 n1 n0 nidx
//                                                              
// Action:
//  Removes idx from the data stack
//  Pushes the integer at idx away from the top of the data stack to the top of the 
//   data stack
//
// Forth standard:
//  6.2.2030
//
// Handling of ambiguous conditions:
//  If nidx is missing from the data stack:
//   offset = dg_datastacknoraddrmissingerror and ( DATASTACKNMISSINGERROR )
//    bufferid = DG_CORE_BUFFERID is pushed to the error stack
//  If there are not nidx parameters under nidx on the data stack:
//   offset = dg_datastackunderflowerror and ( DATASTACKUNDERFLOWERROR )
//    bufferid = DG_CORE_BUFFERID is pushed to the error stack
//   offset = dg_forthpickname and ( PICK )
//    bufferid = DG_CORE_BUFFERID is pushed to the error stack
//
// Failure cases:
//  error getting data stack depth
//  index missing from the data stack
//  error popping index from the data stack
//  data stack isn't deep enough to do the pick
//  error getting target from the data stack
//  error pushing the target to the top of the data stack
//
// Future improvement:
//  change routine to get a pointer to the data stack and work from there
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthroll ( ROLL )
//
// C prototype:
//  void dg_forthroll(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:
//  ( nidx nidx-1 ... n2 n1 n0 idx -- nidx-1 ... n2 n1 n0 nidx )
// 
// Datastack in:
//  nidx nidx-1 ... n2 n1 n0 idx                  integers (64 bit)
//
// Datastack out:
//  nidx-1 ... n2 n1 n0 nidx
//                                                              
// Action:
//  Removes idx from the data stack
//  Removes the integer at idx away from the top of the data stack 
//   and pushes it to the top of the data stack
//
// Forth standard:
//  6.2.2150
//
// Handling of ambiguous conditions:
//
// Failure cases:
//  error getting pointer to the data stack
//  idx missing from the data stack
//  not enough parameters on data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthtib ( TIB )
//
// C prototype:
//  void dg_forthtib(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:
//  ( -- pccbuf )
//
// Datastack out:
//  pccbuf                        pointer to current compile buffer
//                                                              
// Action:
//  Pushes a pointer to the current compile buffer to the data stack.
//
// Forth standard:
//  6.2.2290
//
// Note:
//  The standard says this word is obsolete.
//  The standard suggests using the word SOURCE
//
// Failure cases:
//  error getting current compile buffer id
//  error getting pointer to current compile buffer
//  error pushing current compile buffer pointer to the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthto ( TO )
//
// C prototype:
//  void dg_forthto (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>name<delimiters>morestuff" 
//     -currentinputbuffer- 
//     "morestuff" )
//                                                              
// Compile time action:
//  Parses the next name in the current interpret buffer.
//  Then searches the current search order for the name.
//  If the name is not found an error is pushed to the data stack.
//  If the name is found, the compile type of the found word is examined.
//  If the compile type is VARIABLE the variable is compiled normally and
//   a store is compiled. This means for words of type VARIABLE, TO variablename
//   is equivalent to variablename !
//  If the compile type is a local created with { then code is compiled to pop
//   the data stack and put the popped value into the local on the return stack.
//  If the compile type is a local created with LOCALS| then code is compiled to
//   pop the data stack and put the popped value in the local on the local stack.
//  If the compile type is for a word created with VALUE then code is compiled to
//   pop the data stack and put the popped uint64 into the VALUE's data.
//  If the compile type is for a word created with FVALUE then code is compiled to
//   pop the data stack and put the popped float64 into the FVALUE's data.
//  If the compile type is for a word created with 2VALUE then code is compiled to
//   pop the data stack and put the popped uint128 into the 2VALUE's data.
//
// Examples:
// VARIABLE x
// : t 5 TO X ; ( same as 5 X ! )
//
// : t2 LOCALS| y | 8 TO y ;
//
// : t3 { z } 9 TO z ; 
//
// 99 VALUE x1
// 88 TO x1
// : t4 77 TO x1 ;
//
// 2.0E7 FVALUE x2
// 3.0E1 TO x2
// : t5 7.3E3 TO x2 ;
//
// 11 22 2VALUE x3
// 33 44 TO x3
// : t6 55 66 TO x3 ;
//     
// Forth Standard:
//  6.2.2295
//
// Failure cases:
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// ( TRUE )
//
// C prototype:
//  none, this is implemented as a constant
//
// Stack action shorthand:
//  ( -- TRUE )
//                                                              
// Action:
//  Pushes the value for TRUE to the data stack, which is a -1.
// 
// Forth Standard:
// 6.2.2298
//
// Failure cases:
//  Error pushing a -1 to the data stack.
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthtuck ( TUCK )
//
// C prototype:
//  void dg_forthtuck(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:
//  ( n1 n2 -- n2 n1 n2 )
// 
// Datastack in:
//  n2 n1                        integers (64 bit)
//
// Datastack out:
//  n2 n1 n2                     integers (64 bit) 
//                                                              
// Action:
//  Inserts a copy of the top item on the data stack just below the item 1 away from the
//   top of the data stack.
//
// Forth standard:
//  6.2.2300
//
// Failure cases:
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthugreaterthan ( U> )
//
// C prototype:
//  void dg_forthulessthan (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:
//  ( u1 u2 -- flag )
// 
// Datastack in:
//  u1 u2                         unsigned integers to compare (64 bit)
//
// Datastack out:
//  flag                          u1 and u2 are replaced with a flag based on the 
//                                 comparison (64 bit)
//                                                              
// Action:
//  u1 and u2 are removed from the stack and a flag is push on
//  if u1 is less than u2, the flag is Forth true (-1) otherwise it is Forth false (0)
//
// Forth standard:
//  6.2.2350
//
// Failure cases:
//  error getting pointer to the datastack
//  u1 or u2 is missing from the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////     
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthvalue ( VALUE )
//
// C prototype:
//  void dg_forthvalue (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" )
//  ( -currentnewvariablebuffer- +sizeofUINT64 )
//  ( u -- )
//  
// Current input buffer's current offset in:
//  "<delimiters>word<delimiters>morestuff" 
//
// Current input buffer's current offset out:
//  "<delimiters>morestuff"          
// 
// Current data space buffer in:
//  previously allocated variables
// 
// Current data space buffer out:
//  previously allocated variables + a new variable of one address cell size 
//   (sizeof UINT64)
//
// Stack action of the created word
//  ( -- u )
//
// Forth standard:
//  6.2.2405
//                                                          
// Action:
//  moves the current offset pointer for the current input buffer to the character 
//   after the next word or to the end of the buffer if no word is found
//  creates a new definition in the current vocabulary that pushes the uint64 value
//   at an offset in the current data space buffer to the data stack when the process 
//   is in execute mode
//  and compiles code that calculates the address from the variable's bufferid and 
//   offset and pushes the uint64 value at that address when the process is in 
//   compile mode
//  the offset the value uses is the offset of the next unused byte in the 
//   current data space buffer
//  then this routine allocates one cell size worth of memory (8 bytes) in the data 
//   space buffer (current new variable buffer) and puts the uint64 value u into it
//
// Example:
//  37 VALUE x
//  x ( -- 37 )
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthlinecomment ( #! // \ )
//
// C prototype:
//  void dg_forthlinecomment (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:
//  ( "string<char>morestuff" -currentinputbuffer- 
//     "morestuff" )
//  ( char -- addr length )
//
// Action:
//   skips all characters up to a line termination character
// 
// Note:
//  // is an immediate word which means you can use it to put line 
//   comments in : routines
//  \ is also an immediate word
//  #! is not an immediate word 
//
// Failure cases:
//  error popping the character from the data stack
//  error getting the current input buffer
//  error getting the pointer to the current input buffer
//  error pushing to the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////