commit 6ca68a5be640af6151c30ee70628ce7403db40da
parent 7900d80fd5e30cfa2e35c4294ec0870358147325
Author: binarycat <binarycat@envs.net>
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 <binarycat@envs.net>
Date: Thu, 30 Jun 2022 12:27:43 -0400
Subject: [PATCH] add documentation explaining value and alias in-depth
Diffstat:
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.
+
+# syntax
+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
+memory) yourself.
+
+"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.
+
