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_forthlocalsfetch dg_forthlocalsstore dg_forthtolocals dg_forthlocalsbar dg_forthqueryclearlocals  
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthlocalsfetch ( LOCALS@ )
//
// C prototype:
//  void dg_forthlocalsfetch (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
// 
// Stack action shorthand:
//  ( i -- u )
//
// Data stack in:
//  i                             0 based index of local variable in local variable 
//                                 stack
//
// Data stack out:
//  u                             value of local variable i
//                                                              
// Action:
//  i is popped off the data stack.
//  The value of local variable i is pushed onto the data stack.
//
// Failure cases:
//  error popping i from the data stack
//  u missing from the local variable stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthlocalsstore ( LOCALS! )
//
// C prototype:
//  void dg_forthlocalsstore (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* 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 i -- )
//
// Data stack in:
//  u                             new value of local variable i
//  i                             0 based index of local variable in local variable 
//                                 stack
//                                                              
// Action:
//  Pops u and i off the data stack.
//  The value of local variable i is changed to u.
//
// Failure cases:
//  error popping u or i from the data stack
//  error setting local variable i to the value of u
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthtolocals ( >LOCALS )
//
// C prototype:
//  void dg_forthtolocals (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* 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 -- )
//  ( -locals- u )
//
// Data stack in:
//  u                             value of new local variable
//                                                              
// Action:
//  Pops u off the data stack.
//  A new local variable is pushed onto the end of the locals stack and it's value 
//   is set to u.
//
// Failure cases:
//  error popping u from the data stack
//  error pushing u to the locals stack
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthlocalsbar ( LOCALS| )
//
// C prototype:
//  void dg_forthlocalsbar (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* 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>name0<delimiters>name1<delimiters>...
//    namen<delimiters>|<delimiters>morestuff" 
//     -currentinputbuffer- 
//     "<delimiters>morestuff" )
//                                                              
// Compile time action:
//  The current input buffer is parsed for names up until a | is encountered, the
//   name ; is parsed or until the end of the current interpret buffer is reached.
//   For each name found, a word with that name is created in the locals wordlist 
//   and a call to >LOCALS is compiled. If the name ; is parsed, an error is
//   pushed to the error stack and this function returns.
//
// Run time action:
//  Pops a number for each local word defined and pushes it to the locals stack.
//  This means the local word names represent the data stack parameters in reverse 
//   order.
//
// Note: (August 9, 2020 J.N.)
//  You no longer need whitespace delimiters before and after | 
//  Line terminators in the area before | are treated as white space delimiters. 
//   (This means this function is multiline when loading from a file or using 
//   EVALUATE.)
//
// Forth Standard:
//  13.6.2.1795
//
// Failure cases:
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthqueryclearlocals ( ?CLEAR-LOCALS )
//
// C prototype:
//  void dg_forthqueryclearlocals (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* pBHarrayhead    pointer to a Bufferhandle structure which is 
//                                 used as the bufferhandle for the array where the 
//                                 other bufferhandles are stored.
//                                                              
// Action:
//  If the flag for using locals or the flag for using string locals is set,
//   this routine removes all the words from the locals wordlist.
//
// Failure cases:
//  
// //////////////////////////////////////////////////////////////////////////////////////
// //////////////////////////////////////////////////////////////////////////////////////
//
// dg_forthcurlybrace ( { )
//
// C prototype:
//  void dg_forthcurlybrace (Bufferhandle* pBHarrayhead)
//
// Inputs:
//  Bufferhandle* 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>name0<delimiters>name1<delimiters>...
//    namen<delimiters>|<delimiters>
//    vname0<delimiters>vname1<delimiters>...vnamen<delimiters>
//    --<delimiters>comment}morestuff" 
//     -currentinputbuffer- 
//     "morestuff" )
//                                                              
// Compile time action:
//  This word starts off in the create uninitialized local state.
//  The current input buffer is parsed for names up until the name | is encountered,
//   the name -- is parsed, } is parsed or until the end of the current interpret 
//   buffer is reached.
//   For each name found, a word with that name is created in the locals wordlist 
//   that will compile code to copy a local variable from the return stack frame
//   of the : definition being compiled and push it to the data stack.
//  If the name | is encounter, this word switches to the initialized local state.
//   This state does everything the previous state does for each word found except
//   it also compiles code to pop a value off the data stack and put it into a
//   local variable on the return stack frame. So that you don't have to declare
//   your initialized locals in reverse order, this state puts the top data stack
//   value into the last initialized local, puts the second data stack value into
//   the second last initialized local, and so on.
//  In either state if the name -- is encountered, the rest is parsed and ignored
//   until either a } is parsed or the end of the current interpret buffer is found.
//   This is so you can put a comment after -- 
//  In all states if } or the end of the current interpret buffer is found,
//   this word ends. If } was found, } is skipped.
//
// Note:
//  Locals created with { should compile code that runs faster than locals created
//   with LOCALS|  2022 Jun 21
//
// For example:
// : swap { | x y } y x ;
// : dup { | x } x x ;
// : rot { | x y z } y z x ;
//
// : commentonly { -- my comment }
//
// : foo { uninitlocal1 uninitlocal2 | initlocal1 initlocal2 -- my comment }
//    5 TO uninitlocal1 
//    7 TO uninitlocal2 
//    CRLF
//    initlocal1 U. SPACE 
//    initlocal2 U. SPACE 
//    uninitlocal1 U. SPACE 
//    uninitlocal2 U. ;
// If you do 3 4 foo you should get 3 4 5 7 displayed on a new line
//     
// Forth Standard:
//  based on 13.6.2.2550 but the name, end character, and end parse delimiter rules
//   are different
//
// Failure cases:
//  
// //////////////////////////////////////////////////////////////////////////////////////