FreeForth Primer

Forthers please note: FreeForth has some specific features uncommon to other Forth dialects, that you should be aware of before starting using FreeForth; they are hereunder highlighted in slant green as this paragraph.

PRIMER SUMMARY:
• Distribution License
• Getting Started
  • Distribution Files
  • Installation under Linux
  • Installation under Windows
  • First Steps
  • Getting Online Help
• FreeForth Syntax
• FreeForth Literals
• FreeForth Data Flow
• FreeForth Control Flow
  • Subroutine Call and Return
  • Unstructured Conditional Jumps
  • Two-Alternatives Control Structure
  • Multi-Alternatives and Loop Control Structures
  • Long Jumps
  • Exception Handling
• FreeForth Symbolic Constants
• FreeForth Variables
• Conditional Compilation

FreeForth is a public domain software. Its license offers total freedom to its users, as stated by its LICENSE file.

FreeForth isn't just a toy, it is a small/simple/efficient interactive compiler generating compact and fast i386 native code; since its creation in 2006, I've been using it for my everyday work as much as handy desktop calculator for decimal, hex, binary, and floating-point operations, as for interactive cross-development of industrial real-time security applications embedded in microcontrollers, and for PC-controlled industrial test-benches.

In the following text, commands that you have to type will be in blue fixed font, and what the computer displays will be in black fixed font.

Distribution Files

    mkdir $HOME/ff
    unzip ffXXXXXX.zip -d $HOME/ff

    ln -s /path/to/preferedFFrootdir $HOME/ff
    unzip ffXXXXXX.zip -d $HOME/ff

    #!/usr/bin/ff needs

    sudo ln -s $HOME/ff/ff /usr/bin/ff

    md C:\ff
    cd C:\ff
    unzip ffXXXXXX.zip

    set FFROOT=C:\path\to\preferedFFrootdir\

    set PATH=C:\ff;%PATH%

    ff

    \ Loading'ff.ff: help normal .now {{{ +longconds f. uart! hid'm
    \ FreeForth 1.2 <http://christophe.lavarenne.free.fr/ff>  Try: help
     0;

     0; needs  'hanoi

When you are finished playing with the demo, let's compute your age in number of days: FreeForth understands date (or/and time) literals, that it converts into sequential numbers of days, which are then trivial to use with integer arithmetic operators (using postfix notation, as explained hereunder):

     0; 2008-10-14  1956-7-23  -  .  ;
    19076 0;

FreeForth also comes with a full-fledged floating-point package; let's verify that the tangent of pi/4 is equal to 1.0:

    19076 0; fpi  4.  f/  ftan  f.  ;
    1.000e0 0;

To pass a command-line to the command-shell, simply type it after a double exclamation mark:

    1.000e0 0; !! echo Works under Linux or Windows
    Works under Linux or Windows
     0;

     0; bye

    help

help` ( <name> -- ) displays name's related help (try: help bye)
  Items with no stack diagram are concepts, or hidden non-compilable words.
  Beginner: start with "help DATAstack" to understand "stack diagrams".
  Forth geek: look at "conditionals" and "flow-control" which are unusual,
    and at "anonymous" and "backquote" which are specific to FreeForth.
  Curious: start with the comments at beginning of file "ff.asm".
  see also: man win32.hlp bye ff.help  ff.ff
 0;

    help  ff.help

ff.help is the FreeForth help file, expected by "help`" (defined in ff.ff)
  to be found in FreeForth root directory (where ff.ff is found at boot time).
  Users may create their own help files following the same simple text format,
  and add them into "help`" definition, as explained in commented sample line.
  see also: ff.asm ff.boot ff.ff bed.ff hello
 0; 

Before playing more with FreeForth, let's first learn a bit more about its trivial syntax, handy literals, data flow (use of stacks), and control flow.

    5 TIMES  r 2* .  REPEAT ;

Most words represent a constant value, either literally, where the value is explicitely given by the characters composing the word name (such as the 5 above, literals syntax is fully specified hereunder), or symbolically, where the value is assigned to the word either explicitely by the programmer, to replace all the occurences of a literal constant or constant expression with a meaningful name defined in a single place (see help constant), or implicitely by the compiler, when the programmer defines a data buffer (the compiler allocates memory and assigns its base address to the programmer-defined word, see help create), or a code label (the compiler assigns the current code address to the programmer-defined word, see help :).

What other languages call "expression" or "instruction" is in FreeForth a simple sequence of words called phrase, that the programmer may separate from other phrases by double space or a newline for easier reading, as in the above example which contains three phrases. Phrasing and indentation are mostly useful, as in every language, to exhibit the control structure of program flow; FreeForth offers a rich set of predefined control-structure words, which the programmer may extend at will if needed.

What other languages call "function" or "subroutine" is in FreeForth a sequence of words called definition, beginning with the single-character word  :   (colon) followed by one word as the definition name, and ending with the single-character word  ;   (semicolon).
The colon and its following definition name may be omitted, as in the above example of seven valid words: such an anonymous definition, as it has no name to reference it later, is executed (and "forgotten") immediately when the semicolon is compiled (try it: it should display 8 4 6 2 0). This is where FreeForth provides its interactivity.

Forthers note this is the most important difference between FreeForth and other Forth dialects, which instead provide interactivity with the help of an "interpret" state outside definitions (by opposition with a "compile" state within definitions), where every word is immediately executed, which cannot support forward-references of regular control-structures words. By comparison, FreeForth is always in "compile" state because always within definitions, whether named or anonymous.

What other languages call "executable code and data space" is in FreeForth the memory space where all compiled definitions are stored, naturally called the dictionary, with a separate headers space storing the definitions names (for lookup during the compilation of a new definition), that other languages call "compilation symbol table" (and use only during compilation, and strip off the executable file, except when the debug option is set). Type  words  to list the contents of the headers space.

When FreeForth source code is compiled, each word is looked up in turn in the headers space; if it is found, it is either immediately executed if found with an appended backquote (it's then called a macro), or its execution is postponed (i.e. it is "compiled" into a call assembly instruction jumping to the definition entry point); otherwise, an unfound word is converted into a literal string or number, depending on its last character (see hereunder for more details), or raises an exception with the error message <-error: ??? if the conversion fails.

Forthers note FreeForth backquote-suffix makes defining and using macros much easier than the IMMEDIATE and POSTPONE genuine Forth words: see the ff.boot kernel source file for lots of examples.

FreeForth comments may be inserted in different ways within a source file:

within a line, or across several lines:

the single-character word  (  (left bracket) opens the comment, which is closed by the first character  )  (right bracket) found either on the same source line, or within a later source line (this is the equivalent of the  /*...*/  in the C language)

upto end of line:

the single-character word  \  (backslash) opens a comment, which is closed by the end of line (this is the equivalent of the  //  in C++ and C99); don't forget to insert at least one space after the backslash, otherwise the immediately following newline will be "eaten" as blank separator, and the next line will be commented out up to its end of line!

upto end of file:

the word  EOF  opens a comment upto the end of file; this may be a convenient place to add lots of comments such as documentation or versions followup.

As seen in FreeForth Syntax, when during compilation a word is not found in the dictionary headers space, it is converted to a literal string or number depending on its final character:

• a final  "  (double-quote) marks a literal string, which initial character is processed specially:
  • an initial  .  (dot) compiles a counted string (i.e. with a first byte equal to the string byte-size, and a null byte appended after the last string byte) preceded by a call which, when later executed, will display the string contents; for example,  ."Hello_world!"  will display  Hello world!
  • an initial  !  (exclamation mark) compiles a counted string preceded by a call which, when later executed, will throw an exception with as argument the address of the counted string, such that the exception handler which catches the exception can display the string, typically as error message; for example,  !"divide_by_zero"  will display  <-error: divide by zero
  • an initial  "  (double-quote) compiles a counted string preceded by a call which, when later executed, will return the string's first character address and its byte-size ( -- @ # )
  • an initial  ,  (comma) compiles the string standalone, i.e. with no count and no preceding call; this is useful to compile inline any data and/or code
  • any other initial character with a final double-quote raises an exception with the error message <-error: ???
  Furthermore, five characters within literal strings are processed specially:
  • every  _  (underscore) is replaced with a space -- i.e. you must replace every space within a string with an underscore, otherwise the space would be considered as a separator between two words
  • any character prefixed with a  ^  (caret) is replaced with the corresponding "control" character with an ASCII value 64 less; for example,  ^J  is replaced with the ASCII 74-64 = ASCII 10, i.e. "newline"
  • any character suffixed with a  ~  (tilde) is replaced with the corresponding byte with an ASCII value 128 more; for example,  J~  is replaced with the ASCII 74+128 = ASCII 202
  • any  "  (double-quote) is ignored and skipped (such as after the initial dot or exclamation mark)
  • any character prefixed with a  \  (backslash) is left as is, which is usefull to "escape" these five special characters
  For example, ."Hello_\_my\__world!^J" will display Hello _my_ world! followed by a newline.

• a final arithmetic operator character (among + - * / % & | ^ ) calls number to convert the string (without the final character) into a number, or if it fails calls find to look in the compiler symbol table for a header matching the string (without final), and if found with a "data" type, gets the number in its pointer field (or if it fails raises an exception with the error message <-error: ???); then these finals compile their corresponding binary-op instruction (+:add -:sub *:mul /:div %:mod &:and |:or ^:xor) with the above number as immediate argument, and DATAstack top as destination; simple and efficient "manual" optimization: for example,  3+  is faster and smaller than  3 +
• a final  @  (arobas) calls find as above, and compiles runtime code which will read memory cell at that address and push its contents onto DATAstack; with a variable named var for example, var@ is faster and smaller than  var @
• a final  !  (exclamation-mark) calls find as above, and compiles runtime code which will store DATAstack top at the address and pop DATAstack; with a variable named var for example, var! is faster and smaller than  var !
• a final  _  (underscore) calls number or find as above, and compiles runtime code which will replace DATAstack top with the obtained number; for example,  5_  is faster and smaller than  drop 5  this saves a drop (and a push)
• a final  ,  (comma) calls number or find as above, and compiles runtime code which will store the obtained number at the location pointed at runtime by the compilation pointer (i386 register ebp), which will have to be incremented separately; useful for macros such as s1 which compile inline assembly code
• any other final calls number to convert the string (with its final) into a number (or if it fails raises an exception with the error message <-error: ???), and compiles runtime code which will push that number onto the DATAstack ( -- n ).

• $  changes the conversion base to 16 (hexadecimal)
• &  changes the conversion base to 8 (octal)
• %  changes the conversion base to 2 (binary)
• #  changes the conversion base to the number converted so far

  18  $12  &22  %10010  3#200  12#16  %10&2  9%0  &11%0

• :  (colon) multiplies by 60 the number converted so far, then adds to it the remaining string; this is typically for conversion of hours (or degrees), minutes, seconds, as for example:

    1:10:20 . ; 4220   \ = (1h *60m/h +10m) *60s/m +20s
  

• _  (underscore) multiplies by 24 the number converted so far, then adds to it the remaining string; this is typically for conversion of days into hours, as for example:

    2_1 . ; 49   \ = 2d *24h/d +1h
  

• -  (dash) must be used twice to separate the three numbers of a date (year, month, day), and convert them into a sequential day number in the Gregorian calendar as for example:

    2000-3-1 . ; 730485
  

  .d  \ n -- ; displays n (days since 0000-3-1) as a date
    730485 .d ;  2000-3-1
  .t  \ n -- ; displays n (seconds since midnight) as a time
    47700 .t ;  13:15:00
  .dt \ n -- ; displays n (seconds since 2000-3-1) as a date and time
    300'000'000 .dt ;  2009-9-2_5:20:0
  .now` \ -- ; displays system's current date and time
    .now  wed 2009-8-12_16:4:37

For example, the single-character word  +  (plus), defined to execute an addition taking two input arguments and returning a single output result equal to the sum of the second and top DATAstack items, could have either of the two equivalent following stack-diagram comments:

    + ( n2 n1 -- n ; n=n2+n1 )  \ the stack-diagram ends at the semicolon
    + ( x y -- x+y )            \ less verbose, x+y is the single output

    drop ( x -- )               \ discards top of DATAstack
    dup  ( x -- x x )           \ duplicates top of DATAstack
    over ( x y -- x y x )       \ duplicates second of DATAstack
    swap ( x y -- y x )         \ exchanges second and top of DATAstack

    >r    ( x --   |   == x )
    dup>r ( x -- x |   == x )
    r     (   -- x | x == x )
    r>    (   -- x | x ==   )
    rdrop (   --   | x ==   )

"Computing" cumulative stack-effects is trivial for short sequences; it is good practice to add at end of lines the current DATAstack state to make it easier to follow the data flow on the DATAstack, and check the DATAstack states match at control-flow joins.

A simple example:

  : double  \ n -- 2n
    dup +   \ -- n+n
  ;

Let's use anonymous definitions to test double with different values (note that, as you type the CarriageReturn/NewLine/Enter key after the semicolon to let FreeForth compile your edited line, the . (dot) word prints its output at the beginning of the next line):

  0; 3 double . ;
  6  0; -4 double . ;
  -8  0;

The main arithmetic and logic words (the complete list is available in the ff.help file chapter "INTEGER ARITHMETIC") are:

• + ( x y -- x+y ) addition
• - ( x y -- x-y ) subtraction
• * ( x y -- x*y ) product
• / ( x y -- x/y ) division (truncated)
• % ( x y -- x%y ) modulo
• 1+ ( x -- x+1 ) increment
• 1- ( x -- x-1 ) decrement
• 2* ( x -- 2x ) arithmetic shift left
• 2/ ( x -- x/2 ) arithmetic shift right (signed)
• negate ( x -- -x ) opposite (2's complement)
• ~ ( x -- ~x ) bitwise not (1's complement)
• ^ ( x y -- x^y ) bitwise exclusive-or
• | ( x y -- x|y ) bitwise inclusive-or
• & ( x y -- x&y ) bitwise and
• << ( x y -- x<<y ) logic shift left
• >> ( x y -- x>>y ) logic shift right (unsigned)

  %` ' alias mod`
  ~` ' alias invert`
  ^` ' alias xor`
  |` ' alias or`
  &` ' alias and`
  <<` ' alias lshift`
  >>` ' alias rshift`

Each entry point is declared with the word : (colon) followed by the entry point name, which may be any "word" as defined in the FreeForth Syntax chapter. An entry point must have been declared before its first use: forward references, i.e. forward jumps, are not supported for subroutine entry points (forward references are supported by other control structures).

• to compile a subroutine call to an entry point of a definition, simply use the entry point's name, which must have been previously defined by the word : (colon), as seen in the double example above
• to compile a subroutine return at the end of a definition, simply use the word ; (semicolon)
• to compile a subroutine return inside a definition, use instead the word ;; (double semicolon); as this is an unconditional jump, the next word will never be executed, unless it is the target of another jump, i.e. it is preceded by a THEN or by an END
• instead of the pair of words ;; THEN prefer the shorthand single word ;THEN
• to compile a conditional subroutine return inside a definition, use the word 0; which checks the top of DATAstack, and if null drops it and returns, otherwise lets it on top of DATAstack and continues sequential execution

  : countdown  \ n --
    dup .      \ -- n ; duplicates and displays n
    0;  1-     \ -- n-1 ; if n null, drop&returns, otherwise decrements
    countdown  \ compiles a "call countdown" assemby instruction
  ;            \ changes the "call countdown" into "jmp countdown"
  0; 5 countdown ;
  5 4 3 2 1 0  0;

  0<> 0=  0< 0>=  0<= 0>  C0? C1?   \ --
  <> =  < >=  <= >  u< u>=  u<= u>  \ x y -- x y

  : countdown  \ n --
    dup .      \ -- n ; duplicates and displays n
    1-         \ -- n-1 ; decrements n, this changes the i386 flags
    countdown  \ compiles a "call countdown" assemby instruction
    0>= ?      \ changes the "call countdown" into "jge countdown"
    drop       \ -- ; dispose of the -1 remaining on the DATAstack
  ;            \ this compiles a "ret" assembly instruction
  0; 5 countdown ;
  5 4 3 2 1 0  0;

                    /---> alternativeIfTrue ---\
  ... compute cond?<(fork)                (join)> commonFollowingCode ...
                    \---> alternativeIfFalse---/

• compute is a place holder for arithmetic or logic code which modifies the i386 condition flags
• cond is a place holder for a condition specifier, as described in the previous chapter Unstructured Conditional Jumps
• alternativeIfTrue is a place holder for code to execute when the i386 condition flags match the condition specifier
• alternativeIfFalse is a place holder for code to execute when the i386 condition flags don't match the condition specifier
• commonFollowingCode is a place holder for code to execute after any of the two alternatives

The above graphical representation must be ordered when specified with a textual/sequential language such as FreeForth, where this is done with the three words IF ELSE THEN:

  ... compute cond
  IF   alternativeIfTrue
  ELSE alternativeIfFalse
  THEN
  commonFollowingCode ...

IF ELSE THEN are macros (i.e. executed at compile time) which resolve the forward jumps on the fly, in a single pass:

• IF` compiles a conditional forward jump assembly instruction depending on the opposite of the condition specified by cond (because the jump must not be taken to execute the alternativeIfTrue), and pushes at compile time on the DATAstack the address of the jump-offset byte argument of the jump assembly instruction
• ELSE` compiles an unconditional forward jump jmp assembly instruction, pushes at compile time on the DATAstack the address of the jump-offset byte argument of the jump assembly instruction, then pops at compile time the address pushed by the previous IF, computes the jump offset, and stores it at this address
• THEN` resolves at compile time the previous forward jump, i.e. pops the address pushed by the previous ELSE (or IF if ELSE was omitted), computes the jump offset, and stores it at this address

  : sign  \ n -- ; displays n sign
    0-    \ -- n ; compares n to zero to setup the i386 condition flags
    0< IF ."negative"    \ "0< IF" compiles "jge A" assembly instruction
    ELSE  \ non-negative \ "ELSE" compiles "jmp D; A:" and resolves "jge A"
      0= IF ."null"      \ "0= IF" compiles "jnz B" assembly instruction
      ELSE  ."positive"  \ "ELSE" compiles "jmp C; B:" and resolves "jnz B"
      THEN  \ -- n       \ "THEN" resolves "jmp C" (here is label "C:")
    THEN  \ -- n         \ "THEN" resolves "jmp D" (here is label "D:" = "C:")
    drop  \ -- ; dispose of n remaining on top of DATAstack
  ;
  0; -1 sign ;
  negative  0; 5 sign ;
  positive  0;

• END` compiles no code and resolves all the linked forward jumps, starting from the address contained in the first 32-bits cells of the `mrk compiler variable, until the link address is equal to the second 32-bits cell of the `mrk compiler variable; then, if the code compiled by RTIMES` is found at the start point, END` compiles an rdrop ( -- | n == ) to dispose of the loop count on top of the CALLstack; finally END` restores/pops from the DATAstack at compile time the contents of the `mrk compiler variable
• REPEAT` compiles an unconditional backward jump to the start point; then it does the same thing as END`
• UNTIL` compiles a conditional backward jump to the start point; as for every conditional jump, it must be preceded by a condition specifier (0<> by default), as defined in the above chapter Unstructured Conditional Jumps; then it does the same thing as END`

  \ anonymous definition: displays a multiplication table
  9 TIMES  9 r -    \ -- 9-i     | == i ; i from 8 downto 0, 9-i from 1 upto 9
    9 TIMES  9 r -  \ -- 9-i 9-j | == j ; j from 8 downto 0, 9-j from 1 upto 9
      over*         \ -- 9-i (9-j)*(9-i) ; compute product
      9 <= drop IF space THEN .  \ -- 9-i ; display product right justified
    REPEAT  drop cr \ -- ; dispose of 9-i, "carriage-return" to newline
  REPEAT ;          \ -- ; end of anonymous definition: execute it
   1  2  3  4  5  6  7  8  9 
   2  4  6  8 10 12 14 16 18 
   3  6  9 12 15 18 21 24 27 
   4  8 12 16 20 24 28 32 36 
   5 10 15 20 25 30 35 40 45 
   6 12 18 24 30 36 42 48 54 
   7 14 21 28 35 42 49 56 63 
   8 16 24 32 40 48 56 64 72 
   9 18 27 36 45 54 63 72 81 
   0; 

• TILL` compiles a conditional backward jump to the start point
• WHILE` compiles a conditional forward jump to the end point
• AGAIN` compiles an unconditional backward jump to the start point
• BREAK` compiles an unconditional forward jump to the end point

Note that, as WHILE` and BREAK` use the `mrk compile variable to link the forward jumps of the multi-alternatives control structure, they can be embedded within a nest of two-alternatives control structures, which at compile time use the DATAstack to save/restore their byte-offset addresses, without interfering with the `mrk compiler variable.

The countdown example at the end of the Unstructured Conditional Jumps chapter may be rewritten using a loop control structure:

  : countdown  \ n --
    BEGIN      \ -- n ; marks loop start point "A:"
      dup . 1- \ -- n-1 ; duplicates and displays n, then decrements it
    0< UNTIL   \ -- -1 ; "0< UNTIL" compiles a "jge A" and closes loop
    drop       \ -- ; dispose of the -1 remaining on the DATAstack
  ;

The sign example at the end of the Two-Alternative Control Structure chapter may be rewritten using a multi-alternatives control structure:

  : sign  \ n -- ; displays n sign
    BEGIN 0-  \ -- n ; compares n to zero to setup i386 condition flags
    0< IF ."negative" BREAK \ "BREAK" resolves "0< IF" and compiles forward jump
    0= IF ."null"     BREAK \ "BREAK" resolves "0= IF" and compiles forward jump
          ."positive"       \ default alternative
    END   \ resolves the two forward jumps compiled by the two "BREAK"
    drop  \ -- ; dipose of n remaining on top of DATAstack
  ;

  : check  \ n key @ # -- n ; if n same as key, raise an exception with string
    drop   \ -- n key @ ; dispose of string count, also available at @-1
    >r     \ -- n key | == @ ; move string address away from DATAstack
    = drop \ -- n | == @ ; setup i386 condition flags, dispose of key
    IF r>  \ -- n @ ; get string address back on DATAstack
      1- throw  \ raise an exception with counted string address as errorCode
    THEN   \ -- n | == @ ; this was the DATAstack state before the IF
    rdrop  \ -- n ; dispose of the unused string address on CALLstack
  ;
  : checkwins \ n -- n
    1 "wins_15_points!" check  \ -- n ; check n versus 1
    5 "wins_30_points!" check  \ -- n ; check n versus 5
    8 "wins_40_points!" check  \ -- n ; check n versus 8
  ;
  : wins? \ n -- ; check whether n wins or looses
    checkwins '  \ -- n checkwins ; ' pushes checkwins entry point on DATAstack
    catch        \ -- n r ; r is catch result
    swap .       \ -- r ; displays n followed by a space
    0-           \ -- r ; compares catch result with 0 to setup i386 flags
    0= IF        \ -- 0 ; no throw was executed
      drop       \ -- ; dispose of 0 remaining on top of DATAstack
      ."wins_no_points."
    ;THEN        \ -- @ ; catch result is the counted string address
    c@+          \ -- @+1 # ; get string count and string start address
    type         \ -- ; display string
  ;
  1 wins? ;
  1 wins 15 points!  0; 3 wins? ;
  3 wins no points.  0; 8 wins? ;
  8 wins 40 points!  0;

As in other languages, it is often useful in FreeForth to replace a literal constant by a symbolic constant, which name may carry more meaning than the literal constant value, and which occurences in the source code all refer to a single definition of its corresponding literal value (which modification, if needed, has then to be done in a single place).

To define a symbolic constant, generate its value with an anonymous definition (either with a simple literal constant, or with any computation), and use the defining macro constant` (or its alias equ`), which closes and executes the current anonymous definition, and associates the value popped from the dataStack, with the next word parsed from the source code, to create in the compiler's headers space a new symbol tagged as a symbolic constant, which each later occurence will be compiled into code pushing its value on the dataStack. For example:
1024 equ KB \ one kilobyte
Note that operator-suffixes may be appended to symbolic constants exactly in the same way as for literal constants, as for example:
KB KB* equ MB \ one megabyte
MB KB* equ GB \ one gigabyte

Forthers note a FreeForth symbolic constant definition neither allocates any dictionary heap space, nor spends any time calling and returning from a "centralized" constant definition; instead every reference to a FreeForth symbolic constant is compiled into inline code which execution pushes on the dataStack an embedded copy of the constant value.

The simplest way to create a 32bits variable is:
variable foo creates in the compiler's headers space a symbolic constant named foo equal to the current value of the compiler's heap memory allocation pointer, that it then increments by 4, and initializes at zero the 4 allocated bytes;
foo! ( n -- ) stores into foo the 32bits value n popped from the dataStack;
foo@ ( -- n ) pushes on the dataStack foo's 32bits contents;
foo ( -- @ ) alone pushes on the dataStack foo's base address;
foo off ( -- ) stores 0 into foo (i.e. sets all its bits at zero);
foo on ( -- ) stores -1 into foo (i.e. sets all its bits at one);
foo +! ( n -- ) increments foo's contents by n (note the space between foo and +!);
foo -! ( n -- ) decrements foo's contents by n (note the space between foo and -!).

For variables of other sizes (than 32bits), such as for example for arrays, use:
create bar 8 allot ; creates in the comnpiler's header space a symbolic constant named bar equal to the current value of the compiler's heap allocation pointer, that 8 allot increment by 8, without any initialization of the 8 allocated bytes;
bar c! ( c -- ) stores into bar's first byte the 8 LSBits of c popped from the dataStack;
bar 1+ c@ ( -- c ) pushes on the dataStack bar's second byte;
bar w! ( w -- ) stores into bar's first word the 16 LSBits of w popped from the dataStack;
4 bar+ w@ ( -- w ) pushes on the dataStack bar's third word;
bar! ( n -- ) stores into bar's first long the 32bits value n popped from the dataStack;
bar@ ( -- n ) pushes on the dataStack bar's first long;
bar 2! ( lo hi -- ) stores into bar the two 32bits values hi then lo popped from dataStack;
bar 2@ ( -- lo hi ) pushes on the dataStack bar's 64bits contents;
bar 8 erase ( -- ) clears bar's 8 bytes;
bar 8 $FF fill ( -- ) sets bar's 8 bytes at $FF.

For initializing while allocating memory, such as for example for contant tables, use comma-words:
create table 2 , 1 , 0 , ; creates the symbolic constant table base address where three 32bits values are stored, first 2, then 1, then 0;
, ( n -- ) allocates the next 4 bytes from the heap (4 allot) and stores in them the 32bits of n popped from the dataStack;
w, ( w -- ) allocates the next 2 bytes from the heap (2 allot) and stores in them the 16 LSBits of w popped from the dataStack;
c, ( c -- ) allocates the next byte from the heap (1 allot) and stores in it the 8 LSBits of c popped from the dataStack;
2 4* table+ @ ( -- 0 ) pushes on the dataStack table's third long (at index 2).

WARNING: an easy way to crash FreeForth is to execute an anonymous definition which overwrites itself, such as for example:
create crash 10 TIMES -1 , REPEAT ;
To avoid this, execute a first anonymous definition to allocate memory, then execute a second anonymous definition to initialize the allocated memory:
create safe 40 allot ; safe 10 TIMES -1 over! 4+ REPEAT drop ; \ note the semicolon after allot
You may wonder why the following code doesn't crash:
create safe 40 allot safe 40 $FF fill ;
This is because the semicolon transforms the final call to fill into a jump (this is called "tail-recursion optimization"), then all the anonymous definition instructions are already executed when they are overwritten by the execution of fill (however, if any code were added between fill and the semicolon, the call to fill wouldn't be transformed into a jump, then it would return to code overwritten by its execution, which would eventually crash).

• Read the ff.help file, and use again and again the help command to get online documentation.
• Read the ff.ff file to see which utilities it contains, and how they are coded and commented.
• If you are curious of FreeForth internals, read the long comment at the beginning of the ff.asm file, and explore FreeForth source files.
• If you have any comment about FreeForth, or if you find a bug (and maybe its correction :-) contact me.