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_forthdefinitions dg_forthgetcurrent dg_forthgetorder dg_forthsearchwordlist dg_forthsetcurrent dg_forthsetorder dg_forthwordlist
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthdefinitions ( DEFINITIONS )
//
// C prototype:
//   void dg_forthdefinitions (Bufferhandle* pBHarrayhead) 
//
// Inputs:
//  Bufferhandle* 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:
//  Set the current new word word list to be the same as the top 
//  (first searched) word list in the search order.
//
// Failure cases:
//   error getting pointer to the search order stack
//   search order stack is empty
//   error getting pointer to the word list header array
//   word list id on top of search order is NOT in the word list header array
//   error putting word list id to the current compile word list variable
//
// Tested cases:
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthgetcurrent ( GET-CURRENT )
//
// C prototype:
//   void dg_forthgetcurrent (Bufferhandle* pBHarrayhead) 
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//   ( -- CurrentNewWordWordListId )
// 
// Data stack out: 
//  CurrentNewWordWordListId      identifier of the word list where newly defined
//                                  words are currently added
//                                                            
// Action:
//  pushes the word list id
//  of the current wordlist where newly defined words are added 
//  to the data stack.
//
// Failure cases:
//  error getting current new word word list id
//  error pushing current new word word list id to the data stack
//   
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthgetorder ( GET-ORDER )
//
// C prototype:
//  void dg_forthgetorder (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- wid_n ... wid_1 n )
// 
// Data stack out:  
//  wid_n ... wid_1               n word list identifiers
//  n                             number of word list identifiers on the data stack 
//                                 from GET-ORDER
//                                                            
// Action:
//  Pushes the current search order to the data stack followed by the
//  number of word list identifiers in the search order
//
// Failure cases:
//  error getting pointer to the search order buffer
//  search order buffer is not integer aligned (corrupt); 
//   do -1 SET-ORDER to fix it
//  error pushing search order word list identifiers to the data stack
//  error pushing the number of word list identifiers in the search order to the data 
//   stack
//
// Tested cases:
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthsearchwordlist ( SEARCH-WORDLIST )
//
// C prototype: 
//  void dg_forthsearchwordlist (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* 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 wid -- 0 )     if word not found
//  ( c-addr u wid -- xt 1 )  if word found and it is immediate
//  ( c-addr u wid -- xt -1 ) if word found and it is not immediate
// 
// Datastack in:
//  c-addr                        address of word name string to find
//  u                             length of word name string
//  wid                           word list id of word list to search for name string
//                                 
// Datastack out:
// 0                              if the word name wasn't found 0 is returned
//  or xt 1                       if the word 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
//
// Failure cases:
//  error getting pointer to the data stack
//  not enough items on data stack for this operation
//  error finding definition in word list
//  error getting pointer to the definition
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthsetcurrent ( SET-CURRENT )
//
// C prototype:
//  void dg_forthsetcurrent (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the  
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//   ( wid -- )
// 
// Data stack in:
//  wid                           identifier of new current new word word list  
//                              
// Action:
//  Pops word list identifier from the data stack
//  Sets the current new word word list to this identifier.
//    (This is the word list where newly created words go.)
//
// Failure cases:
//  error popping current compile word list from the data stack
//  word list header array is missing
//  word list does not exist
//  error storing word list id into current compile word list variable
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthsetorder ( SET-ORDER )
//
// C prototype:
//  void dg_forthsetorder (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the  
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( wid_n ... wid_1 n -- )
// 
// Data stack in:
//  wid_n ... wid_1               n word list identifiers 
//  n                             number of word list identifiers on the data stack 
//                                 for SET-ORDER or 0 to specify an empty search 
//                                 order (you are locked out after this)
//                                 or -1 to specify the default search order
//                              
// Action:
//  Pops word list identifiers and n from the data stack
//  Sets the current search order to these identifiers. wid1 is searched first.
//
// Notes:
//  Forth standard specifies the user is allowed to make the search order anything 
//   they want, including an empty search order even though this locks out the user 
//   if they do it.
//
// Failure cases:
//  error getting pointer to the data stack
//  n is missing from the data stack
//  error getting pointer to the search order buffer
//  error pushing the minimum word list to the search order buffer (n = -1 case)
//  number of wordlists < -1 error
//  not enough word list ids on the data stack 
//  error pushing the word list ids to the search order buffer
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthwordlist ( WORDLIST )
//
// C prototype:
//  void dg_forthwordlist (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//
// Stack action shorthand:
//  ( -- wid )
//
// Data stack out:
//  wid                           new word list identifier 
//                              
// Action:
//  creates a new word list
//  pushes the identifier of the new word list onto the data stack.
//
// Failure cases:
//  error creating the new wordlist
//  error pushing the new word list id to the data stack
//  
// //////////////////////////////////////////////////////////////////////////////////////