6ca68a5be640af6151c30ee70628ce7403db40da — binarycat a month ago 7900d80
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
1 files changed, 55 insertions(+), 0 deletions(-)

A fs/doc/value.txt
A fs/doc/value.txt => fs/doc/value.txt +55 -0
@@ 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.