Subversion Repositories forth-cpu

\ ==== Boot Block ==============================================

-1 loaded !

; ==== Short Help ==============================================

This is a subroutine threaded Forth, based on eForth. The

starting base in in hexadecimal. A tutorial, word glossary and

extra code is stored in block storage. A short list of commands

follows ('#' are numbers):

  words       list all Forth words

  see         decompile the next word in the input stream

  # #2 index  get descriptive titles for blocks from '#' to '#2'

  # list      list block number '#'

  # load      execute code in block '#'

  # #2 thru   execute code in blocks '#' to '#2'

; ==== Forth Error Messages: 1/4 ===============================

  -1 ABORT

  -2 ABORT"

  -3 stack overflow

  -4 stack underflow

  -5 return stack overflow

  -6 return stack underflow

  -7 do-loops nested too deeply during execution

  -8 dictionary overflow

  -9 invalid memory address

 -10 division by zero

 -11 result out of range

 -12 argument type mismatch

 -13 undefined word

 -14 interpreting a compile-only word

 -15 invalid FORGET

; ==== Forth Error Messages: 2/4 ===============================

 -16 attempt to use zero-length string as a name

 -17 pictured numeric output string overflow

 -18 parsed string overflow

 -19 definition name too long

 -20 write to a read-only location

 -21 unsupported operation

 -22 control structure mismatch

 -23 address alignment exception

 -24 invalid numeric argument

 -25 return stack imbalance

 -26 loop parameters unavailable

 -27 invalid recursion

 -28 user interrupt

 -29 compiler nesting

 -30 obsolescent feature

; ==== Forth Error Messages: 3/4 ===============================

 -31 >BODY used on non-CREATEd definition

 -32 invalid name argument (e.g., TO xxx)

 -33 block read exception

 -34 block write exception

 -35 invalid block number

 -36 invalid file position

 -37 file I/O exception

 -38 non-existent file

 -39 unexpected end of file

 -40 invalid BASE for floating point conversion

 -41 loss of precision

 -42 floating-point divide by zero

 -43 floating-point result out of range

 -44 floating-point stack overflow

 -45 floating-point stack underflow

; ==== Forth Error Messages: 4/4 ===============================

 -46 floating-point invalid argument

 -47 compilation word list deleted

 -48 invalid POSTPONE

 -49 search-order overflow

 -50 search-order underflow

 -51 compilation word list changed

 -52 control-flow stack overflow

 -53 exception stack overflow

 -54 floating-point underflow

 -55 floating-point unidentified fault

 -56 QUIT

 -57 exception in sending or receiving a character

 -58 [IF], [ELSE], or [THEN] exception

; ==== Description of this file ================================

The next screens contain extra code that can be loaded into the

interpreter if needed. Some of the standard Forth words are

placed here instead of in the image to save on space.

The blocks should be loaded in order unless otherwise stated.

This file is first converted by a utility into a fixed width

format, which can then be loaded onto the target board with

the same utility used to uploaded the bitfile to the FPGA.

Line lengths are limited to 64 characters wide, each block

contains 16 lines. The first line should contain a

description of the block so that when it is displayed with

'index' a glossary can be viewed, allowing quick navigation.

; ==== Scratch Block ===========================================

\ ==== Block Editor 1/2 ========================================

( Block Editor: There is a help section later on )

variable editor-voc 0 editor-voc ! forth

: editor decimal editor-voc 1 set-order ;

get-order editor-voc swap 1+ set-order

$40 constant c/l $10 constant l/b

: (block) blk @ block ;

: (check) dup b/buf c/l / u>= if -24 throw then ;

: (line) (check) c/l * (block) + ;

: b block drop ;

: l blk @ list ;

: n  1 +block b l ;

: p -1 +block b l ;

: d (line) c/l blank ;

: x (block) b/buf blank ;

: s update save-buffers ;

\ ==== Block Editor 2/2 ========================================

: q forth save-buffers ;

: e forth blk @ load editor ;

: ia c/l * + (block) + source drop >in @ +

  swap source nip >in @ - cmove [compile] \ ;

: i 0 swap ia ;

: u update ;

: w words ;

: yank pad c/l ;

: c (line) yank >r swap r> cmove ;

: y (line) yank cmove ;

: ct swap y c ;

: ea (line) c/l evaluate ;

: sw 2dup y (line) swap (line) swap c/l cmove c ;

forth

\ ==== Assembler word set ======================================

variable assembler-voc

bl parse rdrop pad pack$ find drop assembler-voc !

: assembler assembler-voc 1 set-order ;

: ;code assembler ; immediate

: code [compile] : assembler ;

get-order assembler-voc swap 1+ set-order

: end-code forth [compile] ; ; immediate

: words words ;

: forth forth ;

forth

\ ==== CORDIC 1/2 ==============================================

variable lookup -1 cells allot ( 16 values )

$3243 , $1DAC , $0FAD , $07F5 , $03FE , $01FF , $00FF , $007F ,

$003F , $001F , $000F , $0007 , $0003 , $0001 , $0000 , $0000 ,

: arshift ( n u -- n : arithmetic right shift )

  2dup rshift >r swap $8000 and

  if $10 swap - -1 swap lshift else drop 0 then r> or ;

$26DD constant cordic_1K $6487 constant pi/2

variable tx 0 tx ! variable ty 0 ty ! variable tz 0 tz !

variable x  0  x ! variable y  0  y ! variable z  0  z !

variable d  0  d ! variable k  0  k !

\ ==== CORDIC 2/2 ==============================================

( CORDIC: valid in range -pi/2 to pi/2, arguments are in fixed )

( point format with 1 = 16384, angle is given in radians.  )

: cordic ( angle -- sine cosine )

  z ! cordic_1K x ! 0 y ! 0 k !

  $10 begin ?dup while

    z @ 0< d !

    x @ y @ k @ arshift d @ xor d @ - - tx !

    y @ x @ k @ arshift d @ xor d @ - + ty !

    z @ k @ cells lookup + @ d @ xor d @ - - tz !

    tx @ x ! ty @ y ! tz @ z !

    k 1+!

    1-

  repeat y @ x @ ;

: sin cordic drop ;

: cos cordic nip ;

\ ==== Login Code 1/2 ==========================================

\ Login and user management system: @todo clear up with vocabs

: generate count dup >r crc r> ccitt ; ( b -- u )

: .user     ." user>" space ; ( -- )

: .password ." password>" space ; ( -- )

variable user0 0 user0 !

: mk.user ( --; ,  )

  here user0 @ , user0 ! here 0 , bl word count 1+ allot align

  drop bl word generate swap ! ;

: ls.user ( -- : list all users in user database )

  cr user0 @

  begin dup while dup 2 cells + space count type cr @ repeat

  drop cr ;

: find.user ( a -- u | 0 : find user in database, return hash )

  >r user0 @ begin dup while dup 2 cells + count r@ count

  =string if rdrop exit then @ repeat rdrop drop 0 ;

\ ==== Login Code 2/2 ==========================================

: (password) ( u --,  )

  >r begin .password query bl word cr generate

  r@ = until rdrop ;

: fake .password query bl word drop cr ;

: (user)

  begin .user query bl word cr find.user ?dup until ;

: retry ( xt -- : retry word until it succeeds )

  >r begin r@ catch 0= until rdrop ;

: user?     ' (user)     retry ;

: password? ' (password) retry ;

: hide-all 0 1 set-order ;

: login hide-all

  cr user? cell+ @ conceal password? interactive forth ;

mk.user guest guest     mk.user archer dangerzone

mk.user lana  sterling  mk.user cyril  figgis

\ ==== Extra Code 1/7 ==========================================

: 2+ 2 + ;                       ( n -- n )

: 2- 2 - ;                       ( n -- n )

: >= < invert ;                  ( n n -- f )

: simulation? cpu-id $cafe <> ; ( -- f : are we in the matrix? )

: 0<= 0> 0= ;                    ( n n -- f )

: 0>= 0< 0= ;                    ( n n -- f )

: not -1 xor ;                   ( n -- n )

: dabs dup 0< if dnegate then ;  ( d -- d )

: d+  >r swap >r um+ r> r> + + ; ( d d -- d )

: d=  >r swap r> = >r = r> and ; ( d d -- f )

: d<> d= 0= ;                    ( d d -- f )

: roll  dup 0> if swap >r 1- recurse r> swap else drop then ;

: ?exit if rdrop then ;          ( n --, R: n -- n | )

: 2rdrop r> rdrop rdrop >r ;     ( R n n -- )

: 2. swap . . ;                  ( n n -- )

\ ==== Extra Code 2/7 ==========================================

: m* 2dup xor 0< >r abs swap abs um* r> if dnegate then ;

: */mod  >r m* r> m/mod ;  ( n n n -- r q )

: */  */mod nip ;          ( n n n -- q )

: s>d dup 0< ;             ( n -- d : single to double )

: holds begin dup while 1- 2dup + c@ hold repeat 2drop ;

: binary  2 base ! ;                       ( -- )

: octal  8 base ! ;                        ( -- )

: .base base @ dup decimal base ! ; ( -- )

: only -1 set-order ;

: also get-order over swap 1+ set-order ;

: previous get-order swap drop 1- set-order ;

: buffer block ; ( k -- a )

: bye [ 0 , ] ;

: enum dup constant 1+ ; ( n --,  )

: logical 0= 0= ;     ( n -- f )

\ ==== Extra Code 3/7 ==========================================

: square dup * ;      ( n -- )

: limit rot min max ; ( n lo hi -- n )

: odd 1 and logical ; ( n -- )

: even odd invert ;   ( n -- )

: nor or invert ;     ( u u -- u )

: nand and invert ;   ( u u -- u )

: bell 7 emit ;       ( -- )

: under >r dup r> ;   ( n1 n2 -- n1 n1 n2 )

: 2nip >r >r 2drop r> r> ; ( n1 n2 n3 n4 -- n3 n4 )

( n1 n2 n3 n4 -- n1 n2 n3 n4 n1 n2 )

: 2over >r >r 2dup r> swap >r swap r> r> -rot ;

: 2swap >r -rot r> -rot ; ( n1 n2 n3 n4 -- n3 n4 n1 n2 )

: 2tuck 2swap 2over ; ( n1 n2 n3 n4 -- n3 n4 n1 n2 n3 n4 )

: 4drop 2drop 2drop ; ( n1 n2 n3 n4 -- )

: trip dup dup ; ( n -- n n n )

\ ==== Extra Code 4/7 ==========================================

: log  >r 0 swap ( u base -- u )

  begin swap 1+ swap r@ / dup 0= until

  drop 1- rdrop ;

: log2 0 swap ( u -- u )

  begin swap 1+ swap   2/ dup 0= until

  drop 1- ;

: average um+ 2 um/mod nip ; ( u u -- u )

: <=> 2dup > if 2drop -1 exit then < ;

: bounds over + swap ;

: 2, , , ; ( n n -- )

: tab 9 emit ; ( -- )

: drup drop dup ; ( n1 n2 -- n1 n1 )

: lsb $ff and ; ( u -- u )

: --> 1 +block load ;

: scr blk ;

\ ==== Extra Code 5/7 ==========================================

: signum ( n -- -1 | 0 | 1 : Signum function )

  dup 0> if drop  1 exit then

      0< if      -1 exit then

: >< dup 8 rshift swap 8 lshift or ; ( u -- u : swap bytes )

: #digits dup 0= if 1+ exit then base @ log 1+ ;

: ** ( n u -- n )

  ?dup if

    over >r

    begin

      dup 1 >

    while

      swap r@ * swap 1-

    repeat rdrop drop

  else logical 1 and then ;

\ ==== Extra Code 6/7 ==========================================

: b. base @ swap 2 base ! u. base ! ; ( u -- )

: h. base @ swap hex u. base ! ;      ( u -- )

: o. base @ swap 8 base ! u. base ! ; ( u -- )

: d. base @ swap decimal . base ! ;   ( n -- )

: @bits swap @ and ;                  ( a u -- u )

: ?\ if [compile] \ then ; immediate

: ?( if [compile] ( then ; immediate ( )

: defined? ( -- pwd -1 | 0,  : is word defined? )

  bl word find if -1 else drop 0 then ;

: ?if compile dup [compile] if ; immediate

: ?dup-if compile ?dup [compile] if ; immediate

: >body ( dup @ $4000 or <> if 31 -throw then ) cell+ ;

\ ==== Extra Code 7/7 ==========================================

: screens ( k1 k2 -- : list blocks k1 to k2 )

  over -

  for

    dup . dup list 1+ nuf? if rdrop drop exit then

  next drop ;

\ ==== Roulette ================================================

\ Russian Roulette: It would be interesting to do something

\ killed the computer when the player dies

: click ."  *click*" cr ;

: bang  ."  BANG!" cr ;

: roulette random 6 mod if click else bang then ; ( -- )

\ ==== Extended ANSI Escape Codes ==============================

red green        + constant yellow

    green blue   + constant cyan

red       blue   + constant magenta

red green blue + + constant white

: background $a + ;

: color $1e + sgr ;

\ : hide-cursor CSI [char] ? emit $19 10u. [char] l emit ;

\ : show-cursor CSI [char] ? emit $19 10u. [char] h emit ;

: up    [char] A ansi ; ( n -- )

: down  [char] B ansi ; ( n -- )

: left  [char] C ansi ; ( n -- )

: right [char] D ansi ; ( n -- )

\ ==== Screen Saver ============================================

\ An incredibly simple screen saver using ANSI Escape codes

\ for placement and coloring of random characters

: screen-saver ( -- )

  page

  begin

    random 80 mod

    random 40 mod at-xy

    random >char emit

    random 8  mod

    ( random 1 and if background then )

    color

  again ;

; ==== Game: YOU ARE DEAD (HELP) ===============================

This is a clone of the one dimensional rogue like game

available at . The

object is to get to the other side of the screen.

Keys:

w  Turn into '.'

a  Turn into '~'

s  Turn into '>'

d  Move right

q  Quit

Block number 7 is used to store the game state.

\ ==== Game: YOU ARE DEAD 1/6 ==================================

forth variable yad-voc get-order yad-voc swap 1+ set-order

$40 constant c/l $10 constant l/b

: memory 7 block ;

: variables memory c/l + ;

: score    variables 0 cells + ;

: position variables 1 cells + ;

: level    variables 2 cells + ;

: form     variables 3 cells + ;

: continue variables 4 cells + ;

: end c/l 1- ;

: player form @ ;

: .player position @ 1+ 3 at-xy player emit ;

: .goal c/l 3 at-xy [char] # emit ;

: .score ." SCORE: " score @ 5 u.r ;

: .level ." LEVEL: " level @ 5 u.r ;

\ ==== Game: YOU ARE DEAD 2/6 ==================================

: show

  page cr cr space memory c/l type

  .player .goal

  cr .score space .level cr ;

: select ( n -- c )

  dup 0=  if drop [char] <  exit then

  dup 1 = if drop [char] ~  exit then

  dup 2 = if drop [char] .  exit then

  drop bl ;

: die ." YOU ARE DEAD" cr 0 continue ! -56 throw ;

: survived ." YOU SURVIVED" cr .score cr ;

: forms form c@ position @ memory + c@ ; ( -- c c )

\ ==== Game: YOU ARE DEAD 3/6 ==================================

: generate ( -- generate a level )

  c/l 1- for

    random 5 mod ( 3 = most difficult )

    select memory r@ + c!

  next

  bl memory c! bl memory end + c! ;

: normal [char] x ;

: setup ( -- )

  -1 continue !

  memory b/buf 0 fill

  normal form c!

  generate ;

: +score random 4 mod 1 min score +! ; ( -- )

: ?next <> if die else +score then ; ( c c -- )

\ ==== Game: YOU ARE DEAD 4/6 ==================================

: +level

  random 23 mod 5 min score +!

  generate ;

: monster swap >r forms r> = if ?next else 2drop then ;

: command ( -- f )

  dup [char] w = if drop [char] . form c! 0 exit then

  dup [char] a = if drop [char] ~ form c! 0 exit then

  dup [char] d = if drop -1 exit then

  dup [char] s = if drop [char] < form c! 0 exit then

  dup [char] q = if drop -56 throw then

  drop 0 ;

\ ==== Game: YOU ARE DEAD 5/6 ==================================

: rules

  position @ end = if +level exit then

  forms = if exit then

  [char] ~ [char] < monster

  [char] . [char] ~ monster

  [char] < [char] . monster

  normal form c!

  bl position @ memory + c!

  score 1+!

  position 1+! ;

\ ==== Game: YOU ARE DEAD 6/6 ==================================

: game

  begin

  show

  key command if rules then

  level @ 9 >

  until survived ;

: play setup ' game catch drop ;

get-order -rot swap rot set-order

: you-are-dead base @ decimal play base ! ;

forth

\ : resume memory drop ' game catch drop ;

; ==== Brain F*ck Compiler Help 1/2 ============================

Brainfuck is a simple esoteric language with only 8 commands, it

is Turing complete which means it can compute any function which

can be computed - although it is very difficult to do so. The

commands operate on a block of memory 1024 bytes long. A data

pointer indexes into the memory. The commands are:

  >  increment the data pointer

  <  decrement the data pointer

  +  increment value at data pointer

  -  decrement value at data pointer

  .  output byte at data pointer

  ,  accept one byte and store it at data pointer

  [  branch forward to ] if byte at data pointer is zero

  ]  branch back    to [ if byte at data pointer is non-zero

The compiler discards all other input.

; ==== Brain F*ck Compiler Help 2/2 ============================

The following blocks implement the compiler, it translates each

command in a given string into Forth code, compiling it into a

new word definition which can then be executed.

Needless to say, it is not a useful language, but it is fun!

Some example programs are given after the compiler block.

This Forth brain fuck compiler was derived from the one

available Rosetta Code, and so is licensed under the

GNU Free Documentation License [v1.2]. See:

And for more information see:

\ ==== Brain F*ck Compiler 1/2 =================================

: left over c!  1- dup c@ ;

: right over c! 1+ dup c@ ;

: erase 0 fill ;

: initialize pad b/buf erase pad 0 ;

: bf-compile ( c -- )

  >r

  r@ [char] [ = if [compile] begin

                   compile dup [compile] while then

  r@ [char] ] = if [compile] repeat            then

  r@ [char] + = if compile 1+                  then

  r@ [char] - = if compile 1-                  then

  r@ [char] < = if compile left                then

  r@ [char] > = if compile right               then

  r@ [char] , = if compile drop compile key    then

  r@ [char] . = if compile dup  compile emit   then rdrop ;

\ ==== Brain F*ck Compiler 2/2 =================================

: bf ( b u --, : compile brainfuck program into a word )

  >r >r

  [compile] :

  compile initialize

  r> r> for aft

    dup 1+ >r c@ bf-compile r>

  then next

  drop

  compile swap

  compile c@

  compile 2drop

  [compile] ; ;

\ Example, making a simple echo like program called 'cat':

\ : string $" +[,.]" count ; string bf cat

; ==== Brain F*ck Example Programs =============================

From: http://www.hevanet.com/cristofd/brainfuck/short.b

Hello World: ++++++++[>++++[>++>+++>+++>+<<<<-]>+>+>->>+[<]<-]

>>.>---.+++++++..+++.>>.<-.<.+++.------.--------.>>+.>++.

Clear Screen: ++++++++++[>++++++++++>+<<-]>[>.<-]

Beep: +++++++.

Copy Input to Output: ,[.[-],]

Reverse Input: >,[>,]<[.<]

Translate text to brain fuck that prints said Text:

+++++[>+++++++++<-],[[>--.++>+<<-]>+.->[<.>-]<<,]

; ==== eForth v6.66: Help and Tutorial =========================

This Forth is modeled after eForth, described in a book by

C.H. Ting called "eForth Overview", or "The Zen of eForth". It

implements most of the eForth model with some changes expected

from a more modern Forth system.

The processor targeted is called the H2, a rewrite of the

J1 processor ().

It has been extended with a few more instructions and with

interrupts. The system resides on an FPGA Nexys 3 board from

Digilent, with words and peripherals designed for it.

For more see: 

; ==== Help: Introduction ======================================

Forth is a simple, imperative, stack based language that mixes

elements of a high level language with a low level language. It

is possible to fit a small Forth system in a few kilobytes of

RAM complete with an interactive read-evaluate-print loop, an

editor, an assembler and a disassembler.

It is also a language that has fallen out of favor in recent

times (after the micro-computer era) as it is not a very safe

language, nor is it one that allows the programmer to easily

create reusable and maintainable software components.

However it is still suitable for a number of purposes; for

assemblers, to bring up hardware and test it, in memory

constrained systems, as a boot loader, and for fun.

; ==== Help: Philosophy of Forth ===============================

Forth itself has its own philosophy, one in which the programmer

should have a complete understanding of the system, from the

problem that needs to be solved, the algorithms needed to solve

it, the hardware and the software. As the latter two, the

hardware and software are usually very simple in Forth systems

it is possible to optimize the problem across multiple domains,

tailoring each to come up with a solution. Forth eschews

complexity, preferring one off, bespoke solutions. Another

reason it has not seen widespread use.

Advocates of the language are usually quite passionate about

it (as with Lisp, and other niche systems) so it is important

to be pragmatic about Forth. Forth is simply a tool and when

used correctly can be used productively.

; ==== Help: Basics 1/6 ========================================

A Forth system contains an interactive interpreter that parses

text and either compiles or executes functions, called 'words'

in Forth terminology. The system uses Reverse Polish Notation

(RPN) and provides the user with two stacks and a 'dictionary'

(a big block of memory containing 'words' and other data).

The interpreter reads from an input device, such as a keyboard

or a serial port, and writes output to the screen or back over

the serial port. Words and number input are space delimited and

are either compiled into the dictionary depending on the

interpreter mode and whether the word read in is 'immediate'

or not.

This tutorial will describe how to use Forth and how the

interpreter works internally.

; ==== Help: Basics 2/6 ========================================

To start with, simple expressions can be entered and the

results displayed. A line is evaluated after the carriage

return is entered, code will be indented, this can be typed in.

We will start off with a simple expression, adding two numbers

together and displaying the result:

  ( Comments appear within brackets )

  2 2 + .

This prints out '4' and 'ok'. 'ok' is printed out after every

line has been successfully compiled, unless we are in compile

mode. '+' obviously does the addition, and '.' pops a value

off the stack an prints it. Entering a number pushes it onto

the data stack.

; ==== Help: Basics 3/6 ========================================

The data, or variable, stack is a general purpose stack that

the programmer uses to pass data to functions, and to return

data from functions. The stacks are an important concept

within Forth and stack management will take up a lot of a Forth

programmers time.

Numbers are entered in Reverse Polish Notation, this allows

Forth interpreter to immediate process a word or a function as

it is encountered instead of building up a parse tree.

When '2' is encountered it is pushed onto the variable stack,

when the second '2' is input, it is also pushed onto the stack.

The Forth word '+' takes two arguments off the stack, adds them

together and pushes the result back onto the stack. The word

'.' pops a single number off the stack and prints it.

; ==== Help: Basics 4/6 ========================================

Manipulating the stack will be difficult at first, but gets

easier over time. There are standard words for stack

manipulation and a standard methodology for describing

stack effects called 'stack comments'.

A stack comment is a short comment describing the stack before

and after execution of the word, and the type of the arguments

it accepts and returns. For example the stack comment for '+'

is:

  + ( n n -- n : add two numbers together )

All text between '(' and the ')' is discarded by the Forth

system. This comment describes a word that accepts two

signed numbers "n n", and returns a signed number "n".

; ==== Help: Basics 5/6 ========================================

The "--" divides the comment into what the stack looks like

before execution of the word (to the left of "--") and what it

looks like after (to the right of "--"). A comment on the

behavior of the word comes after the semicolon.

Here is a list of some common Forth words and their stack

comments:

  dup  ( n -- n n : duplicate first item on the stack )

  swap ( n1 n2 -- n2 n1 : swap first two items on stack )

  drop ( n -- : drop a value from the stack )

Stack effects are sometimes numbered, which is used to

so the effects on specific arguments can be documented if

the order of arguments and return values matter.

; ==== Help: Basics 6/6 ========================================

Some more words with comments:

  @    ( a -- u : load value from memory address )

  !    ( u a -- : store 'u' at memory location 'a' )

  <    ( n1 n2 -- f : is n1 greater than n2, signed )

  u<   ( u1 u2 -- f : is u1 greater than n2, unsigned )

These words have stack comments, some with numbered arguments,

but they use different letters. The different letters are used

to describe the type of the arguments that the word accepts.

'@', also known as load, takes an address, and '!', takes

an address and a value. "<" takes two signed numbers, "u<"

takes two unsigned numbers and produces a flag. Type checking

is not performed by Forth and is up to the programmer.

; ==== Help: Stack Comments ====================================

Here is a list of stack type descriptions and what they mean:

| Comment  | Meaning                             |

|----------|-------------------------------------|

| a        | cell address                        |

| n        | signed number                       |

| u        | unsigned number                     |

| b        | string address                      |

| c        | single character                    |

| d        | double width number (2 Cells)       |

| f        | boolean flag (-1 = true, 0 = false) |

| k        | block number                        |

| cfa      | code field address of a word        |

| nfa      | name field address of a word        |

| pwd      | previous word address of a word     |

|  | a parsing word                      |

; ==== Help: Expressions =======================================

Let us continue on with some interactive examples before we

start to define new words. Before we saw a trivial example

of adding two numbers together, we will go over a few more

operators first.

  9 2 + . ( Displays 'B', the default base is hexadecimal )

  decimal ( Change the input and output base to decimal )

  9 2 + . ( Displays '11' )

  3 4 dup * swap dup * + . ( Displays 3^2 + 4^2 or 25 )

Negative numbers can be input by prefixing the number with

'-':

  -2 4 * . ( Display -8 )

; ==== Help: Numeric Output 1/2 ================================

The word '.' pops a value off the stack before displaying it,

if we want to examine the stack without popping the value we

can print out the entire contents of the stack with '.s':

  1 2 3 .s ( prints "1 2 3 

  .        ( prints "3" )

  .s       ( prints "1 2 

"

stack. Other useful words for debugging include '?' that

prints the contents at a memory address and 'dump', which

prints a memory dump of a region of memory.

  dump ( a u -- )

  ?    ( a -- )

; ==== Help: Numeric Output 2/2 ================================

Hexadecimal numbers can be entered if the base input and output

base is 16, or by prefixing the number with '$'.

  decimal  $aaa . ( Displays 2730 )

          -$aaa . ( Displays -2730 )

eForth starts up in base 16, valid bases range anywhere from

2 to 36. The base can be changed by either setting a variable

'base' to the desired base, or with the words 'hex' to change

the base back into hexadecimal, or 'decimal' to change the base

to '10'. Variables in Forth are words that leave an address on

the stack when they are called. They can be read or set with

'@' and '!'. For example, "$10 base !" and "hex" are

equivalent, as are "$a base !" and "decimal".

; ==== Help: Word Definitions 1/2 ==============================

For the moment we have not covered how words are defined and

is a good time to do so, the word ":" is used to create a new

word definition and the word ";" is used to terminate one.

Words once defined are added to the 'dictionary', which is

consists of a linked list of words, hence the name

'dictionary'. We can define new words interactively like we can

type expressions in, such as:

  : square dup * ; ( n -- n : square a number )

We can then use square like any other word:

  4 square .  ( prints 16 )

  -5 square . ( prints 25 )

; ==== Help: Word Definitions 2/2 ==============================

'hex' and 'decimal' are defined as:

  : hex $10 base ! ;

  : decimal $a base ! ;

And simple Forth words likewise defined:

  : 2- 2 - ;      ( u -- u : decrement a number by 2 )

  : 2+ 2 + ;      ( u -- u : increment a number by 2 )

  : 2* 1 lshift ; ( u -- u : multiply a number by 2 )

  : 1+ 1 + ;      ( u -- u : increment a number by 1 )

  : negate invert 1+ ; ( n -- n : negate, twos compliment )

It is best to keep all Forth words as short as possible and

reuse code as much as possible.

; ==== Help: Interpreter Loop 1/3 ==============================

All functions, control structures, defining words such as ":",

and simple functions like "square" or "hex" are simply Forth

words, which are either defined in terms of other Forth words

or in terms of primitive operations supported by the H2 CPU.

Currently this does not explain how compilation happens. When

the word ":" is encountered it does multiple things such as

compiling a word header into the dictionary, and it does one

more thing - it puts the Forth system into compile mode. The

system starts out in command mode, in this mode words are

executed, and numbers are pushed onto the stack. In compile

mode, a call to the word is compiled (or an assembly

instruction is inlined) and numbers of turned into literals

that push their value when run.

; ==== Help: Interpreter Loop 2/3 ==============================

There is a special class of words called "immediate" words, ";"

is an immediate word, when it is encountered instead of being

compiled into the dictionary it is executed, it compiles an

exit instruction to terminate the word definition and it puts

the Forth system back into command mode.

Not only are control structures sets of words, like "if",

"else", "then", "begin", "until", but so are words like "("

and "\" which are used to process comments. When executed

they read from the input stream until the they find a ")" or

end of line respectively.

Variables, strings, and defining words (defining words are

that create new words) are all simply Forth words that are

either compiling or immediate, their is no special syntax.

; ==== Help: Interpreter Loop 3/3 ==============================

The command loop goes like this:

Start) Fetch a space delimited word, find it in the dictionary

   Found) Is the system in compile mode?

          Yes) Is the word immediate?

               Yes) Execute It

               No)  Compile a call to it / In-line it

          No)  Execute the word

   Not Found) Is the word a number?

          Yes) Is the system in compile mode?

               Yes) Compile the number

               No)  Push the number onto the stack

          No)  Error!

This simple loop is invoked by the work 'quit' which uses

'query' to fetch and parse the input and 'interpreter' to

perform the state dependent action.

; ==== Help: Control Structures 1/10 ===========================

This will give you some idea what is going on when control

structures are covered in the following blocks. Control

structures can only be used within a word definition, that

is in compile mode, if used in command mode they simply throw

an error.

Some of the control structures available to Forth are:

  if ... then

  if ... else ... then

  for ... next

  for ... aft ... then ... next

  begin ... until

  begin ... again

  begin ... while ... repeat

; ==== Help: Control Structures 2/10 ===========================

Recursion is also available with the 'recurse' word. There

are more advance control flow methods available that will be

described later (such as 'catch', 'throw' and manipulating the

return stack).

"if...then" will be described first. First a simple example,

we will define a word called 'abs' that will return the

absolute value of a number, that is negative numbers will be

turned into positive numbers and positive numbers will stay

the same. This will require the word 'negate' which changes

the sign of a number and '0<' which tests if a number is

negative, their stack effect comments are:

  0<     ( n -- f )

  negate ( n -- n )

; ==== Help: Control Structures 3/10 ===========================

The word 'abs' is then defined as:

  : abs dup 0< if negate then ;

'if' takes an argument off the stack at run time and jumps to

after the 'then' if it is false (zero), if it is true (non-

zero) the negate is performed. From now if a word is shown in

a definition that has not been previously mentioned please

refer to the glossary. We can can use the definition of the

word 'abs' as soon as we terminate the definition with ";":

  -9 abs . ( displays 9 )

   4 abs . ( displays 4 )

This Forth uses two complements to represent negative numbers.

; ==== Help: Control Structures 4/10 ===========================

A number can be negated in twos compliment form by performing

a bitwise not on the number and adding one to it, this is what

the word 'negate' does.

"if...else...then" control structures can be created:

  : min 2dup < if drop else nip then ; ( n n -- n )

  : max 2dup > if drop else nip then ; ( n n -- n )