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.
Diffstat:
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.
