fignition‎ > ‎Documentation‎ > ‎

Built-In Definitions

FIGnition is designed to be used immediately for programming. It implements a simple, self-contained language based closely on FIG-forth, a variant of Forth, but with elements borrowed from the Jupiter-Ace computer from the early 1980s. The FIG-forth ROM image has been adapted from the Mark 1 Forth Computer.

As it stands, this section is not yet a programming manual, merely an introduction to FIGnition's built-in definitions. In the meantime, why not look up the Jupiter-Ace User manual or Leo Brodie's Starting Forth.

Forth Definitions

As delivered FIGnition implements the following core definitions, which means they're byte codes implemented in AVR assembler (Note: this description is a little out-of-date. It will be updated to match Firmware 0.9.8 when released):

 Parameters : Return Stack  
 Word  Appended Text
 Stack Effect
 Action
   (lit)    n  When (lit) is compiled it's followed by a 16-bit number which is pushed onto the stack when (lit) is later executed.
 cfa  execute 
 variable
 Expects the Code Field Address of a Forth definition on the stack and executes the definition, modifying the stack accordingly.
   (branch)      When (branch) is compiled, it's followed by a 16-bit target address. When executed (branch) jumps to the target address.
 boolean  (0branch)      When (branch) is compiled, it's followed by a 16-bit target address. When executed (branch) jumps to the target address if boolean==0 or continues execution otherwise.
   (loop)      When (loop) is compiled, it's followed by a 16-bit target address. When executed (loop) increments the current loop index i by 1 and if it's < the loop limit branches back to the target address, or otherwise continues execution.
 n  (+loop)      When (+loop) is compiled, it's followed by a 16-bit target address. When executed (loop) increments the current loop index i by n and if it's < the loop limit branches back to the target address, or otherwise continues execution.
 limit n
 (do)      When (do) is compiled, it starts a new loop. It sets the current loop index to n and the loop limit to limit.
   i    i  Places the current loop index on the stack.
   leave      Sets the current loop index to the loop limit.
 a b
 and    (a&b)  Returns the bitwise and of the top two items on the stack.
 a b
 or
   (a|b)  Returns the bitwise or of the top two items on the stack.
 a b
 xor    (a^b)  Returns the bitwise xor of the top two items on the stack.
 a b
 <<    (a<<b)  Returns a shifted left b times ( equivalent to a * 2 to the power b)
 a b
 >>    (a>>b)  Returns (unsigned) a shifted right b times (equivalent to a / 2 to the power b)
   ;s      Returns from the currently executing Forth definition.
 : addr
 (does)    pfa :
 Returns the parameter field address of the Forth definition which called (does). The pfa is the same as the return address.
  : value
 r>    value :
 Moves the most recent value on the return stack to the top of the data stack.
 value >r  : value
 Moves the top most data stack value to the top of the return stack.
 : value
 r    value : value
 Copies the most recent value on the return stack to the top of the data stack.
 value  0=    boolean  Returns -1 if value was 0, 0 otherwise (it's a logical inversion, a not operation).
 value
 0<
   boolean  Returns -1 if value was <0, 0 otherwise.
 a b
 +    (a+b)  Returns the sum of a and b.
 low(a) high(a) low(b) high(b)
 d+   low(a+b) high(a+b)
 a and b are 32-bit values stored on the stack with the low word first then the high word for each parameter. d+ returns the 32-bit sum of a and b.
 a  minus    -a  Returns the negation of a.
 low(a) high(a)
 dminus    low(-a), high(-a)
 a is a 32-bit value stored on the stack with the low word first then the high word. Returns the 32-bit negation of a.
 a b
 over    a b a
 Duplicates the last-but-one item on the stack.
 a  drop      Removes the top item from the stack.
 a b
 swap    b a
 Swaps the two most recent items on the stack.
 a  dup   a a
 Duplicates the most recent item on the stack.
 addr  @    Mem[addr]  Returns the memory contents of the 16-bit word addressed at addr. See the understand it section for an explanation of FIGnition memory.
 addr  c@    Mem[addr]  Returns the unsigned memory contents of the 8-bit byte addressed at addr. See the understand it section for an explanation of FIGnition memory.
 value addr
 !      Stores the 16-bit value in Mem[addr].
 value addr
 c!      Stores the 8-bit value in Mem[addr].
 a b
 u*    low(a*b) high(a*b)
 Calculates the unsigned 32-bit result of a*b and stores it on the stack in low-high order.
 low(a) high(a) b
 u/    a%b a/b
 Given the 32-bit value a, Returns the modulus of a mod b and a / b.
 ch  emit      Displays the character ch on the screen and advances the cursor. Character 13 puts the cursor onto a new line, character 7 moves the cursor left overwriting the previous character with a space.
   key    ch  Waits for the user to type a key and returns the character typed.
   inkey    ch  If the user had typed a key, return it else return 0. inkey is the substitute for ?terminal in most Forth implementations.
 addr  i@    AvrMem[addr]  Returns the memory contents of the 16-bit word addressed at addr in the AVR's internal RAM. See the understand it section for an explanation of FIGnition memory.
 addr  ic@    AvrMem[addr]  Returns the unsigned memory contents of the 8-bit byte addressed at addr in the AVR's internal RAM. See the understand it section for an explanation of FIGnition memory.
 value addr  i!    AvrMem[addr]  Stores the 16-bit value in the AVR's internal memory at address addr.
 value addr  ic!    AvrMem[addr]  Stores the least significant 8 bits of value in the AVR's internal memory at address addr.
   vram    addr  Returns the internal RAM address of the video memory.
   clock    addr  Returns the internal RAM address of the 16-bit clock (which increments at 50Hz).
 x y
 at      Sets the display's print position to column x, row y.
   cls      Fills the screen with spaces.
 value  .hex      Displays value in hexadecimal.
 src
 edit      Reads in block number src and starts the editor.
 blockNum  list      Lists block numbered blockNum to the screen.
   trace      Starts the internal trace debugger (it will be disabled on Distribution).
 x y  plot     Plots a point in the current pen mode (see pen)
 blk  blk>    phys Copies disk block blk to the screen and returns its physical page.
 blk phys  >blk    phys Copies disk block blk from the screen to physical page phys.
 orMask andMask port  >port>    oldVal Atomic port access, sets port=(port&andMask)|orMask and returns the old port's contents. See understanding it section on Atomic Access.
 spiInfo  spi     Spi Driver, see the Understanding It section on Spi.

And the following words which themselves are implemented in Forth, which also means they are defined in terms of the above byte codes and compile as 16-bit addresses (Note: this description is a little out-of-date. It will be updated to match Firmware 0.9.8 when released):

Parameters: Return stack
Word
Following Text
Stack Effect
Action

cr


Moves the print position to the  beginning  of the next line, scrolling the screen if necessary.
addr
count

addr+1 len
Given the starting address of a length:text string, returns the address of the text and its length.
addr len
type


Displays len characters of the text from addr.

space


Displays a space character
n
spaces


Displays n space characters

(.")


When compiled, expects text to follow in the format: lengthByte, text and displays the text accordingly (see also .")
src dst len
cmove


Copies len bytes starting at address src to address dst.
dst len ch
fill


Fills len bytes starting at address dst with character ch
dst len
erase


Fills len bytes starting at address dst with character 0
dst len
blanks


Fills len bytes starting at address dst with the space character
value
var
name

creates a variable called name and initialises it to value. Subsequently name returns the address of the variable.
value
const
name

creates a constant called name and initialises it to value. Subsequently, name returns the value.
value addr
+!


Adds value to the variable at addr.
value addr
toggle


Xors value with the variable at addr, storing the result in the variable
value
1+

value+1
Increments value by 1
value
2+

value+2
Increments value by 2

here

addr
Returns the location of the first byte after all the definitions in the Forth system
byteCount
allot


Allocates byteCount bytes at the end of here and adjusts here accordingly.
value
,


Called 'comma'. Allocates 2 bytes to the end of the Forth definitions and stores value in the allocated space.
value
c,


Called 'c-comma'. Allocates 1 byte to the end of the Forth definitions and stores the least significant byte of value in the allocated space.
a b
-

a-b
Subtracts the most recent number entered from the last-but-one number entered, returning the result
a b
=

boolean
Returns -1 if a = b, or 0 otherwise.
a b
<

boolean
Returns -1 if a < b, or 0 otherwise.
a b
>

boolean
Returns -1 if a > b, or 0 otherwise.
a b c
rot

b c a
Like swap, but takes the third most recent number entered and moves it to the most recently entered number
a b
2dup

a b a b
Duplicates the two most recently entered numbers in turn, equivalent to dup but for a 32-bit value
a b
nip

b
Drops the second most recently entered number.
a
?dup

a a (if a!=0)
Duplicates the most recently entered number if it isn't 0
a b
u<

boolean
If (unsigned)a < (unsigned)b then returns -1, or 0 otherwise.

latest

nfa
Returns the name field address of the most recent definition (see Understanding forth definitions).
pfa
pfa>cfa

addr
Converts a parameter field address to a code field address (see Understanding forth definitions)
pfa
pfa>nfa

addr
Converts a parameter field address to a name field address (see Understanding forth definitions)
nfa
nfa>lfa

addr
Converts a name field address to its link field address (see Understanding forth definitions)
nfa
nfa>pfa

addr
Converts a name field address to its parameter field address (see Understanding forth definitions)
nfa
id.


Given a name field address, displays the definition's name.
errNum
message


Displays "Msg#" and then the error number
errNum
error


If the warning<0 restarts Forth, else displays the errNum using message and then does quit.
boolean errNum
?error


If boolean is true, then does error otherwise, continues as normal.

?comp


Tests for the compile/interpret state and gets ?error to generate error 11 if it's in interpret state.

:
definitionName

Marks the beginning of a new procedure/function whose name is definitionName. Puts Forth into compile mode.

;


Ends the current procedure/function and returns to interpret mode.

immediate


Marks the most recent definition as an immediate word (a word which always runs, even in compile mode).
cfa
x,


Compiles a cfa. If the cfa u< 0x100 it compiles a byte otherwise it compiles a full word.

compile

state
Compiles the following word into the instruction stream as a cfa, returning the compilation state

[


Takes the system into interpret mode (usually used within compile mode to switch temporarily into interpret mode).

]

state
Takes the system into compile mode.

smudge


Modifies the latest word's 'smudge' bit so that it can be seen in the dictionary.

<builds
definitionName (at runtime)

Used within a colon definition e.g. definerWord to create a new definition header for definitionName when definerWord definitionName is subsequently executed.

does>


Used within a colon definition to end the definition part and mark the beginning of the action part of a defining word.

(
text

Marks the beginning of a comment (terminated by ')' ). The comment isn't compiled into the code.

hex


Causes numbers to be interpreted in base 16.

decimal


Causes numbers to be interpreted in base 10
ch base
digit

n
Converts a character in base base into its value n. Bases larger than 10(decimal) use capital letters A..F. [@TODO: Support Lower-case as well]
Low(n) High(n) addr
(number)

Low(n) High(n)
Converts a series of digit characters at addr into a value in the current base which is shifted into n (i.e. for each digit n is muliplied by base and the new digit is added). Terminates when a non-digit is found.
addr
number

Low(n) High(n)
Converts a signed 16-bit (or 32-bit) number at addr into a 32-bit value in the current base using (number). 32-bit numbers are denoted by a '.' within the characters.
textAddr delim
enclose

addr 1st ew nc
Forth's generic parser. Parses text from textAddr, skipping initial whitespace and then searches the subsequent text until the delimiter is found or there are no more characters. [@TODO, explain and rename the return parameters]
delim
word


Copies text from the Terminal Input Buffer to the word buffer until the delimiter is found

-find
name
pfa nameLength boolean
Searches the dictionary for name returning its parameter field address, the length of the name and -1 if the name was found

create
name

Creates a new, smudged raw header called name. It can't yet be found in the dictionary and it can't be executed.

[compile]
name

An immediate word. Compiles name into the instruction stream.
n
literal


An immediate word. Compiles the top value on the stack into the instruction stream.
Low(n) High(n)
dliteral


An immediate word. Compiles the top 32-bit value on the stack into the instruction stream.
addr maxChars
expect


Reads characters into addr up to maxChars. Handles delete and new line (but no other editing chars, so cursor keys just end up being displayed as block graphics or UDGs)

interpret


Interprets the input in the Terminal Input Buffer

query


Inputs a line of text into the tib and then resets the current tib input offset to 0.

quit


The interpreter. Takes Forth into interpret mode, inputs a line of text and interprets it. Displays "OK" at the end if Forth hasn't been taken into compile mode.

abort


Displays the startup message and then restarts the interpreter (Quit).

cold


'Resets' Forth, erasing all its defined words and then calls abort.
n
s->d

Low(n) High(n)
Converts a signed 16-bit value into it's 32-bit equivalent.
Low(n) High(n) boolean
d+-

Low(-n) High(-n)
If boolean<0, negates n.
n
abs

abs(n)
Negates n if n was negative.
Low(n) High(n)
dabs

Low(abs(n)) High(abs(n))
Negates n if n was negative (32-bit version)
a b
min

min(a,b)
Returns the minimum of a and b
a b
max

max(a,b)
Returns the maximum of a and b
a b
m*

Low(a*b) High(a*b)
Multiplies two signed 16-bit values, returning the 32-bit result (like u*, but for signed inputs).
a b
m*

Low(a*b) High(a*b)
Multiplies two signed 16-bit values, returning the signed 32-bit result (like u*, but for signed inputs).
a b
*

a*b
Multiplies two signed 16-bit values, returning the signed 16-bit result (like u*, but for signed inputs).
Low(value) High(value) divisor
m/

remainder result
Divides the 32-bit signed value by a signed 16-bit divisor returning a 16-bit remainder and 16-bit result
a b c
*/mod

(a*b/c)
Calculates a*b/c, but uses an intermediate 32-bit result for a*b to avoid overflow.
value divisor
/mod

remainder result
Divides the 16-bit signed value by a signed 16-bit divisor returning a 16-bit remainder and 16-bit result
value divisor
/

result
Divides the 16-bit signed value by a signed 16-bit divisor returning the 16-bit result
value divisor
mod

remainder
Divides the 16-bit signed value by a signed 16-bit divisor returning the 16-bit remainder
Low(value) High(value) divisor
m/mod

remainder Low(result) High(result)
Divides the 32-bit unsigned value by an unsigned 16-bit divisor returning the 16-bit remainder and an unsigned 32-bit result

'
name

(Tick). Used in colon definitions. Compiles the pfa into the instruction stream.
n
back


Compiles a jump target into the instruction stream (used in compilation words).

begin

here 1(at compile time only)
The beginning of a begin ... until; begin ... while ... repeat or begin ... again construct. The compiler places a check code and the target address for begin onto the stack for later processing by until, while, or again
jumpTarget checkCode (at compile time only)
then


The end of an if .. else .. then construct. At run time, does nothing. At compile time expects a checkCode of 2 on the stack and generates an error otherwise. Sets the jumpTarget to the current compilation address (here).
jumpTarget checkCode (at compile time only)
endif


Equivalent to then
loopLimit startingLoopValue (run time only)
do

here 3 (at compile time only)
The beginning of a do ... loop or do ...+loop construct. At run-time starts a do loop, saving the loopLimit in i' and startingLoopValue in i. At compile time, the compiler compiles a (do) instruction then places a check code and the target address for do onto the stack for later processing by loop, or +loop
jumpTarget checkCode (at compile time only)
loop


The end of a do ... loop. construct. At runtime increments i and if it's <i' loops back to its do instruction. At compile time expects a checkCode of 3 on the stack and generates an error otherwise. Compiles the (loop) instruction then the jumpTarget at the current compilation address (here).
n (at run-time only), jumpTarget checkCode (at compile time only)
+loop


The end of a do ... loop. construct. At runtime adds n to i and if it's <i' loops back to its do instruction. At compile time expects a checkCode of 3 on the stack and generates an error otherwise. Compiles the (+loop) instruction then the jumpTarget at the current compilation address (here).
jumpTarget checkCode (at compile time only)
again


The end of a begin ... again. construct. At runtime jumps back to it's begin instruction. At compile time expects a checkCode of 1 on the stack and generates an error otherwise. Compiles a branch to jumpTarget into the instruction stream at (here).
jumpTarget1 checkCode1 jumpTarget2 checkCode2 (at compile time only)
repeat


The end of a begin .. while .. repeat. construct. At runtime jumps back to its begin instruction unless the while instruction returned true. At compile time compiles in an again part (to do the jump back) and then an endif to set the jump from the while part to the current compilation point (here).
n (at run-time only) jumpTarget checkCode (at compile time only)
end


Equivalent to until
boolean (at run-time only)
if

here 2 (at compile time only)
The beginning of an if ... else then construct. At Run-time continues execution if boolean isn't false or jumps to else or then otherwise. At compile time, the compiler places a check code and the target address for if onto the stack for later processing by else or then
jumpTarget checkCode (at compile time only)
else

here 2 (at compile time only)
The optional middle of an if ... else then construct. At Run-time marks the beginning of the else part. At compile time, the compiler checks that checkCode is 2 and stores the current compilation address at jumpTarget if so (so that if can jump to else). It also places the same check code and a new target address for onto the stack for later processing by then
boolean (run-time only); jumpTarget1 checkCode1 (at compile time only)
while

jumpTarget1 checkCode1 here 2 (at compile time only)
The optional middle of an begin .. while ... repeat construct. At Run-time continues execution if boolean isn't false otherwise jumps to after its repeat. At compile time, the compiler checks that checkCode is 1 and then adds a new checkCode of 1 and jump target address for onto the stack for later processing by repeat
value
hold


Pushes value onto the PAD; that is, it decrements hld then stores value at hld.

pad

padAddress
Returns the end of the pad, which in our case is 68b after here.

<#


Resets hld to the end of the pad. <# is used to initialise number conversion. (see Understanding It - Text Processing).
Low(value) High(value)
#>

offset
Ends number conversion by dropping value and returning the offset of the number from the pad (ie. -length)
Low(value) High(value)
sign


Pushes a '-' onto the PAD if value is < 0.
Low(value) High(value)
#

Low(value/base) High(value/base)
Pushes the least significant digit of value in the current base onto the PAD returning value/base.
Low(value) High(value)
#s

0 0
Repeats # until value=0, i.e it converts all the remaining digits of value into text.
Low(value) High(value) fieldWidth
d.r


Given a 32-bit value and a fieldWidth, displays it as a double number padded out to fieldWidth characters with spaces.
Low(value) High(value)
d.


Given a 32-bit value and a remainder, displays it as a double number padded out to its natural width followed by a space.
value
.r


Given a 16-bit value and a fieldWidth, displays it as a number padded out to fieldWidth characters with spaces.
value
.


Given a 16-bit value, displays it as a number padded out to natural width followed by a space.
addr
?


Given the address of a 16-bit value, displays its contents as a number padded out to natural width followed by a space. It's useful for directly displaying a variable without having to type @ . .
blockNum
load


Loads the given block number and continues interpreting from that block. [@TODO, it should push the current interpretation state, load the block and then restore the interpetation state so that blocks can be loaded recursively].

vlist


Lists the current set of words. [@TODO: It should pause after every screen.]

forget
name

Removes name and all subseequent definitions from the dictionary.
n
pen


Sets the pen drawing mode: 0=move (but don't anything), 1=plot, 2=unplot, 3=Plot_Over. See Understanding FIGnition graphics.

0

0
The constant 0 specially redefined to save memory space.

1

0
The constant 1 specially redefined to save memory space.

2

0
The constant 2 specially redefined to save memory space.

3

0
The constant 3 specially redefined to save memory space.

bl

32
The constant 32 (a space character).

tib

addr
Returns the address of the Terminal Input Buffer.


References

[1] The Jupiter Ace User's Manual.
[2] Starting Forth By Leo Brodie.


Comments