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

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

Afs/doc/value.txt | 55+++++++++++++++++++++++++++++++++++++++++++++++++++++++
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. +