1
0
mirror of https://github.com/hsoft/collapseos.git synced 2024-12-24 14:28:06 +11:00

Revamp usage guide a bit

This commit is contained in:
Virgil Dupras 2020-05-03 19:24:41 -04:00
parent d3dbeb450f
commit df242bb9eb
5 changed files with 35 additions and 50 deletions

16
blk/003
View File

@ -2,15 +2,15 @@ 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 for a word
reference.
implementation. The recommended introductory book is Starting
Forth by Leo Brodie. This is the reference that was used to
build this implementation and many of the conventions described
in this book are followed in Collapse OS. Be sure to refer to
the dictionary (B30) for a word reference.
Contents
4 DOES> 6 Compilation vs meta-comp.
8 I/O 14 Addressed devices
18 Signed-ness
4 Number literals 6 Compilation vs meta-comp.
8 Interpreter I/O 11 Signed-ness
14 Addressed devices

23
blk/004
View File

@ -1,16 +1,11 @@
DOES>
Number literals
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> @ ;"
Traditional Forth often use HEX/DEC switches to go from decimal
to hexadecimal parsing. Collapse OS parses literals in a way
that is closer to C.
Straight numbers are decimals, numbers starting with "0x"
are hexadecimals (example "0x12ef"), "0b" prefixes indicate
binary (example "0b1010"), char literals are single characters
surrounded by ' (example 'X'). Char literals can't be used for
whitespaces.

26
blk/008
View File

@ -1,16 +1,16 @@
I/O
Interpreter 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.
The INTERPRET loop, the heart of Collapse OS, feeds itself
from the C< word, which yields a character every time it is
called. If no character is available to interpret, it blocks.
KEY input, however, is direct. Regardless of the input buffer's
state, KEY will return the next typed key.
During normal operations, C< is simply a buffered layer over
KEY, which has the same behavior (but unbuffered). Before
yielding any character, the C< routine fetches a whole line
from KEY, puts it in a buffer, then yields the buffered line,
one character at once.
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. (cont.)
Both C< and KEY can be overridden by setting an alternate
routine at the proper RAM offset (see B80). For example, C<
overrides are used during LOAD so that input comes from
disk blocks instead of keyboard. (cont.)

20
blk/009
View File

@ -1,16 +1,6 @@
(cont.) 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.
KEY overrides can be used to, for example, temporarily give
prompt control to a RS-232 device instead of the keyboard.
Interpreter output is unbuffered and only has EMIT. This
word can also be overriden, mostly as a companion to the
raison d'etre of your KEY override.

View File