Glossary
Curious what's inside ?
Here comes a summary of the routines included in the 9kb of the plain vanilla Mecrisp core
Terminal-IO
?key ( -- Flag ) Checks if a key is waiting
key ( -- Char ) Waits for and fetches the pressed key
emit ( Char -- ) Emits a character.
Stack Jugglers (exactly ANS, some logical extensions)
Single-Jugglers:
depth ( -- +n ) Gives number of single-cell stack items.
nip ( x1 x2 -- x2 )
drop ( x -- )
rot ( x1 x2 x3 -- x2 x3 x1 )
swap ( x1 x2 -- x2 x1 )
tuck ( x1 x2 -- x2 x1 x2 )
over ( x1 x2 -- x1 x2 x1 )
?dup ( x -- 0 | x x )
dup ( x -- x x )
>r ( x -- ) (R: -- x )
r> ( -- x ) (R: x -- )
r@ ( -- x ) (R: x -- x )
Double-Jugglers: They perform the same for double numbers.
2nip ( x1 x2 x3 x4 -- x3 x4 )
2drop ( x1 x2 -- )
2rot ( x1 x2 x3 x4 x5 x6 -- x3 x4 x5 x6 x1 x2 )
2swap ( x1 x2 x3 x4 -- x3 x4 x1 x2 )
2over ( x1 x2 x3 x4 -- x1 x2 x3 x4 x1 x2 )
2dup ( x1 x2 -- x1 x2 x1 x2 )
2>r ( x1 x2 -- ) (R: -- x1 x2 )
2r> ( -- x1 x2 ) (R: x1 x2 -- )
2r@ ( -- x1 x2 ) (R: x1 x2 -- x1 x2 )
Logic (exactly ANS, some logical extensions)
>< ( xy -- yx ) Swap bytes
rshift ( x1 u -- x2 ) Logical right-shift of u bit-places
lshift ( x1 u -- x2 ) Logical left-shift of u bit-places
shr ( x1 -- x2 ) Logical right-shift of one bit-place
shl ( x1 -- x2 ) Logical left-shift of one bit-place
bic ( x1 x2 -- x3 ) Bit clear, identical to "not and"
not ( x1 -- x2 ) Invert all bits
xor ( x1 x2 -- x3 ) Bitwise Exclusive-OR
or ( x1 x2 -- x3 ) Bitwise OR
and ( x1 x2 -- x3 ) Bitwise AND
Calculus for single numbers (exactly ANS, some logical extensions)
um* ( u1 u2 -- ud ) 16*16 = 32 Multiplication
u/mod ( u1 u2 -- u3 u4 ) 16/16 = 16 rem 16 Division
u1 / u2 = u4 remainder u3
/mod ( n1 n2 -- n3 n4 ) n1 / n2 = n4 rem n3
mod ( n1 n2 -- n3 ) n1 / n2 = remainder n3
/ ( n1 n2 -- n3 ) n1 / n2 = n3
* ( u1|n1 u2|n2 -- u3|n3 ) 16*16 = 16 Multiplication
min ( n1 n2 -- n1|n2 ) Keeps smaller of top two items
max ( n1 n2 -- n1|n2 ) Keeps greater of top two items
2- ( u1|n1 -- u2|n2 ) Subtracts two, optimized
1- ( u1|n1 -- u2|n2 ) Subtracts one, optimized
2+ ( u1|n1 -- u2|n2 ) Adds two, optimized
1+ ( u1|n1 -- u2|n2 ) Adds one, optimized
even ( u1|n1 -- u2|n2 ) Makes even. Adds one if uneven.
2* ( n1 -- n2 ) Arithmetric left-shift
2/ ( n1 -- n2 ) Arithmetric right-shift
abs ( n -- u ) Absolute value
?negate ( n1 n2 -- n3 ) Negate n1 if n2 is negative
negate ( n1 -- n2 ) Negate
- ( u1|n1 u2|n2 -- u3|n3 ) Subtraction
+ ( u1|n1 u2|n2 -- u3|n3 ) Addition
Calculus involving double numbers (exactly ANS, some logical extensions)
*/ ( n1 n2 n3 -- n4 ) n1 * n2 / n3 = n4
*/mod ( n1 n2 n3 -- n4 n5 ) n1 * n2 / n3 = n5 remainder n4
m/mod ( d n1 -- n2 n3 ) d / n1 = n3 remainder r2
m* ( n1 n2 -- d ) n1 * n2 = d
um/mod ( ud u1 -- u2 u3 ) ud / u1 = u3 remainder u2
ud/mod ( ud1 ud2 -- ud3 ud4 ) 32/32 = 32 rem 32 Division
ud1 / ud2 = ud4 remainder ud3
udm* ( ud1 ud2 -- ud3-Low ud4-High ) 32*32=64 Multiplication
d2/ ( d1 -- d2 ) Arithmetric right-shift
d2* ( d1 -- d2 ) Arithmetric left-shift
dabs ( d -- ud ) Absolute value
?dnegate ( d1 n -- d2 ) Negate d1 if n is negative
dnegate ( d1 -- d2 ) Negate
d- ( ud1|d1 ud2|d2 -- ud3|d3 ) Subtraction
d+ ( ud1|d1 ud2|d2 -- ud3|d3 ) Addition
s>d ( n -- d ) Makes a signed single number double length
Comparisions (exactly ANS, some logical extensions)
Single-Comparisions:
u<= ( u1 u2 -- flag ) Unsigned comparisions
u>= ( u1 u2 -- flag )
u> ( u1 u2 -- flag )
u< ( u1 u2 -- flag )
<= ( n1 n2 -- flag ) Signed comparisions
>= ( n1 n2 -- flag )
> ( n1 n2 -- flag )
< ( n1 n2 -- flag )
0< ( n - flag ) Negative ?
0<> ( x -- flag )
0= ( x -- flag )
<> ( x1 x2 -- flag )
= ( x1 x2 -- flag )
Double-Comparisions: They perform the same for double numbers.
du> ( ud1 ud2 -- flag )
du< ( ud1 ud2 -- flag )
d> ( d1 d2 -- flag )
d< ( d1 d2 -- flag )
d0< ( d -- flag )
d0= ( d -- flag )
d<> ( d1 d2 -- flag )
d= ( d1 d2 -- flag )
Tools (not only) for s15.16 fixed point numbers (speciality!)
Fixpoint numbers are stored ( n-comma n-whole ) and can be handled
like signed double numbers.
f/ ( df1 df2 -- df3 ) Division of two fixpoint numbers
f* ( df1 df2 -- df3 ) Multiplication
hold< ( char -- )
Adds character to pictured number output buffer
from behind.
f#S ( n-comma1 -- n-comma2 )
Adds 16 comma-digits to number output
f# ( n-comma1 -- n-comma2 )
Adds one comma-digit to number output
f. ( df -- )
Prints a fixpoint number
number ( Counted-String-Address -- 0 )
cstr-addr -- n 1 )
-- n-low n-high 2 )
Tries to convert a string to a number.
Number base (exactly ANS)
binary ( -- ) Sets base to 2
decimal ( -- ) Sets base to 10
hex ( -- ) Sets base to 16
base ( -- a-addr ) Base variable address
Memory access (subtle differences to ANS, special cpu-specific extensions)
Ram and ports:
move ( c-addr1 c-addr2 u -- ) Moves u Bytes in Memory
cbit@ ( mask c-addr -- flag ) Test BIts in byte-location
bit@ ( mask a-addr -- flag ) Test BIts in word-location
cxor! ( mask c-addr -- ) Toggle bits in byte-location
xor! ( mask a-addr -- ) Toggle bits in word-location
cbic! ( mask c-addr -- ) Clear BIts in byte-location
bic! ( mask a-addr -- ) Clear BIts in word-location
cbis! ( mask c-addr -- ) Set BIts in byte-location
bis! ( mask a-addr -- ) Set BIts in word-location
2constant name ( ud|d -- ) Makes a double constant.
constant name ( u|n -- ) Makes a single constant.
2variable name ( ud|d -- ) Makes an initialized double variable
variable name ( n|n -- ) Makes an initialized single variable
nvariable name ( n1*u|n n1 -- ) Makes an initialized variable with
specified size of n1 words
Maximum is 15 words
+! ( u|n a-addr -- ) Add to memory location
2! ( ud|d a-addr -- ) Stores double number in memory
2@ ( a-addr -- ud|d ) Fetches double number from memory
c! ( char c-addr ) Stores byte in memory
c@ ( c-addr -- char ) Fetches byte from memory
! ( u|n a-addr -- ) Stores single number in memory
@ ( a-addr -- u|n ) Fetches single number from memory
Flash:
eraseflash ( -- ) Erases everything. Clears Ram. Restarts Forth.
cflash! ( char c-addr -- ) Writes byte to flash
flash! ( u|n a-addr -- ) Writes single number to flash
Strings and beautiful output (subtle differences to ANS)
String routines:
compare ( cstr-addr-1 cstr-addr-2 -- flag )
Compares two counted strings
skipstring ( cstr-addr -- a-addr )
Increases the pointer to the aligned end of the string.
type ( cstr-addr -- )
Prints a counted string.
s" Hello" Compiles a string and
( -- cstr-addr )
gives back its address when executed.
." Hello" Compiles a string and
( -- )
prints it when executed.
Pictured numerical output:
.digit ( u -- char ) Converts a digit to a char
digit ( char -- u ) Converts a char to a digit
[char] * Compiles code of following char
( -- char ) when executed
char * ( -- char ) gives code of following char
hold ( char -- ) Adds character to pictured number
output buffer from the front.
sign ( n -- ) Add a minus sign to pictured number
output buffer, if n is negative
#S ( ud1|d1 -- 0 0 ) Add all remaining digits
from the double length number to output buffer
# ( ud1|d1 -- ud2|d2 ) Add one digit from the
double length number to output buffer
#> ( ud|d -- cstr-addr )
Drops double number and finishes
pictured numeric output ready for type
<# ( -- ) Prepare pictured number output buffer
u. ( u -- ) Print unsigned single number
. ( n -- ) Print single number
ud. ( ud -- ) Print unsigned double number
d. ( d -- ) Print double number
Deep insights:
words ( -- ) Prints list of defined words.
.s ( many -- many ) Prints stack contents
.rs ( R: many -- many ) Prints return stack contents
User input and its interpretation (more FIG style, speciality!)
query ( -- ) Fetches user input to input buffer
token ( -- cstr-addr ) Cuts one token out of input buffer
parse ( char -- cstr-addr )
Cuts anything delimited by char out of input buffer
interpret ( any -- any ) Execute, compile, fold, optimize...
quit ( many -- ) (R: many -- ) Resets Stacks
Dictionary expansion (speciality!)
, ( u|n -- ) Appends a single number to dictionary
c, ( char -- ) Appends a byte to dictionary
align, ( -- ) Makes Dictionary Pointer even, if uneven.
string, ( cstr-addr -- ) Inserts a string without runtime
literal, ( u|n -- ) Compiles a literal with runtime
2literal, ( ud|d -- ) Compiles a double literal with runtime
inline, ( a-addr -- ) Inlines the choosen subroutine
call, ( a-addr -- ) Compiles a call to a subroutine
jump, ( Hole-for-Opcode Destination Bitmask ) Writes a Jump
to a-addr-Destination with the given Bitmask as
Opcode into the cell sized a-addr-Hole
ret, ( -- ) Compiles a ret opcode
allot ( n -- ) Tries to advance Dictionary Pointer by n bytes
Aborts, if not enough space available
here ( -- a-addr|c-addr )
Gives current position in Dictionary
compiletoram ( -- ) Makes ram the target for compiling
compiletoflash ( -- ) Makes flash the target for compiling
Flags and inventory (speciality!)
smudge ( -- ) Makes current definition visible, burns
collected flags to flash and
takes care of proper ending
inline ( -- ) Makes current definition inlineable.
For flash, place it inside your definition !
immediate ( -- ) Makes current definition immediate.
For flash, place it inside your definition !
setflags ( char -- ) Sets Flags with a mask. This isn't immediate,
but for flash, place it inside your definition !
create name ( -- ) Creates and links a new invisible dictionary
header that does nothing.
Use FIG-style <builds .. does> !
find ( cstr-addr -- a-addr flags )
Searches for a String in Dictionary.
Gives back flags, which are different to ANS !
Compiler essentials (subtle differences to ANS)
execute ( a-addr -- ) Calls subroutine
recurse ( -- ) Lets the current definition call itself
' name ( -- a-addr ) Tries to find name in dictionary
gives back executable address
['] name ( -- a-addr) Tick that compiles the executable address
of found word as literal
postpone name ( -- ) Helps compiling immediate words.
does> ( -- ) executes: ( -- a-addr )
Gives address to where you have stored data.
<builds ( -- ) Makes Dictionary header and reserves space
for special call.
state ( -- a-addr ) Address of state variable
] ( -- ) Switch to compile state
[ ( -- ) Switch to execute state
; ( -- ) Finishes new definition
: name ( -- ) Opens new definition
Control structures (exactly ANS)
Internally, they have complicated compile-time stack effects.
?pairs ( u1 u2 -- ) Aborts, if u1 and u2 are not equal
Decisions:
flag if ... then
flag if ... else ... then
then ( -- ) This is the common
else ( -- ) flag if ... [else ...] then
if ( flag -- ) structure.
Case:
n case
m1 of ... endof
m2 .. ... .....
flag ?of ... endof
all others
endcase
case ( n -- n ) Begins case structure
of ( m -- ) Compares m with n, choose this if n=m
?of ( flag -- ) Flag-of, for custom comparisions
endof ( -- ) End of one possibility
endcase ( n -- ) Ends case structure, discards n
Indefinite Loops:
begin ... again
begin ... flag until
begin ... flag while ... repeat
repeat ( -- ) Finish of a middle-flag-checking loop.
while ( flag -- ) Check a flag in the middle of a loop
until ( flag -- ) begin ... flag until
loops as long flag is true
again ( -- ) begin ... again
is an endless loop
begin ( -- )
Definite Loops:
limit index do ... [one or more leave(s)] ... loop
?do ... [one or more leave(s)] ... loop
do ... [one or more leave(s)] ... n +loop
?do ... [one or more leave(s)] ... n +loop
k ( -- u|n ) Gives third loop index
j ( -- u|n ) Gives second loop index
i ( -- u|n ) Gives innermost loop index
unloop (R: old-limit old-index -- )
Drops innermost loop structure,
pops back old loop structures to loop registers
exit ( -- ) Returns from current definition.
Compiles a ret opcode.
leave ( -- ) (R: old-limit old-index -- )
Leaves current innermost loop promptly
+loop ( u|n -- )
(R: unchanged | old-limit old-index -- )
Adds number to current loop index register
and checks whether to continue or not
loop ( -- )
(R: unchanged | old-limit old-index -- )
Increments current loop index register by one
and checks whether to continue or not.
?do ( Limit Index -- )
(R: unchanged | -- old-limit old-index )
Begins a loop if limit and index are not equal
do ( Limit Index -- )
(R: -- old-limit old-index )
Begins a loop
Hardware access
Reads analog-digital-converter
analog ( u-channel -- u-value ) with 2.5 V reference voltage
adc-1.5 ( u-channel -- u-value ) with 1.5 V reference voltage
adc-vcc ( u-channel -- u-value ) with Vcc as reference
dint ( -- ) Disables Interrupts
eint ( -- ) Enables Interrupts
nop ( -- ) No Operation. Hook for unused IRQs !
irq-port1 ( -- a-addr ) Memory locations for IRQ-Hooks
irq-port2
irq-adc
irq-timera1
irq-timera0
irq-watchdog
irq-timerb1
irq-timerb0
irq-comp only in msp430g2553