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   DiaperGlu Words dg_howhlistswork NEW-HLIST FREE-HLIST PRUNE-ELEMENT FREE-ELEMENT NEW-ELEMENT GET-ELEMENT-NAME$ GET-ELEMENT-VALUE$ SET-ELEMENT-VALUE$ GET-ELEMENT-NEWEST-CHILD GET-ELEMENT-OLDEST-CHILD GET-ELEMENT-OLDER-SIBLING GET-ELEMENT-NEWER-SIBLING SET-ELEMENT-PARENT GET-ELEMENT-PARENT FIND-CLOSEST-ELEMENT-CHILD-BY-NAME$ FIND-ELEMENT-CHILD-BY-NAME$ ELEMENT>DGLUML$ GET-ELEMENT-NUMBER-OF-SORTED-CHILDREN FIND-ELEMENT-CHILD-N PACK-HLIST UNPACK-HLIST >EH EH> DROPEH EH EH[TOP] DUPEH E>EH[TOP] EH-NEW-ELEMENT EH-NEW-ELEMENT>EH NAME$>VALUE$ ?NAME$>VALUE$ EH-?NAME$>VALUE$ NAME$>VALUE EH-NAME$>VALUE$ EH-NAME$>VALUE NAMEW>VALUE$ NAMEW>VALUE EH-NAMEW>VALUE$ EH-NAMEW>VALUE EH-OHERE-W>NEW-ELEMENT EH. EH[ND]. EH[1D]. SYMBOL-ENUM< OSYMBOL-CODE-IMPORTS,< NEW-FLAT-OSYMBOL-BUF FREE-FLAT-OSYMBOL-BUF SYMBOL OSYMBOL OSYMBOL-IMPORT EH-NEW-ELEMENTS NEW-HLISTWITHROOT>EH QUERY-POST-EH-NEW-ELEMENTS
// //////////////////////////////////////////////////////////////////////////////////////
//
// How heirarchical lists work
//
// A hierarchical list is an array of name string value string pairs where each
//  element in the array can have another element as it's parent. Elements
//  with the same parent are sorted by their name strings and at the same time
//  arranged in the order that they were added to the parent. This means Diaperglu 
//  maintains two orderings for an element's children:
//    A linked list of the order in which they were added,
//    and an array of the element ids of the children sorted by their name strings.
//
// If two elements with the same name string are added to a parent, and you
//  try to find the element with the name string for that parent, the find
//  function returns the index of the one added last.
//
// This means you can use hierarchical lists to represent various data
//  structures such as hashes, symbol lists, word lists, and with a bit of work,
//  even XML. To do XML you have to figure out a way to deal with when there
//  are tags in the middle with text on both sides... since this implementation
//  only has one value string for each name string.
//
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthnewhlist ( NEW-HLIST )
//
// C prototype:
//   void dg_forthnewhlist (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:
//   ( -- hlistid )
//                                                            
// Action:
//  Creates a new empty hierarchical list and returns the new hierarchical list's id
//    on the data stack.
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthfreehlist ( FREE-HLIST )
//
// C prototype:
//   void dg_forthfreehlist (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:
//   ( hlistid -- )
//                                                            
// Action:
//  Frees a previously created hierarchical list.
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthprunehlistelement ( PRUNE-ELEMENT )
//
// C prototype:
//   void dg_forthprunehlistelement(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:
//   ( elementid hlistid -- )
//                                                            
// Action:
//  Frees the children of a hierarchical list element.
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthfreehlistelement ( FREE-ELEMENT )
//
// C prototype:
//   void dg_forthfreehlistelement(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:
//   ( elementid hlistid -- )
//                                                            
// Action:
//  Frees a previously created hierarchical list element along with all it's children.
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthnewhlistelement ( NEW-ELEMENT )
//
// C prototype:
//   void dg_forthnewhlistelement (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:
//  ( parentelementid hlistid -- elementid )
//  ( value$ name$ -$- )
//                                                            
// Action:
//  Create a new hlist element in hlist hlistid as a child element under the parent element
//    parentelementid. This new element will have the name value pair name$ and value$.
//    This new child becomes the 'newest' child of the parent element in the parent's list
//    of how recently the element was added as a child of the parent. 
//    It's also sorted into the parent's sorted list of children according to the name$.
//    The name$ is treated as an unsigned byte array and the bytes are compared in order from
//    lowest byte in memory to the highest against all the other children in the sorted list.  
//
// Note:
//  If parentelementid is DG_ENDOFLIST (-1) then the element has no parent and is a 
//   top level element.
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthgethlistelementnom ( GET-ELEMENT-NAME$ )
//
// C prototype:
//   void dg_forthgethlistelementnom (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:
//  ( elementid hlistid -- )
//  ( -$- name$ )
//                                                            
// Action:
//  Gets the name string of the indicated hlist element and pushes it to the string stack.  
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthgethlistelementvalue ( GET-ELEMENT-VALUE$ )
//
// C prototype:
//   void dg_forthgethlistelementvalue (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:
//  ( elementid hlistid -- )
//  ( -$- value$ )
//                                                            
// Action:
//  Gets the value string of the indicated hlist element and pushes it to the string stack.  
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthsethlistelementvalue ( SET-ELEMENT-VALUE$ )
//
// C prototype:
//   void dg_forthsethlistelementvalue (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:
//  ( elementid hlistid -- )
//  ( value$ -$- )
//                                                            
// Action:
//  Pops a string from the string stack and replaces the indicated hlist element's 
//   value string with it.  
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthgethlistnewestchild ( GET-ELEMENT-NEWEST-CHILD )
//
// C prototype:
//   void dg_forthgethlistnewestchild (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:
//  ( parentelementid hlistid -- newestchildid )
//                                                            
// Action:
//  Gets the childid of child element most recently added to the indicated hlist 
//   element.  
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthgethlistoldestchild ( GET-ELEMENT-OLDEST-CHILD )
//
// C prototype:
//   void dg_forthgethlistoldestchild (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:
//  ( parentelementid hlistid -- oldestchildid )
//                                                            
// Action:
//  Gets the childid of child element first added to the indicated hlist element
//   that is still a child of the indicated hlist element.
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthgethlistoldersibling ( GET-ELEMENT-OLDER-SIBLING )
//
// C prototype:
//   void dg_forthgethlistoldersibling (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:
//  ( childelementid hlistid -- nextoldersiblingid )
//                                                            
// Action:
//  If parent of the indicated element has another child that was added to the parent 
//   before the indicated child element, this routine returns the element id of the
//   child added just before this element. Otherwise this routine returns 
//   DG_ENDOFWORDLIST (-1)
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthgethlistnewersibling ( GET-ELEMENT-NEWER-SIBLING )
//
// C prototype:
//   void dg_forthgethlistnewersibling (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:
//  ( childelementid hlistid -- nextoldersiblingid )
//                                                            
// Action:
//  If parent of the indicated element has another child that was added to the parent 
//   more recently than the indicated child element, this routine returns the element 
//   id of the child added just after this element. Otherwise this routine returns 
//   DG_ENDOFWORDLIST (-1)
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthchangehlistparent ( SET-ELEMENT-PARENT )
//
// C prototype:
//   void dg_forthchangehlistparent (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:
//  ( newparentelementid childelementid hlistid -- )
//                                                            
// Action:
//  Removes the indicated child element from it's current parent and adds it as a child
//   of the indicated new parent. This child becomes the most recently added child of 
//   the new parent and is also sorted into the new parent's list of sorted children by 
//   name$.
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthgethlistparent ( GET-ELEMENT-PARENT )
//
// C prototype:
//   void dg_forthgethlistparent (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:
//  ( newparentelementid childelementid hlistid -- )
//                                                            
// Action:
//  Returns parent elemend id of the indicated child element.
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthfindclosesthlistchild ( FIND-CLOSEST-ELEMENT-CHILD-BY-NAME$ )
//
// C prototype:
//   void dg_forthfindclosesthlistchild (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:
// ( parentelementid hlistid -- closestchildid sortkeyindexafterlastmatch compareflag )
// ( name$ -$- )
//                                                            
// Action:
//  Searches the sorted child list of the indicated parent element for the child element 
//   have the next greater or equal name string as the indicated name string.
//   If the found child's name string matches, the compare flag's value is 0, and the
//    closestchildid is the element id of the most recently added child that has the 
//    same name string.
//   If the found child's name string does not match, the compare flag is 1 (for greater 
//    than), and the closestchildid is the elemend id of the child with the name string 
//    just less than. sortkeyindexafterlastmatch is the index in the parent's sorted 
//    list of child element ids of the child element with the last matching name string 
//    or the first one greater.
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthfindhlistchild ( FIND-ELEMENT-CHILD-BY-NAME$ )
//
// C prototype:
//   void dg_forthfindhlistchild (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:
// ( parentelementid hlistid -- childid )
// ( name$ -$- )
//                                                            
// Action:
//  Searches the sorted child list of the indicated parent element for the child 
//   element most recently added that has the same name string. If found the childid 
//   of the matching element is returned. Otherwise DG_ENDOFWORDLIST (-1) is returned.
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthhlisttoxmlstring ( ELEMENT>DGLUML$ )
//
// C prototype:
//   void dg_forthhlisttoxmlstring (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:
// ( indentationstepsize rootelementid hlistid -- )
// ( -$- dgluml$ )
//                                                            
// Action:
//  Converts the indicated element and all it's children into an xml like string. The 
//   names and values are converted to an url form encoded string. In the event an 
//   element has both a value and an element, the element goes immediately after 
//   <name$>, then the children come, each on a separate line. Each nesting level
//   of children is indented indentationstepsize.
//  So for an indentionstepsize of 2 it looks like this:
//   <rootelementname$>rootelementvalue$
//     <1stchildname$>1stchildvalue$</1stchildname$>
//     <2ndchildname$>2ndchildvalue$</2ndchildname$>
//   </rootelementname$>
//
//  The value strings are url encoded, which also encodes and carriage returns or line
//   feeds in the value string.
//  This way you can determine the true end of the value string when a parent has both 
//   a value string and children by looking for the first carriage return or line feed. 
//   < and > in the value strings are also url encoded so in the event there is
//   no children, you can just look for the next < as the end of the value string.
//   The DGLUML$>ELEMENT routine when I write it will probably consider any 
//   character that should have been url encoded as a terminator for the value string. 
//     
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthgethowmanyhlistkids ( GET-ELEMENT-NUMBER-OF-SORTED-CHILDREN )
//
// C prototype:
//   void dg_forthgethowmanyhlistkids(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:
// ( parentelementid hlistid -- numberofchildren )
//                                                            
// Action:
//  Returns the number of children in the indicated parent element's list of sorted 
//   children.
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthgethlistsortedchildn ( FIND-ELEMENT-CHILD-N )
//
// C prototype:
//   void dg_forthgethlistsortedchildn(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 parentelementid hlistid -- childelementid )
//                                                            
// Action:
//  Returns the element id of the nth child in the indicated parent element's list of
//   sorted children. n is a 0 based index.
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthpackhlist ( PACK-HLIST )
//
// C prototype:
//   void dg_forthpackhlist(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:
// ( hlistid -- packedbufferid )
//                                                            
// Action:
//  Packs the hlist into one new buffer. The hlist is unchanged.
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthunpackhlist ( UNPACK-HLIST )
//
// C prototype:
//   void dg_forthunpackhlist(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:
//  ( packedbufferid -- hlistid )
//                                                            
// Action:
//  Unpacks the the buffer into a new hlist. The buffer is changed.
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthtoeh ( >EH )
//
// C prototype:
//   void dg_forthtoeh(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:
//  ( elementid hlistid -- ) ( -EH- elementid hlistid )
//                                                            
// Action:
//  Pops two UINT64s from the data stack and pushes the
//   two UINT64s to the EH stack keeping the order the same.
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthehfrom ( EH> )
//
// C prototype:
//   void dg_forthehfrom(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:
//  ( elementid hlistid -EH- ) ( -- elementid hlistid )
//                                                            
// Action:
//  Pops two UINT64s from the EH stack and pushes the
//   two UINT64s to the data stack keeping the order the same.
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthdropeh ( DROPEH )
//
// C prototype:
//   void dg_forthdropeh(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:
//  ( elementid hlistid -EH- )
//                                                            
// Action:
//  Pops two UINT64s from the EH stack and throws them away.
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthehtop ( EH[TOP] EH )
//
// C prototype:
//   void dg_forthehtop(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:
//  ( elementid hlistid -EH- elementid hlistid ) ( -- elementid hlistid )
//                                                            
// Action:
//  Copies the top two UINT64s from the EH stack amd
//   pushes them onto the data stack in the same order.
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthdupeh ( DUPEH )
//
// C prototype:
//   void dg_forthdupeh(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:
//  ( elementid hlistid -EH- elementid hlistid elementid hlistid )
//                                                            
// Action:
//  Pushes a copy of the top element id hlist id pair on the EH stack
//   onto the top of the EH stack.
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthetoehtop ( E>EH[TOP] )
//
// C prototype:
//   void dg_forthetoehtop(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:
//  ( newelementid -- )
//  ( elementid hlistid -EH- newelementid hlistid )
//                                                            
// Action:
//  Pops a new element id off of the data stack.
//  The copies the new element id to the top element id hlist id pair
//   on the EH stack.
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthehnewelement ( EH-NEW-ELEMENT )
//
// C prototype:
//   void dg_forthehnewelement(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:
//  ( parentelementid hlistid -EH- parentelementid hlistid )
//  ( value$ name$ -$- )
//                                                            
// Action:
//  Makes a new element using the parent element id and hlist id on the top of
//   of the EH stack and the name$ and value$ on the top of the string stack.
//   Then drops the name$ and value$ from the string stack.
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthehnewelementtoeh ( EH-NEW-ELEMENT>EH )
//
// C prototype:
//   void dg_forthehnewelementtoeh(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:
//  ( parentelementid hlistid -EH- parentelementid hlistid childelementid hlistid )
//  ( value$ name$ -$- )
//                                                            
// Action:
//  Makes a new element using the parent element id and hlist id on the top of
//   of the EH stack and the name$ and value$ on the top of the string stack.
//   The new element's element id and hlist id are pushed onto the top of the
//   EH stack, and the name$ and value$ are dropped from the string stack.
//
// Failure cases:
//
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthnamestrtovaluestr ( NAME$>VALUE$ )
//
// C prototype:
//   void dg_forthnamestrtovaluestr(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:
//  ( parentelementid hlistid -- )
//  ( name$ -$- value$ )
//                                                            
// Action:
//  Pops parentelementid and hlistid of the data stack.
//  Then finds the child element under the parent element in the hlist who's name
//   is name$. Then drops the name$ and pushes the value$ of the newest child element
//   with that name to the string stack. If the child with that name is not found
//   an error is pushed to the error stack.
//
// Failure cases:
//  A child element with a matching name string wasn't found.
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthquerynamestrtovaluestr ( ?NAME$>VALUE$ )
//
// C prototype:
//   void dg_forthquerynamestrtovaluestr(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:
//  ( parentelementid hlistid -- )
//  ( name$ -$- value$| )
//  ( -- foundflag )
//                                                            
// Action:
//  Pops parentelementid and hlistid of the data stack.
//  Then finds the child element under the parent element in the hlist who's name
//   is name$. Then drops the name$. 
//   Then, if any children with that name exist, pushes the value$ of the newest 
//   child with that name to the string stack and pushes TRUE to the data stack. 
//   If a child with that name does not exist, pushes FALSE to the data stack.
//
// Failure cases:
//  A child element with a matching name string wasn't found.
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthehquerynamestrtovaluestr ( EH-?NAME$>VALUE$ )
//
// C prototype:
//   void dg_forthehquerynamestrtovaluestr(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:
//  ( parentelementid hlistid -EH- parentelementid hlistid )
//  ( name$ -$- value$| )
//  ( -- foundflag )
//                                                            
// Action:
//  Gets parentelementid and hlistid from the top of the EH stack.
//  Then finds the child element under the parent element in the hlist who's name
//   is name$. Then drops the name$. 
//   Then, if any children with that name exist, pushes the value$ of the newest 
//   child with that name to the string stack and pushes TRUE to the data stack. 
//   If a child with that name does not exist, pushes FALSE to the data stack.
//
// Failure cases:
//  A child element with a matching name string wasn't found.
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthnamestrtovalue ( NAME$>VALUE )
//
// C prototype:
//   void dg_forthnamestrtovalue(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:
//  ( parentelementid hlistid -- value )
//  ( name$ -$- )
//                                                            
// Action:
//  Pops parentelementid and hlistid of the data stack.
//  Then finds the child element under the parent element in the hlist who's name
//   is name$. Then drops the name$ off the string stack and treats the
//   child element's value$ as a UINT64 and pushes it to the data stack.
//
// Failure cases:
//  A child element with a matching name string wasn't found.
//  The child element's value string is not long enough to hold a UINT64
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthehnamestrtovaluestr ( EH-NAME$>VALUE$ )
//
// C prototype:
//   void dg_forthehnamestrtovaluestr(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:
//  ( parentelementid hlistid -EH- parentelementid hlistid )
//  ( name$ -$- value$ )
//                                                            
// Action:
//  Uses the parentelementid and hlistid on top of the EH stack.
//  Then finds the child element under the parent element in the hlist who's name
//   is name$. Then drops the name$ and pushes the child element's value$ to the
//   string stack.
//
// Failure cases:
//  A child element with a matching name string wasn't found.
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthehnamestrtovalue ( EH-NAME$>VALUE )
//
// C prototype:
//   void dg_forthehnamestrtovalue(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:
//  ( -- value )
//  ( parentelementid hlistid -EH- parentelementid hlistid )
//  ( name$ -$- )
//                                                            
// Action:
//  Uses the parentelementid and hlistid on top of the EH stack.
//  Then finds the child element under the parent element in the hlist who's name
//   is name$. Then drops the name$ off the string stack and treats the
//   child element's value$ as a UINT64 and pushes it to the data stack.
//
// Failure cases:
//  A child element with a matching name string wasn't found.
//  The child element's value string is not long enough to hold a UINT64
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthnamewtovaluestr ( NAMEW>VALUE$ )
//
// C prototype:
//   void dg_forthnamewtovaluestr(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:
//  ( parentelementid hlistid -- )
//  ( -$- value$ )
//  ( "<delimiters>word<delimiters>morestuff" 
//     -currentinputbuffer- "<delimiters>morestuff" )
//                                                            
// Action:
//  Pops parentelementid and hlistid of the data stack.
//  Moves the current offset pointer in the current input buffer to skip 
//   any leading 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 the
//   next occurrence of a delimiter or to the end of the buffer if that comes
//   first, to find the end of the word.
//  Then finds the child element under the parent element in the hlist who's name
//   matches the parsed word. Then pushes the child element's value$ to the
//   string stack.
//
// Failure cases:
//  A child element with a matching name string wasn't found.
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthnamewtovalue ( NAMEW>VALUE )
//
// C prototype:
//   void dg_forthnamewtovalue(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:
//  ( parentelementid hlistid -- )
//  ( -- value )
//  ( "<delimiters>word<delimiters>morestuff" -currentinputbuffer- 
//     "<delimiters>morestuff" )
//                                                            
// Action:
//  Pops parentelementid and hlistid of the data stack.
//  Moves the current offset pointer in the current input buffer to skip 
//   any leading 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 the
//   next occurrence of a delimiter or to the end of the buffer if that comes
//   first, to find the end of the word.
//  Then finds the child element under the parent element in the hlist who's name
//   matches the parsed word. Then treats the child element's value$ as a UINT64
//   and pushes it to the data stack.
//
// Failure cases:
//  A child element with a matching name string wasn't found.
//  The child element's value string was not long enough to hold a UINT64.
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthehnamewtovaluestr ( EH-NAMEW>VALUE$ )
//
// C prototype:
//   void dg_forthehnamewtovaluestr(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:
//  ( parentelementid hlistid -EH- parentelementid hlistid )
//  ( -$- value$ )
//  ( "<delimiters>word<delimiters>morestuff" 
//     -currentinputbuffer- "<delimiters>morestuff" )
//                                                            
// Action:
//  Gets the parentelementid and hlistid from the top of the EH stack.
//  Moves the current offset pointer in the current input buffer to skip 
//   any leading 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 the
//   next occurrence of a delimiter or to the end of the buffer if that comes
//   first, to find the end of the word.
//  Then finds the child element under the parent element in the hlist who's name
//   matches the parsed word. Then pushes the child element's value$ to the
//   string stack.
//
// Failure cases:
//  A child element with a matching name string wasn't found.
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthehnamewtovalue ( EH-NAMEW>VALUE )
//
// C prototype:
//   void dg_forthehnamewtovalue(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:
//  ( parentelementid hlistid -EH- parentelementid hlistid )
//  ( -- value )
//  ( "<delimiters>word<delimiters>morestuff" 
//     -currentinputbuffer- "<delimiters>morestuff" )
//                                                            
// Action:
//  Gets the parentelementid and hlistid from the top of the EH stack.
//  Moves the current offset pointer in the current input buffer to skip 
//   any leading 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 the
//   next occurrence of a delimiter or to the end of the buffer if that comes
//   first, to find the end of the word.
//  Then finds the child element under the parent element in the hlist who's name
//   matches the parsed word. Then treats the child element's value$ as a UINT64
//   and pushes it to the data stack.
//
// Failure cases:
//  A child element with a matching name string wasn't found.
//  The child element's value string was not long enough to hold a UINT64.
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthehoherewtonewelement ( EH-OHERE-W>NEW-ELEMENT OSYMBOL )
//
// C prototype:
//   void dg_forthehoherewtonewelement(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:
//  ( parentelementid hlistid -EH- parentelementid hlistid )
//  ( "<delimiters>word<delimiters>morestuff" 
//     -currentinputbuffer- "<delimiters>morestuff" )
//                                                            
// Action:
//  Moves the current offset pointer in the current input buffer to skip 
//   any leading 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 the
//   next occurrence of a delimiter or to the end of the buffer if that comes
//   first, to find the end of the word.
//  Makes a new element using the parent element id and hlist id on the top of
//   of the EH stack and a name$ equal to the word parsed and a value
//   equal to the UINT64 current offset in the current compile buffer.
//
// Failure cases:
//
// Tested cases:
//   
/// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthosymbolentry ( OSYMBOL-ENTRY )
//
// C prototype:
//   void dg_forthosymbolentry(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:
//  ( parentelementid hlistid -EH- parentelementid hlistid )
//  ( "<delimiters>word<delimiters>morestuff" 
//     -currentinputbuffer- "<delimiters>morestuff" )
//                                                            
// Action:
//  Moves the current offset pointer in the current input buffer to skip 
//   any leading 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 the
//   next occurrence of a delimiter or to the end of the buffer if that comes
//   first, to find the end of the word.
//  Makes a new element using the parent element id and hlist id on the top of
//   of the EH stack and a name$ equal to the word parsed and a value
//   equal to the UINT64 current offset in the current compile buffer.
//  Then makes a child element of this new element that has the name "ENTRY"
//   and no value.
//
// Note:
//  This adds the ENTRY attribute to an export symbol. On Mac, this is ignored and the
//   symbol is treated like a regular export symbol. On Windows, this changes the
//   export symbol into an entry symbol so the linker will allow you to use it as the
//   entry point of an exe. It seems the section of a .obj file that has the /ENTRY
//   specification in it might no longer required. If so, I may remove this section
//   in the future which means you might be able to just use OSYMBOL instead of
//   OSYMBOL-ENTRY on Windows in the future. J.N. 2022 May 22.
//
// Failure cases:
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthehdot ( EH. )
//
// C prototype:
//   void dg_forthehdot(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:
//  ( parentelementid hlistid -EH- parentelementid hlistid )
//  ( "<delimiters>word<delimiters>morestuff" 
//     -currentinputbuffer- "<delimiters>morestuff" )
//                                                            
// Action:
//  Moves the current offset pointer in the current input buffer to skip 
//   any leading 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 the
//   next occurrence of a delimiter or to the end of the buffer if that comes
//   first, to find the end of the word.
//  Searches the hlist whose parent element id and hlist id on the top of the 
//   EH stack for  the child with the parsed name. If not found, a not found error 
//   is pushed to the error stack. If found, the first 8 bytes of the child's value 
//   string is assumed to be a UINT64 and is pushed to the data stack. If the 
//   child's value string is too short, an error is pushed to the data stack.
//
// Note:
//  This function uses a key$ value symbol list whose parent element id and hlist id
//   are on top of the EH stack. This will probably be the symbol list for the stuff 
//   you are currently assembling. If so, the name$ is the symbol name, and the value
//   is probably an offset in the current compile buffer.
//
// Failure cases:
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthehbracketnddot ( EH[ND]. )
//
// C prototype:
//   void dg_forthehbracketnddot(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:
//  ( parentelementidnd-1 hlistidnd-1 ... parentelementid0 hlistid0 -EH- 
//     parentelementidnd-1 hlistidnd-1 ... parentelementid0 hlistid0 )
//  ( "<delimiters>word<delimiters>morestuff" 
//     -currentinputbuffer- "<delimiters>morestuff" )
//                                                            
// Action:
//  Moves the current offset pointer in the current input buffer to skip 
//   any leading 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 the
//   next occurrence of a delimiter or to the end of the buffer if that comes
//   first, to find the end of the word.
//  Searches the hlist whose parent element id and hlist id are at depth nd (0 based)  
//   on the EH stack for the child with the parsed name. If not found, a not found 
//   error is pushed to the error stack. If found, the first 8 bytes of the child's 
//   value string is assumed to be a UINT64 and is pushed to the data stack. If the 
//   child's value string is too short, an error is pushed to the data stack.
//
// Note:
//  This function uses a key$ value symbol list whose parent element id and hlist id
//   are on the EH stack at 0 based depth nd. This will probably be the symbol list 
//   for the stuff you are currently assembling or generating links for. 
//   If so, the name$ is the symbol name, and the value is probably an offset in the 
//   current compile buffer.
//
// Failure cases:
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthehbracket1ddot ( EH[1D]. )
//
// C prototype:
//   void dg_forthehbracket1ddot(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:
//  ( parentelementid1 hlistid1 parentelementid0 hlistid0 -EH- 
//     parentelementid1 hlistid1 parentelementid0 hlistid0 )
//  ( "<delimiters>word<delimiters>morestuff" 
//     -currentinputbuffer- "<delimiters>morestuff" )
//                                                            
// Action:
//  Moves the current offset pointer in the current input buffer to skip 
//   any leading 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 the
//   next occurrence of a delimiter or to the end of the buffer if that comes
//   first, to find the end of the word.
//  Searches the hlist whose parent element id and hlist id 1 are one below the top 
//   on the EH stack for the child with the parsed name. If not found, a not found 
//   error is pushed to the error stack. If found, the first 8 bytes of the child's 
//   value string is assumed to be a UINT64 and is pushed to the data stack. 
//   If the child's value string is too short, an error is pushed to the data stack.
//
// Note:
//  This function uses a key$ value symbol list whose parent element id and hlist id
//   are on the EH stack 1 below the top. This will probably be the symbol list 
//   for the stuff you are currently generating import links for. 
//   If so, the name$ is the symbol name, and the value is probably the offset of
//   where either the run time or compile time linker will put the link value.
//
// Failure cases:
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthsymbol ( SYMBOL )
//
// C prototype:
//  void dg_forthsymbol (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:
//  ( symbolvalue -- )
//  ( elementid hlistid -EH- elementid hlistid )
//
// Data stack in:
//  symbolvalue                   UINT64 value of the new element
//
// Data stack out:
//  none
//
// EH stack in and out:
//  elementid                     current parent element id of the symbol list
//  hlistid                       current hlist id of the glu/nglu list
//
// Current input buffer's current offset in:
//  "<delimiters>word<delimiters>morestuff" 
//
// Current input buffer's current offset out:
//  "<delimiters>morestuff"
//
// Action:
//  This routine adds an element with the name string equal to the
//   next word in the input stream and value equal to the UINT64 value
//   popped off the data stack under the parent element in the hlist given
//   by the top element id hlist id pair on the EH stack.
//  Then the current input stream buffer's current offset is moved past
//   the word which was just used.
//
// Note:
//  The value string of the element is 8 bytes and is the binary value of the UINT64.
//  (This routine treats the value string as if it were a UINT64.)
//
// Failure cases:
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthehoherewtonewelement ( EH-OHERE-W>NEW-ELEMENT OSYMBOL )
//
// C prototype:
//  void dg_forthehoherewtonewelement (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:
//  ( elementid hlistid -EH- elementid hlistid )
//
// EH stack in and out:
//  elementid                     current parent element id of the symbol list
//  hlistid                       current hlist id of the glu/nglu list
//
// Current input buffer's current offset in:
//  "<delimiters>word<delimiters>morestuff" 
//
// Current input buffer's current offset out:
//  "<delimiters>morestuff"
//
// Action:
//  This routine adds an element to the hlist whose parent element id
//   and hlist id are on top of the EH stack. The name string of the added element
//   is equal to the next word in the input stream and UINT64 binary value of the
//   value string is equal to the current offset in the current compile buffer.
//  Then the current input stream buffer's current offset is moved past
//   the word which was just used.
//
// Note:
//  The value string of the element is 8 bytes and is the UINT64 binary value of the 
//   current compile buffers current offset. (This routine treats the value string as
//   if it were a UINT64.)
//
// Failure cases:
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthosymbolimport ( OSYMBOL-IMPORT )
//
// C prototype:
//  void dg_forthosymbolimport (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:
//  ( importelementid importhlistid exportelementid exporthlistid -EH- 
//     importelementid importhlistid exportelementid exporthlistid )
//
// EH stack in and out:
//  importelementid                parent element id of the import symbol list
//  importhlistid                  hlist id of the hlist holding the symbol list
//
// Current input buffer's current offset in:
//  "<delimiters>word<delimiters>morestuff" 
//
// Current input buffer's current offset out:
//  "<delimiters>morestuff"
//
// Action:
//  If needed for the operating system, this will compile an import link.
//  Then this routine adds an import to the import symbol list. To add the
//   import, this routine expects symbol list parents on top of the eh stack.
//   To add the import this routine adds an element to the hlist whose parent 
//   element id and hlist id are one below the top of the EH stack. The name 
//   string of the added element is equal to the next word in the input stream 
//   and UINT64 binary value of the value string is equal to the current offset 
//   in the current compile buffer.
//  Then the current input stream buffer's current offset is moved past
//   the word which was just used.
//
// Note:
//  The value string of the element is 8 bytes and is the UINT64 binary value of the 
//   current compile buffers current offset. (This routine treats the value string as
//   if it were a UINT64.)
//  (2022 Apr 10 J.N.) On Mac, you give the linker the offsets of 4 byte displacements
//   to adjust. The offsets are to the memory holding the 8 byte addresses of each link.
//   The linker builds the array of imported pointers for you so you don't have to worry
//   about it and it also means the linker only needs to import each symbol once at run
//   time once for your entire application. It also means you can use the import links
//   with any instruction that supports the [O] addressing mode, you just need to make
//   sure the displacement size is 4 bytes. However, only CALL, is portable to Windows.
//   Since the Mac compile time linker adds to the offsets you give it, you have to
//   sure the compiled offset is 0.
//  (2022 Apr 10 J.N.) On Win64, you give the linker the offset of 8 byte pointers.
//   But since Windows does not put the address of the target into these pointers at
//   run time and instead puts the address of a link table holding jumps to the true
//   address, this instruction compiles a branch over an 8 byte pointer and uses the 
//   offset of the pointer for the link. This also means you can only use 
//   OSYMBOL-IMPORT with CALL, at this time.
//
// Usage:
//  IMP CALL, OSYMBOL-IMPORT myimportfunctionname 
//
// Failure cases:
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthsymbolenumcurly ( SYMBOL-ENUM< )
//
// C prototype:
//  void dg_forthsymbolenumcurly (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:
//  ( stepsize startvalue parentelementid parenthlistid -- valueafterend )
//  ( "<delimiters>word1<delimiters>word2"...
//    <delimiters>wordu<delimiters>}morestuff" -currentinputbuffer- 
//     "morestuff" )
//  
// Current input buffer's current offset in:
//  "<delimiters>word1<delimiters>word2"...
//    <delimiters>wordu<delimiters>}morestuff"
//
// Current input buffer's current offset out:
//  "morestuff"          
//
// Forth standard:
//  none
//                                                          
// Action:
//  Pops the parent hlist id off the data stack.
//  Pops the element hlist id off the data stack.
//  Pops the start value off the data stack. 
//  Pops the step size off the data stack.
//  Moves the current offset pointer for the current input buffer to the character 
//   after the next > or to the end of the buffer if > is not found.
//  For each word found before the > or end of buffer, whichever come first:
//   Tries to convert the word to a number using the current BASE. 
//   For the first word of each group words that can be converted to a number, the
//    step size is set to this number.
//   For the second and all following words of the group that can be converted to
//    a number, the value is set to this number. 
//   If the word can not be converted to a number, then 
//    if it's not the first value or if the value wasn't just set,
//     the step size is added to the value. Then, this function 
//     adds a new element to the hlist whose parent is element id hlist id passed in.
//     The name$ of this new element is the word parsed. The value string of this
//     new element is set to the current value. (The value string is treated as a
//     UINT64. ) 
//   Then a new group of words is started. 
//
// Example:
//  1 6 elementid hlistid ENUM< 
//   x  
//   y  z 
//   2 w
//   3 1
//   v u>
//
//  7 is on the data stack after
//
//  x gets the value 6
//  y gets the value 7
//  z gets the value 8
//  w gets the value 10
//  v gets the value 1
//  u gets the value 4
//
// Note:
//  For this function, the value strings are treated as UINT64s. (The binary value of
//   the each UINT64 is put into the value string.)
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthosymbolcodeimportscommacurly ( OSYMBOL-CODE-IMPORTS,< )
//
// C prototype:
//  void dg_forthosymbolcodeimportscommacurly (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:
//  ( importelementid importhlistid exportelementid exporthlistid -EH- 
//     importelementid importhlistid exportelementid exporthlistid )
//
// EH stack in and out:
//  importelementid                parent element id of the import symbol list
//  importhlistid                  hlist id of the hlist holding the symbol list
//  
// Current input buffer's current offset in:
//  "<delimiters>word1<delimiters>word2"...
//    <delimiters>wordu<delimiters>}morestuff"
//
// Current input buffer's current offset out:
//  "morestuff"          
//
// Forth standard:
//  none
//                                                          
// Action:
//  Moves the current offset pointer for the current input buffer to the character 
//   after the next > or to the end of the buffer if > is not found.
//  For each word found before the > or end of buffer, whichever come first:
//   Compiles the code and/or data for a code import link. The stuff compiled is 
//   operating system dependendent. Then a symbol is added to the current import
//   symbol list. The name of the symbol is the word parsed. The value of the
//   symbol is the start offset of the data portion of the compiled import link.
//   The parent element id hlist id of the import symbol list is the eh pair one
//   below the top on the eh stack.
//   Then a new group of words is started. 
//
// Example:
//  OSYMBOL-CODE-IMPORTS,<
//   symbolname1
//   symbolname2
//  >
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthnewflatosymbolbuf ( NEW-FLAT-OSYMBOL-BUF )
//
// C prototype:
//  void dg_forthnewflatosymbolbuf (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:
//  ( -EH- importelementid importhlistid exportelementid exporthlistid )
//  ( -r- oldcurrentcompilebufid )
//
// EH stack in and out:
//  importelementid                parent element id of the import symbol list
//  importhlistid                  hlist id of the hlist holding the symbol list         
//
// Forth standard:
//  none
//                                                          
// Action:
//  Pushes the current compile buffer's id to the rstack.
//  Then allocates a new buffer and makes it the current compile buffer.
//  Then creates a new hlist.
//  Then makes two parent elements, one for the import symbol list and another for the
//   export symbol list.
//  Then pushes the import symbol list's parent element id hlist id to the eh stack.
//  Then pushes the export symbol list's parent element id hlist id to the eh stack.
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthfreeflatosymbolbuf ( FREE-FLAT-OSYMBOL-BUF )
//
// C prototype:
//  void dg_forthfreeflatosymbolbuf (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:
//  ( importelementid importhlistid exportelementid exporthlistid -EH- )
//  ( oldcurrentcompilebufid -r- )
//
// EH stack in and out:
//  importelementid                parent element id of the import symbol list
//  importhlistid                  hlist id of the hlist holding the symbol list         
//
// Forth standard:
//  none
//                                                          
// Action:
//  Drops the top two element id hlist id pairs from the eh stack.
//  This assumes that both symbol lists were on the same hlist and uses one of the
//   dropped hlist ids to free the hlist holding them.
//  Then this frees the current compile buffer.
//  Then this pops the saved old current compile buffer id off the rstack and makes it 
//   the current compile buffer.
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthehnewelements ( EH-NEW-ELEMENTS )
//
// C prototype:
//  void dg_forthehnewelements (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:
//  ( parentelementid parenthlistid -EH- )
//  ( value$0 name$0 value$1 name$1 ... value$u-1 name$u-1 -$- )
//  ( u -- )
//
// EH stack in and out:
//  parentelementid                parent element id of hlist to add elements to
//  parenthlistid                  parent hlist id of hlist to add elements to
//
// Data stack in:
//  u                              number of value$ name$ pairs to add
//
// String stack in
//  a list of value$ name$ pairs to add to the parent element
//
// Forth standard:
//  none
//                                                          
// Action:
//  Removes u from the data stack, and u value$ name$ pairs from the string stack
//    and adds u elements to the parent element with the hlist id element id on the
//    of the eh stack. Each element added has the name$ and value$ from a value$
//    name$ pair removed from the string stack.
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthnewhlistwithroottoeh ( NEW-HLISTWITHROOT>EH )
//
// C prototype:
//  void dg_forthnewhlistwithroottoeh (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:
//  ( -EH- 0 hlistid )
//
// EH stack in:
//  none
//
// EH stack out:
//  0 hlistid                     elementid hlistid of new hierarchical list 
//                                  containing a single root element
//                                                              
// Action:
//  Creates a new hlist and adds a root element with the name "root".
//  Then the element id of the new root element, which is 0,
//   is pushed to the EH stack
//  Then the id of this new hlist is pushed to the EH stack.
//
// Failure cases:
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthquerypostehnewelements ( QUERY-POST-EH-NEW-ELEMENTS )
//
// C prototype:
//  void dg_forthquerypostehnewelements (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:
//  ( -EH- 0 hlistid )
//
// EH in:
//  none
//
// EH stack out:
//  0 hlistid                     elementid hlistid of new hierarchical list 
//                                  containing a single root element
//                                  that has the get and post name$=value$
//                                  pairs as child elements
//                                                              
// Action:
//  Creates a new hlist and adds a root element with the name "root".
//  Then the element id of the new root element, which is 0,
//   is pushed to the EH stack
//  Then the id of this new hlist is pushed to the EH stack.
//  Then converts the form$ passed with method get and/or post into a list of name$
//   value$ pairs, ULRDECODE$ each name$ and value$, and adds the decoded name$
//   value$ pairs as child elements of the root element in the new hlist. 
//
// Failure cases:
//  
// //////////////////////////////////////////////////////////////////////////////////////