Help for young Jedis to feel the Forth: Starting forth """translation"""

[mcctuxic]

Hi,

for young jedis to become knowing members of the Forth "Starting Forth" by Joe Brodie is still and fully understandable the bible to learn from.

Unfortunately the Forth dialect used in the examples is ... of an ancient tongue. And "if you know one Forth - you know one Forth", which is exactly what Chuck Moore wanted, and which is GOOD! :)

The updated online version of "Starting Forth" is of .... 2003.

Especially the more advanced and interesting topics of "Starting Forth" beginning at page 215 (first edition, pdf-Version) use
words, I am uncertain of, whether I am able to successfully map them to words available with Zeptoforth.

Would it be possible to have a little table in the documentation, which helps mapping those words into Zeptoforth in a
way, which make it more easy to try the examples of those chapters of "Starting Forth" oneself with Zeptoforth?

[tabemann]

On Fri, Jul 26, 2024 at 1:31 PM mcctuxic ***@***.***> wrote: Hi, for young jedis to become knowing members of the Forth "Starting Forth" by Joe Brodie is still and fully understandable the bible to learn from. Unfortunately the Forth dialect used in the examples is ... of an ancient tongue. And "if you know one Forth - you know one Forth", which is exactly what Chuck Moore wanted, and which is GOOD! :) The updated online version of "Starting Forth" is of .... 2003. Especially the more advanced and interesting topics of "Starting Forth" beginning at page 215 (first edition, pdf-Version) use words, I am uncertain of, whether I am able to successfully map them to words available with Zeptoforth. Would it be possible to have a little table in the documentation, which helps mapping those words into Zeptoforth in a way, which make it more easy to try the examples of those chapters of "Starting Forth" oneself with Zeptoforth?

For starters, "Starting Forth" assumes that the cell size is 2 bytes, when in zeptoforth it is 4 bytes. However, good practice is to refer to cells with CELLS ( count -- bytes ) or add single cell offsets with CELL+ ( offset -- offset' ). Also, one should not define arrays by defining a VARIABLE with a name in zeptoforth. The following line in "Starting Forth": VARIABLE LIMITS 8 ALLOT ought to idiomatically be: 5 CELLS ALIGNED-BUFFER: LIMITS (BUFFER: is also supported, but ALIGNED-BUFFER: ensures that the alloted space is cell-aligned, which is very important on the RP2040 as unaligned cell accesses will trigger hardfaults. Also note that you need to reboot before you can access this space if compiling to flash.) VARIABLE LIMITS 8 ALLOT will not have the desired behavior when compiling to flash, as VARIABLE LIMITS defines a variable in RAM (which will be available after a reboot if you are compiling to flash) while ALLOT, while compiling to flash, will allot space in the flash dictionary. Likewise, 340 LIMITS 2 + ! ought to be: 340 LIMITS CELL+ ! or: 340 LIMITS 1 CELLS + ! As for: : LIMIT 2* LIMITS + ; should be: : LIMIT CELLS LIMITS + ; I won't repeat the above for other examples which follow similar patterns. As for ERASE, zeptoforth has ERASE, but it is in the COMPAT module. You can get it without importing all of COMPAT with: COMPAT IMPORT-FROM ERASE The same goes with .R and U.R, which you can get with: COMPAT IMPORT-FROM .R and COMPAT IMPORT-FROM U.R As for DUMP, zeptoforth has DUMP, but it works differently from the DUMP mentioned in "Starting Forth", having the signature: DUMP ( start-addr end-addr -- ) where end-addr is exclusive; for instance, if you want to dump 1024 bytes starting at FOO, execute: FOO DUP 1024 + DUMP Another word in COMPAT is ? : COMPAT IMPORT-FROM ? Another note is that ' when compiling should be ['] if you want it to do what you want. As for BASE, in zeptoforth it is a variable containing the current task's BASE and is accessed with BASE @ and BASE ! . As for the outer interpreter, in zeptoforth it's named OUTER rather than INTERPRET, but it is not recommended you call it directly. And I am only on the chapter you mentioned... I highly suggest you at least read the 2003 edition, as a number of these things have probably changed in it in a fashion that makes it more aligned with zeptoforth (however, the COMPAT stuff and things like DUMP will still be different most likely). Travis

[mcctuxic]

On 07/26 12:47, tabemann wrote: On Fri, Jul 26, 2024 at 1:31 PM mcctuxic ***@***.***> wrote: > Hi, > > for young jedis to become knowing members of the Forth "Starting Forth" by > Joe Brodie is still and fully understandable the bible to learn from. > > Unfortunately the Forth dialect used in the examples is ... of an ancient > tongue. And "if you know one Forth - you know one Forth", which is exactly > what Chuck Moore wanted, and which is GOOD! :) > > The updated online version of "Starting Forth" is of .... 2003. > > Especially the more advanced and interesting topics of "Starting Forth" > beginning at page 215 (first edition, pdf-Version) use > words, I am uncertain of, whether I am able to successfully map them to > words available with Zeptoforth. > > Would it be possible to have a little table in the documentation, which > helps mapping those words into Zeptoforth in a > way, which make it more easy to try the examples of those chapters of > "Starting Forth" oneself with Zeptoforth? > For starters, "Starting Forth" assumes that the cell size is 2 bytes, when in zeptoforth it is 4 bytes. However, good practice is to refer to cells with CELLS ( count -- bytes ) or add single cell offsets with CELL+ ( offset -- offset' ). Also, one should not define arrays by defining a VARIABLE with a name in zeptoforth. The following line in "Starting Forth": VARIABLE LIMITS 8 ALLOT ought to idiomatically be: 5 CELLS ALIGNED-BUFFER: LIMITS (BUFFER: is also supported, but ALIGNED-BUFFER: ensures that the alloted space is cell-aligned, which is very important on the RP2040 as unaligned cell accesses will trigger hardfaults. Also note that you need to reboot before you can access this space if compiling to flash.) VARIABLE LIMITS 8 ALLOT will not have the desired behavior when compiling to flash, as VARIABLE LIMITS defines a variable in RAM (which will be available after a reboot if you are compiling to flash) while ALLOT, while compiling to flash, will allot space in the flash dictionary. Likewise, 340 LIMITS 2 + ! ought to be: 340 LIMITS CELL+ ! or: 340 LIMITS 1 CELLS + ! As for: : LIMIT 2* LIMITS + ; should be: : LIMIT CELLS LIMITS + ; I won't repeat the above for other examples which follow similar patterns. As for ERASE, zeptoforth has ERASE, but it is in the COMPAT module. You can get it without importing all of COMPAT with: COMPAT IMPORT-FROM ERASE The same goes with .R and U.R, which you can get with: COMPAT IMPORT-FROM .R and COMPAT IMPORT-FROM U.R As for DUMP, zeptoforth has DUMP, but it works differently from the DUMP mentioned in "Starting Forth", having the signature: DUMP ( start-addr end-addr -- ) where end-addr is exclusive; for instance, if you want to dump 1024 bytes starting at FOO, execute: FOO DUP 1024 + DUMP Another word in COMPAT is ? : COMPAT IMPORT-FROM ? Another note is that ' when compiling should be ['] if you want it to do what you want. As for BASE, in zeptoforth it is a variable containing the current task's BASE and is accessed with BASE @ and BASE ! . As for the outer interpreter, in zeptoforth it's named OUTER rather than INTERPRET, but it is not recommended you call it directly. And I am only on the chapter you mentioned... I highly suggest you at least read the 2003 edition, as a number of these things have probably changed in it in a fashion that makes it more aligned with zeptoforth (however, the COMPAT stuff and things like DUMP will still be different most likely). Travis

Oh thank you master Yoda! The Forth is great with you! :) ;) So...as often in programming...don't hardcode constants! That is: In the context of "amount of memory" cellwise use cell/s instead of 2 or 4....right? What I currently think to not fully understand is this "VARIABLE vs. ALLOT" thing. Is this correct? VARIABLE creates variables in RAM even when the regarding word is defined in flash. But it is legal code, if one accepts one extra boot to get things up and running and accepts that the contents of the variable will not survive a power cycle / a reboot. ALLOT in contrast allocates memory, where it is used. While compiling to flash, memory of the flash is allocated, when compiling to RAM it is allocated from RAM. So a word definition, which mixes the use of VARIABLE with ALLOT serves two worlds (RAM/FLASH) when compiled to FLASH in the unexpected way. But in general a variable in RAM isn't a bad thing, is it?

…

--

Reply to this email directly or view it on GitHub: #122 (comment) You are receiving this because you authored the thread. Message ID: ***@***.***>

[tabemann]

On Sat, Jul 27, 2024 at 6:10 AM mcctuxic ***@***.***> wrote: Oh thank you master Yoda! The Forth is great with you! :) ;)

I do my best not to let it go to my head - lol.

So...as often in programming...don't hardcode constants! That is: In the context of "amount of memory" cellwise use cell/s instead of 2 or 4....right?

I admit to at times using 4 instead of CELL , 4 + instead of CELL+ , or 4 * (or 2 LSHIFT) instead of CELLS, but in general it is good practice to use CELL , CELL+ , and CELLS here

What I currently think to not fully understand is this "VARIABLE vs. ALLOT" thing. Is this correct? VARIABLE creates variables in RAM even when the regarding word is defined in flash. But it is legal code, if one accepts one extra boot to get things up and running and accepts that the contents of the variable will not survive a power cycle / a reboot. ALLOT in contrast allocates memory, where it is used. While compiling to flash, memory of the flash is allocated, when compiling to RAM it is allocated from RAM. So a word definition, which mixes the use of VARIABLE with ALLOT serves two worlds (RAM/FLASH) when compiled to FLASH in the unexpected way. But in general a variable in RAM isn't a bad thing, is it?

You are correct. In zeptoforth you should not mix VARIABLE's with ALLOT as done in some older Forths; it will not do what you want it to do if you are compiling to flash ─ it will create a CONSTANT in flash pointing to a cell in RAM and then increment the flash HERE pointer by the specified amount. VARIABLE creates a CONSTANT in the current dictionary being compiled to that points to an address in RAM that will contain one cell, and advances a pointer stored in flash so that the next VARIABLE , 2VARIABLE , BUFFER: , or like will start at the next cell in RAM. Note that when compiling to flash this address will only be usable to storing data after rebooting (not rebooting before accessing the VARIABLE will result in undefined behavior, in many cases in the form of a crash). By design the values of VARIABLE's do not survive a reboot. ALLOT simply adds a number to the current HERE pointer. Note that in zeptoforth there is a HERE pointer pointing into flash, and each task has its own HERE pointer which points into its RAM dictionary. Which one will be added to depends on whether one is compiling to RAM or to flash. When compiling to RAM HERE will return the HERE pointer for the current task pointing into its RAM dictionary, while compiling to flash HERE will return the HERE pointer pointing to the flash dictionary. Note that in many cases one will want specifically the HERE pointer in RAM for the current task rather than the HERE pointer in flash. For that one should use RAM-HERE , RAM-ALLOT , and RAM-ALIGN, , rather than HERE , ALLOT , and ALIGN, . Note that WITH-ALLOT and WITH-ALIGNED-ALLOT , which are very useful words, one always manipulates the current task's RAM HERE pointer, not the flash HERE pointer, even when one is compiling to flash. Travis

…

Message ID: <tabemann/zeptoforth/repo-discussions/122/comments/10166916@ github.com>

[mcctuxic]

On 07/27 01:52, tabemann wrote: On Sat, Jul 27, 2024 at 6:10 AM mcctuxic ***@***.***> wrote: > Oh thank you master Yoda! The Forth is great with you! :) ;) > I do my best not to let it go to my head - lol. > So...as often in programming...don't hardcode constants! That is: > In the context of "amount of memory" cellwise use cell/s instead > of 2 or 4....right? > I admit to at times using 4 instead of CELL , 4 + instead of CELL+ , or 4 * (or 2 LSHIFT) instead of CELLS, but in general it is good practice to use CELL , CELL+ , and CELLS here

"magic numbers" make code very hard to read and to understand, yes :)

> What I currently think to not fully understand is this "VARIABLE vs. > ALLOT" thing. > > Is this correct? > VARIABLE creates variables in RAM even when the regarding word is > defined in flash. But it is legal code, if one accepts one extra boot > to get things up and running and accepts that the contents of the > variable will not survive a power cycle / a reboot. > ALLOT in contrast allocates memory, where it is used. While compiling > to flash, memory of the flash is allocated, when compiling to RAM it > is allocated from RAM. > So a word definition, which mixes the use of VARIABLE with ALLOT serves > two worlds (RAM/FLASH) when compiled to FLASH in the unexpected way. > > But in general a variable in RAM isn't a bad thing, is it? You are correct. In zeptoforth you should not mix VARIABLE's with ALLOT as done in some older Forths; it will not do what you want it to do if you are compiling to flash ─ it will create a CONSTANT in flash pointing to a cell in RAM and then increment the flash HERE pointer by the specified amount. VARIABLE creates a CONSTANT in the current dictionary being compiled to that points to an address in RAM that will contain one cell, and advances a pointer stored in flash so that the next VARIABLE , 2VARIABLE , BUFFER: , or like will start at the next cell in RAM. Note that when compiling to flash this address will only be usable to storing data after rebooting (not rebooting before accessing the VARIABLE will result in undefined behavior, in many cases in the form of a crash). By design the values of VARIABLE's do not survive a reboot. ALLOT simply adds a number to the current HERE pointer. Note that in zeptoforth there is a HERE pointer pointing into flash, and each task has its own HERE pointer which points into its RAM dictionary. Which one will be added to depends on whether one is compiling to RAM or to flash. When compiling to RAM HERE will return the HERE pointer for the current task pointing into its RAM dictionary, while compiling to flash HERE will return the HERE pointer pointing to the flash dictionary. Note that in many cases one will want specifically the HERE pointer in RAM for the current task rather than the HERE pointer in flash. For that one should use RAM-HERE , RAM-ALLOT , and RAM-ALIGN, , rather than HERE , ALLOT , and ALIGN, . Note that WITH-ALLOT and WITH-ALIGNED-ALLOT , which are very useful words, one always manipulates the current task's RAM HERE pointer, not the flash HERE pointer, even when one is compiling to flash. Travis

Thanks a lot for the explanation and info Travis - very appreciated!!! I think I will have to meditate it an additional night before enlightenment strikes me...I think, Zeptoforth is "An elegant" but not a "weapon," (which is a good thing!) but definitely "for a more civilized age." I am holding the laser programming tool already in my hands...but the wrong way around at times... :) :) ;)

…

> Message ID: <tabemann/zeptoforth/repo-discussions/122/comments/10166916@ > github.com> -- Reply to this email directly or view it on GitHub: #122 (comment) You are receiving this because you authored the thread. Message ID: ***@***.***>