1
0
mirror of https://github.com/hsoft/collapseos.git synced 2024-11-26 09:38:06 +11:00

Compare commits

...

5 Commits

Author SHA1 Message Date
Virgil Dupras
fca0e79da3 cmp: fix & and | logic
It simply didn't work before, except for =.
2020-04-05 17:36:07 -04:00
Virgil Dupras
74a32db5cc Move forth/*.txt to root folder 2020-04-05 16:12:28 -04:00
Virgil Dupras
974018831e Add chained comparison support 2020-04-05 16:11:17 -04:00
Virgil Dupras
7b34268a9a Add "DUMP" word 2020-04-05 13:53:03 -04:00
Virgil Dupras
7df7416e9e fmt: add word ".x" and fix .X to 4 chars output
Simpler code, more predictable output.
2020-04-05 12:15:43 -04:00
6 changed files with 182 additions and 74 deletions

View File

@ -1,21 +1,11 @@
Be sure to read "usage.txt" for a guide to Collapse OS' Forth.
*** Glossary ***
Stack notation: "<stack before> -- <stack after>". Rightmost is top of stack
(TOS). For example, in "a b -- c d", b is TOS before, d is TOS after. "R:" means
that the Return Stack is modified. "I:" prefix means "IMMEDIATE", that is, that
this stack transformation is made at compile time.
DOES>: Used inside a colon definition that itself uses CREATE, DOES> transforms
that newly created word into a "does cell", that is, a regular cell ( when
called, puts the cell's addr on PS), but right after that, it executes words
that appear after the DOES>.
"does cells" always allocate 4 bytes (2 for the cell, 2 for the DOES> link) and
there is no need for ALLOT in colon definition.
At compile time, colon definition stops processing words when reaching the
DOES>.
Example: ": CONSTANT CREATE HERE @ ! DOES> @ ;"
Word references (wordref): When we say we have a "word reference", it's a
pointer to a words *code link*. For example, the label "PLUS:" in this unit is a
word reference. Why not refer to the beginning of the word struct? Because we
@ -54,20 +44,6 @@ IMMEDIATE -- Flag the latest defined word as immediate.
LITN n -- Write number n as a literal.
VARIABLE c -- Creates cell x with 2 bytes allocation.
Compilation vs meta-compilation. When you compile a word with "[COMPILE] foo",
its straightforward: It writes down to HERE wither the address of the word or
a number literal.
When you *meta* compile, it's a bit more mind blowing. It fetches the address
of the word specified by the caller, then writes that number as a literal,
followed by a reference to ",".
Example: ": foo [COMPILE] bar;" is the equivalent of ": foo bar ;" if bar is
not an immediate. However, ": foo COMPILE bar ;" is the equivalent of
": foo ['] bar , ;". Got it?
Meta-compile only works with real words, not number literals.
*** Flow ***
Note about flow words: flow words can only be used in definitions. In the
INTERPRET loop, they don't have the desired effect because each word from the
@ -156,32 +132,6 @@ SLEN a -- n Push length of str at a.
*** I/O ***
A little word about inputs. There are two kind of inputs: direct and buffered.
As a general rule, we read line in a buffer, then feed words in it to the
interpreter. That's what "WORD" does. If it's at the End Of Line, it blocks and
wait until another line is entered.
KEY input, however, is direct. Regardless of the input buffer's state, KEY will
return the next typed key.
PARSING AND BOOTSTRAP: Parsing number literal is a very "core" activity of
Forth, and therefore generally seen as having to be implemented in native code.
However, Collapse OS' Forth supports many kinds of literals: decimal, hex, char,
binary. This incurs a significant complexity penalty.
What if we could implement those parsing routines in Forth? "But it's a core
routine!" you say. Yes, but here's the deal: at its native core, only decimal
parsing is supported. It lives in the "(parsed)" word. The interpreter's main
loop is initially set to simply call that word.
However, in core.fs, "(parsex)", "(parsec)" and "(parseb)" are implemented, in
Forth, then "(parse)", which goes through them all is defined. Then, "(parsef)",
which is the variable in which the interpreter's word pointer is set, is
updated to that new "(parse)" word.
This way, we have a full-featured (and extensible) parsing with a tiny native
core.
(parse) a -- n Parses string at a as a number and push the result
in n as well as whether parsing was a success in f
(false = failure, true = success)
@ -193,11 +143,15 @@ core.
number parsing. By default, (parse).
(print) a -- Print string at addr a.
. n -- Print n in its decimal form
.X n -- Print n in its hexadecimal form. In hex, numbers
.x n -- Print n's LSB in hex form. Always 2 characters.
.X n -- Print n in hex form. Always 4 characters. Numbers
are never considered negative. "-1 .X" --> ffff
." xxx" -- *I* Compiles string literal xxx followed by a call
to (print)
are never considered negative. "-1 .X -> ffff"
C< -- c Read one char from buffered input.
DUMP n a -- Prints n bytes at addr a in a hexdump format.
Prints in chunks of 8 bytes. Doesn't do partial
lines. Output is designed to fit in 32 columns.
EMIT c -- Spit char c to output stream
IN> -- a Address of variable containing current pos in input
buffer.

View File

@ -1,6 +1,6 @@
TARGETS = runbin/runbin forth/forth
# Those Forth source files are in a particular order
FORTHSRCS = core.fs print.fs str.fs parse.fs readln.fs fmt.fs z80a.fs
FORTHSRCS = core.fs cmp.fs print.fs str.fs parse.fs readln.fs fmt.fs z80a.fs
FORTHSRC_PATHS = ${FORTHSRCS:%=../forth/%} forth/run.fs
OBJS = emul.o libz80/libz80.o
SLATEST = ../tools/slatest

38
forth/cmp.fs Normal file
View File

@ -0,0 +1,38 @@
( Words useful for complex comparison operations )
( n1 -- n1 true )
: <>{ 1 ;
( n1 f -- f )
: <>} SWAP DROP ;
: _|&
( n1 n2 cell )
>R >R DUP R> R> ( n1 n1 n2 cell )
@ EXECUTE ( n1 f )
;
( n1 f n2 -- n1 f )
: _|
CREATE , DOES>
( n1 f n2 cell )
ROT IF 2DROP 1 EXIT THEN ( n1 true )
_|&
;
: _&
CREATE , DOES>
( n1 f n2 cell )
ROT NOT IF 2DROP 0 EXIT THEN ( n1 true )
_|&
;
( All words below have this signature:
n1 f n2 -- n1 f )
' = _| |=
' = _& &=
' > _| |>
' > _& &>
' < _| |<
' < _& &<

View File

@ -1,7 +1,6 @@
( requires core, parse )
( TODO FORGET this word )
: PUSHDGTS
: _
999 SWAP ( stop indicator )
DUP 0 = IF '0' EXIT THEN ( 0 is a special case )
BEGIN
@ -16,7 +15,7 @@
( that "0 1 -" thing is because we don't parse negative
number correctly yet. )
DUP 0 < IF '-' EMIT 0 1 - * THEN
PUSHDGTS
_
BEGIN
DUP '9' > IF DROP EXIT THEN ( stop indicator, we're done )
EMIT
@ -25,24 +24,53 @@
: ? @ . ;
: PUSHDGTS
999 SWAP ( stop indicator )
DUP 0 = IF '0' EXIT THEN ( 0 is a special case )
BEGIN
DUP 0 = IF DROP EXIT THEN
16 /MOD ( r q )
SWAP ( r q )
: _
DUP 9 > IF 10 - 'a' +
ELSE '0' + THEN ( q d )
SWAP ( d q )
AGAIN
ELSE '0' + THEN
;
: .X ( n -- )
( For hex display, there are no negatives )
PUSHDGTS
( For hex display, there are no negatives )
: .x
256 MOD ( ensure < 0x100 )
16 /MOD ( l h )
_ EMIT ( l )
_ EMIT
;
: .X
256 /MOD ( l h )
.x .x
;
( a -- a+8 )
: _
DUP ( save for 2nd loop )
':' EMIT DUP .x SPC
4 0 DO
DUP @
256 /MOD SWAP
.x .x
SPC
2 +
LOOP
DROP
8 0 DO
DUP C@
DUP <>{ 0x20 &< 0x7e |> <>}
IF DROP '.' THEN
EMIT
1 +
LOOP
LF
;
( n a -- )
: DUMP
LF
BEGIN
DUP 'f' > IF DROP EXIT THEN ( stop indicator, we're done )
EMIT
OVER 1 < IF DROP EXIT THEN
_
SWAP 8 - SWAP
AGAIN
;

88
usage.txt Normal file
View File

@ -0,0 +1,88 @@
Collapse OS usage guide
This document is not meant to be an introduction to Forth, but to instruct the
user about the peculiarities of this Forth implemenation. Be sure to refer to
dictionary.txt for a word reference.
*** DOES>
Used inside a colon definition that itself uses CREATE, DOES> transforms that
newly created word into a "does cell", that is, a regular cell ( when called,
puts the cell's addr on PS), but right after that, it executes words that appear
after the DOES>.
"does cells" always allocate 4 bytes (2 for the cell, 2 for the DOES> link) and
there is no need for ALLOT in colon definition.
At compile time, colon definition stops processing words when reaching the
DOES>.
Example: ": CONSTANT CREATE HERE @ ! DOES> @ ;"
*** Compilation vs meta-compilation
Compilation vs meta-compilation. When you compile a word with "[COMPILE] foo",
its straightforward: It writes down to HERE wither the address of the word or
a number literal.
When you *meta* compile, it's a bit more mind blowing. It fetches the address
of the word specified by the caller, then writes that number as a literal,
followed by a reference to ",".
Example: ": foo [COMPILE] bar;" is the equivalent of ": foo bar ;" if bar is
not an immediate. However, ": foo COMPILE bar ;" is the equivalent of
": foo ['] bar , ;". Got it?
Meta-compile only works with real words, not number literals.
*** I/O
A little word about inputs. There are two kind of inputs: direct and buffered.
As a general rule, we read line in a buffer, then feed words in it to the
interpreter. That's what "WORD" does. If it's at the End Of Line, it blocks and
wait until another line is entered.
KEY input, however, is direct. Regardless of the input buffer's state, KEY will
return the next typed key.
PARSING AND BOOTSTRAP: Parsing number literal is a very "core" activity of
Forth, and therefore generally seen as having to be implemented in native code.
However, Collapse OS' Forth supports many kinds of literals: decimal, hex, char,
binary. This incurs a significant complexity penalty.
What if we could implement those parsing routines in Forth? "But it's a core
routine!" you say. Yes, but here's the deal: at its native core, only decimal
parsing is supported. It lives in the "(parsed)" word. The interpreter's main
loop is initially set to simply call that word.
However, in core.fs, "(parsex)", "(parsec)" and "(parseb)" are implemented, in
Forth, then "(parse)", which goes through them all is defined. Then, "(parsef)",
which is the variable in which the interpreter's word pointer is set, is
updated to that new "(parse)" word.
This way, we have a full-featured (and extensible) parsing with a tiny native
core.
*** Chained comparisons
The unit "cmp.fs" contains words to facilitate chained comparisons with a single
reference number. This allows, for example, to easily express "a == b or a == c"
or "a > b and a < c".
The way those chained comparison words work is that, unlike single comparison
operators, they don't have a "n1 n2 -- f" signature, but rather a "n1 f n2 -- n1
f" signature. That is, each operator "carries over" the reference number in
addition to the latest flag.
You open a chain with "<>{" and you close a chain with "<>}". Then, in between
those words, you can chain operators. For example, to check whether A == B or A
== C, you would write:
A <>{ B &= C |= <>}
The first operator must be of the "&" type because the chain starts with its
flag to true. For example, "<>{ <>}" yields true.
To check whether A is in between B and C inclusively, you would write:
A <>{ B 1 - &> C 1 + &< <>}