Author: binarycat <email@example.com>
Date: Thu, 30 Jun 2022 13:01:24 -0400
in-depth documentation for value and alias
I heard some people found this confusing, so here's my attempt to expalin.
From 16872ac546bbbfc89d0a5f9ba486474df076c95a Mon Sep 17 00:00:00 2001
From: binarycat <firstname.lastname@example.org>
Date: Thu, 30 Jun 2022 12:27:43 -0400
Subject: [PATCH] add documentation explaining value and alias in-depth
1 file changed, 55 insertions(+), 0 deletions(-)
diff --git a/fs/doc/value.txt b/fs/doc/value.txt
@@ -0,0 +1,55 @@
+# value and alias semantics in-depth
+There are several words that are used to define other words, such as
+":" and "code", but the three that will be explained here are
+"create", "value", and "alias".
+create is mostly straitforward, it defines a word that pushes an
+address to the stack. The address that it pushes is the same as the
+one returned by "here" after the word is defined. To use this to
+store a cell-sized value (4 bytes), you would to something like this:
+ create foo 7 ,
+ foo @ . \ 7
+ 9 foo !
+This works fine, but always having to specify the extra "@" can become
+a bit repetitive. "value" exists to reduce the amount of calls
+needed. It does this by making the defined word implicitly call "@"
+after putting the address on the stack.
+This poses a new problem: if the word is always calling "@", how do we
+change the value? We can do this using "to", which sets a global flag
+telling the next value-defined word to execute "!" instead of "@".
+Using this, our example above becomes:
+ 7 value foo
+ foo .
+ 9 to foo
+There are two more words that modify the same global variable as "to":
+"to+" and "to'". to+ replaces the implicit "@" with "+!", while to'
+replaces it with "noop", causing the address to be pushed to the
+stack, same as if the word was defined with "create".
+"alias" works very similar to "value", except instead of words just
+implicitly calling "@", they implicitly call "@" then "execute". this
+is useful when you want to (re)define a word later. "to" and similar
+words all behave the same on alias-defined words, replacing the
+implicit "@ execute" call.
+all of these words use different syntax for defining words.
+"create" is once again the simplest, only parsing a name for the new
+word and requiring you to do everything else (such as "allot"-ing
+"value" is nearly the same, except it takes an argument on the stack
+for the initial value.
+"alias" parses two words, first the name of an already defined word,
+then the name of the name of the new word being defined. It does not
+have any effect on the stack.