ESP32Forth-Local-variables.TXT

\ ESP32Forth-Local-variables

\ ESP32Forth supports local variables.
\ They are declared between { and } right after the colon-definition, e.g.:

: 3x+1 { x -- sum }  x 3 * 1 + ;

\ Here x is taken from the stack at the call and can be
\ used as a local variable in the definition.

: 2OVER { a b c d -- a b }  a b c d a b ;

\ Assignment/modification of local variables is done with to and +to, e.g.:

: a+bEXP2 { a b -- (a+b)^2 }
  0 { result }
  a a *        to  result
  b b *       +to  result
  a b * 2 *   +to  result
  result
;

\ EOF

Important: If you use local variables in a definition,
you should not use >r and r> in the same word,
as it can interfere with the internal handling of the local variables.

There must be two hyphens (--) in the stack effect for local variables
in ESP32Forth (and most Forth systems with locals).

Stack-effect rules
1. Input variables (before --)
text
: 3x+1 { x -- sum }     \ x comes from the data stack
  x 3 * 1 + ;           \ returns sum to the data stack
Stack before call: ( x -- sum )

2. Output variables (after --)
text
: a+bEXP2 { a b -- (a+b)^2 }
  0 { result }
  ...
  result ;              \ result goes out to the data stack
Stack before call: ( a b -- (a+b)^2 )

3. -- always separates input from output

: 2OVER { a b c d -- a b }
  a b c d a b ;         \ takes 4, returns 2
Stack before call: ( a b c d -- a b )

Why two hyphens?
First -: Ends the input list (what's taken from the stack)

Second -: Starts the output list (what's placed on the stack)

--- would be incorrect syntax – Forth expects exactly --.

Typical examples

{ x -- n }      \ input: x, output: n
{ -- n }        \ no input, output: n
{ x y -- z }    \ input: x y, output: z
{ x y z -- }    \ input: x y z, no output
{ x -- x }      \ input: x, output: same x

Your code is correct: { a b -- (a+b)^2 } means "takes a b
from the stack, returns (a+b)^2 to the stack".

 Det der står efter -- er fri dokumentation/kommentar – ikke en del af Forth‑syntaksen.

Stack‑effekt syntaks i Forth
text
: navn { input1 input2 -- output1 output2 }  \ <-- Kommentar her
Før --: Lokale variabler (bindes til stack‑elementer)
Efter --: Fri tekst som beskriver, hvad ordet returnerer.

Eksempler på "fri tekst" efter --
text
: 3x+1 { x -- 3*x+1 }      \ Beskriver hvad der returneres
: MAX { a b -- larger }     \ Navngiver resultatet
: AREA { l w -- area }      \ Kort beskrivelse
: SWAP { a b -- b a }       \ Præcis stack‑effekt
: 2OVER { a b c d -- a b } \ Klassisk Forth stack notation
Hvad parseren ignorerer
Forth‑kompileren læser kun:

text
{ x y -- }    \ x og y er lokale variabler
Alt efter -- (inkl. parenteser (a+b)^2) er kommentar der:

Ikke påvirker kompilation

Kun er til læsbarhed

Kan udelades uden fejl

text
: a+bEXP2 { a b -- }  \ <-- Fungerer også!
  ... result ;
(a+b)^2 er altså din kommentar til at forklare logikken – Forth bryder sig ikke om den, men det gør koden meget læsbar!

Angående "0 { result }" blive result også en variabel
man fx. kan arbejde med inde i ordet?
Ja, præcis! result bliver også en fuldt ud funktionel lokal variabel, som du kan læse fra og skrive til inde i ordet.

Sådan virker 0 { result }

: a+bEXP2 { a b -- (a+b)^2 }
  0 { result }          \ result initialiseres til 0
  a a *       to result \ result = a*a
  b b *      +to result \ result += b*b
  a b * 2 *  +to result \ result += 2*a*b
  result               \ læg result på stakken
;

result er en ægte lokal variabel
Efter 0 { result } kan du:

Læse værdien: result henter den aktuelle værdi på datastakken

Skrive værdien: to result sætter ny værdi

Tilføje til værdien: +to result øger den eksisterende værdi

Bruge i beregninger: result 2 *, result a + osv.

Flere lokale variabler samtidigt

: complex { x y -- result }
  0 { sum }
  1 { count }

  x to sum          \ sum = x
  y +to sum         \ sum += y
  count 2 * to count \ count = 2

  sum count *       \ return sum*count
;

Vigtige regler
Alle lokale variabler (både input som a b og interne som result) er tilgængelige i hele ordet

to variabel: Sætter værdien (overskriver)

+to variabel: Tilføjer til værdien (sum)

Ingen kollision: result er forskellig fra a og b – hver er sin egen "boks"

Scope: Alle lokaler findes kun inde i dette ord, forsvinder når ordet afsluttes

0 { result } skaber altså en lokal variabel result startende med værdien 0,
som du frit kan arbejde med ligesom a og b.
Det er med til at gøre koden læsbar uden at skulle jonglere med stack‑elementer hele tiden.