dusk os fork
git clone git://git.alexwennerberg.com/duskos
Log | Files | Refs | README | LICENSE

commit d9ad228c80f1133d8ee94d3592b6e841c9542986
parent 0f2c3eff56ba25fee792146083a91c173023eeeb
Author: Virgil Dupras <hsoft@hardcoded.net>
Date:   Sun, 18 Jun 2023 16:37:59 -0400

doc: fix and improve "to" semantics docs

When I removed to semantics of aliases, I amended the "to" semantics docs in a
way that made them non-sensical. I've fixed this and added some more details.

Mfs/doc/usage.txt | 18+++++++++++-------
1 file changed, 11 insertions(+), 7 deletions(-)

diff --git a/fs/doc/usage.txt b/fs/doc/usage.txt @@ -199,20 +199,24 @@ Values are very similar to cells: they're a piece of memory attached to a "handling" routine. With the cell, the routine is a noop, it returns the address of the piece of memory. -With values it's not a noop. The first fetches the value in memory, the second -jumps to the address contained by that memory. +With values, the "@" routine is attached to the cell and automatically called +(or "equivalent to called", some pretty HAL magic happens at compile time making +"to" semantics pretty efficient) when the value is invoked. This means that +calling a value returns the value in the cell rather than the address of the +cell. -These routines come with... side effects. How can you modify a value? You need a -"to" word. +This is convenient, but raises a question: How can you modify a value? You need +a "to" word. The "to" words ("to", "to+", etc.) set a global variable with a pointer to an -alternate routine for value words to execute. For example, the "to" word makes -that global variable point to "!". +alternate routine for value words to execute. The "to" word makes that global +variable point to "!", "to+" makes it point to "1+!", etc.. This means that when you do "42 to myvalue", instead of "myvalue" executing the equivalent of "addr-of-myvalue @", it executes "addr-of-myvalue !". -As soon as a "to" override is used, the global "to" pointer is reset to 0. +As soon as a "to" override is used once, the global "to" pointer is reset to 0 +(meaning "@"). Refer to doc/dict for a complete list of "to" words.